Messages
Count tokens in a Message
beta.messages.count_tokens(**kwargs) -> BetaMessageTokensCountModels
BetaBrowserStateChange = BetaBrowserStateChangeTabOpened { tab_id, type } | BetaBrowserStateChangeDownloadStarted { download_id, type, url } | BetaBrowserStateChangeDownloadCompleted { download_id, type, url, 2 more } | BetaBrowserStateChangeDownloadFailed { download_id, type, url, error }A tab this call's execution opened that remains open at its end —
the creation delta of the tabs inventory, not an event log.
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.
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).
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).
tab_id is the caller-assigned identifier for the tab; title and
url describe the page the tab is currently showing and may be empty
strings (a blank tab legitimately has both empty). active marks the
tab that is active after this call; whenever tabs is non-empty,
exactly one entry is marked.
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.
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.
This may be one the following values:
5m: 5 minutes1h: 1 hour
Defaults to 5m. See prompt caching pricing for details.
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.
Always greater than start_block_index; a single-block citation has end_block_index = start_block_index + 1.
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.
Always greater than start_block_index; a single-block citation has end_block_index = start_block_index + 1.
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.
Always greater than start_block_index; a single-block citation has end_block_index = start_block_index + 1.
Counted separately from document_index; server-side web search results are not included in this count.
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.
Always greater than start_block_index; a single-block citation has end_block_index = start_block_index + 1.
Counted separately from document_index; server-side web search results are not included in this count.
BetaCodeExecutionToolResultBlockContent = BetaCodeExecutionToolResultError { error_code, type } | BetaCodeExecutionResultBlock { content, return_code, stderr, 2 more } | BetaEncryptedCodeExecutionResultBlock { content, encrypted_stdout, return_code, 2 more }Code execution result with encrypted stdout for PFC + web_search results.
Code execution result with encrypted stdout for PFC + web_search results.
Create a cache control breakpoint at this content block.
Create a cache control breakpoint at this content block.
This may be one the following values:
5m: 5 minutes1h: 1 hour
Defaults to 5m. See prompt caching pricing for details.
BetaCodeExecutionToolResultBlockParamContent = BetaCodeExecutionToolResultErrorParam { error_code, type } | BetaCodeExecutionResultBlockParam { content, return_code, stderr, 2 more } | BetaEncryptedCodeExecutionResultBlockParam { content, encrypted_stdout, return_code, 2 more }Code execution result with encrypted stdout for PFC + web_search results.
Code execution result with encrypted stdout for PFC + web_search results.
Users should round-trip these blocks from responses to subsequent requests to maintain context across compaction boundaries.
When content is None, the block represents a failed compaction. The server treats these as no-ops. Empty string content is not allowed.
Create a cache control breakpoint at this content block.
Create a cache control breakpoint at this content block.
This may be one the following values:
5m: 5 minutes1h: 1 hour
Defaults to 5m. See prompt caching pricing for details.
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.
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.
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.
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.
Create a cache control breakpoint at this content block.
Create a cache control breakpoint at this content block.
This may be one the following values:
5m: 5 minutes1h: 1 hour
Defaults to 5m. See prompt caching pricing for details.
BetaContentBlock = BetaTextBlock { citations, text, type } | BetaThinkingBlock { signature, thinking, type } | BetaRedactedThinkingBlock { data, type } | 14 moreResponse model for a file uploaded to the container.
Response model for a file uploaded to the container.
BetaContentBlockParam = BetaTextBlockParam { text, type, cache_control, citations } | BetaImageBlockParam { source, type, cache_control, transformations } | BetaRequestDocumentBlock { source, type, cache_control, 3 more } | 20 moreRegular text content.
Regular text content.
BetaContentBlockSourceContent = BetaTextBlockParam { text, type, cache_control, citations } | BetaImageBlockParam { source, type, cache_control, transformations }
The id (msg_...) from this client's previous /v1/messages response. The server compares that request's prompt fingerprint against this one and returns diagnostics.cache_miss_reason when the prompt-cache prefix could not be reused. Pass null on the first turn to opt in without a prior message to compare.
The id (msg_...) from this client's previous /v1/messages response. The server compares that request's prompt fingerprint against this one and returns diagnostics.cache_miss_reason when the prompt-cache prefix could not be reused. Pass null on the first turn to opt in without a prior message to compare.
One block appears per hop where a preceding model actually ran this turn and
declined. A turn where no preceding model ran and declined has no such
boundary and carries no block — the signal for whether a fallback model
served the response is the presence of a fallback_message entry in
usage.iterations, not this block.
The block is treated like a server-tool content block for streaming: it
arrives via the standard content_block_start / content_block_stop
pair and carries no deltas.
Accepted in messages[].content and not rendered into the prompt; not
validated against the request's fallbacks chain or top-level model.
Echo the assistant turn back verbatim, including this block in its original position. The block marks the boundary between content produced before and after a fallback hop, and the server relies on that boundary to validate the turn: when thinking runs flank the boundary, omitting the block merges them into one span the server cannot validate (the request is rejected), and moving it into the middle of a single run is likewise rejected; between non-thinking blocks the block's placement has no validation effect.
Requires anthropic-beta: fallback-credit-2026-07-01; without that
header the field accepts the bare string only. The bare string and the
mode-less object are equivalent (both select strict), so wrapping
an existing token changes nothing by itself.
How a failing token affects the retry. strict (the default, and the bare-string behavior): a failing redemption is a 400 and the retry is not served. best_effort: the retry is served either way — a token-layer failure no longer rejects the request; the retry proceeds at normal price and the outcome is reported on the response's usage.fallback_credit. Two failures stay hard in both modes: a malformed token, and combining fallback_credit_token with fallbacks.
How a failing token affects the retry. strict (the default, and the bare-string behavior): a failing redemption is a 400 and the retry is not served. best_effort: the retry is served either way — a token-layer failure no longer rejects the request; the retry proceeds at normal price and the outcome is reported on the response's usage.fallback_credit. Two failures stay hard in both modes: a malformed token, and combining fallback_credit_token with fallbacks.
status: BetaFallbackCreditRedeemed { type } | BetaFallbackCreditNotApplied { reason, type, remove_to_redeem }Whether the fallback-credit reprice was applied to this response's billing.
Whether the fallback-credit reprice was applied to this response's billing.
A union discriminated on type. redeemed: the retry is billed as if
the conversation had been on the retry model all along — including when the
resulting shift is zero because there was nothing to move. not_applied:
no reprice was applied; the arm's reason says why.
The request could enable cyber harm, such as malware or exploit development. Benign cybersecurity work can also trigger this category.
The request could enable biological harm, such as dangerous lab methods. Beneficial life sciences work can also trigger this category.
The request could assist the development of competing AI models, which is restricted under Anthropic's commercial terms. Benign machine learning work can also trigger this category.
The request asks the model to reproduce its internal reasoning in the response text. To get reasoning in a structured form instead, use adaptive thinking.
BetaFallbacksParam = Array[BetaFallbackParam { model, max_tokens, output_config, 2 more }] | :defaultOpt-in server-side retry on one or more substitute models when the requested model declines for policy reasons. Tried in order: if the first entry also declines, the second is tried, and so on. The string "default" requests the requested model's server-defined default fallback configuration.
Opt-in server-side retry on one or more substitute models when the requested model declines for policy reasons. Tried in order: if the first entry also declines, the second is tried, and so on. The string "default" requests the requested model's server-defined default fallback configuration.
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.
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.
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.
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.
BetaIterationsUsage = Array[BetaMessageIterationUsage { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 4 more } | BetaCompactionIterationUsage { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more } | BetaAdvisorMessageIterationUsage { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 4 more } | BetaFallbackMessageIterationUsage { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 4 more }]Per-iteration token usage breakdown.
Per-iteration token usage breakdown.
Each entry represents one sampling iteration, with its own input/output token counts and cache statistics, discriminated by type. For message entries (model sampling iterations, such as the turns of a server-side tool use loop), this allows you to:
- Determine which iterations exceeded long context thresholds (>=200k tokens)
- Calculate the context window size from the last
messageentry - Understand token accumulation across server-side tool use loops
A compaction entry reports the token usage of the compaction operation itself — the server-side request that summarizes the context being closed — NOT the size of the context that was compacted away, and its token counts can be much smaller than that closed context (for example, a compaction that closes a ~200k-token context can report only a few thousand tokens). Do not derive the context window size from a compaction entry, even when it is the last entry. A compaction entry's tokens are not included in the top-level usage fields. When an input-token trigger is in effect (the default — 150,000 tokens unless configured otherwise), each compaction entry closes a context that had reached at least that threshold, though the context can exceed it by the final iteration's output and tool results.
Create a cache control breakpoint at this content block.
Create a cache control breakpoint at this content block.
This may be one the following values:
5m: 5 minutes1h: 1 hour
Defaults to 5m. See prompt caching pricing for details.
BetaMemoryTool20250818Command = BetaMemoryTool20250818ViewCommand { command, path, view_range } | BetaMemoryTool20250818CreateCommand { command, file_text, path } | BetaMemoryTool20250818StrReplaceCommand { command, new_str, old_str, path } | 3 more
The model that will complete your prompt.
The model that will complete your prompt.
See models for additional details and options.
Reflects the raw reasoning the model produced, not the (possibly shorter)
summarized thinking text returned in the response body. Computed by
re-tokenizing the raw reasoning text, so it may differ from the model's exact
generation count by a small number of tokens. Always ≤ output_tokens;
output_tokens - thinking_tokens approximates the non-reasoning output.
BetaRawContentBlockDelta = BetaTextDelta { text, type } | BetaInputJSONDelta { partial_json, type } | BetaCitationsDelta { citation, type } | 3 more
BetaRawMessageStreamEvent = BetaRawMessageStartEvent { message, type } | BetaRawMessageDeltaEvent { context_management, delta, type, usage } | BetaRawMessageStopEvent { type } | 3 more
Pass redacted_thinking blocks back to the API unchanged when continuing a multi-turn conversation.
See extended thinking for details.
BetaTextCitation = BetaCitationCharLocation { cited_text, document_index, document_title, 4 more } | BetaCitationPageLocation { cited_text, document_index, document_title, 4 more } | BetaCitationContentBlockLocation { cited_text, document_index, document_title, 4 more } | 2 more
BetaTextCitationParam = BetaCitationCharLocationParam { cited_text, document_index, document_title, 3 more } | BetaCitationPageLocationParam { cited_text, document_index, document_title, 3 more } | BetaCitationContentBlockLocationParam { cited_text, document_index, document_title, 3 more } | 2 more
This is an opaque field and should not be interpreted or parsed. When passing thinking blocks back to the API (required when using tools with extended thinking), pass them back exactly as received, with this field intact.
See extended thinking for details.
Must be ≥1024 and less than max_tokens.
See extended thinking for details.
BetaThinkingConfigParam = BetaThinkingConfigEnabled { budget_tokens, type, display_ } | BetaThinkingConfigDisabled { type } | BetaThinkingConfigAdaptive { type, display_ }Configuration for enabling Claude's extended thinking.
Configuration for enabling Claude's extended thinking.
When enabled, responses include thinking content blocks showing Claude's thinking process before the final answer. Requires a minimum budget of 1,024 tokens and counts towards your max_tokens limit.
See extended thinking for details.
Per-frame increment of a coarse, running estimate of the tokens this thinking block has produced so far. Present whenever the thinking-token-count-2026-05-13 beta is set; null unless thinking.display resolves to "omitted" and a count is due this frame. Sum the increments across thinking_delta frames on this block for a progress indicator. Each increment is a non-negative multiple of a fixed quantum and the cadence is rate-limited, so this is a deliberately lossy display hint, not a billable count; usage.output_tokens remains authoritative.
BetaToolChoice = BetaToolChoiceAuto { type, disable_parallel_tool_use } | BetaToolChoiceAny { type, disable_parallel_tool_use } | BetaToolChoiceTool { name, type, disable_parallel_tool_use } | BetaToolChoiceNone { type }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.
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.
Create a cache control breakpoint at this content block.
Create a cache control breakpoint at this content block.
This may be one the following values:
5m: 5 minutes1h: 1 hour
Defaults to 5m. See prompt caching pricing for details.
BetaToolUnion = BetaTool { input_schema, name, allowed_callers, 7 more } | BetaToolBash20241022 { name, type, allowed_callers, 4 more } | BetaToolBash20250124 { name, type, allowed_callers, 4 more } | 25 moreCode execution tool with REPL state persistence (daemon mode + gVisor checkpoint).
Code execution tool with REPL state persistence (daemon mode + gVisor checkpoint).
The two letter ISO country code of the user.
The two letter ISO country code of the user.
The IANA timezone of the user.
The IANA timezone of the user.