Message Batches API changedbuild-with-claude/batch-processing
Recorded here
Lines+18added
Lines−18removed
From line
40
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits34to this page, all time
The whole hunk
from line 40, old and new numbered
/
from line 40
4040* You want to optimize for cost efficiency
4141* You’re running large-scale evaluations or analyses
4242
43The Message Batches API is Anthropic’s first implementation of this pattern.
43The Message Batches API implements this pattern.
4444
4545# Message Batches API
4646
from line 67
6767
6868* A Message Batch is limited to either 100,000 Message requests or 256 MB in size, whichever is reached first.
6969* 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.
70* Batch results are available for 29 days after creation. After that, you can still view the Batch, but its results will no longer be available for download.
71* Batches are scoped to a [Workspace](https://platform.claude.com/settings/workspaces) in the Claude Console. You may view all batches (and their results) that were created within the Workspace your request runs in.
70* Batch results are available for 29 days after creation. After that, you can still view the batch, but its results are no longer available for download.
71* Batches are scoped to a [Workspace in the Claude Console](https://platform.claude.com/settings/workspaces). You can view all batches (and their results) that were created within the Workspace your request runs in.
7272* 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 might be slowed down based on current demand and your request volume. In that case, you might see more requests expiring after 24 hours.
7373* Because of high throughput and concurrent processing, batches might go slightly over the [spend limit](https://platform.claude.com/docs/en/manage-claude/workspaces#setting-workspace-limits) configured in the Claude Console for your Workspace.
7474* Each batched request must have [`max_tokens`](https://platform.claude.com/docs/en/api/messages/create#create.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.
from line 442
442442<Tip>
443443 **Test your batch requests with the Messages API**
444444
445 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.
445 The API validates the `params` object of each message request asynchronously, and returns validation errors when processing of the entire batch has ended. To check that you build your input correctly, verify your request shape with the [Messages API](https://platform.claude.com/docs/en/api/messages/create) first.
446446</Tip>
447447
448448When a batch is first created, the response has a processing status of `in_progress`.
from line 622
622622
623623### Listing all Message Batches
624624
625You can list all Message Batches in your Workspace using the [list endpoint](https://platform.claude.com/docs/en/api/messages/batches/list). The API supports pagination, automatically fetching additional pages as needed:
625You can list all Message Batches in your Workspace using the [list endpoint](https://platform.claude.com/docs/en/api/messages/batches/list). Results are paginated. The SDK fetches additional pages as needed:
626626
627627<CodeGroup>
628628 ```bash cURL
from line 730
730730
731731Once batch processing has ended, each Messages request in the batch has a result. There are four result types:
732732
733| Result type | Description |
734| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
735| `succeeded` | Request was successful. Includes the message result. |
736| `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. |
737| `canceled` | User canceled the batch before this request could be sent to the model. You will not be billed for these requests. |
738| `expired` | Batch reached its 24-hour expiration before this request could be sent to the model. You will not be billed for these requests. |
733| Result type | Description |
734| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
735| `succeeded` | Request was successful. Includes the message result. |
736| `errored` | Request encountered an error and a message was not created. Possible errors include invalid requests and internal server errors. You aren’t billed for these requests. |
737| `canceled` | User canceled the batch before this request could be sent to the model. You aren’t billed for these requests. |
738| `expired` | Batch reached its 24-hour expiration before this request could be sent to the model. You aren’t billed for these requests. |
739739
740740The batch’s `request_counts` object counts the requests still processing and the requests with each result type.
741741
742742(See `message_batch.request_counts` on `messages/batches/retrieve` in [the API reference](https://platform.claude.com/docs/en/api/messages/batches/retrieve#message_batch.request_counts).)
743743
744Results of the batch are available for download at the [`results_url`](https://platform.claude.com/docs/en/api/messages/batches/retrieve#message_batch.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.
744Results of the batch are available for download at the [`results_url`](https://platform.claude.com/docs/en/api/messages/batches/retrieve#message_batch.results_url) property on the Message Batch and, if your organization’s permissions allow, in the Console. Because the results can be large, [stream results](https://platform.claude.com/docs/en/api/messages/batches/results) back rather than download them all at once.
745745
746746<CodeGroup>
747747 ```bash cURL
from line 958
958958Batch results use the API version of the request that created the batch.
959959
960960<Tip>
961 **Batch results may not match input order**
961 **Batch results might not match input order**
962962
963 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.
963 Batch results can be returned in any order, and might 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.
964964</Tip>
965965
966966### Canceling a Message Batch
967967
968You can cancel a Message Batch that is currently processing using the [cancel endpoint](https://platform.claude.com/docs/en/api/messages/batches/cancel). 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.
968You can cancel a Message Batch that is currently processing using the [cancel endpoint](https://platform.claude.com/docs/en/api/messages/batches/cancel). Immediately after cancellation, a batch’s `processing_status` is `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 might contain partial results for requests that were processed before cancellation.
969969
970970<CodeGroup>
971971 ```bash cURL
from line 1582
15821582The `output-300k-2026-03-24` beta header raises the `max_tokens` cap to 300,000 for batch requests using Claude Opus 5.5, Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 5.5, Claude Sonnet 5, Claude Sonnet 4.6, or Claude Haiku 5.5. Include the header to generate outputs far longer than the standard 128k `max_tokens` limit in a single turn.
15831583
15841584<Note>
1585 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, Claude Models on Google Cloud (Google managed), or Microsoft Foundry.
1585 Extended output is available on the Message Batches API only, not the synchronous Messages API. It is available on the Claude API and Claude Platform on AWS.
15861586</Note>
15871587
15881588Use 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.
from line 1831
18311831* Verify that the total batch request size doesn’t exceed 256 MB. If the request size is too large, you might get a 413 `request_too_large` error.
18321832* 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.
18331833* Ensure each request in the batch has a unique `custom_id`.
1834* 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.
1834* Ensure that it has been less than 29 days since batch `created_at` (not processing `ended_at`) time. After 29 days, results are no longer available for download.
18351835* Confirm that the batch has not been canceled.
18361836
18371837Note that the failure of one request in a batch does not affect the processing of other requests.
No line in this hunk matches that.