Files & Batches
Create Message Batch
Creates a batch of Messages requests that run asynchronously.
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
requestshas acustom_idandparams.paramstakes the same fields as Create Message, includingmax_tokens. Items cannot usespeed: "fast". custom_idis 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
400when 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
402when 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_idcontent, sendanthropic-beta: files-api-2025-04-14. - Send an
Idempotency-Keyto retry a timed-out create request safely. See Retry safely with an idempotency key.
Request
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
{
"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
in_progress, canceling, or ended.processing, succeeded, errored, canceled, or expired.expired.null until the batch has ended.Authorization
BearerAuth API Key authentication. Create or manage API keys in Dashboard > API > API Keys.
In: header
Headers
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"
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.
1 <= length <= 255Request 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