Skip to main content

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​

  1. Create a Segment account at segment.com and set up a workspace.
  2. 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.
  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 regionHost
USapi.segmentapis.com
EUeu1.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.

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​

MethodResourceAccess
list_sourcesSourcesRead
get_sourceSourcesRead
create_sourceSourcesWrite
update_sourceSourcesWrite
replace_source_labelsSourcesWrite
list_destinationsDestinationsRead
get_destinationDestinationsRead
create_destinationDestinationsWrite
update_destinationDestinationsWrite
list_destination_subscriptionsDestination subscriptionsRead
create_destination_subscriptionDestination subscriptionsWrite
update_destination_subscriptionDestination subscriptionsWrite
list_warehousesWarehousesRead
get_warehouseWarehousesRead
create_warehouseWarehousesWrite
connect_source_to_warehouseWarehousesWrite
list_reverse_etl_modelsReverse ETL modelsRead
get_reverse_etl_modelReverse ETL modelsRead
create_reverse_etl_modelReverse ETL modelsWrite
update_reverse_etl_modelReverse ETL modelsWrite
list_labelsLabelsRead
list_functionsFunctionsRead
list_catalog_sourcesCatalogRead
list_catalog_destinationsCatalogRead
list_catalog_warehousesCatalogRead

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.