Check 24-hour turnaround and constraints before using Claude Message Batches API for 50% discount

What are the discount rates and eligibility conditions for the Message Batches API?

According to the models and pricing documentation, the Message Batches API provides a flat 50% unit price discount across major models, including Claude 3.5 Sonnet, Claude 3.5 Haiku, and Claude 3 Opus. Compared to the standard synchronous /v1/messages endpoint, both input and output token rates are halved.

The source is the Anthropic official pricing documentation, verified on October 26, 2026.

Prompt caching can also be used inside batch requests. When stable system instructions exceeding 1,024 tokens are shared across batch items, cache writes cost 62.5% of base input rates, and cache reads drop to just 5%. Reusing shared instructions during bulk dataset processing maximizes overall cost savings.

How do the 24-hour turnaround window and asynchronous retrieval work?

The batch processing documentation specifies a turnaround SLA of up to 24 hours. While many jobs finish within minutes depending on platform load, infrastructure design must accommodate the full 24-hour window.

Batches are submitted via JSON payloads to the POST /v1/messages/batches endpoint. A single batch can include up to 10,000 individual message requests, with a maximum total payload size of 32MB. Upon receipt, the API immediately returns a unique batch identifier (id) in the in_progress state.

When execution concludes, the batch status transitions to ended, exposing a results_url. You download and parse a JSON Lines (JSONL) file from this URL. Because result files are retained for 29 days following completion, you should retrieve and archive them in persistent storage before expiration.

How are errors and cancellations handled for individual requests?

Each request in a batch is tagged with a custom identifier string via custom_id. Developers supply this identifier (up to 64 characters) to correlate individual responses within the downloaded result file.

Requests inside a batch execute independently. If 3 out of 1,000 requests encounter token limit errors or invalid parameters, processing for the remaining 997 requests proceeds unaffected. Each line in the result file records the custom_id alongside a execution state: succeeded, errored, canceled, or expired.

If you need to halt an active batch, call the POST /v1/messages/batches/{batch_id}/cancel endpoint. The status shifts to canceling, and unprocessed requests are marked as canceled without incurring charges. Only requests that completed execution prior to cancellation are billed.

Which production workloads are best suited for batch processing?

The batch API suits backend workloads where cost efficiency takes precedence over immediate latency. Review your candidate pipelines against these criteria before migrating synchronous code:

1. Asynchronous data pipelines without immediate user interaction: Daily support ticket classification, bulk document labeling, and overnight OCR verification benefit substantially.
2. Large-scale model evaluation and benchmark suites: Running prompt iterations across tens of thousands of test cases cuts evaluation budgets in half.
3. Scheduled knowledge base summarization and embeddings: Nightly jobs that ingest and condense documentation or wiki updates fit naturally.
4. Exclusion of user-facing interactive interfaces: Never deploy batch endpoints for user chat interfaces or real-time code autocomplete where users expect instantaneous feedback.

These considerations serve as technical recommendations for system architecture. Separate latency-critical user paths from asynchronous background queues cleanly.

What should developers verify in code and infrastructure before adoption?

The Python SDK repository illustrates that batch processing patterns diverge significantly from synchronous calls. Rather than blocking on a single request, systems require polling loops or asynchronous worker queues.

First, set up a dedicated database table to persist batch metadata. Storing the batch id, creation timestamp, execution status, list of custom_id values, and original record mappings ensures safe reconciliation when results arrive.

Second, inspect your account tier rate limits for enqueued tokens. Anthropic enforces separate limits on the cumulative volume of tokens queued in batch processing alongside standard request-per-minute constraints. If your payload exceeds the queue ceiling, the API returns a rate_limit_error, requiring you to partition large workloads into smaller batches.

Review your backend services today to isolate non-real-time jobs, and validate payload parsing logic with a small pilot batch first. The official documentation was verified on October 26, 2026.