Messages
api/beta/messages
History
api/beta/messages Changed · +206 / -44 lines
This page is larger than the 256 KiB this site keeps, so one side of the diff below stops where the stored text does.
- `string` - - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 31 more` + - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 38 more` - `"message-batches-2024-09-24"`
- `"mid-conversation-tool-changes-2026-07-01"` + - `"compact-2026-01-12"` + + - `"computer-use-2025-11-24"` + + - `"mcp-tunnels-2026-06-22"` + + - `"structured-outputs-2025-11-13"` + + - `"task-budgets-2026-03-13"` + + - `"thinking-display-updates-2026-08-18"` + + - `"ce-user-management-2026-07-13"` + - `"anthropic-user-profile-id": optional string` The user profile ID to attribute this request to. Use when acting on behalf of a party other than your organization. Requires the `user-profiles` beta header.
- `type: "enabled"` - - `display: optional "summarized" or "omitted" or null` + - `display: optional "summarized" or "omitted" or "updates" or null` 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. Defaults to `summarized`.
- `"omitted"` + - `"updates"` + - `BetaThinkingConfigDisabled object` - `type: "disabled"`
- `type: "adaptive"` - - `display: optional "summarized" or "omitted" or null` + - `display: optional "summarized" or "omitted" or "updates" or null` 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. Defaults to `summarized`.
- `"omitted"` + - `"updates"` + - `Default = "default"` - `inference_geo: optional string or null`
Per-iteration token usage breakdown. - Each entry represents one sampling iteration, with its own input/output token counts and cache statistics. This allows you to: + Each entry represents one sampling iteration, with its own input/output token counts and cache statistics, discriminated by `type`. For `message` entries (model sampling iterations, such as the turns of a server-side tool use loop), this allows you to: - Determine which iterations exceeded long context thresholds (>=200k tokens) - - Calculate the true context window size from the last iteration + - Calculate the context window size from the last `message` entry - Understand token accumulation across server-side tool use loops + A `compaction` entry reports the token usage of the compaction operation itself — the server-side request that summarizes the context being closed — NOT the size of the context that was compacted away, and its token counts can be much smaller than that closed context (for example, a compaction that closes a ~200k-token context can report only a few thousand tokens). Do not derive the context window size from a `compaction` entry, even when it is the last entry. A `compaction` entry's tokens are not included in the top-level `usage` fields. When an input-token trigger is in effect (the default — 150,000 tokens unless configured otherwise), each `compaction` entry closes a context that had reached at least that threshold, though the context can exceed it by the final iteration's output and tool results. + - `BetaMessageIterationUsage object` Token usage for a sampling iteration.
Per-iteration token usage breakdown. - Each entry represents one sampling iteration, with its own input/output token counts and cache statistics. This allows you to: + Each entry represents one sampling iteration, with its own input/output token counts and cache statistics, discriminated by `type`. For `message` entries (model sampling iterations, such as the turns of a server-side tool use loop), this allows you to: - Determine which iterations exceeded long context thresholds (>=200k tokens) - - Calculate the true context window size from the last iteration + - Calculate the context window size from the last `message` entry - Understand token accumulation across server-side tool use loops + A `compaction` entry reports the token usage of the compaction operation itself — the server-side request that summarizes the context being closed — NOT the size of the context that was compacted away, and its token counts can be much smaller than that closed context (for example, a compaction that closes a ~200k-token context can report only a few thousand tokens). Do not derive the context window size from a `compaction` entry, even when it is the last entry. A `compaction` entry's tokens are not included in the top-level `usage` fields. When an input-token trigger is in effect (the default — 150,000 tokens unless configured otherwise), each `compaction` entry closes a context that had reached at least that threshold, though the context can exceed it by the final iteration's output and tool results. + - `output_tokens: number` The cumulative number of output tokens which were used.
- `string` - - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 31 more` + - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 38 more` - `"message-batches-2024-09-24"`
- `"mid-conversation-tool-changes-2026-07-01"` + - `"compact-2026-01-12"` + + - `"computer-use-2025-11-24"` + + - `"mcp-tunnels-2026-06-22"` + + - `"structured-outputs-2025-11-13"` + + - `"task-budgets-2026-03-13"` + + - `"thinking-display-updates-2026-08-18"` + + - `"ce-user-management-2026-07-13"` + - `"anthropic-user-profile-id": optional string` The user profile ID to attribute this request to. Use when acting on behalf of a party other than your organization. Requires the `user-profiles` beta header.
- `type: "enabled"` - - `display: optional "summarized" or "omitted" or null` + - `display: optional "summarized" or "omitted" or "updates" or null` 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. Defaults to `summarized`.
- `"omitted"` + - `"updates"` + - `BetaThinkingConfigDisabled object` - `type: "disabled"`
- `type: "adaptive"` - - `display: optional "summarized" or "omitted" or null` + - `display: optional "summarized" or "omitted" or "updates" or null` 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. Defaults to `summarized`.
- `"omitted"` + - `"updates"` + - `tool_choice: optional BetaToolChoice` How the model should use the provided tools. The model can use a specific tool, any available tool, decide by itself, or not use tools at all.
- `enabled: optional boolean or null` - Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - - - `screenshot: optional BetaBrowserScreenshotConfig or null` - - `screenshot`'s config overrides. - - - `defer_loading: optional boolean or null` - - Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - - - `enabled: optional boolean or null` - - Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - - - `scroll: optional BetaBrowserScrollConfig or null` - - `scroll`'s config overrides. - - - `defer_loading: optional boolean or null` - - Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - - - `enabled: optional boolean or null` - - Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - - - `scroll_to: optional BetaBrowserScrollToConfig or null` - - `scroll_to`'s config overrides. - - - `defer_loading: optional boolean or null` - - Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - - - `enabled: optional boolean or null` - - Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - - - `switch_tab: optional BetaBrowserSwitchTabConfig or null` - - `switch_tab`'s config overrides. - - - `defer_loading: optional boolean or null` - - Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - - - `enabled: optional boolean or null` - - Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema. - - - `triple_click: optional BetaBrowserTripleClickConfig or null` - - `triple_click`'s config overrides. - - - `defer_loading: optional boolean or null` - - Defer loading for this member. Must resolve to the same value on every enabled member of the toolset. - - - `enabled: optional boolean or null` - - Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enab + Whether this member is offered to the model. Default is per member, per the
api/beta/messages Changed · +6222 / -10384 lines
### Headers ### Body parameters #### Response (200) ### Headers ### Body parameters #### Response (200) ## Domain types ## Messages › Batches ### Create a Message Batch #### Headers #### Body parameters #### Returns #### Example ##### Response (200) ### Retrieve a Message Batch #### Path parameters #### Headers #### Returns #### Example ##### Response (200) ### List Message Batches #### Query parameters #### Headers #### Returns #### Example ##### Response (200) ### Cancel a Message Batch #### Path parameters #### Headers #### Returns #### Example ##### Response (200) ### Delete a Message Batch #### Path parameters #### Headers #### Returns #### Example ##### Response (200) ### Retrieve Message Batch results #### Path parameters #### Headers #### Returns #### Example ### Header Parameters ### Body Parameters #### Response ### Header Parameters ### Body Parameters #### Response ## Domain Types # Batches ## Create a Message Batch ### Header Parameters ### Body Parameters #### Response ## Retrieve a Message Batch ### Path Parameters ### Header Parameters #### Response ## List Message Batches ### Query Parameters ### Header Parameters #### Response ## Cancel a Message Batch ### Path Parameters ### Header Parameters #### Response ## Delete a Message Batch ### Path Parameters ### Header Parameters #### Response ## Retrieve Message Batch results ### Path Parameters ### Header Parameters ## Domain Types ### Beta Deleted Message Batch ### Beta Message Batch ### Beta Message Batch Canceled Result ### Beta Message Batch Errored Result ### Beta Message Batch Expired Result ### Beta Message Batch Individual Response ### Beta Message Batch Request Counts ### Beta Message Batch Result ### Beta Message Batch Succeeded Result
This page is larger than the 256 KiB this site keeps, so one side of the diff below stops where the stored text does.
api/beta/messages Changed · +11 / -11 lines
This page is larger than the 256 KiB this site keeps, so one side of the diff below stops where the stored text does.
- `version: string` - Skill version or 'latest' for most recent version + The resolved version: a skill version ID for custom skills. - `content: array of BetaContentBlock`
- `enabled: optional boolean or null` - Whether this member is offered to the model. Default is per member, per the toolset's documentation. + Whether this member is offered to the model. Default is per member, per the toolset's docu
api/beta/messages Changed · +6396 / -926 lines
### Beta Browser Close Tab Config ### Beta Browser Double Click Config ### Beta Browser File Upload Config ### Beta Browser Find Config ### Beta Browser Form Input Config ### Beta Browser Get Page Text Config ### Beta Browser Hold Key Config ### Beta Browser Hover Config ### Beta Browser Javascript Exec Config ### Beta Browser Key Config ### Beta Browser Left Click Config ### Beta Browser Left Click Drag Config ### Beta Browser Left Mouse Down Config ### Beta Browser Left Mouse Up Config ### Beta Browser List Tabs Config ### Beta Browser Middle Click Config ### Beta Browser Mouse Move Config ### Beta Browser Navigate Config ### Beta Browser New Tab Config ### Beta Browser Read Console Config ### Beta Browser Read Network Config ### Beta Browser Read Page Config ### Beta Browser Right Click Config ### Beta Browser Screenshot Config ### Beta Browser Scroll Config ### Beta Browser Scroll To Config ### Beta Browser State Block Param ### Beta Browser State Change ### Beta Browser State Change Download Completed ### Beta Browser State Change Download Failed ### Beta Browser State Change Download Started ### Beta Browser State Change Tab Opened ### Beta Browser State Tab Entry ### Beta Browser Switch Tab Config ### Beta Browser Toolset 20260801 ### Beta Browser Toolset Configs ### Beta Browser Triple Click Config ### Beta Browser Type Config ### Beta Browser Wait Config ### Beta Browser Zoom Config ### Beta Computer Cursor Position Config ### Beta Computer Double Click Config ### Beta Computer Hold Key Config ### Beta Computer Key Config ### Beta Computer Left Click Config ### Beta Computer Left Click Drag Config ### Beta Computer Left Mouse Down Config ### Beta Computer Left Mouse Up Config ### Beta Computer Middle Click Config ### Beta Computer Mouse Move Config ### Beta Computer Right Click Config ### Beta Computer Screenshot Config ### Beta Computer Scroll Config ### Beta Computer Toolset 20260801 ### Beta Computer Toolset Configs ### Beta Computer Triple Click Config ### Beta Computer Type Config ### Beta Computer Wait Config ### Beta Computer Zoom Config ### Beta Image Transformations Param ### Beta Mid Conversation System Block Param
This page is larger than the 256 KiB this site keeps, so one side of the diff below stops where the stored text does.
api/beta/messages First recorded · 42254 lines, first recorded
# Messages ## Create a Message ### Header Parameters ### Body Parameters ### Returns ### Example #### Response ## Count tokens in a Message ### Header Parameters ### Body Parameters ### Returns ### Example #### Response ## Domain Types ### Beta Advisor Message Iteration Usage ### Beta Advisor Redacted Result Block ### Beta Advisor Redacted Result Block Param ### Beta Advisor Result Block ### Beta Advisor Result Block Param ### Beta Advisor Tool 20260301 ### Beta Advisor Tool Result Block ### Beta Advisor Tool Result Block Param ### Beta Advisor Tool Result Error ### Beta Advisor Tool Result Error Param ### Beta All Thinking Turns ### Beta Base64 Image Source ### Beta Base64 PDF Source ### Beta Bash Code Execution Output Block ### Beta Bash Code Execution Output Block Param ### Beta Bash Code Execution Result Block ### Beta Bash Code Execution Result Block Param ### Beta Bash Code Execution Tool Result Block ### Beta Bash Code Execution Tool Result Block Param ### Beta Bash Code Execution Tool Result Error ### Beta Bash Code Execution Tool Result Error Param ### Beta Cache Control Ephemeral ### Beta Cache Creation ### Beta Cache Miss Messages Changed ### Beta Cache Miss Model Changed ### Beta Cache Miss Previous Message Not Found ### Beta Cache Miss System Changed ### Beta Cache Miss Tools Changed ### Beta Cache Miss Unavailable ### Beta Citation Char Location ### Beta Citation Char Location Param ### Beta Citation Config ### Beta Citation Content Block Location ### Beta Citation Content Block Location Param ### Beta Citation Page Location ### Beta Citation Page Location Param ### Beta Citation Search Result Location ### Beta Citation Search Result Location Param ### Beta Citation Web Search Result Location Param ### Beta Citations Config Param ### Beta Citations Delta ### Beta Citations Web Search Result Location ### Beta Clear Thinking 20251015 Edit ### Beta Clear Thinking 20251015 Edit Response ### Beta Clear Tool Uses 20250919 Edit ### Beta Clear Tool Uses 20250919 Edit Response ### Beta Code Execution Output Block ### Beta Code Execution Output Block Param ### Beta Code Execution Result Block ### Beta Code Execution Result Block Param ### Beta Code Execution Tool 20250522 ### Beta Code Execution Tool 20250825 ### Beta Code Execution Tool 20260120 ### Beta Code Execution Tool 20260521 ### Beta Code Execution Tool Result Block ### Beta Code Execution Tool Result Block Content ### Beta Code Execution Tool Result Block Param ### Beta Code Execution Tool Result Block Param Content ### Beta Code Execution Tool Result Error ### Beta Code Execution Tool Result Error Code ### Beta Code Execution Tool Result Error Param ### Beta Compact 20260112 Edit ### Beta Compaction Block ### Beta Compaction Block Param ### Beta Compaction Content Block Delta ### Beta Compaction Iteration Usage ### Beta Container ### Beta Container Params ### Beta Container Upload Block ### Beta Container Upload Block Param ### Beta Content Block ### Beta Content Block Param ### Beta Content Block Source ### Beta Content Block Source Content ### Beta Context Management Config ### Beta Context Management Response ### Beta Count Tokens Context Management Response ### Beta Diagnostics ### Beta Diagnostics Param ### Beta Direct Caller ### Beta Document Block ### Beta Encrypted Code Execution Result Block ### Beta Encrypted Code Execution Result Block Param ### Beta Fallback Block ### Beta Fallback Block Param ### Beta Fallback Credit Not Applied ### Beta Fallback Credit Redeemed ### Beta Fallback Credit Token Param ### Beta Fallback Credit Usage ### Beta Fallback Info ### Beta Fallback Info Param ### Beta Fallback Message Iteration Usage ### Beta Fallback Param ### Beta Fallback Refusal Trigger ### Beta Fallbacks Param ### Beta File Document Source ### Beta File Image Source ### Beta Image Block Param ### Beta Input JSON Delta ### Beta Input Tokens Clear At Least ### Beta Input Tokens Trigger ### Beta Iterations Usage ### Beta JSON Output Format ### Beta MCP Tool Config ### Beta MCP Tool Default Config ### Beta MCP Tool Result Block ### Beta MCP Tool Use Block ### Beta MCP Tool Use Block Param ### Beta MCP Toolset ### Beta Memory Tool 20250818 ### Beta Memory Tool 20250818 Command ### Beta Memory Tool 20250818 Create Command ### Beta Memory Tool 20250818 Delete Command ### Beta Memory Tool 20250818 Insert Command ### Beta Memory Tool 20250818 Rename Command ### Beta Memory Tool 20250818 Str Replace Command ### Beta Memory Tool 20250818 View Command ### Beta Message ### Beta Message Delta Usage ### Beta Message Iteration Usage ### Beta Message Param ### Beta Message Tokens Count ### Beta Metadata ### Beta Mid Conversation System Block Param ### Beta Output Config ### Beta Output Tokens Details ### Beta Plain Text Source ### Beta Raw Content Block Delta ### Beta Raw Content Block Delta Event ### Beta Raw Content Block Start Event ### Beta Raw Content Block Stop Event ### Beta Raw Message Delta Event ### Beta Raw Message Start Event ### Beta Raw Message Stop Event ### Beta Raw Message Stream Event ### Beta Redacted Thinking Block ### Beta Redacted Thinking Block Param ### Beta Refusal Stop Details ### Beta Request Document Block ### Beta Request MCP Server Tool Configuration ### Beta Request MCP Server URL Definition ### Beta Request MCP Tool Result Block Param ### Beta Request Tool Addition Block ### Beta Request Tool Removal Block ### Beta Search Result Block Param ### Beta Server Tool Caller ### Beta Server Tool Caller 20260120 ### Beta Server Tool Usage ### Beta Server Tool Use Block ### Beta Server Tool Use Block Param ### Beta Signature Delta ### Beta Skill ### Beta Skill Params ### Beta Stop Reason ### Beta Text Block ### Beta Text Block Param ### Beta Text Citation ### Beta Text Citation Param ### Beta Text Delta ### Beta Text Editor Code Execution Create Result Block ### Beta Text Editor Code Execution Create Result Block Param ### Beta Text Editor Code Execution Str Replace Result Block ### Beta Text Editor Code Execution Str Replace Result Block Param ### Beta Text Editor Code Execution Tool Result Block ### Beta Text Editor Code Execution Tool Result Block Param ### Beta Text Editor Code Execution Tool Result Error ### Beta Text Editor Code Execution Tool Result Error Param ### Beta Text Editor Code Execution View Result Block ### Beta Text Editor Code Execution View Result Block Param ### Beta Thinking Block ### Beta Thinking Block Param ### Beta Thinking Config Adaptive ### Beta Thinking Config Disabled ### Beta Thinking Config Enabled ### Beta Thinking Config Param ### Beta Thinking Delta ### Beta Thinking Turns ### Beta Token Task Budget ### Beta Tool ### Beta Tool Bash 20241022 ### Beta Tool Bash 20250124 ### Beta Tool Change MCP Tool Reference ### Beta Tool Change MCP Toolset Reference ### Beta Tool Change Tool Reference ### Beta Tool Choice ### Beta Tool Choice Any ### Beta Tool Choice Auto ### Beta Tool Choice None ### Beta Tool Choice Tool ### Beta Tool Computer Use 20241022 ### Beta Tool Computer Use 20250124 ### Beta Tool Computer Use 20251124 ### Beta Tool Reference Block ### Beta Tool Reference Block Param ### Beta Tool Result Block Param ### Beta Tool Search Tool Bm25 20251119 ### Beta Tool Search Tool Regex 20251119 ### Beta Tool Search Tool Result Block ### Beta Tool Search Tool Result Block Param ### Beta Tool Search Tool Result Error ### Beta Tool Search Tool Result Error Param ### Beta Tool Search Tool Search Result Block ### Beta Tool Search Tool Search Result Block Param ### Beta Tool Text Editor 20241022 ### Beta Tool Text Editor 20250124 ### Beta Tool Text Editor 20250429 ### Beta Tool Text Editor 20250728 ### Beta Tool Union ### Beta Tool Use Block ### Beta Tool Use Block Param ### Beta Tool Uses Keep ### Beta Tool Uses Trigger ### Beta URL Image Source ### Beta URL PDF Source ### Beta Usage ### Beta User Location ### Beta Web Fetch Block ### Beta Web Fetch Block Param ### Beta Web Fetch Tool 20250910 ### Beta Web Fetch Tool 20260209 ### Beta Web Fetch Tool 20260309 ### Beta Web Fetch Tool 20260318 ### Beta Web Fetch Tool Result Block ### Beta Web Fetch Tool Result Block Param ### Beta Web Fetch Tool Result Error Block ### Beta Web Fetch Tool Result Error Block Param ### Beta Web Fetch Tool Result Error Code ### Beta Web Search Result Block ### Beta Web Search Result Block Param ### Beta Web Search Tool 20250305 ### Beta Web Search Tool 20260209 ### Beta Web Search Tool 20260318 ### Beta Web Search Tool Request Error ### Beta Web Search Tool Result Block ### Beta Web Search Tool Result Block Content ### Beta Web Search Tool Result Block Param ### Beta Web Search Tool Result Block Param Content ### Beta Web Search Tool Result Error ### Beta Web Search Tool Result Error Code # Batches ## Create a Message Batch ### Header Parameters ### Body Parameters ### Returns ### Example #### Response ## Retrieve a Message Batch ### Path Parameters ### Header Parameters ### Returns ### Example #### Response ## List Message Batches ### Query Parameters ### Header Parameters ### Returns ### Example #### Response ## Cancel a Message Batch ### Path Parameters ### Header Parameters ### Returns ### Example #### Response ## Delete a Message Batch ### Path Parameters ### Header Parameters ### Returns ### Example #### Response ## Retrieve Message Batch results ### Path Parameters ### Header Parameters ### Returns ### Example ## Domain Types ### Beta Deleted Message Batch ### Beta Message Batch ### Beta Message Batch Canceled Result ### Beta Message Batch Errored Result ### Beta Message Batch Expired Result ### Beta Message Batch Individual Response ### Beta Message Batch Request Counts ### Beta Message Batch Result ### Beta Message Batch Succeeded Result
This page is larger than the 256 KiB this site keeps, so one side of the diff below stops where the stored text does.
The first capture of this source. The page was already there, and this is what it said.
---
title: Messages
url: https://platform.claude.com/docs/en/api/beta/messages
---
# Messages
## Create a Message
**post** `/v1/messages`
Send a structured list of input messages with text and/or image content, and the model will generate the next message in the conversation.
The Messages API can be used for either single queries or stateless multi-turn conversations.
Learn more about the Messages API in our [user guide](https://platform.claude.com/docs/en/get-started)
### Header Parameters
- `"anthropic-beta": optional array of AnthropicBeta`
Optional header to specify the beta version(s) you want to use.
- `string`
- `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 30 more`
- `"message-batches-2024-09-24"`
- `"prompt-caching-2024-07-31"`
- `"computer-use-2024-10-22"`
- `"computer-use-2025-01-24"`
- `"pdfs-2024-09-25"`
- `"token-counting-2024-11-01"`
- `"token-efficient-tools-2025-02-19"`
- `"output-128k-2025-02-19"`
- `"files-api-2025-04-14"`
- `"mcp-client-2025-04-04"`
- `"mcp-client-2025-11-20"`
- `"dev-full-thinking-2025-05-14"`
- `"interleaved-thinking-2025-05-14"`
- `"code-execution-2025-05-22"`
- `"extended-cache-ttl-2025-04-11"`
- `"context-1m-2025-08-07"`
- `"context-management-2025-06-27"`
- `"model-context-window-exceeded-2025-08-26"`
- `"skills-2025-10-02"`
- `"fast-mode-2026-02-01"`
- `"output-300k-2026-03-24"`
- `"user-profiles-2026-03-24"`
- `"advisor-tool-2026-03-01"`
- `"managed-agents-2026-04-01"`
- `"cache-diagnosis-2026-04-07"`
- `"dreaming-2026-04-21"`
- `"thinking-token-count-2026-05-13"`
- `"server-side-fallback-2026-06-01"`
- `"server-side-fallback-2026-07-01"`
- `"fallback-credit-2026-06-01"`
- `"fallback-credit-2026-07-01"`
- `"agent-memory-2026-07-22"`
- `"mid-conversation-tool-changes-2026-07-01"`
- `"anthropic-user-profile-id": optional string`
The user profile ID to attribute this request to. Use when acting on behalf of a party other than your organization. Requires the `user-profiles` beta header.
### Body Parameters
- `max_tokens: number`
The maximum number of tokens to generate before stopping.
Note that our models may stop _before_ reaching this maximum. This parameter only specifies the absolute maximum number of tokens to generate.
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.
Different models have different maximum values for this parameter. See [models](https://platform.claude.com/docs/en/about-claude/models/overview) for details.
- `messages: array of BetaMessageParam`
Input messages.
Our models are trained to operate on alternating `user` and `assistant` conversational turns. When creating a new `Message`, you specify the prior conversational turns with the `messages` parameter, and the model then generates the next `Message` in the conversation. Consecutive `user` or `assistant` turns in your request will be combined into a single turn.
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.
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.
Example with a single `user` message:
```json
[{"role": "user", "content": "Hello, Claude"}]
```
Example with multiple conversational turns:
```json
[
{"role": "user", "content": "Hello there."},
{"role": "assistant", "content": "Hi, I'm Claude. How can I help you?"},
{"role": "user", "content": "Can you explain LLMs in plain English?"},
]
```
Example with a partially-filled response from Claude:
```json
[
{"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"},
{"role": "assistant", "content": "The best answer is ("},
]
```
Each input message `content` may be either a single `string` or an array of content blocks, where each block has a specific `type`. Using a `string` for `content` is shorthand for an array of one content block of type `"text"`. The following input messages are equivalent:
```json
{"role": "user", "content": "Hello, Claude"}
```
```json
{"role": "user", "content": [{"type": "text", "text": "Hello, Claude"}]}
```
See [input examples](https://platform.claude.com/docs/en/build-with-claude/working-with-messages).
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.
There is a limit of 100,000 messages in a single request.
- `content: string or array of BetaContentBlockParam`
- `string`
- `array of BetaContentBlockParam`
- `BetaTextBlockParam object { text, type, cache_control, citations }`
- `text: string`
- `type: "text"`
- `"text"`
- `cache_control: optional BetaCacheControlEphemeral or null`
Create a cache control breakpoint at this content block.
- `type: "ephemeral"`
- `"ephemeral"`
- `ttl: optional "5m" or "1h"`
The time-to-live for the cache control breakpoint.
This may be one the following values:
- `5m`: 5 minutes
- `1h`: 1 hour
Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) for details.
- `"5m"`
- `"1h"`
- `citations: optional array of BetaTextCitationParam or null`
- `BetaCitationCharLocationParam object { cited_text, document_index, document_title, 3 more }`
- `cited_text: string`
- `document_index: number`
- `document_title: string or null`
- `end_char_index: number`
- `start_char_index: number`
- `type: "char_location"`
- `"char_location"`
- `BetaCitationPageLocationParam object { cited_text, document_index, document_title, 3 more }`
- `cited_text: string`
- `document_index: number`
- `document_title: string or null`
- `end_page_number: number`
- `start_page_number: number`
- `type: "page_location"`
- `"page_location"`
- `BetaCitationContentBlockLocationParam object { cited_text, document_index, document_title, 3 more }`
- `cited_text: string`
The full text of the cited block range, concatenated.
Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns.
- `document_index: number`
- `document_title: string or null`
- `end_block_index: number`
Exclusive 0-based end index of the cited block range in the source's `content` array.
Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`.
- `start_block_index: number`
0-based index of the first cited block in the source's `content` array.
- `type: "content_block_location"`
- `"content_block_location"`
- `BetaCitationWebSearchResultLocationParam object { cited_text, encrypted_index, title, 2 more }`
- `cited_text: string`
- `encrypted_index: string`
- `title: string or null`
- `type: "web_search_result_location"`
- `"web_search_result_location"`
- `url: string`
- `BetaCitationSearchResultLocationParam object { cited_text, end_block_index, search_result_index, 4 more }`
- `cited_text: string`
The full text of the cited block range, concatenated.
Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns.
- `end_block_index: number`
Exclusive 0-based end index of the cited block range in the source's `content` array.
Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`.
- `search_result_index: number`
0-based index of the cited search result among all `search_result` content blocks in the request, in the order they appear across messages and tool results.
Counted separately from `document_index`; server-side web search results are not included in this count.
- `source: string`
- `start_block_index: number`
0-based index of the first cited block in the source's `content` array.
- `title: string or null`
- `type: "search_result_location"`
Cut at 300 lines.