SPB Git

Repository Public

batch-processing.md 72.4 KB 1,893 lines markdown

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
Files main
Menu

Theme