How the Message Batches API works

When you send a request to the Message Batches API:

1. The system creates a new Message Batch with the provided Messages requests.
2. The batch is then processed asynchronously, with each request handled independently.
3. You can poll for the status of the batch and retrieve results when processing has ended for all requests.

This is especially useful for bulk operations that don't require immediate results, such as:

• Large-scale evaluations: Process thousands of test cases efficiently.
• Content moderation: Analyze large volumes of user-generated content asynchronously.
• Data analysis: Generate insights or summaries for large datasets.
• Bulk content generation: Create large amounts of text for various purposes (for example, product descriptions, article summaries).

Batch limitations

• A Message Batch is limited to either 100,000 Message requests or 256 MB in size, whichever is reached first.
• The system processes each batch as fast as possible, with most batches completing within 1 hour. You can access batch results when all messages have completed or after 24 hours, whichever comes first. Batches expire if processing does not complete within 24 hours.
• Batch results are available for 29 days after creation. After that, you may still view the Batch, but its results will no longer be available for download.
• Batches are scoped to a Workspace. You may view all batches (and their results) that were created within the Workspace your request runs in.
• Rate limits apply to both Batches API HTTP requests and the number of requests within a batch waiting to be processed. See Message Batches API rate limits. Additionally, processing may be slowed down based on current demand and your request volume. In that case, you may see more requests expiring after 24 hours.
• Because of high throughput and concurrent processing, batches may go slightly over your Workspace's configured spend limit.
• Each batched request must have max_tokens of at least 1. max_tokens: 0 (cache pre-warming) is not supported inside a batch, because an ephemeral cache entry written during batch processing would likely expire before the follow-up request runs.

Supported models

All active models support the Message Batches API.

What can be batched

Almost any request you can make to the Messages API can be included in a batch. This includes:

• Vision
• Tool use, including all server tools (web search, web fetch, code execution, MCP connectors, advisor, and tool search)
• System messages
• Multi-turn conversations
• Extended thinking
• Most beta features

Because each request in the batch is processed independently, you can mix different types of requests within a single batch.

A small number of Messages API parameters are not supported in batch requests. Including any of these returns a validation error:

Parameter	Why
stream: true	Batch results come back as a single file, not a stream.
speed (Fast mode)	Fast mode tunes synchronous latency, which doesn't apply to asynchronous batch processing.
max_tokens: 0	See Batch limitations.

Because batches can take longer than 5 minutes to process, consider using the 1-hour cache duration with prompt caching for better cache hit rates when processing batches with shared context.