TokenLab

Files & Batches

Create Message Batch

Creates a batch of Messages requests that run asynchronously.

POST
/v1/messages/batches

Overview

Send up to 100,000 Messages requests in one call. The batch runs asynchronously. The response returns at once with processing_status set to in_progress. Retrieve the batch until it has ended, then get the results.

Notes

  • Each item in requests has a custom_id and params. params takes the same fields as Create Message, including max_tokens. Items cannot use speed: "fast".
  • custom_id is 1 to 64 letters, digits, underscores, or hyphens, and must be unique in the batch.
  • Every model in the batch must be available for batches. TokenLab rejects the whole request with 400 when a model is not, or when no single route can serve all the models in the batch.
  • TokenLab reserves the estimated cost when it accepts the batch and returns 402 when the balance cannot cover it. After the batch ends, TokenLab settles the usage of the requests that succeeded. Batch prices may differ from synchronous prices.
  • If an item references file_id content, send anthropic-beta: files-api-2025-04-14.
  • Send an Idempotency-Key to retry a timed-out create request safely. See Retry safely with an idempotency key.

Example

Request

cURL
curl -X POST "https://api.tokenlab.sh/v1/messages/batches" \
  -H "x-api-key: sk-your-api-key" \
  -H "anthropic-version: 2023-06-01" \
  -H "Idempotency-Key: 6f1c2a9e-0b7d-4c1e-9a53-2d9f3a1b7c10" \
  -H "Content-Type: application/json" \
  -d '{
    "requests": [
      {
        "custom_id": "request-1",
        "params": {
          "model": "claude-sonnet-5",
          "max_tokens": 1024,
          "messages": [{"role": "user", "content": "Hello, Claude!"}]
        }
      },
      {
        "custom_id": "request-2",
        "params": {
          "model": "claude-sonnet-5",
          "max_tokens": 1024,
          "messages": [{"role": "user", "content": "Name three colors."}]
        }
      }
    ]
  }'

Response example

Response

200 OK
{
  "id": "msgbatch_01ABC123",
  "type": "message_batch",
  "processing_status": "in_progress",
  "request_counts": {
    "processing": 2,
    "succeeded": 0,
    "errored": 0,
    "canceled": 0,
    "expired": 0
  },
  "ended_at": null,
  "created_at": "2026-11-01T10:00:00Z",
  "expires_at": "2026-11-02T10:00:00Z",
  "cancel_initiated_at": null,
  "archived_at": null,
  "results_url": null
}

Important fields

idstring
Message batch ID. Use it to retrieve, cancel, or delete the batch and to get its results.
processing_statusstring
in_progress, canceling, or ended.
request_countsobject
Number of requests that are processing, succeeded, errored, canceled, or expired.
expires_atstring
When the batch expires. Requests that have not finished by then end as expired.
results_urlstring|null
URL of the results. It is null until the batch has ended.

Authorization

BearerAuth
AuthorizationBearer <token>

API Key authentication. Create or manage API keys in Dashboard > API > API Keys.

In: header

Headers

X-TokenLab-Delivery-Policy?string

Per-request Delivery policy. Overrides the API key and Workspace defaults. Auto tries TokenLab Verified first and may switch once to Official only before output, request acceptance, or persistent resource creation.

Value in

  • "auto"
  • "verified"
  • "official"
Idempotency-Key?string

Optional key that makes a create request safe to retry. Send a new unique value, such as a UUID, for each task. A retry with the same key and the same body returns the result of the original create request, usually the original task, and does not create, dispatch, or charge a second task. A different body with a key that was already accepted is rejected with 409. A key longer than 255 characters is ignored, and the request then has no idempotency protection. See Retry safely with an idempotency key.

Length1 <= length <= 255

Request Body

application/json

Response

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json