A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Segment API is how an app or AI agent works with a Segment workspace: sending a customer event into a source, creating a source or destination, editing a tracking plan, or deploying a function. Access is split across two credentials, a source write key that can only send events in, and a workspace token tied to an account role that sets which resources it can read or change. Segment versions each management method on its own track, so a single method can be alpha, beta, or stable while the rest stay put.
How an app or AI agent connects to Segment depends on what it needs to do. There is a route for sending customer events into a source, and a separate route for managing the workspace itself, like its sources, destinations, tracking plans and functions. Each route has its own credential, a write key for sending events and a workspace token for managing the account, and each carries its own reach.
The Tracking API receives customer events over HTTP at api.segment.io (EU: events.eu1.segmentapis.com), with one POST endpoint per call type (identify, track, page, screen, group, alias) plus batch. A request authenticates with a source write key, sent as the HTTP Basic auth username with an empty password, or carried in the request body. A write key can only send events into its one source.
The Public API manages the workspace at api.segmentapis.com (EU: api.eu1.segmentapis.com): sources, destinations, tracking plans, functions, warehouses, and IAM. It follows REST conventions, pages lists with a cursor, and authenticates with a workspace access token sent as a Bearer token. The token inherits an IAM role, so its reach is set by the role and labels assigned at creation, not by a per-method scope.
Segment does not push API-level lifecycle notifications. To receive the events a workspace collects, an integration adds a Webhooks (Actions) destination that POSTs each event to an HTTPS URL, with optional shared-secret signing for verification. Notifications are configured as a destination rather than subscribed to through the Tracking or Public API.
A write key identifies one source and lets a caller send events into it. It is sent as the HTTP Basic auth username with an empty password, or placed in the request body. A write key cannot read data or change the workspace; it can only write events to its source. A source can hold more than one write key, and a key is created and revoked through the source's settings or the Public API.
A workspace access token authenticates the Public API as a Bearer token in the Authorization header. Only a Workspace Owner can create one, assigning it either Workspace Owner access (every resource) or Workspace Member access with granular per-resource permissions and labels. The same role model that governs a logged-in user governs the token, and a Workspace Admin or Owner can change or revoke it.
Segment Apps use a web-based OAuth authorization flow so a Workspace Owner can grant a third-party app access to a specific workspace and source. An app requests a scope of workspace to change all resources or workspace:read to read them, and the granted token then calls the Public API. This is the route for partner integrations rather than first-party workspace tokens.
Segment splits into two APIs that do different jobs. The Tracking API sends customer events into a source, like identifying a user or recording an action. The Public API manages the workspace, like creating sources and destinations, editing tracking plans, and deploying functions, where a write changes how a whole pipeline collects or routes data.
Methods that send customer events into a source: identify, track, page, screen, group, alias, and batch.
Public API methods for creating and managing the sources that collect data.
Public API methods for managing the destinations that data is routed to.
Public API methods for managing tracking plans and the rules that validate events.
Public API methods for managing the custom source and destination functions that run code on data.
Public API methods for reading the workspace an access token belongs to.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
Tracking API (events)Methods that send customer events into a source: identify, track, page, screen, group, alias, and batch.7 | ||||||
| POST | /v1/identify | Tie a user to their traits and a userId, recording who the customer is. | write | Write key | Current | |
Sends an event into the source the write key belongs to. Requires a userId or anonymousId. Base host api.segment.io (EU: events.eu1.segmentapis.com). Acts onevent Permission (capability) Write keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/track | Record an action a user performed, with an event name and properties. | write | Write key | Current | |
The core event call. Requires an event name plus a userId or anonymousId. Acts onevent Permission (capability) Write keyVersionAvailable since the API’s base version Webhook eventNone Rate limitUp to 32 KB per event SourceOfficial documentation ↗ | ||||||
| POST | /v1/page | Record a web page view, with the page name and properties. | write | Write key | Current | |
Records a page view into the source. Acts onevent Permission (capability) Write keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/screen | Record a mobile app screen view, the app equivalent of a page. | write | Write key | Current | |
Records a screen view into the source. Acts onevent Permission (capability) Write keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/group | Associate a user with a group, like an account or organization, and its traits. | write | Write key | Current | |
Links a user to a groupId. Acts onevent Permission (capability) Write keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/alias | Merge two user identities, mapping a previous id to a new one. | write | Write key | Current | |
Used mainly to connect an anonymous user to an identified one. Acts onevent Permission (capability) Write keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/batch | Send a series of identify, track, page, screen and group calls in a single request. | write | Write key | Current | |
Saves outbound requests. A batch is capped at 500 KB, with each event below 32 KB. Acts onevent Permission (capability) Write keyVersionAvailable since the API’s base version Webhook eventNone Rate limitUp to 500 KB per batch SourceOfficial documentation ↗ | ||||||
SourcesPublic API methods for creating and managing the sources that collect data.6 | ||||||
| GET | /sources | List the sources in the workspace (cursor-paginated). | read | — | Current | |
Public API. Reach is set by the token's IAM role, not a per-method scope; a Workspace Member needs source read permission. Acts onsource Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /sources/{sourceId} | Retrieve a single source by its id. | read | — | Current | |
Public API. Read access depends on the token's role and the source's labels. Acts onsource Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /sources | Create a new source to start collecting data into the workspace. | write | — | Current | |
Public API. A write that adds a data pipeline; needs a token with workspace or source write permission. Acts onsource Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /sources/{sourceId} | Update a source's name, settings or enabled state. | write | — | Current | |
Public API. Changes how the source collects data. Acts onsource Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /sources/{sourceId} | Delete a source, stopping data collection through it. | write | — | Current | |
Public API. Irreversible; removes the pipeline and its write keys. Acts onsource Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /sources/{sourceId}/writekey | Create a new write key for a source. | write | — | Current | |
Public API. A new write key can send events into the source, so this grants Tracking API access. Acts onwriteKey Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
DestinationsPublic API methods for managing the destinations that data is routed to.5 | ||||||
| GET | /destinations | List the destinations in the workspace (cursor-paginated). | read | — | Current | |
Public API. Reach is set by the token's IAM role. Acts ondestination Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /destinations/{destinationId} | Retrieve a single destination by its id. | read | — | Current | |
Public API. Read-only. Acts ondestination Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /destinations | Connect a new destination so collected data is routed to it. | write | — | Current | |
Public API. A write that starts sending workspace data to a new tool. Acts ondestination Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /destinations/{destinationId} | Update a destination's settings or enabled state. | write | — | Current | |
Public API. Changes where and how data is delivered. Acts ondestination Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /destinations/{destinationId} | Delete a destination, stopping data delivery to it. | write | — | Current | |
Public API. Stops routing data to the tool. Acts ondestination Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Tracking PlansPublic API methods for managing tracking plans and the rules that validate events.5 | ||||||
| GET | /tracking-plans | List the tracking plans in the workspace (cursor-paginated). | read | — | Current | |
Public API. Reach is set by the token's IAM role. Acts ontrackingPlan Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /tracking-plans/{trackingPlanId} | Retrieve a single tracking plan by its id. | read | — | Current | |
Public API. Read-only. Acts ontrackingPlan Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /tracking-plans | Create a tracking plan that defines which events and properties are valid. | write | — | Current | |
Public API. Defines the schema events are validated against. Acts ontrackingPlan Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /tracking-plans/{trackingPlanId}/rules | Replace the full set of validation rules in a tracking plan. | write | — | Current | |
Public API. Overwrites the rules that govern which events are allowed. Acts ontrackingPlanRule Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /tracking-plans/{trackingPlanId} | Delete a tracking plan. | write | — | Current | |
Public API. Removes the plan and its rules. Acts ontrackingPlan Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
FunctionsPublic API methods for managing the custom source and destination functions that run code on data.6 | ||||||
| GET | /functions | List the functions in the workspace (cursor-paginated). | read | — | Current | |
Public API. Reach is set by the token's IAM role. Acts onfunction Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /functions/{functionId} | Retrieve a single function by its id, including its code. | read | — | Current | |
Public API. Returns the function's source code. Acts onfunction Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /functions | Create a function that runs custom code as a source or destination. | write | — | Current | |
Public API. Adds code that runs on the workspace's data. Acts onfunction Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /functions/{functionId} | Update a function's code, name or settings. | write | — | Current | |
Public API. Changes the code that runs on data. Acts onfunction Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /functions/{functionId}/deploy | Deploy a function, putting its current code into effect. | write | — | Current | |
Public API. Makes the latest code live for connected sources or destinations. Acts onfunction Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /functions/{functionId} | Delete a function. | write | — | Current | |
Public API. Removes the function and its versions. Acts onfunction Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
WorkspacePublic API methods for reading the workspace an access token belongs to.1 | ||||||
| GET | / | Retrieve the workspace the access token belongs to. | read | — | Current | |
Public API. The root endpoint; returns the workspace tied to the token. Acts onworkspace Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Segment does not push lifecycle notifications back to an integration through the Tracking or Public API. Instead, a Webhooks destination forwards the events a workspace collects to a URL, so notifications are configured as a destination rather than subscribed to as an API event.
| Event | What it signals | Triggered by |
|---|
Segment limits how fast and how much an app can call, with separate models for the two APIs. The Tracking API caps event throughput and payload size, while the Public API meters management requests by token, IP address and request complexity.
The two APIs are limited differently. The Tracking API meters event throughput, with Segment recommending a maximum of about 1,000 requests per second per workspace, and rejecting bursts beyond capacity with HTTP 429 and a Retry-After header. The Public API limits management requests by IP address, access token, and request complexity, reporting status through the X-RateLimit-Consumed, X-RateLimit-Remaining and X-RateLimit-Reset response headers, and returning HTTP 429 when a window is exceeded. Segment does not publish a single fixed per-minute number for the Public API.
The Public API uses cursor (token) pagination on list endpoints. A request sets pagination.count, an integer from 1 to 1000 that defaults to 200, and pagination.cursor to continue from a position. The response returns current, next and previous cursors plus totalEntries, and a missing next cursor means the last page. The Tracking API does not paginate, since it only writes events.
A Tracking API event is capped at 32 KB, and a batch request at 500 KB total. The Public API returns at most 1000 items per page, the maximum value of pagination.count. The Public API also returns 413 when a request body exceeds the server's size limit.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 200 | ok | The request was accepted. The Tracking API returns 200 for an accepted event, and the Public API returns 200 for a successful read or update. A Tracking API 200 means the event was received, not that it passed validation, so a malformed event can still be dropped later. | For the Tracking API, confirm acceptance in the Segment Debugger rather than relying on the 200 alone. |
| 400 | bad request | The Tracking API rejects a request whose JSON is invalid or whose payload is over the size limit. | Fix the JSON or reduce the payload below 32 KB per event and 500 KB per batch, then resend. |
| 401 | unauthorized | On the Public API, the access token is missing, invalid, or lacks permission for the request. | Send a valid Bearer token whose IAM role covers the resource, and rotate the token if it leaked. |
| 404 | not found | The requested resource does not exist or is not visible to this token. | Verify the resource id and confirm the token's workspace and role can see it. |
| 409 | conflict | There was a conflict processing the request, like creating a resource that already exists. | Re-read the current state and resolve the conflict before retrying. |
| 422 | unprocessable entity | A parameter is invalid or a required field is missing. The errors array names the field and the validation type. | Read the errors array, fix the named field, and resend. |
| 429 | too many requests | Too many sequential or concurrent requests were made. The X-RateLimit-Reset header gives when the window resets. | Back off until the reset time and smooth the request rate; the Tracking API also returns a Retry-After header. |
| 500 | internal server error | Segment could not serve the request because of an internal failure (any 5xx). | Retry with backoff and contact Segment support if it persists. |
Segment versions the Public API per endpoint rather than across the whole API, so an individual method can be alpha, beta or stable, and a call is routed to the most stable version available unless it asks for another. The Tracking API is a single continuously available endpoint with no dated version.
Segment versions the Public API per endpoint, where a method can be alpha, beta or stable, and a request is routed to the most stable version available unless it pins another. The SDKs and OpenAPI specification track an overall release number, currently 73.0.0, that advances as endpoints are added and matured.
Segment stopped allowing new Config API tokens, directing all new integrations to the Public API. The Config API keeps working for existing tokens but receives no further development.
The Segment Public API reached general availability, replacing the Config API as the supported way to manage a workspace and its resources programmatically.
Segment's Tracking API has long received customer events through identify, track, page, screen, group, alias and batch calls. The Public API launched in beta as the modern management API and successor to the Config API.
Pin an endpoint to a specific version when relying on its current shape, since a new version only appears on a breaking change.
Segment Public API versioning ↗Bollard AI sits between a team's AI agents and Segment. Grant each agent exactly the access it needs, read or write, across the Tracking API and the Public API, and every call is checked and logged.