Batches

Not every API call needs a response in 2 seconds. Batch processing lets you submit up to 100,000 requests at once, get results within 24 hours, and pay 50% less than real-time pricing.

When to batch

Use batches for workloads that are:

• Latency-tolerant: results needed in hours, not seconds
• High-volume: dozens to thousands of items
• Independent: each request doesn't depend on the previous one's result

Examples: document classification, data extraction from 500 PDFs, running eval sets, content moderation at scale, translating a backlog of articles.

Submitting a batch

const batch = await client.messages.batches.create({
  requests: items.map((item, i) => ({
    custom_id: "item-" + i,
    params: {
      model: "claude-sonnet-4-6",
      max_tokens: 256,
      messages: [{
        role: "user",
        content: "Classify this text: " + item.text,
      }],
    },
  })),
});

console.log(batch.id); // msgbatch_abc123

Each request in the batch gets a custom_id you choose — use it to match results back to your inputs.

Polling for results

Batches are async. Poll for status:

let status = await client.messages.batches.retrieve(batch.id);

while (status.processing_status === "in_progress") {
  await new Promise(r => setTimeout(r, 30_000)); // 30s interval
  status = await client.messages.batches.retrieve(batch.id);
}

// Stream results
for await (const result of client.messages.batches.results(batch.id)) {
  if (result.result.type === "succeeded") {
    const content = result.result.message.content[0].text;
    // Process result for result.custom_id
  }
}

Handling failures

Some requests in a batch may fail while others succeed. Always check result.result.type:

• succeeded — normal response
• errored — the request hit an API error
• expired — the batch timed out before processing this request

Build your pipeline to handle partial results. Store successes, retry failures separately.

Cost comparison

Method	Input cost (Opus)	Speed	Best for
Real-time	$5 / MTok	Seconds	User-facing features
Real-time + caching	$0.50 / MTok cached	Seconds	Repeated prompts
Batches	$2.50 / MTok	Hours	Bulk processing
Batches + caching	$0.25 / MTok cached	Hours	Maximum savings

On Opus 4.7, batches also support extended output (up to 300K tokens per response with the output-300k-2026-03-24 beta header).

What's next

You've covered every API capability. The final lesson puts it all together: going to production with logging, monitoring, fallbacks, cost guardrails, and a kill switch.

---