Files & Batches
Retrieve Message Batch
Retrieves the status and request counts of a Message Batch.
Overview
Return the status, request counts, and timestamps of a Message Batch that your organization created. Poll this endpoint until processing_status is ended, then get the results.
Notes
processing_statusisin_progress,canceling, orended.results_urlisnulluntil the batch has ended.- A batch that does not exist or was deleted returns
404. A batch that is not ready to be read yet can return409; retry later.
Request
curl -X GET "https://api.tokenlab.sh/v1/messages/batches/msgbatch_01ABC123" \
-H "x-api-key: sk-your-api-key" \
-H "anthropic-version: 2023-06-01"Response
{
"id": "msgbatch_01ABC123",
"type": "message_batch",
"processing_status": "ended",
"request_counts": {
"processing": 0,
"succeeded": 2,
"errored": 0,
"canceled": 0,
"expired": 0
},
"ended_at": "2026-11-01T10:20:00Z",
"created_at": "2026-11-01T10:00:00Z",
"expires_at": "2026-11-02T10:00:00Z",
"cancel_initiated_at": null,
"archived_at": null,
"results_url": "https://api.tokenlab.sh/v1/messages/batches/msgbatch_01ABC123/results"
}Important fields
processing_statusstring
in_progress, canceling, or ended.request_countsobject
Number of requests that are
processing, succeeded, errored, canceled, or expired.ended_atstring|null
When processing ended, or
null.cancel_initiated_atstring|null
When a cancel request was accepted, or
null.results_urlstring|null
URL of the results, or
null.Authorization
BearerAuth AuthorizationBearer <token>
API Key authentication. Create or manage API keys in Dashboard > API > API Keys.
In: header
Path Parameters
message_batch_id*string
Message batch identifier
Response
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json