Message Batches API
APIDefinition
An asynchronous Claude API for processing multiple requests in a batch with 50% cost savings versus synchronous requests. Processing takes up to 24 hours with no guaranteed latency SLA. Does not support iterative tool use, streaming, or prompt caching. Best for scheduled, non-blocking analysis.
Example Usage
Use batch API for overnight report generation across thousands of records; use synchronous API for blocking pre-merge PR checks.
Why It Matters for the CCA-F Exam
The Batches API is tested heavily because its constraints are easy to confuse. Candidates must know: 50% cost savings, up to 24 hours processing, no streaming, no iterative tool use, no prompt caching, and that `custom_id` is the correct correlation mechanism. Questions also distinguish when to use batch vs synchronous by latency and interactivity requirements.
In Depth
The Message Batches API is an asynchronous interface for submitting multiple independent Claude requests in a single batch operation, with a guaranteed 50% cost reduction compared to equivalent synchronous requests. It is designed for workloads where latency tolerance is high and throughput matters more than time-to-first-token.
How it works
You construct a batch by assembling an array of request objects, each with a custom_id string you control and a params object that mirrors a standard messages request (model, max_tokens, messages, system, tools, etc.). You POST this array to the batches endpoint. The API immediately returns a batch object with a processing_status of "in_progress" and an id you use for polling.
Processing is not instant — the SLA allows up to 24 hours, though in practice batches often complete within minutes. There is no webhook; you poll GET /v1/messages/batches/{id} until processing_status is "ended". Then you stream the results from the batch's results_url, which delivers newline-delimited JSON — one result record per line, each containing the custom_id and either a result (the full messages response) or an error.
Results are not guaranteed to arrive in submission order. Always match results to your original requests using custom_id.
What the Batches API does not support
Three constraints frequently appear on the CCA-F exam:
- No streaming — batch requests are fire-and-forget; there is no live SSE connection.
- No iterative tool use — you cannot run a multi-turn tool loop inside a single batch request. Tool calls in batch results must be resolved externally and resubmitted as new requests.
- No prompt caching — cache-control headers on batch requests are ignored.
When to use it
The Batches API excels at large-scale async jobs: nightly sentiment analysis over thousands of support tickets, bulk document classification, evaluating a model against a test suite, or generating reports for a scheduled job. It is the wrong choice for any user-facing interaction (use synchronous streaming) or any workflow requiring real-time tool use (use the synchronous API with tool loops).
A practical integration pattern is to use custom_id to encode a record identifier from your data store, making it trivial to join batch results back to the originating rows after polling.
For cost-sensitive workloads that need faster turnaround than 24 hours, prompt caching on synchronous requests is the alternative lever — though it and the Batches API are mutually exclusive. See Batch Processing Strategy for decision guidance.
Frequently Asked Questions
How do I match batch results to my original requests?
Each result record contains the `custom_id` you supplied in the original request. Assign `custom_id` values that map directly to primary keys or identifiers in your data store (e.g., `"ticket-8471"`). Do not rely on result order, because results are delivered in processing completion order, not submission order.
Can I cancel a batch in progress?
Yes. A batch can be cancelled by sending a POST to its cancel endpoint while `processing_status` is `"in_progress"`. Requests that were already processed before the cancel are still billed. The batch status changes to `"canceling"` and eventually `"ended"` with partial results available.
What is the maximum batch size?
A single batch can contain up to 10,000 requests. If your workload exceeds this, split it across multiple batches and track them independently. The 50% discount applies to each batch regardless of size, so splitting has no cost penalty.