Batches changedapi/beta/messages/batches
Recorded here
Lines+51added
Lines−51removed
From line
13
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits29to 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-beta": optional array of AnthropicBeta`
2727
from line 159
159159
160160 Messages API creation parameters for the individual request.
161161
162 See the [Messages API reference](https://platform.claude.com/docs/en/api/messages) for full documentation on available parameters.
162 See the [Messages API reference](https://platform.claude.com/docs/en/api/messages?sdk_languages=http) for full documentation on available parameters.
163163
164164 - `max_tokens: number`
165165
from line 167
167167
168168 Note that our models may stop _before_ reaching this maximum. This parameter only specifies the absolute maximum number of tokens to generate.
169169
170 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.
170 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.
171171
172 Different models have different maximum values for this parameter. See [models](https://platform.claude.com/docs/en/about-claude/models/overview) for details.
172 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.
173173
174174 minimum: 0
175175
from line 181
181181
182182 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.
183183
184 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).
184 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).
185185
186186 Example with a single `user` message:
187187
from line 218
218218 {"role": "user", "content": [{"type": "text", "text": "Hello, Claude"}]}
219219 ```
220220
221 See [input examples](https://platform.claude.com/docs/en/build-with-claude/working-with-messages).
221 See [input examples](https://platform.claude.com/docs/en/build-with-claude/working-with-messages?sdk_languages=http).
222222
223 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.
223 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.
224224
225225 There is a limit of 100,000 messages in a single request.
226226
from line 253
253253 - `5m`: 5 minutes
254254 - `1h`: 1 hour
255255
256 Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) for details.
256 Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?sdk_languages=http) for details.
257257
258258 - `"5m"`
259259
from line 3782
37823782
37833783 - `fallbacks: optional BetaFallbacksParam or null`
37843784
3785 Opt-in server-side retry on one or more substitute models when the requested model declines for policy reasons. Tried in order: if the first entry also declines, the second is tried, and so on. Some models don't support fallbacks; on those models, a list of fallback models returns a 400 error. See [Server-side fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#server-side-fallback). The string "default" requests the requested model's server-defined default fallback configuration. On a model that doesn't support fallbacks, the request runs on the requested model alone, so a declined request stays declined.
3785 Opt-in server-side retry on one or more substitute models when the requested model declines for policy reasons. Tried in order: if the first entry also declines, the second is tried, and so on. Some models don't support fallbacks; on those models, a list of fallback models returns a 400 error. See [Server-side fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback?sdk_languages=http#server-side-fallback). The string "default" requests the requested model's server-defined default fallback configuration. On a model that doesn't support fallbacks, the request runs on the requested model alone, so a declined request stays declined.
37863786
37873787 - `array of BetaFallbackParam`
37883788
from line 3814
38143814
38153815 - `format: optional BetaJSONOutputFormat or null`
38163816
3817 A schema to specify Claude's output format in responses. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs)
3817 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)
38183818
38193819 - `type: "json_schema"`
38203820
from line 3862
38623862
38633863 Must be ≥1024 and less than `max_tokens`.
38643864
3865 See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) for details.
3865 See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking?sdk_languages=http) for details.
38663866
38673867 minimum: 1024
38683868
from line 3880
38803880
38813881 - `display: optional "summarized" or "omitted" or "updates" or null`
38823882
3883 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).
3883 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).
38843884
38853885 - `"summarized"`
38863886
from line 3906
39063906
39073907 - `display: optional "summarized" or "omitted" or "updates" or null`
39083908
3909 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).
3909 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).
39103910
39113911 - `"summarized"`
39123912
from line 3960
39603960
39613961 Determines whether to use priority capacity (if available) or standard capacity for this request.
39623962
3963 Anthropic offers different levels of service for your API requests. See [service-tiers](https://platform.claude.com/docs/en/api/service-tiers) for details.
3963 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.
39643964
39653965 - `"auto"`
39663966
from line 3986
39863986
39873987 Whether to incrementally stream the response using server-sent events. When `true`, SDKs return a raw event stream.
39883988
3989 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.
3989 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.
39903990
39913991 - `system: optional string or array of BetaTextBlockParam`
39923992
39933993 System prompt.
39943994
3995 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).
3995 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).
39963996
39973997 - `string`
39983998
from line 4016
40164016
40174017 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.
40184018
4019 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.
4019 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.
40204020
40214021 - `BetaThinkingConfigEnabled object`
40224022
from line 4082
40824082
40834083 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.
40844084
4085 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)).
4085 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)).
40864086
40874087 Each tool definition includes:
40884088
from line 4138
41384138
41394139 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.
41404140
4141 See our [guide](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview) for more details.
4141 See our [guide](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview?sdk_languages=http) for more details.
41424142
41434143 - `BetaTool object`
41444144
from line 4225
42254225
42264226 **Deprecated**
42274227
4228 Deprecated: Use `output_config.format` instead. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs)
4228 Deprecated: Use `output_config.format` instead. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs?sdk_languages=http)
42294229
42304230 A schema to specify Claude's output format in responses. This parameter will be removed in a future release.
42314231
from line 4431
44314431
44324432This 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.
44334433
4434Learn more about the Message Batches API in our [user guide](https://platform.claude.com/docs/en/build-with-claude/batch-processing)
4434Learn more about the Message Batches API in our [user guide](https://platform.claude.com/docs/en/build-with-claude/batch-processing?sdk_languages=http)
44354435
44364436### Path parameters
44374437
from line 4445
44454445
44464446 The version of the Claude API you want to use.
44474447
4448 Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning).
4448 Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning?sdk_languages=http).
44494449
44504450- `"anthropic-beta": optional array of AnthropicBeta`
44514451
from line 4707
47074707
47084708List all Message Batches within a Workspace. Most recently created batches are returned first.
47094709
4710Learn more about the Message Batches API in our [user guide](https://platform.claude.com/docs/en/build-with-claude/batch-processing)
4710Learn more about the Message Batches API in our [user guide](https://platform.claude.com/docs/en/build-with-claude/batch-processing?sdk_languages=http)
47114711
47124712### Query parameters
47134713
from line 4733
47334733
47344734 The version of the Claude API you want to use.
47354735
4736 Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning).
4736 Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning?sdk_languages=http).
47374737
47384738- `"anthropic-beta": optional array of AnthropicBeta`
47394739
from line 5016
50165016
50175017The 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.
50185018
5019Learn more about the Message Batches API in our [user guide](https://platform.claude.com/docs/en/build-with-claude/batch-processing)
5019Learn more about the Message Batches API in our [user guide](https://platform.claude.com/docs/en/build-with-claude/batch-processing?sdk_languages=http)
50205020
50215021### Path parameters
50225022
from line 5030
50305030
50315031 The version of the Claude API you want to use.
50325032
5033 Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning).
5033 Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning?sdk_languages=http).
50345034
50355035- `"anthropic-beta": optional array of AnthropicBeta`
50365036
from line 5295
52955295
52965296Message 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.
52975297
5298Learn more about the Message Batches API in our [user guide](https://platform.claude.com/docs/en/build-with-claude/batch-processing)
5298Learn more about the Message Batches API in our [user guide](https://platform.claude.com/docs/en/build-with-claude/batch-processing?sdk_languages=http)
52995299
53005300### Path parameters
53015301
from line 5309
53095309
53105310 The version of the Claude API you want to use.
53115311
5312 Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning).
5312 Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning?sdk_languages=http).
53135313
53145314- `"anthropic-beta": optional array of AnthropicBeta`
53155315
from line 5466
54665466
54675467Each 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.
54685468
5469Learn more about the Message Batches API in our [user guide](https://platform.claude.com/docs/en/build-with-claude/batch-processing)
5469Learn more about the Message Batches API in our [user guide](https://platform.claude.com/docs/en/build-with-claude/batch-processing?sdk_languages=http)
54705470
54715471### Path parameters
54725472
from line 5480
54805480
54815481 The version of the Claude API you want to use.
54825482
5483 Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning).
5483 Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning?sdk_languages=http).
54845484
54855485- `"anthropic-beta": optional array of AnthropicBeta`
54865486
from line 5857
58575857
58585858 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.
58595859
5860 See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) for details.
5860 See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking?sdk_languages=http) for details.
58615861
58625862 - `thinking: string`
58635863
from line 5875
58755875
58765876 Pass `redacted_thinking` blocks back to the API unchanged when continuing a multi-turn conversation.
58775877
5878 See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#redacted-thinking-blocks) for details.
5878 See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking?sdk_languages=http#redacted-thinking-blocks) for details.
58795879
58805880 - `BetaToolUseBlock object`
58815881
from line 6681
66816681 - `5m`: 5 minutes
66826682 - `1h`: 1 hour
66836683
6684 Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) for details.
6684 Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?sdk_languages=http) for details.
66856685
66866686 - `"5m"`
66876687
from line 7322
73227322
73237323 - `"code_execution_20260120"`
73247324
7325 - `"code_execution_20260521"`
7326
7327 - `cache_control: optional BetaCacheControlEphemeral or null`
7328
7329 Create a cache control breakpoint at this content block.
7330
7331 - `defer_loading: optional boolean`
7332
7333 If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.
7334
7335 - `input_examples: optional array of map[unknown]`
7336
7337 - `strict: optional boolean`
7338
7339 When true, guarantees schema validation on tool names and inputs
7340
7341 - `BetaToolComputerUse20
7325 - `"code_executio
No line in this hunk matches that.