Message Batches API

1 · What the Message Batches API is essential

Most of the time you call Claude one request at a time and wait for the answer — that's the synchronous Messages API you already know. But sometimes you have thousands of requests and no human waiting on any single one: classify a week of support tickets overnight, summarize 50,000 documents, generate embeddings-style labels for a whole catalog. For that, Anthropic gives you the Message Batches API.

A batch is exactly what it sounds like: you hand Claude a list of independent requests in one call, Anthropic processes them asynchronously (in the background, on its own schedule), and you come back later to collect the results. Each request in the batch is an ordinary Messages API request — same model, max_tokens, messages — just wrapped with a label you choose (custom_id) so you can tell the answers apart.

The trade you're making: you give up immediacy (results aren't instant — most batches finish within an hour, and the hard cap is 24 hours) and you get back ~50% off every input and output token. For non-urgent bulk work, that's a huge lever.

2 · The batch lifecycle essential

Every batch goes through the same four beats. Learn this shape once and the code below is just wiring:

Read it left to right. First you build a list of requests, each tagged with a custom_id. You submit the list and get back a batch object with an id and a processing_status. Because processing happens in the background, you poll — ask "are you done yet?" — until the status becomes "ended". Then you retrieve the results, which arrive in any order, and use your custom_ids to line each answer back up with the request that produced it. The whole run is billed at roughly half the normal per-token price.

3 · Recipe 1 — submit a batch essential

Here is the real SDK, end to end for the submit step. Each request is wrapped in a Request with a custom_id you choose and a params block that is a normal non-streaming Messages request. The custom_id is your label — use something meaningful (a ticket ID, a row key) so you can match results later.

submit.py# needs: pip install anthropic + ANTHROPIC_API_KEY; makes real API calls
import anthropic
from anthropic.types.message_create_params import MessageCreateParamsNonStreaming
from anthropic.types.messages.batch_create_params import Request

client = anthropic.Anthropic()   # reads ANTHROPIC_API_KEY from the environment

tickets = {
    "ticket-8801": "I was charged twice for my subscription this month.",
    "ticket-8802": "How do I export my data to CSV?",
    "ticket-8803": "The app crashes every time I open the reports tab.",
}

requests = [
    Request(
        custom_id=ticket_id,                         # YOUR label — match results by this
        params=MessageCreateParamsNonStreaming(
            model="claude-haiku-4-5",                # cheap+fast: classification is easy work
            max_tokens=64,
            system="Classify the ticket as one word: billing, howto, or bug.",
            messages=[{"role": "user", "content": text}],
        ),
    )
    for ticket_id, text in tickets.items()
]

batch = client.messages.batches.create(requests=requests)
print(batch.id)                  # e.g. msgbatch_01AbC...  — save this
print(batch.processing_status)   # "in_progress"

4 · Recipe 2 — poll until the batch ends intermediate

After submitting you have a batch id but no answers yet. You poll: call retrieve(id) on a loop and check processing_status. When it flips to "ended", processing is finished (whether every item succeeded, errored, or expired — "ended" just means the batch is done being worked on).

poll.py# needs: pip install anthropic + ANTHROPIC_API_KEY; makes real API calls
import time
import anthropic

client = anthropic.Anthropic()

while True:
    batch = client.messages.batches.retrieve("msgbatch_01AbC...")   # the id from submit
    if batch.processing_status == "ended":
        break
    # request_counts breaks the batch down while it runs
    counts = batch.request_counts
    print("still working:", counts.processing,
          "| done:", counts.succeeded, "| errored:", counts.errored)
    time.sleep(30)      # be patient — most batches finish within an hour, max 24h

print("batch ended")
print("succeeded:", batch.request_counts.succeeded)
print("errored:  ", batch.request_counts.errored)

5 · Recipe 3 — retrieve results & match by custom_id intermediate

Once the batch has ended, stream the results with .results(id). Each result carries the custom_id you set and a result whose .type tells you what happened. On success, the full Message is at result.result.message — the same object a normal call returns, so you read .content the same way. Build a dict keyed by custom_id so the arbitrary arrival order stops mattering.

results.py# needs: pip install anthropic + ANTHROPIC_API_KEY; makes real API calls
import anthropic

client = anthropic.Anthropic()

answers = {}
for result in client.messages.batches.results("msgbatch_01AbC..."):
    cid = result.custom_id                 # the label you chose at submit time
    kind = result.result.type              # succeeded | errored | canceled | expired
    if kind == "succeeded":
        msg = result.result.message        # a normal Message object
        text = next((b.text for b in msg.content if b.type == "text"), "")
        answers[cid] = text
    elif kind == "errored":
        # per-item failure — the rest of the batch is unaffected
        answers[cid] = f"ERROR: {result.result.error.type}"
    elif kind == "expired":
        answers[cid] = "EXPIRED — resubmit this one"
    elif kind == "canceled":
        answers[cid] = "CANCELED"

# arrival order was arbitrary; the dict lines everything back up by id
for cid in sorted(answers):
    print(cid, "->", answers[cid])

ticket-8801 -> billing
ticket-8802 -> howto
ticket-8803 -> bug

6 · Error handling per item advanced

In the synchronous API a bad request raises an exception and you deal with it right there. In a batch there is no single call to wrap in try/except — instead, each item carries its own outcome. The four result.result.type values map to four different reactions:

The practical rule: treat the results stream as a reconciliation step. Walk every item, route successes to your output, and collect the errored / expired custom_ids into a "retry" list you can feed straight into the next batch.

7 · Batch vs realtime vs streaming — when to use which advanced

The API gives you three delivery modes for the same underlying model. Choosing correctly is a latency-vs-cost decision:

A simple test: is anyone blocked on this exact response? If yes → synchronous or streaming. If the work can happen overnight or "sometime in the next hour" → batch, and take the discount. Streaming and batching solve opposite problems — streaming minimizes perceived latency for one interactive request; batching maximizes throughput per dollar for many non-interactive ones. Don't reach for a batch just to save money on a latency-sensitive path.

8 · Cost math (this one runs offline) professional

Before you commit a big job to a batch, it's worth doing the arithmetic: how much does the ~50% discount actually save, and is the added latency worth it? The helper below is pure stdlib and runs with a plain python file.py — no API key, no network. It compares the realtime cost of N requests against the batch cost.

cost.pydef batch_savings(num_requests, in_tokens, out_tokens,
                  in_price_per_mtok, out_price_per_mtok, batch_discount=0.50):
    """Compare realtime vs batch cost for a bulk job. Prices are $ per 1M tokens.
    batch_discount=0.50 means batch pays 50% of the realtime per-token price."""
    per_request = (in_tokens * in_price_per_mtok
                   + out_tokens * out_price_per_mtok) / 1_000_000
    realtime = per_request * num_requests
    batch = realtime * (1 - batch_discount)
    return {
        "realtime_usd": round(realtime, 2),
        "batch_usd": round(batch, 2),
        "saved_usd": round(realtime - batch, 2),
        "saved_pct": round(100 * (realtime - batch) / realtime),
    }

# 50,000 classification calls on Haiku ($1 in / $5 out per 1M tokens)
result = batch_savings(
    num_requests=50_000, in_tokens=400, out_tokens=8,
    in_price_per_mtok=1.00, out_price_per_mtok=5.00,
)
for k, v in result.items():
    print(f"{k}: {v}")

realtime_usd: 22.0
batch_usd: 11.0
saved_usd: 11.0
saved_pct: 50

9 · Tech-lead — production batch pipelines tech-lead

A lead owns the batch as a pipeline, not a one-off call. The scale limits set the shape: a single batch holds up to 100,000 requests or 256 MB, processes within 24 hours, and keeps results available for 29 days. Design around those numbers:

Production batch checklist

1. Idempotency via custom_id. Make custom_id a stable key from your own data (a row ID, a content hash) — not a random UUID. Then a resubmit after a crash overwrites cleanly instead of duplicating work, and reconciliation is a simple keyed merge.
2. Chunk large jobs. A 500k-item run won't fit in one batch — split into chunks under the 100k / 256MB limits and track each chunk's batch id. Chunking also bounds blast radius: one bad chunk fails alone.
3. Persist the batch id immediately. The id is your only handle. Write it to a durable store the moment create() returns, before you start polling — if your poller dies, you can resume from the id.
4. Reconcile every item. Walk the full results stream, route succeeded to output, and collect errored / expired custom_ids into a retry batch. Never assume 100% success.
5. Monitor request_counts. Alert on rising errored counts — a spike usually means a bug in how you built the requests, caught early before you burn the whole job.
6. Lean on prompt caching + a cheap model. A shared system prompt across all items caches well; classification-shaped work runs fine on claude-haiku-4-5. Stack those on top of the 50% batch discount for the lowest cost per item.

The mental model: a batch pipeline is an at-least-once job queue you don't have to run. Anthropic owns the workers and the scheduling; your job is to build clean requests with stable ids, persist the handle, and reconcile the outcomes. Get idempotency and reconciliation right and the pipeline survives crashes, partial failures, and reruns without duplicating spend or losing results.

IN, OUT = 5.0, 25.0   # $ per million tokens, Opus 4.8

def realtime_cost(in_tok, out_tok):
    return in_tok/1e6*IN + out_tok/1e6*OUT

def batch_cost(in_tok, out_tok):
    return realtime_cost(in_tok, out_tok) * 0.5   # Batches = 50% off

i, o = 2_000_000, 500_000
print(f"realtime: ${realtime_cost(i,o):.2f}")   # $22.50
print(f"batch   : ${batch_cost(i,o):.2f}")      # $11.25
print(f"saved   : ${realtime_cost(i,o)-batch_cost(i,o):.2f}")  # $11.25

import anthropic
from anthropic.types.message_create_params import MessageCreateParamsNonStreaming
from anthropic.types.messages.batch_create_params import Request

client = anthropic.Anthropic()
texts = ["Great product!", "Awful service.", "It was fine."]

batch = client.messages.batches.create(requests=[
    Request(
        custom_id=f"item-{i}",
        params=MessageCreateParamsNonStreaming(
            model="claude-haiku-4-5", max_tokens=16,
            messages=[{"role": "user",
                       "content": f"Sentiment (positive/negative/neutral), one word: {t}"}],
        ),
    )
    for i, t in enumerate(texts)
])
print(batch.id, batch.processing_status)   # msgbatch_..., "in_progress"

import time

while True:
    b = client.messages.batches.retrieve(batch.id)
    if b.processing_status == "ended":
        break
    time.sleep(30)                       # most batches finish within the hour

out = {}
for r in client.messages.batches.results(batch.id):
    match r.result.type:
        case "succeeded":
            msg = r.result.message
            out[r.custom_id] = next((b.text for b in msg.content if b.type == "text"), "")
        case "errored":
            # invalid_request -> fix & resubmit; server errors -> safe to retry
            out[r.custom_id] = f"ERR:{r.result.error.type}"
        case "expired" | "canceled":
            out[r.custom_id] = r.result.type
print(out)

shared_system = [
    {"type": "text", "text": "You are a contract analyst."},
    {"type": "text", "text": LARGE_CONTRACT_TEXT,
     "cache_control": {"type": "ephemeral"}},   # cache the big shared block
]
questions = ["Termination clause?", "Payment schedule?", "Governing law?"]

batch = client.messages.batches.create(requests=[
    Request(custom_id=f"q-{i}",
        params=MessageCreateParamsNonStreaming(
            model="claude-opus-4-8", max_tokens=512,
            system=shared_system,
            messages=[{"role": "user", "content": q}]))
    for i, q in enumerate(questions)
])

def collect(batch_id):
    ok, retry = {}, []
    for r in client.messages.batches.results(batch_id):
        if r.result.type == "succeeded":
            ok[r.custom_id] = r.result.message
        elif r.result.type == "errored" and r.result.error.type == "invalid_request":
            pass                          # permanent — do NOT blindly retry; log it
        else:                             # errored(server) / expired -> retryable
            retry.append(r.custom_id)
    return ok, retry

# Rebuild requests for the retry ids from your source-of-truth store, keeping ids:
def resubmit(retry_ids, source):
    if not retry_ids:
        return None
    return client.messages.batches.create(requests=[
        Request(custom_id=cid, params=source[cid]) for cid in retry_ids])

def choose_mode(latency_sensitive, volume, long_output):
    if latency_sensitive and long_output:
        return "streaming — token-by-token so the user sees progress, no HTTP timeout"
    if latency_sensitive:
        return "realtime (messages.create) — sub-second single response"
    if volume >= 1000:
        return "batch — 50% cheaper, async, up to 24h; ideal for bulk offline jobs"
    return "realtime — small volume, not worth batch orchestration"

print(choose_mode(True,  1,     True))    # coding assistant  -> streaming
print(choose_mode(True,  1,     False))   # chat turn         -> realtime
print(choose_mode(False, 50000, True))    # nightly enrichment-> batch

Knowledge check check yourself