Message Batch Processing

Overview (confidence: high)

Message batch processing is the asynchronous processing of large volumes of Messages API requests via the Message Batches API — Anthropic’s implementation of the batch pattern. Instead of processing requests one at a time with immediate responses, multiple requests are submitted together and processed asynchronously. Most batches finish in under 1 hour, and all usage is charged at 50% of standard API prices.

It fits when you need to process large volumes of data, immediate responses are not required, cost efficiency matters, or you’re running large-scale evaluations or analyses.

Batch Limitations (confidence: high)

• A batch is limited to 100,000 Message requests or 256 MB in size, whichever comes first.
• Results accessible when all messages complete or after 24 hours, whichever comes first; batches expire if processing doesn’t complete within 24 hours.
• Results available for 29 days after creation.
• Batches are scoped to a Workspace.
• Each batched request must have max_tokens of at least 1; max_tokens: 0 (cache pre-warming) is not supported.
• Processing may be slowed by demand; batches may go slightly over the Workspace’s configured spend limit.

What Can Be Batched (confidence: high)

Almost any Messages API request: vision, tool use (including server tools — web search, web fetch, code execution, MCP connectors, advisor, tool search), system messages, multi-turn conversations, extended thinking, and most beta features. Each request is processed independently, so different request types can be mixed in one batch.

Unsupported parameters: stream: true, speed (Fast mode), store/previous_thread_event_id (Threads — stateful), cache_hint/context_hint, max_tokens: 0, and research preview mode.

Server Tools and the Agentic Loop (confidence: high)

All server tools work in batch requests — the batch worker runs the same server-side agentic loop as the synchronous Messages API. Because there’s no open connection to maintain, the batch loop runs more iterations per turn before returning stop_reason: "pause_turn"; a paused turn can be continued in a follow-up request. The batch worker throttles web_search per organization and retries automatically.

Extended Output (beta) (confidence: high)

The output-300k-2026-03-24 beta header raises the max_tokens cap to 300,000 for batch requests on Claude Opus 5, Opus 4.8/4.7/4.6, Sonnet 5, and Sonnet 4.6 — available on the Message Batches API only, not the synchronous Messages API. A single 300k-token generation can take over an hour; standard batch pricing (50%) applies.

Prompt Caching in Batches (confidence: high)

The Batches API supports prompt caching; the discounts stack with batch pricing. Cache hits are best-effort (typically 30–98% hit rates). To maximize hits: include identical cache_control blocks in every request, maintain a steady stream to prevent 5-minute cache expiry, and share as much cached content as possible. For longer batches, consider the 1-hour cache duration.

Best Practices (confidence: high)

• Poll processing status and implement retry logic for failed requests.
• Use meaningful custom_id values — result order is not guaranteed, so match via custom_id.
• Dry-run a single request shape with the Messages API to avoid validation errors.
• Break very large datasets into multiple batches.
• The failure of one request doesn’t affect the others.

Related

prompt-caching token-usage-reduction tool-context-management tool-search-tool

Open Questions

• Whether the 50% batch discount and 300k extended-output cap signal a general industry shift toward async batch paths for long-form generation.
• How batch-mode pause_turn continuation interacts with tool search’s deferred loading in practice.

Sources

• raw/external/platform-claude-com-batch-processing-d8088a83.md