# Anthropic — Message Batches API

Status: DOCUMENTED · LIVE_VERIFIED (all 6 endpoints exercised on 2026-09-18 with a regular API key; two batches created, polled, results downloaded, cancelled and deleted).
Sources:

• https://platform.claude.com/docs/en/build-with-claude/batch-processing (user guide)
• https://platform.claude.com/docs/en/api/messages/batches/create · /retrieve · /list · /cancel · /delete · /results (reference; api/beta/messages/batches/* are the beta-typed twins)
• https://platform.claude.com/docs/en/api/rate-limits#message-batches-api
• Live run: tmp-live/platform-anthropic/batches-scenario.json (sanitized), reports/live-requests.jsonl

Last verified: 2026-09-18

# 1. What it is

Asynchronous, bulk submission of Messages API requests. You POST a list of independent requests[] (each = custom_id + full Messages params), the batch is processed in the background, you poll the batch object until processing_status == "ended", then download a .jsonl results file. Each request is processed independently (one failure does not affect the others) and results are not ordered — match them with custom_id.

# What can be batched

Everything the Messages API accepts, mixed freely inside one batch: vision, PDFs, system prompts, multi-turn, extended thinking, tool use incl. all server tools (web search, web fetch, code execution, MCP connector, advisor, tool search), structured outputs, prompt caching, "most beta features" (put the anthropic-beta header on the batch create call; it applies to every request). The batch worker runs the same server-side agentic loop as the synchronous API but with more iterations per turn before returning stop_reason: "pause_turn"; a pause_turn result must be continued in a follow-up request. web_search is throttled per organization inside batches and retried automatically. max_tokens: 0 (cache pre-warm) is rejected. Prompt-cache hits are best-effort (30–98 %); the 1-hour TTL (cache_control: {type: "ephemeral", ttl: "1h"}) is recommended.

# 2. Endpoints

results_url returned on the batch object is the absolute URL of the results endpoint (https://api.anthropic.com/v1/messages/batches/{id}/results).

# Pagination (list)

ID-cursor style: limit (1–100, default 20), before_id, after_id. Response { "data": [...], "has_more": bool, "first_id": ..., "last_id": ... }. Most recently created first. Observed: ?limit=1 → one batch, has_more: false (only one batch existed); ?after_id=<that id> → data: [].

# 3. Request body (create)

{
  "requests": [
    { "custom_id": "ok-1",
      "params": { "model": "claude-haiku-4-5-20251001", "max_tokens": 8,
                  "messages": [{"role": "user", "content": "Reply with OK."}] } },
    { "custom_id": "bad-model-1",
      "params": { "model": "claude-does-not-exist-1", "max_tokens": 8,
                  "messages": [{"role": "user", "content": "Reply with OK."}] } }
  ]
}

• requests[] — 1..100,000 items. Empty list → 400 invalid_request_error: "requests: List should have at least 1 item after validation, not 0" (observed).
• requests[].custom_id — string, 1–64 chars, ^[a-zA-Z0-9_-]{1,64}$, unique within the batch. Duplicate → 400 "requests: custom_ids must be unique within a batch. Duplicate custom_idfound:dup" (observed).
• requests[].params — the complete POST /v1/messages body (model, max_tokens, messages, system, tools, tool_choice, thinking, output_config, container, mcp_servers, context_management, metadata, service_tier, stop_sequences, temperature/top_p/top_k, …). Full flattened list (380 parameters): generated/fragments/parameters/anthropic-batches.json.
• Per-request validation that can only be detected at processing time (e.g. unknown model) does not fail the create call: it surfaces as an errored result (observed: not_found_error "model: claude-does-not-exist-1").

# 4. The MessageBatch object

{
  "id": "msgbatch_01F32YGd3yxLE1nLvRTSo8QD", "type": "message_batch",
  "processing_status": "in_progress",
  "request_counts": {"processing": 2, "succeeded": 0, "errored": 0, "canceled": 0, "expired": 0},
  "ended_at": null, "created_at": "2026-09-19T01:49:44.445332+00:00",
  "expires_at": "2026-09-20T01:49:44.445332+00:00", "archived_at": null,
  "cancel_initiated_at": null, "results_url": null
}

# Lifecycle

stateDiagram-v2
  [*] --> in_progress : POST /v1/messages/batches
  in_progress --> ended : all requests succeeded/errored/expired (≤ 24 h)
  in_progress --> canceling : POST …/cancel
  canceling --> ended : in-flight requests finish or are canceled
  ended --> [*] : DELETE (allowed only here)

• DELETE while in_progress → 400 invalid_request_error "In progress batches cannot be deleted. Consider canceling the batch instead." (observed). While canceling → 400 "Batch … has not finished canceling. Please wait for cancellation to completed before deleting." (observed, sic). After ended → 200 {"id": "...", "type": "message_batch_deleted"}; a later GET returns 404 not_found_error "Message Batch … not found.".
• POST …/cancel is idempotent: second call returned 200 with the same canceling object. Requests already finished before the cancel keep their result; the rest end as canceled. Observed for a fresh 1-request batch: request_counts.canceled = 1, ended ~30 s later.
• GET …/results before ended → 404 not_found_error "Message Batch … has no available results." (observed).

# 5. Results (GET …/results)

• Content type application/x-jsonl (one JSON object per line, streamed; may be large — read line by line). Order is not the request order (observed: bad-model-1 came before ok-1).
• Line shape (MessageBatchIndividualResponse): {"custom_id": "...", "result": {...}} with result.type ∈:

Errored requests are not billed; expired/canceled requests are not billed either (documented). Errors inside errored can be any Messages API error (invalid_request_error, not_found_error, rate_limit_error, overloaded_error, api_error…) — retry the overloaded/api_error ones in a new batch.

# 6. Errors (batch endpoints themselves)

# 7. SDK surface

Python typing helpers (documented): anthropic.types.messages.batch_create_params.Request, anthropic.types.message_create_params.MessageCreateParamsNonStreaming.

# 8. Live run summary (2026-09-18, claude-haiku-4-5-20251001, cost ≈ $0.0001)

Both batches were deleted; no residue. Examples: examples/anthropic/batch/ · Tests: tests/anthropic/test_batches.py (run_batch_tests marker).

# 9. Gotchas

• max_tokens: 0 and stream are rejected at create time; an invalid model is not — it becomes an errored result.
• Results are unordered and keyed only by custom_id; the results endpoint 404s until ended.
• You cannot delete an in-progress batch — cancel first, then wait for ended.
• Retention clock is created_at (29 days), not ended_at.
• Batch responses report usage.service_tier: "batch"; Usage/Cost Admin reports can filter service_tiers[]=batch.
• Console downloads of results can be disabled per organization/workspace (privacy control).