Message Batches API changedbuild-with-claude/batch-processing
Nearest release: v2.1.312, published under an hour before this site recorded the change. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Recorded here
Lines+27added
Lines−23removed
From line
9
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits27to this page, all time
The whole hunk
from line 9, old and new numbered
/
from line 9
99* You need to process large volumes of data
1010* Immediate responses are not required
1111* You want to optimize for cost efficiency
12* You're running large-scale evaluations or analyses
12* You’re running large-scale evaluations or analyses
1313
14The Message Batches API is Anthropic's first implementation of this pattern.
14The Message Batches API is Anthropic’s first implementation of this pattern.
1515
1616<Note>
1717 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).
from line 19
1919
2020# Message Batches API
2121
22The 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.
22The 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 percent and increasing throughput.
2323
2424You can [explore the API reference directly](https://platform.claude.com/docs/en/api/messages/batches/create), in addition to this guide.
2525
from line 31
31312. The batch is then processed asynchronously, with each request handled independently.
32323. You can poll for the status of the batch and retrieve results when processing has ended for all requests.
3333
34This is especially useful for bulk operations that don't require immediate results, such as:
34This is especially useful for bulk operations that don’t require immediate results, such as:
3535
3636* Large-scale evaluations: Process thousands of test cases efficiently.
3737* Content moderation: Analyze large volumes of user-generated content asynchronously.
from line 46
4646* 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.
4747* 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.
4848* Because of high throughput and concurrent processing, batches may go slightly over the [spend limit](https://platform.claude.com/settings/billing) configured in the Claude Console for your Workspace.
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.
49* 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.
5050
5151### Supported models
5252
from line 70
7070| Parameter | Why |
7171| -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
7272| `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| `fallbacks` ([Server-side fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#server-side-fallback)) | Server-side fallback doesn't apply to batches. To retry refused requests, see [Refusals in Message Batches](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#refusals-in-message-batches). |
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| `fallbacks` ([Server-side fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#server-side-fallback)) | Server-side fallback doesn’t apply to batches. To retry refused requests, see [Refusals in Message Batches](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#refusals-in-message-batches). |
7575| `max_tokens: 0` | See [Batch limitations](https://platform.claude.com/docs/en/build-with-claude/batch-processing#batch-limitations). |
7676
7777<Tip>
from line 116
116116
117117A Message Batch is composed of a list of requests to create a Message. The shape of an individual request comprises:
118118
119* 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}$`).
120* A `params` object with the standard [Messages API](https://platform.claude.com/docs/en/api/messages/create) parameters
119* A unique [`custom_id`](https://platform.claude.com/docs/en/api/messages/batches/create#create.requests.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}$`).
120* A [`params`](https://platform.claude.com/docs/en/api/messages/batches/create#create.requests.params) object with the standard [Messages API](https://platform.claude.com/docs/en/api/messages/create) parameters
121121
122122You can [create a batch](https://platform.claude.com/docs/en/api/messages/batches/create) by passing this list into the `requests` parameter:
123123
from line 411
411411 ```
412412</CodeGroup>
413413
414In 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.
414In 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.
415415
416416<Tip>
417417 **Test your batch requests with the Messages API**
from line 443
443443
444444### Tracking your batch
445445
446The 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/messages/batches/retrieve).
446The Message Batch’s [`processing_status`](https://platform.claude.com/docs/en/api/messages/batches/retrieve#message_batch.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.
447447
448(See the `messages/batches/retrieve` method in [the API reference](https://platform.claude.com/docs/en/api/messages/batches/retrieve).)
449
448450#### Polling for Message Batch completion
449451
450To 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:
452To 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:
451453
452454<CodeGroup>
453455 ```bash cURL
from line 711
709711| `canceled` | User canceled the batch before this request could be sent to the model. You will not be billed for these requests. |
710712| `expired` | Batch reached its 24-hour expiration before this request could be sent to the model. You will not be billed for these requests. |
711713
712The batch's `request_counts` shows an overview of your results, indicating how many requests reached each of these four states.
714The batch’s `request_counts` object counts the requests still processing and the requests with each result type.
713715
714Results 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.
716(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).)
715717
718Results 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.
719
716720<CodeGroup>
717721 ```bash cURL
718722 # Streams the batch's .jsonl results, one result on each line.
from line 939
935939
936940### Canceling a Message Batch
937941
938You 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.
942You 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.
939943
940944<CodeGroup>
941945 ```bash cURL
from line 1549
15451549
15461550Because there is no open connection to maintain, the batch loop can run **more iterations in a 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 complete; 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).
15471551
1548The batch worker additionally throttles `web_search` for each 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.
1552The batch worker additionally throttles `web_search` for each 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.
15491553
15501554### Extended output (beta)
15511555
from line 1802
17981802
17991803If experiencing unexpected behavior:
18001804
1801* 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.
1802* 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.
1805* 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.
1806* 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.
18031807* Ensure each request in the batch has a unique `custom_id`.
18041808* 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.
18051809* Confirm that the batch has not been canceled.
from line 1818
18141818
18151819## Data retention
18161820
1817Batch 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.
1821Batch 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}`](https://platform.claude.com/docs/en/api/messages/batches/delete) 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.
18181822
18191823For ZDR eligibility across all features, see [API and data retention](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention).
18201824
from line 1841
18371841 The Message Batches API offers a 50 percent 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).
18381842 </Accordion>
18391843
1840 <Accordion title="Can I update a batch after it's been submitted?">
1844 <Accordion title="Can I update a batch after it’s been submitted?">
18411845 No, once a batch has been submitted, it cannot be modified. If you need to make changes, cancel the current batch and submit a new one. Note that cancellation might not take immediate effect.
18421846 </Accordion>
18431847
from line 1858
18541858
18551859 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.
18561860 2. Each request within a batch is processed independently, with no data leakage between requests.
1857 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).
1861 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).
18581862 4. Downloading batch results in the Console can be disabled on the organization level or on a per-workspace basis.
18591863 </Accordion>
18601864
No line in this hunk matches that.