Building with the Claude API · lesson 15 of 17

Message Batches API

Submit thousands of messages.create requests in one job. 50% off input + output. Async (results within 24h, usually faster).

When to use

Offline classification.
Bulk extraction over a corpus.
Evaluation harnesses.
Backfills.
Anything where latency doesn't matter and throughput / cost do.

When NOT to use

Interactive UI.
Anything time-sensitive (SLA < 24h is risky).
Single requests (overhead exceeds the discount).

Shape

batch = client.messages.batches.create(
    requests=[
        {
            "custom_id": "row-001",
            "params": {
                "model": "claude-sonnet-4-6",
                "max_tokens": 1024,
                "messages": [{"role": "user", "content": "..."}],
            },
        },
        # up to 10,000 entries, up to 256MB total
    ]
)

Poll client.messages.batches.retrieve(batch.id) until processing_status = "ended", then fetch results_url.

Practical tips

Use custom_id to map results back to your input row.
A batch can mix models — useful for an eval comparing Haiku vs Sonnet.
Batches also benefit from prompt caching across the requests within them. Cache hits inside a batch are common.
Failures are per-request; the batch as a whole still completes. Inspect result.type ("succeeded" / "errored" / "canceled" / "expired").

CCA-F note