Repository Public
1---2title: Batch processing3url: https://platform.claude.com/docs/en/build-with-claude/batch-processing4description: Process large volumes of Messages requests asynchronously with the Message Batches API, cutting costs by 50% and increasing throughput.5---67Batch processing is a powerful approach for handling large volumes of requests efficiently. Instead of processing requests one at a time with immediate responses, batch processing allows you to submit multiple requests together for asynchronous processing. This pattern is particularly useful when:89* You need to process large volumes of data10* Immediate responses are not required11* You want to optimize for cost efficiency12* You're running large-scale evaluations or analyses1314The Message Batches API is Anthropic's first implementation of this pattern.1516<Note>17 To learn how zero data retention (ZDR) applies to this feature, see [API and data retention](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention).18</Note>1920# Message Batches API2122The Message Batches API is a powerful, cost-effective way to asynchronously process large volumes of [Messages](https://platform.claude.com/docs/en/api/messages/create) requests. This approach is well-suited to tasks that do not require immediate responses, with most batches finishing in less than 1 hour while reducing costs by 50% and increasing throughput.2324You can [explore the API reference directly](https://platform.claude.com/docs/en/api/messages/batches/create), in addition to this guide.2526## How the Message Batches API works2728When you send a request to the Message Batches API:29301. The system creates a new Message Batch with the provided Messages requests.312. The batch is then processed asynchronously, with each request handled independently.323. You can poll for the status of the batch and retrieve results when processing has ended for all requests.3334This is especially useful for bulk operations that don't require immediate results, such as:3536* Large-scale evaluations: Process thousands of test cases efficiently.37* Content moderation: Analyze large volumes of user-generated content asynchronously.38* Data analysis: Generate insights or summaries for large datasets.39* Bulk content generation: Create large amounts of text for various purposes (for example, product descriptions, article summaries).4041### Batch limitations4243* A Message Batch is limited to either 100,000 Message requests or 256 MB in size, whichever is reached first.44* The system processes each batch as fast as possible, with most batches completing within 1 hour. You can access batch results when all messages have completed or after 24 hours, whichever comes first. Batches expire if processing does not complete within 24 hours.45* Batch results are available for 29 days after creation. After that, you may still view the Batch, but its results will no longer be available for download.46* Batches are scoped to a [Workspace](https://platform.claude.com/settings/workspaces). You may view all batches (and their results) that were created within the Workspace your request runs in.47* Rate limits apply to both Batches API HTTP requests and the number of requests within a batch waiting to be processed. See [Message Batches API rate limits](https://platform.claude.com/docs/en/api/rate-limits#message-batches-api). Additionally, processing may be slowed down based on current demand and your request volume. In that case, you may see more requests expiring after 24 hours.48* Because of high throughput and concurrent processing, batches may go slightly over your Workspace's configured [spend limit](https://platform.claude.com/settings/billing).49* Each batched request must have `max_tokens` of at least `1`. `max_tokens: 0` ([cache pre-warming](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#pre-warming-the-cache)) is not supported inside a batch, because an ephemeral cache entry written during batch processing would likely expire before the follow-up request runs.5051### Supported models5253All [active models](https://platform.claude.com/docs/en/models/overview) support the Message Batches API.5455### What can be batched5657Almost any request you can make to the Messages API can be included in a batch. This includes:5859* Vision60* Tool use, including all [server tools](https://platform.claude.com/docs/en/agents-and-tools/tool-use/server-tools) (web search, web fetch, code execution, MCP connectors, advisor, and tool search)61* System messages62* Multi-turn conversations63* Extended thinking64* Most beta features6566Because each request in the batch is processed independently, you can mix different types of requests within a single batch.6768A small number of Messages API parameters are **not** supported in batch requests. Including any of these returns a validation error:6970| Parameter | Why |71| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |72| `stream: true` | Batch results come back as a single file, not a stream. |73| `speed` ([Fast mode](https://platform.claude.com/docs/en/build-with-claude/fast-mode)) | Fast mode tunes synchronous latency, which doesn't apply to asynchronous batch processing. |74| `max_tokens: 0` | See [Batch limitations](https://platform.claude.com/docs/en/build-with-claude/batch-processing#batch-limitations). |7576<Tip>77 Because batches can take longer than 5 minutes to process, consider using the [1-hour cache duration](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#1-hour-cache-duration) with prompt caching for better cache hit rates when processing batches with shared context.78</Tip>7980## Pricing8182The Batches API offers significant cost savings. All usage is charged at 50% of the standard API prices.8384| Model | Batch input | Batch output |85| :------------------------------------------------------------------------------------------------------------------------------------ | :----------- | :------------ |86| Claude Fable 5.1 | $5 / MTok | $25 / MTok |87| Claude Mythos 5.1 ([limited availability](https://anthropic.com/glasswing)) | $5 / MTok | $25 / MTok |88| Claude Fable 5 | $5 / MTok | $25 / MTok |89| Claude Mythos 5 ([limited availability](https://anthropic.com/glasswing)) | $5 / MTok | $25 / MTok |90| Claude Opus 5 | $2.50 / MTok | $12.50 / MTok |91| Claude Opus 4.8 | $2.50 / MTok | $12.50 / MTok |92| Claude Opus 4.7 | $2.50 / MTok | $12.50 / MTok |93| Claude Opus 4.6 | $2.50 / MTok | $12.50 / MTok |94| Claude Opus 4.5 | $2.50 / MTok | $12.50 / MTok |95| Claude Opus 4.1 ([retired, except on Bedrock and Google Cloud](https://platform.claude.com/docs/en/about-claude/model-deprecations)) | $7.50 / MTok | $37.50 / MTok |96| Claude Opus 4 ([retired, except on Google Cloud](https://platform.claude.com/docs/en/about-claude/model-deprecations)) | $7.50 / MTok | $37.50 / MTok |97| Claude Sonnet 5 | $1 / MTok | $5 / MTok |98| Claude Sonnet 4.6 | $1.50 / MTok | $7.50 / MTok |99| Claude Sonnet 4.5 | $1.50 / MTok | $7.50 / MTok |100| Claude Sonnet 4 ([retired, except on Bedrock and Google Cloud](https://platform.claude.com/docs/en/about-claude/model-deprecations)) | $1.50 / MTok | $7.50 / MTok |101| Claude Haiku 4.5 | $0.50 / MTok | $2.50 / MTok |102| Claude Haiku 3.5 ([retired, except on Bedrock and Google Cloud](https://platform.claude.com/docs/en/about-claude/model-deprecations)) | $0.40 / MTok | $2 / MTok |103104## How to use the Message Batches API105106### Prepare and create your batch107108A Message Batch is composed of a list of requests to create a Message. The shape of an individual request comprises:109110* A unique `custom_id` for identifying the Messages request. Must be 1 to 64 characters and contain only alphanumeric characters, hyphens, and underscores (matching `^[a-zA-Z0-9_-]{1,64}$`).111* A `params` object with the standard [Messages API](https://platform.claude.com/docs/en/api/messages/create) parameters112113You can [create a batch](https://platform.claude.com/docs/en/api/messages/batches/create) by passing this list into the `requests` parameter:114115<CodeGroup>116 ```bash cURL117 curl https://api.anthropic.com/v1/messages/batches \118 --header "x-api-key: $ANTHROPIC_API_KEY" \119 --header "anthropic-version: 2023-06-01" \120 --header "content-type: application/json" \121 --data \122 '{123 "requests": [124 {125 "custom_id": "my-first-request",126 "params": {127 "model": "claude-opus-5",128 "max_tokens": 1024,129 "messages": [130 {"role": "user", "content": "Hello, world"}131 ]132 }133 },134 {135 "custom_id": "my-second-request",136 "params": {137 "model": "claude-opus-5",138 "max_tokens": 1024,139 "messages": [140 {"role": "user", "content": "Hi again, friend"}141 ]142 }143 }144 ]145 }'146 ```147148 ```bash CLI149 ant messages:batches create <<'YAML'150 requests:151 - custom_id: my-first-request152 params:153 model: claude-opus-5154 max_tokens: 1024155 messages:156 - role: user157 content: Hello, world158 - custom_id: my-second-request159 params:160 model: claude-opus-5161 max_tokens: 1024162 messages:163 - role: user164 content: Hi again, friend165 YAML166 ```167168 ```python Python169 from anthropic.types.message_create_params import MessageCreateParamsNonStreaming170 from anthropic.types.messages.batch_create_params import Request171172 client = anthropic.Anthropic()173174 message_batch = client.messages.batches.create(175 requests=[176 Request(177 custom_id="my-first-request",178 params=MessageCreateParamsNonStreaming(179 model="claude-opus-5",180 max_tokens=1024,181 messages=[182 {183 "role": "user",184 "content": "Hello, world",185 }186 ],187 ),188 ),189 Request(190 custom_id="my-second-request",191 params=MessageCreateParamsNonStreaming(192 model="claude-opus-5",193 max_tokens=1024,194 messages=[195 {196 "role": "user",197 "content": "Hi again, friend",198 }199 ],200 ),201 ),202 ]203 )204205 print(message_batch)206 ```207208 ```typescript TypeScript209 const client = new Anthropic();210211 const messageBatch = await client.messages.batches.create({212 requests: [213 {214 custom_id: "my-first-request",215 params: {216 model: "claude-opus-5",217 max_tokens: 1024,218 messages: [{ role: "user", content: "Hello, world" }]219 }220 },221 {222 custom_id: "my-second-request",223 params: {224 model: "claude-opus-5",225 max_tokens: 1024,226 messages: [{ role: "user", content: "Hi again, friend" }]227 }228 }229 ]230 });231232 console.log(messageBatch);233 ```234235 ```csharp C#236 using Anthropic;237 using Anthropic.Models.Messages;238 using Anthropic.Models.Messages.Batches;239240 AnthropicClient client = new();241242 var batch = await client.Messages.Batches.Create(new BatchCreateParams243 {244 Requests =245 [246 new()247 {248 CustomID = "my-first-request",249 Params = new()250 {251 Model = Model.ClaudeOpus5,252 MaxTokens = 1024,253 Messages =254 [255 new() { Role = Role.User, Content = "Hello, world" }256 ]257 }258 },259 new()260 {261 CustomID = "my-second-request",262 Params = new()263 {264 Model = Model.ClaudeOpus5,265 MaxTokens = 1024,266 Messages =267 [268 new() { Role = Role.User, Content = "Hi again, friend" }269 ]270 }271 }272 ]273 });274275 Console.WriteLine(batch);276 ```277278 ```go Go279 client := anthropic.NewClient()280281 batch, _ := client.Messages.Batches.New(context.Background(),282 anthropic.MessageBatchNewParams{283 Requests: []anthropic.MessageBatchNewParamsRequest{284 {285 CustomID: "my-first-request",286 Params: anthropic.MessageBatchNewParamsRequestParams{287 Model: anthropic.ModelClaudeOpus5,288 MaxTokens: 1024,289 Messages: []anthropic.MessageParam{290 anthropic.NewUserMessage(291 anthropic.NewTextBlock("Hello, world"),292 ),293 },294 },295 },296 {297 CustomID: "my-second-request",298 Params: anthropic.MessageBatchNewParamsRequestParams{299 Model: anthropic.ModelClaudeOpus5,300 MaxTokens: 1024,301 Messages: []anthropic.MessageParam{302 anthropic.NewUserMessage(303 anthropic.NewTextBlock("Hi again, friend"),304 ),305 },306 },307 },308 },309 })310311 fmt.Println(batch.ID)312 ```313314 ```java Java315 AnthropicClient client = AnthropicOkHttpClient.fromEnv();316317 BatchCreateParams params = BatchCreateParams.builder()318 .addRequest(319 BatchCreateParams.Request.builder()320 .customId("my-first-request")321 .params(322 BatchCreateParams.Request.Params.builder()323 .model(Model.CLAUDE_OPUS_5)324 .maxTokens(1024)325 .addUserMessage("Hello, world")326 .build()327 )328 .build()329 )330 .addRequest(331 BatchCreateParams.Request.builder()332 .customId("my-second-request")333 .params(334 BatchCreateParams.Request.Params.builder()335 .model(Model.CLAUDE_OPUS_5)336 .maxTokens(1024)337 .addUserMessage("Hi again, friend")338 .build()339 )340 .build()341 )342 .build();343344 MessageBatch messageBatch = client.messages().batches().create(params);345346 System.out.println(messageBatch);347 ```348349 ```php PHP350 $client = new Client();351352 $batch = $client->messages->batches->create(353 requests: [354 [355 'custom_id' => 'my-first-request',356 'params' => [357 'model' => 'claude-opus-5',358 'max_tokens' => 1024,359 'messages' => [360 ['role' => 'user', 'content' => 'Hello, world']361 ]362 ]363 ],364 [365 'custom_id' => 'my-second-request',366 'params' => [367 'model' => 'claude-opus-5',368 'max_tokens' => 1024,369 'messages' => [370 ['role' => 'user', 'content' => 'Hi again, friend']371 ]372 ]373 ]374 ],375 );376377 echo $batch->id;378 ```379380 ```ruby Ruby381 client = Anthropic::Client.new382383 batch = client.messages.batches.create(384 requests: [385 {386 custom_id: "my-first-request",387 params: {388 model: "claude-opus-5",389 max_tokens: 1024,390 messages: [391 { role: "user", content: "Hello, world" }392 ]393 }394 },395 {396 custom_id: "my-second-request",397 params: {398 model: "claude-opus-5",399 max_tokens: 1024,400 messages: [401 { role: "user", content: "Hi again, friend" }402 ]403 }404 }405 ]406 )407408 puts batch409 ```410</CodeGroup>411412In this example, two separate requests are batched together for asynchronous processing. Each request has a unique `custom_id` and contains the standard parameters you'd use for a Messages API call.413414<Tip>415 **Test your batch requests with the Messages API**416417 Validation of the `params` object for each message request is performed asynchronously, and validation errors are returned when processing of the entire batch has ended. You can ensure that you are building your input correctly by verifying your request shape with the [Messages API](https://platform.claude.com/docs/en/api/messages/create) first.418</Tip>419420When a batch is first created, the response has a processing status of `in_progress`.421422```json Output423{424 "id": "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d",425 "type": "message_batch",426 "processing_status": "in_progress",427 "request_counts": {428 "processing": 2,429 "succeeded": 0,430 "errored": 0,431 "canceled": 0,432 "expired": 0433 },434 "ended_at": null,435 "created_at": "2024-09-24T18:37:24.100435Z",436 "expires_at": "2024-09-25T18:37:24.100435Z",437 "cancel_initiated_at": null,438 "results_url": null439}440```441442### Tracking your batch443444The Message Batch's `processing_status` field indicates the stage of processing the batch is in. It starts as `in_progress`, then updates to `ended` once all the requests in the batch have finished processing, and results are ready. You can monitor the state of your batch by visiting the [Console](https://platform.claude.com/settings/workspaces/default/batches), or using the [retrieval endpoint](https://platform.claude.com/docs/en/api/retrieving-message-batches).445446#### Polling for Message Batch completion447448To poll a Message Batch, you'll need its `id`, which is provided in the response when creating a batch or by listing batches. You can implement a polling loop that checks the batch status periodically until processing has ended:449450<CodeGroup>451 ```bash cURL452 #!/bin/sh453 # ...454 # Check the status; repeat until processing_status is "ended"455 curl -s "https://api.anthropic.com/v1/messages/batches/$MESSAGE_BATCH_ID" \456 --header "x-api-key: $ANTHROPIC_API_KEY" \457 --header "anthropic-version: 2023-06-01" \458 | jq -r '.processing_status'459 ```460461 ```bash CLI462 #!/bin/bash463 # ...464 # Check the status; repeat until processing_status is "ended"465 ant messages:batches retrieve \466 --message-batch-id "$MESSAGE_BATCH_ID" \467 --transform processing_status --raw-output468 ```469470 ```python Python471 import time472473 client = anthropic.Anthropic()474475 MESSAGE_BATCH_ID = "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d"476477 message_batch = None478 while True:479 message_batch = client.messages.batches.retrieve(MESSAGE_BATCH_ID)480 if message_batch.processing_status == "ended":481 break482483 print(f"Batch {MESSAGE_BATCH_ID} is still processing...")484 time.sleep(60)485 print(message_batch)486 ```487488 ```typescript TypeScript489 const client = new Anthropic();490491 const messageBatchId = "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d";492493 let messageBatch;494 while (true) {495 messageBatch = await client.messages.batches.retrieve(messageBatchId);496 if (messageBatch.processing_status === "ended") {497 break;498 }499500 console.log(`Batch ${messageBatchId} is still processing... waiting`);501 await new Promise((resolve) => setTimeout(resolve, 60_000));502 }503 console.log(messageBatch);504 ```505506 ```csharp C#507 AnthropicClient client = new();508 string messageBatchId = Environment.GetEnvironmentVariable("MESSAGE_BATCH_ID");509510 MessageBatch messageBatch = null;511 while (true)512 {513 messageBatch = await client.Messages.Batches.Retrieve(messageBatchId);514 if (messageBatch.ProcessingStatus == "ended")515 {516 break;517 }518519 Console.WriteLine($"Batch {messageBatchId} is still processing...");520 await Task.Delay(60000);521 }522 Console.WriteLine(messageBatch);523 ```524525 ```go Go526 client := anthropic.NewClient()527 messageBatchID := os.Getenv("MESSAGE_BATCH_ID")528529 var messageBatch *anthropic.MessageBatch530 for {531 var err error532 messageBatch, err = client.Messages.Batches.Get(context.TODO(), messageBatchID, anthropic.MessageBatchGetParams{})533 if err != nil {534 log.Fatal(err)535 }536 if messageBatch.ProcessingStatus == "ended" {537 break538 }539540 fmt.Printf("Batch %s is still processing...\n", messageBatchID)541 time.Sleep(60 * time.Second)542 }543 fmt.Println(messageBatch)544 ```545546 ```java Java547 import com.anthropic.models.messages.batches.MessageBatch;548 // ...549 AnthropicClient client = AnthropicOkHttpClient.fromEnv();550 String messageBatchId = "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d";551552 MessageBatch messageBatch = null;553 while (true) {554 messageBatch = client.messages().batches().retrieve(messageBatchId);555 if (messageBatch.processingStatus().equals(MessageBatch.ProcessingStatus.ENDED)) {556 break;557 }558559 System.out.println("Batch " + messageBatchId + " is still processing...");560 Thread.sleep(60000);561 }562 System.out.println(messageBatch);563 ```564565 ```php PHP566 $client = new Client();567 $messageBatchId = getenv("MESSAGE_BATCH_ID");568569 $messageBatch = null;570 while (true) {571 $messageBatch = $client->messages->batches->retrieve(572 messageBatchID: $messageBatchId,573 );574 if ($messageBatch->processingStatus === "ended") {575 break;576 }577578 echo "Batch {$messageBatchId} is still processing...\n";579 sleep(60);580 }581 echo json_encode($messageBatch, JSON_PRETTY_PRINT);582 ```583584 ```ruby Ruby585 client = Anthropic::Client.new586587 message_batch_id = ENV["MESSAGE_BATCH_ID"]588 message_batch = nil589 loop do590 message_batch = client.messages.batches.retrieve(message_batch_id)591 break if message_batch.processing_status == :ended592593 puts "Batch #{message_batch_id} is still processing..."594 sleep 60595 end596 puts message_batch597 ```598</CodeGroup>599600### Listing all Message Batches601602You can list all Message Batches in your Workspace using the [list endpoint](https://platform.claude.com/docs/en/api/listing-message-batches). The API supports pagination, automatically fetching additional pages as needed:603604<CodeGroup>605 ```bash cURL606 #!/bin/sh607 # Fetches one page. While the response's has_more is true, pass its608 # last_id as after_id to fetch the next page. (The SDKs and the CLI609 # perform automatic pagination.)610 curl -s "https://api.anthropic.com/v1/messages/batches?limit=20" \611 --header "x-api-key: $ANTHROPIC_API_KEY" \612 --header "anthropic-version: 2023-06-01"613 ```614615 ```bash CLI616 # Automatically fetches more pages as needed617 ant messages:batches list --limit 20618 ```619620 ```python Python621 client = anthropic.Anthropic()622623 # Automatically fetches more pages as needed.624 for message_batch in client.messages.batches.list(limit=20):625 print(message_batch)626 ```627628 ```typescript TypeScript629 const client = new Anthropic();630631 // Automatically fetches more pages as needed.632 for await (const messageBatch of client.messages.batches.list({633 limit: 20634 })) {635 console.log(messageBatch);636 }637 ```638639 ```csharp C#640 AnthropicClient client = new();641642 var parameters = new BatchListParams643 {644 Limit = 20645 };646647 // Automatically fetches more pages as needed648 var page = await client.Messages.Batches.List(parameters);649 await foreach (var messageBatch in page.Paginate())650 {651 Console.WriteLine(messageBatch);652 }653 ```654655 ```go Go656 client := anthropic.NewClient()657658 // Automatically fetches more pages as needed659 iter := client.Messages.Batches.ListAutoPaging(context.TODO(), anthropic.MessageBatchListParams{660 Limit: anthropic.Int(20),661 })662663 for iter.Next() {664 messageBatch := iter.Current()665 fmt.Println(messageBatch)666 }667668 if err := iter.Err(); err != nil {669 log.Fatal(err)670 }671 ```672673 ```java Java674 AnthropicClient client = AnthropicOkHttpClient.fromEnv();675676 // Automatically fetches more pages as needed677 for (MessageBatch messageBatch : client678 .messages()679 .batches()680 .list(BatchListParams.builder().limit(20).build())681 .autoPager()) {682 System.out.println(messageBatch);683 }684 ```685686 ```php PHP687 $client = new Client();688689 // Automatically fetches more pages as needed690 foreach ($client->messages->batches->list(limit: 20)->pagingEachItem() as $messageBatch) {691 echo $messageBatch->id . "\n";692 }693 ```694695 ```ruby Ruby696 client = Anthropic::Client.new697698 # Automatically fetches more pages as needed699 client.messages.batches.list(limit: 20).auto_paging_each do |message_batch|700 puts message_batch701 end702 ```703</CodeGroup>704705### Retrieving batch results706707Once batch processing has ended, each Messages request in the batch has a result. There are four result types:708709| Result type | Description |710| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |711| `succeeded` | Request was successful. Includes the message result. |712| `errored` | Request encountered an error and a message was not created. Possible errors include invalid requests and internal server errors. You will not be billed for these requests. |713| `canceled` | User canceled the batch before this request could be sent to the model. You will not be billed for these requests. |714| `expired` | Batch reached its 24-hour expiration before this request could be sent to the model. You will not be billed for these requests. |715716The batch's `request_counts` shows an overview of your results, indicating how many requests reached each of these four states.717718Results of the batch are available for download at the `results_url` property on the Message Batch, and if the organization permission allows, in the Console. Because of the potentially large size of the results, it's recommended to [stream results](https://platform.claude.com/docs/en/api/messages/batches/results) back rather than download them all at once.719720<CodeGroup>721 ```bash cURL722 #!/bin/sh723 # Fetch the batch's results_url, then stream the .jsonl results it724 # points to. For per-result handling (retries, validation errors),725 # use the SDK examples in the other tabs.726 RESULTS_URL=$(curl -s "https://api.anthropic.com/v1/messages/batches/msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d" \727 --header "anthropic-version: 2023-06-01" \728 --header "x-api-key: $ANTHROPIC_API_KEY" \729 | jq -r '.results_url')730731 curl -s "$RESULTS_URL" \732 --header "anthropic-version: 2023-06-01" \733 --header "x-api-key: $ANTHROPIC_API_KEY" \734 | jq -r '"\(.result.type): \(.custom_id)"'735 ```736737 ```bash CLI738 # Prints one line per result, e.g. `{"custom_id":"test-1","type":"succeeded",…}`.739 # For per-result handling (retries, validation errors), use the SDK740 # examples in the other tabs.741 ant messages:batches results \742 --message-batch-id msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d \743 --transform '{custom_id,"type":result.type,"error":result.error.error.type}' \744 --format jsonl745 ```746747 ```python Python748 client = anthropic.Anthropic()749750 # Stream results file in memory-efficient chunks, processing one at a time751 for result in client.messages.batches.results(752 "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d",753 ):754 outcome = result.result755 match outcome.type:756 case "succeeded":757 print(f"Success! {result.custom_id}")758 case "errored":759 if outcome.error.error.type == "invalid_request_error":760 # Request body must be fixed before re-sending request761 print(f"Validation error {result.custom_id}")762 else:763 # Request can be retried directly764 print(f"Server error {result.custom_id}")765 case "expired":766 print(f"Request expired {result.custom_id}")767 ```768769 ```typescript TypeScript770 const client = new Anthropic();771772 // Stream results file in memory-efficient chunks, processing one at a time773 for await (const result of await client.messages.batches.results(774 "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d"775 )) {776 switch (result.result.type) {777 case "succeeded":778 console.log(`Success! ${result.custom_id}`);779 break;780 case "errored":781 if (result.result.error.type === "invalid_request_error") {782 // Request body must be fixed before re-sending request783 console.log(`Validation error: ${result.custom_id}`);784 } else {785 // Request can be retried directly786 console.log(`Server error: ${result.custom_id}`);787 }788 break;789 case "expired":790 console.log(`Request expired: ${result.custom_id}`);791 break;792 }793 }794 ```795796 ```csharp C#797 AnthropicClient client = new();798799 await foreach (var result in client.Messages.Batches.ResultsStreaming("msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d"))800 {801 switch (result.Result.Type)802 {803 case "succeeded":804 Console.WriteLine($"Success! {result.CustomID}");805 break;806 case "errored":807 if (result.Result.Error?.Type == "invalid_request")808 {809 Console.WriteLine($"Validation error: {result.CustomID}");810 }811 else812 {813 Console.WriteLine($"Server error: {result.CustomID}");814 }815 break;816 case "expired":817 Console.WriteLine($"Request expired: {result.CustomID}");818 break;819 }820 }821 ```822823 ```go Go824 client := anthropic.NewClient()825826 stream := client.Messages.Batches.ResultsStreaming(context.TODO(), "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d", anthropic.MessageBatchResultsParams{})827828 for stream.Next() {829 result := stream.Current()830831 switch variant := result.Result.AsAny().(type) {832 case anthropic.MessageBatchSucceededResult:833 fmt.Printf("Success! %s\n", result.CustomID)834 case anthropic.MessageBatchErroredResult:835 fmt.Printf("Error: %s - %s\n", result.CustomID, variant.Error.Error.Message)836 case anthropic.MessageBatchExpiredResult:837 fmt.Printf("Request expired: %s\n", result.CustomID)838 }839 }840841 if err := stream.Err(); err != nil {842 log.Fatal(err)843 }844 ```845846 ```java Java847 import com.anthropic.core.http.StreamResponse;848 import com.anthropic.models.messages.batches.BatchResultsParams;849 import com.anthropic.models.messages.batches.MessageBatchIndividualResponse;850 // ...851 AnthropicClient client = AnthropicOkHttpClient.fromEnv();852853 // Stream results file in memory-efficient chunks, processing one at a time854 try (855 StreamResponse<MessageBatchIndividualResponse> streamResponse = client856 .messages()857 .batches()858 .resultsStreaming(859 BatchResultsParams.builder()860 .messageBatchId("msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d")861 .build()862 )863 ) {864 streamResponse865 .stream()866 .forEach(result -> {867 switch (result.result().type().value()) {868 case SUCCEEDED -> System.out.println("Success! " + result.customId());869 case ERRORED -> {870 if (result.result().asErrored().error().error().isInvalidRequestError()) {871 // Request body must be fixed before re-sending request872 System.out.println("Validation error: " + result.customId());873 } else {874 // Request can be retried directly875 System.out.println("Server error: " + result.customId());876 }877 }878 case EXPIRED -> System.out.println("Request expired: " + result.customId());879 }880 });881 }882 ```883884 ```php PHP885 use Anthropic\Messages\Batches\MessageBatchErroredResult;886 use Anthropic\Messages\Batches\MessageBatchExpiredResult;887 use Anthropic\Messages\Batches\MessageBatchSucceededResult;888889 $client = new Client();890891 foreach ($client->messages->batches->resultsStream(messageBatchID: 'msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d') as $result) {892 switch (true) {893 case $result->result instanceof MessageBatchSucceededResult:894 echo "Success! {$result->customID}\n";895 break;896 case $result->result instanceof MessageBatchErroredResult:897 if ($result->result->error->error->type === "invalid_request_error") {898 echo "Validation error: {$result->customID}\n";899 } else {900 echo "Server error: {$result->customID}\n";901 }902 break;903 case $result->result instanceof MessageBatchExpiredResult:904 echo "Request expired: {$result->customID}\n";905 break;906 }907 }908 ```909910 ```ruby Ruby911 client = Anthropic::Client.new912913 client.messages.batches.results_streaming("msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d").each do |result|914 outcome = result.result915 case outcome916 when Anthropic::Models::Messages::MessageBatchSucceededResult917 puts "Success! #{result.custom_id}"918 when Anthropic::Models::Messages::MessageBatchErroredResult919 if outcome.error.type == :invalid_request920 puts "Validation error: #{result.custom_id}"921 else922 puts "Server error: #{result.custom_id}"923 end924 when Anthropic::Models::Messages::MessageBatchExpiredResult925 puts "Request expired: #{result.custom_id}"926 end927 end928 ```929</CodeGroup>930931The results are in `.jsonl` format, where each line is a valid JSON object representing the result of a single request in the Message Batch. For each streamed result, you can do something different depending on its `custom_id` and result type. Here is an example set of results:932933```jsonl .jsonl file934{"custom_id":"my-second-request","result":{"type":"succeeded","message":{"id":"msg_014VwiXbi91y3JMjcpyGBHX5","type":"message","role":"assistant","model":"claude-opus-5","content":[{"type":"text","text":"Hello again! It's nice to see you. How can I assist you today? Is there anything specific you'd like to chat about or any questions you have?"}],"stop_reason":"end_turn","stop_sequence":null,"usage":{"input_tokens":11,"output_tokens":36}}}}935{"custom_id":"my-first-request","result":{"type":"succeeded","message":{"id":"msg_01FqfsLoHwgeFbguDgpz48m7","type":"message","role":"assistant","model":"claude-opus-5","content":[{"type":"text","text":"Hello! How can I assist you today? Feel free to ask me any questions or let me know if there's anything you'd like to chat about."}],"stop_reason":"end_turn","stop_sequence":null,"usage":{"input_tokens":10,"output_tokens":34}}}}936```937938If your result has an error, its `result.error` will be set to the standard [error shape](https://platform.claude.com/docs/en/api/errors#error-shapes).939940<Tip>941 **Batch results may not match input order**942943 Batch results can be returned in any order, and may not match the ordering of requests when the batch was created. In the preceding example, the result for the second batch request is returned before the first. To correctly match results with their corresponding requests, always use the `custom_id` field.944</Tip>945946### Canceling a Message Batch947948You can cancel a Message Batch that is currently processing using the [cancel endpoint](https://platform.claude.com/docs/en/api/canceling-message-batches). Immediately after cancellation, a batch's `processing_status` will be `canceling`. You can use the same polling technique described earlier to wait until cancellation is finalized. Canceled batches end up with a status of `ended` and may contain partial results for requests that were processed before cancellation.949950<CodeGroup>951 ```bash cURL952 #!/bin/sh953 # ...954 curl --request POST https://api.anthropic.com/v1/messages/batches/$MESSAGE_BATCH_ID/cancel \955 --header "x-api-key: $ANTHROPIC_API_KEY" \956 --header "anthropic-version: 2023-06-01"957 ```958959 ```bash CLI960 #!/bin/bash961 # ...962 ant messages:batches cancel --message-batch-id "$MESSAGE_BATCH_ID"963 ```964965 ```python Python966 client = anthropic.Anthropic()967968 MESSAGE_BATCH_ID = "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d"969970 message_batch = client.messages.batches.cancel(971 MESSAGE_BATCH_ID,972 )973 print(message_batch)974 ```975976 ```typescript TypeScript977 const client = new Anthropic();978979 const messageBatch = await client.messages.batches.cancel(MESSAGE_BATCH_ID);980 console.log(messageBatch);981 ```982983 ```csharp C#984 AnthropicClient client = new();985 string messageBatchId = Environment.GetEnvironmentVariable("MESSAGE_BATCH_ID");986987 var messageBatch = await client.Messages.Batches.Cancel(messageBatchId);988 Console.WriteLine(messageBatch);989 ```990991 ```go Go992 client := anthropic.NewClient()993 messageBatchID := os.Getenv("MESSAGE_BATCH_ID")994995 messageBatch, err := client.Messages.Batches.Cancel(context.TODO(), messageBatchID, anthropic.MessageBatchCancelParams{})996 if err != nil {997 log.Fatal(err)998 }999 fmt.Println(messageBatch)1000 ```10011002 ```java Java1003 import com.anthropic.models.messages.batches.*;1004 // ...1005 AnthropicClient client = AnthropicOkHttpClient.fromEnv();10061007 MessageBatch messageBatch = client1008 .messages()1009 .batches()1010 .cancel("msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d");1011 System.out.println(messageBatch);1012 ```10131014 ```php PHP1015 $client = new Client();10161017 $messageBatch = $client->messages->batches->cancel(1018 messageBatchID: 'msgbatch_example_id',1019 );1020 echo $messageBatch;1021 ```10221023 ```ruby Ruby1024 client = Anthropic::Client.new10251026 message_batch_id = ENV.fetch("MESSAGE_BATCH_ID")1027 message_batch = client.messages.batches.cancel(message_batch_id)1028 puts message_batch1029 ```1030</CodeGroup>10311032The response shows the batch in a `canceling` state:10331034```json Output1035{1036 "id": "msgbatch_013Zva2CMHLNnXjNJJKqJ2EF",1037 "type": "message_batch",1038 "processing_status": "canceling",1039 "request_counts": {1040 "processing": 2,1041 "succeeded": 0,1042 "errored": 0,1043 "canceled": 0,1044 "expired": 01045 },1046 "ended_at": null,1047 "created_at": "2024-09-24T18:37:24.100435Z",1048 "expires_at": "2024-09-25T18:37:24.100435Z",1049 "cancel_initiated_at": "2024-09-24T18:39:03.114875Z",1050 "results_url": null1051}1052```10531054### Using prompt caching with Message Batches10551056The Message Batches API supports prompt caching, allowing you to potentially reduce costs and processing time for batch requests. The pricing discounts from prompt caching and Message Batches can stack, providing even greater cost savings when both features are used together. However, because batch requests are processed asynchronously and concurrently, cache hits are provided on a best-effort basis. Users typically experience cache hit rates ranging from 30% to 98%, depending on their traffic patterns.10571058To maximize the likelihood of cache hits in your batch requests:105910601. Include identical `cache_control` blocks in every Message request within your batch.10612. Maintain a steady stream of requests to prevent cache entries from expiring after their 5-minute lifetime.10623. Structure your requests to share as much cached content as possible.10631064Example of implementing prompt caching in a batch:10651066<CodeGroup>1067 ```bash cURL1068 curl https://api.anthropic.com/v1/messages/batches \1069 --header "x-api-key: $ANTHROPIC_API_KEY" \1070 --header "anthropic-version: 2023-06-01" \1071 --header "content-type: application/json" \1072 --data \1073 '{1074 "requests": [1075 {1076 "custom_id": "my-first-request",1077 "params": {1078 "model": "claude-opus-5",1079 "max_tokens": 1024,1080 "system": [1081 {1082 "type": "text",1083 "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"1084 },1085 {1086 "type": "text",1087 "text": "<the entire contents of Pride and Prejudice>",1088 "cache_control": {"type": "ephemeral"}1089 }1090 ],1091 "messages": [1092 {"role": "user", "content": "Analyze the major themes in Pride and Prejudice."}1093 ]1094 }1095 },1096 {1097 "custom_id": "my-second-request",1098 "params": {1099 "model": "claude-opus-5",1100 "max_tokens": 1024,1101 "system": [1102 {1103 "type": "text",1104 "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"1105 },1106 {1107 "type": "text",1108 "text": "<the entire contents of Pride and Prejudice>",1109 "cache_control": {"type": "ephemeral"}1110 }1111 ],1112 "messages": [1113 {"role": "user", "content": "Write a summary of Pride and Prejudice."}1114 ]1115 }1116 }1117 ]1118 }'1119 ```11201121 ```bash CLI1122 ant messages:batches create <<'YAML'1123 requests:1124 - custom_id: my-first-request1125 params:1126 model: claude-opus-51127 max_tokens: 10241128 system:1129 - type: text1130 text: >1131 You are an AI assistant tasked with analyzing literary works. Your1132 goal is to provide insightful commentary on themes, characters, and1133 writing style.1134 - type: text1135 text: "<the entire contents of Pride and Prejudice>"1136 cache_control:1137 type: ephemeral1138 messages:1139 - role: user1140 content: Analyze the major themes in Pride and Prejudice.1141 - custom_id: my-second-request1142 params:1143 model: claude-opus-51144 max_tokens: 10241145 system:1146 - type: text1147 text: >1148 You are an AI assistant tasked with analyzing literary works. Your1149 goal is to provide insightful commentary on themes, characters, and1150 writing style.1151 - type: text1152 text: "<the entire contents of Pride and Prejudice>"1153 cache_control:1154 type: ephemeral1155 messages:1156 - role: user1157 content: Write a summary of Pride and Prejudice.1158 YAML1159 ```11601161 ```python Python1162 from anthropic.types.message_create_params import MessageCreateParamsNonStreaming1163 from anthropic.types.messages.batch_create_params import Request11641165 client = anthropic.Anthropic()11661167 message_batch = client.messages.batches.create(1168 requests=[1169 Request(1170 custom_id="my-first-request",1171 params=MessageCreateParamsNonStreaming(1172 model="claude-opus-5",1173 max_tokens=1024,1174 system=[1175 {1176 "type": "text",1177 "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n",1178 },1179 {1180 "type": "text",1181 "text": "<the entire contents of Pride and Prejudice>",1182 "cache_control": {"type": "ephemeral"},1183 },1184 ],1185 messages=[1186 {1187 "role": "user",1188 "content": "Analyze the major themes in Pride and Prejudice.",1189 }1190 ],1191 ),1192 ),1193 Request(1194 custom_id="my-second-request",1195 params=MessageCreateParamsNonStreaming(1196 model="claude-opus-5",1197 max_tokens=1024,1198 system=[1199 {1200 "type": "text",1201 "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n",1202 },1203 {1204 "type": "text",1205 "text": "<the entire contents of Pride and Prejudice>",1206 "cache_control": {"type": "ephemeral"},1207 },1208 ],1209 messages=[1210 {1211 "role": "user",1212 "content": "Write a summary of Pride and Prejudice.",1213 }1214 ],1215 ),1216 ),1217 ]1218 )1219 ```12201221 ```typescript TypeScript1222 const client = new Anthropic();12231224 const messageBatch = await client.messages.batches.create({1225 requests: [1226 {1227 custom_id: "my-first-request",1228 params: {1229 model: "claude-opus-5",1230 max_tokens: 1024,1231 system: [1232 {1233 type: "text",1234 text: "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"1235 },1236 {1237 type: "text",1238 text: "<the entire contents of Pride and Prejudice>",1239 cache_control: { type: "ephemeral" }1240 }1241 ],1242 messages: [1243 { role: "user", content: "Analyze the major themes in Pride and Prejudice." }1244 ]1245 }1246 },1247 {1248 custom_id: "my-second-request",1249 params: {1250 model: "claude-opus-5",1251 max_tokens: 1024,1252 system: [1253 {1254 type: "text",1255 text: "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"1256 },1257 {1258 type: "text",1259 text: "<the entire contents of Pride and Prejudice>",1260 cache_control: { type: "ephemeral" }1261 }1262 ],1263 messages: [{ role: "user", content: "Write a summary of Pride and Prejudice." }]1264 }1265 }1266 ]1267 });1268 ```12691270 ```csharp C#1271 using Anthropic;1272 using Anthropic.Models.Messages;1273 using Anthropic.Models.Messages.Batches;12741275 AnthropicClient client = new()1276 {1277 ApiKey = Environment.GetEnvironmentVariable("ANTHROPIC_API_KEY")1278 };12791280 var messageBatch = await client.Messages.Batches.Create(new BatchCreateParams1281 {1282 Requests =1283 [1284 new()1285 {1286 CustomID = "my-first-request",1287 Params = new()1288 {1289 Model = Model.ClaudeOpus5,1290 MaxTokens = 1024,1291 System = new List<TextBlockParam>1292 {1293 new()1294 {1295 Text = "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"1296 },1297 new()1298 {1299 Text = "<the entire contents of Pride and Prejudice>",1300 CacheControl = new()1301 }1302 },1303 Messages =1304 [1305 new() { Role = Role.User, Content = "Analyze the major themes in Pride and Prejudice." }1306 ]1307 }1308 },1309 new()1310 {1311 CustomID = "my-second-request",1312 Params = new()1313 {1314 Model = Model.ClaudeOpus5,1315 MaxTokens = 1024,1316 System = new List<TextBlockParam>1317 {1318 new()1319 {1320 Text = "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"1321 },1322 new()1323 {1324 Text = "<the entire contents of Pride and Prejudice>",1325 CacheControl = new()1326 }1327 },1328 Messages =1329 [1330 new() { Role = Role.User, Content = "Write a summary of Pride and Prejudice." }1331 ]1332 }1333 }1334 ]1335 });1336 ```13371338 ```go Go1339 client := anthropic.NewClient()13401341 messageBatch, err := client.Messages.Batches.New(context.TODO(), anthropic.MessageBatchNewParams{1342 Requests: []anthropic.MessageBatchNewParamsRequest{1343 {1344 CustomID: "my-first-request",1345 Params: anthropic.MessageBatchNewParamsRequestParams{1346 Model: anthropic.ModelClaudeOpus5,1347 MaxTokens: 1024,1348 System: []anthropic.TextBlockParam{1349 {1350 Text: "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n",1351 },1352 {1353 Text: "<the entire contents of Pride and Prejudice>",1354 CacheControl: anthropic.NewCacheControlEphemeralParam(),1355 },1356 },1357 Messages: []anthropic.MessageParam{1358 anthropic.NewUserMessage(anthropic.NewTextBlock("Analyze the major themes in Pride and Prejudice.")),1359 },1360 },1361 },1362 {1363 CustomID: "my-second-request",1364 Params: anthropic.MessageBatchNewParamsRequestParams{1365 Model: anthropic.ModelClaudeOpus5,1366 MaxTokens: 1024,1367 System: []anthropic.TextBlockParam{1368 {1369 Text: "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n",1370 },1371 {1372 Text: "<the entire contents of Pride and Prejudice>",1373 CacheControl: anthropic.NewCacheControlEphemeralParam(),1374 },1375 },1376 Messages: []anthropic.MessageParam{1377 anthropic.NewUserMessage(anthropic.NewTextBlock("Write a summary of Pride and Prejudice.")),1378 },1379 },1380 },1381 },1382 })1383 if err != nil {1384 log.Fatal(err)1385 }1386 fmt.Println(messageBatch)1387 ```13881389 ```java Java1390 import com.anthropic.models.messages.CacheControlEphemeral;1391 // ...1392 import com.anthropic.models.messages.batches.*;1393 // ...1394 AnthropicClient client = AnthropicOkHttpClient.fromEnv();13951396 BatchCreateParams createParams = BatchCreateParams.builder()1397 .addRequest(1398 BatchCreateParams.Request.builder()1399 .customId("my-first-request")1400 .params(1401 BatchCreateParams.Request.Params.builder()1402 .model(Model.CLAUDE_OPUS_5)1403 .maxTokens(1024)1404 .systemOfTextBlockParams(1405 List.of(1406 TextBlockParam.builder()1407 .text(1408 "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"1409 )1410 .build(),1411 TextBlockParam.builder()1412 .text("<the entire contents of Pride and Prejudice>")1413 .cacheControl(CacheControlEphemeral.builder().build())1414 .build()1415 )1416 )1417 .addUserMessage("Analyze the major themes in Pride and Prejudice.")1418 .build()1419 )1420 .build()1421 )1422 .addRequest(1423 BatchCreateParams.Request.builder()1424 .customId("my-second-request")1425 .params(1426 BatchCreateParams.Request.Params.builder()1427 .model(Model.CLAUDE_OPUS_5)1428 .maxTokens(1024)1429 .systemOfTextBlockParams(1430 List.of(1431 TextBlockParam.builder()1432 .text(1433 "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"1434 )1435 .build(),1436 TextBlockParam.builder()1437 .text("<the entire contents of Pride and Prejudice>")1438 .cacheControl(CacheControlEphemeral.builder().build())1439 .build()1440 )1441 )1442 .addUserMessage("Write a summary of Pride and Prejudice.")1443 .build()1444 )1445 .build()1446 )1447 .build();14481449 MessageBatch messageBatch = client.messages().batches().create(createParams);1450 ```14511452 ```php PHP1453 $client = new Client();14541455 $messageBatch = $client->messages->batches->create(1456 requests: [1457 [1458 'custom_id' => 'my-first-request',1459 'params' => [1460 'model' => 'claude-opus-5',1461 'max_tokens' => 1024,1462 'system' => [1463 [1464 'type' => 'text',1465 'text' => 'You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n'1466 ],1467 [1468 'type' => 'text',1469 'text' => '<the entire contents of Pride and Prejudice>',1470 'cache_control' => ['type' => 'ephemeral']1471 ]1472 ],1473 'messages' => [1474 ['role' => 'user', 'content' => 'Analyze the major themes in Pride and Prejudice.']1475 ]1476 ]1477 ],1478 [1479 'custom_id' => 'my-second-request',1480 'params' => [1481 'model' => 'claude-opus-5',1482 'max_tokens' => 1024,1483 'system' => [1484 [1485 'type' => 'text',1486 'text' => 'You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n'1487 ],1488 [1489 'type' => 'text',1490 'text' => '<the entire contents of Pride and Prejudice>',1491 'cache_control' => ['type' => 'ephemeral']1492 ]1493 ],1494 'messages' => [1495 ['role' => 'user', 'content' => 'Write a summary of Pride and Prejudice.']1496 ]1497 ]1498 ]1499 ],1500 );1501 ```15021503 ```ruby Ruby1504 client = Anthropic::Client.new15051506 message_batch = client.messages.batches.create(1507 requests: [1508 {1509 custom_id: "my-first-request",1510 params: {1511 model: "claude-opus-5",1512 max_tokens: 1024,1513 system: [1514 {1515 type: "text",1516 text: "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"1517 },1518 {1519 type: "text",1520 text: "<the entire contents of Pride and Prejudice>",1521 cache_control: { type: "ephemeral" }1522 }1523 ],1524 messages: [1525 { role: "user", content: "Analyze the major themes in Pride and Prejudice." }1526 ]1527 }1528 },1529 {1530 custom_id: "my-second-request",1531 params: {1532 model: "claude-opus-5",1533 max_tokens: 1024,1534 system: [1535 {1536 type: "text",1537 text: "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"1538 },1539 {1540 type: "text",1541 text: "<the entire contents of Pride and Prejudice>",1542 cache_control: { type: "ephemeral" }1543 }1544 ],1545 messages: [1546 { role: "user", content: "Write a summary of Pride and Prejudice." }1547 ]1548 }1549 }1550 ]1551 )1552 ```1553</CodeGroup>15541555In this example, both requests in the batch include identical system messages and the full text of Pride and Prejudice marked with `cache_control` to increase the likelihood of cache hits.15561557### Server tools and the agentic loop15581559All [server tools](https://platform.claude.com/docs/en/agents-and-tools/tool-use/server-tools) (web search, web fetch, code execution, MCP connectors, advisor, and tool search) work in batch requests. The batch worker runs the same server-side agentic loop as the synchronous Messages API.15601561Because there is no open connection to maintain, the batch loop runs **more iterations per turn** than a synchronous request before it returns `stop_reason: "pause_turn"`. If a batch result comes back with `pause_turn`, the turn did not finish; you can continue it by submitting the paused assistant content in a follow-up request (batch or synchronous) exactly as shown in the [pause\_turn continuation pattern](https://platform.claude.com/docs/en/agents-and-tools/tool-use/server-tools#the-server-side-loop-and-pause-turn).15621563The batch worker additionally throttles `web_search` per organization so that highly concurrent batch processing does not exhaust your organization's web-search rate limit. The batch retries throttled requests automatically; you don't need to handle this yourself, but very large web-search batches might take longer to complete.15641565### Extended output (beta)15661567The `output-300k-2026-03-24` beta header raises the `max_tokens` cap to 300,000 for batch requests using Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 5, or Claude Sonnet 4.6. Include the header to generate outputs far longer than the standard 128k `max_tokens` limit in a single turn.15681569<Note>1570 Extended output is available on the Message Batches API only, not the synchronous Messages API. It is supported on the Claude API and Claude Platform on AWS, and is not currently available on Amazon Bedrock, Google Cloud, or Microsoft Foundry.1571</Note>15721573Use extended output for long-form generation such as book-length drafts and technical documentation, exhaustive structured data extraction, large code-generation scaffolds, and long reasoning chains.15741575A single 300k-token generation can take over an hour to complete, so plan your batch submissions with the 24-hour processing window in mind. Standard batch pricing (50% of standard API prices) applies.15761577<CodeGroup>1578 ```bash cURL1579 curl https://api.anthropic.com/v1/messages/batches \1580 --header "x-api-key: $ANTHROPIC_API_KEY" \1581 --header "anthropic-version: 2023-06-01" \1582 --header "anthropic-beta: output-300k-2026-03-24" \1583 --header "content-type: application/json" \1584 --data \1585 '{1586 "requests": [1587 {1588 "custom_id": "long-form-request",1589 "params": {1590 "model": "claude-opus-5",1591 "max_tokens": 300000,1592 "messages": [1593 {"role": "user", "content": "Write a comprehensive technical guide to building distributed systems, covering architecture patterns, consistency models, fault tolerance, and operational best practices."}1594 ]1595 }1596 }1597 ]1598 }'1599 ```16001601 ```bash CLI1602 ant beta:messages:batches create --beta output-300k-2026-03-24 <<'YAML'1603 requests:1604 - custom_id: long-form-request1605 params:1606 model: claude-opus-51607 max_tokens: 3000001608 messages:1609 - role: user1610 content: >-1611 Write a comprehensive technical guide to building distributed1612 systems, covering architecture patterns, consistency models,1613 fault tolerance, and operational best practices.1614 YAML1615 ```16161617 ```python Python1618 from anthropic.types.beta.message_create_params import MessageCreateParamsNonStreaming1619 from anthropic.types.beta.messages.batch_create_params import Request16201621 client = anthropic.Anthropic()16221623 message_batch = client.beta.messages.batches.create(1624 betas=["output-300k-2026-03-24"],1625 requests=[1626 Request(1627 custom_id="long-form-request",1628 params=MessageCreateParamsNonStreaming(1629 model="claude-opus-5",1630 max_tokens=300_000,1631 messages=[1632 {1633 "role": "user",1634 "content": "Write a comprehensive technical guide to building distributed systems, covering architecture patterns, consistency models, fault tolerance, and operational best practices.",1635 }1636 ],1637 ),1638 ),1639 ],1640 )16411642 print(message_batch)1643 ```16441645 ```typescript TypeScript1646 const client = new Anthropic();16471648 const messageBatch = await client.beta.messages.batches.create({1649 betas: ["output-300k-2026-03-24"],1650 requests: [1651 {1652 custom_id: "long-form-request",1653 params: {1654 model: "claude-opus-5",1655 max_tokens: 300000,1656 messages: [1657 {1658 role: "user",1659 content:1660 "Write a comprehensive technical guide to building distributed systems, covering architecture patterns, consistency models, fault tolerance, and operational best practices."1661 }1662 ]1663 }1664 }1665 ]1666 });16671668 console.log(messageBatch);1669 ```16701671 ```csharp C#1672 using Anthropic;1673 using Anthropic.Models.Beta.Messages;1674 using Anthropic.Models.Beta.Messages.Batches;1675 using Model = Anthropic.Models.Messages.Model;16761677 AnthropicClient client = new();16781679 var batch = await client.Beta.Messages.Batches.Create(new BatchCreateParams1680 {1681 Betas = ["output-300k-2026-03-24"],1682 Requests =1683 [1684 new()1685 {1686 CustomID = "long-form-request",1687 Params = new()1688 {1689 Model = Model.ClaudeOpus5,1690 MaxTokens = 300_000,1691 Messages =1692 [1693 new() { Role = Role.User, Content = "Write a comprehensive technical guide to building distributed systems, covering architecture patterns, consistency models, fault tolerance, and operational best practices." }1694 ]1695 }1696 }1697 ]1698 });16991700 Console.WriteLine(batch);1701 ```17021703 ```go Go1704 client := anthropic.NewClient()17051706 batch, err := client.Beta.Messages.Batches.New(context.Background(),1707 anthropic.BetaMessageBatchNewParams{1708 Betas: []anthropic.AnthropicBeta{"output-300k-2026-03-24"},1709 Requests: []anthropic.BetaMessageBatchNewParamsRequest{1710 {1711 CustomID: "long-form-request",1712 Params: anthropic.BetaMessageBatchNewParamsRequestParams{1713 Model: anthropic.ModelClaudeOpus5,1714 MaxTokens: 300_000,1715 Messages: []anthropic.BetaMessageParam{1716 anthropic.NewBetaUserMessage(1717 anthropic.NewBetaTextBlock("Write a comprehensive technical guide to building distributed systems, covering architecture patterns, consistency models, fault tolerance, and operational best practices."),1718 ),1719 },1720 },1721 },1722 },1723 })1724 if err != nil {1725 panic(err)1726 }17271728 fmt.Println(batch.ID)1729 ```17301731 ```java Java1732 import com.anthropic.models.beta.messages.batches.*;17331734 void main() {1735 AnthropicClient client = AnthropicOkHttpClient.fromEnv();17361737 BatchCreateParams params = BatchCreateParams.builder()1738 .addBeta("output-300k-2026-03-24")1739 .addRequest(1740 BatchCreateParams.Request.builder()1741 .customId("long-form-request")1742 .params(1743 BatchCreateParams.Request.Params.builder()1744 .model(Model.CLAUDE_OPUS_5)1745 .maxTokens(300_000L)1746 .addUserMessage("Write a comprehensive technical guide to building distributed systems, covering architecture patterns, consistency models, fault tolerance, and operational best practices.")1747 .build()1748 )1749 .build()1750 )1751 .build();17521753 BetaMessageBatch messageBatch = client.beta().messages().batches().create(params);17541755 IO.println(messageBatch);1756 }1757 ```17581759 ```php PHP1760 $client = new Client();17611762 $batch = $client->beta->messages->batches->create(1763 betas: ['output-300k-2026-03-24'],1764 requests: [1765 [1766 'custom_id' => 'long-form-request',1767 'params' => [1768 'model' => 'claude-opus-5',1769 'max_tokens' => 300_000,1770 'messages' => [1771 ['role' => 'user', 'content' => 'Write a comprehensive technical guide to building distributed systems, covering architecture patterns, consistency models, fault tolerance, and operational best practices.']1772 ]1773 ]1774 ]1775 ],1776 );17771778 echo $batch->id;1779 ```17801781 ```ruby Ruby1782 client = Anthropic::Client.new17831784 batch = client.beta.messages.batches.create(1785 betas: ["output-300k-2026-03-24"],1786 requests: [1787 {1788 custom_id: "long-form-request",1789 params: {1790 model: "claude-opus-5",1791 max_tokens: 300_000,1792 messages: [1793 { role: "user", content: "Write a comprehensive technical guide to building distributed systems, covering architecture patterns, consistency models, fault tolerance, and operational best practices." }1794 ]1795 }1796 }1797 ]1798 )17991800 puts batch1801 ```1802</CodeGroup>18031804### Best practices for effective batching18051806To get the most out of the Batches API:18071808* Monitor batch processing status regularly and implement appropriate retry logic for failed requests.1809* Use meaningful `custom_id` values to easily match results with requests, since order is not guaranteed.1810* Consider breaking very large datasets into multiple batches for better manageability.1811* Dry run a single request shape with the Messages API to avoid validation errors.18121813### Troubleshooting common issues18141815If experiencing unexpected behavior:18161817* Verify that the total batch request size doesn't exceed 256 MB. If the request size is too large, you may get a 413 `request_too_large` error.1818* Check that you're using [supported models](https://platform.claude.com/docs/en/build-with-claude/batch-processing#supported-models) for all requests in the batch.1819* Ensure each request in the batch has a unique `custom_id`.1820* Ensure that it has been less than 29 days since batch `created_at` (not processing `ended_at`) time. If over 29 days have passed, results will no longer be viewable.1821* Confirm that the batch has not been canceled.18221823Note that the failure of one request in a batch does not affect the processing of other requests.18241825## Batch storage and privacy18261827* **Workspace isolation**: Batches are isolated within the Workspace they are created in. They can only be accessed by API requests in that same Workspace, or users with permission to view Workspace batches in the Console.18281829* **Result availability**: Batch results are available for 29 days after the batch is created, allowing ample time for retrieval and processing.18301831## Data retention18321833Batch processing stores request and response data for up to 29 days after batch creation. You can delete a message batch at any time after processing using the `DELETE /v1/messages/batches/{batch_id}` endpoint. To delete an in-progress batch, cancel it first. Asynchronous processing requires server-side storage of both inputs and outputs until batch completion and result retrieval.18341835For ZDR eligibility across all features, see [API and data retention](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention).18361837## FAQ18381839<AccordionGroup>1840 <Accordion title="How long does it take for a batch to process?">1841 Batches may take up to 24 hours for processing, but many finish sooner. Actual processing time depends on the size of the batch, current demand, and your request volume. It is possible for a batch to expire and not complete within 24 hours.1842 </Accordion>18431844 <Accordion title="Is the Batches API available for all models?">1845 See [Supported models](https://platform.claude.com/docs/en/build-with-claude/batch-processing#supported-models) for the list of supported models.1846 </Accordion>18471848 <Accordion title="Can I use the Message Batches API with other API features?">1849 Yes, the Message Batches API supports nearly all features available in the Messages API, including most beta features. A small number of parameters (`stream`, `speed`, and `max_tokens: 0`) are not supported. See [What can be batched](https://platform.claude.com/docs/en/build-with-claude/batch-processing#what-can-be-batched) for the full list.1850 </Accordion>18511852 <Accordion title="How does the Message Batches API affect pricing?">1853 The Message Batches API offers a 50% discount on all usage compared to standard API prices. This applies to input tokens, output tokens, and any special tokens. For more on pricing, visit [Pricing](https://claude.com/pricing#anthropic-api).1854 </Accordion>18551856 <Accordion title="Can I update a batch after it's been submitted?">1857 No, once a batch has been submitted, it cannot be modified. If you need to make changes, you should cancel the current batch and submit a new one. Note that cancellation may not take immediate effect.1858 </Accordion>18591860 <Accordion title="Are there Message Batches API rate limits and do they interact with the Messages API rate limits?">1861 The Message Batches API has HTTP requests-based rate limits in addition to limits on the number of requests in need of processing. See [Message Batches API rate limits](https://platform.claude.com/docs/en/api/rate-limits#message-batches-api). Usage of the Batches API does not affect rate limits in the Messages API.1862 </Accordion>18631864 <Accordion title="How do I handle errors in my batch requests?">1865 When you retrieve the results, each request has a `result` field indicating whether it `succeeded`, `errored`, was `canceled`, or `expired`. For `errored` results, additional error information is provided. View the error response object in the [API reference](https://platform.claude.com/docs/en/api/messages/batches/create).1866 </Accordion>18671868 <Accordion title="How does the Message Batches API handle privacy and data separation?">1869 The Message Batches API is designed with strong privacy and data separation measures:18701871 1. Batches and their results are isolated within the Workspace in which they were created. This means they can only be accessed by API requests in that same Workspace.1872 2. Each request within a batch is processed independently, with no data leakage between requests.1873 3. Results are only available for a limited time (29 days), and follow Anthropic's [data retention policy](https://support.claude.com/en/articles/7996866-how-long-do-you-store-personal-data).1874 4. Downloading batch results in the Console can be disabled on the organization-level or on a per-workspace basis.1875 </Accordion>18761877 <Accordion title="Can I use prompt caching in the Message Batches API?">1878 Yes, it is possible to use prompt caching with Message Batches API. However, because asynchronous batch requests can be processed concurrently and in any order, cache hits are provided on a best-effort basis.1879 </Accordion>1880</AccordionGroup>18811882## Next steps18831884<CardGroup cols={2}>1885 <Card title="Search results" icon="magnifying-glass" href="https://platform.claude.com/docs/en/build-with-claude/search-results">1886 Enable natural citations for RAG applications by providing search results with source attribution.1887 </Card>18881889 <Card title="Prompt caching" icon="database" href="https://platform.claude.com/docs/en/build-with-claude/prompt-caching">1890 Reduce cost and latency by caching prompt prefixes shared across requests in a batch.1891 </Card>1892</CardGroup>1893