The Message Batches API, Explained

What the Batches API is

Batches is a supporting endpoint layered on top of the Messages API. Instead of sending one request and blocking for one response, you submit many requests as a single batch and retrieve the results later. Each request in the batch is an ordinary Messages API call — same model, same message shape, same parameters — wrapped with a custom_id you assign so you can match answers back to inputs.

• Asynchronous: you submit, then poll, then retrieve — you never hold a connection open waiting.
• Roughly 50% cheaper than standard pricing on all token usage in the batch.
• Up to 100,000 requests or 256 MB per batch.
• Most batches finish within an hour; the maximum is 24 hours.
• Results remain available for 29 days after the batch is created.
• Every Messages API feature is supported — vision, tools, prompt caching, structured outputs, and multi-turn conversations.

How it works: submit, poll, retrieve

The lifecycle has three stages. You create the batch with a list of requests, each carrying a custom_id and a params object identical to what you would pass to a single Messages API call. You then poll the batch's processing_status until it reads "ended". Finally you stream the results, matching each one back to its custom_id and checking whether it succeeded.

{
  "requests": [
    {
      "custom_id": "classify-001",
      "params": {
        "model": "claude-opus-4-8",
        "max_tokens": 64,
        "messages": [
          { "role": "user", "content": "Classify sentiment (one word): The product is excellent!" }
        ]
      }
    },
    {
      "custom_id": "classify-002",
      "params": {
        "model": "claude-opus-4-8",
        "max_tokens": 64,
        "messages": [
          { "role": "user", "content": "Classify sentiment (one word): Terrible service, never again." }
        ]
      }
    }
  ]
}

// Each result carries your custom_id and a result.type:
//   "succeeded" -> read result.message.content
//   "errored"   -> inspect result.error (fix and resubmit, or retry)
//   "canceled"  -> the batch was canceled
//   "expired"   -> not completed within 24h; resubmit

• Create: POST the requests; the response gives you a batch id and an initial processing_status.
• Poll: retrieve the batch by id and check processing_status until it is "ended".
• Retrieve: stream the results; each has a custom_id and a result whose type is succeeded, errored, canceled, or expired.
• You can cancel a batch in flight; its status moves to "canceling".

Sync vs. batch: which to use

The deciding question is whether a human is waiting. If a user is staring at a screen expecting a reply, that is a real-time path and it must use the synchronous Messages API. Batches trades latency for cost and throughput, so it fits work that can complete minutes or hours later without anyone blocked.

The tool-use myth

A common misconception is that batch jobs are text-only and cannot use tools. That is false. Because each request in a batch is a full Messages API call, it can include tool definitions, tool_choice, images, prompt caching, and multi-turn message histories — everything the synchronous API supports.

• Tool use works: include tools and tool_choice in a request's params just as you would synchronously.
• Multi-turn works: a request's messages array can carry a full prior conversation, including assistant and tool_result turns.
• Prompt caching works and pairs especially well with batches — a large shared system prompt across many requests is cached, compounding the savings.
• Vision and structured outputs work too.

The cost math

The batch discount is roughly 50% off standard input and output token pricing, applied to every request in the batch. On a large offline workload the savings are simply half the sync bill — and they stack with prompt caching, since cache reads are already far cheaper than full-price input.