Batches changedapi/messages/batches
Recorded here
Lines+43added
Lines−43removed
From line
13
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits24to this page, all time
The whole hunk
from line 13, old and new numbered
/
This page is larger than the 256 KiB this site keeps, so one side of the diff below stops where the stored text does.
from line 13
1313
1414The Message Batches API can be used to process multiple Messages API requests at once. Once a Message Batch is created, it begins processing immediately. Batches can take up to 24 hours to complete.
1515
16Learn more about the Message Batches API in our [user guide](https://platform.claude.com/docs/en/build-with-claude/batch-processing)
16Learn more about the Message Batches API in our [user guide](https://platform.claude.com/docs/en/build-with-claude/batch-processing?sdk_languages=http)
1717
1818### Headers
1919
from line 21
2121
2222 The version of the Claude API you want to use.
2323
24 Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning).
24 Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning?sdk_languages=http).
2525
2626- `"anthropic-user-profile-id": optional string`
2727
from line 53
5353
5454 Messages API creation parameters for the individual request.
5555
56 See the [Messages API reference](https://platform.claude.com/docs/en/api/messages) for full documentation on available parameters.
56 See the [Messages API reference](https://platform.claude.com/docs/en/api/messages?sdk_languages=http) for full documentation on available parameters.
5757
5858 - `max_tokens: number`
5959
from line 61
6161
6262 Note that our models may stop _before_ reaching this maximum. This parameter only specifies the absolute maximum number of tokens to generate.
6363
64 Set to `0` to populate the [prompt cache](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#pre-warming-the-cache) without generating a response.
64 Set to `0` to populate the [prompt cache](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?sdk_languages=http#pre-warming-the-cache) without generating a response.
6565
66 Different models have different maximum values for this parameter. See [models](https://platform.claude.com/docs/en/about-claude/models/overview) for details.
66 Different models have different maximum values for this parameter. See [models](https://platform.claude.com/docs/en/about-claude/models/overview?sdk_languages=http) for details.
6767
6868 minimum: 0
6969
from line 75
7575
7676 Each input message must be an object with a `role` and `content`. You can specify a single `user`-role message, or you can include multiple `user` and `assistant` messages.
7777
78 If the final message uses the `assistant` role, the response content will continue immediately from the content in that message. This can be used to constrain part of the model's response. This is called prefill. On models that don't support prefill, creating a message that ends with a partial `assistant` response returns a 400 error. See [Prefill not supported](https://platform.claude.com/docs/en/api/errors#prefill-not-supported).
78 If the final message uses the `assistant` role, the response content will continue immediately from the content in that message. This can be used to constrain part of the model's response. This is called prefill. On models that don't support prefill, creating a message that ends with a partial `assistant` response returns a 400 error. See [Prefill not supported](https://platform.claude.com/docs/en/api/errors?sdk_languages=http#prefill-not-supported).
7979
8080 Example with a single `user` message:
8181
from line 112
112112 {"role": "user", "content": [{"type": "text", "text": "Hello, Claude"}]}
113113 ```
114114
115 See [input examples](https://platform.claude.com/docs/en/build-with-claude/working-with-messages).
115 See [input examples](https://platform.claude.com/docs/en/build-with-claude/working-with-messages?sdk_languages=http).
116116
117 Note that if you want to include a [system prompt](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#give-claude-a-role), you can use the top-level `system` parameter — there is no `"system"` role for input messages in the Messages API.
117 Note that if you want to include a [system prompt](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices?sdk_languages=http#give-claude-a-role), you can use the top-level `system` parameter — there is no `"system"` role for input messages in the Messages API.
118118
119119 There is a limit of 100,000 messages in a single request.
120120
from line 147
147147 - `5m`: 5 minutes
148148 - `1h`: 1 hour
149149
150 Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) for details.
150 Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?sdk_languages=http) for details.
151151
152152 - `"5m"`
153153
from line 1277
12771277
12781278 - `format: optional JSONOutputFormat or null`
12791279
1280 A schema to specify Claude's output format in responses. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs)
1280 A schema to specify Claude's output format in responses. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs?sdk_languages=http)
12811281
12821282 - `type: "json_schema"`
12831283
from line 1289
12891289
12901290 Determines whether to use priority capacity (if available) or standard capacity for this request.
12911291
1292 Anthropic offers different levels of service for your API requests. See [service-tiers](https://platform.claude.com/docs/en/api/service-tiers) for details.
1292 Anthropic offers different levels of service for your API requests. See [service-tiers](https://platform.claude.com/docs/en/api/service-tiers?sdk_languages=http) for details.
12931293
12941294 - `"auto"`
12951295
from line 1307
13071307
13081308 Whether to incrementally stream the response using server-sent events. When `true`, SDKs return a raw event stream.
13091309
1310 In the TypeScript, Python and Ruby SDKs, the recommended way to stream is `messages.stream()`. It sets `stream` for you and accumulates the events into the final message. See [Streaming with SDKs](https://platform.claude.com/docs/en/build-with-claude/streaming#streaming-with-sdks) for an example in each language.
1310 In the TypeScript, Python and Ruby SDKs, the recommended way to stream is `messages.stream()`. It sets `stream` for you and accumulates the events into the final message. See [Streaming with SDKs](https://platform.claude.com/docs/en/build-with-claude/streaming?sdk_languages=http#streaming-with-sdks) for an example in each language.
13111311
13121312 - `system: optional string or array of TextBlockParam`
13131313
13141314 System prompt.
13151315
1316 A system prompt is a way of providing context and instructions to Claude, such as specifying a particular goal or role. See our [guide to system prompts](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#give-claude-a-role).
1316 A system prompt is a way of providing context and instructions to Claude, such as specifying a particular goal or role. See our [guide to system prompts](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices?sdk_languages=http#give-claude-a-role).
13171317
13181318 - `string`
13191319
from line 1337
13371337
13381338 With `{"type": "adaptive"}`, Claude decides when and how much to think. With `{"type": "enabled"}` (manual extended thinking), you set a `budget_tokens` of at least 1,024. Thinking tokens count toward your `max_tokens` limit.
13391339
1340 Which `type` values are accepted, and what happens when you omit `thinking`, depend on the model. See [thinking](https://platform.claude.com/docs/en/build-with-claude/thinking#configuring-thinking) for each model's behavior.
1340 Which `type` values are accepted, and what happens when you omit `thinking`, depend on the model. See [thinking](https://platform.claude.com/docs/en/build-with-claude/thinking?sdk_languages=http#configuring-thinking) for each model's behavior.
13411341
13421342 - `ThinkingConfigEnabled object`
13431343
from line 1349
13491349
13501350 Must be ≥1024 and less than `max_tokens`.
13511351
1352 See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) for details.
1352 See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking?sdk_languages=http) for details.
13531353
13541354 minimum: 1024
13551355
13561356 - `display: optional "summarized" or "omitted" or null`
13571357
1358 Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. The default depends on the model; see [Controlling thinking display](https://platform.claude.com/docs/en/build-with-claude/thinking#controlling-thinking-display).
1358 Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. The default depends on the model; see [Controlling thinking display](https://platform.claude.com/docs/en/build-with-claude/thinking?sdk_languages=http#controlling-thinking-display).
13591359
13601360 - `"summarized"`
13611361
from line 1375
13751375
13761376 - `display: optional "summarized" or "omitted" or null`
13771377
1378 Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. The default depends on the model; see [Controlling thinking display](https://platform.claude.com/docs/en/build-with-claude/thinking#controlling-thinking-display).
1378 Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. The default depends on the model; see [Controlling thinking display](https://platform.claude.com/docs/en/build-with-claude/thinking?sdk_languages=http#controlling-thinking-display).
13791379
13801380 - `"summarized"`
13811381
from line 1437
14371437
14381438 If you include `tools` in your API request, the model may return `tool_use` content blocks that represent the model's use of those tools. You can then run those tools using the tool input generated by the model and then optionally return results back to the model using `tool_result` content blocks.
14391439
1440 There are two types of tools: **client tools** and **server tools**. The behavior described below applies to client tools. For [server tools](https://platform.claude.com/docs/en/agents-and-tools/tool-use/server-tools), see their individual documentation as each has its own behavior (e.g., the [web search tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool)).
1440 There are two types of tools: **client tools** and **server tools**. The behavior described below applies to client tools. For [server tools](https://platform.claude.com/docs/en/agents-and-tools/tool-use/server-tools?sdk_languages=http), see their individual documentation as each has its own behavior (e.g., the [web search tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool?sdk_languages=http)).
14411441
14421442 Each tool definition includes:
14431443
from line 1493
14931493
14941494 Tools can be used for workflows that include running client-side tools and functions, or more generally whenever you want the model to produce a particular JSON structure of output.
14951495
1496 See our [guide](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview) for more details.
1496 See our [guide](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview?sdk_languages=http) for more details.
14971497
14981498 - `Tool object`
14991499
from line 3272
32723272
32733273This endpoint is idempotent and can be used to poll for Message Batch completion. To access the results of a Message Batch, make a request to the `results_url` field in the response.
32743274
3275Learn more about the Message Batches API in our [user guide](https://platform.claude.com/docs/en/build-with-claude/batch-processing)
3275Learn more about the Message Batches API in our [user guide](https://platform.claude.com/docs/en/build-with-claude/batch-processing?sdk_languages=http)
32763276
32773277### Path parameters
32783278
from line 3286
32863286
32873287 The version of the Claude API you want to use.
32883288
3289 Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning).
3289 Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning?sdk_languages=http).
32903290
32913291- `"anthropic-workspace-id": optional string`
32923292
from line 3441
34413441
34423442List all Message Batches within a Workspace. Most recently created batches are returned first.
34433443
3444Learn more about the Message Batches API in our [user guide](https://platform.claude.com/docs/en/build-with-claude/batch-processing)
3444Learn more about the Message Batches API in our [user guide](https://platform.claude.com/docs/en/build-with-claude/batch-processing?sdk_languages=http)
34453445
34463446### Query parameters
34473447
from line 3467
34673467
34683468 The version of the Claude API you want to use.
34693469
3470 Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning).
3470 Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning?sdk_languages=http).
34713471
34723472- `"anthropic-workspace-id": optional string`
34733473
from line 3643
36433643
36443644The number of canceled requests is specified in `request_counts`. To determine which requests were canceled, check the individual results within the batch. Note that cancellation may not result in any canceled requests if they were non-interruptible.
36453645
3646Learn more about the Message Batches API in our [user guide](https://platform.claude.com/docs/en/build-with-claude/batch-processing)
3646Learn more about the Message Batches API in our [user guide](https://platform.claude.com/docs/en/build-with-claude/batch-processing?sdk_languages=http)
36473647
36483648### Path parameters
36493649
from line 3657
36573657
36583658 The version of the Claude API you want to use.
36593659
3660 Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning).
3660 Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning?sdk_languages=http).
36613661
36623662- `"anthropic-workspace-id": optional string`
36633663
from line 3815
38153815
38163816Message Batches can only be deleted once they've finished processing. If you'd like to delete an in-progress batch, you must first cancel it.
38173817
3818Learn more about the Message Batches API in our [user guide](https://platform.claude.com/docs/en/build-with-claude/batch-processing)
3818Learn more about the Message Batches API in our [user guide](https://platform.claude.com/docs/en/build-with-claude/batch-processing?sdk_languages=http)
38193819
38203820### Path parameters
38213821
from line 3829
38293829
38303830 The version of the Claude API you want to use.
38313831
3832 Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning).
3832 Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning?sdk_languages=http).
38333833
38343834- `"anthropic-workspace-id": optional string`
38353835
from line 3879
38793879
38803880Each line in the file is a JSON object containing the result of a single request in the Message Batch. Results are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests.
38813881
3882Learn more about the Message Batches API in our [user guide](https://platform.claude.com/docs/en/build-with-claude/batch-processing)
3882Learn more about the Message Batches API in our [user guide](https://platform.claude.com/docs/en/build-with-claude/batch-processing?sdk_languages=http)
38833883
38843884### Path parameters
38853885
from line 3893
38933893
38943894 The version of the Claude API you want to use.
38953895
3896 Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning).
3896 Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning?sdk_languages=http).
38973897
38983898- `"anthropic-workspace-id": optional string`
38993899
from line 4164
41644164
41654165 This is an opaque field and should not be interpreted or parsed. When passing thinking blocks back to the API (required when using tools with extended thinking), pass them back exactly as received, with this field intact.
41664166
4167 See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) for details.
4167 See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking?sdk_languages=http) for details.
41684168
41694169 - `thinking: string`
41704170
from line 4182
41824182
41834183 Pass `redacted_thinking` blocks back to the API unchanged when continuing a multi-turn conversation.
41844184
4185 See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#redacted-thinking-blocks) for details.
4185 See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking?sdk_languages=http#redacted-thinking-blocks) for details.
41864186
41874187 - `ToolUseBlock object`
41884188
from line 4884
48844884
48854885 - `"reasoning_extraction"`
48864886
4887 The request asks the model to reproduce its internal reasoning in the response text. To get reasoning in a structured form instead, use [adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/adaptive-thinking).
4887 The request asks the model to reproduce its internal reasoning in the response text. To get reasoning in a structured form instead, use [adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/adaptive-thinking?sdk_languages=http).
48884888
48894889 - `"general_harms"`
48904890
from line 5677
56775677
56785678 This is an opaque field and should not be interpreted or parsed. When passing thinking blocks back to the API (required when using tools with extended thinking), pass them back exactly as received, with this field intact.
56795679
5680 See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) for details.
5680 See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking?sdk_languages=http) for details.
56815681
56825682 - `thinking: string`
56835683
from line 5695
56955695
56965696 Pass `redacted_thinking` blocks back to the API unchanged when continuing a multi-turn conversation.
56975697
5698 See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#redacted-thinking-blocks) for details.
5698 See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking?sdk_languages=http#redacted-thinking-blocks) for details.
56995699
57005700 - `ToolUseBlock object`
57015701
from line 6397
63976397
63986398 - `"reasoning_extraction"`
63996399
6400 The request asks the model to reproduce its internal reasoning in the response text. To get reasoning in a structured form instead, use [adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/adaptive-thinking).
6400 The request asks the model to reproduce its internal reasoning in the response text. To get reasoning in a structured form instead, use [adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/adaptive-thinking?sdk_languages=http).
64016401
64026402 - `"general_harms"`
64036403
from line 6962
69626962
69636963 This is an opaque field and should not be interpreted or parsed. When passing thinking blocks back to the API (required when using tools with extended thinking), pass them back exactly as received, with this field intact.
69646964
6965 See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) for details.
6965 See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking?sdk_languages=http) for details.
69666966
69676967 - `thinking: string`
69686968
from line 6980
69806980
69816981 Pass `redacted_thinking` blocks back to the API unchanged when continuing a multi-turn conversation.
69826982
6983 See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#redacted-thinking-blocks) for details.
6983 See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking?sdk_languages=http#redacted-thinking-blocks) for details.
69846984
69856985 - `ToolUseBlock object`
69866986
from line 7682
76827682
76837683 - `"reasoning_extraction"`
76847684
7685 The request asks the model to reproduce its internal reasoning in the response text. To get reasoning in a structured form instead, use [adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/adaptive-thinking).
7685 The request asks the model to reproduce its internal reasoning in the response text. To get reasoning in a structured form instead, use [adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/adaptive-thinking?sdk_languages=http).
76867686
76877687 - `"general_harms"`
76887688
from line 8199
81998199
82008200 This is an opaque field and should not be interpreted or parsed. When passing thinking blocks back to the API (required when using tools with extended thinking), pass them back exactly as received, with this field intact.
82018201
8202 See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) for details.
8202 See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking?sdk_languages=http) for details.
82038203
82048204 - `thinking: string`
82058205
from line 8217
82178217
82188218 Pass `redacted_thinking` blocks back to the API unchanged when continuing a multi-turn conversation.
82198219
8220 See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#redacted-thinking-blocks) for details.
8220 See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking?sdk_languages=http#redacted-thinking-blocks) for details.
82218221
82228222 - `ToolUseBlock object`
82238223
from line 8645
86458645
86468646 - `start_line: number or null`
86478647
8648 - `total_lines: number or null`
8649
8650 - `TextEditorCodeExecutionCreateResultBlock object`
8651
8652 - `type: "text_editor_code_execution_create_result"`
8653
8654 default: text_editor_code_execution_create_result
8655
8656 - `is_file_update: boolean`
8657
8658 - `TextEditorCodeExecutionStrReplaceResultBlock object`
8659
8660 - `type: "text_editor_code_execution_str_replace_result"`
8661
8662 default: text_editor_code_execution_str_replace_result
8663
8664 - `lines: array of string or null`
8665
8666 - `new_lines: number or null`
8667
8668 - `new_start: number or null`
8669
8670 - `old_lines: number or null`
8671
8672 - `old_start: number or null`
8673
8674 - `tool_use_id: string`
8675
8676 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
8677
8678 - `ToolSearchToolR
8648 - `total_lines: num
No line in this hunk matches that.