Message Batches API changedbuild-with-claude/batch-processing
Nearest release: v2.1.307, published an hour after 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+121added
Lines−123removed
From line
1
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits22to this page, all time
The whole hunk
from line 1, old and new numbered
/
from line 1
11---
22title: Batch processing
33url: https://platform.claude.com/docs/en/build-with-claude/batch-processing
4description: Process large volumes of Messages requests asynchronously with the Message Batches API, cutting costs by 50% and increasing throughput.
4description: Process large volumes of Messages requests asynchronously with the Message Batches API, cutting costs by 50 percent and increasing throughput.
55---
66
77Batch 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:
from line 42
4242
4343* A Message Batch is limited to either 100,000 Message requests or 256 MB in size, whichever is reached first.
4444* 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.
45* 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.
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.
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.
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 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.
4949* 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.
5050
from line 67
6767
6868A small number of Messages API parameters are **not** supported in batch requests. Including any of these returns a validation error:
6969
70| 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). |
70| 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| `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). |
75| `max_tokens: 0` | See [Batch limitations](https://platform.claude.com/docs/en/build-with-claude/batch-processing#batch-limitations). |
7576
7677<Tip>
7778 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.
from line 80
7980
8081## Pricing
8182
82The Batches API offers significant cost savings. All usage is charged at 50% of the standard API prices.
83The Batches API offers significant cost savings. All usage is charged at 50 percent of the standard API prices.
8384
8485| Model | Batch input | Batch output |
8586| :----------------------------------------------------------------------------------------------------------------------------------- | :----------- | :------------ |
from line 124
123124<CodeGroup>
124125 ```bash cURL
125126 curl https://api.anthropic.com/v1/messages/batches \
126 --header "x-api-key: $ANTHROPIC_API_KEY" \
127 --header "anthropic-version: 2023-06-01" \
128 --header "content-type: application/json" \
129 --data \
130 '{
127 -H "x-api-key: $ANTHROPIC_API_KEY" \
128 -H "anthropic-version: 2023-06-01" \
129 -H "content-type: application/json" \
130 -d '{
131131 "requests": [
132 {
133 "custom_id": "my-first-request",
134 "params": {
135 "model": "claude-opus-5-5",
136 "max_tokens": 1024,
137 "messages": [
138 {"role": "user", "content": "Hello, world"}
139 ]
140 }
141 },
142 {
143 "custom_id": "my-second-request",
144 "params": {
145 "model": "claude-opus-5-5",
146 "max_tokens": 1024,
147 "messages": [
148 {"role": "user", "content": "Hi again, friend"}
149 ]
150 }
132 {
133 "custom_id": "my-first-request",
134 "params": {
135 "model": "claude-opus-5-5",
136 "max_tokens": 1024,
137 "messages": [
138 {"role": "user", "content": "Hello, world"}
139 ]
151140 }
141 },
142 {
143 "custom_id": "my-second-request",
144 "params": {
145 "model": "claude-opus-5-5",
146 "max_tokens": 1024,
147 "messages": [
148 {"role": "user", "content": "Hi again, friend"}
149 ]
150 }
151 }
152152 ]
153 }'
153 }'
154154 ```
155155
156156 ```bash CLI
from line 453
453453 ```bash cURL
454454 # Check the status; repeat until processing_status is "ended"
455455 curl "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"
456 -H "x-api-key: $ANTHROPIC_API_KEY" \
457 -H "anthropic-version: 2023-06-01"
458458 ```
459459
460460 ```bash CLI
from line 603
603603 # last_id as after_id to fetch the next page. (The SDKs and the CLI
604604 # perform automatic pagination.)
605605 curl -s "https://api.anthropic.com/v1/messages/batches?limit=20" \
606 --header "x-api-key: $ANTHROPIC_API_KEY" \
607 --header "anthropic-version: 2023-06-01"
606 -H "x-api-key: $ANTHROPIC_API_KEY" \
607 -H "anthropic-version: 2023-06-01"
608608 ```
609609
610610 ```bash CLI
from line 717
717717 # Streams the batch's .jsonl results, one result per line.
718718 # For per-result handling (retries, validation errors), use the Claude SDK.
719719 curl "https://api.anthropic.com/v1/messages/batches/msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d/results" \
720 --header "anthropic-version: 2023-06-01" \
721 --header "x-api-key: $ANTHROPIC_API_KEY"
720 -H "anthropic-version: 2023-06-01" \
721 -H "x-api-key: $ANTHROPIC_API_KEY"
722722 ```
723723
724724 ```bash CLI
725 # Prints one result per line, e.g. `{"custom_id":"test-1","result":{"type":"succeeded",…}}`.
725 # Prints one result per line, for example `{"custom_id":"test-1","result":{"type":"succeeded",…}}`.
726726 # For per-result handling (retries, validation errors), use the SDK
727727 # examples in the other tabs.
728728 ant messages:batches results \
from line 938
938938
939939<CodeGroup>
940940 ```bash cURL
941 curl --request POST https://api.anthropic.com/v1/messages/batches/$MESSAGE_BATCH_ID/cancel \
942 --header "x-api-key: $ANTHROPIC_API_KEY" \
943 --header "anthropic-version: 2023-06-01"
941 curl -X POST https://api.anthropic.com/v1/messages/batches/$MESSAGE_BATCH_ID/cancel \
942 -H "x-api-key: $ANTHROPIC_API_KEY" \
943 -H "anthropic-version: 2023-06-01"
944944 ```
945945
946946 ```bash CLI
from line 1038
10381038
10391039### Using prompt caching with Message Batches
10401040
1041The 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.
1041The 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 percent to 98 percent, depending on their traffic patterns.
10421042
10431043To maximize the likelihood of cache hits in your batch requests:
10441044
from line 1051
10511051<CodeGroup>
10521052 ```bash cURL
10531053 curl https://api.anthropic.com/v1/messages/batches \
1054 --header "x-api-key: $ANTHROPIC_API_KEY" \
1055 --header "anthropic-version: 2023-06-01" \
1056 --header "content-type: application/json" \
1057 --data \
1058 '{
1054 -H "x-api-key: $ANTHROPIC_API_KEY" \
1055 -H "anthropic-version: 2023-06-01" \
1056 -H "content-type: application/json" \
1057 -d '{
10591058 "requests": [
1060 {
1061 "custom_id": "my-first-request",
1062 "params": {
1063 "model": "claude-opus-5-5",
1064 "max_tokens": 1024,
1065 "system": [
1066 {
1067 "type": "text",
1068 "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"
1069 },
1070 {
1071 "type": "text",
1072 "text": "<the entire contents of Pride and Prejudice>",
1073 "cache_control": {"type": "ephemeral"}
1074 }
1075 ],
1076 "messages": [
1077 {"role": "user", "content": "Analyze the major themes in Pride and Prejudice."}
1078 ]
1059 {
1060 "custom_id": "my-first-request",
1061 "params": {
1062 "model": "claude-opus-5-5",
1063 "max_tokens": 1024,
1064 "system": [
1065 {
1066 "type": "text",
1067 "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"
1068 },
1069 {
1070 "type": "text",
1071 "text": "<the entire contents of Pride and Prejudice>",
1072 "cache_control": {"type": "ephemeral"}
10791073 }
1080 },
1081 {
1082 "custom_id": "my-second-request",
1083 "params": {
1084 "model": "claude-opus-5-5",
1085 "max_tokens": 1024,
1086 "system": [
1087 {
1088 "type": "text",
1089 "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"
1090 },
1091 {
1092 "type": "text",
1093 "text": "<the entire contents of Pride and Prejudice>",
1094 "cache_control": {"type": "ephemeral"}
1095 }
1096 ],
1097 "messages": [
1098 {"role": "user", "content": "Write a summary of Pride and Prejudice."}
1099 ]
1074 ],
1075 "messages": [
1076 {"role": "user", "content": "Analyze the major themes in Pride and Prejudice."}
1077 ]
1078 }
1079 },
1080 {
1081 "custom_id": "my-second-request",
1082 "params": {
1083 "model": "claude-opus-5-5",
1084 "max_tokens": 1024,
1085 "system": [
1086 {
1087 "type": "text",
1088 "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"
1089 },
1090 {
1091 "type": "text",
1092 "text": "<the entire contents of Pride and Prejudice>",
1093 "cache_control": {"type": "ephemeral"}
11001094 }
1095 ],
1096 "messages": [
1097 {"role": "user", "content": "Write a summary of Pride and Prejudice."}
1098 ]
11011099 }
1100 }
11021101 ]
1103 }'
1102 }'
11041103 ```
11051104
11061105 ```bash CLI
from line 1542
15431542
15441543All [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.
15451544
1546Because 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).
1545Because 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 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).
15471546
1548The 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.
1547The 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.
15491548
15501549### Extended output (beta)
15511550
from line 1556
15571556
15581557Use 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.
15591558
1560A 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.
1559A 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 percent of standard API prices) applies.
15611560
15621561<CodeGroup>
15631562 ```bash cURL
15641563 curl https://api.anthropic.com/v1/messages/batches \
1565 --header "x-api-key: $ANTHROPIC_API_KEY" \
1566 --header "anthropic-version: 2023-06-01" \
1567 --header "anthropic-beta: output-300k-2026-03-24" \
1568 --header "content-type: application/json" \
1569 --data \
1570 '{
1564 -H "x-api-key: $ANTHROPIC_API_KEY" \
1565 -H "anthropic-version: 2023-06-01" \
1566 -H "anthropic-beta: output-300k-2026-03-24" \
1567 -H "content-type: application/json" \
1568 -d '{
15711569 "requests": [
1572 {
1573 "custom_id": "long-form-request",
1574 "params": {
1575 "model": "claude-opus-5-5",
1576 "max_tokens": 300000,
1577 "messages": [
1578 {"role": "user", "content": "Write a comprehensive technical guide to building distributed systems, covering architecture patterns, consistency models, fault tolerance, and operational best practices."}
1579 ]
1580 }
1570 {
1571 "custom_id": "long-form-request",
1572 "params": {
1573 "model": "claude-opus-5-5",
1574 "max_tokens": 300000,
1575 "messages": [
1576 {"role": "user", "content": "Write a comprehensive technical guide to building distributed systems, covering architecture patterns, consistency models, fault tolerance, and operational best practices."}
1577 ]
15811578 }
1579 }
15821580 ]
1583 }'
1581 }'
15841582 ```
15851583
15861584 ```bash CLI
from line 1786
17881786
17891787### Best practices for effective batching
17901788
1791To get the most out of the Batches API:
1789To use the Batches API effectively:
17921790
17931791* Monitor batch processing status regularly and implement appropriate retry logic for failed requests.
1794* Use meaningful `custom_id` values to easily match results with requests, since order is not guaranteed.
1792* Use meaningful `custom_id` values to easily match results with requests, because order is not guaranteed.
17951793* Consider breaking very large datasets into multiple batches for better manageability.
17961794* Dry run a single request shape with the Messages API to avoid validation errors.
17971795
from line 1797
17991797
18001798If experiencing unexpected behavior:
18011799
1802* 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.
1800* 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.
18031801* 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.
18041802* Ensure each request in the batch has a unique `custom_id`.
18051803* 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.
from line 1807
18091807
18101808## Batch storage and privacy
18111809
1812* **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.
1810* **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.
18131811
1814* **Result availability**: Batch results are available for 29 days after the batch is created, allowing ample time for retrieval and processing.
1812* **Result availability:** Batch results are available for 29 days after the batch is created, allowing ample time for retrieval and processing.
18151813
18161814## Data retention
18171815
from line 1821
18231821
18241822<AccordionGroup>
18251823 <Accordion title="How long does it take for a batch to process?">
1826 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.
1824 Batches might take up to 24 hours for processing, but many complete 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.
18271825 </Accordion>
18281826
18291827 <Accordion title="Is the Batches API available for all models?">
from line 1829
18311829 </Accordion>
18321830
18331831 <Accordion title="Can I use the Message Batches API with other API features?">
1834 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.
1832 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`, `fallbacks`, 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.
18351833 </Accordion>
18361834
18371835 <Accordion title="How does the Message Batches API affect pricing?">
1838 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).
1836 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).
18391837 </Accordion>
18401838
18411839 <Accordion title="Can I update a batch after it's been submitted?">
1842 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.
1840 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 might not take immediate effect.
18431841 </Accordion>
18441842
18451843 <Accordion title="Are there Message Batches API rate limits and do they interact with the Messages API rate limits?">
from line 1854
18561854 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.
18571855 2. Each request within a batch is processed independently, with no data leakage between requests.
18581856 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).
1859 4. Downloading batch results in the Console can be disabled on the organization-level or on a per-workspace basis.
1857 4. Downloading batch results in the Console can be disabled on the organization level or on a per-workspace basis.
18601858 </Accordion>
18611859
18621860 <Accordion title="Can I use prompt caching in the Message Batches API?">
1863 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.
1861 Yes, it is possible to use prompt caching with the 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.
18641862 </Accordion>
18651863</AccordionGroup>
18661864
from line 1866
18681866
18691867<CardGroup cols={2}>
18701868 <Card title="Search results" icon="magnifying-glass" href="https://platform.claude.com/docs/en/build-with-claude/search-results">
1871 Enable natural citations for RAG applications by providing search results with source attribution.
1869 Get natural citations for RAG applications by providing search results with source attribution.
18721870 </Card>
18731871
18741872 <Card title="Prompt caching" icon="database" href="https://platform.claude.com/docs/en/build-with-claude/prompt-caching">
No line in this hunk matches that.