Implementation:Anthropics Anthropic sdk python MessageBatch

Knowledge Sources	Anthropic SDK Python
Domains	API Types, Batch API
Last Updated	2026-02-15 12:00 GMT

Overview

MessageBatch is a Pydantic model that represents the state of a message batch in the Anthropic Batch API. It tracks the lifecycle of a batch request from creation through processing to completion, including request counts, timestamps, results availability, and processing status.

Description

The MessageBatch class extends BaseModel and encapsulates the full state of a batch processing job. A message batch allows you to submit multiple message requests at once for asynchronous processing.

Key fields include:

• id -- A unique string identifier for the batch.
• processing_status -- One of "in_progress", "canceling", or "ended".
• request_counts -- A MessageBatchRequestCounts object that tallies requests by status (processing, succeeded, errored, canceled, expired). The sum always equals the total batch size.
• results_url -- A URL to a .jsonl file containing results, available only once processing ends. Results are not guaranteed to be in the same order as requests; use custom_id to match.
• type -- Always "message_batch".

Timestamp fields (all datetime objects):

• created_at -- When the batch was created.
• expires_at -- When the batch expires (24 hours after creation).
• ended_at -- When processing ended (optional, set only after completion).
• archived_at -- When the batch was archived and results became unavailable (optional).
• cancel_initiated_at -- When cancellation was initiated (optional).

Usage

Use MessageBatch when working with the Batch API to process large numbers of messages asynchronously. It is returned by batch creation, retrieval, listing, and cancellation endpoints. This is useful for:

• Monitoring batch processing progress via processing_status and request_counts.
• Downloading results once a batch has ended via results_url.
• Managing batch lifecycle including cancellation and archival.

Code Reference

Source Location

• Repository: Anthropic SDK Python
• File: src/anthropic/types/messages/message_batch.py

Signature

class MessageBatch(BaseModel):
    id: str
    archived_at: Optional[datetime] = None
    cancel_initiated_at: Optional[datetime] = None
    created_at: datetime
    ended_at: Optional[datetime] = None
    expires_at: datetime
    processing_status: Literal["in_progress", "canceling", "ended"]
    request_counts: MessageBatchRequestCounts
    results_url: Optional[str] = None
    type: Literal["message_batch"]

Import

from anthropic.types.messages import MessageBatch

I/O Contract

Fields

Field	Type	Required	Description
id	str	Yes	Unique object identifier for the batch.
created_at	datetime	Yes	RFC 3339 timestamp of batch creation.
expires_at	datetime	Yes	RFC 3339 timestamp of batch expiry (24 hours after creation).
processing_status	Literal["in_progress", "canceling", "ended"]	Yes	Current processing status of the batch.
request_counts	MessageBatchRequestCounts	Yes	Tally of requests by status.
type	Literal["message_batch"]	Yes	Object type. Always "message_batch".
archived_at	Optional[datetime]	No	When the batch was archived and results became unavailable.
cancel_initiated_at	Optional[datetime]	No	When cancellation was initiated.
ended_at	Optional[datetime]	No	When processing ended.
results_url	Optional[str]	No	URL to .jsonl results file. Available only after processing ends.

Usage Examples

import anthropic

client = anthropic.Anthropic()

# Create a message batch
batch = client.messages.batches.create(
    requests=[
        {
            "custom_id": "request-1",
            "params": {
                "model": "claude-sonnet-4-20250514",
                "max_tokens": 1024,
                "messages": [{"role": "user", "content": "Hello, Claude"}],
            },
        },
        {
            "custom_id": "request-2",
            "params": {
                "model": "claude-sonnet-4-20250514",
                "max_tokens": 1024,
                "messages": [{"role": "user", "content": "What is 2+2?"}],
            },
        },
    ]
)

print(f"Batch ID: {batch.id}")
print(f"Status: {batch.processing_status}")
print(f"Created: {batch.created_at}")
print(f"Expires: {batch.expires_at}")
print(f"Request counts: {batch.request_counts}")

# Poll for completion
retrieved = client.messages.batches.retrieve(batch.id)
if retrieved.processing_status == "ended":
    print(f"Results URL: {retrieved.results_url}")

Related Pages

• Completion -- Legacy completion response, an alternative API interface.
• MessageCountTokensParams -- Token counting for individual message requests.