Twilio Segment

Twilio Segment

This connector manages one Segment workspace (customer data platform) through the Segment Public API with a workspace token: sources, destinations and their mappings, warehouses and their syncs, tracking plans and rules (Protocols), Functions, event volume, Delivery Overview and destination delivery metrics, API call and MTU usage, and the Audit Trail. Changing or deleting sources and destinations is possible but installed switched off.

Setup (about 3 minutes; you need to be a Workspace Owner)

1. In Segment open Settings, Workspace settings, Access Management, Tokens (https://app.segment.com/goto-my-workspace/settings/access-management/tokens) and click Create Token.
2. Choose a Public API token (not a Config API token). Give it the least role that covers what you want: Workspace Member with read-only roles (for example Source Read-only, Tracking Plan Read-only) for reading; Workspace Owner only if the write tools will be switched on. The token is shown once: copy it at once.
3. Paste it into SEGMENT_API_TOKEN. It is sent as a Bearer token and only to Segment.
4. Set SEGMENT_API_HOST to the workspace's region: https://api.segmentapis.com for US workspaces, https://eu1.api.segmentapis.com for EU workspaces. A token only works in its own region.

A token belongs to one workspace; create one connector per workspace.

Limits: Segment limits requests per token, IP address and endpoint; over the limit it answers 429 with a Retry-After header. Some endpoints are stricter: segment_list_warehouse_syncs 2 requests a minute, segment_get_event_volume 60 a minute, segment_list_tracking_plan_rules and segment_get_warehouse_connection_state 200 a minute. Prefer list tools over many single reads, and never loop over items.

Pagination: list tools take count (1 to 1000) and cursor. When the answer has pagination.next, call the same tool again with cursor set to it; when it is missing you have everything.

How to work

1. Map the workspace: segment_get_workspace, segment_list_sources, segment_list_destinations, segment_list_warehouses; per source segment_get_source, segment_list_source_destinations, segment_list_source_warehouses, segment_get_source_schema_settings; per destination segment_get_destination and segment_list_destination_subscriptions (Actions mappings).
2. Data health: segment_get_event_volume for volume over time, segment_get_delivery_overview for where events are dropped (step by step, with discard reasons), segment_get_destination_delivery_metrics for one destination, segment_get_warehouse, segment_get_warehouse_connection_state and segment_list_warehouse_syncs for warehouses.
3. Governance (Protocols): segment_list_tracking_plans, segment_get_tracking_plan, segment_list_tracking_plan_rules, segment_list_tracking_plan_sources.
4. Code and usage: segment_list_functions, segment_get_function, segment_get_daily_api_calls_usage, segment_get_daily_mtu_usage, and segment_list_audit_events for who changed what.
5. Changes (installed switched off): segment_update_source and segment_update_destination rename or enable and disable; a disabled source or destination drops data, so confirm with the user before each call. segment_delete_source and segment_delete_destination cannot be undone and need the user's explicit confirmation of the id and name.

Times are ISO 8601 (2026-10-13T00:00:00Z); end times are exclusive.

Secrets: tools leave out settings fields that usually hold credentials (API keys, secrets, tokens, passwords) of destinations and warehouses. segment_get_source returns the source's write keys, which let anyone send data into that source.

Common errors

• 403 "Not authorized to perform this operation": the token is wrong or revoked, belongs to a workspace in the other region, or its role does not allow this resource.
• 401: no token was sent; set SEGMENT_API_TOKEN.
• 404: no resource with that id in this workspace.
• 422: a parameter is missing or invalid; the message names it (for example a Delivery Overview time range longer than its granularity allows).
• A message about a feature: the workspace has no Protocols, Functions or Destination Subscriptions.
• 429: rate limited; wait for Retry-After.

Out of scope here: sending events (the Tracking API uses a source's write key with HTTP Basic on api.segment.io, a different credential and host), creating sources, destinations and warehouses, filters, transformations, Reverse ETL, Engage audiences and computed traits, IAM, regulations (deletion and suppression) and the catalog.