How to Use the Message Batches API for Bulk Processing with the Anthropic Python SDK

The Message Batches API enables asynchronous processing of up to 10,000 Claude requests in a single batch job using the client.messages.batches resource, which exposes methods to create, monitor, cancel, and stream results via JSONL.

The Message Batches API in the anthropic/anthropic-sdk-python repository provides a scalable solution for high-throughput workloads that do not require immediate responses. By submitting requests as a batch rather than individual synchronous calls, you reduce overhead and allow Anthropic to process your workload asynchronously within a 24-hour window.

Core Architecture of the Batches API

In src/anthropic/resources/messages/batches.py, the SDK implements batch operations through the Batches class, which extends SyncAPIResource and AsyncAPIResource. This class serves as the primary interface for all batch-related HTTP operations, internally routing calls through _post, _get, and _delete helpers.

The architecture relies on several key components:

• BatchCreateParams: Defined in src/anthropic/types/messages/batch_create_params.py, this TypedDict validates the payload for the create method, requiring an iterable of Request objects.
• MessageBatch: A Pydantic model in src/anthropic/types/messages/message_batch.py representing the API response containing batch metadata and processing_status.
• JSONLDecoder: Used by the results() method to lazily stream the .jsonl result file without loading the entire dataset into memory.
• Pagination: The list() method returns SyncPage[MessageBatch] or AsyncPage[MessageBatch], supporting cursor-based traversal via after_id, before_id, and limit parameters.

Creating a Message Batch

To initiate bulk processing, construct a list of Request objects and pass them to client.messages.batches.create(). Each request must include a unique custom_id and standard message parameters.

from anthropic import Anthropic
from anthropic.types.messages.batch_create_params import Request

client = Anthropic()

batch = client.messages.batches.create(
    requests=[
        Request(
            custom_id="req-1",
            params={
                "model": "claude-3-5-sonnet-20240620",
                "max_tokens": 1024,
                "messages": [{"role": "user", "content": "Explain quantum tunnelling"}],
            },
        ),
        Request(
            custom_id="req-2",
            params={
                "model": "claude-3-opus-20240229",
                "max_tokens": 512,
                "messages": [{"role": "user", "content": "Generate a haiku about AI"}],
            },
        ),
    ]
)

print(f"Batch ID: {batch.id}")
print(f"Processing status: {batch.processing_status}")

The create method validates the payload against BatchCreateParams in src/anthropic/types/messages/batch_create_params.py and submits the batch via a POST request to the underlying API.

Monitoring Batch Status

After creation, poll the batch status using the retrieve() method until the processing_status indicates completion. According to the implementation in src/anthropic/resources/messages/batches.py, valid terminal states include succeeded, errored, and canceled.

import time

batch_id = batch.id
while True:
    info = client.messages.batches.retrieve(batch_id)
    print(f"Status: {info.processing_status}")
    if info.processing_status in {"succeeded", "errored", "canceled"}:
        break
    time.sleep(10)

Managing Batches

The SDK provides comprehensive lifecycle management through the list(), cancel(), and delete() methods.

Listing Batches

Retrieve paginated batches using cursor-based navigation:

pages = client.messages.batches.list(limit=5)
for batch in pages:
    print(batch.id, batch.processing_status)

The list implementation returns a SyncPage[MessageBatch] object defined in the base pagination handlers, allowing traversal through large result sets efficiently.

Canceling and Deleting

To halt processing of an in-progress batch, invoke the cancel() method. For cleanup after completion or failure, use delete():

# Cancel an active batch

canceled = client.messages.batches.cancel(batch_id)
print(f"Cancelled: {canceled.processing_status}")

# Delete a finished batch

deleted = client.messages.batches.delete(batch_id)
print(f"Deleted batch ID: {deleted.id}")

The delete() method returns a DeletedMessageBatch model from src/anthropic/types/messages/deleted_message_batch.py, confirming the removal of the batch metadata.

Retrieving Batch Results

Once a batch reaches the succeeded state, download the results using the results() method. This returns a JSONLDecoder[MessageBatchIndividualResponse] that streams the JSONL file line-by-line, yielding typed response objects without memory exhaustion.

result_stream = client.messages.batches.results(batch_id)
for result in result_stream:
    print(result.custom_id, result.result)

Each item in the stream corresponds to one request from your original batch, maintaining the custom_id you assigned for correlation. For a complete working example, reference examples/batch_results.py in the SDK repository.

Summary

• The Batches resource in client.messages.batches manages bulk processing through six core methods: create, retrieve, list, cancel, delete, and results.
• Request construction requires the Request TypedDict with a unique custom_id and standard message parameters, validated by BatchCreateParams.
• Status monitoring relies on polling retrieve() until the processing_status reaches a terminal state (succeeded, errored, or canceled).
• Result retrieval uses JSONL streaming via JSONLDecoder to handle large result sets efficiently without loading the entire file into memory.
• All operations are implemented in src/anthropic/resources/messages/batches.py with type definitions in src/anthropic/types/messages/.

Frequently Asked Questions

How many requests can I include in a single Message Batch?

You can include up to 10,000 requests per batch. Each request must be a Request object containing a unique custom_id and the standard parameters for message creation. The batch processes asynchronously and must complete within 24 hours.

What is the difference between canceling and deleting a batch?

Canceling (client.messages.batches.cancel) stops processing for batches in the in_progress state, transitioning them to canceled. Deleting (client.messages.batches.delete) removes the batch metadata and results from Anthropic's servers after processing completes, returning a DeletedMessageBatch confirmation. You cannot delete a batch while it is still processing.

How do I correlate results with my original requests?

When creating a batch, assign a unique custom_id to each Request object. The results() method returns a stream where each MessageBatchIndividualResponse maintains this custom_id, allowing you to map responses back to your original inputs without relying on array order.

Can I access raw HTTP responses or stream the API response?

Yes. The Batches class provides with_raw_response and with_streaming_response accessors that return the underlying httpx.Response or a streaming wrapper, respectively. These are defined in src/anthropic/resources/messages/batches.py and allow access to headers, status codes, or body streaming without buffering.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}