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 for ChatGPT, Claude and other MCP clients, or call it from a Python task.
Sign up for a plan with the Public API
- Create a Segment account at segment.com and set up a workspace.
- Move the workspace to the Team plan. Segment's pricing page 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.
- 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
- Sign in to Segment as a Workspace Owner. Only an Owner can create tokens.
- Open Settings, then Workspace settings, then Access Management, then Tokens.
- 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.
- 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.
- 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
- Open Connectors, then Segment, and click Connect.
- Fill in Credential Name, such as "Marketing workspace", paste the token into Public API Token, and pick the Region of the workspace.
- 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.
- In the task editor, choose Add connector from the Package + menu and select the credential. See Task resources.
List sources and their destinations from a task
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 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_destinationandcreate_warehouseneed ametadata_idfrom the matching catalog method. The catalog entry'soptionslist the settings keys the new resource needs.replace_source_labelsreplaces 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 inlist_labels.connect_source_to_warehouseadds one connection and removes none.create_warehousedoes 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_subscriptionsends its fields inside theinputobject Segment expects. Segment's docs do not list the fields allowed insideinput, so this connector sendsname,trigger,enabledandsettingsonly.list_functionsneedsresource_type, one ofSOURCE,DESTINATION,INSERT_SOURCE,INSERT_DESTINATIONorINSERT_TRANSFORMATION. The workspace needs the Functions feature. The connector reads Function metadata only and never creates, edits or deploys Function code.list_labelsis not paged. A key can have several values, so each label also carries anid(key:value) and aname(key=value) that tell apart labels sharing a key.- Destination
settingscan hold the credentials of the tool a destination sends to. Treat alist_destinationsorget_destinationresult 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.