# ApiTraffic REST API

> Base URL, versioning, authentication, errors, pagination and rate limits for the ApiTraffic REST API, with an overview of every resource.

Source: https://www.apitraffic.io/docs/api-reference/introduction

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:

```text
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:

```text
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.

| Object | Format | Example |
| --- | --- | --- |
| Account | `acc_` + 27 letters and digits | `acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa` |
| Environment | 6 lowercase letters and digits | `prd7k2` |
| Bucket | 7 lowercase letters and digits | `k3m9p2x` |
| Request | `req_` + 27 letters and digits | `req_2nA8fK3pQ7xV1mZ5tR9wB4cL6hY` |
| API token | `tkn_` + 27 letters and digits | `tkn_2kF9wQ4mX7pL1vB8nR3tZ6cH5yJ` |
| MCP token | `mcp_` + 27 letters and digits | `mcp_2pR7vK1xN9mQ4tB6wZ3cL8hY5fD` |
| Redaction | `red_` + 27 letters and digits | `red_2qW8eR4tY6uI1oP3aS5dF7gH9jK` |
| Exclusion | `xcl_` + 27 letters and digits | `xcl_2zX4cV6bN8mA1sD3fG5hJ7kL9qP` |
| Event | `evt_` + 27 letters and digits | `evt_2tG5yH7uJ9iK1oL3pZ6xC8vB4nM` |
| Stream view | `sv_` + 27 letters and digits | `sv_2vC8xZ1aS3dF5gH7jK9lQ2wE4rT` |

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:

```bash
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:

| Token | Where it comes from | What it can do |
| --- | --- | --- |
| **API token** (`tok_…`) | **Account** → **API Tokens**, or [Create API token](https://www.apitraffic.io/docs/api-reference/api-tokens#create-api-token) | Depends on its role (below). Use it for scripts, CI and integrations. |
| **User session** | Signing in to the app | Acts as that person, with their account role. Some operations, such as closing the account, only accept a session. |
| **OAuth access token** | An application you connect through [OAuth](https://www.apitraffic.io/docs/integrations/oauth) | Member-level access to one account. Read-only unless the app was granted write access. |

MCP tokens (`mcp_…`) only work with the [MCP server](https://www.apitraffic.io/docs/integrations/mcp-server), not the REST API.

### API token roles

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

| Role | Access |
| --- | --- |
| `administrator` | Everything an account admin can do, including creating tokens, minting [embed](https://www.apitraffic.io/docs/integrations/embed) tokens and changing redaction rules, exclusions and firewall policies. The only API token role that can mint embed tokens. |
| `user` | Everything a member can do: read all data, create and edit buckets, events and similar resources. It cannot create or change tokens, mint embed tokens, change redaction rules, exclusions or firewall policies, or delete buckets, environments or requests. |
| `ingest` | Only what an SDK needs: [Get SDK settings](https://www.apitraffic.io/docs/api-reference/buckets#get-sdk-settings) and the offline definitions download, which serves the same settings. It can't mint embed tokens. Every other operation answers `403`. Give this role to tokens that ship inside your application. |

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:

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

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

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

## Errors

Errors use standard HTTP status codes and a JSON body:

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

| Field | Description |
| --- | --- |
| `message` | What went wrong, in plain words. For validation errors it names the parameter. |
| `code` | A numeric ApiTraffic error code. Branch on this, not on `message`. |
| `moreInformation` | A reference URL for the code. |
| `data` | Extra detail when there is some, for example the plan limit that was reached. Otherwise `{}`. |

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

| Status | Code | Meaning |
| --- | --- | --- |
| `400` | `1000` | A parameter is missing or invalid. The message names it. |
| `400` | `2007` | The `criteria` filter could not be parsed, or uses a body condition your plan does not include. |
| `400` | `2009` | The `streamViewSid` does not exist in this bucket. |
| `401` | `2003` | The `Authorization` header is malformed. |
| `401` | `2004` | No token was sent. |
| `401` | `2005` | The token is unknown, revoked or expired. |
| `401` | `2043` | The token was sent in the query string. Use the `Authorization` header. |
| `402` | `2400` | The account has no active subscription (for example, the trial ended). Error name `SUBSCRIPTION_REQUIRED`. |
| `403` | `2010` | The token may not do this: wrong account, a role without the permission, or an `ingest` token. |
| `403` | `2221` | The account's plan does not include this feature. `data.feature` names it. |
| `403` | `2509` | The operation would change the read-only sample bucket. |
| `403` | `2510` | Sample data is turned off for this account. |
| `404` | `4000` | The object does not exist, or is not in this account. |
| `409` | `2213` | A plan limit was reached (for example, the number of buckets or tokens). `data` carries the allowance. |
| `410` | `2640` | The account has been closed. |
| `413` | | The request body is larger than 1 MB. |
| `422` | `5108` | A body condition matches too many requests to count exactly. Narrow the time range or add filters. |
| `422` | `5110` | Body search needs a body retention window of at least 30 days. |
| `429` | `RATE_LIMITED` | Too many requests. Wait for `Retry-After` seconds. This code is a string. |
| `429` | `2222` | The plan's allowance for this billing period is used up (for example, AI diagnoses). |
| `502` | `5105` | An analytics query failed. Retry. |
| `503` | `2099` | Authentication is briefly unavailable. Retry. |
| `503` | `2108` | A token change could not be applied right now. Nothing was changed. Retry. |
| `503` | `5102`, `5103`, `5104`, `5109` | Analytics are temporarily unavailable. Retry after `Retry-After` seconds. |
| `504` | `5101` | An analytics query took too long. Retry, or narrow the time range. |

Each resource page lists the codes specific to its operations.

## Pagination

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

```json
{
  "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](https://www.apitraffic.io/docs/api-reference/requests#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:

| Budget | Applies to | Default limit |
| --- | --- | --- |
| Account | Every authenticated request, counted per account | 3,000 requests per minute |
| Anonymous | Unauthenticated requests, counted per IP address | 300 requests per minute |
| Sign-in | Sign-in, sign-up, password reset and MFA verification, counted per IP address | 60 requests per minute |

Responses carry the budget you are closest to exhausting:

| Header | Meaning |
| --- | --- |
| `RateLimit-Limit` | Requests allowed in the window |
| `RateLimit-Remaining` | Requests left in the window |
| `RateLimit-Reset` | Seconds until the window resets |

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

```json
{
  "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

| Resource | What it covers |
| --- | --- |
| [Authentication](https://www.apitraffic.io/docs/api-reference/authentication) | The signed-in user's profile, checking a token, signing out, embed tokens |
| [API tokens](https://www.apitraffic.io/docs/api-reference/api-tokens) | Tokens for scripts, integrations and SDKs |
| [MCP tokens](https://www.apitraffic.io/docs/api-reference/mcp-tokens) | Tokens for AI assistants that use the MCP server |
| [Environments](https://www.apitraffic.io/docs/api-reference/environments) | Production, staging and other environments, and the default |
| [Buckets](https://www.apitraffic.io/docs/api-reference/buckets) | Buckets and their settings, plus the configuration the SDK downloads |
| [Requests](https://www.apitraffic.io/docs/api-reference/requests) | Captured requests: search, detail, concurrency, AI prompts |
| [Stream views](https://www.apitraffic.io/docs/api-reference/stream-views) | Saved filters on a bucket's requests |
| [Metrics](https://www.apitraffic.io/docs/api-reference/metrics) | Traffic summary, throughput, response time and the weekly traffic pattern |
| [APM](https://www.apitraffic.io/docs/api-reference/apm) | Where request time goes, slow endpoints and operations, regressions, dependencies, distributed traces |
| [Spans](https://www.apitraffic.io/docs/api-reference/spans) | Database, cache and outbound operations inside requests |
| [Endpoints](https://www.apitraffic.io/docs/api-reference/endpoints) | Detected endpoints and their metrics, endpoint rules, attention signals |
| [Drift](https://www.apitraffic.io/docs/api-reference/drift) | API drift findings, baselines, scan health and AI diagnoses |
| [Hosts](https://www.apitraffic.io/docs/api-reference/hosts) | Server health, per-server traffic, saturation and restarts |
| [Redactions](https://www.apitraffic.io/docs/api-reference/redactions) | Rules that remove sensitive data before it is stored |
| [Exclusions](https://www.apitraffic.io/docs/api-reference/exclusions) | Rules that stop matching traffic from being captured |
| [WAF](https://www.apitraffic.io/docs/api-reference/waf) | Firewall policies, managed rulesets, the policy simulator and firewall analytics |
| [Events](https://www.apitraffic.io/docs/api-reference/events) | Deploy, incident and configuration markers on your charts |
| [Collections and shares](https://www.apitraffic.io/docs/api-reference/collections-and-shares) | Collections of requests and public share links |
| [Account data](https://www.apitraffic.io/docs/api-reference/account-data) | Purging data and closing the account |
| [Workflows](https://www.apitraffic.io/docs/api-reference/workflows) | Automations that run when matching requests arrive |
| [Account activity](https://www.apitraffic.io/docs/api-reference/activity) | The account's history and the catalog of event types |

## Related

- [API tokens](https://www.apitraffic.io/docs/account/api-tokens):
    Make the token your scripts and integrations use.

- [Search and filter requests](https://www.apitraffic.io/docs/traffic/search):
    The criteria language used to filter requests, metrics and exclusions.

- [MCP server](https://www.apitraffic.io/docs/integrations/mcp-server):
    Let AI assistants query your traffic directly.

- [Buckets API](https://www.apitraffic.io/docs/api-reference/buckets):
    Start with the buckets in your account.