<!-- Generated by scripts/generate-llms.mjs from docs/connectors/segment.md. Do not edit. -->

Source: https://qbash.com/docs/connectors/segment

# Connect Segment

Tasks call Segment through `qbash.integrations.segment` with a Public API workspace token you store on the Connectors page. The connector reads sources, destinations, destination subscriptions, warehouses, Reverse ETL models, labels, Functions and the catalog of source, destination and warehouse types. Its writes create and update sources, destinations, destination subscriptions and Reverse ETL models, replace a source's labels, create warehouses and connect a source to a warehouse.

No method deletes anything, returns a source write key, changes Function code, or manages tokens, users, roles or billing. Sending tracking events takes a source write key, a separate credential this connector never handles.

After you connect Segment, you can add its tools to a [qbash MCP server](https://qbash.com/docs-markdown/mcp-servers/overview.md#package) for ChatGPT, Claude and other MCP clients, or call it from a Python task.

## Sign up for a plan with the Public API

1. Create a Segment account at [segment.com](https://segment.com) and set up a workspace.
2. Move the workspace to the **Team** plan. Segment's [pricing page](https://www.twilio.com/en-us/products/connections/pricing) lists Public API access on Team, a 14-day free trial, and a starting price of $120 per month. It does not say whether the trial asks for a card. The **Business** plan is priced through Segment sales.
3. Check that you can open **Settings**, then **Workspace settings**, then **Access Management** in the workspace. You need the Workspace Owner role to create tokens.

The Free plan does not include the Public API. Segment's docs say Public API create, read, update and delete calls carry no extra charge.

Segment runs two regions, and each has its own API host:

| Workspace region | Host |
| --- | --- |
| US | `api.segmentapis.com` |
| EU | `eu1.api.segmentapis.com` |

You pick the region on the credential and qbash sends every call to the matching host.

## Create a Public API token

1. Sign in to Segment as a Workspace Owner. Only an Owner can create tokens.
2. Open **Settings**, then **Workspace settings**, then **Access Management**, then **Tokens**.
3. Add a token with a description. It must be a **Public API** token. A Config API token and a source write key are different credentials, and neither works here.
4. Choose **Workspace Member** access, not **Workspace Owner**. The connector never needs Owner rights, and the narrower role limits what a task can change in your workspace.
5. Copy the token and keep it somewhere safe, then paste it into qbash.

A token covers one workspace. A second workspace needs its own token and its own credential in qbash.

The token has no fine-grained scopes, so Owner or Member access is the only choice. Segment's docs do not say what Workspace Member access allows, and we have not confirmed which of this connector's methods a Member token can call. Test each method you plan to use before you rely on it.

## Add the token in qbash

1. Open **Connectors**, then **Segment**, and click **Connect**.
2. Fill in **Credential Name**, such as "Marketing workspace", paste the token into **Public API Token**, and pick the **Region** of the workspace.
3. Save. qbash checks the token format and region only and does not call Segment on save. The first call from a task shows whether Segment accepts the token.
4. In the task editor, choose **Add connector** from the Package **+** menu and select the credential. See [Task resources](https://qbash.com/docs-markdown/tasks/task-editor.md#resources).

## List sources and their destinations from a task

```python
sources = qbash.integrations.segment.list_sources(count=50)
destinations = qbash.integrations.segment.list_destinations(count=100)
by_source = {}
for destination in destinations["destinations"]:
    by_source.setdefault(destination["sourceId"], []).append(destination["name"])
for source in sources["sources"]:
    qbash.output({"source": source["slug"], "enabled": source["enabled"], "destinations": by_source.get(source["id"], [])})
```

List methods take `count` (1 to 1000, default 100) and `cursor`, and return `next_cursor`. Pass it back as `cursor` until it is `None`. Responses keep Segment's own key names, such as `sourceId` and `metadata`. The [SDK Reference](https://qbash.com/docs-markdown/tasks/sdk-reference.md) lists every method and its parameters.

## Methods

| Method | Resource | Access |
| --- | --- | --- |
| `list_sources` | Sources | Read |
| `get_source` | Sources | Read |
| `create_source` | Sources | Write |
| `update_source` | Sources | Write |
| `replace_source_labels` | Sources | Write |
| `list_destinations` | Destinations | Read |
| `get_destination` | Destinations | Read |
| `create_destination` | Destinations | Write |
| `update_destination` | Destinations | Write |
| `list_destination_subscriptions` | Destination subscriptions | Read |
| `create_destination_subscription` | Destination subscriptions | Write |
| `update_destination_subscription` | Destination subscriptions | Write |
| `list_warehouses` | Warehouses | Read |
| `get_warehouse` | Warehouses | Read |
| `create_warehouse` | Warehouses | Write |
| `connect_source_to_warehouse` | Warehouses | Write |
| `list_reverse_etl_models` | Reverse ETL models | Read |
| `get_reverse_etl_model` | Reverse ETL models | Read |
| `create_reverse_etl_model` | Reverse ETL models | Write |
| `update_reverse_etl_model` | Reverse ETL models | Write |
| `list_labels` | Labels | Read |
| `list_functions` | Functions | Read |
| `list_catalog_sources` | Catalog | Read |
| `list_catalog_destinations` | Catalog | Read |
| `list_catalog_warehouses` | Catalog | Read |

## Details that affect results

- Source write keys are removed from every response, so a task never sees them.
- `create_source`, `create_destination` and `create_warehouse` need a `metadata_id` from the matching catalog method. The catalog entry's `options` list the settings keys the new resource needs.
- `replace_source_labels` replaces every label on the source with the list you send. Pass an empty list to clear them. A label's key and value must already exist in `list_labels`.
- `connect_source_to_warehouse` adds one connection and removes none. `create_warehouse` does not disconnect existing sources.
- Destination subscriptions and Reverse ETL models are alpha endpoints in Segment's API. The subscription endpoints need the Destination Subscriptions feature on the workspace. Subscription and Reverse ETL writes are limited to 5 requests per minute.
- `update_destination_subscription` sends its fields inside the `input` object Segment expects. Segment's docs do not list the fields allowed inside `input`, so this connector sends `name`, `trigger`, `enabled` and `settings` only.
- `list_functions` needs `resource_type`, one of `SOURCE`, `DESTINATION`, `INSERT_SOURCE`, `INSERT_DESTINATION` or `INSERT_TRANSFORMATION`. The workspace needs the Functions feature. The connector reads Function metadata only and never creates, edits or deploys Function code.
- `list_labels` is not paged. A key can have several values, so each label also carries an `id` (`key:value`) and a `name` (`key=value`) that tell apart labels sharing a key.
- Destination `settings` can hold the credentials of the tool a destination sends to. Treat a `list_destinations` or `get_destination` result as sensitive, and keep it out of task output you share.
- A 401 marks the credential as needing a new token. Segment's docs list 401 for a missing, incorrect or under-permissioned token, so a region that does not match the workspace, a plan without the Public API or a Member token that is too narrow for the call may all read as 401. A 403 does not mark the credential, and its message points to the plan and the token's access level.
- A 429 reaches your task with the wait Segment asks for. Segment's docs recommend the list methods over many single reads.
