1# Message Batches API — Python
2 
3The Batches API (`POST /v1/messages/batches`) processes Messages API requests asynchronously at 50% of standard prices.
4 
5## Key Facts
6 
7- Up to 100,000 requests or 256 MB per batch
8- Most batches complete within 1 hour; maximum 24 hours
9- Results available for 29 days after creation
10- 50% cost reduction on all token usage
11- All Messages API features supported (vision, tools, caching, etc.)
12 
13---
14 
15## Create a Batch
16 
17```python
18import anthropic
19from anthropic.types.message_create_params import MessageCreateParamsNonStreaming
20from anthropic.types.messages.batch_create_params import Request
21 
22client = anthropic.Anthropic()
23 
24message_batch = client.messages.batches.create(
25    requests=[
26        Request(
27            custom_id="request-1",
28            params=MessageCreateParamsNonStreaming(
29                model="claude-opus-4-8",
30                max_tokens=16000,
31                messages=[{"role": "user", "content": "Summarize climate change impacts"}]
32            )
33        ),
34        Request(
35            custom_id="request-2",
36            params=MessageCreateParamsNonStreaming(
37                model="claude-opus-4-8",
38                max_tokens=16000,
39                messages=[{"role": "user", "content": "Explain quantum computing basics"}]
40            )
41        ),
42    ]
43)
44 
45print(f"Batch ID: {message_batch.id}")
46print(f"Status: {message_batch.processing_status}")
47```
48 
49---
50 
51## Poll for Completion
52 
53```python
54import time
55 
56while True:
57    batch = client.messages.batches.retrieve(message_batch.id)
58    if batch.processing_status == "ended":
59        break
60    print(f"Status: {batch.processing_status}, processing: {batch.request_counts.processing}")
61    time.sleep(60)
62 
63print("Batch complete!")
64print(f"Succeeded: {batch.request_counts.succeeded}")
65print(f"Errored: {batch.request_counts.errored}")
66```
67 
68---
69 
70## Retrieve Results
71 
72> **Note:** Examples below use `match/case` syntax, requiring Python 3.10+. For earlier versions, use `if/elif` chains instead.
73 
74```python
75for result in client.messages.batches.results(message_batch.id):
76    match result.result.type:
77        case "succeeded":
78            msg = result.result.message
79            text = next((b.text for b in msg.content if b.type == "text"), "")
80            print(f"[{result.custom_id}] {text[:100]}")
81        case "errored":
82            if result.result.error.type == "invalid_request":
83                print(f"[{result.custom_id}] Validation error - fix request and retry")
84            else:
85                print(f"[{result.custom_id}] Server error - safe to retry")
86        case "canceled":
87            print(f"[{result.custom_id}] Canceled")
88        case "expired":
89            print(f"[{result.custom_id}] Expired - resubmit")
90```
91 
92---
93 
94## Cancel a Batch
95 
96```python
97cancelled = client.messages.batches.cancel(message_batch.id)
98print(f"Status: {cancelled.processing_status}")  # "canceling"
99```
100 
101---
102 
103## List Batches (auto-pagination)
104 
105Iterating the return value of any `list()` call auto-paginates across all pages — do not index into `.data` if you want the full set:
106 
107```python
108for batch in client.messages.batches.list(limit=20):
109    print(batch.id, batch.processing_status)
110```
111 
112For manual control, use `first_page.has_next_page()` / `first_page.get_next_page()` / `first_page.next_page_info()`; `first_page.data` holds the current page's items and `first_page.last_id` is the cursor.
113 
114---
115 
116## Batch with Prompt Caching
117 
118```python
119shared_system = [
120    {"type": "text", "text": "You are a literary analyst."},
121    {
122        "type": "text",
123        "text": large_document_text,  # Shared across all requests
124        "cache_control": {"type": "ephemeral"}
125    }
126]
127 
128message_batch = client.messages.batches.create(
129    requests=[
130        Request(
131            custom_id=f"analysis-{i}",
132            params=MessageCreateParamsNonStreaming(
133                model="claude-opus-4-8",
134                max_tokens=16000,
135                system=shared_system,
136                messages=[{"role": "user", "content": question}]
137            )
138        )
139        for i, question in enumerate(questions)
140    ]
141)
142```
143 
144---
145 
146## Full End-to-End Example
147 
148```python
149import anthropic
150import time
151from anthropic.types.message_create_params import MessageCreateParamsNonStreaming
152from anthropic.types.messages.batch_create_params import Request
153 
154client = anthropic.Anthropic()
155 
156# 1. Prepare requests
157items_to_classify = [
158    "The product quality is excellent!",
159    "Terrible customer service, never again.",
160    "It's okay, nothing special.",
161]
162 
163requests = [
164    Request(
165        custom_id=f"classify-{i}",
166        params=MessageCreateParamsNonStreaming(
167            model="claude-haiku-4-5",
168            max_tokens=50,
169            messages=[{
170                "role": "user",
171                "content": f"Classify as positive/negative/neutral (one word): {text}"
172            }]
173        )
174    )
175    for i, text in enumerate(items_to_classify)
176]
177 
178# 2. Create batch
179batch = client.messages.batches.create(requests=requests)
180print(f"Created batch: {batch.id}")
181 
182# 3. Wait for completion
183while True:
184    batch = client.messages.batches.retrieve(batch.id)
185    if batch.processing_status == "ended":
186        break
187    time.sleep(10)
188 
189# 4. Collect results
190results = {}
191for result in client.messages.batches.results(batch.id):
192    if result.result.type == "succeeded":
193        msg = result.result.message
194        results[result.custom_id] = next((b.text for b in msg.content if b.type == "text"), "")
195 
196for custom_id, classification in sorted(results.items()):
197    print(f"{custom_id}: {classification}")
198```
199