1# Message Batches API — TypeScript
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```typescript
18import Anthropic from "@anthropic-ai/sdk";
19 
20const client = new Anthropic();
21 
22const messageBatch = await client.messages.batches.create({
23  requests: [
24    {
25      custom_id: "request-1",
26      params: {
27        model: "claude-opus-4-7",
28        max_tokens: 16000,
29        messages: [
30          { role: "user", content: "Summarize climate change impacts" },
31        ],
32      },
33    },
34    {
35      custom_id: "request-2",
36      params: {
37        model: "claude-opus-4-7",
38        max_tokens: 16000,
39        messages: [
40          { role: "user", content: "Explain quantum computing basics" },
41        ],
42      },
43    },
44  ],
45});
46 
47console.log(`Batch ID: ${messageBatch.id}`);
48console.log(`Status: ${messageBatch.processing_status}`);
49```
50 
51---
52 
53## Poll for Completion
54 
55```typescript
56let batch;
57while (true) {
58  batch = await client.messages.batches.retrieve(messageBatch.id);
59  if (batch.processing_status === "ended") break;
60  console.log(
61    `Status: ${batch.processing_status}, processing: ${batch.request_counts.processing}`,
62  );
63  await new Promise((resolve) => setTimeout(resolve, 60_000));
64}
65 
66console.log("Batch complete!");
67console.log(`Succeeded: ${batch.request_counts.succeeded}`);
68console.log(`Errored: ${batch.request_counts.errored}`);
69```
70 
71---
72 
73## Retrieve Results
74 
75```typescript
76for await (const result of await client.messages.batches.results(
77  messageBatch.id,
78)) {
79  switch (result.result.type) {
80    case "succeeded":
81      console.log(
82        `[${result.custom_id}] ${result.result.message.content[0].text.slice(0, 100)}`,
83      );
84      break;
85    case "errored":
86      if (result.result.error.type === "invalid_request") {
87        console.log(`[${result.custom_id}] Validation error - fix and retry`);
88      } else {
89        console.log(`[${result.custom_id}] Server error - safe to retry`);
90      }
91      break;
92    case "expired":
93      console.log(`[${result.custom_id}] Expired - resubmit`);
94      break;
95  }
96}
97```
98 
99---
100 
101## Cancel a Batch
102 
103```typescript
104const cancelled = await client.messages.batches.cancel(messageBatch.id);
105console.log(`Status: ${cancelled.processing_status}`); // "canceling"
106```
107