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

> Unlock efficient bulk processing with the Anthropic Python SDK Message Batches API. Quickly submit up to 10,000 Claude requests and stream results asynchronously. Learn more now.

- Repository: [Anthropic/anthropic-sdk-python](https://github.com/anthropics/anthropic-sdk-python)
- Tags: how-to-guide
- Published: 2026-02-23

---

**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`](https://github.com/anthropics/anthropic-sdk-python/blob/main/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`](https://github.com/anthropics/anthropic-sdk-python/blob/main/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`](https://github.com/anthropics/anthropic-sdk-python/blob/main/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.

```python
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`](https://github.com/anthropics/anthropic-sdk-python/blob/main/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`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/resources/messages/batches.py), valid terminal states include `succeeded`, `errored`, and `canceled`.

```python
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:

```python
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()`:

```python

# 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`](https://github.com/anthropics/anthropic-sdk-python/blob/main/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.

```python
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`](https://github.com/anthropics/anthropic-sdk-python/blob/main/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`](https://github.com/anthropics/anthropic-sdk-python/blob/main/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`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/resources/messages/batches.py) and allow access to headers, status codes, or body streaming without buffering.