Page history
Count tokens in a Message
api/beta/messages/count_tokens
History
api/beta/messages/count_tokens Changed · +21 / -3 lines
from line 16
- `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"`
from line 86
- `"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.
from line 1704
- `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`.
from line 1712
- `"omitted"` + - `"updates"` + - `BetaThinkingConfigDisabled object` - `type: "disabled"`
from line 1722
- `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`.
from line 1729
- `"summarized"` - `"omitted"` + + - `"updates"` - `tool_choice: optional BetaToolChoice`
api/beta/messages/count_tokens Changed · +392 / -491 lines
# Count tokens in a Message ## Headers ## Body parameters ## Returns ## Example ### Response (200) ## Count tokens in a Message ### Header Parameters ### Body Parameters ### Returns ### Example #### Response
The two sides of this change are too far apart to line up, so this is the differ's own diff of it.
from line 1
---- -title: Count tokens in a Message -url: https://platform.claude.com/docs/en/api/beta/messages/count_tokens ---- - -## Count tokens in a Message - -**post** `/v1/messages/count_tokens` +# Count tokens in a Message + +**POST** `/v1/messages/count_tokens` Count the number of tokens in a Message.
from line 8
Learn more about token counting in our [user guide](https://platform.claude.com/docs/en/build-with-claude/token-counting) -### Header Parameters +## Headers - `"anthropic-beta": optional array of AnthropicBeta`
from line 90
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 +## Body parameters - `messages: array of BetaMessageParam`
from line 149
- `array of BetaContentBlockParam` - - `BetaTextBlockParam object { text, type, cache_control, citations }` + - `BetaTextBlockParam object` - `text: string` + minLength: 1 + - `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"`
from line 180
- `citations: optional array of BetaTextCitationParam or null` - - `BetaCitationCharLocationParam object { cited_text, document_index, document_title, 3 more }` + - `BetaCitationCharLocationParam object` - `cited_text: string` - `document_index: number` + minimum: 0 + - `document_title: string or null` + maxLength: 500, minLength: 1 + - `end_char_index: number` - `start_char_index: number` + minimum: 0 + - `type: "char_location"` - - `"char_location"` - - - `BetaCitationPageLocationParam object { cited_text, document_index, document_title, 3 more }` + - `BetaCitationPageLocationParam object` - `cited_text: string` - `document_index: number` + minimum: 0 + - `document_title: string or null` + maxLength: 500, minLength: 1 + - `end_page_number: number` - `start_page_number: number` + minimum: 1 + - `type: "page_location"` - - `"page_location"` - - - `BetaCitationContentBlockLocationParam object { cited_text, document_index, document_title, 3 more }` + - `BetaCitationContentBlockLocationParam object` - `cited_text: string`
from line 230
- `document_index: number` + minimum: 0 + - `document_title: string or null` + maxLength: 500, minLength: 1 + - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array.
from line 246
0-based index of the first cited block in the source's `content` array. + minimum: 0 + - `type: "content_block_location"` - - `"content_block_location"` - - - `BetaCitationWebSearchResultLocationParam object { cited_text, encrypted_index, title, 2 more }` + - `BetaCitationWebSearchResultLocationParam object` - `cited_text: string`
from line 258
- `title: string or null` + maxLength: 512, minLength: 1 + - `type: "web_search_result_location"` - - `"web_search_result_location"` - - `url: string` - - `BetaCitationSearchResultLocationParam object { cited_text, end_block_index, search_result_index, 4 more }` + minLength: 1 + + - `BetaCitationSearchResultLocationParam object` - `cited_text: string`
from line 286
Counted separately from `document_index`; server-side web search results are not included in this count. + minimum: 0 + - `source: string` - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. + minimum: 0 + - `title: string or null` - `type: "search_result_location"` - - `"search_result_location"` - - - `BetaImageBlockParam object { source, type, cache_control, transformations }` + - `BetaImageBlockParam object` - `source: BetaBase64ImageSource or BetaURLImageSource or BetaFileImageSource` - - `BetaBase64ImageSource object { data, media_type, type }` + - `BetaBase64ImageSource object` - `data: string` + format: byte + - `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"` - `"image/jpeg"`
from line 322
- `type: "base64"` - - `"base64"` - - - `BetaURLImageSource object { type, url }` + - `BetaURLImageSource object` - `type: "url"` - - `"url"` - - `url: string` - - `BetaFileImageSource object { file_id, type }` + - `BetaFileImageSource object` - `file_id: string` - `type: "file"` - - `"file"` - - `type: "image"` - - `"image"` - - `cache_control: optional BetaCacheControlEphemeral or null` Create a cache control breakpoint at this content block.
from line 352
- `"error"` - - `BetaRequestDocumentBlock object { source, type, cache_control, 3 more }` + - `BetaRequestDocumentBlock object` - `source: BetaBase64PDFSource or BetaPlainTextSource or BetaContentBlockSource or 2 more` - - `BetaBase64PDFSource object { data, media_type, type }` + - `BetaBase64PDFSource object` - `data: string` + format: byte + - `media_type: "application/pdf"` - - `"application/pdf"` - - `type: "base64"` - - `"base64"` - - - `BetaPlainTextSource object { data, media_type, type }` + - `BetaPlainTextSource object` - `data: string` - `media_type: "text/plain"` - - `"text/plain"` - - `type: "text"` - - `"text"` - - - `BetaContentBlockSource object { content, type }` + - `BetaContentBlockSource object` - `content: string or array of BetaContentBlockSourceContent`
from line 382
- `BetaContentBlockSourceContent = array of BetaContentBlockSourceContent` - - `BetaTextBlockParam object { text, type, cache_control, citations }` - - - `BetaImageBlockParam object { source, type, cache_control, transformations }` + - `BetaTextBlockParam object` + + - `BetaImageBlockParam object` - `type: "content"` - - `"content"` - - - `BetaURLPDFSource object { type, url }` + - `BetaURLPDFSource object` - `type: "url"` - - `"url"` - - `url: string` - - `BetaFileDocumentSource object { file_id, type }` + - `BetaFileDocumentSource object` - `file_id: string` - `type: "file"` - - `"file"` - - `type: "document"` - - `"document"` - - `cache_control: optional BetaCacheControlEphemeral or null` Create a cache control breakpoint at this content block.
from line 412
- `context: optional string or null` + minLength: 1 + - `title: optional string or null` - - `BetaSearchResultBlockParam object { content, source, title, 3 more }` + maxLength: 500, minLength: 1 + + - `BetaSearchResultBlockParam object` - `content: array of BetaTextBlockParam` - `text: string` + minLength: 1 + - `type: "text"` - `cache_control: optional BetaCacheControlEphemeral or null`
from line 440
- `type: "search_result"` - - `"search_result"` - - `cache_control: optional BetaCacheControlEphemeral or null` Create a cache control breakpoint at this content block. - `citations: optional BetaCitationsConfigParam` - - `BetaThinkingBlockParam object { signature, thinking, type }` + - `BetaThinkingBlockParam object` - `signature: string`
from line 460
- `type: "thinking"` - - `"thinking"` - - - `BetaRedactedThinkingBlockParam object { data, type }` + - `BetaRedactedThinkingBlockParam object` - `data: string`
from line 468
- `type: "redacted_thinking"` - - `"redacted_thinking"` - - - `BetaToolUseBlockParam object { id, input, name, 4 more }` + - `BetaToolUseBlockParam object` - `id: string` + pattern: ^[a-zA-Z0-9_-]+$ + - `input: map[unknown]` - `name: string` + maxLength: 200, minLength: 1 + - `type: "tool_use"` - - `"tool_use"` - - `cache_control: optional BetaCacheControlEphemeral or null` Create a cache control breakpoint at this content block.
from line 490
Tool invocation directly from the model. - - `BetaDirectCaller object { type }` + - `BetaDirectCaller object` Tool invocation directly from the model. - `type: "direct"` - - `"direct"` - - - `BetaServerToolCaller object { tool_id, type }` + - `BetaServerToolCaller object` Tool invocation generated by a server-side tool. - `tool_id: string` + pattern: ^srvtoolu_[a-zA-Z0-9_]+$ + - `type: "code_execution_20250825"` - - `"code_execution_20250825"` - - - `BetaServerToolCaller20260120 object { tool_id, type }` + - `BetaServerToolCaller20260120 object` - `tool_id: string` + pattern: ^srvtoolu_[a-zA-Z0-9_]+$ + - `type: "code_execution_20260120"` - - `"code_execution_20260120"` - - `toolset_name: optional string or null` For a toolset member tool_use, the toolset family this member belongs to. - - `BetaToolResultBlockParam object { tool_use_id, type, cache_control, 3 more }` + maxLength: 64, minLength: 1, pattern: ^[a-zA-Z0-9_-]+$ + + - `BetaToolResultBlockParam object` - `tool_use_id: string` + pattern: ^[a-zA-Z0-9_-]+$ + - `type: "tool_result"` - - `"tool_result"` - - `cache_control: optional BetaCacheControlEphemeral or null` Create a cache control breakpoint at this content block.
from line 538
- `array of BetaTextBlockParam or BetaImageBlockParam or BetaSearchResultBlockParam or 3 more` - - `BetaTextBlockParam object { text, type, cache_control, citations }` - - - `BetaImageBlockParam object { source, type, cache_control, transformations }` - - - `BetaSearchResultBlockParam object { content, source, title, 3 more }` - - - `BetaRequestDocumentBlock object { source, type, cache_control, 3 more }` - - - `BetaToolReferenceBlockParam object { tool_name, type, cache_control }` + - `BetaTextBlockParam object` + + - `BetaImageBlockParam object` + + - `BetaSearchResultBlockParam object` + + - `BetaRequestDocumentBlock object` + + - `BetaToolReferenceBlockParam object` Tool reference block that can be included in tool_result content. - `tool_name: string` + maxLength: 256, minLength: 1, pattern: ^[a-zA-Z0-9_-]{1,256}$ + - `type: "tool_reference"` - - `"tool_reference"` - - `cache_control: optional BetaCacheControlEphemeral or null` Create a cache control breakpoint at this content block. - - `BetaBrowserStateBlockParam object { tabs, type, cache_control, state_changes }` + - `BetaBrowserStateBlockParam object` The caller's browser state after a browser toolset member call — the full inventory of open tabs, which tab is active, and any side
from line 574
All tabs open in the browser after this call — the full inventory, not a delta. May be empty. Whenever non-empty, exactly one entry carries `active: true`. + maxItems: 100 + - `tab_id: string` The caller-assigned identifier for this tab, unique within the inventory. + maxLength: 4096, minLength: 1, pattern: ^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$ + - `title: string` The title of the page the tab is showing. May be empty. + maxLength: 4096, pattern: ^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$ + - `url: string` The URL of the page the tab is showing. May be empty. + maxLength: 4096, pattern: ^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$ + - `active: optional boolean` Whether this tab is the active tab after this call. Whenever `tabs` is non-empty, exactly one entry is marked `active: true`. - `type: "browser_state"` - - `"browser_state"` - - `cache_control: optional BetaCacheControlEphemeral or null` Create a cache control breakpoint at this content block.
from line 608
Tabs opened and download state changes during this call. "Nothing to report" is expressed by omitting the field, never by an empty list. - - `BetaBrowserStateChangeTabOpened object { tab_id, type }` + maxItems: 200, minItems: 1 + + - `BetaBrowserStateChangeTabOpened object` A tab this call's execution opened that remains open at its end — the creation delta of the `tabs` inventory, not an event log.
from line 624
The `tab_id` of the opened tab, present in `tabs`. + maxLength: 4096, minLength: 1, pattern: ^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$ + - `type: "tab_opened"` - - `"tab_opened"` - - - `BetaBrowserStateChangeDownloadStarted object { download_id, type, url }` + - `BetaBrowserStateChangeDownloadStarted object` A file download that started during this call.
from line 636
The caller-assigned identifier for this download, stable across the state changes reporting it. + maxLength: 4096, minLength: 1, pattern: ^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$ + - `type: "download_started"` - - `"download_started"` - - `url: string` The final post-redirect URL the download was served from. - - `BetaBrowserStateChangeDownloadCompleted object { download_id, type, url, 2 more }` + maxLength: 4096, pattern: ^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$ + + - `BetaBrowserStateChangeDownloadCompleted object` A file download that finished during this call, reported with the same `download_id` as its `download_started` — or without a prior
from line 657
The caller-assigned identifier for this download, stable across the state changes reporting it. + maxLength: 4096, minLength: 1, pattern: ^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$ + - `type: "download_completed"` - - `"download_completed"` - - `url: string` The final post-redirect URL the download was served from. + maxLength: 4096, pattern: ^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$ + - `path: optional string or null` Where the executor saved the file, on the executor's filesystem. Only included when another tool in the same environment can read the file at that path. + pattern: ^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$, maxLength: 4096 + - `size_bytes: optional number or null` The completed download's size. - - `BetaBrowserStateChangeDownloadFailed object { download_id, type, url, error }` + minimum: 0 + + - `BetaBrowserStateChangeDownloadFailed object` A file download that failed — or was cancelled — during this call.
from line 687
The caller-assigned identifier for this download, stable across the state changes reporting it. + maxLength: 4096, minLength: 1, pattern: ^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$ + - `type: "download_failed"` - - `"download_failed"` - - `url: string` The final post-redirect URL the download was served from. + maxLength: 4096, pattern: ^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$ + - `error: optional string or null` The failure or cancellation detail, when known. + pattern: ^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$, maxLength: 4096 + - `is_error: optional boolean` - `toolset_name: optional string or null` For a toolset member tool_result, the toolset family of the paired tool_use. - - `BetaServerToolUseBlockParam object { id, input, name, 3 more }` + maxLength: 64, minLength: 1, pattern: ^[a-zA-Z0-9_-]+$ + + - `BetaServerToolUseBlockParam object` - `id: string` + pattern: ^srvtoolu_[a-zA-Z0-9_]+$ + - `input: map[unknown]` - `name: "advisor" or "web_search" or "web_fetch" or 5 more`
from line 739
- `type: "server_tool_use"` - - `"server_tool_use"` - - `cache_control: optional BetaCacheControlEphemeral or null` Create a cache control breakpoint at this content block.
from line 747
Tool invocation directly from the model. - - `BetaDirectCaller object { type }` + - `BetaDirectCaller object` Tool invocation directly from the model. - - `BetaServerToolCaller object { tool_id, type }` + - `BetaServerToolCaller object` Tool invocation generated by a server-side tool. - - `BetaServerToolCaller20260120 object { tool_id, type }` - - - `BetaWebSearchToolResultBlockParam object { content, tool_use_id, type, 2 more }` + - `BetaServerToolCaller20260120 object` + + - `BetaWebSearchToolResultBlockParam object` - `content: BetaWebSearchToolResultBlockParamContent`
from line 769
- `type: "web_search_result"` - - `"web_search_result"` - - `url: string` - `page_age: optional string or null` - - `BetaWebSearchToolRequestError object { error_code, type }` + - `BetaWebSearchToolRequestError object` - `error_code: BetaWebSearchToolResultErrorCode`
from line 791
- `type: "web_search_tool_result_error"` - - `"web_search_tool_result_error"` - - `tool_use_id: string` + pattern: ^srvtoolu_[a-zA-Z0-9_]+$ + - `type: "web_search_tool_result"` - - `"web_search_tool_result"` - - `cache_control: optional BetaCacheControlEphemeral or null` Create a cache control breakpoint at this content block.
from line 805
Tool invocation directly from the model. - - `BetaDirectCaller object { type }` + - `BetaDirectCaller object` Tool invocation directly from the model. - - `BetaServerToolCaller object { tool_id, type }` + - `BetaServerToolCaller object` Tool invocation generated by a server-side tool. - - `BetaServerToolCaller20260120 object { tool_id, type }` - - - `BetaWebFetchToolResultBlockParam object { content, tool_use_id, type, 2 more }` + - `BetaServerToolCaller20260120 object` + + - `BetaWebFetchToolResultBlockParam object` - `content: BetaWebFetchToolResultErrorBlockParam or BetaWebFetchBlockParam` - - `BetaWebFetchToolResultErrorBlockParam object { error_code, type }` + - `BetaWebFetchToolResultErrorBlockParam object` - `error_code: BetaWebFetchToolResultErrorCode`
from line 843
- `type: "web_fetch_tool_result_error"` - - `"web_fetch_tool_result_error"` - - - `BetaWebFetchBlockParam object { content, type, url, retrieved_at }` + - `BetaWebFetchBlockParam object` - `content: BetaRequestDocumentBlock` - `type: "web_fetch_result"` - - `"web_fetch_result"` - - `url: string` Fetched content URL
from line 859
- `tool_use_id: string` + pattern: ^srvtoolu_[a-zA-Z0-9_]+$ + - `type: "web_fetch_tool_result"` - - `"web_fetch_tool_result"` - - `cache_control: optional BetaCacheControlEphemeral or null` Create a cache control breakpoint at this content block.
from line 871
Tool invocation directly from the model. - - `BetaDirectCaller object { type }` + - `BetaDirectCaller object` Tool invocation directly from the model. - - `BetaServerToolCaller object { tool_id, type }` + - `BetaServerToolCaller object` Tool invocation generated by a server-side tool. - - `BetaServerToolCaller20260120 object { tool_id, type }` - - - `BetaAdvisorToolResultBlockParam object { content, tool_use_id, type, cache_control }` + - `BetaServerToolCaller20260120 object` + + - `BetaAdvisorToolResultBlockParam object` - `content: BetaAdvisorToolResultErrorParam or BetaAdvisorResultBlockParam or BetaAdvisorRedactedResultBlockParam` - - `BetaAdvisorToolResultErrorParam object { error_code, type }` + - `BetaAdvisorToolResultErrorParam object` - `error_code: "max_uses_exceeded" or "prompt_too_long" or "too_many_requests" or 4 more`
from line 905
- `type: "advisor_tool_result_error"` - - `"advisor_tool_result_error"` - - - `BetaAdvisorResultBlockParam object { text, type, stop_reason }` + - `BetaAdvisorResultBlockParam object` - `text: string` - `type: "advisor_result"` - - `"advisor_result"` - - `stop_reason: optional string or null` - - `BetaAdvisorRedactedResultBlockParam object { encrypted_content, type, stop_reason }` + - `BetaAdvisorRedactedResultBlockParam object` - `encrypted_content: string`
from line 921
- `type: "advisor_redacted_result"` - - `"advisor_redacted_result"` - - `stop_reason: optional string or null` - `tool_use_id: string` + pattern: ^srvtoolu_[a-zA-Z0-9_]+$ + - `type: "advisor_tool_result"` - - `"advisor_tool_result"` - - `cache_control: optional BetaCacheControlEphemeral or null` Create a cache control breakpoint at this content block. - - `BetaCodeExecutionToolResultBlockParam object { content, tool_use_id, type, cache_control }` + - `BetaCodeExecutionToolResultBlockParam object` - `content: BetaCodeExecutionToolResultBlockParamContent` Code execution result with encrypted stdout for PFC + web_search results. - - `BetaCodeExecutionToolResultErrorParam object { error_code, type }` + - `BetaCodeExecutionToolResultErrorParam object` - `error_code: BetaCodeExecutionToolResultErrorCode`
from line 953
- `type: "code_execution_tool_result_error"` - - `"code_execution_tool_result_error"` - - - `BetaCodeExecutionResultBlockParam object { content, return_code, stderr, 2 more }` + - `BetaCodeExecutionResultBlockParam object` - `content: array of BetaCodeExecutionOutputBlockParam`
from line 961
- `type: "code_execution_output"` - - `"code_execution_output"` - - `return_code: number` - `stderr: string`
from line 969
- `type: "code_execution_result"` - - `"code_execution_result"` - - - `BetaEncryptedCodeExecutionResultBlockParam object { content, encrypted_stdout, return_code, 2 more }` + - `BetaEncryptedCodeExecutionResultBlockParam object` Code execution result with encrypted stdout for PFC + web_search results.
from line 987
- `type: "encrypted_code_execution_result"` - - `"encrypted_code_execution_result"` - - `tool_use_id: string` + pattern: ^srvtoolu_[a-zA-Z0-9_]+$ + - `type: "code_execution_tool_result"` - - `"code_execution_tool_result"` - - `cache_control: optional BetaCacheControlEphemeral or null` Create a cache control breakpoint at this content block. - - `BetaBashCodeExecutionToolResultBlockParam object { content, tool_use_id, type, cache_control }` + - `BetaBashCodeExecutionToolResultBlockParam object` - `content: BetaBashCodeExecutionToolResultErrorParam or BetaBashCodeExecutionResultBlockParam` - - `BetaBashCodeExecutionToolResultErrorParam object { error_code, type }` + - `BetaBashCodeExecutionToolResultErrorParam object` - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more`
from line 1017
- `type: "bash_code_execution_tool_result_error"` - - `"bash_code_execution_tool_result_error"` - - - `BetaBashCodeExecutionResultBlockParam object { content, return_code, stderr, 2 more }` + - `BetaBashCodeExecutionResultBlockParam object` - `content: array of BetaBashCodeExecutionOutputBlockParam`
from line 1025
- `type: "bash_code_execution_output"` - - `"bash_code_execution_output"` - - `return_code: number` - `stderr: string`
from line 1033
- `type: "bash_code_execution_result"` - - `"bash_code_execution_result"` - - `tool_use_id: string` + pattern: ^srvtoolu_[a-zA-Z0-9_]+$ + - `type: "bash_code_execution_tool_result"` - - `"bash_code_execution_tool_result"` - - `cache_control: optional BetaCacheControlEphemeral or null` Create a cache control breakpoint at this content block. - - `BetaTextEditorCodeExecutionToolResultBlockParam object { content, tool_use_id, type, cache_control }` + - `BetaTextEditorCodeExecutionToolResultBlockParam object` - `content: BetaTextEditorCodeExecutionToolResultErrorParam or BetaTextEditorCodeExecutionViewResultBlockParam or BetaTextEditorCodeExecutionCreateResultBlockParam or BetaTextEditorCodeExecutionStrReplaceResultBlockParam` - - `BetaTextEditorCodeExecutionToolResultErrorParam object { error_code, type, error_message }` + - `BetaTextEditorCodeExecutionToolResultErrorParam object` - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more`
from line 1063
- `type: "text_editor_code_execution_tool_result_error"` - - `"text_editor_code_execution_tool_result_error"` - - `error_message: optional string or null` - - `BetaTextEditorCodeExecutionViewResultBlockParam object { content, file_type, type, 3 more }` + - `BetaTextEditorCodeExecutionViewResultBlockParam object` - `content: string`
from line 1079
- `type: "text_editor_code_execution_view_result"` - - `"text_editor_code_execution_view_result"` - - `num_lines: optional number or null` - `start_line: optional number or null` - `total_lines: optional number or null` - - `BetaTextEditorCodeExecutionCreateResultBlockParam object { is_file_update, type }` + - `BetaTextEditorCodeExecutionCreateResultBlockParam object` - `is_file_update: boolean` - `type: "text_editor_code_execution_create_result"` - - `"text_editor_code_execution_create_result"` - - - `BetaTextEditorCodeExecutionStrReplaceResultBlockParam object { type, lines, new_lines, 3 more }` + - `BetaTextEditorCodeExecutionStrReplaceResultBlockParam object` - `type: "text_editor_code_execution_str_replace_result"` - - `"text_editor_code_execution_str_replace_result"` - - `lines: optional array of string or null` - `new_lines: optional number or null`
from line 1107
- `tool_use_id: string` + pattern: ^srvtoolu_[a-zA-Z0-9_]+$ + - `type: "text_editor_code_execution_tool_result"` - - `"text_editor_code_execution_tool_result"` - - `cache_control: optional BetaCacheControlEphemeral or null` Create a cache control breakpoint at this content block. - - `BetaToolSearchToolResultBlockParam object { content, tool_use_id, type, cache_control }` + - `BetaToolSearchToolResultBlockParam object` - `content: BetaToolSearchToolResultErrorParam or BetaToolSearchToolSearchResultBlockParam` - - `BetaToolSearchToolResultErrorParam object { error_code, type, error_message }` + - `BetaToolSearchToolResultErrorParam object` - `error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"`
from line 1133
- `type: "tool_search_tool_result_error"` - - `"tool_search_tool_result_error"` - - `error_message: optional string or null` - - `BetaToolSearchToolSearchResultBlockParam object { tool_references, type }` + - `BetaToolSearchToolSearchResultBlockParam object` - `tool_references: array of BetaToolReferenceBlockParam` - `tool_name: string` + maxLength: 256, minLength: 1, pattern: ^[a-zA-Z0-9_-]{1,256}$ + - `type: "tool_reference"` - `cache_control: optional BetaCacheControlEphemeral or null`
from line 1151
- `type: "tool_search_tool_search_result"` - - `"tool_search_tool_search_result"` - - `tool_use_id: string` + pattern: ^srvtoolu_[a-zA-Z0-9_]+$ + - `type: "tool_search_tool_result"` - - `"tool_search_tool_result"` - - `cache_control: optional BetaCacheControlEphemeral or null` Create a cache control breakpoint at this content block. - - `BetaMCPToolUseBlockParam object { id, input, name, 3 more }` + - `BetaMCPToolUseBlockParam object` - `id: string` + pattern: ^[a-zA-Z0-9_-]+$ + - `input: map[unknown]` - `name: string`
from line 1177
- `type: "mcp_tool_use"` - - `"mcp_tool_use"` - - `cache_control: optional BetaCacheControlEphemeral or null` Create a cache control breakpoint at this content block. - - `BetaRequestMCPToolResultBlockParam object { tool_use_id, type, cache_control, 2 more }` + - `BetaRequestMCPToolResultBlockParam object` - `tool_use_id: string` + pattern: ^[a-zA-Z0-9_-]+$ + - `type: "mcp_tool_result"` - - `"mcp_tool_result"` - - `cache_control: optional BetaCacheControlEphemeral or null` Create a cache control breakpoint at this content block.
from line 1201
- `text: string` + minLength: 1 + - `type: "text"` - `cache_control: optional BetaCacheControlEphemeral or null`
from line 1213
- `is_error: optional boolean` - - `BetaContainerUploadBlockParam object { file_id, type, cache_control }` + - `BetaContainerUploadBlockParam object` A content block that represents a file to be uploaded to the container Files uploaded via this block will be available in the container's input directory.
from line 1222
- `type: "container_upload"` - - `"container_upload"` - - `cache_control: optional BetaCacheControlEphemeral or null` Create a cache control breakpoint at this content block. - - `BetaCompactionBlockParam object { type, cache_control, content, encrypted_content }` + - `BetaCompactionBlockParam object` A compaction block containing summary of previous context.
from line 1238
- `type: "compaction"` - - `"compaction"` - - `cache_control: optional BetaCacheControlEphemeral or null` Create a cache control breakpoint at this content block.
from line 1250
Opaque metadata from prior compaction, to be round-tripped verbatim - - `BetaRequestToolAdditionBlock object { tool, type, cache_control }` + - `BetaRequestToolAdditionBlock object` Mid-conversation directive to surface a declared tool.
from line 1265
server assigns to MCP-resolved tools — use `mcp_tool_reference` or `mcp_toolset_reference` for those. - - `BetaToolChangeToolReference object { name, type }` + - `BetaToolChangeToolReference object` Reference to a single tool the caller declared directly in `tools[]`. Does not accept the composed `{server}_{name}` form the
from line 1274
- `name: string` + pattern: ^[a-zA-Z0-9_-]{1,128}$ + - `type: "tool_reference"` - - `"tool_reference"` - - - `BetaToolChangeMCPToolReference object { name, server_name, type }` + - `BetaToolChangeMCPToolReference object` Reference to a single MCP tool by its server and remote name — the same `server_name`/`name` pair `mcp_tool_use` carries.
from line 1289
- `type: "mcp_tool_reference"` - - `"mcp_tool_reference"` - - - `BetaToolChangeMCPToolsetReference object { server_name, type }` + - `BetaToolChangeMCPToolsetReference object` Reference to every tool in the named MCP server's toolset.
from line 1297
- `type: "mcp_toolset_reference"` - - `"mcp_toolset_reference"` - - `type: "tool_addition"` - - `"tool_addition"` - - `cache_control: optional BetaCacheControlEphemeral or null` Create a cache control breakpoint at this content block. - - `BetaRequestToolRemovalBlock object { tool, type, cache_control }` + - `BetaRequestToolRemovalBlock object` Mid-conversation directive to withdraw a tool.
from line 1318
server assigns to MCP-resolved tools — use `mcp_tool_reference` or `mcp_toolset_reference` for those. - - `BetaToolChangeToolReference object { name, type }` + - `BetaToolChangeToolReference object` Reference to a single tool the caller declared directly in `tools[]`. Does not accept the composed `{server}_{name}` form the server assigns to MCP-resolved tools — use `mcp_tool_reference` or `mcp_toolset_reference` for those. - - `BetaToolChangeMCPToolReference object { name, server_name, type }` + - `BetaToolChangeMCPToolReference object` Reference to a single MCP tool by its server and remote name — the same `server_name`/`name` pair `mcp_tool_use` carries. - - `BetaToolChangeMCPToolsetReference object { server_name, type }` + - `BetaToolChangeMCPToolsetReference object` Reference to every tool in the named MCP server's toolset. - `type: "tool_removal"` - - `"tool_removal"` - - `cache_control: optional BetaCacheControlEphemeral or null` Create a cache control breakpoint at this content block. - - `BetaFallbackBlockParam object { from, to, type, trigger }` + - `BetaFallbackBlockParam object` A `fallback` block echoed back from a prior response.
from line 1440
- `type: "fallback"` - - `"fallback"` - - `trigger: optional unknown` The response block's `trigger`, echoed verbatim. Accepted and ignored by the server; any object or `null` is allowed.
from line 1472
List of context management edits to apply - - `BetaClearToolUses20250919Edit object { type, clear_at_least, clear_tool_inputs, 3 more }` + minItems: 0 + + - `BetaClearToolUses20250919Edit object` - `type: "clear_tool_uses_20250919"` - - `"clear_tool_uses_20250919"` - - `clear_at_least: optional BetaInputTokensClearAtLeast or null` Minimum number of tokens that must be cleared when triggered. Context will only be modified if at least this many tokens can be removed. - `type: "input_tokens"` - - `"input_tokens"` - - `value: number` + minimum: 0 + - `clear_tool_inputs: optional boolean or array of string or null` Whether to clear all tool inputs (bool) or specific tool inputs to clear (list)
from line 1506
- `type: "tool_uses"` - - `"tool_uses"` - - `value: number` + minimum: 0 + - `trigger: optional BetaInputTokensTrigger or BetaToolUsesTrigger` Condition that triggers the context management strategy - - `BetaInputTokensTrigger object { type, value }` + - `BetaInputTokensTrigger object` - `type: "input_tokens"` - - `"input_tokens"` - - `value: number` - - `BetaToolUsesTrigger object { type, value }` + minimum: 1 + + - `BetaToolUsesTrigger object` - `type: "tool_uses"` - - `"tool_uses"` - - `value: number` - - `BetaClearThinking20251015Edit object { type, keep }` + minimum: 1 + + - `BetaClearThinking20251015Edit object` - `type: "clear_thinking_20251015"` - - `"clear_thinking_20251015"` - - `keep: optional BetaThinkingTurns or BetaAllThinkingTurns or "all"` Number of most recent assistant turns to keep thinking blocks for. Older turns will have their thinking blocks removed. - - `BetaThinkingTurns object { type, value }` + - `BetaThinkingTurns object` - `type: "thinking_turns"` - - `"thinking_turns"` - - `value: number` - - `BetaAllThinkingTurns object { type }` + minimum: 1 + + - `BetaAllThinkingTurns object` - `type: "all"` - - `"all"` - - `"all"` - - `"all"` - - - `BetaCompact20260112Edit object { type, instructions, pause_after_compaction, trigger }` + - `BetaCompact20260112Edit object` Automatically compact older context when reaching the configured trigger threshold. - `type: "compact_20260112"` - - `"compact_20260112"` - - `instructions: optional string or null` Additional instructions for summarization.
from line 1574
MCP servers to be utilized in this request + maxItems: 20 + - `name: string` - `type: "url"` - - `"url"` - - `url: string` - `authorization_token: optional string or null`
from line 1618
- `type: "json_schema"` - - `"json_schema"` - - `task_budget: optional BetaTokenTaskBudget or null` User-configurable total token budget across contexts.
from line 1626
Total token budget across all contexts in the session. + minimum: 1024 + - `type: "tokens"` The budget type. Currently only 'tokens' is supported. - - `"tokens"` - - `remaining: optional number or null` Remaining tokens in the budget. Use this to track usage across contexts when implementing compaction client-side. Defaults to total if not provided. -- `output_format: optional BetaJSONOutputFormat or null` - - Deprecated: Use `output_config.format` instead. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) - - A schema to specify Claude's output format in responses. This parameter will be removed in a future release. + minimum: 0 - `speed: optional "standard" or "fast" or null`
from line 1658
- `text: string` + minLength: 1 + - `type: "text"` - `cache_control: optional BetaCacheControlEphemeral or null`
from line 1676
See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) for details. - - `BetaThinkingConfigEnabled object { budget_tokens, type, display }` + - `BetaThinkingConfigEnabled object` - `budget_tokens: number`
from line 1686
See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) for details. + minimum: 1024 + - `type: "enabled"` - - `"enabled"` - - `display: optional "summarized" or "omitted" 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`.
from line 1698
- `"omitted"` - - `BetaThinkingConfigDisabled object { type }` + - `BetaThinkingConfigDisabled object` - `type: "disabled"` - - `"disabled"` - - - `BetaThinkingConfigAdaptive object { type, display }` + - `BetaThinkingConfigAdaptive object` - `type: "adaptive"` - - `"adaptive"` - - `display: optional "summarized" or "omitted" 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`.
from line 1718
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. - - `BetaToolChoiceAuto object { type, disable_parallel_tool_use }` + - `BetaToolChoiceAuto object` The model will automatically decide whether to use tools. - `type: "auto"` - - `"auto"` - - `disable_parallel_tool_use: optional boolean` Whether to disable parallel tool use. Defaults to `false`. If set to `true`, the model will output at most one tool use. - - `BetaToolChoiceAny object { type, disable_parallel_tool_use }` + - `BetaToolChoiceAny object` The model will use any available tools. - `type: "any"` - - `"any"` - - `disable_parallel_tool_use: optional boolean` Whether to disable parallel tool use. Defaults to `false`. If set to `true`, the model will output exactly one tool use. - - `BetaToolChoiceTool object { name, type, disable_parallel_tool_use }` + - `BetaToolChoiceTool object` The model will use the specified tool with `tool_choice.name`.
from line 1752
- `type: "tool"` - - `"tool"` - - `disable_parallel_tool_use: optional boolean` Whether to disable parallel tool use. Defaults to `false`. If set to `true`, the model will output exactly one tool use. - - `BetaToolChoiceNone object { type }` + - `BetaToolChoiceNone object` The model will not be allowed to use tools. - `type: "none"` - - - `"none"` - `tools: optional array of BetaTool or BetaToolBash20241022 or BetaToolBash20250124 or 25 more`
from line 1828
See our [guide](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview) for more details. - - `BetaTool object { input_schema, name, allowed_callers, 7 more }` - - - `input_schema: object { type, properties, required }` + - `BetaTool object` + + - `input_schema: object` [JSON schema](https://json-schema.org/draft/2020-12) for this tool's input.
from line 1838
- `type: "object"` - - `"object"` - - `properties: optional map[unknown] or null` - `required: optional array of string or null`
from line 1848
This is how the tool will be called by the model and in `tool_use` blocks. + maxLength: 128, minLength: 1, pattern: ^[a-zA-Z0-9_-]{1,128}$ + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"`
from line 1886
- `type: optional "custom" or null` - - `"custom"` - - - `BetaToolBash20241022 object { name, type, allowed_callers, 4 more }` + - `BetaToolBash20241022 object` - `name: "bash"`
from line 1894
This is how the tool will be called by the model and in `tool_use` blocks. - - `"bash"` - - `type: "bash_20241022"` - - `"bash_20241022"` - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"`
from line 1920
When true, guarantees schema validation on tool names and inputs - - `BetaToolBash20250124 object { name, type, allowed_callers, 4 more }` + - `BetaToolBash20250124 object` - `name: "bash"`
from line 1928
This is how the tool will be called by the model and in `tool_use` blocks. - - `"bash"` - - `type: "bash_20250124"` - - `"bash_20250124"` - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"`
from line 1954
When true, guarantees schema validation on tool names and inputs - - `BetaCodeExecutionTool20250522 object { name, type, allowed_callers, 3 more }` + - `BetaCodeExecutionTool20250522 object` - `name: "code_execution"`
from line 1962
This is how the tool will be called by the model and in `tool_use` blocks. - - `"code_execution"` - - `type: "code_execution_20250522"` - - `"code_execution_20250522"` - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"`
from line 1986
When true, guarantees schema validation on tool names and inputs - - `BetaCodeExecutionTool20250825 object { name, type, allowed_callers, 3 more }` + - `BetaCodeExecutionTool20250825 object` - `name: "code_execution"`
from line 1994
This is how the tool will be called by the model and in `tool_use` blocks. - - `"code_execution"` - - `type: "code_execution_20250825"` + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` + + - `"direct"` + - `"code_execution_20250825"` + - `"code_execution_20260120"` + + - `"code_execution_20260521"` + + - `cache_control: optional BetaCacheControlEphemeral or null` + + Create a cache control breakpoint at this content block. + + - `defer_loading: optional boolean` + + If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. + + - `strict: optional boolean` + + When true, guarantees schema validation on tool names and inputs + + - `BetaCodeExecutionTool20260120 object` + + Code execution tool with REPL state persistence (daemon mode + gVisor checkpoint). + + - `name: "code_execution"` + + Name of the tool. + + This is how the tool will be called by the model and in `tool_use` blocks. + + - `type: "code_execution_20260120"` + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"`
from line 2052
When true, guarantees schema validation on tool names and inputs - - `BetaCodeExecutionTool20260120 object { name, type, allowed_callers, 3 more }` - - Code execution tool with REPL state persistence (daemon mode + gVisor checkpoint). + - `BetaCodeExecutionTool20260521 object` + + Code execution tool with REPL state persistence. - `name: "code_execution"`
from line 2062
This is how the tool will be called by the model and in `tool_use` blocks. - - `"code_execution"` - - - `type: "code_execution_20260120"` + - `type: "code_execution_20260521"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` + + - `"direct"` + + - `"code_execution_20250825"` - `"code_execution_20260120"` - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - - - `"direct"` - - - `"code_execution_20250825"` - - - `"code_execution_20260120"` - - `"code_execution_20260521"` - `cache_control: optional BetaCacheControlEphemeral or null`
from line 2086
When true, guarantees schema validation on tool names and inputs - - `BetaCodeExecutionTool20260521 object { name, type, allowed_callers, 3 more }` - - Code execution tool with REPL state persistence. - - - `name: "code_execution"` - - Name of the tool. - - This is how the tool will be called by the model and in `tool_use` blocks. - - - `"code_execution"` - - - `type: "code_execution_20260521"` - - - `"code_execution_20260521"` - - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - - - `"direct"` - - - `"code_execution_20250825"` - - - `"code_execution_20260120"` - - - `"code_execution_20260521"` - - - `cache_control: optional BetaCacheControlEphemeral or null` - - Create a cache control breakpoint at this content block. - - - `defer_loading: optional boolean` - - If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - - - `strict: optional boolean` - - When true, guarantees schema validation on tool names and inputs - - - `BetaBrowserToolset20260801 object { type, allowed_callers, cache_control, configs }` + - `BetaBrowserToolset20260801 object` The browser toolset: a single `tools[]` entry (carrying no `name`) that declares the browser tool family. The model is served
from line 2094
from its schema. - `type: "browser_toolset_20260801"` - - - `"browser_toolset_20260801"` - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"`
from line 2490
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. - - `BetaToolComputerUse20241022 object { display_height_px, display_width_px, name, 7 more }` + - `BetaToolComputerUse20241022 object` - `display_height_px: number` The height of the display in pixels. + minimum: 1 + - `display_width_px: number` The width of the display in pixels. + minimum: 1 + - `name: "computer"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - - `"computer"` - - `type: "computer_20241022"` - - `"computer_20241022"` - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"`
from line 2534
The X11 display number (e.g. 0, 1) for the display. + minimum: 0 + - `input_examples: optional array of map[unknown]` - `strict: optional boolean` When true, guarantees schema validation on tool names and inputs - - `BetaMemoryTool20250818 object { name, type, allowed_callers, 4 more }` + - `BetaMemoryTool20250818 object` - `name: "memory"`
from line 2550
This is how the tool will be called by the model and in `tool_use` blocks. - - `"memory"` - - `type: "memory_20250818"` - - `"memory_20250818"` - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"`
from line 2576
When true, guarantees schema validation on tool names and inputs - - `BetaToolComputerUse20250124 object { display_height_px, display_width_px, name, 7 more }` + - `BetaToolComputerUse20250124 object` - `display_height_px: number` The height of the display in pixels. + minimum: 1 + - `display_width_px: number` The width of the display in pixels. + minimum: 1 + - `name: "computer"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - - `"computer"` - - `type: "computer_20250124"` - - `"computer_20250124"` - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"`
from line 2620
The X11 display number (e.g. 0, 1) for the display. + minimum: 0 + - `input_examples: optional array of map[unknown]` - `strict: optional boolean` When true, guarantees schema validation on tool names and inputs - - `BetaToolTextEditor20241022 object { name, type, allowed_callers, 4 more }` + - `BetaToolTextEditor20241022 object` - `name: "str_replace_editor"`
from line 2636
This is how the tool will be called by the model and in `tool_use` blocks. - - `"str_replace_editor"` - - `type: "text_editor_20241022"` - - `"text_editor_20241022"` - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"`
from line 2662
When true, guarantees schema validation on tool names and inputs - - `BetaToolComputerUse20251124 object { display_height_px, display_width_px, name, 8 more }` + - `BetaToolComputerUse20251124 object` - `display_height_px: number` The height of the display in pixels. + minimum: 1 + - `display_width_px: number` The width of the display in pixels. + minimum: 1 + - `name: "computer"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - - `"computer"` - - `type: "computer_20251124"` - - `"computer_20251124"` - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"`
from line 2706
The X11 display number (e.g. 0, 1) for the display. + minimum: 0 + - `enable_zoom: optional boolean` Whether to enable an action to take a zoomed-in screenshot of the screen.
from line 2718
When true, guarantees schema validation on tool names and inputs - - `BetaComputerToolset20260801 object { type, allowed_callers, cache_control, configs }` + - `BetaComputerToolset20260801 object` The computer toolset: a single `tools[]` entry (carrying no `name`) that declares the computer tool family. The model is
from line 2731
- `type: "computer_toolset_20260801"` - - `"computer_toolset_20260801"` - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"`
from line 2958
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. - - `BetaToolTextEditor20250124 object { name, type, allowed_callers, 4 more }` + - `BetaToolTextEditor20250124 object` - `name: "str_replace_editor"`
from line 2966
This is how the tool will be called by the model and in `tool_use` blocks. - - `"str_replace_editor"` - - `type: "text_editor_20250124"` - - `"text_editor_20250124"` - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"`
from line 2992
When true, guarantees schema validation on tool names and inputs - - `BetaToolTextEditor20250429 object { name, type, allowed_callers, 4 more }` + - `BetaToolTextEditor20250429 object` - `name: "str_replace_based_edit_tool"`
from line 3000
This is how the tool will be called by the model and in `tool_use` blocks. - - `"str_replace_based_edit_tool"` - - `type: "text_editor_20250429"` - - `"text_editor_20250429"` - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"`
from line 3026
When true, guarantees schema validation on tool names and inputs - - `BetaToolTextEditor20250728 object { name, type, allowed_callers, 5 more }` + - `BetaToolTextEditor20250728 object` - `name: "str_replace_based_edit_tool"`
from line 3034
This is how the tool will be called by the model and in `tool_use` blocks. - - `"str_replace_based_edit_tool"` - - `type: "text_editor_20250728"` - - `"text_editor_20250728"` - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"`
from line 3060
Maximum number of characters to display when viewing a file. If not specified, defaults to displaying the full file. + minimum: 1 + - `strict: optional boolean` When true, guarantees schema validation on tool names and inputs - - `BetaWebSearchTool20250305 object { name, type, allowed_callers, 7 more }` + - `BetaWebSearchTool20250305 object` - `name: "web_search"`
from line 3074
This is how the tool will be called by the model and in `tool_use` blocks. - - `"web_search"` - - `type: "web_search_20250305"` - - `"web_search_20250305"` - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"`
from line 3106
Maximum number of times the tool can be used in the API request. + exclusiveMinimum: 0 + - `strict: optional boolean` When true, guarantees schema validation on tool names and inputs
from line 3118
- `type: "approximate"` - - `"approximate"` - - `city: optional string or null` The city of the user. + maxLength: 255, minLength: 1 + - `country: optional string or null` The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user. + maxLength: 2, minLength: 2 + - `region: optional string or null` The region of the user. + maxLength: 255, minLength: 1 + - `timezone: optional string or null` The [IANA timezone](https://nodatime.org/TimeZones) of the user. - - `BetaWebFetchTool20250910 object { name, type, allowed_callers, 8 more }` + maxLength: 255, minLength: 1 + + - `BetaWebFetchTool20250910 object` - `name: "web_fetch"`
from line 3150
This is how the tool will be called by the model and in `tool_use` blocks. - - `"web_fetch"` - - `type: "web_fetch_20250910"` - - `"web_fetch_20250910"` - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"`
from line 3186
Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. + exclusiveMinimum: 0 + - `max_uses: optional number or null` Maximum number of times the tool can be used in the API request. + exclusiveMinimum: 0 + - `strict: optional boolean` When true, guarantees schema validation on tool names and inputs - - `BetaWebSearchTool20260209 object { name, type, allowed_callers, 7 more }` + - `BetaWebSearchTool20260209 object` - `name: "web_search"`
from line 3206
This is how the tool will be called by the model and in `tool_use` blocks. - - `"web_search"` - - `type: "web_search_20260209"` - - `"web_search_20260209"` - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"`
from line 3238
Maximum number of times the tool can be used in the API request. + exclusiveMinimum: 0 + - `strict: optional boolean` When true, guarantees schema validation on tool names and inputs
from line 3248
Parameters for the user's location. Used to provide more relevant search results. - - `BetaWebFetchTool20260209 object { name, type, allowed_callers, 8 more }` + - `BetaWebFetchTool20260209 object` - `name: "web_fetch"`
from line 3256
This is how the tool will be called by the model and in `tool_use` blocks. - - `"web_fetch"` - - `type: "web_fetch_20260209"` - - `"web_fetch_20260209"` - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"`
from line 3292
Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. + exclusiveMinimum: 0 + - `max_uses: optional number or null` Maximum number of times the tool can be used in the API request. + exclusiveMinimum: 0 + - `strict: optional boolean` When true, guarantees schema validation on tool names and inputs - - `BetaWebFetchTool20260309 object { name, type, allowed_callers, 9 more }` + - `BetaWebFetchTool20260309 object` Web fetch tool with use_cache parameter for bypassing cached content.
from line 3314
This is how the tool will be called by the model and in `tool_use` blocks. - - `"web_fetch"` - - `type: "web_fetch_20260309"` - - `"web_fetch_20260309"` - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"`
from line 3350
Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. + exclusiveMinimum: 0 + - `max_uses: optional number or null` Maximum number of times the tool can be used in the API request. + exclusiveMinimum: 0 + - `strict: optional boolean` When true, guarantees schema validation on tool names and inputs
from line 3366
Whether to use cached content. Set to false to bypass the cache and fetch fresh content. Only set to false when the user explicitly requests fresh content or when fetching rapidly-changing sources. - - `BetaWebSearchTool20260318 object { name, type, allowed_callers, 8 more }` + - `BetaWebSearchTool20260318 object` - `name: "web_search"`
from line 3374
This is how the tool will be called by the model and in `tool_use` blocks. - - `"web_search"` - - `type: "web_search_20260318"` - - `"web_search_20260318"` - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"`
from line 3406
Maximum number of times the tool can be used in the API request. + exclusiveMinimum: 0 + - `response_inclusion: optional "full" or "excluded"` How this tool's result blocks appear in the API response when the result was consumed by a completed code_execution call in the same turn. 'full' returns the complete content (default). 'excluded' drops the nested server_tool_use and result block pair entirely. Results from direct calls, or from code_execution calls that paused before completing, are always returned in full so they can be sent back on the next turn.
from line 3424
Parameters for the user's location. Used to provide more relevant search results. - - `BetaWebFetchTool20260318 object { name, type, allowed_callers, 10 more }` + - `BetaWebFetchTool20260318 object` - `name: "web_fetch"`
from line 3432
This is how the tool will be called by the model and in `tool_use` blocks. - - `"web_fetch"` - - `type: "web_fetch_20260318"` - - `"web_fetch_20260318"` - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"`
from line 3468
Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. + exclusiveMinimum: 0 + - `max_uses: optional number or null` Maximum number of times the tool can be used in the API request. + exclusiveMinimum: 0 + - `response_inclusion: optional "full" or "excluded"` How this tool's result blocks appear in the API response when the result was consumed by a completed code_execution call in the same turn. 'full' returns the complete content (default). 'excluded' drops the nested server_tool_use and result block pair entirely. Results from direct calls, or from code_execution calls that paused before completing, are always returned in full so they can be sent back on the next turn.
from line 3492
Whether to use cached content. Set to false to bypass the cache and fetch fresh content. Only set to false when the user explicitly requests fresh content or when fetching rapidly-changing sources. - - `BetaAdvisorTool20260301 object { model, name, type, 7 more }` + - `BetaAdvisorTool20260301 object` - `model: Model`
from line 3506
This is how the tool will be called by the model and in `tool_use` blocks. - - `"advisor"` - - `type: "advisor_20260301"` - - `"advisor_20260301"` - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"`
from line 3534
Bounds the advisor's total output (thinking + text) per call. When the advisor hits this cap, the returned advisor_result or advisor_redacted_result block carries stop_reason='max_tokens', and a truncation note is appended to the advice text the worker model sees (inside the encrypted blob in redacted mode). When set, the server also emits a remaining-tokens budget block in the advisor's prompt so the advisor self-shapes toward the cap. When omitted, the advisor model's default output cap applies and no budget block is emitted. + minimum: 1024 + - `max_uses: optional number or null` Maximum number of times the tool can be used in the API request. + exclusiveMinimum: 0 + - `strict: optional boolean` When true, guarantees schema validation on tool names and inputs - - `BetaToolSearchToolBm25_20251119 object { name, type, allowed_callers, 3 more }` + - `BetaToolSearchToolBm25_20251119 object` - `name: "tool_search_tool_bm25"`
from line 3554
This is how the tool will be called by the model and in `tool_use` blocks. + - `type: "tool_search_tool_bm25_20251119" or "tool_search_tool_bm25"` + + - `"tool_search_tool_bm25_20251119"` + - `"tool_search_tool_bm25"` - - `type: "tool_search_tool_bm25_20251119" or "tool_search_tool_bm25"` - - - `"tool_search_tool_bm25_20251119"` - - - `"tool_search_tool_bm25"` - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"`
from line 3582
When true, guarantees schema validation on tool names and inputs - - `BetaToolSearchToolRegex20251119 object { name, type, allowed_callers, 3 more }` + - `BetaToolSearchToolRegex20251119 object` - `name: "tool_search_tool_regex"`
from line 3590
This is how the tool will be called by the model and in `tool_use` blocks. + - `type: "tool_search_tool_regex_20251119" or "tool_search_tool_regex"` + + - `"tool_search_tool_regex_20251119"` + - `"tool_search_tool_regex"` - - `type: "tool_search_tool_regex_20251119" or "tool_search_tool_regex"` - - - `"tool_search_tool_regex_20251119"` - - - `"tool_search_tool_regex"` - - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` - `"direct"`
from line 3618
When true, guarantees schema validation on tool names and inputs - - `BetaMCPToolset object { mcp_server_name, type, cache_control, 2 more }` + - `BetaMCPToolset object` Configuration for a group of tools from an MCP server.
from line 3629
Name of the MCP server to configure tools for + maxLength: 255, minLength: 1 + - `type: "mcp_toolset"` - - `"mcp_toolset"` - - `cache_control: optional BetaCacheControlEphemeral or null` Create a cache control breakpoint at this content block.
from line 3653
- `enabled: optional boolean` -### Returns - -- `BetaMessageTokensCount object { context_management, input_tokens }` +- `output_format: optional BetaJSONOutputFormat or null` + + **Deprecated** + + Deprecated: Use `output_config.format` instead. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) + + A schema to specify Claude's output format in responses. This parameter will be removed in a future release. + +## Returns + +- `BetaMessageTokensCount object` - `context_management: BetaCountTokensContextManagementResponse or null`
from line 3677
The total number of tokens across the provided list of messages, system prompt, and tools. -### Example - -```http +## Example + +```bash curl https://api.anthropic.com/v1/messages/count_tokens \ -H 'Content-Type: application/json' \ -H 'anthropic-version: 2023-06-01' \
from line 3719
}' ``` -#### Response +### Response (200) ```json {
api/beta/messages/count_tokens Changed · +885 / -129 lines
The two sides of this change are too far apart to line up, so this is the differ's own diff of it.
from line 21
- `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" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 31 more` - `"message-batches-2024-09-24"`
from line 66
- `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` + + - `"user-profiles-2026-08-18"` - `"advisor-tool-2026-03-01"`
from line 291
- `"search_result_location"` - - `BetaImageBlockParam object { source, type, cache_control }` + - `BetaImageBlockParam object { source, type, cache_control, transformations }` - `source: BetaBase64ImageSource or BetaURLImageSource or BetaFileImageSource`
from line 337
Create a cache control breakpoint at this content block. + - `transformations: optional BetaImageTransformationsParam or null` + + Configures the transformations the server applies to this image before the model observes it. Each key names a condition the server transforms images for; its value selects the transformation applied. Omitted keys keep their default behavior, and an empty object is equivalent to omitting the field. + + - `oversized_image: optional "downsize" or "error"` + + What the server does when this image exceeds the model's maximum image size. `"downsize"` (the default) scales the image down to fit, which changes the dimensions the model observes without telling you. `"error"` instead rejects the request with a 400 error naming the image's dimensions and the largest dimensions that fit, so you can scale the image deliberately — your image is never silently scaled down. + + - `"downsize"` + + - `"error"` + - `BetaRequestDocumentBlock object { source, type, cache_control, 3 more }` - `source: BetaBase64PDFSource or BetaPlainTextSource or BetaContentBlockSource or 2 more`
from line 387
- `BetaTextBlockParam object { text, type, cache_control, citations }` - - `BetaImageBlockParam object { source, type, cache_control }` + - `BetaImageBlockParam object { source, type, cache_control, transformations }` - `type: "content"`
from line 479
- `"redacted_thinking"` - - `BetaToolUseBlockParam object { id, input, name, 3 more }` + - `BetaToolUseBlockParam object { id, input, name, 4 more }` - `id: string`
from line 525
- `"code_execution_20260120"` - - `BetaToolResultBlockParam object { tool_use_id, type, cache_control, 2 more }` + - `toolset_name: optional string or null` + + For a toolset member tool_use, the toolset family this member belongs to. + + - `BetaToolResultBlockParam object { tool_use_id, type, cache_control, 3 more }` - `tool_use_id: string`
from line 541
Create a cache control breakpoint at this content block. - - `content: optional string or array of BetaTextBlockParam or BetaImageBlockParam or BetaSearchResultBlockParam or 2 more` + - `content: optional string or array of BetaTextBlockParam or BetaImageBlockParam or BetaSearchResultBlockParam or 3 more` - `string` - - `array of BetaTextBlockParam or BetaImageBlockParam or BetaSearchResultBlockParam or 2 more` + - `array of BetaTextBlockParam or BetaImageBlockParam or BetaSearchResultBlockParam or 3 more` - `BetaTextBlockParam object { text, type, cache_control, citations }` - - `BetaImageBlockParam object { source, type, cache_control }` + - `BetaImageBlockParam object { source, type, cache_control, transformations }` - `BetaSearchResultBlockParam object { content, source, title, 3 more }`
from line 569
Create a cache control breakpoint at this content block. + - `BetaBrowserStateBlockParam object { tabs, type, cache_control, state_changes }` + + The caller's browser state after a browser toolset member call — + the full inventory of open tabs, which tab is active, and any side + effects (tabs opened, download state changes) the call produced. + + At most one per `tool_result`, only on a non-error result answering a + browser toolset member `tool_use`. The server renders the + model-visible text from it; the model never sees the raw fields. + + - `tabs: array of BetaBrowserStateTabEntry` + + All tabs open in the browser after this call — the full inventory, not a delta. May be empty. Whenever non-empty, exactly one entry carries `active: true`. + + - `tab_id: string` + + The caller-assigned identifier for this tab, unique within the inventory. + + - `title: string` + + The title of the page the tab is showing. May be empty. + + - `url: string` + + The URL of the page the tab is showing. May be empty. + + - `active: optional boolean` + + Whether this tab is the active tab after this call. Whenever `tabs` is non-empty, exactly one entry is marked `active: true`. + + - `type: "browser_state"` + + - `"browser_state"` + + - `cache_control: optional BetaCacheControlEphemeral or null` + + Create a cache control breakpoint at this content block. + + - `state_changes: optional array of BetaBrowserStateChange or null` + + Tabs opened and download state changes during this call. "Nothing to report" is expressed by omitting the field, never by an empty list. + + - `BetaBrowserStateChangeTabOpened object { tab_id, type }` + + A tab this call's execution opened that remains open at its end — + the creation delta of the `tabs` inventory, not an event log. + + Carries only the `tab_id`; the tab's `title` and `url` live on its + `tabs` entry, which must include the same `tab_id`. A tab opened + during a failed call gets no deferred `tab_opened`; it simply appears + in the next result's `tabs` inventory. + + - `tab_id: string` + + The `tab_id` of the opened tab, present in `tabs`. + + - `type: "tab_opened"` + + - `"tab_opened"` + + - `BetaBrowserStateChangeDownloadStarted object { download_id, type, url }` + + A file download that started during this call. + + - `download_id: string` + + The caller-assigned identifier for this download, stable across the state changes reporting it. + + - `type: "download_started"` + + - `"download_started"` + + - `url: string` + + The final post-redirect URL the download was served from. + + - `BetaBrowserStateChangeDownloadCompleted object { download_id, type, url, 2 more }` + + A file download that finished during this call, reported with the + same `download_id` as its `download_started` — or without a prior + `download_started`, when the download finished during the call that + started it (at most one state change per `download_id` per result). + + - `download_id: string` + + The caller-assigned identifier for this download, stable across the state changes reporting it. + + - `type: "download_completed"` + + - `"download_completed"` + + - `url: string` + + The final post-redirect URL the download was served from. + + - `path: optional string or null` + + Where the executor saved the file, on the executor's filesystem. Only included when another tool in the same environment can read the file at that path. + + - `size_bytes: optional number or null` + + The completed download's size. + + - `BetaBrowserStateChangeDownloadFailed object { download_id, type, url, error }` + + A file download that failed — or was cancelled — during this call. + + - `download_id: string` + + The caller-assigned identifier for this download, stable across the state changes reporting it. + + - `type: "download_failed"` + + - `"download_failed"` + + - `url: string` + + The final post-redirect URL the download was served from. + + - `error: optional string or null` + + The failure or cancellation detail, when known. + - `is_error: optional boolean` + + - `toolset_name: optional string or null` + + For a toolset member tool_result, the toolset family of the paired tool_use. - `BetaServerToolUseBlockParam object { id, input, name, 3 more }`
from line 1276
- `encrypted_content: optional string or null` Opaque metadata from prior compaction, to be round-tripped verbatim - - - `BetaMidConversationSystemBlockParam object { content, type, cache_control }` - - System instructions that appear mid-conversation. - - Use this block to provide or update system-level instructions at a specific - point in the conversation, rather than only via the top-level `system` parameter. - - - `content: array of BetaTextBlockParam or BetaRequestToolAdditionBlock or BetaRequestToolRemovalBlock` - - System instruction text blocks. - - - `BetaTextBlockParam object { text, type, cache_control, citations }` - - - `BetaRequestToolAdditionBlock object { tool, type, cache_control }` - - Mid-conversation directive to surface a declared tool. - - `tool` references a tool (or MCP toolset) by name from the request's - `tools`; it is offered to the model from this point in the - conversation onward. - - - `tool: BetaToolChangeToolReference or BetaToolChangeMCPToolReference or BetaToolChangeMCPToolsetReference` - - Reference to a single tool the caller declared directly in - `tools[]`. Does not accept the composed `{server}_{name}` form the - server assigns to MCP-resolved tools — use `mcp_tool_reference` or - `mcp_toolset_reference` for those. - - - `BetaToolChangeToolReference object { name, type }` - - Reference to a single tool the caller declared directly in - `tools[]`. Does not accept the composed `{server}_{name}` form the - server assigns to MCP-resolved tools — use `mcp_tool_reference` or - `mcp_toolset_reference` for those. - - - `name: string` - - - `type: "tool_reference"` - - - `"tool_reference"` - - - `BetaToolChangeMCPToolReference object { name, server_name, type }` - - Reference to a single MCP tool by its server and remote name — the - same `server_name`/`name` pair `mcp_tool_use` carries. - - - `name: string` - - - `server_name: string` - - - `type: "mcp_tool_reference"` - - - `"mcp_tool_reference"` - - - `BetaToolChangeMCPToolsetReference object { server_name, type }` - - Reference to every tool in the named MCP server's toolset. - - - `server_name: string` - - - `type: "mcp_toolset_reference"` - - - `"mcp_toolset_reference"` - - - `type: "tool_addition"` - - - `"tool_addition"` - - - `cache_control: optional BetaCacheControlEphemeral or null` - - Create a cache control breakpoint at this content block. - - - `BetaRequestToolRemovalBlock object { tool, type, cache_control }` - - Mid-conversation directive to withdraw a tool. - - `tool` references a tool (or MCP toolset) by name from the request's - `tools`; it is no longer offered to the model from this point in the - conversation onward. - - - `tool: BetaToolChangeToolReference or BetaToolChangeMCPToolReference or BetaToolChangeMCPToolsetReference` - - Reference to a single tool the caller declared directly in - `tools[]`. Does not accept the composed `{server}_{name}` form the - server assigns to MCP-resolved tools — use `mcp_tool_reference` or - `mcp_toolset_reference` for those. - - - `BetaToolChangeToolReference object { name, type }` - - Reference to a single tool the caller declared directly in - `tools[]`. Does not accept the composed `{server}_{name}` form the - server assigns to MCP-resolved tools — use `mcp_tool_reference` or - `mcp_toolset_reference` for those. - - - `BetaToolChangeMCPToolReference object { name, server_name, type }` - - Reference to a single MCP tool by its server and remote name — the - same `server_name`/`name` pair `mcp_tool_use` carries. - - - `BetaToolChangeMCPToolsetReference object { server_name, type }` - - Reference to every tool in the named MCP server's toolset. - - - `type: "tool_removal"` - - - `"tool_removal"` - - - `cache_control: optional BetaCacheControlEphemeral or null` - - Create a cache control breakpoint at this content block. - - - `type: "mid_conv_system"` - - - `"mid_conv_system"` - - - `cache_control: optional BetaCacheControlEphemeral or null` - - Create a cache control breakpoint at this content block. - `BetaRequestToolAdditionBlock object { tool, type, cache_control }`
from line 1285
`tools`; it is offered to the model from this point in the conversation onward. + - `tool: BetaToolChangeToolReference or BetaToolChangeMCPToolReference or BetaToolChangeMCPToolsetReference` + + Reference to a single tool the caller declared directly in + `tools[]`. Does not accept the composed `{server}_{name}` form the + server assigns to MCP-resolved tools — use `mcp_tool_reference` or + `mcp_toolset_reference` for those. + + - `BetaToolChangeToolReference object { name, type }` + + Reference to a single tool the caller declared directly in + `tools[]`. Does not accept the composed `{server}_{name}` form the + server assigns to MCP-resolved tools — use `mcp_tool_reference` or + `mcp_toolset_reference` for those. + + - `name: string` + + - `type: "tool_reference"` + + - `"tool_reference"` + + - `BetaToolChangeMCPToolReference object { name, server_name, type }` + + Reference to a single MCP tool by its server and remote name — the + same `server_name`/`name` pair `mcp_tool_use` carries. + + - `name: string` + + - `server_name: string` + + - `type: "mcp_tool_reference"` + + - `"mcp_tool_reference"` + + - `BetaToolChangeMCPToolsetReference object { server_name, type }` + + Reference to every tool in the named MCP server's toolset. + + - `server_name: string` + + - `type: "mcp_toolset_reference"` + + - `"mcp_toolset_reference"` + + - `type: "tool_addition"` + + - `"tool_addition"` + + - `cache_control: optional BetaCacheControlEphemeral or null` + + Create a cache control breakpoint at this content block. + - `BetaRequestToolRemovalBlock object { tool, type, cache_control }` Mid-conversation directive to withdraw a tool.
from line 1343
`tool` references a tool (or MCP toolset) by name from the request's `tools`; it is no longer offered to the model from this point in the conversation onward. + + - `tool: BetaToolChangeToolReference or BetaToolChangeMCPToolReference or BetaToolChangeMCPToolsetReference` + + Reference to a single tool the caller declared directly in + `tools[]`. Does not accept the composed `{server}_{name}` form the + server assigns to MCP-resolved tools — use `mcp_tool_reference` or + `mcp_toolset_reference` for those. + + - `BetaToolChangeToolReference object { name, type }` + + Reference to a single tool the caller declared directly in + `tools[]`. Does not accept the composed `{server}_{name}` form the + server assigns to MCP-resolved tools — use `mcp_tool_reference` or + `mcp_toolset_reference` for those. + + - `BetaToolChangeMCPToolReference object { name, server_name, type }` + + Reference to a single MCP tool by its server and remote name — the + same `server_name`/`name` pair `mcp_tool_use` carries. + + - `BetaToolChangeMCPToolsetReference object { server_name, type }` + + Reference to every tool in the named MCP server's toolset. + + - `type: "tool_removal"` + + - `"tool_removal"` + + - `cache_control: optional BetaCacheControlEphemeral or null` + + Create a cache control breakpoint at this content block. - `BetaFallbackBlockParam object { from, to, type, trigger }`
from line 1825
- `"none"` -- `tools: optional array of BetaTool or BetaToolBash20241022 or BetaToolBash20250124 or 23 more` +- `tools: optional array of BetaTool or BetaToolBash20241022 or BetaToolBash20250124 or 25 more` Definitions of tools that the model may use.
from line 2173
When true, guarantees schema validation on tool names and inputs + - `BetaBrowserToolset20260801 object { type, allowed_callers, cache_control, configs }` + + The browser toolset: a single `tools[]` entry (carrying no + `name`) that declares the browser tool family. The model is served + the family's tool with any members disabled via `configs` removed + from its schema. + + - `type: "browser_toolset_20260801"` + + - `"browser_toolset_20260801"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `"code_execution_20260521"` + + - `cache_control: optional BetaCacheControlEphemeral or null` + + Create a cache control breakpoint at this content block. + + - `configs: optional BetaBrowserToolsetConfigs or null` + + Per-member configuration for `browser_toolset_20260801`: one + optional field per member tool, keyed by the member name — the same + name the member's `tool_use` blocks carry. Every member is an + accepted key, and a member's defaults apply wherever its key is + absent. Unknown keys are rejected: the field set is this toolset + version's complete member set. + + - `close_tab: optional BetaBrowserCloseTabConfig or null` + + `close_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. + + - `double_click: optional BetaBrowserDoubleClickConfig or null` + + `double_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 enabled resolves false is withheld from the served schema. + + - `file_upload: optional BetaBrowserFileUploadConfig or null` + + `file_upload`'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. + + - `find: optional BetaBrowserFindConfig or null` + + `find`'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. + + - `form_input: optional BetaBrowserFormInputConfig or null` + + `form_input`'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. + + - `get_page_text: optional BetaBrowserGetPageTextConfig or null` + + `get_page_text`'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. + + - `hold_key: optional BetaBrowserHoldKeyConfig or null` + + `hold_key`'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. + + - `hover: optional BetaBrowserHoverConfig or null` + + `hover`'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. + + - `javascript_exec: optional BetaBrowserJavascriptExecConfig or null` + + `javascript_exec`'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. + + - `key: optional BetaBrowserKeyConfig or null` + + `key`'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. + + - `left_click: optional BetaBrowserLeftClickConfig or null` + + `left_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 enabled resolves false is withheld from the served schema. + + - `left_click_drag: optional BetaBrowserLeftClickDragConfig or null` + + `left_click_drag`'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. + + - `left_mouse_down: optional BetaBrowserLeftMouseDownConfig or null` + + `left_mouse_down`'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. + + - `left_mouse_up: optional BetaBrowserLeftMouseUpConfig or null` + + `left_mouse_up`'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. + + - `list_tabs: optional BetaBrowserListTabsConfig or null` + + `list_tabs`'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. + + - `middle_click: optional BetaBrowserMiddleClickConfig or null` + + `middle_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 enabled resolves false is withheld from the served schema. + + - `mouse_move: optional BetaBrowserMouseMoveConfig or null` + + `mouse_move`'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. + + - `navigate: optional BetaBrowserNavigateConfig or null` + + `navigate`'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. + + - `new_tab: optional BetaBrowserNewTabConfig or null` + + `new_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. + + - `read_console: optional BetaBrowserReadConsoleConfig or null` + + `read_console`'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. + + - `read_network: optional BetaBrowserReadNetworkConfig or null` + + `read_network`'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. + + - `read_page: optional BetaBrowserReadPageConfig or null` + + `read_page`'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. + + - `right_click: optional BetaBrowserRightClickConfig or null` + + `right_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 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 enabled resolves false is withheld from the served schema. + + - `type: optional BetaBrowserTypeConfig or null` + + `type`'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. + + - `wait: optional BetaBrowserWaitConfig or null` + + `wait`'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. + + - `zoom: optional BetaBrowserZoomConfig or null` + + `zoom`'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. + - `BetaToolComputerUse20241022 object { display_height_px, display_width_px, name, 7 more }` - `display_height_px: number`
from line 2808
- `strict: optional boolean` When true, guarantees schema validation on tool names and inputs + + - `BetaComputerToolset20260801 object { type, allowed_callers, cache_control, configs }` + + The computer toolset: a single `tools[]` entry (carrying no + `name`) that declares the computer tool family. The model is + served the family's tool with any members disabled via `configs` + removed from its schema. Every member is enabled by default, zoom + included. The single-tool options `display_number` and + `enable_zoom` are not fields of a toolset entry — it carries only + `type`, `configs`, and `cache_control`; zoom is controlled + via `configs.zoom.enabled`. + + - `type: "computer_toolset_20260801"` + + - `"computer_toolset_20260801"` + + - `allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120" or "code_execution_20260521"` + + - `"direct"` + + - `"code_execution_20250825"` + + - `"code_execution_20260120"` + + - `"code_execution_20260521"` + + - `cache_control: optional BetaCacheControlEphemeral or null` + + Create a cache control breakpoint at this content block. + + - `configs: optional BetaComputerToolsetConfigs or null` + + Per-member configuration for `computer_toolset_20260801`: one + optional field per member tool, keyed by the member name — the same + name the member's `tool_use` blocks carry. Every member is an + accepted key, and a member's defaults apply wherever its key is + absent. Unknown keys are rejected: the field set is this toolset + version's complete member set. + + - `cursor_position: optional BetaComputerCursorPositionConfig or null` + + `cursor_position`'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. + + - `double_click: optional BetaComputerDoubleClickConfig or null` + + `double_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 enabled resolves false is withheld from the served schema. + + - `hold_key: optional BetaComputerHoldKeyConfig or null` + + `hold_key`'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. + + - `key: optional BetaComputerKeyConfig or null` + + `key`'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. + + - `left_click: optional BetaComputerLeftClickConfig or null` + + `left_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 enabled resolves false is withheld from the served schema. + + - `left_click_drag: optional BetaComputerLeftClickDragConfig or null` + + `left_click_drag`'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. + + - `left_mouse_down: optional BetaComputerLeftMouseDownConfig or null` + + `left_mouse_down`'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. + + - `left_mouse_up: optional BetaComputerLeftMouseUpConfig or null` + + `left_mouse_up`'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. + + - `middle_click: optional BetaComputerMiddleClickConfig or null` + + `middle_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 enabled resolves false is withheld from the served schema. + + - `mouse_move: optional BetaComputerMouseMoveConfig or null` + + `mouse_move`'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. + + - `right_click: optional BetaComputerRightClickConfig or null` + + `right_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 enabled resolves false is withheld from the served schema. + + - `screenshot: optional BetaComputerScreenshotConfig 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 BetaComputerScrollConfig 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. + + - `triple_click: optional BetaComputerTripleClickConfig 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 enabled resolves false is withheld from the served schema. + + - `type: optional BetaComputerTypeConfig or null` + + `type`'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. + + - `wait: optional BetaComputerWaitConfig or null` + + `wait`'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. + + - `zoom: optional BetaComputerZoomConfig or null` + + `zoom`'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. - `BetaToolTextEditor20250124 object { name, type, allowed_callers, 4 more }`
from line 3790
"role": "user" } ], - "model": "claude-opus-4-6", + "model": "claude-opus-5", "system": [ { "text": "Today'\''s date is 2024-06-01.",
api/beta/messages/count_tokens First recorded · 3074 lines, first recorded
## Count tokens in a Message ### Header Parameters ### Body Parameters ### Returns ### Example #### Response
The first capture of this source. The page was already there, and this is what it said.
---
title: Count tokens in a Message
url: https://platform.claude.com/docs/en/api/beta/messages/count_tokens
---
## Count tokens in a Message
**post** `/v1/messages/count_tokens`
Count the number of tokens in a Message.
The Token Count API can be used to count the number of tokens in a Message, including tools, images, and documents, without creating it.
Learn more about token counting in our [user guide](https://platform.claude.com/docs/en/build-with-claude/token-counting)
### 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
- `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"`
- `"search_result_location"`
- `BetaImageBlockParam object { source, type, cache_control }`
- `source: BetaBase64ImageSource or BetaURLImageSource or BetaFileImageSource`
- `BetaBase64ImageSource object { data, media_type, type }`
- `data: string`
- `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"`
Cut at 300 lines.