> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.vapi.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.vapi.ai/_mcp/server.

# List traffic allocations

GET https://api.vapi.ai/traffic-allocations

The append-only history of an assistant's allocations, newest first. Traffic splitting is in beta, rolling out to select organizations; requests from organizations without access receive a 403.

Reference: https://docs.vapi.ai/api-reference/traffic-allocations/traffic-allocation-controller-find-all-paginated

## Authentication

- `Authorization` header (bearer token, required) — Authenticate server-side requests with a private Vapi API key. Create or copy a key from the [Vapi Dashboard](https://dashboard.vapi.ai) and send it in the `Authorization` header as `Bearer <token>`. Keep private API keys out of client-side code and public repositories.

## Request

### Query parameters

- `assistantId` (string, optional) — Filter to allocations for this assistant.
- `page` (integer, optional) — The page number to return. Defaults to 1.
- `limit` (integer, optional) — The maximum number of items to return. Defaults to 100.
- `sortOrder` (enum, optional) — The sort order for pagination. Defaults to 'DESC'.
  - Allowed values: `ASC`, `DESC`

## Response

### 200

- `results` (list of TrafficAllocation, required)
- `metadata` (PaginationMeta, required) — Pagination and retention metadata returned with a paginated list of phone numbers.

## Errors

### 403 Forbidden Error

Traffic splitting is not enabled for your organization. The feature is in beta, rolling out to select organizations.

- `any`

## Types

### TrafficAllocation

- `id` (string, required) — Unique identifier. The most recently created allocation for an assistant is the one in effect.
- `orgId` (string, required)
- `allocationIntent` (enum, required) — 'explicit' splits calls across this allocation's targets. 'follow-latest' sends every call to the newest published version.
  - Allowed values: `follow-latest`, `explicit`
- `createdAt` (datetime, required) — When this allocation was created, which is also when it took effect.
- `actorType` (enum, required) — Who created this allocation. 'system' means Vapi created it automatically, for example when a publish advances a follow-latest allocation.
  - Allowed values: `user`, `api-key`, `system`
- `targets` (list of TrafficAllocationTarget, required) — The versions this allocation splits calls across, in position order. Empty for follow-latest allocations.
- `assistantId` (string, optional) — The assistant this allocation splits calls for.
- `actorId` (string, optional) — The user id or API key id that created this allocation. Absent for system rows.
- `actorEmail` (string, optional) — Email of the user who created this allocation, as of that time.
- `description` (string, optional) — The note given when this allocation was created, if any.

### PaginationMeta

Pagination and retention metadata returned with a paginated list of phone numbers.

- `itemsPerPage` (double, required) — The number of phone numbers returned per page.
- `totalItems` (double, required) — The total number of phone numbers matching the request.
- `currentPage` (double, required) — The current page number.
- `totalPages` (double, optional)
- `hasNextPage` (boolean, optional)
- `nextCursor` (string, optional) — Opaque cursor for the next page under keyset pagination (PRO-3163). Pass it back as the `cursor` query param to fetch the next page without an OFFSET scan. Present only when a further page likely exists.
- `sortOrder` (enum, optional)
  - Allowed values: `ASC`, `DESC`
- `itemsBeyondRetention` (boolean, optional) — Whether additional matching phone numbers exist beyond the organization's data-retention window.
- `createdAtLe` (datetime, optional) — The inclusive upper creation-time boundary applied to the result set.
- `createdAtGe` (datetime, optional) — The inclusive lower creation-time boundary applied to the result set.

### TrafficAllocationTarget

- `assistantVersion` (string, required) — The assistant version this target sends calls to, such as "v7".
- `position` (double, required) — The target's place in the split, starting at 0. Set from the order of the targets array.
- `percentage` (double, required) — Share of calls sent to this version, from 0 to 100 with up to three decimal places. Targets add up to exactly 100. A 0% target keeps the version in the split without sending it calls.

## Examples

**Response**

```json
{
  "results": [
    {
      "id": "string",
      "orgId": "string",
      "allocationIntent": "follow-latest",
      "createdAt": "2024-01-15T09:30:00Z",
      "actorType": "user",
      "targets": [
        {
          "assistantVersion": "string",
          "position": 1.1,
          "percentage": 1.1
        }
      ],
      "assistantId": "string",
      "actorId": "string",
      "actorEmail": "string",
      "description": "string"
    }
  ],
  "metadata": {
    "itemsPerPage": 1.1,
    "totalItems": 1.1,
    "currentPage": 1.1,
    "totalPages": 1.1,
    "hasNextPage": true,
    "nextCursor": "string",
    "sortOrder": "ASC",
    "itemsBeyondRetention": true,
    "createdAtLe": "2024-01-15T09:30:00Z",
    "createdAtGe": "2024-01-15T09:30:00Z"
  }
}
```