ApiTraffic REST API

The ApiTraffic REST API gives scripts, CI pipelines and internal tools the same data and settings you use in the app: buckets, captured requests, metrics, APM, redaction and exclusion rules, event markers and more. Every request and response body is JSON.

This page covers what is common to every operation. Each resource page then lists its operations with parameters, response fields and examples.

Base URL and versioning #

All operations live under one base URL:

https://api.apitraffic.io/v1

The version is the first path segment (/v1). There is no version header and no date-based versioning: changes within v1 add fields and operations, so write clients that ignore fields they do not recognize.

Most operations are scoped to an account, and many to a bucket inside it:

https://api.apitraffic.io/v1/accounts/{accountSid}/buckets/{bucketSid}/requests

Identifiers #

Every object has a string identifier (a “sid”) whose prefix tells you its type. You can copy the ones you need from the app.

Timestamps are ISO 8601 strings in UTC, for example 2026-10-19T14:05:00.000Z. Query parameters that take a time expect the same format, ending in Z.

Authentication #

Send a bearer token in the Authorization header of every request:

curl https://api.apitraffic.io/v1/accounts/acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa/buckets \
  -H "Authorization: Bearer $APITRAFFIC_TOKEN"

The scheme is case-sensitive (Bearer). Tokens in the query string are refused with 401 and code 2043, because URLs end up in logs and browser history.

The REST API accepts three kinds of token:

MCP tokens (mcp_…) only work with the MCP server, not the REST API.

API token roles #

An API token’s role decides which operations it may call:

People signed in to the app are checked the same way: owners and admins can do everything, members get the user set. Operations that need more than member access say so under Permissions.

Warning: A token can only reach the account it belongs to. Putting another account’s sid in the path answers 403 with code 2010, even for a valid token.

Responses #

Successful responses use 200 and return the object or collection directly, with no envelope:

{
  "sid": "k3m9p2x",
  "accountSid": "acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa",
  "name": "Acme Store API"
}

Deletes return the deleted object’s sid and a flag:

{ "sid": "k3m9p2x", "deleted": true }

Errors #

Errors use standard HTTP status codes and a JSON body:

{
  "message": "\"name\" is required",
  "code": 1000,
  "moreInformation": "https://apitraffic.io/api/errors/1000",
  "data": {}
}

A few responses use a slightly different body, noted in the table: the rate limit (429), a missing subscription (402) and a closed account (410) return code and message without moreInformation and data. Requests that fail before reaching ApiTraffic’s handlers (an unknown path, a body that is too large) return statusCode, error and message.

Error codes #

Each resource page lists the codes specific to its operations.

Pagination #

List operations return an object with the records and a hasMore flag:

{
  "hasMore": false,
  "records": [ ]
}

How you get the next page depends on the resource:

• Captured requests use a cursor. Pass the from value of one page as the from query parameter of the next, until hasMore is false. See List requests.
• Events return the newest first, up to limit. To go further back, pass the startedAt of the last event you have as endTime.
• Purge history takes limit and offset.
• Configuration lists (buckets, tokens, redactions, exclusions) return every record in one response, and hasMore is always false.

Rate limits #

Requests are counted in fixed one-minute windows:

Responses carry the budget you are closest to exhausting:

Over the limit, the API answers 429 with a Retry-After header:

{
  "successful": false,
  "code": "RATE_LIMITED",
  "message": "Too many requests. Please retry after the indicated delay."
}

The account budget is shared by everything that calls the API for that account, including the app and the MCP server. A script that loops over many requests should read RateLimit-Remaining and slow down before it reaches zero.

Retries and idempotency #

The API has no idempotency keys. GET, PUT and DELETE are safe to retry. Retrying a POST that timed out can create a second object, so list first to check whether the first attempt succeeded.

Retry 429, 502, 503 and 504 responses with backoff, and honor Retry-After when it is present. Do not retry 4xx responses other than 429 without changing the request.

Limits #

• Request bodies are limited to 1 MB.
• Each request must finish within 90 seconds. Analytics reads over long ranges may answer 504 sooner; narrow the range and retry.

Resources #

Related #

• API tokens: Make the token your scripts and integrations use.

• Search and filter requests: The criteria language used to filter requests, metrics and exclusions.

• MCP server: Let AI assistants query your traffic directly.

• Buckets API: Start with the buckets in your account.