TokenLab

Files & Batches

Retrieve Message Batch

Retrieves the status and request counts of a Message Batch.

GET
/v1/messages/batches/{message_batch_id}

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_status is in_progress, canceling, or ended.
  • results_url is null until 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 return 409; retry later.

Example

Request

cURL
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 example

Response

200 OK
{
  "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