Messaggi

Crea un messaggio

client.beta.messages.create(params, options?): BetaMessage | Stream<BetaRawMessageStreamEvent>

POST/v1/messages

Invia un elenco strutturato di messaggi di input con contenuto testuale e/o immagini, e il modello genererà il messaggio successivo nella conversazione.

Conta i token in un messaggio

client.beta.messages.countTokens(params, options?): BetaMessageTokensCount

POST/v1/messages/count_tokens

Conta il numero di token in un messaggio.

Models

interface BetaAdvisorMessageIterationUsage { type: "advisor_message"; cache_creation; cache_creation_input_tokens; /* 4 more */ }

Token usage for an advisor sub-inference iteration.

interface BetaAdvisorRedactedResultBlock { type: "advisor_redacted_result"; encrypted_content; stop_reason }

type: "advisor_redacted_result"

defaultadvisor_redacted_result

encrypted_content: string

Opaque blob containing the advisor's output. Round-trip verbatim; do not inspect or modify.

stop_reason: string | null

The advisor sub-inference's stop reason (same values as the top-level message stop_reason).

interface BetaAdvisorRedactedResultBlockParam { type: "advisor_redacted_result"; encrypted_content; stop_reason }

type: "advisor_redacted_result"

encrypted_content: string

Opaque blob produced by a prior response; must be round-tripped verbatim.

stop_reason?: string | null

interface BetaAdvisorResultBlock { type: "advisor_result"; stop_reason; text }

type: "advisor_result"

defaultadvisor_result

stop_reason: string | null

The advisor sub-inference's stop reason (same values as the top-level message stop_reason). max_tokens indicates the advisor's output was truncated at the tool's max_tokens value or the advisor model's policy cap.

text: string

interface BetaAdvisorResultBlockParam { type: "advisor_result"; text; stop_reason }

type: "advisor_result"

text: string

stop_reason?: string | null

interface BetaAdvisorTool20260301 { type: "advisor_20260301"; model; name; /* 7 more */ }

interface BetaAdvisorToolResultBlock { type: "advisor_tool_result"; content; tool_use_id }

interface BetaAdvisorToolResultBlockParam { type: "advisor_tool_result"; content; tool_use_id; cache_control }

interface BetaAdvisorToolResultError { type: "advisor_tool_result_error"; error_code }

type: "advisor_tool_result_error"

defaultadvisor_tool_result_error

error_code: "max_uses_exceeded" | "prompt_too_long" | "too_many_requests" | 4 more

One of the following:

"max_uses_exceeded"

"prompt_too_long"

"too_many_requests"

"overloaded"

"unavailable"

"execution_time_exceeded"

"model_not_found"

interface BetaAdvisorToolResultErrorParam { type: "advisor_tool_result_error"; error_code }

type: "advisor_tool_result_error"

error_code: "max_uses_exceeded" | "prompt_too_long" | "too_many_requests" | 4 more

One of the following:

"max_uses_exceeded"

"prompt_too_long"

"too_many_requests"

"overloaded"

"unavailable"

"execution_time_exceeded"

"model_not_found"

interface BetaAllThinkingTurns { type: "all" }

type: "all"

interface BetaBase64ImageSource { type: "base64"; data; media_type }

type: "base64"

data: string

formatbyte

media_type: "image/jpeg" | "image/png" | "image/gif" | "image/webp"

One of the following:

"image/jpeg"

"image/png"

"image/gif"

"image/webp"

interface BetaBase64PDFSource { type: "base64"; data; media_type }

type: "base64"

data: string

formatbyte

media_type: "application/pdf"

interface BetaBashCodeExecutionOutputBlock { type: "bash_code_execution_output"; file_id }

type: "bash_code_execution_output"

defaultbash_code_execution_output

file_id: string

interface BetaBashCodeExecutionOutputBlockParam { type: "bash_code_execution_output"; file_id }

type: "bash_code_execution_output"

file_id: string

interface BetaBashCodeExecutionResultBlock { type: "bash_code_execution_result"; content; return_code; /* 2 more */ }

type: "bash_code_execution_result"

defaultbash_code_execution_result

content: Array<BetaBashCodeExecutionOutputBlock { type: "bash_code_execution_output"; file_id }>

type: "bash_code_execution_output"

defaultbash_code_execution_output

file_id: string

return_code: number

stderr: string

stdout: string

interface BetaBashCodeExecutionResultBlockParam { type: "bash_code_execution_result"; content; return_code; /* 2 more */ }

type: "bash_code_execution_result"

content: Array<BetaBashCodeExecutionOutputBlockParam { type: "bash_code_execution_output"; file_id }>

type: "bash_code_execution_output"

file_id: string

return_code: number

stderr: string

stdout: string

interface BetaBashCodeExecutionToolResultBlock { type: "bash_code_execution_tool_result"; content; tool_use_id }

interface BetaBashCodeExecutionToolResultBlockParam { type: "bash_code_execution_tool_result"; content; tool_use_id; cache_control }

interface BetaBashCodeExecutionToolResultError { type: "bash_code_execution_tool_result_error"; error_code }

type: "bash_code_execution_tool_result_error"

defaultbash_code_execution_tool_result_error

error_code: "invalid_tool_input" | "unavailable" | "too_many_requests" | 2 more

One of the following:

"invalid_tool_input"

"unavailable"

"too_many_requests"

"execution_time_exceeded"

"output_file_too_large"

interface BetaBashCodeExecutionToolResultErrorParam { type: "bash_code_execution_tool_result_error"; error_code }

type: "bash_code_execution_tool_result_error"

error_code: "invalid_tool_input" | "unavailable" | "too_many_requests" | 2 more

One of the following:

"invalid_tool_input"

"unavailable"

"too_many_requests"

"execution_time_exceeded"

"output_file_too_large"

type BetaBrowserClickTarget = BetaBrowserCoordinateTarget | BetaBrowserRefTarget

Where to act: either a viewport coordinate or an element reference.

One of the following:

interface BetaBrowserCoordinateTarget { type: "coordinate"; x; y }

A point in the browser viewport, in viewport pixels (the same frame as a full-viewport screenshot).

type: "coordinate"

x: number

Pixels from the left edge of the viewport.

minimum0

y: number

Pixels from the top edge of the viewport.

minimum0

interface BetaBrowserRefTarget { type: "ref"; ref }

An element on the page, identified by a reference from a prior read_page or find result. References are scoped to the tab that produced them and become stale after navigation or a major re-render.

type: "ref"

ref: string

An element reference (e.g. "ref_7") returned by a prior read_page or find result.

interface BetaBrowserCloseTabConfig { defer_loading; enabled }

close_tab's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | 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.

interface BetaBrowserCloseTabInput { tab_id }

Close the tab with the given tab_id.

tab_id: string

The tab to close.

interface BetaBrowserCloseTabToolUseBlock { type: "tool_use"; id; input; /* 3 more */ }

interface BetaBrowserCoordinateTarget { type: "coordinate"; x; y }

A point in the browser viewport, in viewport pixels (the same frame as a full-viewport screenshot).

type: "coordinate"

x: number

Pixels from the left edge of the viewport.

minimum0

y: number

Pixels from the top edge of the viewport.

minimum0

interface BetaBrowserDoubleClickConfig { defer_loading; enabled }

double_click's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | 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.

interface BetaBrowserDoubleClickInput { target; modifiers; tab_id }

Double left-click at a viewport coordinate or on an element by reference.

interface BetaBrowserDoubleClickToolUseBlock { type: "tool_use"; id; input; /* 3 more */ }

interface BetaBrowserFileUploadConfig { defer_loading; enabled }

file_upload's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | 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.

interface BetaBrowserFileUploadInput { target; document_ids; paths; tab_id }

Set the value of a file-input element to one or more files. The target must be an element reference; at least one of paths or document_ids is required.

target: BetaBrowserRefTarget { type: "ref"; ref }

type: "ref"

ref: string

An element reference (e.g. "ref_7") returned by a prior read_page or find result.

document_ids?: Array<string> | null

References to files the harness has staged, for deployments where the browser executor cannot read the caller's filesystem.

minItems1

paths?: Array<string> | null

File paths on the browser executor's filesystem.

minItems1

tab_id?: string | null

Tab to act on. Defaults to the active tab when omitted.

interface BetaBrowserFileUploadToolUseBlock { type: "tool_use"; id; input; /* 3 more */ }

interface BetaBrowserFindConfig { defer_loading; enabled }

find's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | 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.

interface BetaBrowserFindInput { query; tab_id }

Find elements matching a natural-language description (e.g. "search bar", "add to cart button") and return up to 20 matches with element references.

query: string

Natural-language description of the element(s) to find.

tab_id?: string | null

Tab to act on. Defaults to the active tab when omitted.

interface BetaBrowserFindToolUseBlock { type: "tool_use"; id; input; /* 3 more */ }

interface BetaBrowserFormInputConfig { defer_loading; enabled }

form_input's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | 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.

interface BetaBrowserFormInputInput { target; value; tab_id }

Set the value of a form element (input, textarea, select, checkbox). Use a boolean for checkboxes, an option value or text for selects.

target: BetaBrowserRefTarget { type: "ref"; ref }

type: "ref"

ref: string

An element reference (e.g. "ref_7") returned by a prior read_page or find result.

value: BetaBrowserFormInputValue

The value to set.

One of the following:

string

number

boolean

tab_id?: string | null

Tab to act on. Defaults to the active tab when omitted.

interface BetaBrowserFormInputToolUseBlock { type: "tool_use"; id; input; /* 3 more */ }

type BetaBrowserFormInputValue = string | number | boolean

One of the following:

string

number

boolean

interface BetaBrowserGetPageTextConfig { defer_loading; enabled }

get_page_text's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | 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.

interface BetaBrowserGetPageTextInput { tab_id }

Return the page's visible text content as plain text, prioritizing article content. Suited to articles, documentation, and other text-heavy pages.

tab_id?: string | null

Tab to act on. Defaults to the active tab when omitted.

interface BetaBrowserGetPageTextToolUseBlock { type: "tool_use"; id; input; /* 3 more */ }

interface BetaBrowserHoldKeyConfig { defer_loading; enabled }

hold_key's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | 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.

interface BetaBrowserHoldKeyInput { duration; text; tab_id }

Hold a key or key chord down for a duration, then release it. Uses the same key names and "+" chord syntax as the key action.

duration: number

Seconds to hold the key down (maximum 30).

minimum0

maximum30

text: string

The key or chord to hold.

tab_id?: string | null

Tab to act on. Defaults to the active tab when omitted.

interface BetaBrowserHoldKeyToolUseBlock { type: "tool_use"; id; input; /* 3 more */ }

interface BetaBrowserHoverConfig { defer_loading; enabled }

hover's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | 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.

interface BetaBrowserHoverInput { target; tab_id }

Move the cursor to a coordinate or element without clicking.

target: BetaBrowserClickTarget

Where to act: either a viewport coordinate or an element reference.

One of the following:

interface BetaBrowserCoordinateTarget { type: "coordinate"; x; y }

A point in the browser viewport, in viewport pixels (the same frame as a full-viewport screenshot).

type: "coordinate"

x: number

Pixels from the left edge of the viewport.

minimum0

y: number

Pixels from the top edge of the viewport.

minimum0

interface BetaBrowserRefTarget { type: "ref"; ref }

type: "ref"

ref: string

An element reference (e.g. "ref_7") returned by a prior read_page or find result.

tab_id?: string | null

Tab to act on. Defaults to the active tab when omitted.

interface BetaBrowserHoverToolUseBlock { type: "tool_use"; id; input; /* 3 more */ }

interface BetaBrowserJavascriptExecConfig { defer_loading; enabled }

javascript_exec's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | 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.

interface BetaBrowserJavascriptExecInput { text; tab_id }

Execute JavaScript in the page context and return the value of the last expression. The code runs with access to the DOM, window, and page variables. Write the expression you want evaluated — do NOT use return.

text: string

JavaScript to execute in the page context.

tab_id?: string | null

Tab to act on. Defaults to the active tab when omitted.

interface BetaBrowserJavascriptExecToolUseBlock { type: "tool_use"; id; input; /* 3 more */ }

interface BetaBrowserKeyConfig { defer_loading; enabled }

key's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | 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.

interface BetaBrowserKeyInput { text; repeat; tab_id }

Press a key or key chord. Use "+" to combine modifiers with a key (e.g. "ctrl+a", "cmd+shift+p") and space to sequence presses (e.g. "Backspace Backspace Delete"). Common names like "Return", "Tab", "Escape", "BackSpace" are supported.

text: string

The key, chord, or space-separated sequence to press.

repeat?: number | null

Number of times to repeat. Default 1.

minimum1

maximum100

tab_id?: string | null

Tab to act on. Defaults to the active tab when omitted.

interface BetaBrowserKeyToolUseBlock { type: "tool_use"; id; input; /* 3 more */ }

interface BetaBrowserLeftClickConfig { defer_loading; enabled }

left_click's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | 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.

interface BetaBrowserLeftClickDragConfig { defer_loading; enabled }

left_click_drag's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | 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.

interface BetaBrowserLeftClickDragInput { from; target; tab_id }

Press at from, drag to target, release. Both must be coordinate targets.

interface BetaBrowserLeftClickDragToolUseBlock { type: "tool_use"; id; input; /* 3 more */ }

interface BetaBrowserLeftClickInput { target; modifiers; tab_id }

Left-click at a viewport coordinate or on an element by reference.

interface BetaBrowserLeftClickToolUseBlock { type: "tool_use"; id; input; /* 3 more */ }

interface BetaBrowserLeftMouseDownConfig { defer_loading; enabled }

left_mouse_down's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | 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.

interface BetaBrowserLeftMouseDownInput { target; tab_id }

Press and hold the left mouse button at a viewport coordinate. Pair with left_mouse_up to perform a custom drag.

target: BetaBrowserCoordinateTarget { type: "coordinate"; x; y }

A point in the browser viewport, in viewport pixels (the same frame as a full-viewport screenshot).

type: "coordinate"

x: number

Pixels from the left edge of the viewport.

minimum0

y: number

Pixels from the top edge of the viewport.

minimum0

tab_id?: string | null

Tab to act on. Defaults to the active tab when omitted.

interface BetaBrowserLeftMouseDownToolUseBlock { type: "tool_use"; id; input; /* 3 more */ }

interface BetaBrowserLeftMouseUpConfig { defer_loading; enabled }

left_mouse_up's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | 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.

interface BetaBrowserLeftMouseUpInput { target; tab_id }

Release the left mouse button at a viewport coordinate.

target: BetaBrowserCoordinateTarget { type: "coordinate"; x; y }

A point in the browser viewport, in viewport pixels (the same frame as a full-viewport screenshot).

type: "coordinate"

x: number

Pixels from the left edge of the viewport.

minimum0

y: number

Pixels from the top edge of the viewport.

minimum0

tab_id?: string | null

Tab to act on. Defaults to the active tab when omitted.

interface BetaBrowserLeftMouseUpToolUseBlock { type: "tool_use"; id; input; /* 3 more */ }

interface BetaBrowserListTabsConfig { defer_loading; enabled }

list_tabs's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | 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.

interface BetaBrowserListTabsInput

List all open tabs with each tab's tab_id, title, and URL.

interface BetaBrowserListTabsToolUseBlock { type: "tool_use"; id; input; /* 3 more */ }

interface BetaBrowserMiddleClickConfig { defer_loading; enabled }

middle_click's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | 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.

interface BetaBrowserMiddleClickInput { target; modifiers; tab_id }

Middle-click at a viewport coordinate or on an element by reference.

interface BetaBrowserMiddleClickToolUseBlock { type: "tool_use"; id; input; /* 3 more */ }

interface BetaBrowserMouseMoveConfig { defer_loading; enabled }

mouse_move's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | 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.

interface BetaBrowserMouseMoveInput { target; tab_id }

Move the pointer to a viewport coordinate without clicking.

target: BetaBrowserCoordinateTarget { type: "coordinate"; x; y }

A point in the browser viewport, in viewport pixels (the same frame as a full-viewport screenshot).

type: "coordinate"

x: number

Pixels from the left edge of the viewport.

minimum0

y: number

Pixels from the top edge of the viewport.

minimum0

tab_id?: string | null

Tab to act on. Defaults to the active tab when omitted.

interface BetaBrowserMouseMoveToolUseBlock { type: "tool_use"; id; input; /* 3 more */ }

interface BetaBrowserNavigateConfig { defer_loading; enabled }

navigate's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | 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.

interface BetaBrowserNavigateInput { url; tab_id }

Navigate to a URL, or go back/forward/reload in history. The protocol may be omitted (defaults to https://).

url: string

The URL to navigate to, or "back" / "forward" / "reload" for history navigation.

tab_id?: string | null

Tab to act on. Defaults to the active tab when omitted.

interface BetaBrowserNavigateToolUseBlock { type: "tool_use"; id; input; /* 3 more */ }

interface BetaBrowserNewTabConfig { defer_loading; enabled }

new_tab's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | 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.

interface BetaBrowserNewTabInput

Open a new empty tab and return its tab_id.

interface BetaBrowserNewTabToolUseBlock { type: "tool_use"; id; input; /* 3 more */ }

interface BetaBrowserReadConsoleConfig { defer_loading; enabled }

read_console's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | 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.

interface BetaBrowserReadConsoleInput { tab_id }

Return console output (log entries, errors, warnings) accumulated since the driver attached to the tab and since the last read, one line per entry. An empty result does not mean no traffic for a tab that predates attach.

tab_id?: string | null

Tab to act on. Defaults to the active tab when omitted.

interface BetaBrowserReadConsoleToolUseBlock { type: "tool_use"; id; input; /* 3 more */ }

interface BetaBrowserReadNetworkConfig { defer_loading; enabled }

read_network's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | 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.

interface BetaBrowserReadNetworkInput { tab_id }

Return the network requests (method, URL, status, MIME type, timing) recorded since the driver attached to the tab and since the last read, one line per entry. An empty result does not mean no traffic for a tab that predates attach.

tab_id?: string | null

Tab to act on. Defaults to the active tab when omitted.

interface BetaBrowserReadNetworkToolUseBlock { type: "tool_use"; id; input; /* 3 more */ }

interface BetaBrowserReadPageConfig { defer_loading; enabled }

read_page's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | 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 BetaBrowserReadPageFilter = "all" | "interactive"

One of the following:

"all"

"interactive"

interface BetaBrowserReadPageInput { depth; filter; ref; tab_id }

Return a structured accessibility tree of the page (or the subtree rooted at ref), with element references like [ref_7] that can be used as targets on later actions. Output is capped at 50,000 characters — narrow with ref or a smaller depth when exceeded.

depth?: number | null

Maximum tree depth. Default 15.

minimum1

filter?: BetaBrowserReadPageFilter | null

Which elements to include. Omitted: every visible element. "interactive": interactive elements only. "all": additionally includes off-viewport elements.

One of the following:

"all"

"interactive"

ref?: string | null

Element reference to read a subtree from. Omit to read from the page root.

tab_id?: string | null

Tab to act on. Defaults to the active tab when omitted.

interface BetaBrowserReadPageToolUseBlock { type: "tool_use"; id; input; /* 3 more */ }

interface BetaBrowserRefTarget { type: "ref"; ref }

type: "ref"

ref: string

An element reference (e.g. "ref_7") returned by a prior read_page or find result.

interface BetaBrowserRightClickConfig { defer_loading; enabled }

right_click's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | 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.

interface BetaBrowserRightClickInput { target; modifiers; tab_id }

Right-click at a viewport coordinate or on an element by reference.

interface BetaBrowserRightClickToolUseBlock { type: "tool_use"; id; input; /* 3 more */ }

interface BetaBrowserScreenshotConfig { defer_loading; enabled }

screenshot's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | 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.

interface BetaBrowserScreenshotInput { tab_id }

Capture the current browser viewport.

tab_id?: string | null

Tab to act on. Defaults to the active tab when omitted.

interface BetaBrowserScreenshotToolUseBlock { type: "tool_use"; id; input; /* 3 more */ }

interface BetaBrowserScrollConfig { defer_loading; enabled }

scroll's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | 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 BetaBrowserScrollDirection = "up" | "down" | "left" | "right"

One of the following:

"up"

"down"

"left"

"right"

interface BetaBrowserScrollInput { scroll_direction; target; scroll_amount; tab_id }

Scroll at a viewport position. target must be a coordinate target.

scroll_direction: BetaBrowserScrollDirection

One of the following:

"up"

"down"

"left"

"right"

target: BetaBrowserCoordinateTarget { type: "coordinate"; x; y }

A point in the browser viewport, in viewport pixels (the same frame as a full-viewport screenshot).

type: "coordinate"

x: number

Pixels from the left edge of the viewport.

minimum0

y: number

Pixels from the top edge of the viewport.

minimum0

scroll_amount?: number | null

Scroll-wheel notches (1–10). Default 3.

minimum1

maximum10

tab_id?: string | null

Tab to act on. Defaults to the active tab when omitted.

interface BetaBrowserScrollToConfig { defer_loading; enabled }

scroll_to's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | 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.

interface BetaBrowserScrollToInput { target; tab_id }

Scroll an element into view.

target: BetaBrowserRefTarget { type: "ref"; ref }

type: "ref"

ref: string

An element reference (e.g. "ref_7") returned by a prior read_page or find result.

tab_id?: string | null

Tab to act on. Defaults to the active tab when omitted.

interface BetaBrowserScrollToToolUseBlock { type: "tool_use"; id; input; /* 3 more */ }

interface BetaBrowserScrollToolUseBlock { type: "tool_use"; id; input; /* 3 more */ }

interface BetaBrowserStateBlockParam { type: "browser_state"; tabs; 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.

type BetaBrowserStateChange = BetaBrowserStateChangeTabOpened | BetaBrowserStateChangeDownloadStarted | BetaBrowserStateChangeDownloadCompleted | BetaBrowserStateChangeDownloadFailed

One of the following:

interface BetaBrowserStateChangeDownloadCompleted { type: "download_completed"; download_id; 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).

type: "download_completed"

download_id: string

The caller-assigned identifier for this download, stable across the state changes reporting it.

minLength1

maxLength4096

pattern^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$

url: string

The final post-redirect URL the download was served from.

maxLength4096

pattern^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$

path?: string | 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.

maxLength4096

pattern^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$

size_bytes?: number | null

The completed download's size.

minimum0

interface BetaBrowserStateChangeDownloadFailed { type: "download_failed"; download_id; url; error }

A file download that failed — or was cancelled — during this call.

type: "download_failed"

download_id: string

The caller-assigned identifier for this download, stable across the state changes reporting it.

minLength1

maxLength4096

pattern^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$

url: string

The final post-redirect URL the download was served from.

maxLength4096

pattern^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$

error?: string | null

The failure or cancellation detail, when known.

maxLength4096

pattern^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$

interface BetaBrowserStateChangeDownloadStarted { type: "download_started"; download_id; url }

A file download that started during this call.

type: "download_started"

download_id: string

The caller-assigned identifier for this download, stable across the state changes reporting it.

minLength1

maxLength4096

pattern^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$

url: string

The final post-redirect URL the download was served from.

maxLength4096

pattern^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$

interface BetaBrowserStateChangeTabOpened { type: "tab_opened"; tab_id }

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.

type: "tab_opened"

tab_id: string

The tab_id of the opened tab, present in tabs.

minLength1

maxLength4096

pattern^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$

interface BetaBrowserStateTabEntry { tab_id; title; url; active }

One open browser tab reported in a browser_state block's tabs inventory.

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.

tab_id: string

The caller-assigned identifier for this tab, unique within the inventory.

minLength1

maxLength4096

pattern^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$

title: string

The title of the page the tab is showing. May be empty.

maxLength4096

pattern^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$

url: string

The URL of the page the tab is showing. May be empty.

maxLength4096

pattern^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$

active?: boolean

Whether this tab is the active tab after this call. Whenever tabs is non-empty, exactly one entry is marked active: true.

interface BetaBrowserSwitchTabConfig { defer_loading; enabled }

switch_tab's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | 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.

interface BetaBrowserSwitchTabInput { tab_id }

Make the tab with the given tab_id the active tab — the tab that actions without a tab_id apply to.

tab_id: string

The tab to switch to.

interface BetaBrowserSwitchTabToolUseBlock { type: "tool_use"; id; input; /* 3 more */ }

type BetaBrowserToolUseBlock = BetaBrowserNavigateToolUseBlock | BetaBrowserListTabsToolUseBlock | BetaBrowserNewTabToolUseBlock | 28 more

One of the following:

interface BetaBrowserToolset20260801 { type: "browser_toolset_20260801"; 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"

cache_control?: BetaCacheControlEphemeral | null

Create a cache control breakpoint at this content block.

type: "ephemeral"

ttl?: "5m" | "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 for details.

One of the following:

"5m"

"1h"

configs?: BetaBrowserToolsetConfigs | null

Sparse per-member overrides, keyed by member name. Absent, null, and {} are equivalent; a member's defaults apply wherever its key is absent.

interface BetaBrowserToolsetConfigs { type; close_tab; double_click; /* 28 more */ }

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.

interface BetaBrowserTripleClickConfig { defer_loading; enabled }

triple_click's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | 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.

interface BetaBrowserTripleClickInput { target; modifiers; tab_id }

Triple left-click at a viewport coordinate or on an element by reference (typically selects a line or paragraph).

interface BetaBrowserTripleClickToolUseBlock { type: "tool_use"; id; input; /* 3 more */ }

interface BetaBrowserTypeConfig { defer_loading; enabled }

type's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | 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.

interface BetaBrowserTypeInput { text; tab_id }

Type a literal string at the current focus.

text: string

The text to type.

tab_id?: string | null

Tab to act on. Defaults to the active tab when omitted.

interface BetaBrowserTypeToolUseBlock { type: "tool_use"; id; input; /* 3 more */ }

interface BetaBrowserWaitConfig { defer_loading; enabled }

wait's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | 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.

interface BetaBrowserWaitInput { duration; tab_id }

Pause for the given duration.

duration: number

Seconds to wait (maximum 30).

minimum0

maximum30

tab_id?: string | null

Tab to act on. Defaults to the active tab when omitted.

interface BetaBrowserWaitToolUseBlock { type: "tool_use"; id; input; /* 3 more */ }

interface BetaBrowserZoomConfig { defer_loading; enabled }

zoom's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | 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.

interface BetaBrowserZoomInput { region; tab_id }

Return a cropped screenshot of the given viewport region, scaled up for closer inspection — useful for small icons, buttons, or text. Coordinates are in the same viewport-pixel space as a full screenshot.

region: Array<number>

[x0, y0, x1, y1] in viewport pixels.

minItems4

maxItems4

tab_id?: string | null

Tab to act on. Defaults to the active tab when omitted.

interface BetaBrowserZoomToolUseBlock { type: "tool_use"; id; input; /* 3 more */ }

interface BetaCacheControlEphemeral { type: "ephemeral"; ttl }

type: "ephemeral"

ttl?: "5m" | "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 for details.

One of the following:

"5m"

"1h"

interface BetaCacheCreation { ephemeral_1h_input_tokens; ephemeral_5m_input_tokens }

ephemeral_1h_input_tokens: number

The number of input tokens used to create the 1 hour cache entry.

default0

minimum0

ephemeral_5m_input_tokens: number

The number of input tokens used to create the 5 minute cache entry.

default0

minimum0

interface BetaCacheMissMessagesChanged { type: "messages_changed"; cache_missed_input_tokens }

type: "messages_changed"

defaultmessages_changed

cache_missed_input_tokens: number

Approximate number of input tokens that would have been read from cache had the prefix matched the previous request.

interface BetaCacheMissModelChanged { type: "model_changed"; cache_missed_input_tokens }

type: "model_changed"

defaultmodel_changed

cache_missed_input_tokens: number

Approximate number of input tokens that would have been read from cache had the prefix matched the previous request.

interface BetaCacheMissPreviousMessageNotFound { type: "previous_message_not_found" }

type: "previous_message_not_found"

defaultprevious_message_not_found

type BetaCacheMissReason = BetaCacheMissModelChanged | BetaCacheMissSystemChanged | BetaCacheMissToolsChanged | 3 more

One of the following:

interface BetaCacheMissSystemChanged { type: "system_changed"; cache_missed_input_tokens }

type: "system_changed"

defaultsystem_changed

cache_missed_input_tokens: number

Approximate number of input tokens that would have been read from cache had the prefix matched the previous request.

interface BetaCacheMissToolsChanged { type: "tools_changed"; cache_missed_input_tokens }

type: "tools_changed"

defaulttools_changed

cache_missed_input_tokens: number

Approximate number of input tokens that would have been read from cache had the prefix matched the previous request.

interface BetaCacheMissUnavailable { type: "unavailable" }

type: "unavailable"

defaultunavailable

interface BetaCitationCharLocation { type: "char_location"; cited_text; document_index; /* 4 more */ }

type: "char_location"

defaultchar_location

cited_text: string

document_index: number

minimum0

document_title: string | null

end_char_index: number

file_id: string | null

start_char_index: number

minimum0

interface BetaCitationCharLocationParam { type: "char_location"; cited_text; document_index; /* 3 more */ }

type: "char_location"

cited_text: string

document_index: number

minimum0

document_title: string | null

minLength1

maxLength500

end_char_index: number

start_char_index: number

minimum0

interface BetaCitationConfig { enabled }

enabled: boolean

defaultfalse

interface BetaCitationContentBlockLocation { type: "content_block_location"; cited_text; document_index; /* 4 more */ }

type: "content_block_location"

defaultcontent_block_location

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

minimum0

document_title: string | 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.

file_id: string | null

start_block_index: number

0-based index of the first cited block in the source's content array.

minimum0

interface BetaCitationContentBlockLocationParam { type: "content_block_location"; cited_text; document_index; /* 3 more */ }

type: "content_block_location"

cited_text: string

The full text of the cited block range, concatenated.

document_index: number

minimum0

document_title: string | null

minLength1

maxLength500

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.

minimum0

interface BetaCitationPageLocation { type: "page_location"; cited_text; document_index; /* 4 more */ }

type: "page_location"

defaultpage_location

cited_text: string

document_index: number

minimum0

document_title: string | null

end_page_number: number

file_id: string | null

start_page_number: number

minimum1

interface BetaCitationPageLocationParam { type: "page_location"; cited_text; document_index; /* 3 more */ }

type: "page_location"

cited_text: string

document_index: number

minimum0

document_title: string | null

minLength1

maxLength500

end_page_number: number

start_page_number: number

minimum1

interface BetaCitationSearchResultLocation { type: "search_result_location"; cited_text; end_block_index; /* 4 more */ }

type: "search_result_location"

defaultsearch_result_location

cited_text: string

The full text of the cited block range, concatenated.

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.

minimum0

source: string

start_block_index: number

0-based index of the first cited block in the source's content array.

minimum0

title: string | null

interface BetaCitationSearchResultLocationParam { type: "search_result_location"; cited_text; end_block_index; /* 4 more */ }

type: "search_result_location"

cited_text: string

The full text of the cited block range, concatenated.

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.

minimum0

source: string

start_block_index: number

0-based index of the first cited block in the source's content array.

minimum0

title: string | null

interface BetaCitationWebSearchResultLocationParam { type: "web_search_result_location"; cited_text; encrypted_index; /* 2 more */ }

type: "web_search_result_location"

cited_text: string

encrypted_index: string

title: string | null

minLength1

maxLength512

url: string

minLength1

interface BetaCitationsConfigParam { enabled }

enabled?: boolean

interface BetaCitationsDelta { type: "citations_delta"; citation }

interface BetaCitationsWebSearchResultLocation { type: "web_search_result_location"; cited_text; encrypted_index; /* 2 more */ }

type: "web_search_result_location"

defaultweb_search_result_location

cited_text: string

encrypted_index: string

title: string | null

maxLength512

url: string

interface BetaClearThinking20251015Edit { type: "clear_thinking_20251015"; keep }

type: "clear_thinking_20251015"

keep?: BetaThinkingTurns | BetaAllThinkingTurns | "all"

Number of most recent assistant turns to keep thinking blocks for. Older turns will have their thinking blocks removed.

One of the following:

interface BetaThinkingTurns { type: "thinking_turns"; value }

type: "thinking_turns"

value: number

minimum1

interface BetaAllThinkingTurns { type: "all" }

type: "all"

"all"

interface BetaClearThinking20251015EditResponse { type: "clear_thinking_20251015"; cleared_input_tokens; cleared_thinking_turns }

type: "clear_thinking_20251015"

The type of context management edit applied.

defaultclear_thinking_20251015

cleared_input_tokens: number

Number of input tokens cleared by this edit.

minimum0

cleared_thinking_turns: number

Number of thinking turns that were cleared.

minimum0

interface BetaClearToolUses20250919Edit { type: "clear_tool_uses_20250919"; clear_at_least; clear_tool_inputs; /* 3 more */ }

interface BetaClearToolUses20250919EditResponse { type: "clear_tool_uses_20250919"; cleared_input_tokens; cleared_tool_uses }

type: "clear_tool_uses_20250919"

The type of context management edit applied.

defaultclear_tool_uses_20250919

cleared_input_tokens: number

Number of input tokens cleared by this edit.

minimum0

cleared_tool_uses: number

Number of tool uses that were cleared.

minimum0

interface BetaCodeExecutionOutputBlock { type: "code_execution_output"; file_id }

type: "code_execution_output"

defaultcode_execution_output

file_id: string

interface BetaCodeExecutionOutputBlockParam { type: "code_execution_output"; file_id }

type: "code_execution_output"

file_id: string

interface BetaCodeExecutionResultBlock { type: "code_execution_result"; content; return_code; /* 2 more */ }

type: "code_execution_result"

defaultcode_execution_result

content: Array<BetaCodeExecutionOutputBlock { type: "code_execution_output"; file_id }>

type: "code_execution_output"

defaultcode_execution_output

file_id: string

return_code: number

stderr: string

stdout: string

interface BetaCodeExecutionResultBlockParam { type: "code_execution_result"; content; return_code; /* 2 more */ }

type: "code_execution_result"

content: Array<BetaCodeExecutionOutputBlockParam { type: "code_execution_output"; file_id }>

type: "code_execution_output"

file_id: string

return_code: number

stderr: string

stdout: string

interface BetaCodeExecutionTool20250522 { type: "code_execution_20250522"; name; allowed_callers; /* 3 more */ }

interface BetaCodeExecutionTool20250825 { type: "code_execution_20250825"; name; allowed_callers; /* 3 more */ }

interface BetaCodeExecutionTool20260120 { type: "code_execution_20260120"; name; allowed_callers; /* 3 more */ }

Code execution tool with REPL state persistence (daemon mode + gVisor checkpoint).

interface BetaCodeExecutionTool20260521 { type: "code_execution_20260521"; name; allowed_callers; /* 3 more */ }

Code execution tool with REPL state persistence.

interface BetaCodeExecutionToolResultBlock { type: "code_execution_tool_result"; content; tool_use_id }

type: "code_execution_tool_result"

defaultcode_execution_tool_result

content: BetaCodeExecutionToolResultBlockContent

One of the following:

tool_use_id: string

pattern^srvtoolu_[a-zA-Z0-9_]+$

type BetaCodeExecutionToolResultBlockContent = BetaCodeExecutionToolResultError | BetaCodeExecutionResultBlock | BetaEncryptedCodeExecutionResultBlock

One of the following:

interface BetaCodeExecutionToolResultBlockParam { type: "code_execution_tool_result"; content; tool_use_id; cache_control }

type: "code_execution_tool_result"

content: BetaCodeExecutionToolResultBlockParamContent

One of the following:

tool_use_id: string

pattern^srvtoolu_[a-zA-Z0-9_]+$

cache_control?: BetaCacheControlEphemeral | null

Create a cache control breakpoint at this content block.

type: "ephemeral"

ttl?: "5m" | "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 for details.

One of the following:

"5m"

"1h"

type BetaCodeExecutionToolResultBlockParamContent = BetaCodeExecutionToolResultErrorParam | BetaCodeExecutionResultBlockParam | BetaEncryptedCodeExecutionResultBlockParam

One of the following:

interface BetaCodeExecutionToolResultError { type: "code_execution_tool_result_error"; error_code }

type: "code_execution_tool_result_error"

defaultcode_execution_tool_result_error

error_code: BetaCodeExecutionToolResultErrorCode

One of the following:

"invalid_tool_input"

"unavailable"

"too_many_requests"

"execution_time_exceeded"

type BetaCodeExecutionToolResultErrorCode = "invalid_tool_input" | "unavailable" | "too_many_requests" | "execution_time_exceeded"

One of the following:

"invalid_tool_input"

"unavailable"

"too_many_requests"

"execution_time_exceeded"

interface BetaCodeExecutionToolResultErrorParam { type: "code_execution_tool_result_error"; error_code }

type: "code_execution_tool_result_error"

error_code: BetaCodeExecutionToolResultErrorCode

One of the following:

"invalid_tool_input"

"unavailable"

"too_many_requests"

"execution_time_exceeded"

interface BetaCompact20260112Edit { type: "compact_20260112"; instructions; pause_after_compaction; trigger }

Automatically compact older context when reaching the configured trigger threshold.

type: "compact_20260112"

instructions?: string | null

Additional instructions for summarization.

pause_after_compaction?: boolean

Whether to pause after compaction and return the compaction block to the user.

trigger?: BetaInputTokensTrigger | null

When to trigger compaction. Defaults to 150000 input tokens.

type: "input_tokens"

value: number

minimum1

interface BetaCompactionBlock { type: "compaction"; content; encrypted_content; /* 2 more */ }

A compaction block returned when autocompact is triggered.

When content is None, it indicates the compaction failed to produce a valid summary (e.g., malformed output from the model). Clients may round-trip compaction blocks with null content; the server treats them as no-ops.

interface BetaCompactionBlockParam { type: "compaction"; cache_control; content; /* 3 more */ }

A compaction block containing summary of previous context.

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.

interface BetaCompactionConfig { type: "summarize"; instructions }

Compact the whole conversation and return a signed compaction block, alone, that a later request sends back first in messages, in place of the messages it summarizes. There is no trigger and no pause flag: sending the parameter compacts, and nothing is sampled after the block.

The summarization prompt is the server's own unless instructions are given, which then replace it for this request; a value that is empty or only whitespace counts as absent.

type: "summarize"

instructions?: string | null

Replaces the server's default summarization prompt for this request. An empty or whitespace-only value counts as absent.

maxLength16384

interface BetaCompactionContentBlockDelta { type: "compaction_delta"; content; encrypted_content }

type: "compaction_delta"

defaultcompaction_delta

content: string | null

encrypted_content: string | null

Opaque metadata from prior compaction, to be round-tripped verbatim

interface BetaCompactionIterationUsage { type: "compaction"; cache_creation; cache_creation_input_tokens; /* 3 more */ }

Token usage for a compaction iteration.

type: "compaction"

Usage for a compaction iteration

defaultcompaction

cache_creation: BetaCacheCreation | null

Breakdown of cached tokens by TTL

ephemeral_1h_input_tokens: number

The number of input tokens used to create the 1 hour cache entry.

default0

minimum0

ephemeral_5m_input_tokens: number

The number of input tokens used to create the 5 minute cache entry.

default0

minimum0

cache_creation_input_tokens: number

The number of input tokens used to create the cache entry.

default0

minimum0

cache_read_input_tokens: number

The number of input tokens read from the cache.

default0

minimum0

input_tokens: number

The number of input tokens which were used.

minimum0

output_tokens: number

The number of output tokens which were used.

minimum0

interface BetaComputerCursorPositionConfig { defer_loading; enabled }

cursor_position's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | 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.

interface BetaComputerCursorPositionInput

Get the current (x, y) pixel coordinate of the cursor.

interface BetaComputerCursorPositionToolUseBlock { type: "tool_use"; id; input; /* 3 more */ }

interface BetaComputerDoubleClickConfig { defer_loading; enabled }

double_click's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | 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.

interface BetaComputerDoubleClickInput { coordinate; text }

Double-click the left mouse button at the specified (x, y) pixel coordinate, or the current cursor position if coordinate is omitted.

coordinate?: Array<number> | null

(x, y): x pixels from the left edge, y pixels from the top edge.

minItems2

maxItems2

text?: string | null

Optional key combination to hold down during this action (e.g. "ctrl", "shift", "ctrl+shift").

interface BetaComputerDoubleClickToolUseBlock { type: "tool_use"; id; input; /* 3 more */ }

interface BetaComputerHoldKeyConfig { defer_loading; enabled }

hold_key's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | 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.

interface BetaComputerHoldKeyInput { duration; text }

Hold down a key or key-combination for a specified duration. Uses the same key syntax as key.

duration: number

Duration to hold the key, in seconds.

maximum300

text: string

The key or key-combination to hold.

interface BetaComputerHoldKeyToolUseBlock { type: "tool_use"; id; input; /* 3 more */ }

interface BetaComputerKeyConfig { defer_loading; enabled }

key's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | 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.

interface BetaComputerKeyInput { text; repeat }

Press a key or key-combination on the keyboard. Use "+" to combine modifiers with a key (e.g. "ctrl+s", "alt+Tab", "ctrl+shift+Escape"). Key names are case-insensitive; common names like "Return", "Tab", "Escape", "Up", "Down", "Left", "Right", "Home", "End", "Page_Up", "Page_Down", "Delete", "BackSpace" are supported.

text: string

The key or key-combination to press.

repeat?: number | null

Number of times to repeat the key press. Default is 1.

minimum1

maximum100

interface BetaComputerKeyToolUseBlock { type: "tool_use"; id; input; /* 3 more */ }

interface BetaComputerLeftClickConfig { defer_loading; enabled }

left_click's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | 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.

interface BetaComputerLeftClickDragConfig { defer_loading; enabled }

left_click_drag's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | 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.

interface BetaComputerLeftClickDragInput { coordinate; start_coordinate; text }

Click and drag the cursor from start_coordinate to coordinate.

coordinate: Array<number>

(x, y): x pixels from the left edge, y pixels from the top edge.

minItems2

maxItems2

start_coordinate: Array<number>

(x, y): x pixels from the left edge, y pixels from the top edge.

minItems2

maxItems2

text?: string | null

Optional key combination to hold down during this action (e.g. "ctrl", "shift", "ctrl+shift").

interface BetaComputerLeftClickDragToolUseBlock { type: "tool_use"; id; input; /* 3 more */ }

interface BetaComputerLeftClickInput { coordinate; text }

Click the left mouse button at the specified (x, y) pixel coordinate, or the current cursor position if coordinate is omitted.

coordinate?: Array<number> | null

(x, y): x pixels from the left edge, y pixels from the top edge.

minItems2

maxItems2

text?: string | null

Optional key combination to hold down during this action (e.g. "ctrl", "shift", "ctrl+shift").

interface BetaComputerLeftClickToolUseBlock { type: "tool_use"; id; input; /* 3 more */ }

interface BetaComputerLeftMouseDownConfig { defer_loading; enabled }

left_mouse_down's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | 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.

interface BetaComputerLeftMouseDownInput

Press and hold the left mouse button at the current cursor position.

interface BetaComputerLeftMouseDownToolUseBlock { type: "tool_use"; id; input; /* 3 more */ }

interface BetaComputerLeftMouseUpConfig { defer_loading; enabled }

left_mouse_up's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | 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.

interface BetaComputerLeftMouseUpInput

Release the left mouse button.

interface BetaComputerLeftMouseUpToolUseBlock { type: "tool_use"; id; input; /* 3 more */ }

interface BetaComputerMiddleClickConfig { defer_loading; enabled }

middle_click's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | 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.

interface BetaComputerMiddleClickInput { coordinate; text }

Click the middle mouse button at the specified (x, y) pixel coordinate, or the current cursor position if coordinate is omitted.

coordinate?: Array<number> | null

(x, y): x pixels from the left edge, y pixels from the top edge.

minItems2

maxItems2

text?: string | null

Optional key combination to hold down during this action (e.g. "ctrl", "shift", "ctrl+shift").

interface BetaComputerMiddleClickToolUseBlock { type: "tool_use"; id; input; /* 3 more */ }

interface BetaComputerMouseMoveConfig { defer_loading; enabled }

mouse_move's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | 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.

interface BetaComputerMouseMoveInput { coordinate }

Move the cursor to a specified (x, y) pixel coordinate. Use this ONLY to hover without clicking; otherwise use a click action directly.

coordinate: Array<number>

(x, y): x pixels from the left edge, y pixels from the top edge.

minItems2

maxItems2

interface BetaComputerMouseMoveToolUseBlock { type: "tool_use"; id; input; /* 3 more */ }

interface BetaComputerRightClickConfig { defer_loading; enabled }

right_click's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | 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.

interface BetaComputerRightClickInput { coordinate; text }

Click the right mouse button at the specified (x, y) pixel coordinate, or the current cursor position if coordinate is omitted.

coordinate?: Array<number> | null

(x, y): x pixels from the left edge, y pixels from the top edge.

minItems2

maxItems2

text?: string | null

Optional key combination to hold down during this action (e.g. "ctrl", "shift", "ctrl+shift").

interface BetaComputerRightClickToolUseBlock { type: "tool_use"; id; input; /* 3 more */ }

interface BetaComputerScreenshotConfig { defer_loading; enabled }

screenshot's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | 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.

interface BetaComputerScreenshotInput

Take a screenshot of the screen.

interface BetaComputerScreenshotToolUseBlock { type: "tool_use"; id; input; /* 3 more */ }

interface BetaComputerScrollConfig { defer_loading; enabled }

scroll's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | 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 BetaComputerScrollDirection = "up" | "down" | "left" | "right"

One of the following:

"up"

"down"

"left"

"right"

interface BetaComputerScrollInput { scroll_amount; scroll_direction; coordinate; text }

Scroll the screen at the specified (x, y) pixel coordinate, or the current cursor position if coordinate is omitted. Do NOT use PageUp/PageDown to scroll.

scroll_amount: number

Number of 'clicks' of the scroll wheel.

scroll_direction: BetaComputerScrollDirection

One of the following:

"up"

"down"

"left"

"right"

coordinate?: Array<number> | null

(x, y): x pixels from the left edge, y pixels from the top edge.

minItems2

maxItems2

text?: string | null

Optional key combination to hold down during this action (e.g. "ctrl", "shift", "ctrl+shift").

interface BetaComputerScrollToolUseBlock { type: "tool_use"; id; input; /* 3 more */ }

type BetaComputerToolUseBlock = BetaComputerKeyToolUseBlock | BetaComputerHoldKeyToolUseBlock | BetaComputerTypeToolUseBlock | 14 more

One of the following:

interface BetaComputerToolset20260801 { type: "computer_toolset_20260801"; 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"

cache_control?: BetaCacheControlEphemeral | null

Create a cache control breakpoint at this content block.

type: "ephemeral"

ttl?: "5m" | "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 for details.

One of the following:

"5m"

"1h"

configs?: BetaComputerToolsetConfigs | null

Sparse per-member overrides, keyed by member name. Absent, null, and {} are equivalent; a member's defaults apply wherever its key is absent.

interface BetaComputerToolsetConfigs { type; cursor_position; double_click; /* 14 more */ }

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.

interface BetaComputerTripleClickConfig { defer_loading; enabled }

triple_click's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | 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.

interface BetaComputerTripleClickInput { coordinate; text }

Triple-click the left mouse button at the specified (x, y) pixel coordinate, or the current cursor position if coordinate is omitted.

coordinate?: Array<number> | null

(x, y): x pixels from the left edge, y pixels from the top edge.

minItems2

maxItems2

text?: string | null

Optional key combination to hold down during this action (e.g. "ctrl", "shift", "ctrl+shift").

interface BetaComputerTripleClickToolUseBlock { type: "tool_use"; id; input; /* 3 more */ }

interface BetaComputerTypeConfig { defer_loading; enabled }

type's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | 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.

interface BetaComputerTypeInput { text }

Type a string of text on the keyboard.

text: string

The text to type.

interface BetaComputerTypeToolUseBlock { type: "tool_use"; id; input; /* 3 more */ }

interface BetaComputerWaitConfig { defer_loading; enabled }

wait's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | 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.

interface BetaComputerWaitInput { duration }

Wait for a specified duration.

duration: number

Duration to wait, in seconds.

maximum300

interface BetaComputerWaitToolUseBlock { type: "tool_use"; id; input; /* 3 more */ }

interface BetaComputerZoomConfig { defer_loading; enabled }

zoom's config overrides.

defer_loading?: boolean | null

Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.

enabled?: boolean | 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.

interface BetaComputerZoomInput { region }

Take a screenshot of a rectangular region. Region coordinates are in the full-screenshot space (not physical display pixels). The crop is scaled up to fill the image budget so fine details become legible.

region: Array<number>

(x0, y0, x1, y1): The region to capture.

minItems4

maxItems4

interface BetaComputerZoomToolUseBlock { type: "tool_use"; id; input; /* 3 more */ }

interface BetaContainer { id; expires_at; skills }

Information about the container used in the request (for the code execution tool)

id: string

Identifier for the container used in this request

expires_at: string

The time at which the container will expire.

formatdate-time

skills: Array<BetaContainerSkill> | null

Skills loaded in the container

type: "anthropic" | "custom"

Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined)

One of the following:

"anthropic"

"custom"

skill_id: string

Skill ID

minLength1

maxLength64

version: string

The resolved version: a skill version ID for custom skills.

minLength1

maxLength64

interface BetaContainerParams { id; skills }

Container parameters with skills to be loaded.

id?: string | null

Container id

skills?: Array<BetaSkillParams> | null

List of skills to load in the container

maxItems20

type: "anthropic" | "custom"

Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined)

One of the following:

"anthropic"

"custom"

skill_id: string

Skill ID

minLength1

maxLength64

version?: string

Skill version or 'latest' for most recent version

minLength1

maxLength64

interface BetaContainerSkill { type; skill_id; version }

A skill that was loaded in a container (response model).

type: "anthropic" | "custom"

Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined)

One of the following:

"anthropic"

"custom"

skill_id: string

Skill ID

minLength1

maxLength64

version: string

The resolved version: a skill version ID for custom skills.

minLength1

maxLength64

interface BetaContainerUploadBlock { type: "container_upload"; file_id }

Response model for a file uploaded to the container.

type: "container_upload"

defaultcontainer_upload

file_id: string

interface BetaContainerUploadBlockParam { type: "container_upload"; file_id; cache_control }

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.

type: "container_upload"

file_id: string

cache_control?: BetaCacheControlEphemeral | null

Create a cache control breakpoint at this content block.

type: "ephemeral"

ttl?: "5m" | "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 for details.

One of the following:

"5m"

"1h"

type BetaContentBlock = BetaTextBlock | BetaThinkingBlock | BetaRedactedThinkingBlock | 15 more

One of the following:

type BetaContentBlockParam = BetaTextBlockParam | BetaImageBlockParam | BetaRequestDocumentBlock | 21 more

One of the following:

interface BetaContentBlockSource { type: "content"; content }

type: "content"

content: string | Array<BetaContentBlockSourceContent>

One of the following:

string

Array<BetaContentBlockSourceContent>

interface BetaTextBlockParam { type: "text"; text; cache_control; citations }

interface BetaImageBlockParam { type: "image"; source; cache_control; transformations }

type BetaContentBlockSourceContent = BetaTextBlockParam | BetaImageBlockParam

One of the following:

interface BetaTextBlockParam { type: "text"; text; cache_control; citations }

interface BetaImageBlockParam { type: "image"; source; cache_control; transformations }

interface BetaContextManagementConfig { edits }

interface BetaContextManagementResponse { applied_edits }

interface BetaCountTokensContextManagementResponse { original_input_tokens }

original_input_tokens: number

The original token count before context management was applied

interface BetaDiagnostics { cache_miss_reason }

Request-level diagnostics: why the prompt cache could not fully reuse the prefix of the request named by diagnostics.previous_message_id.

cache_miss_reason: BetaCacheMissReason | null

Explains why the prompt cache could not fully reuse the prefix from the request identified by diagnostics.previous_message_id. null means diagnosis is still pending — the response was serialized before the background comparison completed.

One of the following:

interface BetaDiagnosticsParam { previous_message_id }

Request-level diagnostics. Currently carries the previous response id for prompt-cache divergence reporting.

previous_message_id?: string | null

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.

maxLength256

interface BetaDirectCaller { type: "direct" }

Tool invocation directly from the model.

type: "direct"

interface BetaDocumentBlock { type: "document"; citations; source; title }

interface BetaEncryptedCodeExecutionResultBlock { type: "encrypted_code_execution_result"; content; encrypted_stdout; /* 2 more */ }

Code execution result with encrypted stdout for PFC + web_search results.

type: "encrypted_code_execution_result"

defaultencrypted_code_execution_result

content: Array<BetaCodeExecutionOutputBlock { type: "code_execution_output"; file_id }>

type: "code_execution_output"

defaultcode_execution_output

file_id: string

encrypted_stdout: string

return_code: number

stderr: string

interface BetaEncryptedCodeExecutionResultBlockParam { type: "encrypted_code_execution_result"; content; encrypted_stdout; /* 2 more */ }

Code execution result with encrypted stdout for PFC + web_search results.

type: "encrypted_code_execution_result"

content: Array<BetaCodeExecutionOutputBlockParam { type: "code_execution_output"; file_id }>

type: "code_execution_output"

file_id: string

encrypted_stdout: string

return_code: number

stderr: string

interface BetaFallbackBlock { type: "fallback"; from; to; trigger }

Marks the point in content where one model's output gives way to the next.

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.

interface BetaFallbackBlockParam { type: "fallback"; from; to; trigger }

A fallback block echoed back from a prior response.

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.

type: "fallback"

from: BetaFallbackInfoParam { model }

Identifies one hop of a fallback transition.

to: BetaFallbackInfoParam { model }

Identifies one hop of a fallback transition.

trigger?: unknown

The response block's trigger, echoed verbatim. Accepted and ignored by the server; any object or null is allowed.

interface BetaFallbackCreditNotApplied { type: "not_applied"; reason; remove_to_redeem }

No reprice was applied; reason says why.

interface BetaFallbackCreditRedeemed { type: "redeemed" }

The reprice was applied: the retry is billed as if the conversation had been on the retry model all along.

type: "redeemed"

defaultredeemed

interface BetaFallbackCreditTokenParam { token; mode }

Object form of fallback_credit_token: the token plus a redemption mode.

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.

token: string

The opaque fallback_credit_token from a prior refusal's stop_details — the same string the bare-string form carries.

minLength1

maxLength2048

mode?: "strict" | "best_effort"

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.

One of the following:

"strict"

"best_effort"

interface BetaFallbackCreditUsage { status }

Outcome of the fallback_credit_token presented on this request.

status: BetaFallbackCreditRedeemed | BetaFallbackCreditNotApplied

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.

One of the following:

interface BetaFallbackCreditRedeemed { type: "redeemed" }

The reprice was applied: the retry is billed as if the conversation had been on the retry model all along.

type: "redeemed"

defaultredeemed

interface BetaFallbackCreditNotApplied { type: "not_applied"; reason; remove_to_redeem }

No reprice was applied; reason says why.

interface BetaFallbackInfo { model }

Identifies one hop of a fallback transition.

interface BetaFallbackInfoParam { model }

Identifies one hop of a fallback transition.

interface BetaFallbackMessageIterationUsage { type: "fallback_message"; cache_creation; cache_creation_input_tokens; /* 4 more */ }

Token usage for the fallback-model attempt of a server-side fallback request.

The terminal entry of a fallback-served turn: when a fallback hop's output is the returned message, the entry for the iteration that completed it carries this type in place of message. A declined hop and the serving hop's earlier tool-loop iterations produce message entries. Whether a fallback model served the response is signalled by the presence of this entry in usage.iterations.

interface BetaFallbackParam { model; max_tokens; output_config; /* 2 more */ }

One entry in the fallbacks chain on a /v1/messages request.

model is required. The override fields (max_tokens, thinking, output_config, and speed) set the corresponding parameter for this attempt only and are validated as if the request were made to model. Any other key is rejected at parse time.

interface BetaFallbackRefusalTrigger { type: "refusal"; category }

The from model declined for policy reasons.

type: "refusal"

defaultrefusal

category: "cyber" | "bio" | "frontier_llm" | 2 more | null

The policy category that triggered the from model's refusal at this hop. null when the refusal doesn't map to a named category. Same vocabulary as stop_details.category.

One of the following:

"cyber"

The request could enable cyber harm, such as malware or exploit development. Benign cybersecurity work can also trigger this category.

"bio"

The request could enable biological harm, such as dangerous lab methods. Beneficial life sciences work can also trigger this category.

"frontier_llm"

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.

"reasoning_extraction"

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.

"general_harms"

The request could be related to an area that was determined as harmful. Benign work might sometimes trigger this category.

type BetaFallbacksParam = Array<BetaFallbackParam> | "default" | null

Opt-in server-side retry on one or more substitute models when the requested model declines for policy reasons. Tried in order: if the first entry also declines, the second is tried, and so on. Some models don't support fallbacks; on those models, a list of fallback models returns a 400 error. See Server-side fallback. The string "default" requests the requested model's server-defined default fallback configuration. On a model that doesn't support fallbacks, the request runs on the requested model alone, so a declined request stays declined.

One of the following:

interface BetaFileDocumentSource { type: "file"; file_id }

type: "file"

file_id: string

interface BetaFileImageSource { type: "file"; file_id }

type: "file"

file_id: string

interface BetaImageBlockParam { type: "image"; source; cache_control; transformations }

interface BetaImageTransformationsParam { oversized_image }

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?: "downsize" | "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.

One of the following:

"downsize"

"error"

interface BetaInputJSONDelta { type: "input_json_delta"; partial_json }

type: "input_json_delta"

defaultinput_json_delta

partial_json: string

interface BetaInputTokensClearAtLeast { type: "input_tokens"; value }

type: "input_tokens"

value: number

minimum0

interface BetaInputTokensTrigger { type: "input_tokens"; value }

type: "input_tokens"

value: number

minimum1

type BetaInputTransformation = BetaThinkingDroppedInputTransformation | BetaThinkingMismatchAllowedInputTransformation

One entry of input_transformations: either a change the API made to the request's input before showing it to the model, or a block that failed a binding check and was still shown to the model unchanged. The type field says which.

One of the following:

type BetaIterationsUsage = Array<BetaMessageIterationUsage | BetaCompactionIterationUsage | BetaAdvisorMessageIterationUsage | BetaFallbackMessageIterationUsage> | null

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:

Calculate the context window size from the last message entry
Understand token accumulation across server-side tool use loops

A compaction entry reports the token usage of the compaction operation itself — the server-side request that summarizes the context being closed — NOT the size of the context that was compacted away, and its token counts can be much smaller than that closed context (for example, a compaction that closes a ~200k-token context can report only a few thousand tokens). Do not derive the context window size from a compaction entry, even when it is the last entry. A compaction entry's tokens are not included in the top-level usage fields. When an input-token trigger is in effect (the default — 150,000 tokens unless configured otherwise), each compaction entry closes a context that had reached at least that threshold, though the context can exceed it by the final iteration's output and tool results.

One of the following:

interface BetaJSONOutputFormat { type: "json_schema"; schema }

type: "json_schema"

schema: Record<string, unknown>

The JSON schema of the format

interface BetaMCPTool { input_schema; name; description }

A tool as an MCP server lists it: its name on that server, its description, and its input schema.

input_schema: Record<string, unknown>

description?: string

interface BetaMCPToolConfig { defer_loading; enabled }

Configuration for a specific tool in an MCP toolset.

defer_loading?: boolean

enabled?: boolean

interface BetaMCPToolDefaultConfig { defer_loading; enabled }

Default configuration for tools in an MCP toolset.

defer_loading?: boolean

enabled?: boolean

interface BetaMCPToolListingBlock { type: "mcp_tool_listing"; mcp_server_name; tools }

The tool listing the server fetched from an MCP server while producing this response. Send the assistant message back unchanged, this block included, so later requests use this listing instead of asking the MCP server again.

type: "mcp_tool_listing"

defaultmcp_tool_listing

mcp_server_name: string

tools: Array<BetaMCPTool { input_schema; name; description }>

input_schema: Record<string, unknown>

description?: string

interface BetaMCPToolListingBlockParam { type: "mcp_tool_listing"; mcp_server_name; tools }

The tool listing an MCP server returned while an earlier response was produced, as that response carried it. Send the assistant message back unchanged, this block included, and the server uses this listing for the matching mcp_toolset instead of asking the MCP server again.

type: "mcp_tool_listing"

mcp_server_name: string

The name of the MCP server this listing came from, as mcp_servers declares it.

minLength1

maxLength255

tools: Array<BetaMCPToolParam { input_schema; name; description }>

The server's tools, exactly as the response listed them.

input_schema: Record<string, unknown>

The tool's input schema as the MCP server lists it, verbatim.

The tool's name as the MCP server lists it (not prefixed with the server name).

minLength1

description?: string | null

The tool's description as the MCP server lists it.

interface BetaMCPToolParam { input_schema; name; description }

A tool as an MCP server lists it: its name on that server, its description, and its input schema.

input_schema: Record<string, unknown>

The tool's input schema as the MCP server lists it, verbatim.

The tool's name as the MCP server lists it (not prefixed with the server name).

minLength1

description?: string | null

The tool's description as the MCP server lists it.

interface BetaMCPToolResultBlock { type: "mcp_tool_result"; content; is_error; tool_use_id }

interface BetaMCPToolUseBlock { type: "mcp_tool_use"; id; input; /* 2 more */ }

type: "mcp_tool_use"

defaultmcp_tool_use

id: string

pattern^[a-zA-Z0-9_-]+$

input: Record<string, unknown>

The name of the MCP tool

server_name: string

The name of the MCP server

interface BetaMCPToolUseBlockParam { type: "mcp_tool_use"; id; input; /* 3 more */ }

type: "mcp_tool_use"

id: string

pattern^[a-zA-Z0-9_-]+$

input: Record<string, unknown>

server_name: string

The name of the MCP server

cache_control?: BetaCacheControlEphemeral | null

Create a cache control breakpoint at this content block.

type: "ephemeral"

ttl?: "5m" | "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 for details.

One of the following:

"5m"

"1h"

interface BetaMCPToolset { type: "mcp_toolset"; mcp_server_name; cache_control; /* 3 more */ }

Configuration for a group of tools from an MCP server.

Allows configuring enabled status and defer_loading for all tools from an MCP server, with optional per-tool overrides.

interface BetaMemoryTool20250818 { type: "memory_20250818"; name; allowed_callers; /* 4 more */ }

type BetaMemoryTool20250818Command = BetaMemoryTool20250818ViewCommand | BetaMemoryTool20250818CreateCommand | BetaMemoryTool20250818StrReplaceCommand | 3 more

One of the following:

interface BetaMemoryTool20250818CreateCommand { command; file_text; path }

command: "create"

Command type identifier

defaultcreate

file_text: string

Content to write to the file

path: string

Path where the file should be created

interface BetaMemoryTool20250818DeleteCommand { command; path }

command: "delete"

Command type identifier

defaultdelete

path: string

Path to the file or directory to delete

interface BetaMemoryTool20250818InsertCommand { command; insert_line; insert_text; path }

command: "insert"

Command type identifier

defaultinsert

insert_line: number

Line number where text should be inserted

minimum1

insert_text: string

Text to insert at the specified line

path: string

Path to the file where text should be inserted

interface BetaMemoryTool20250818RenameCommand { command; new_path; old_path }

command: "rename"

Command type identifier

defaultrename

new_path: string

New path for the file or directory

old_path: string

Current path of the file or directory

interface BetaMemoryTool20250818StrReplaceCommand { command; new_str; old_str; path }

command: "str_replace"

Command type identifier

defaultstr_replace

new_str: string

Text to replace with

old_str: string

Text to search for and replace

path: string

Path to the file where text should be replaced

interface BetaMemoryTool20250818ViewCommand { command; path; view_range }

command: "view"

Command type identifier

defaultview

path: string

Path to directory or file to view

view_range?: Array<number>

Optional line range for viewing specific lines

minItems2

maxItems2

interface BetaMessage { type: "message"; id; container; /* 10 more */ }

interface BetaMessageDeltaUsage { cache_creation_input_tokens; cache_read_input_tokens; fallback_credit; /* 5 more */ }

interface BetaMessageIterationUsage { type: "message"; cache_creation; cache_creation_input_tokens; /* 4 more */ }

Token usage for a sampling iteration.

type: "message"

Usage for a sampling iteration

defaultmessage

cache_creation: BetaCacheCreation | null

Breakdown of cached tokens by TTL

ephemeral_1h_input_tokens: number

The number of input tokens used to create the 1 hour cache entry.

default0

minimum0

ephemeral_5m_input_tokens: number

The number of input tokens used to create the 5 minute cache entry.

default0

minimum0

cache_creation_input_tokens: number

The number of input tokens used to create the cache entry.

default0

minimum0

cache_read_input_tokens: number

The number of input tokens read from the cache.

default0

minimum0

input_tokens: number

The number of input tokens which were used.

minimum0

model: Model | null

The model that will complete your prompt.

See models for additional details and options.

One of the following:

output_tokens: number

The number of output tokens which were used.

minimum0

interface BetaMessageParam { content; role; clear_at; output_config }

interface BetaMessageTokensCount { context_management; input_tokens }

context_management: BetaCountTokensContextManagementResponse | null

Information about context management applied to the message.

original_input_tokens: number

The original token count before context management was applied

input_tokens: number

The total number of tokens across the provided list of messages, system prompt, and tools.

interface BetaMetadata { user_id }

user_id?: string | null

An external identifier for the user who is associated with the request.

This should be a uuid, hash value, or other opaque identifier. Anthropic may use this id to help detect abuse. Do not include any identifying information such as name, email address, or phone number.

maxLength512

interface BetaOutputConfig { effort; format; task_budget }

interface BetaOutputTokensDetails { thinking_tokens }

thinking_tokens: number

Number of output tokens the model generated as internal reasoning, including the thinking-block delimiter tokens.

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.

default0

minimum0

interface BetaPlainTextSource { type: "text"; data; media_type }

type: "text"

data: string

media_type: "text/plain"

type BetaRawContentBlockDelta = BetaTextDelta | BetaInputJSONDelta | BetaCitationsDelta | 3 more

One of the following:

interface BetaRawContentBlockDeltaEvent { type: "content_block_delta"; delta; index }

type: "content_block_delta"

defaultcontent_block_delta

delta: BetaRawContentBlockDelta

One of the following:

index: number

interface BetaRawContentBlockStartEvent { type: "content_block_start"; content_block; index }

interface BetaRawContentBlockStopEvent { type: "content_block_stop"; index }

type: "content_block_stop"

defaultcontent_block_stop

index: number

interface BetaRawMessageDeltaEvent { type: "message_delta"; context_management; delta; /* 2 more */ }

interface BetaRawMessageStartEvent { type: "message_start"; message }

type: "message_start"

defaultmessage_start

message: BetaMessage { type: "message"; id; container; /* 10 more */ }

interface BetaRawMessageStopEvent { type: "message_stop" }

type: "message_stop"

defaultmessage_stop

type BetaRawMessageStreamEvent = BetaRawMessageStartEvent | BetaRawMessageDeltaEvent | BetaRawMessageStopEvent | 3 more

One of the following:

interface BetaRedactedThinkingBlock { type: "redacted_thinking"; data }

type: "redacted_thinking"

defaultredacted_thinking

data: string

The contents of this redacted thinking block, returned when portions of the model's thinking were safety-redacted. This field is opaque and encrypted, with no readable content.

Pass redacted_thinking blocks back to the API unchanged when continuing a multi-turn conversation.

See extended thinking for details.

interface BetaRedactedThinkingBlockParam { type: "redacted_thinking"; data }

type: "redacted_thinking"

data: string

The data value of this redacted thinking block, exactly as returned by the API in a previous response. Opaque and encrypted; pass it back unchanged.

interface BetaRefusalStopDetails { type: "refusal"; category; explanation; /* 3 more */ }

Structured information about a refusal.

interface BetaRequestDocumentBlock { type: "document"; source; cache_control; /* 3 more */ }

interface BetaRequestMCPServerToolConfiguration { allowed_tools; enabled }

allowed_tools?: Array<string> | null

enabled?: boolean | null

interface BetaRequestMCPServerURLDefinition { type: "url"; name; url; /* 2 more */ }

type: "url"

url: string

authorization_token?: string | null

tool_configuration?: BetaRequestMCPServerToolConfiguration | null

allowed_tools?: Array<string> | null

enabled?: boolean | null

interface BetaRequestMCPToolResultBlockParam { type: "mcp_tool_result"; tool_use_id; cache_control; /* 2 more */ }

interface BetaRequestToolAdditionBlock { type: "tool_addition"; tool; cache_control }

Mid-conversation directive to make a tool available.

tool is a reference to a tool (or MCP toolset) declared in the request's tools. Under the inline-tools-2026-09-15 beta it may instead be a reference to a tool defined earlier in messages, or a tool_definition object that carries an inline tool definition in definition (the same object a tools entry holds). An mcp_toolset definition also requires the mcp-client-2026-09-15 beta. The tool is offered to the model from this point in the conversation onward.

interface BetaRequestToolRemovalBlock { type: "tool_removal"; tool; cache_control }

Mid-conversation directive to withdraw a tool.

tool references a tool (or MCP toolset) by name: one declared in the request's tools or defined earlier in messages. It is no longer offered to the model from this point in the conversation onward.

interface BetaResponseTool { type; input_schema; name; /* 6 more */ }

A custom tool definition, as sent.

interface BetaResponseToolAdditionBlock { type: "tool_addition"; tool }

An entry of a compaction block's tool_changes: a tool the compacted range made available, as a reference to a tools entry or MCP toolset, or as the tool definition in effect at the end of the range, by value. Send it back unchanged.

interface BetaResponseToolChangeMCPToolReference { type: "mcp_tool_reference"; name; server_name }

Reference to a single MCP tool, by its server and its name on that server, as a compaction block's tool_changes entry reports it. Send it back unchanged with the block.

type: "mcp_tool_reference"

defaultmcp_tool_reference

server_name: string

interface BetaResponseToolChangeMCPToolsetReference { type: "mcp_toolset_reference"; server_name }

Reference to every tool in the named MCP server's toolset, as a compaction block's tool_changes entry reports it. Send it back unchanged with the block.

type: "mcp_toolset_reference"

defaultmcp_toolset_reference

server_name: string

interface BetaResponseToolChangeToolReference { type: "tool_reference"; name }

Reference to a single tool, by the name the model uses to call it, as a compaction block's tool_changes entry reports it: a tool declared in tools or defined by an earlier tool_addition block. Send it back unchanged with the block.

type: "tool_reference"

defaulttool_reference

interface BetaResponseToolInputSchema { type: "object"; properties; required }

JSON schema for this tool's input.

This defines the shape of the input that your tool accepts and that the model will produce.

type: "object"

properties?: Record<string, unknown> | null

required?: Array<string> | null

interface BetaResponseToolRemovalBlock { type: "tool_removal"; tool }

An entry of a compaction block's tool_changes: a tool of the request's tools (or an MCP tool or toolset) that the compacted range withdrew. Send it back unchanged.

type BetaResponseToolUnion = BetaResponseTool | BetaToolBash20241022 | BetaToolBash20250124 | 25 more

One of the following:

interface BetaSearchResultBlockParam { type: "search_result"; content; source; /* 3 more */ }

interface BetaServerToolCaller { type: "code_execution_20250825"; tool_id }

Tool invocation generated by a server-side tool.

type: "code_execution_20250825"

tool_id: string

pattern^srvtoolu_[a-zA-Z0-9_]+$

interface BetaServerToolCaller20260120 { type: "code_execution_20260120"; tool_id }

type: "code_execution_20260120"

tool_id: string

pattern^srvtoolu_[a-zA-Z0-9_]+$

interface BetaServerToolUsage { web_fetch_requests; web_search_requests }

web_fetch_requests: number

The number of web fetch tool requests.

default0

minimum0

web_search_requests: number

The number of web search tool requests.

default0

minimum0

interface BetaServerToolUseBlock { type: "server_tool_use"; id; input; /* 2 more */ }

interface BetaServerToolUseBlockParam { type: "server_tool_use"; id; input; /* 3 more */ }

interface BetaSignatureDelta { type: "signature_delta"; signature }

type: "signature_delta"

defaultsignature_delta

signature: string

The signature for this thinking block: an opaque value used to verify that the block was generated by Claude when it is passed back to the API. Delivered in a signature_delta event just before the block's content_block_stop event.

interface BetaSkillParams { type; skill_id; version }

Specification for a skill to be loaded in a container (request model).

type: "anthropic" | "custom"

Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined)

One of the following:

"anthropic"

"custom"

skill_id: string

Skill ID

minLength1

maxLength64

version?: string

Skill version or 'latest' for most recent version

minLength1

maxLength64

type BetaStopReason = "end_turn" | "max_tokens" | "stop_sequence" | 5 more

One of the following:

"end_turn"

"max_tokens"

"stop_sequence"

"tool_use"

"pause_turn"

"compaction"

"refusal"

"model_context_window_exceeded"

interface BetaSummarizeCompaction { type: "summarize"; instructions }

The summarization prompt is the server's own unless instructions are given, which then replace it for this request; a value that is empty or only whitespace counts as absent.

type: "summarize"

instructions?: string | null

Replaces the server's default summarization prompt for this request. An empty or whitespace-only value counts as absent.

maxLength16384

interface BetaSystemMessageOutputConfig { effort }

Per-message output configuration on a role:"system" input message.

Fields here apply per-turn; format remains top-level only. An empty {} is accepted on a message that carries content; a message with neither content nor output_config fields is rejected.

effort?: "low" | "medium" | "high" | 2 more | null

How much effort the model should put into its response. Higher effort levels may result in more thorough analysis but take longer.

Valid values are low, medium, high, xhigh, or max.

One of the following:

"low"

"medium"

"high"

"xhigh"

"max"

interface BetaTextBlock { type: "text"; citations; text }

interface BetaTextBlockParam { type: "text"; text; cache_control; citations }

type BetaTextCitation = BetaCitationCharLocation | BetaCitationPageLocation | BetaCitationContentBlockLocation | 2 more

One of the following:

type BetaTextCitationParam = BetaCitationCharLocationParam | BetaCitationPageLocationParam | BetaCitationContentBlockLocationParam | 2 more

One of the following:

interface BetaTextDelta { type: "text_delta"; text }

type: "text_delta"

defaulttext_delta

text: string

interface BetaTextEditorCodeExecutionCreateResultBlock { type: "text_editor_code_execution_create_result"; is_file_update }

type: "text_editor_code_execution_create_result"

defaulttext_editor_code_execution_create_result

is_file_update: boolean

interface BetaTextEditorCodeExecutionCreateResultBlockParam { type: "text_editor_code_execution_create_result"; is_file_update }

type: "text_editor_code_execution_create_result"

is_file_update: boolean

interface BetaTextEditorCodeExecutionStrReplaceResultBlock { type: "text_editor_code_execution_str_replace_result"; lines; new_lines; /* 3 more */ }

type: "text_editor_code_execution_str_replace_result"

defaulttext_editor_code_execution_str_replace_result

lines: Array<string> | null

new_lines: number | null

new_start: number | null

old_lines: number | null

old_start: number | null

interface BetaTextEditorCodeExecutionStrReplaceResultBlockParam { type: "text_editor_code_execution_str_replace_result"; lines; new_lines; /* 3 more */ }

type: "text_editor_code_execution_str_replace_result"

lines?: Array<string> | null

new_lines?: number | null

new_start?: number | null

old_lines?: number | null

old_start?: number | null

interface BetaTextEditorCodeExecutionToolResultBlock { type: "text_editor_code_execution_tool_result"; content; tool_use_id }

interface BetaTextEditorCodeExecutionToolResultBlockParam { type: "text_editor_code_execution_tool_result"; content; tool_use_id; cache_control }

interface BetaTextEditorCodeExecutionToolResultError { type: "text_editor_code_execution_tool_result_error"; error_code; error_message }

type: "text_editor_code_execution_tool_result_error"

defaulttext_editor_code_execution_tool_result_error

error_code: "invalid_tool_input" | "unavailable" | "too_many_requests" | 2 more

One of the following:

"invalid_tool_input"

"unavailable"

"too_many_requests"

"execution_time_exceeded"

"file_not_found"

error_message: string | null

interface BetaTextEditorCodeExecutionToolResultErrorParam { type: "text_editor_code_execution_tool_result_error"; error_code; error_message }

type: "text_editor_code_execution_tool_result_error"

error_code: "invalid_tool_input" | "unavailable" | "too_many_requests" | 2 more

One of the following:

"invalid_tool_input"

"unavailable"

"too_many_requests"

"execution_time_exceeded"

"file_not_found"

error_message?: string | null

interface BetaTextEditorCodeExecutionViewResultBlock { type: "text_editor_code_execution_view_result"; content; file_type; /* 3 more */ }

type: "text_editor_code_execution_view_result"

defaulttext_editor_code_execution_view_result

content: string

file_type: "text" | "image" | "pdf"

One of the following:

"text"

"image"

"pdf"

num_lines: number | null

start_line: number | null

total_lines: number | null

interface BetaTextEditorCodeExecutionViewResultBlockParam { type: "text_editor_code_execution_view_result"; content; file_type; /* 3 more */ }

type: "text_editor_code_execution_view_result"

content: string

file_type: "text" | "image" | "pdf"

One of the following:

"text"

"image"

"pdf"

num_lines?: number | null

start_line?: number | null

total_lines?: number | null

interface BetaThinkingBlock { type: "thinking"; signature; thinking }

type: "thinking"

defaultthinking

signature: string

A value used to verify that this thinking block was generated by Claude when it is passed back to the API.

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.

thinking: string

The text of Claude's thinking process for this block.

interface BetaThinkingBlockBinding { prefix_mismatch_behavior }

Controls for block binding: what happens when a thinking block this request sends back fails the conversation check. Every field is optional; an empty object means every default.

prefix_mismatch_behavior?: BetaThinkingPrefixMismatchBehavior | null

"error" (default) | "drop_block". What happens when a thinking block in messages fails the conversation check (it was created in a different conversation, or the messages before it have changed since). "error" fails the request with a 400 error. "drop_block" removes the failing blocks and the request proceeds; each removal is reported in input_transformations.

One of the following:

"error"

"drop_block"

interface BetaThinkingBlockParam { type: "thinking"; signature; thinking }

type: "thinking"

signature: string

The signature value of this thinking block, exactly as returned by the API in a previous response. Used to verify that the block was generated by Claude.

Thinking blocks must be passed back unmodified and in their original order; a modified block results in a 400 invalid_request_error.

thinking: string

The thinking text of this block as returned by the API.

interface BetaThinkingConfigAdaptive { type: "adaptive"; block_binding; display }

type: "adaptive"

block_binding?: BetaThinkingBlockBinding | null

Controls for block binding: what happens when a thinking block this request sends back fails the conversation check. null, absent or an empty object means every default.

prefix_mismatch_behavior?: BetaThinkingPrefixMismatchBehavior | null

One of the following:

"error"

"drop_block"

display?: "summarized" | "omitted" | "updates" | 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. The default depends on the model; see Controlling thinking display.

One of the following:

"summarized"

"omitted"

"updates"

interface BetaThinkingConfigBetweenTools { type: "between_tools" }

type: "between_tools"

interface BetaThinkingConfigDisabled { type: "disabled" }

type: "disabled"

interface BetaThinkingConfigEnabled { type: "enabled"; budget_tokens; block_binding; display }

type BetaThinkingConfigParam = BetaThinkingConfigEnabled | BetaThinkingConfigDisabled | BetaThinkingConfigBetweenTools | BetaThinkingConfigAdaptive

Configuration for Claude's thinking.

With {"type": "adaptive"}, Claude decides when and how much to think. With {"type": "enabled"} (manual extended thinking), you set a budget_tokens of at least 1,024. Thinking tokens count toward your max_tokens limit.

Which type values are accepted, and what happens when you omit thinking, depend on the model. See thinking for each model's behavior.

One of the following:

interface BetaThinkingDelta { type: "thinking_delta"; estimated_tokens; thinking }

type: "thinking_delta"

defaultthinking_delta

estimated_tokens: number | null

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.

thinking: string

The incremental thinking text for this content block. Concatenate the thinking values of successive thinking_delta events to assemble the block's full thinking value.

interface BetaThinkingDroppedInputTransformation { type: "thinking_dropped"; path; reason }

type: "thinking_dropped"

Always thinking_dropped for this entry type.

defaultthinking_dropped

path: string

Where the removed block was in your request, as messages.{i}.content.{j}: i indexes the messages array you sent and j that message's content array — the same form error messages use.

reason: "model_binding_mismatch" | "prefix_binding_mismatch" | "organization_binding_mismatch" | "end_user_binding_mismatch"

Which binding check removed the block: model_binding_mismatch — it was created by a model whose reasoning the requested model may not read; prefix_binding_mismatch — the conversation before it differs from the conversation it was created in (the rest of that turn's consecutive thinking blocks are removed with it, each with this reason); organization_binding_mismatch — it was created under a different organization (an Anthropic organization, AWS account or Google Cloud project) and this organization is not one of its additional organizations; end_user_binding_mismatch — it was created for a different end user, or was removed by the consumer-organization binding. A block that would fail several checks reports one reason, in this order of precedence: organization_binding_mismatch, end_user_binding_mismatch, model_binding_mismatch, prefix_binding_mismatch.

One of the following:

"model_binding_mismatch"

"prefix_binding_mismatch"

"organization_binding_mismatch"

"end_user_binding_mismatch"

interface BetaThinkingMismatchAllowedInputTransformation { type: "thinking_mismatch_allowed"; path; reason }

type: "thinking_mismatch_allowed"

Always thinking_mismatch_allowed for this entry type.

defaultthinking_mismatch_allowed

path: string

Where the block is in your request, as messages.{i}.content.{j}: i indexes the messages array you sent and j that message's content array — the same form error messages use.

reason: "model_binding_mismatch" | "prefix_binding_mismatch" | "organization_binding_mismatch" | "end_user_binding_mismatch"

Which binding check the block failed; the block was shown to the model all the same. Always prefix_binding_mismatch today — the conversation before the block differs from the conversation it was created in, or the block carries no record of one on a model that requires it. Were the check enforced for this request, the block would have been removed or the request rejected (thinking.block_binding.prefix_mismatch_behavior). A removal also takes the rest of that turn's consecutive thinking blocks, whereas here each block is checked on its own, so thinking_mismatch_allowed entries are a lower bound on what enforcement would remove.

One of the following:

"model_binding_mismatch"

"prefix_binding_mismatch"

"organization_binding_mismatch"

"end_user_binding_mismatch"

type BetaThinkingPrefixMismatchBehavior = "error" | "drop_block"

What happens when a thinking block in messages fails the conversation check: it was created in a different conversation, or the messages before it have changed since. "error" (the default) fails the request with a 400 error. "drop_block" removes the failing blocks and the request proceeds; the model no longer sees the dropped reasoning.

One of the following:

"error"

"drop_block"

interface BetaThinkingTurns { type: "thinking_turns"; value }

type: "thinking_turns"

value: number

minimum1

interface BetaTokenTaskBudget { type: "tokens"; total; remaining }

User-configurable total token budget across contexts.

type: "tokens"

The budget type. Currently only 'tokens' is supported.

total: number

Total token budget across all contexts in the session.

minimum1024

remaining?: number | null

Remaining tokens in the budget. Use this to track usage across contexts when implementing compaction client-side. Defaults to total if not provided.

minimum0

interface BetaTool { type; input_schema; name; /* 7 more */ }

interface BetaToolBash20241022 { type: "bash_20241022"; name; allowed_callers; /* 4 more */ }

interface BetaToolBash20250124 { type: "bash_20250124"; name; allowed_callers; /* 4 more */ }

interface BetaToolChangeMCPToolReference { type: "mcp_tool_reference"; name; server_name }

Reference to a single MCP tool by its server and remote name; the same server_name/name pair mcp_tool_use carries.

type: "mcp_tool_reference"

server_name: string

interface BetaToolChangeMCPToolsetReference { type: "mcp_toolset_reference"; server_name }

Reference to every tool in the named MCP server's toolset.

type: "mcp_toolset_reference"

server_name: string

interface BetaToolChangeToolDefinition { type: "tool_definition"; definition }

A tool defined by value, as a compaction block's tool_changes entry reports it: definition is the tool's definition as it was sent, in the form of a tools entry, without cache_control. Send it back unchanged with the block.

type: "tool_definition"

defaulttool_definition

definition: BetaResponseToolUnion

One of the following:

interface BetaToolChangeToolDefinitionParam { type: "tool_definition"; definition }

A tool defined by value: definition is a tools entry (any kind tools accepts, an MCP toolset included). An mcp_toolset given here also requires the mcp-client-2026-09-15 beta.

type: "tool_definition"

definition: BetaToolUnion

One of the following:

interface BetaToolChangeToolReference { type: "tool_reference"; name }

Reference to a single tool, by the name the model uses to call it: a tool declared in tools or defined by an earlier tool_addition block. 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.

type: "tool_reference"

pattern^[a-zA-Z0-9_-]{1,128}$

type BetaToolChoice = BetaToolChoiceAuto | BetaToolChoiceAny | BetaToolChoiceTool | BetaToolChoiceNone

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.

One of the following:

interface BetaToolChoiceAny { type: "any"; disable_parallel_tool_use }

The model will use any available tools.

type: "any"

disable_parallel_tool_use?: boolean

Whether to disable parallel tool use.

Defaults to false. If set to true, the model will output exactly one tool use.

interface BetaToolChoiceAuto { type: "auto"; disable_parallel_tool_use }

The model will automatically decide whether to use tools.

type: "auto"

disable_parallel_tool_use?: boolean

Whether to disable parallel tool use.

Defaults to false. If set to true, the model will output at most one tool use.

interface BetaToolChoiceNone { type: "none" }

The model will not be allowed to use tools.

type: "none"

interface BetaToolChoiceTool { type: "tool"; name; disable_parallel_tool_use }

The model will use the specified tool with tool_choice.name.

type: "tool"

The name of the tool to use.

disable_parallel_tool_use?: boolean

Whether to disable parallel tool use.

Defaults to false. If set to true, the model will output exactly one tool use.

interface BetaToolComputerUse20241022 { type: "computer_20241022"; display_height_px; display_width_px; /* 7 more */ }

interface BetaToolComputerUse20250124 { type: "computer_20250124"; display_height_px; display_width_px; /* 7 more */ }

interface BetaToolComputerUse20251124 { type: "computer_20251124"; display_height_px; display_width_px; /* 8 more */ }

interface BetaToolReferenceBlock { type: "tool_reference"; tool_name }

type: "tool_reference"

defaulttool_reference

tool_name: string

minLength1

maxLength256

pattern^[a-zA-Z0-9_-]{1,256}$

interface BetaToolReferenceBlockParam { type: "tool_reference"; tool_name; cache_control }

Tool reference block that can be included in tool_result content.

type: "tool_reference"

tool_name: string

minLength1

maxLength256

pattern^[a-zA-Z0-9_-]{1,256}$

cache_control?: BetaCacheControlEphemeral | null

Create a cache control breakpoint at this content block.

type: "ephemeral"

ttl?: "5m" | "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 for details.

One of the following:

"5m"

"1h"

interface BetaToolResultBlockParam { type: "tool_result"; tool_use_id; cache_control; /* 3 more */ }

interface BetaToolSearchToolBm25_20251119 { type; name; allowed_callers; /* 3 more */ }

interface BetaToolSearchToolRegex20251119 { type; name; allowed_callers; /* 3 more */ }

interface BetaToolSearchToolResultBlock { type: "tool_search_tool_result"; content; tool_use_id }

interface BetaToolSearchToolResultBlockParam { type: "tool_search_tool_result"; content; tool_use_id; cache_control }

interface BetaToolSearchToolResultError { type: "tool_search_tool_result_error"; error_code; error_message }

type: "tool_search_tool_result_error"

defaulttool_search_tool_result_error

error_code: "invalid_tool_input" | "unavailable" | "too_many_requests" | "execution_time_exceeded"

One of the following:

"invalid_tool_input"

"unavailable"

"too_many_requests"

"execution_time_exceeded"

error_message: string | null

interface BetaToolSearchToolResultErrorParam { type: "tool_search_tool_result_error"; error_code; error_message }

type: "tool_search_tool_result_error"

error_code: "invalid_tool_input" | "unavailable" | "too_many_requests" | "execution_time_exceeded"

One of the following:

"invalid_tool_input"

"unavailable"

"too_many_requests"

"execution_time_exceeded"

error_message?: string | null

interface BetaToolSearchToolSearchResultBlock { type: "tool_search_tool_search_result"; tool_references }

type: "tool_search_tool_search_result"

defaulttool_search_tool_search_result

tool_references: Array<BetaToolReferenceBlock { type: "tool_reference"; tool_name }>

type: "tool_reference"

defaulttool_reference

tool_name: string

minLength1

maxLength256

pattern^[a-zA-Z0-9_-]{1,256}$

interface BetaToolSearchToolSearchResultBlockParam { type: "tool_search_tool_search_result"; tool_references }

type: "tool_search_tool_search_result"

tool_references: Array<BetaToolReferenceBlockParam { type: "tool_reference"; tool_name; cache_control }>

type: "tool_reference"

tool_name: string

minLength1

maxLength256

pattern^[a-zA-Z0-9_-]{1,256}$

cache_control?: BetaCacheControlEphemeral | null

Create a cache control breakpoint at this content block.

type: "ephemeral"

ttl?: "5m" | "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 for details.

One of the following:

"5m"

"1h"

interface BetaToolTextEditor20241022 { type: "text_editor_20241022"; name; allowed_callers; /* 4 more */ }

interface BetaToolTextEditor20250124 { type: "text_editor_20250124"; name; allowed_callers; /* 4 more */ }

interface BetaToolTextEditor20250429 { type: "text_editor_20250429"; name; allowed_callers; /* 4 more */ }

interface BetaToolTextEditor20250728 { type: "text_editor_20250728"; name; allowed_callers; /* 5 more */ }

type BetaToolUnion = BetaTool | BetaToolBash20241022 | BetaToolBash20250124 | 25 more

One of the following:

interface BetaToolUseBlock { type: "tool_use"; id; input; /* 3 more */ }

interface BetaToolUseBlockParam { type: "tool_use"; id; input; /* 4 more */ }

type BetaToolUseCaller = BetaDirectCaller | BetaServerToolCaller | BetaServerToolCaller20260120

Which party invoked the tool call: the model directly, or a server tool on its behalf.

One of the following:

interface BetaDirectCaller { type: "direct" }

Tool invocation directly from the model.

type: "direct"

interface BetaServerToolCaller { type: "code_execution_20250825"; tool_id }

Tool invocation generated by a server-side tool.

type: "code_execution_20250825"

tool_id: string

pattern^srvtoolu_[a-zA-Z0-9_]+$

interface BetaServerToolCaller20260120 { type: "code_execution_20260120"; tool_id }

type: "code_execution_20260120"

tool_id: string

pattern^srvtoolu_[a-zA-Z0-9_]+$

interface BetaToolUsesKeep { type: "tool_uses"; value }

type: "tool_uses"

value: number

minimum0

interface BetaToolUsesTrigger { type: "tool_uses"; value }

type: "tool_uses"

value: number

minimum1

type BetaToolsetToolUseBlock = BetaBrowserToolUseBlock | BetaComputerToolUseBlock | BetaToolUseBlock

One of the following:

interface BetaURLImageSource { type: "url"; url }

type: "url"

url: string

interface BetaURLPDFSource { type: "url"; url }

type: "url"

url: string

interface BetaUsage { cache_creation; cache_creation_input_tokens; cache_read_input_tokens; /* 9 more */ }

interface BetaUserLocation { type: "approximate"; city; country; /* 2 more */ }

type: "approximate"

city?: string | null

The city of the user.

minLength1

maxLength255

country?: string | null

The two letter ISO country code of the user.

minLength2

maxLength2

region?: string | null

The region of the user.

minLength1

maxLength255

timezone?: string | null

The IANA timezone of the user.

minLength1

maxLength255

interface BetaWebFetchBlock { type: "web_fetch_result"; content; retrieved_at; url }

type: "web_fetch_result"

defaultweb_fetch_result

content: BetaDocumentBlock { type: "document"; citations; source; title }

retrieved_at: string | null

ISO 8601 timestamp when the content was retrieved

url: string

Fetched content URL

interface BetaWebFetchBlockParam { type: "web_fetch_result"; content; url; retrieved_at }

type: "web_fetch_result"

content: BetaRequestDocumentBlock { type: "document"; source; cache_control; /* 3 more */ }

url: string

Fetched content URL

retrieved_at?: string | null

ISO 8601 timestamp when the content was retrieved

interface BetaWebFetchTool20250910 { type: "web_fetch_20250910"; name; allowed_callers; /* 9 more */ }

interface BetaWebFetchTool20260209 { type: "web_fetch_20260209"; name; allowed_callers; /* 9 more */ }

interface BetaWebFetchTool20260309 { type: "web_fetch_20260309"; name; allowed_callers; /* 10 more */ }

Web fetch tool with use_cache parameter for bypassing cached content.

interface BetaWebFetchTool20260318 { type: "web_fetch_20260318"; name; allowed_callers; /* 11 more */ }

interface BetaWebFetchToolResultBlock { type: "web_fetch_tool_result"; content; tool_use_id; caller }

interface BetaWebFetchToolResultBlockParam { type: "web_fetch_tool_result"; content; tool_use_id; /* 2 more */ }

interface BetaWebFetchToolResultErrorBlock { type: "web_fetch_tool_result_error"; error_code }

type: "web_fetch_tool_result_error"

defaultweb_fetch_tool_result_error

error_code: BetaWebFetchToolResultErrorCode

One of the following:

"invalid_tool_input"

"url_too_long"

"url_not_allowed"

"url_not_in_prior_context"

"url_not_accessible"

"unsupported_content_type"

"too_many_requests"

"max_uses_exceeded"

"unavailable"

"content_too_large"

interface BetaWebFetchToolResultErrorBlockParam { type: "web_fetch_tool_result_error"; error_code }

type: "web_fetch_tool_result_error"

error_code: BetaWebFetchToolResultErrorCode

One of the following:

"invalid_tool_input"

"url_too_long"

"url_not_allowed"

"url_not_in_prior_context"

"url_not_accessible"

"unsupported_content_type"

"too_many_requests"

"max_uses_exceeded"

"unavailable"

"content_too_large"

type BetaWebFetchToolResultErrorCode = "invalid_tool_input" | "url_too_long" | "url_not_allowed" | 7 more

One of the following:

"invalid_tool_input"

"url_too_long"

"url_not_allowed"

"url_not_in_prior_context"

"url_not_accessible"

"unsupported_content_type"

"too_many_requests"

"max_uses_exceeded"

"unavailable"

"content_too_large"

interface BetaWebFetchURLSourceAll { type: "all" }

The url_sources variant under which a source contributes in full: every result of the tool filter's source, or all user input.

type: "all"

interface BetaWebFetchURLSourceExcept { type: "except"; tools }

The tool filter variant under which every result but the named tools' contributes.

type: "except"

tools: Array<BetaWebFetchURLSourceToolReference { type: "tool_reference"; name }>

type: "tool_reference"

interface BetaWebFetchURLSourceNone { type: "none" }

The url_sources variant under which a source contributes nothing: no result of the tool filter's source, or no user input.

type: "none"

interface BetaWebFetchURLSourceOnly { type: "only"; tools }

The tool filter variant under which only the named tools' results contribute.

type: "only"

tools: Array<BetaWebFetchURLSourceToolReference { type: "tool_reference"; name }>

type: "tool_reference"

interface BetaWebFetchURLSourceToolReference { type: "tool_reference"; name }

One entry of a tool filter's tools: it must name a tool declared in this request's tools[].

type: "tool_reference"

interface BetaWebFetchURLSources { client_tool_results; server_tool_results; user_input }

Which sources contribute to the set of URLs web fetch may fetch.

Each key is a tagged variant: user_input is all or none; the two tool filters are all, none, only (only the named tools' results) or except (every result but the named tools'). A named tool must be declared in this request's tools[].

interface BetaWebSearchResultBlock { type: "web_search_result"; encrypted_content; page_age; /* 2 more */ }

type: "web_search_result"

defaultweb_search_result

encrypted_content: string

page_age: string | null

title: string

url: string

interface BetaWebSearchResultBlockParam { type: "web_search_result"; encrypted_content; title; /* 2 more */ }

type: "web_search_result"

encrypted_content: string

title: string

url: string

page_age?: string | null

interface BetaWebSearchTool20250305 { type: "web_search_20250305"; name; allowed_callers; /* 7 more */ }

interface BetaWebSearchTool20260209 { type: "web_search_20260209"; name; allowed_callers; /* 7 more */ }

interface BetaWebSearchTool20260318 { type: "web_search_20260318"; name; allowed_callers; /* 8 more */ }

interface BetaWebSearchToolRequestError { type: "web_search_tool_result_error"; error_code }

type: "web_search_tool_result_error"

error_code: BetaWebSearchToolResultErrorCode

One of the following:

"invalid_tool_input"

"unavailable"

"max_uses_exceeded"

"too_many_requests"

"query_too_long"

"request_too_large"

interface BetaWebSearchToolResultBlock { type: "web_search_tool_result"; content; tool_use_id; caller }

type BetaWebSearchToolResultBlockContent = BetaWebSearchToolResultError | Array<BetaWebSearchResultBlock>

One of the following:

interface BetaWebSearchToolResultBlockParam { type: "web_search_tool_result"; content; tool_use_id; /* 2 more */ }

type BetaWebSearchToolResultBlockParamContent = Array<BetaWebSearchResultBlockParam> | BetaWebSearchToolRequestError

One of the following:

interface BetaWebSearchToolResultError { type: "web_search_tool_result_error"; error_code }

type: "web_search_tool_result_error"

defaultweb_search_tool_result_error

error_code: BetaWebSearchToolResultErrorCode

One of the following:

"invalid_tool_input"

"unavailable"

"max_uses_exceeded"

"too_many_requests"

"query_too_long"

"request_too_large"

type BetaWebSearchToolResultErrorCode = "invalid_tool_input" | "unavailable" | "max_uses_exceeded" | 3 more

One of the following:

"invalid_tool_input"

"unavailable"

"max_uses_exceeded"

"too_many_requests"

"query_too_long"

"request_too_large"

MessaggiBatch

Crea un batch di messaggi

client.beta.messages.batches.create(params, options?): BetaMessageBatch

POST/v1/messages/batches

Invia un batch di richieste di creazione di messaggi.

Recupera un batch di messaggi

client.beta.messages.batches.retrieve(messageBatchID, params?, options?): BetaMessageBatch

GET/v1/messages/batches/{message_batch_id}

Questo endpoint è idempotente e può essere utilizzato per eseguire il polling del completamento di un batch di messaggi. Per accedere ai risultati di un batch di messaggi, effettua una richiesta all'URL indicato nel campo results_url della risposta.

Elenca i batch di messaggi

client.beta.messages.batches.list(params?, options?): Page<BetaMessageBatch>

GET/v1/messages/batches

Elenca tutti i batch di messaggi all'interno di un Workspace. I batch creati più di recente vengono restituiti per primi.

Annulla un batch di messaggi

client.beta.messages.batches.cancel(messageBatchID, params?, options?): BetaMessageBatch

POST/v1/messages/batches/{message_batch_id}/cancel

I batch possono essere annullati in qualsiasi momento prima del termine dell'elaborazione. Una volta avviato l'annullamento, il batch entra nello stato canceling, durante il quale il sistema può completare eventuali richieste in corso non interrompibili prima di finalizzare l'annullamento.

Elimina un batch di messaggi

client.beta.messages.batches.delete(messageBatchID, params?, options?): BetaDeletedMessageBatch

DELETE/v1/messages/batches/{message_batch_id}

Recupera i risultati di un batch di messaggi

client.beta.messages.batches.results(messageBatchID, params?, options?): BetaMessageBatchIndividualResponse | Stream<BetaMessageBatchIndividualResponse>

GET/v1/messages/batches/{message_batch_id}/results

Trasmette in streaming i risultati di un batch di messaggi come file .jsonl.

Messaggi

Models

MessaggiBatch

MessaggiBatch