Claude Message Batches

Use Message Batches for independent jobs that do not need an immediate interactive answer. A batch is processed asynchronously; its overall completion does not mean every item succeeded.

#Create a batch

This Python example requires the anthropic package, an authorized API key and ANTHROPIC_MODEL. Creating a batch starts real processing and may incur charges.

pythonCopy
import os
from anthropic import Anthropic

client = Anthropic()
batch = client.messages.batches.create(requests=[{
    "custom_id": "sample-001",
    "params": {
        "model": os.environ["ANTHROPIC_MODEL"],
        "max_tokens": 128,
        "messages": [{"role": "user", "content": "Define a Python iterator."}],
    },
}])
print(batch.id, batch.processing_status)

Retain the batch ID and a durable mapping from custom_id to the original input. Do not create another batch simply because a client timed out; reconcile the first operation first.

#Retrieve status and results

The following fragment uses the same client and saved batch.id:

pythonCopy
status = client.messages.batches.retrieve(batch.id)
if status.processing_status == "ended":
    for item in client.messages.batches.results(batch.id):
        print(item.custom_id, item.result.type)

Poll with a bounded interval and a deadline. Match results by custom_id, because output order is not guaranteed. Handle succeeded, errored, canceled and expired separately. Retry only eligible failed items after recording their original outcome.

Batch size, retention, processing window and discounts can change. Check the official reference and your workspace's rate/spend limits before submitting a large job. Cancellation can still leave already processed items; it is not proof of zero usage.

Batch processing↗ · Batches API↗