Category: Claude AI

The Message Batches API lets you submit up to 100,000 Claude requests in a single call and receive results asynchronously — at exactly 50% of standard token prices. Most batches finish in under an hour. Results remain downloadable for 29 days. This page covers every verified limit, the per-tier rate limit tables, and how batch pricing stacks with prompt caching.

Pricing: 50% off standard rates

Every token processed through the Message Batches API is billed at half the standard input and output price. No quality difference from synchronous requests — only timing. The table below shows verified batch prices for active models.

Model	Batch input (per MTok)	Batch output (per MTok)	Standard input (per MTok)	Standard output (per MTok)
Claude Fable 5	$5.00	$25.00	$10.00	$50.00
Claude Opus 4.8 (legacy — still listed)	$2.50	$12.50	$5.00	$25.00
Claude Opus 4.7	$2.50	$12.50	$5.00	$25.00
Claude Opus 4.6	$2.50	$12.50	$5.00	$25.00
Claude Opus 4.5	$2.50	$12.50	$5.00	$25.00
Claude Sonnet 4.6 (legacy — still listed)	$1.50	$7.50	$3.00	$15.00
Claude Sonnet 4.5	$1.50	$7.50	$3.00	$15.00
Claude Haiku 4.5	$0.50	$2.50	$1.00	$5.00

Source: platform.claude.com/docs/en/build-with-claude/batch-processing

Key limits at a glance

Limit	Value
Maximum requests per batch	100,000
Maximum batch payload size	256 MB
Typical completion time	Under 1 hour
Hard expiration window	24 hours from creation
Result retention period	29 days after creation
Zero Data Retention eligible	No
Results format	JSONL, streamed via results_url
Supported models	All active Claude models

A batch expires if processing has not completed within 24 hours. Any individual request within that batch that did not finish is marked expired — you are not billed for expired or errored requests. Batch results (the JSONL file) are accessible for download for 29 days after the batch was created; after that the batch object itself is still visible but results can no longer be downloaded.

Message Batches API rate limits by tier

The Message Batches API has its own rate-limit pool, shared across all models, separate from the standard Messages API limits. The “processing queue” count refers to individual batch requests (not batches) that have been submitted but not yet completed by the model.

Tier	RPM (API calls)	Max batch requests in processing queue	Max batch requests per batch
Tier 1	50	100,000	100,000
Tier 2	1,000	200,000	100,000
Tier 3	2,000	300,000	100,000
Tier 4	4,000	500,000	100,000

Source: platform.claude.com/docs/en/api/rate-limits

RPM here limits how fast you can make HTTP requests to the Batches API endpoints (create, retrieve, list, cancel). It does not limit how many individual requests inside a batch are processed per minute — that is governed by the queue cap above. If high demand causes processing to slow, more individual requests within a batch may reach the 24-hour expiration limit.

Stacking batch pricing with prompt caching

The Batches API documentation explicitly states that the 50% batch discount and prompt caching discounts stack. Cache writes incur a one-time cost at 1.25x the base input rate (5-minute TTL) or 2x (1-hour TTL); subsequent cache reads cost 0.1x the base input rate. Because batches process asynchronously and may take longer than 5 minutes, Anthropic recommends using the 1-hour cache duration for batch requests that share large context.

The following example uses Claude Opus 4.8 (legacy — still listed) (standard input: $5.00/MTok) to show what each token type costs in a batch with a 1-hour cached system prompt.

Token type	Multiplier applied	Effective price per MTok	How calculated
Uncached input (standard)	1x	$5.00	Baseline
Uncached input (batch)	0.5x	$2.50	50% batch discount
Cache write — 1h TTL (batch)	2x × 0.5x = 1x	$5.00	2x write cost, then 50% batch
Cache read (batch)	0.1x × 0.5x = 0.05x	$0.25	10% read cost, then 50% batch
Output (batch)	0.5x of $25.00	$12.50	50% batch discount on output

In practice: if you cache a 50,000-token system prompt once and then read it across 1,000 batch requests, the cache write costs $0.25 (50K tokens at $5.00/MTok effective), while 1,000 cache reads cost $12.50 total (50M tokens at $0.25/MTok). The same 50 million tokens without caching would cost $125 in batch input (50 MTok at the $2.50/MTok batch rate). Cache hit rates on batches vary; Anthropic’s documentation notes typical rates of 30% to 98% depending on traffic patterns, since batch requests are processed concurrently rather than sequentially.

How results come back

When the batch finishes (or the 24-hour limit is reached), a results_url property is set on the batch object. Results are in JSONL format — one JSON object per line, in any order (not necessarily matching submission order). Each result carries the custom_id you assigned, plus a result object of type succeeded, errored, canceled, or expired. Streaming the results file rather than downloading it all at once is recommended for large batches. You are not billed for errored, canceled, or expired requests.

Related on Tygart Media: tokens to words · Claude Code billing · how much Claude costs.

Claude Opus 4 (claude-opus-4-20250514) and Claude Sonnet 4 (claude-sonnet-4-20250514) are deprecated and retire on June 15, 2026, after which requests to them return a 404. The official replacements are claude-opus-4-8 and claude-sonnet-4-6. But swapping the model string alone will break a working integration: depending on which target you choose, several request parameters that were valid on the May 2025 models now return a 400 error, and two changes alter behavior silently. This page maps each removed or changed parameter to the exact failure and the fix.

One distinction governs the whole migration. The Opus path (to claude-opus-4-8) is the strict one: it removes temperature/top_p/top_k and manual thinking budgets entirely. The Sonnet path (to claude-sonnet-4-6) is gentler: it keeps sampling parameters (with the older “one of temperature or top_p, not both” rule) and still accepts budget_tokens as deprecated-but-functional. The one rule both paths share: assistant-turn prefills now return 400.

The breaking-change matrix

Each row is a change that breaks on at least one migration target. “Error” means the API rejects the request server-side (HTTP 400) even though the SDK request type still type-checks. “Silent” means no error — the behavior simply differs.

Change	On Opus 4.8	On Sonnet 4.6	Symptom	Fix
thinking: {type:"enabled", budget_tokens:N}	400 error (removed)	Deprecated, still works	400 on Opus; cost/latency drift on Sonnet	thinking: {type:"adaptive"} + output_config.effort
temperature / top_p / top_k	400 error (removed)	Keep only one of temperature or top_p	400 on Opus if any set; 400 on Sonnet if both set	Remove on Opus; steer via prompt. Keep one on Sonnet
Assistant-turn prefill (last message role:"assistant")	400 error	400 error	Request rejected on both	output_config.format (structured outputs) or system-prompt instruction
thinking.display default	Defaults to "omitted"	Returns summarized text	Reasoning text empty on Opus (silent)	Set display: "summarized" on Opus
Tokenizer	New tokenizer (more tokens)	Unchanged tokenizer	Same text counts higher on Opus; max_tokens too tight	Re-baseline with count_tokens; add headroom
output_format (top-level)	Deprecated API-wide	Deprecated API-wide	Works, but slated for removal	Move to output_config: {format: {...}}

Model ID swaps and retirement dates

Retiring model	Model ID	Retires	Replacement
Claude Opus 4	claude-opus-4-20250514 (alias claude-opus-4-0)	June 15, 2026	claude-opus-4-8
Claude Sonnet 4	claude-sonnet-4-20250514 (alias claude-sonnet-4-0)	June 15, 2026	claude-sonnet-4-6

These are the original May 2025 models, not the later Opus 4.6 or Sonnet 4.5 releases. Use the exact replacement strings above — do not append a date suffix to claude-opus-4-8 or claude-sonnet-4-6 (they are dateless pinned snapshots).

budget_tokens to adaptive thinking

The Opus path removes the fixed thinking budget. thinking: {type:"enabled", budget_tokens:N} returns a 400 on claude-opus-4-8. The replacement is adaptive thinking — the model decides how much to think per request — with overall depth controlled by the effort parameter (low | medium | high | xhigh | max). There is no direct token-count equivalent; effort is an output-level control, not a thinking budget.

# Before (Claude Opus 4 / Sonnet 4)
client.messages.create(
    model="claude-opus-4-20250514",
    max_tokens=16000,
    thinking={"type": "enabled", "budget_tokens": 10000},
    messages=[{"role": "user", "content": "..."}],
)

# After (Claude Opus 4.8)
client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    output_config={"effort": "high"},  # or "max", "xhigh", "medium", "low"
    messages=[{"role": "user", "content": "..."}],
)

On the Sonnet path, budget_tokens is deprecated but still functional on claude-sonnet-4-6, so it will not 400 — but you should still migrate to adaptive thinking. Note also that Sonnet 4.6 defaults to effort: "high" where Sonnet 4 had no effort parameter at all; if you do not set it explicitly you may see higher latency and token use after the swap.

Sampling parameters: removed vs. restricted

This is where the two paths diverge most. On claude-opus-4-8, setting temperature, top_p, or top_k to any non-default value returns a 400. Remove them entirely and steer behavior through prompting instead. (If you used temperature=0 for determinism, note it never guaranteed identical outputs on prior models either.)

# Opus path — sampling params 400 on claude-opus-4-8
# Before
client.messages.create(
    model="claude-opus-4-20250514",
    temperature=0.7,
    top_p=0.9,
    messages=[...],
)

# After — remove them
client.messages.create(
    model="claude-opus-4-8",
    messages=[...],
)

On claude-sonnet-4-6 the older Claude 4.x rule still applies: you may pass one of temperature or top_p, but passing both returns a 400. So a Sonnet 4 to Sonnet 4.6 move only requires dropping one of the two if you were setting both.

Assistant-turn prefills to structured outputs

Prefilling the final assistant turn — ending your messages array with a role: "assistant" message to force a response shape — returns a 400 on both claude-opus-4-8 and claude-sonnet-4-6. This is the one breaking change you cannot dodge by choosing the gentler target. The replacement depends on what the prefill was doing.

Prefill was used for	Replacement
Forcing JSON / YAML / schema output	output_config.format with a json_schema
Forcing a classification label	A tool with an enum field, or structured outputs
Skipping preambles (“Here is…”)	System-prompt instruction: respond directly, no preamble
Continuing an interrupted response	Move continuation into the user turn
Steering around bad refusals	Usually unnecessary now — plain user-turn prompting suffices

# Before (fails on both targets) — prefill forcing JSON shape
messages=[
    {"role": "user", "content": "Extract the name."},
    {"role": "assistant", "content": "{\"name\": \""},
]

# After — structured outputs replace the prefill
client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    output_config={"format": {"type": "json_schema", "schema": SCHEMA}},
    messages=[{"role": "user", "content": "Extract the name."}],
)

Thinking display: the silent one

On claude-opus-4-8, thinking blocks still stream, but their thinking text field is empty unless you opt in — the default is display: "omitted". There is no error; if your UI rendered the summarized reasoning, it now shows a long pause before output. Restore it by setting the display mode:

thinking = {
    "type": "adaptive",
    "display": "summarized",  # default is "omitted" on Opus 4.8/4.7
}

The block-field name is unchanged — it is still block.thinking on a thinking-type block. The fix is the request parameter, not the response-handling code. (Sonnet 4.6 is not affected by this default change.)

The new tokenizer: re-baseline max_tokens

This change is Opus-only and easy to miss because it produces no error. claude-opus-4-8 uses the tokenizer introduced with Opus 4.7, under which the same text tokenizes to roughly 1x–1.35x as many tokens — up to about 35% more, around 30% on typical content, varying by workload. Three consequences:

What to check	Why
max_tokens ceilings and compaction triggers	The same output now consumes more tokens; tight limits truncate mid-thought
Client-side token estimators (e.g. fixed char-to-token ratios)	Calibrated against the old tokenizer; now undercount
Cost and rate-limit dashboards	count_tokens returns higher numbers; re-baseline before reacting

Re-run client.messages.count_tokens(model="claude-opus-4-8", ...) on a representative sample of your prompts. Do not apply a blanket multiplier. Sonnet 4.6 keeps the older tokenizer, so a Sonnet 4 to Sonnet 4.6 move has no tokenizer re-baseline to do.

The full checklist

Step	Opus 4 to 4.8	Sonnet 4 to 4.6
Update model ID string	Required	Required
Replace budget_tokens with adaptive thinking	Required (400)	Recommended (deprecated)
Sampling params	Remove all (400)	Keep only one (both 400)
Remove assistant-turn prefills	Required (400)	Required (400)
Set display: "summarized" if showing reasoning	Required for visible thinking	Not applicable
Re-baseline max_tokens for new tokenizer	Required	Not applicable
Set effort explicitly	Defaults to high	Defaults to high
Move output_format to output_config.format	Recommended	Recommended
Verify tool inputs parsed with a JSON parser	Recommended	Recommended
Spot-check one request, then roll out	Required	Required

If you run Claude Code, /claude-api migrate applies the model swap, breaking-parameter changes, prefill replacement, and effort calibration across a codebase, then produces a verify-it-yourself checklist. It asks you to confirm scope before editing any files.

Related on Tygart Media: Claude Fable 5 guide · API quickstart.