Create a Message Batch changedapi/beta/messages/batches/create
Recorded here
Lines+23added
Lines−23removed
From line
11
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits26to this page, all time
The whole hunk
from line 11, old and new numbered
/
from line 11
1111
1212The 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.
1313
14Learn more about the Message Batches API in our [user guide](https://platform.claude.com/docs/en/build-with-claude/batch-processing)
14Learn more about the Message Batches API in our [user guide](https://platform.claude.com/docs/en/build-with-claude/batch-processing?sdk_languages=http)
1515
1616## Headers
1717
from line 19
1919
2020 The version of the Claude API you want to use.
2121
22 Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning).
22 Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning?sdk_languages=http).
2323
2424- `"anthropic-beta": optional array of AnthropicBeta`
2525
from line 157
157157
158158 Messages API creation parameters for the individual request.
159159
160 See the [Messages API reference](https://platform.claude.com/docs/en/api/messages) for full documentation on available parameters.
160 See the [Messages API reference](https://platform.claude.com/docs/en/api/messages?sdk_languages=http) for full documentation on available parameters.
161161
162162 - `max_tokens: number`
163163
from line 165
165165
166166 Note that our models may stop _before_ reaching this maximum. This parameter only specifies the absolute maximum number of tokens to generate.
167167
168 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.
168 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.
169169
170 Different models have different maximum values for this parameter. See [models](https://platform.claude.com/docs/en/about-claude/models/overview) for details.
170 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.
171171
172172 minimum: 0
173173
from line 179
179179
180180 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.
181181
182 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).
182 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).
183183
184184 Example with a single `user` message:
185185
from line 216
216216 {"role": "user", "content": [{"type": "text", "text": "Hello, Claude"}]}
217217 ```
218218
219 See [input examples](https://platform.claude.com/docs/en/build-with-claude/working-with-messages).
219 See [input examples](https://platform.claude.com/docs/en/build-with-claude/working-with-messages?sdk_languages=http).
220220
221 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.
221 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.
222222
223223 There is a limit of 100,000 messages in a single request.
224224
from line 251
251251 - `5m`: 5 minutes
252252 - `1h`: 1 hour
253253
254 Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) for details.
254 Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching?sdk_languages=http) for details.
255255
256256 - `"5m"`
257257
from line 3780
37803780
37813781 - `fallbacks: optional BetaFallbacksParam or null`
37823782
3783 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.
3783 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.
37843784
37853785 - `array of BetaFallbackParam`
37863786
from line 3812
38123812
38133813 - `format: optional BetaJSONOutputFormat or null`
38143814
3815 A schema to specify Claude's output format in responses. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs)
3815 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)
38163816
38173817 - `type: "json_schema"`
38183818
from line 3860
38603860
38613861 Must be ≥1024 and less than `max_tokens`.
38623862
3863 See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) for details.
3863 See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking?sdk_languages=http) for details.
38643864
38653865 minimum: 1024
38663866
from line 3878
38783878
38793879 - `display: optional "summarized" or "omitted" or "updates" or null`
38803880
3881 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).
3881 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).
38823882
38833883 - `"summarized"`
38843884
from line 3904
39043904
39053905 - `display: optional "summarized" or "omitted" or "updates" or null`
39063906
3907 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).
3907 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).
39083908
39093909 - `"summarized"`
39103910
from line 3958
39583958
39593959 Determines whether to use priority capacity (if available) or standard capacity for this request.
39603960
3961 Anthropic offers different levels of service for your API requests. See [service-tiers](https://platform.claude.com/docs/en/api/service-tiers) for details.
3961 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.
39623962
39633963 - `"auto"`
39643964
from line 3984
39843984
39853985 Whether to incrementally stream the response using server-sent events. When `true`, SDKs return a raw event stream.
39863986
3987 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.
3987 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.
39883988
39893989 - `system: optional string or array of BetaTextBlockParam`
39903990
39913991 System prompt.
39923992
3993 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).
3993 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).
39943994
39953995 - `string`
39963996
from line 4014
40144014
40154015 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.
40164016
4017 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.
4017 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.
40184018
40194019 - `BetaThinkingConfigEnabled object`
40204020
from line 4080
40804080
40814081 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.
40824082
4083 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)).
4083 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)).
40844084
40854085 Each tool definition includes:
40864086
from line 4136
41364136
41374137 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.
41384138
4139 See our [guide](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview) for more details.
4139 See our [guide](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview?sdk_languages=http) for more details.
41404140
41414141 - `BetaTool object`
41424142
from line 4223
42234223
42244224 **Deprecated**
42254225
4226 Deprecated: Use `output_config.format` instead. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs)
4226 Deprecated: Use `output_config.format` instead. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs?sdk_languages=http)
42274227
42284228 A schema to specify Claude's output format in responses. This parameter will be removed in a future release.
42294229
No line in this hunk matches that.