Message Batches run large sets of Messages API requests asynchronously at 50% of the normal token rate, in exchange for latency. They share limits and pricing with the OpenAI-format Batch API.
The API follows Anthropic's Message Batches API, so the official Anthropic clients work unchanged.
The flow
- Create a batch with
POST /v1/messages/batches, carrying every request inline. - Poll it with
GET /v1/messages/batches/{id}untilprocessing_statusisended. - Stream the results from
GET /v1/messages/batches/{id}/results.
There is no input file to upload: the requests are the body of the create call. PrivateMind stores them as an input file named msgbatch_….jsonl with purpose: batch. The file appears in your file list, can't be deleted through the Files API, and is removed with the batch.
A batch created with an org application key is shared with the org, unless a request references a private file. One created with any other key is private to that user, and so is its input file. See who can see a file.
Create a batch
curl -s "https://api.privatemind.com/v1/messages/batches" \
-H "x-api-key: $PMIND_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "Content-Type: application/json" \
-d '{
"requests": [
{"custom_id": "req-1", "params": {"model": "<model-id>", "max_tokens": 1024,
"messages": [{"role": "user", "content": "Summarise: ..."}]}},
{"custom_id": "req-2", "params": {"model": "<model-id>", "max_tokens": 1024,
"messages": [{"role": "user", "content": "Translate to French: ..."}]}}
]
}'import anthropic
client = anthropic.Anthropic(base_url="https://api.privatemind.com", api_key=PMIND_KEY)
batch = client.messages.batches.create(requests=[
{"custom_id": "req-1", "params": {"model": "<model-id>", "max_tokens": 1024,
"messages": [{"role": "user", "content": "Summarise: ..."}]}},
{"custom_id": "req-2", "params": {"model": "<model-id>", "max_tokens": 1024,
"messages": [{"role": "user", "content": "Translate to French: ..."}]}},
])
print(batch.id, batch.processing_status) # msgbatch_... in_progresscustom_id(required): 1 to 64 letters, digits,_or-, unique within the batch. Results are matched by it, not by order.params(required): a normal/v1/messagesrequest.max_tokensis required andstreamis ignored. Thinking, tools, images andfilesources all work.
Every request is checked when you create the batch. One invalid request rejects the whole batch, and nothing is created. The 400 names the request, for example requests.3 (req-4): max_tokens: Field required. A model without batch turned on in your org also rejects the batch, with a 400 such as requests.0: body.model is not batch-eligible on this cluster. A batch that would take your org over its storage quota gets 413.
The batch object
{
"id": "msgbatch_abc123",
"type": "message_batch",
"processing_status": "in_progress",
"request_counts": { "processing": 2, "succeeded": 0, "errored": 0, "canceled": 0, "expired": 0 },
"created_at": "2026-09-30T02:04:32Z",
"expires_at": "2026-10-01T02:04:32Z",
"ended_at": null,
"cancel_initiated_at": null,
"archived_at": null,
"results_url": null
}processing_status is in_progress, then canceling if you cancel with requests still running, then ended. Once it is ended, ended_at and results_url are set.
request_counts always adds up to the number of requests and updates as they finish, so you can track progress.
Check status
curl -s "https://api.privatemind.com/v1/messages/batches/msgbatch_abc123" \
-H "x-api-key: $PMIND_KEY" -H "anthropic-version: 2023-06-01"import time
while batch.processing_status != "ended":
time.sleep(30)
batch = client.messages.batches.retrieve(batch.id)
print(batch.request_counts)There is no push notification, so poll at a modest interval.
Results
Once the batch has ended, GET /v1/messages/batches/{id}/results streams JSONL with one line per request. Lines can come in any order, so match them on custom_id. Asking earlier returns 409, and the Python SDK's results() raises an error without sending the request, because it checks results_url first.
for line in client.messages.batches.results(batch.id):
if line.result.type == "succeeded":
print(line.custom_id, [b.text for b in line.result.message.content if b.type == "text"])
else:
print(line.custom_id, line.result.type)curl -s "https://api.privatemind.com/v1/messages/batches/msgbatch_abc123/results" \
-H "x-api-key: $PMIND_KEY" -H "anthropic-version: 2023-06-01"Each line has your custom_id and a result of one of four types:
{"custom_id": "req-1", "result": {"type": "succeeded", "message": {"id": "msg_...", "type": "message", "role": "assistant", "content": [ ... ], "stop_reason": "end_turn", "usage": { ... }}}}
{"custom_id": "req-2", "result": {"type": "errored", "error": {"type": "error", "error": {"type": "invalid_request_error", "message": "..."}}}}
{"custom_id": "req-3", "result": {"type": "canceled"}}
{"custom_id": "req-4", "result": {"type": "expired"}}succeeded:messageis exactly what/v1/messageswould have returned.errored:erroruses the same types as the error table, such asinvalid_request_errororbilling_error.canceled: you cancelled the batch before this request started.expired: the 24-hour window ended before this request ran.
Cancel a batch
curl -s -X POST "https://api.privatemind.com/v1/messages/batches/msgbatch_abc123/cancel" \
-H "x-api-key: $PMIND_KEY" -H "anthropic-version: 2023-06-01"Requests that have not started are cancelled. Requests already running finish and are billed, so the batch may stay canceling briefly before it ends. Cancelling an ended batch returns it unchanged.
List batches
for b in client.messages.batches.list(limit=20):
print(b.id, b.processing_status)GET /v1/messages/batches lists the message batches you can see, newest first. Page with limit (1 to 1000, default 20) and after_id or before_id. The SDK pages for you. Batches from the OpenAI-format Batch API are not in this list.
Delete a batch
curl -s -X DELETE "https://api.privatemind.com/v1/messages/batches/msgbatch_abc123" \
-H "x-api-key: $PMIND_KEY" -H "anthropic-version: 2023-06-01"Only an ended batch can be deleted. Deleting a running one returns 409, so cancel it first. Deleting removes the batch and its results at once. Usage already recorded for it stays in usage.
Limits and retention
- Requests per batch: up to 10,000.
- Request body: up to 64 MB for the create call.
- Completion window: 24 hours from creation. Requests not run by then expire.
- Scheduling: batch work shares capacity with live traffic and slows it by no more than a small margin. See When batch work runs.
- Pricing: 50% of the normal per-token rate, applied to work that actually ran.
- Rate of creation: each org can create 20 batches per hour and have 50,000 requests queued or running. Both caps are shared with the Batch API.
- Retention: results are kept for 29 days after the batch ends. Then they are deleted,
archived_atis set andresults_urlgoes back tonull. Delete sooner if you do not need them. - Storage: the batch's internal input file counts toward your org's storage quota until the batch is deleted or retention removes it.
Batch requests and results hold your content on our servers, so Message Batches are not eligible for zero-data-retention (ZDR) arrangements.
Where next
- Messages API for the request shape each batch request carries.
- Batch API for the OpenAI-shaped equivalent.
- Budgets and limits for how the 50% batch rate counts against your budget.
- Errors for status codes and error types.