Messages
Create a Message
beta.messages.create(**kwargs) -> BetaMessageSend a structured list of input messages with text and/or image content, and the model will generate the next message in the conversation.
Count tokens in a Message
beta.messages.count_tokens(**kwargs) -> BetaMessageTokensCountCount the number of tokens in a Message.
Models
class BetaAdvisorMessageIterationUsage: type: "advisor_message"; cache_creation; cache_creation_input_tokens; ... # 4 moreToken usage for an advisor sub-inference iteration.
Token usage for an advisor sub-inference iteration.
class BetaAdvisorRedactedResultBlock: type: "advisor_redacted_result"; encrypted_content; stop_reason
type: Literal["advisor_redacted_result"]
Opaque blob containing the advisor's output. Round-trip verbatim; do not inspect or modify.
The advisor sub-inference's stop reason (same values as the top-level message stop_reason).
class BetaAdvisorRedactedResultBlockParam: type: "advisor_redacted_result"; encrypted_content; stop_reason
Opaque blob produced by a prior response; must be round-tripped verbatim.
class BetaAdvisorResultBlock: type: "advisor_result"; stop_reason; text
type: Literal["advisor_result"]
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.
class BetaAdvisorResultBlockParam: type: "advisor_result"; text; stop_reason
class BetaAdvisorTool20260301: type: "advisor_20260301"; model; name; ... # 7 more
class BetaAdvisorToolResultBlock: type: "advisor_tool_result"; content; tool_use_id
class BetaAdvisorToolResultBlockParam: type: "advisor_tool_result"; content; tool_use_id; cache_control
class BetaAdvisorToolResultError: type: "advisor_tool_result_error"; error_code
type: Literal["advisor_tool_result_error"]
error_code: Literal["max_uses_exceeded", "prompt_too_long", "too_many_requests", 4 more]
class BetaAdvisorToolResultErrorParam: type: "advisor_tool_result_error"; error_code
error_code: Literal["max_uses_exceeded", "prompt_too_long", "too_many_requests", 4 more]
class BetaAllThinkingTurns: type: "all"
class BetaBase64ImageSource: type: "base64"; data; media_type
data: str
media_type: Literal["image/jpeg", "image/png", "image/gif", "image/webp"]
class BetaBase64PDFSource: type: "base64"; data; media_type
data: str
class BetaBashCodeExecutionOutputBlock: type: "bash_code_execution_output"; file_id
type: Literal["bash_code_execution_output"]
class BetaBashCodeExecutionOutputBlockParam: type: "bash_code_execution_output"; file_id
class BetaBashCodeExecutionResultBlock: type: "bash_code_execution_result"; content; return_code; ... # 2 more
type: Literal["bash_code_execution_result"]
content: List[BetaBashCodeExecutionOutputBlock]
type: Literal["bash_code_execution_output"]
class BetaBashCodeExecutionResultBlockParam: type: "bash_code_execution_result"; content; return_code; ... # 2 more
content: List[BetaBashCodeExecutionOutputBlockParam]
class BetaBashCodeExecutionToolResultBlock: type: "bash_code_execution_tool_result"; content; tool_use_id
class BetaBashCodeExecutionToolResultBlockParam: type: "bash_code_execution_tool_result"; content; tool_use_id; cache_control
class BetaBashCodeExecutionToolResultError: type: "bash_code_execution_tool_result_error"; error_code
type: Literal["bash_code_execution_tool_result_error"]
error_code: Literal["invalid_tool_input", "unavailable", "too_many_requests", 2 more]
class BetaBashCodeExecutionToolResultErrorParam: type: "bash_code_execution_tool_result_error"; error_code
error_code: Literal["invalid_tool_input", "unavailable", "too_many_requests", 2 more]
type BetaBrowserClickTarget = ...Where to act: either a viewport coordinate or an element reference.
Where to act: either a viewport coordinate or an element reference.
class BetaBrowserCoordinateTarget: type: "coordinate"; x; yA point in the browser viewport, in viewport pixels (the same frame as a
full-viewport screenshot).
A point in the browser viewport, in viewport pixels (the same frame as a full-viewport screenshot).
x: intPixels from the left edge of the viewport.
Pixels from the left edge of the viewport.
y: intPixels from the top edge of the viewport.
Pixels from the top edge of the viewport.
class BetaBrowserRefTarget: type: "ref"; refAn 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.
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.
An element reference (e.g. "ref_7") returned by a prior read_page or find result.
class BetaBrowserCloseTabConfig: defer_loading; enabledclose_tab's config overrides.
close_tab's config overrides.
Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.
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.
class BetaBrowserCloseTabInput: tab_idClose the tab with the given tab_id.
Close the tab with the given tab_id.
The tab to close.
class BetaBrowserCloseTabToolUseBlock: type: "tool_use"; id; input; ... # 3 more
class BetaBrowserCoordinateTarget: type: "coordinate"; x; yA point in the browser viewport, in viewport pixels (the same frame as a
full-viewport screenshot).
A point in the browser viewport, in viewport pixels (the same frame as a full-viewport screenshot).
x: intPixels from the left edge of the viewport.
Pixels from the left edge of the viewport.
y: intPixels from the top edge of the viewport.
Pixels from the top edge of the viewport.
class BetaBrowserDoubleClickConfig: defer_loading; enableddouble_click's config overrides.
double_click's config overrides.
Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.
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.
class BetaBrowserDoubleClickInput: target; modifiers; tab_idDouble left-click at a viewport coordinate or on an element by reference.
Double left-click at a viewport coordinate or on an element by reference.
class BetaBrowserDoubleClickToolUseBlock: type: "tool_use"; id; input; ... # 3 more
class BetaBrowserFileUploadConfig: defer_loading; enabledfile_upload's config overrides.
file_upload's config overrides.
Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.
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.
class BetaBrowserFileUploadInput: target; document_ids; paths; tab_idSet 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.
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: BetaBrowserRefTargetAn 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.
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.
An element reference (e.g. "ref_7") returned by a prior read_page or find result.
document_ids: Optional[List[str]]References to files the harness has staged, for deployments where the browser executor cannot read the caller's filesystem.
References to files the harness has staged, for deployments where the browser executor cannot read the caller's filesystem.
paths: Optional[List[str]]File paths on the browser executor's filesystem.
File paths on the browser executor's filesystem.
Tab to act on. Defaults to the active tab when omitted.
class BetaBrowserFileUploadToolUseBlock: type: "tool_use"; id; input; ... # 3 more
class BetaBrowserFindConfig: defer_loading; enabledfind's config overrides.
find's config overrides.
Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.
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.
class BetaBrowserFindInput: query; tab_idFind elements matching a natural-language description (e.g. "search bar", "add to
cart button") and return up to 20 matches with element references.
Find elements matching a natural-language description (e.g. "search bar", "add to cart button") and return up to 20 matches with element references.
Natural-language description of the element(s) to find.
Tab to act on. Defaults to the active tab when omitted.
class BetaBrowserFindToolUseBlock: type: "tool_use"; id; input; ... # 3 more
class BetaBrowserFormInputConfig: defer_loading; enabledform_input's config overrides.
form_input's config overrides.
Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.
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.
class BetaBrowserFormInputInput: target; value; tab_idSet the value of a form element (input, textarea, select, checkbox). Use a
boolean for checkboxes, an option value or text for selects.
Set the value of a form element (input, textarea, select, checkbox). Use a boolean for checkboxes, an option value or text for selects.
target: BetaBrowserRefTargetAn 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.
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.
An element reference (e.g. "ref_7") returned by a prior read_page or find result.
value: BetaBrowserFormInputValueThe value to set.
The value to set.
Tab to act on. Defaults to the active tab when omitted.
class BetaBrowserFormInputToolUseBlock: type: "tool_use"; id; input; ... # 3 more
type BetaBrowserFormInputValue = Union[str, float, bool]
class BetaBrowserGetPageTextConfig: defer_loading; enabledget_page_text's config overrides.
get_page_text's config overrides.
Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.
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.
class BetaBrowserGetPageTextInput: tab_idReturn the page's visible text content as plain text, prioritizing article
content. Suited to articles, documentation, and other text-heavy pages.
Return the page's visible text content as plain text, prioritizing article content. Suited to articles, documentation, and other text-heavy pages.
Tab to act on. Defaults to the active tab when omitted.
class BetaBrowserGetPageTextToolUseBlock: type: "tool_use"; id; input; ... # 3 more
class BetaBrowserHoldKeyConfig: defer_loading; enabledhold_key's config overrides.
hold_key's config overrides.
Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.
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.
class BetaBrowserHoldKeyInput: duration; text; tab_idHold a key or key chord down for a duration, then release it. Uses the same key
names and "+" chord syntax as the key action.
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: floatSeconds to hold the key down (maximum 30).
Seconds to hold the key down (maximum 30).
The key or chord to hold.
Tab to act on. Defaults to the active tab when omitted.
class BetaBrowserHoldKeyToolUseBlock: type: "tool_use"; id; input; ... # 3 more
class BetaBrowserHoverConfig: defer_loading; enabledhover's config overrides.
hover's config overrides.
Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.
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.
class BetaBrowserHoverInput: target; tab_idMove the cursor to a coordinate or element without clicking.
Move the cursor to a coordinate or element without clicking.
class BetaBrowserHoverToolUseBlock: type: "tool_use"; id; input; ... # 3 more
class BetaBrowserJavascriptExecConfig: defer_loading; enabledjavascript_exec's config overrides.
javascript_exec's config overrides.
Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.
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.
class BetaBrowserJavascriptExecInput: text; tab_idExecute 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.
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.
JavaScript to execute in the page context.
Tab to act on. Defaults to the active tab when omitted.
class BetaBrowserJavascriptExecToolUseBlock: type: "tool_use"; id; input; ... # 3 more
class BetaBrowserKeyConfig: defer_loading; enabledkey's config overrides.
key's config overrides.
Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.
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.
class BetaBrowserKeyInput: text; repeat; tab_idPress 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.
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.
The key, chord, or space-separated sequence to press.
repeat: Optional[int]Number of times to repeat. Default 1.
Number of times to repeat. Default 1.
Tab to act on. Defaults to the active tab when omitted.
class BetaBrowserKeyToolUseBlock: type: "tool_use"; id; input; ... # 3 more
class BetaBrowserLeftClickConfig: defer_loading; enabledleft_click's config overrides.
left_click's config overrides.
Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.
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.
class BetaBrowserLeftClickDragConfig: defer_loading; enabledleft_click_drag's config overrides.
left_click_drag's config overrides.
Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.
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.
class BetaBrowserLeftClickDragInput: from_; target; tab_idPress at from, drag to target, release. Both must be coordinate targets.
Press at from, drag to target, release. Both must be coordinate targets.
from_: BetaBrowserCoordinateTargetA point in the browser viewport, in viewport pixels (the same frame as a
full-viewport screenshot).
A point in the browser viewport, in viewport pixels (the same frame as a full-viewport screenshot).
x: intPixels from the left edge of the viewport.
Pixels from the left edge of the viewport.
y: intPixels from the top edge of the viewport.
Pixels from the top edge of the viewport.
target: BetaBrowserCoordinateTargetA point in the browser viewport, in viewport pixels (the same frame as a
full-viewport screenshot).
A point in the browser viewport, in viewport pixels (the same frame as a full-viewport screenshot).
x: intPixels from the left edge of the viewport.
Pixels from the left edge of the viewport.
y: intPixels from the top edge of the viewport.
Pixels from the top edge of the viewport.
Tab to act on. Defaults to the active tab when omitted.
class BetaBrowserLeftClickDragToolUseBlock: type: "tool_use"; id; input; ... # 3 more
class BetaBrowserLeftClickInput: target; modifiers; tab_idLeft-click at a viewport coordinate or on an element by reference.
Left-click at a viewport coordinate or on an element by reference.
class BetaBrowserLeftClickToolUseBlock: type: "tool_use"; id; input; ... # 3 more
class BetaBrowserLeftMouseDownConfig: defer_loading; enabledleft_mouse_down's config overrides.
left_mouse_down's config overrides.
Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.
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.
class BetaBrowserLeftMouseDownInput: target; tab_idPress and hold the left mouse button at a viewport coordinate. Pair with
left_mouse_up to perform a custom drag.
Press and hold the left mouse button at a viewport coordinate. Pair with left_mouse_up to perform a custom drag.
target: BetaBrowserCoordinateTargetA point in the browser viewport, in viewport pixels (the same frame as a
full-viewport screenshot).
A point in the browser viewport, in viewport pixels (the same frame as a full-viewport screenshot).
x: intPixels from the left edge of the viewport.
Pixels from the left edge of the viewport.
y: intPixels from the top edge of the viewport.
Pixels from the top edge of the viewport.
Tab to act on. Defaults to the active tab when omitted.
class BetaBrowserLeftMouseDownToolUseBlock: type: "tool_use"; id; input; ... # 3 more
class BetaBrowserLeftMouseUpConfig: defer_loading; enabledleft_mouse_up's config overrides.
left_mouse_up's config overrides.
Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.
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.
class BetaBrowserLeftMouseUpInput: target; tab_idRelease the left mouse button at a viewport coordinate.
Release the left mouse button at a viewport coordinate.
target: BetaBrowserCoordinateTargetA point in the browser viewport, in viewport pixels (the same frame as a
full-viewport screenshot).
A point in the browser viewport, in viewport pixels (the same frame as a full-viewport screenshot).
x: intPixels from the left edge of the viewport.
Pixels from the left edge of the viewport.
y: intPixels from the top edge of the viewport.
Pixels from the top edge of the viewport.
Tab to act on. Defaults to the active tab when omitted.
class BetaBrowserLeftMouseUpToolUseBlock: type: "tool_use"; id; input; ... # 3 more
class BetaBrowserListTabsConfig: defer_loading; enabledlist_tabs's config overrides.
list_tabs's config overrides.
Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.
Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema.
List all open tabs with each tab's tab_id, title, and URL.
class BetaBrowserListTabsToolUseBlock: type: "tool_use"; id; input; ... # 3 more
class BetaBrowserMiddleClickConfig: defer_loading; enabledmiddle_click's config overrides.
middle_click's config overrides.
Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.
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.
class BetaBrowserMiddleClickInput: target; modifiers; tab_idMiddle-click at a viewport coordinate or on an element by reference.
Middle-click at a viewport coordinate or on an element by reference.
class BetaBrowserMiddleClickToolUseBlock: type: "tool_use"; id; input; ... # 3 more
class BetaBrowserMouseMoveConfig: defer_loading; enabledmouse_move's config overrides.
mouse_move's config overrides.
Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.
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.
class BetaBrowserMouseMoveInput: target; tab_idMove the pointer to a viewport coordinate without clicking.
Move the pointer to a viewport coordinate without clicking.
target: BetaBrowserCoordinateTargetA point in the browser viewport, in viewport pixels (the same frame as a
full-viewport screenshot).
A point in the browser viewport, in viewport pixels (the same frame as a full-viewport screenshot).
x: intPixels from the left edge of the viewport.
Pixels from the left edge of the viewport.
y: intPixels from the top edge of the viewport.
Pixels from the top edge of the viewport.
Tab to act on. Defaults to the active tab when omitted.
class BetaBrowserMouseMoveToolUseBlock: type: "tool_use"; id; input; ... # 3 more
class BetaBrowserNavigateConfig: defer_loading; enablednavigate's config overrides.
navigate's config overrides.
Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.
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.
class BetaBrowserNavigateInput: url; tab_idNavigate to a URL, or go back/forward/reload in history. The protocol may be
omitted (defaults to https://).
Navigate to a URL, or go back/forward/reload in history. The protocol may be omitted (defaults to https://).
The URL to navigate to, or "back" / "forward" / "reload" for history navigation.
Tab to act on. Defaults to the active tab when omitted.
class BetaBrowserNavigateToolUseBlock: type: "tool_use"; id; input; ... # 3 more
class BetaBrowserNewTabConfig: defer_loading; enablednew_tab's config overrides.
new_tab's config overrides.
Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.
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.
Open a new empty tab and return its tab_id.
class BetaBrowserNewTabToolUseBlock: type: "tool_use"; id; input; ... # 3 more
class BetaBrowserReadConsoleConfig: defer_loading; enabledread_console's config overrides.
read_console's config overrides.
Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.
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.
class BetaBrowserReadConsoleInput: tab_idReturn 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.
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 to act on. Defaults to the active tab when omitted.
class BetaBrowserReadConsoleToolUseBlock: type: "tool_use"; id; input; ... # 3 more
class BetaBrowserReadNetworkConfig: defer_loading; enabledread_network's config overrides.
read_network's config overrides.
Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.
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.
class BetaBrowserReadNetworkInput: tab_idReturn 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.
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 to act on. Defaults to the active tab when omitted.
class BetaBrowserReadNetworkToolUseBlock: type: "tool_use"; id; input; ... # 3 more
class BetaBrowserReadPageConfig: defer_loading; enabledread_page's config overrides.
read_page's config overrides.
Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.
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 = Literal["all", "interactive"]
class BetaBrowserReadPageInput: depth; filter; ref; tab_idReturn 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.
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: Optional[int]Maximum tree depth. Default 15.
Maximum tree depth. Default 15.
filter: Optional[BetaBrowserReadPageFilter]Which elements to include. Omitted: every visible element. "interactive": interactive elements only. "all": additionally includes off-viewport elements.
Which elements to include. Omitted: every visible element. "interactive": interactive elements only. "all": additionally includes off-viewport elements.
Element reference to read a subtree from. Omit to read from the page root.
Tab to act on. Defaults to the active tab when omitted.
class BetaBrowserReadPageToolUseBlock: type: "tool_use"; id; input; ... # 3 more
class BetaBrowserRefTarget: type: "ref"; refAn 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.
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.
An element reference (e.g. "ref_7") returned by a prior read_page or find result.
class BetaBrowserRightClickConfig: defer_loading; enabledright_click's config overrides.
right_click's config overrides.
Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.
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.
class BetaBrowserRightClickInput: target; modifiers; tab_idRight-click at a viewport coordinate or on an element by reference.
Right-click at a viewport coordinate or on an element by reference.
class BetaBrowserRightClickToolUseBlock: type: "tool_use"; id; input; ... # 3 more
class BetaBrowserScreenshotConfig: defer_loading; enabledscreenshot's config overrides.
screenshot's config overrides.
Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.
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.
class BetaBrowserScreenshotInput: tab_idCapture the current browser viewport.
Capture the current browser viewport.
Tab to act on. Defaults to the active tab when omitted.
class BetaBrowserScreenshotToolUseBlock: type: "tool_use"; id; input; ... # 3 more
class BetaBrowserScrollConfig: defer_loading; enabledscroll's config overrides.
scroll's config overrides.
Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.
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 = Literal["up", "down", "left", "right"]
class BetaBrowserScrollInput: scroll_direction; target; scroll_amount; tab_idScroll at a viewport position. target must be a coordinate target.
Scroll at a viewport position. target must be a coordinate target.
scroll_direction: BetaBrowserScrollDirection
target: BetaBrowserCoordinateTargetA point in the browser viewport, in viewport pixels (the same frame as a
full-viewport screenshot).
A point in the browser viewport, in viewport pixels (the same frame as a full-viewport screenshot).
x: intPixels from the left edge of the viewport.
Pixels from the left edge of the viewport.
y: intPixels from the top edge of the viewport.
Pixels from the top edge of the viewport.
scroll_amount: Optional[int]Scroll-wheel notches (1–10). Default 3.
Scroll-wheel notches (1–10). Default 3.
Tab to act on. Defaults to the active tab when omitted.
class BetaBrowserScrollToConfig: defer_loading; enabledscroll_to's config overrides.
scroll_to's config overrides.
Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.
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.
class BetaBrowserScrollToInput: target; tab_idScroll an element into view.
Scroll an element into view.
target: BetaBrowserRefTargetAn 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.
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.
An element reference (e.g. "ref_7") returned by a prior read_page or find result.
Tab to act on. Defaults to the active tab when omitted.
class BetaBrowserScrollToToolUseBlock: type: "tool_use"; id; input; ... # 3 more
class BetaBrowserScrollToolUseBlock: type: "tool_use"; id; input; ... # 3 more
class BetaBrowserStateBlockParam: type: "browser_state"; tabs; cache_control; state_changesThe 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.
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 = ...
class BetaBrowserStateChangeDownloadCompleted: type: "download_completed"; download_id; url; ... # 2 moreA file download that finished during this call, reported with the
same download_id as its download_started — or without a prior
download_started, when the download finished during the call that
started it (at most one state change per download_id per result).
A file download that finished during this call, reported with the
same download_id as its download_started — or without a prior
download_started, when the download finished during the call that
started it (at most one state change per download_id per result).
download_id: strThe caller-assigned identifier for this download, stable across the state changes reporting it.
The caller-assigned identifier for this download, stable across the state changes reporting it.
url: strThe final post-redirect URL the download was served from.
The final post-redirect URL the download was served from.
path: Optional[str]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.
Where the executor saved the file, on the executor's filesystem. Only included when another tool in the same environment can read the file at that path.
size_bytes: Optional[int]The completed download's size.
The completed download's size.
class BetaBrowserStateChangeDownloadFailed: type: "download_failed"; download_id; url; errorA file download that failed — or was cancelled — during this call.
A file download that failed — or was cancelled — during this call.
download_id: strThe caller-assigned identifier for this download, stable across the state changes reporting it.
The caller-assigned identifier for this download, stable across the state changes reporting it.
url: strThe final post-redirect URL the download was served from.
The final post-redirect URL the download was served from.
error: Optional[str]The failure or cancellation detail, when known.
The failure or cancellation detail, when known.
class BetaBrowserStateChangeDownloadStarted: type: "download_started"; download_id; urlA file download that started during this call.
A file download that started during this call.
download_id: strThe caller-assigned identifier for this download, stable across the state changes reporting it.
The caller-assigned identifier for this download, stable across the state changes reporting it.
url: strThe final post-redirect URL the download was served from.
The final post-redirect URL the download was served from.
class BetaBrowserStateChangeTabOpened: type: "tab_opened"; tab_idA tab this call's execution opened that remains open at its end —
the creation delta of the tabs inventory, not an event log.
A tab this call's execution opened that remains open at its end —
the creation delta of the tabs inventory, not an event log.
Carries only the tab_id; the tab's title and url live on its
tabs entry, which must include the same tab_id. A tab opened
during a failed call gets no deferred tab_opened; it simply appears
in the next result's tabs inventory.
tab_id: strThe tab_id of the opened tab, present in tabs.
The tab_id of the opened tab, present in tabs.
class BetaBrowserStateTabEntry: tab_id; title; url; activeOne open browser tab reported in a browser_state block's tabs
inventory.
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: strThe caller-assigned identifier for this tab, unique within the inventory.
The caller-assigned identifier for this tab, unique within the inventory.
title: strThe title of the page the tab is showing. May be empty.
The title of the page the tab is showing. May be empty.
url: strThe URL of the page the tab is showing. May be empty.
The URL of the page the tab is showing. May be empty.
Whether this tab is the active tab after this call. Whenever tabs is non-empty, exactly one entry is marked active: true.
class BetaBrowserSwitchTabConfig: defer_loading; enabledswitch_tab's config overrides.
switch_tab's config overrides.
Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.
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.
class BetaBrowserSwitchTabInput: tab_idMake the tab with the given tab_id the active tab — the tab that actions without
a tab_id apply to.
Make the tab with the given tab_id the active tab — the tab that actions without a tab_id apply to.
The tab to switch to.
class BetaBrowserSwitchTabToolUseBlock: type: "tool_use"; id; input; ... # 3 more
type BetaBrowserToolUseBlock = ...
class BetaBrowserToolset20260801: type: "browser_toolset_20260801"; cache_control; configsThe 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.
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.
cache_control: Optional[BetaCacheControlEphemeral]Create a cache control breakpoint at this content block.
Create a cache control breakpoint at this content block.
ttl: Optional[Literal["5m", "1h"]]The time-to-live for the cache control breakpoint.
The time-to-live for the cache control breakpoint.
This may be one the following values:
5m: 5 minutes1h: 1 hour
Defaults to 5m. See prompt caching pricing for details.
configs: Optional[BetaBrowserToolsetConfigs]Sparse per-member overrides, keyed by member name. Absent, null, and {} are equivalent; a member's defaults apply wherever its key is absent.
Sparse per-member overrides, keyed by member name. Absent, null, and {} are equivalent; a member's defaults apply wherever its key is absent.
class BetaBrowserToolsetConfigs: type; close_tab; double_click; ... # 28 morePer-member configuration for browser_toolset_20260801: one
optional field per member tool, keyed by the member name — the same
name the member's tool_use blocks carry. Every member is an
accepted key, and a member's defaults apply wherever its key is
absent. Unknown keys are rejected: the field set is this toolset
version's complete member set.
Per-member configuration for browser_toolset_20260801: one
optional field per member tool, keyed by the member name — the same
name the member's tool_use blocks carry. Every member is an
accepted key, and a member's defaults apply wherever its key is
absent. Unknown keys are rejected: the field set is this toolset
version's complete member set.
class BetaBrowserTripleClickConfig: defer_loading; enabledtriple_click's config overrides.
triple_click's config overrides.
Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.
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.
class BetaBrowserTripleClickInput: target; modifiers; tab_idTriple left-click at a viewport coordinate or on an element by reference
(typically selects a line or paragraph).
Triple left-click at a viewport coordinate or on an element by reference (typically selects a line or paragraph).
class BetaBrowserTripleClickToolUseBlock: type: "tool_use"; id; input; ... # 3 more
class BetaBrowserTypeConfig: defer_loading; enabledtype's config overrides.
type's config overrides.
Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.
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.
class BetaBrowserTypeInput: text; tab_idType a literal string at the current focus.
Type a literal string at the current focus.
The text to type.
Tab to act on. Defaults to the active tab when omitted.
class BetaBrowserTypeToolUseBlock: type: "tool_use"; id; input; ... # 3 more
class BetaBrowserWaitConfig: defer_loading; enabledwait's config overrides.
wait's config overrides.
Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.
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.
class BetaBrowserWaitInput: duration; tab_idPause for the given duration.
Pause for the given duration.
duration: floatSeconds to wait (maximum 30).
Seconds to wait (maximum 30).
Tab to act on. Defaults to the active tab when omitted.
class BetaBrowserWaitToolUseBlock: type: "tool_use"; id; input; ... # 3 more
class BetaBrowserZoomConfig: defer_loading; enabledzoom's config overrides.
zoom's config overrides.
Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.
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.
class BetaBrowserZoomInput: region; tab_idReturn 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.
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: List[int][x0, y0, x1, y1] in viewport pixels.
[x0, y0, x1, y1] in viewport pixels.
Tab to act on. Defaults to the active tab when omitted.
class BetaBrowserZoomToolUseBlock: type: "tool_use"; id; input; ... # 3 more
class BetaCacheControlEphemeral: type: "ephemeral"; ttl
ttl: Optional[Literal["5m", "1h"]]The time-to-live for the cache control breakpoint.
The time-to-live for the cache control breakpoint.
This may be one the following values:
5m: 5 minutes1h: 1 hour
Defaults to 5m. See prompt caching pricing for details.
class BetaCacheCreation: ephemeral_1h_input_tokens; ephemeral_5m_input_tokens
ephemeral_1h_input_tokens: intThe number of input tokens used to create the 1 hour cache entry.
The number of input tokens used to create the 1 hour cache entry.
ephemeral_5m_input_tokens: intThe number of input tokens used to create the 5 minute cache entry.
The number of input tokens used to create the 5 minute cache entry.
class BetaCacheMissMessagesChanged: type: "messages_changed"; cache_missed_input_tokens
type: Literal["messages_changed"]
Approximate number of input tokens that would have been read from cache had the prefix matched the previous request.
class BetaCacheMissModelChanged: type: "model_changed"; cache_missed_input_tokens
type: Literal["model_changed"]
Approximate number of input tokens that would have been read from cache had the prefix matched the previous request.
class BetaCacheMissPreviousMessageNotFound: type: "previous_message_not_found"
type: Literal["previous_message_not_found"]
type BetaCacheMissReason = ...
class BetaCacheMissSystemChanged: type: "system_changed"; cache_missed_input_tokens
type: Literal["system_changed"]
Approximate number of input tokens that would have been read from cache had the prefix matched the previous request.
class BetaCacheMissToolsChanged: type: "tools_changed"; cache_missed_input_tokens
type: Literal["tools_changed"]
Approximate number of input tokens that would have been read from cache had the prefix matched the previous request.
class BetaCacheMissUnavailable: type: "unavailable"
type: Literal["unavailable"]
class BetaCitationCharLocation: type: "char_location"; cited_text; document_index; ... # 4 more
type: Literal["char_location"]
document_index: int
start_char_index: int
class BetaCitationCharLocationParam: type: "char_location"; cited_text; document_index; ... # 3 more
document_index: int
document_title: Optional[str]
start_char_index: int
class BetaCitationConfig: enabled
enabled: bool
class BetaCitationContentBlockLocation: type: "content_block_location"; cited_text; document_index; ... # 4 more
type: Literal["content_block_location"]
cited_text: strThe full text of the cited block range, concatenated.
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: int
end_block_index: intExclusive 0-based end index of the cited block range in the source's content array.
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: int0-based index of the first cited block in the source's content array.
0-based index of the first cited block in the source's content array.
class BetaCitationContentBlockLocationParam: type: "content_block_location"; cited_text; document_index; ... # 3 more
cited_text: strThe full text of the cited block range, concatenated.
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: int
document_title: Optional[str]
end_block_index: intExclusive 0-based end index of the cited block range in the source's content array.
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: int0-based index of the first cited block in the source's content array.
0-based index of the first cited block in the source's content array.
class BetaCitationPageLocation: type: "page_location"; cited_text; document_index; ... # 4 more
type: Literal["page_location"]
document_index: int
start_page_number: int
class BetaCitationPageLocationParam: type: "page_location"; cited_text; document_index; ... # 3 more
document_index: int
document_title: Optional[str]
start_page_number: int
class BetaCitationSearchResultLocation: type: "search_result_location"; cited_text; end_block_index; ... # 4 more
type: Literal["search_result_location"]
cited_text: strThe full text of the cited block range, concatenated.
The full text of the cited block range, concatenated.
Always equals the contents of content[start_block_index:end_block_index] joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns.
end_block_index: intExclusive 0-based end index of the cited block range in the source's content array.
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: int0-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.
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.
start_block_index: int0-based index of the first cited block in the source's content array.
0-based index of the first cited block in the source's content array.
class BetaCitationSearchResultLocationParam: type: "search_result_location"; cited_text; end_block_index; ... # 4 more
cited_text: strThe full text of the cited block range, concatenated.
The full text of the cited block range, concatenated.
Always equals the contents of content[start_block_index:end_block_index] joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns.
end_block_index: intExclusive 0-based end index of the cited block range in the source's content array.
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: int0-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.
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.
start_block_index: int0-based index of the first cited block in the source's content array.
0-based index of the first cited block in the source's content array.
class BetaCitationWebSearchResultLocationParam: type: "web_search_result_location"; cited_text; encrypted_index; ... # 2 more
title: Optional[str]
url: str
class BetaCitationsConfigParam: enabled
class BetaCitationsDelta: type: "citations_delta"; citation
class BetaCitationsWebSearchResultLocation: type: "web_search_result_location"; cited_text; encrypted_index; ... # 2 more
type: Literal["web_search_result_location"]
title: Optional[str]
class BetaClearThinking20251015Edit: type: "clear_thinking_20251015"; keep
keep: Optional[Keep]Number of most recent assistant turns to keep thinking blocks for. Older turns will have their thinking blocks removed.
Number of most recent assistant turns to keep thinking blocks for. Older turns will have their thinking blocks removed.
class BetaThinkingTurns: type: "thinking_turns"; value
value: int
class BetaAllThinkingTurns: type: "all"
class BetaClearThinking20251015EditResponse: type: "clear_thinking_20251015"; cleared_input_tokens; cleared_thinking_turns
type: Literal["clear_thinking_20251015"]The type of context management edit applied.
The type of context management edit applied.
cleared_input_tokens: intNumber of input tokens cleared by this edit.
Number of input tokens cleared by this edit.
cleared_thinking_turns: intNumber of thinking turns that were cleared.
Number of thinking turns that were cleared.
class BetaClearToolUses20250919Edit: type: "clear_tool_uses_20250919"; clear_at_least; clear_tool_inputs; ... # 3 more
class BetaClearToolUses20250919EditResponse: type: "clear_tool_uses_20250919"; cleared_input_tokens; cleared_tool_uses
type: Literal["clear_tool_uses_20250919"]The type of context management edit applied.
The type of context management edit applied.
cleared_input_tokens: intNumber of input tokens cleared by this edit.
Number of input tokens cleared by this edit.
cleared_tool_uses: intNumber of tool uses that were cleared.
Number of tool uses that were cleared.
class BetaCodeExecutionOutputBlock: type: "code_execution_output"; file_id
type: Literal["code_execution_output"]
class BetaCodeExecutionOutputBlockParam: type: "code_execution_output"; file_id
class BetaCodeExecutionResultBlock: type: "code_execution_result"; content; return_code; ... # 2 more
type: Literal["code_execution_result"]
content: List[BetaCodeExecutionOutputBlock]
type: Literal["code_execution_output"]
class BetaCodeExecutionResultBlockParam: type: "code_execution_result"; content; return_code; ... # 2 more
content: List[BetaCodeExecutionOutputBlockParam]
class BetaCodeExecutionTool20250522: type: "code_execution_20250522"; name; allowed_callers; ... # 3 more
class BetaCodeExecutionTool20250825: type: "code_execution_20250825"; name; allowed_callers; ... # 3 more
class BetaCodeExecutionTool20260120: type: "code_execution_20260120"; name; allowed_callers; ... # 3 moreCode execution tool with REPL state persistence (daemon mode + gVisor checkpoint).
Code execution tool with REPL state persistence (daemon mode + gVisor checkpoint).
class BetaCodeExecutionTool20260521: type: "code_execution_20260521"; name; allowed_callers; ... # 3 moreCode execution tool with REPL state persistence.
Code execution tool with REPL state persistence.
class BetaCodeExecutionToolResultBlock: type: "code_execution_tool_result"; content; tool_use_id
type: Literal["code_execution_tool_result"]
tool_use_id: str
type BetaCodeExecutionToolResultBlockContent = ...
class BetaCodeExecutionToolResultBlockParam: type: "code_execution_tool_result"; content; tool_use_id; cache_control
tool_use_id: str
cache_control: Optional[BetaCacheControlEphemeral]Create a cache control breakpoint at this content block.
Create a cache control breakpoint at this content block.
ttl: Optional[Literal["5m", "1h"]]The time-to-live for the cache control breakpoint.
The time-to-live for the cache control breakpoint.
This may be one the following values:
5m: 5 minutes1h: 1 hour
Defaults to 5m. See prompt caching pricing for details.
type BetaCodeExecutionToolResultBlockParamContent = ...
class BetaCodeExecutionToolResultError: type: "code_execution_tool_result_error"; error_code
type: Literal["code_execution_tool_result_error"]
error_code: BetaCodeExecutionToolResultErrorCode
type BetaCodeExecutionToolResultErrorCode = Literal["invalid_tool_input", "unavailable", "too_many_requests", "execution_time_exceeded"]
class BetaCodeExecutionToolResultErrorParam: type: "code_execution_tool_result_error"; error_code
error_code: BetaCodeExecutionToolResultErrorCode
class BetaCompact20260112Edit: type: "compact_20260112"; instructions; pause_after_compaction; triggerAutomatically compact older context when reaching the configured trigger threshold.
Automatically compact older context when reaching the configured trigger threshold.
Additional instructions for summarization.
Whether to pause after compaction and return the compaction block to the user.
trigger: Optional[BetaInputTokensTrigger]When to trigger compaction. Defaults to 150000 input tokens.
When to trigger compaction. Defaults to 150000 input tokens.
value: int
class BetaCompactionBlock: type: "compaction"; content; encrypted_content; ... # 2 moreA compaction block returned when autocompact is triggered.
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.
class BetaCompactionBlockParam: type: "compaction"; cache_control; content; ... # 3 moreA compaction block containing summary of previous context.
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.
class BetaCompactionConfig: type: "summarize"; instructionsCompact 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.
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.
instructions: Optional[str]Replaces the server's default summarization prompt for this request. An empty or whitespace-only value counts as absent.
Replaces the server's default summarization prompt for this request. An empty or whitespace-only value counts as absent.
class BetaCompactionContentBlockDelta: type: "compaction_delta"; content; encrypted_content
type: Literal["compaction_delta"]
Opaque metadata from prior compaction, to be round-tripped verbatim
class BetaCompactionIterationUsage: type: "compaction"; cache_creation; cache_creation_input_tokens; ... # 3 moreToken usage for a compaction iteration.
Token usage for a compaction iteration.
type: Literal["compaction"]Usage for a compaction iteration
Usage for a compaction iteration
cache_creation: Optional[BetaCacheCreation]Breakdown of cached tokens by TTL
Breakdown of cached tokens by TTL
ephemeral_1h_input_tokens: intThe number of input tokens used to create the 1 hour cache entry.
The number of input tokens used to create the 1 hour cache entry.
ephemeral_5m_input_tokens: intThe number of input tokens used to create the 5 minute cache entry.
The number of input tokens used to create the 5 minute cache entry.
cache_creation_input_tokens: intThe number of input tokens used to create the cache entry.
The number of input tokens used to create the cache entry.
cache_read_input_tokens: intThe number of input tokens read from the cache.
The number of input tokens read from the cache.
input_tokens: intThe number of input tokens which were used.
The number of input tokens which were used.
output_tokens: intThe number of output tokens which were used.
The number of output tokens which were used.
class BetaComputerCursorPositionConfig: defer_loading; enabledcursor_position's config overrides.
cursor_position's config overrides.
Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.
Whether this member is offered to the model. Default is per member, per the toolset's documentation. A member whose enabled resolves false is withheld from the served schema.
Get the current (x, y) pixel coordinate of the cursor.
class BetaComputerCursorPositionToolUseBlock: type: "tool_use"; id; input; ... # 3 more
class BetaComputerDoubleClickConfig: defer_loading; enableddouble_click's config overrides.
double_click's config overrides.
Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.
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.
class BetaComputerDoubleClickInput: coordinate; textDouble-click the left mouse button at the specified (x, y) pixel coordinate, or
the current cursor position if coordinate is omitted.
Double-click the left mouse button at the specified (x, y) pixel coordinate, or
the current cursor position if coordinate is omitted.
coordinate: Optional[List[int]](x, y): x pixels from the left edge, y pixels from the top edge.
(x, y): x pixels from the left edge, y pixels from the top edge.
Optional key combination to hold down during this action (e.g. "ctrl", "shift", "ctrl+shift").
class BetaComputerDoubleClickToolUseBlock: type: "tool_use"; id; input; ... # 3 more
class BetaComputerHoldKeyConfig: defer_loading; enabledhold_key's config overrides.
hold_key's config overrides.
Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.
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.
class BetaComputerHoldKeyInput: duration; textHold down a key or key-combination for a specified duration. Uses the same key
syntax as key.
Hold down a key or key-combination for a specified duration. Uses the same key
syntax as key.
duration: intDuration to hold the key, in seconds.
Duration to hold the key, in seconds.
The key or key-combination to hold.
class BetaComputerHoldKeyToolUseBlock: type: "tool_use"; id; input; ... # 3 more
class BetaComputerKeyConfig: defer_loading; enabledkey's config overrides.
key's config overrides.
Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.
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.
class BetaComputerKeyInput: text; repeatPress 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.
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.
The key or key-combination to press.
repeat: Optional[int]Number of times to repeat the key press. Default is 1.
Number of times to repeat the key press. Default is 1.
class BetaComputerKeyToolUseBlock: type: "tool_use"; id; input; ... # 3 more
class BetaComputerLeftClickConfig: defer_loading; enabledleft_click's config overrides.
left_click's config overrides.
Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.
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.
class BetaComputerLeftClickDragConfig: defer_loading; enabledleft_click_drag's config overrides.
left_click_drag's config overrides.
Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.
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.
class BetaComputerLeftClickDragInput: coordinate; start_coordinate; textClick and drag the cursor from start_coordinate to coordinate.
Click and drag the cursor from start_coordinate to coordinate.
coordinate: List[int](x, y): x pixels from the left edge, y pixels from the top edge.
(x, y): x pixels from the left edge, y pixels from the top edge.
start_coordinate: List[int](x, y): x pixels from the left edge, y pixels from the top edge.
(x, y): x pixels from the left edge, y pixels from the top edge.
Optional key combination to hold down during this action (e.g. "ctrl", "shift", "ctrl+shift").
class BetaComputerLeftClickDragToolUseBlock: type: "tool_use"; id; input; ... # 3 more
class BetaComputerLeftClickInput: coordinate; textClick the left mouse button at the specified (x, y) pixel coordinate, or the
current cursor position if coordinate is omitted.
Click the left mouse button at the specified (x, y) pixel coordinate, or the
current cursor position if coordinate is omitted.
coordinate: Optional[List[int]](x, y): x pixels from the left edge, y pixels from the top edge.
(x, y): x pixels from the left edge, y pixels from the top edge.
Optional key combination to hold down during this action (e.g. "ctrl", "shift", "ctrl+shift").
class BetaComputerLeftClickToolUseBlock: type: "tool_use"; id; input; ... # 3 more
class BetaComputerLeftMouseDownConfig: defer_loading; enabledleft_mouse_down's config overrides.
left_mouse_down's config overrides.
Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.
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.
Press and hold the left mouse button at the current cursor position.
class BetaComputerLeftMouseDownToolUseBlock: type: "tool_use"; id; input; ... # 3 more
class BetaComputerLeftMouseUpConfig: defer_loading; enabledleft_mouse_up's config overrides.
left_mouse_up's config overrides.
Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.
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.
Release the left mouse button.
class BetaComputerLeftMouseUpToolUseBlock: type: "tool_use"; id; input; ... # 3 more
class BetaComputerMiddleClickConfig: defer_loading; enabledmiddle_click's config overrides.
middle_click's config overrides.
Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.
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.
class BetaComputerMiddleClickInput: coordinate; textClick the middle mouse button at the specified (x, y) pixel coordinate, or the
current cursor position if coordinate is omitted.
Click the middle mouse button at the specified (x, y) pixel coordinate, or the
current cursor position if coordinate is omitted.
coordinate: Optional[List[int]](x, y): x pixels from the left edge, y pixels from the top edge.
(x, y): x pixels from the left edge, y pixels from the top edge.
Optional key combination to hold down during this action (e.g. "ctrl", "shift", "ctrl+shift").
class BetaComputerMiddleClickToolUseBlock: type: "tool_use"; id; input; ... # 3 more
class BetaComputerMouseMoveConfig: defer_loading; enabledmouse_move's config overrides.
mouse_move's config overrides.
Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.
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.
class BetaComputerMouseMoveInput: coordinateMove the cursor to a specified (x, y) pixel coordinate. Use this ONLY to hover
without clicking; otherwise use a click action directly.
Move the cursor to a specified (x, y) pixel coordinate. Use this ONLY to hover without clicking; otherwise use a click action directly.
coordinate: List[int](x, y): x pixels from the left edge, y pixels from the top edge.
(x, y): x pixels from the left edge, y pixels from the top edge.
class BetaComputerMouseMoveToolUseBlock: type: "tool_use"; id; input; ... # 3 more
class BetaComputerRightClickConfig: defer_loading; enabledright_click's config overrides.
right_click's config overrides.
Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.
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.
class BetaComputerRightClickInput: coordinate; textClick the right mouse button at the specified (x, y) pixel coordinate, or the
current cursor position if coordinate is omitted.
Click the right mouse button at the specified (x, y) pixel coordinate, or the
current cursor position if coordinate is omitted.
coordinate: Optional[List[int]](x, y): x pixels from the left edge, y pixels from the top edge.
(x, y): x pixels from the left edge, y pixels from the top edge.
Optional key combination to hold down during this action (e.g. "ctrl", "shift", "ctrl+shift").
class BetaComputerRightClickToolUseBlock: type: "tool_use"; id; input; ... # 3 more
class BetaComputerScreenshotConfig: defer_loading; enabledscreenshot's config overrides.
screenshot's config overrides.
Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.
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.
Take a screenshot of the screen.
class BetaComputerScreenshotToolUseBlock: type: "tool_use"; id; input; ... # 3 more
class BetaComputerScrollConfig: defer_loading; enabledscroll's config overrides.
scroll's config overrides.
Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.
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 = Literal["up", "down", "left", "right"]
class BetaComputerScrollInput: scroll_amount; scroll_direction; coordinate; textScroll 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 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.
Number of 'clicks' of the scroll wheel.
scroll_direction: BetaComputerScrollDirection
coordinate: Optional[List[int]](x, y): x pixels from the left edge, y pixels from the top edge.
(x, y): x pixels from the left edge, y pixels from the top edge.
Optional key combination to hold down during this action (e.g. "ctrl", "shift", "ctrl+shift").
class BetaComputerScrollToolUseBlock: type: "tool_use"; id; input; ... # 3 more
type BetaComputerToolUseBlock = ...
class BetaComputerToolset20260801: type: "computer_toolset_20260801"; cache_control; configsThe computer toolset: a single tools[] entry (carrying no
name) that declares the computer tool family. The model is
served the family's tool with any members disabled via configs
removed from its schema. Every member is enabled by default, zoom
included. The single-tool options display_number and
enable_zoom are not fields of a toolset entry — it carries only
type, configs, and cache_control; zoom is controlled
via configs.zoom.enabled.
The computer toolset: a single tools[] entry (carrying no
name) that declares the computer tool family. The model is
served the family's tool with any members disabled via configs
removed from its schema. Every member is enabled by default, zoom
included. The single-tool options display_number and
enable_zoom are not fields of a toolset entry — it carries only
type, configs, and cache_control; zoom is controlled
via configs.zoom.enabled.
cache_control: Optional[BetaCacheControlEphemeral]Create a cache control breakpoint at this content block.
Create a cache control breakpoint at this content block.
ttl: Optional[Literal["5m", "1h"]]The time-to-live for the cache control breakpoint.
The time-to-live for the cache control breakpoint.
This may be one the following values:
5m: 5 minutes1h: 1 hour
Defaults to 5m. See prompt caching pricing for details.
configs: Optional[BetaComputerToolsetConfigs]Sparse per-member overrides, keyed by member name. Absent, null, and {} are equivalent; a member's defaults apply wherever its key is absent.
Sparse per-member overrides, keyed by member name. Absent, null, and {} are equivalent; a member's defaults apply wherever its key is absent.
class BetaComputerToolsetConfigs: type; cursor_position; double_click; ... # 14 morePer-member configuration for computer_toolset_20260801: one
optional field per member tool, keyed by the member name — the same
name the member's tool_use blocks carry. Every member is an
accepted key, and a member's defaults apply wherever its key is
absent. Unknown keys are rejected: the field set is this toolset
version's complete member set.
Per-member configuration for computer_toolset_20260801: one
optional field per member tool, keyed by the member name — the same
name the member's tool_use blocks carry. Every member is an
accepted key, and a member's defaults apply wherever its key is
absent. Unknown keys are rejected: the field set is this toolset
version's complete member set.
class BetaComputerTripleClickConfig: defer_loading; enabledtriple_click's config overrides.
triple_click's config overrides.
Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.
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.
class BetaComputerTripleClickInput: coordinate; textTriple-click the left mouse button at the specified (x, y) pixel coordinate, or
the current cursor position if coordinate is omitted.
Triple-click the left mouse button at the specified (x, y) pixel coordinate, or
the current cursor position if coordinate is omitted.
coordinate: Optional[List[int]](x, y): x pixels from the left edge, y pixels from the top edge.
(x, y): x pixels from the left edge, y pixels from the top edge.
Optional key combination to hold down during this action (e.g. "ctrl", "shift", "ctrl+shift").
class BetaComputerTripleClickToolUseBlock: type: "tool_use"; id; input; ... # 3 more
class BetaComputerTypeConfig: defer_loading; enabledtype's config overrides.
type's config overrides.
Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.
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.
class BetaComputerTypeInput: textType a string of text on the keyboard.
Type a string of text on the keyboard.
The text to type.
class BetaComputerTypeToolUseBlock: type: "tool_use"; id; input; ... # 3 more
class BetaComputerWaitConfig: defer_loading; enabledwait's config overrides.
wait's config overrides.
Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.
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.
class BetaComputerWaitInput: durationWait for a specified duration.
Wait for a specified duration.
duration: intDuration to wait, in seconds.
Duration to wait, in seconds.
class BetaComputerWaitToolUseBlock: type: "tool_use"; id; input; ... # 3 more
class BetaComputerZoomConfig: defer_loading; enabledzoom's config overrides.
zoom's config overrides.
Defer loading for this member. Must resolve to the same value on every enabled member of the toolset.
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.
class BetaComputerZoomInput: regionTake 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.
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: List[int](x0, y0, x1, y1): The region to capture.
(x0, y0, x1, y1): The region to capture.
class BetaComputerZoomToolUseBlock: type: "tool_use"; id; input; ... # 3 more
class BetaContainer: id; expires_at; skillsInformation about the container used in the request (for the code execution tool)
Information about the container used in the request (for the code execution tool)
Identifier for the container used in this request
expires_at: datetimeThe time at which the container will expire.
The time at which the container will expire.
skills: Optional[List[BetaContainerSkill]]Skills loaded in the container
Skills loaded in the container
type: Literal["anthropic", "custom"]Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined)
Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined)
skill_id: strSkill ID
Skill ID
version: strThe resolved version: a skill version ID for custom skills.
The resolved version: a skill version ID for custom skills.
class BetaContainerParams: id; skillsContainer parameters with skills to be loaded.
Container parameters with skills to be loaded.
Container id
skills: Optional[List[BetaSkillParams]]List of skills to load in the container
List of skills to load in the container
type: Literal["anthropic", "custom"]Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined)
Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined)
skill_id: strSkill ID
Skill ID
version: Optional[str]Skill version or 'latest' for most recent version
Skill version or 'latest' for most recent version
class BetaContainerSkill: type; skill_id; versionA skill that was loaded in a container (response model).
A skill that was loaded in a container (response model).
type: Literal["anthropic", "custom"]Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined)
Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined)
skill_id: strSkill ID
Skill ID
version: strThe resolved version: a skill version ID for custom skills.
The resolved version: a skill version ID for custom skills.
class BetaContainerUploadBlock: type: "container_upload"; file_idResponse model for a file uploaded to the container.
Response model for a file uploaded to the container.
type: Literal["container_upload"]
class BetaContainerUploadBlockParam: type: "container_upload"; file_id; cache_controlA 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.
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.
cache_control: Optional[BetaCacheControlEphemeral]Create a cache control breakpoint at this content block.
Create a cache control breakpoint at this content block.
ttl: Optional[Literal["5m", "1h"]]The time-to-live for the cache control breakpoint.
The time-to-live for the cache control breakpoint.
This may be one the following values:
5m: 5 minutes1h: 1 hour
Defaults to 5m. See prompt caching pricing for details.
type BetaContentBlock = ...
type BetaContentBlockParam = ...
class BetaContentBlockSource: type: "content"; content
content: Union[str, List[BetaContentBlockSourceContent]]
class BetaTextBlockParam: type: "text"; text; cache_control; citations
class BetaImageBlockParam: type: "image"; source; cache_control; transformations
type BetaContentBlockSourceContent = ...
class BetaTextBlockParam: type: "text"; text; cache_control; citations
class BetaImageBlockParam: type: "image"; source; cache_control; transformations
class BetaContextManagementConfig: edits
class BetaContextManagementResponse: applied_edits
class BetaCountTokensContextManagementResponse: original_input_tokens
The original token count before context management was applied
class BetaDiagnostics: cache_miss_reasonRequest-level diagnostics: why the prompt cache could not fully reuse
the prefix of the request named by diagnostics.previous_message_id.
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: Optional[BetaCacheMissReason]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.
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.
class BetaDiagnosticsParam: previous_message_idRequest-level diagnostics. Currently carries the previous response
id for prompt-cache divergence reporting.
Request-level diagnostics. Currently carries the previous response id for prompt-cache divergence reporting.
previous_message_id: Optional[str]The id (msg_...) from this client's previous /v1/messages response. The server compares that request's prompt fingerprint against this one and returns diagnostics.cache_miss_reason when the prompt-cache prefix could not be reused. Pass null on the first turn to opt in without a prior message to compare.
The id (msg_...) from this client's previous /v1/messages response. The server compares that request's prompt fingerprint against this one and returns diagnostics.cache_miss_reason when the prompt-cache prefix could not be reused. Pass null on the first turn to opt in without a prior message to compare.
class BetaDirectCaller: type: "direct"Tool invocation directly from the model.
Tool invocation directly from the model.
class BetaDocumentBlock: type: "document"; citations; source; title
class BetaEncryptedCodeExecutionResultBlock: type: "encrypted_code_execution_result"; content; encrypted_stdout; ... # 2 moreCode execution result with encrypted stdout for PFC + web_search results.
Code execution result with encrypted stdout for PFC + web_search results.
type: Literal["encrypted_code_execution_result"]
content: List[BetaCodeExecutionOutputBlock]
type: Literal["code_execution_output"]
class BetaEncryptedCodeExecutionResultBlockParam: type: "encrypted_code_execution_result"; content; encrypted_stdout; ... # 2 moreCode execution result with encrypted stdout for PFC + web_search results.
Code execution result with encrypted stdout for PFC + web_search results.
content: List[BetaCodeExecutionOutputBlockParam]
class BetaFallbackBlock: type: "fallback"; from_; to; triggerMarks the point in content where one model's output gives way to the next.
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.
class BetaFallbackBlockParam: type: "fallback"; from_; to; triggerA fallback block echoed back from a prior response.
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.
from_: BetaFallbackInfoParamIdentifies one hop of a fallback transition.
Identifies one hop of a fallback transition.
Identifies one hop of a fallback transition.
Identifies one hop of a fallback transition.
The response block's trigger, echoed verbatim. Accepted and ignored by the server; any object or null is allowed.
class BetaFallbackCreditNotApplied: type: "not_applied"; reason; remove_to_redeemNo reprice was applied; reason says why.
No reprice was applied; reason says why.
class BetaFallbackCreditRedeemed: type: "redeemed"The reprice was applied: the retry is billed as if the conversation
had been on the retry model all along.
The reprice was applied: the retry is billed as if the conversation had been on the retry model all along.
type: Literal["redeemed"]
class BetaFallbackCreditTokenParam: token; modeObject form of fallback_credit_token: the token plus a redemption
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: strThe opaque fallback_credit_token from a prior refusal's stop_details — the same string the bare-string form carries.
The opaque fallback_credit_token from a prior refusal's stop_details — the same string the bare-string form carries.
mode: Optional[Literal["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.
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.
class BetaFallbackCreditUsage: statusOutcome of the fallback_credit_token presented on this request.
Outcome of the fallback_credit_token presented on this request.
status: StatusWhether the fallback-credit reprice was applied to this response's billing.
Whether the fallback-credit reprice was applied to this response's billing.
A union discriminated on type. redeemed: the retry is billed as if
the conversation had been on the retry model all along — including when the
resulting shift is zero because there was nothing to move. not_applied:
no reprice was applied; the arm's reason says why.
class BetaFallbackCreditRedeemed: type: "redeemed"The reprice was applied: the retry is billed as if the conversation
had been on the retry model all along.
The reprice was applied: the retry is billed as if the conversation had been on the retry model all along.
type: Literal["redeemed"]
class BetaFallbackCreditNotApplied: type: "not_applied"; reason; remove_to_redeemNo reprice was applied; reason says why.
No reprice was applied; reason says why.
class BetaFallbackInfo: modelIdentifies one hop of a fallback transition.
Identifies one hop of a fallback transition.
class BetaFallbackInfoParam: modelIdentifies one hop of a fallback transition.
Identifies one hop of a fallback transition.
class BetaFallbackMessageIterationUsage: type: "fallback_message"; cache_creation; cache_creation_input_tokens; ... # 4 moreToken usage for the fallback-model attempt of a server-side fallback request.
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.
class BetaFallbackParam: model; max_tokens; output_config; ... # 2 moreOne entry in the fallbacks chain on a /v1/messages request.
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.
class BetaFallbackRefusalTrigger: type: "refusal"; categoryThe from model declined for policy reasons.
The from model declined for policy reasons.
type: Literal["refusal"]
category: Optional[Literal["cyber", "bio", "frontier_llm", 2 more]]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.
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.
The request could enable cyber harm, such as malware or exploit development. Benign cybersecurity work can also trigger this category.
The request could enable biological harm, such as dangerous lab methods. Beneficial life sciences work can also trigger this category.
The request could assist the development of competing AI models, which is restricted under Anthropic's commercial terms. Benign machine learning work can also trigger this category.
The request asks the model to reproduce its internal reasoning in the response text. To get reasoning in a structured form instead, use adaptive thinking.
The request could be related to an area that was determined as harmful. Benign work might sometimes trigger this category.
type BetaFallbacksParam = Union[List[BetaFallbackParam], Literal["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.
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.
class BetaFileDocumentSource: type: "file"; file_id
class BetaFileImageSource: type: "file"; file_id
class BetaImageBlockParam: type: "image"; source; cache_control; transformations
class BetaImageTransformationsParam: oversized_imageConfigures the transformations the server applies to this image before the model observes it. Each key names a condition the server transforms images for; its value selects the transformation applied. Omitted keys keep their default behavior, and an empty object is equivalent to omitting the field.
Configures the transformations the server applies to this image before the model observes it. Each key names a condition the server transforms images for; its value selects the transformation applied. Omitted keys keep their default behavior, and an empty object is equivalent to omitting the field.
oversized_image: Optional[Literal["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.
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.
class BetaInputJSONDelta: type: "input_json_delta"; partial_json
type: Literal["input_json_delta"]
class BetaInputTokensClearAtLeast: type: "input_tokens"; value
value: int
class BetaInputTokensTrigger: type: "input_tokens"; value
value: int
type BetaInputTransformation = ...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 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.
type BetaIterationsUsage = Optional[List[BetaIterationsUsageItem]]Per-iteration token usage breakdown.
Per-iteration token usage breakdown.
Each entry represents one sampling iteration, with its own input/output token counts and cache statistics, discriminated by type. For message entries (model sampling iterations, such as the turns of a server-side tool use loop), this allows you to:
- Calculate the context window size from the last
messageentry - Understand token accumulation across server-side tool use loops
A compaction entry reports the token usage of the compaction operation itself — the server-side request that summarizes the context being closed — NOT the size of the context that was compacted away, and its token counts can be much smaller than that closed context (for example, a compaction that closes a ~200k-token context can report only a few thousand tokens). Do not derive the context window size from a compaction entry, even when it is the last entry. A compaction entry's tokens are not included in the top-level usage fields. When an input-token trigger is in effect (the default — 150,000 tokens unless configured otherwise), each compaction entry closes a context that had reached at least that threshold, though the context can exceed it by the final iteration's output and tool results.
class BetaJSONOutputFormat: type: "json_schema"; schema
The JSON schema of the format
class BetaMCPTool: input_schema; name; descriptionA tool as an MCP server lists it: its name on that server, its
description, and its input schema.
A tool as an MCP server lists it: its name on that server, its description, and its input schema.
class BetaMCPToolConfig: defer_loading; enabledConfiguration for a specific tool in an MCP toolset.
Configuration for a specific tool in an MCP toolset.
class BetaMCPToolDefaultConfig: defer_loading; enabledDefault configuration for tools in an MCP toolset.
Default configuration for tools in an MCP toolset.
class BetaMCPToolListingBlock: type: "mcp_tool_listing"; mcp_server_name; toolsThe 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.
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: Literal["mcp_tool_listing"]
tools: List[BetaMCPTool]
class BetaMCPToolListingBlockParam: type: "mcp_tool_listing"; mcp_server_name; toolsThe 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.
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.
mcp_server_name: strThe name of the MCP server this listing came from, as mcp_servers declares it.
The name of the MCP server this listing came from, as mcp_servers declares it.
tools: List[BetaMCPToolParam]The server's tools, exactly as the response listed them.
The server's tools, exactly as the response listed them.
The tool's input schema as the MCP server lists it, verbatim.
name: strThe tool's name as the MCP server lists it (not prefixed with the server name).
The tool's name as the MCP server lists it (not prefixed with the server name).
The tool's description as the MCP server lists it.
class BetaMCPToolParam: input_schema; name; descriptionA tool as an MCP server lists it: its name on that server, its
description, and its input schema.
A tool as an MCP server lists it: its name on that server, its description, and its input schema.
The tool's input schema as the MCP server lists it, verbatim.
name: strThe tool's name as the MCP server lists it (not prefixed with the server name).
The tool's name as the MCP server lists it (not prefixed with the server name).
The tool's description as the MCP server lists it.
class BetaMCPToolResultBlock: type: "mcp_tool_result"; content; is_error; tool_use_id
class BetaMCPToolUseBlock: type: "mcp_tool_use"; id; input; ... # 2 more
type: Literal["mcp_tool_use"]
id: str
The name of the MCP tool
The name of the MCP server
class BetaMCPToolUseBlockParam: type: "mcp_tool_use"; id; input; ... # 3 more
class BetaMCPToolset: type: "mcp_toolset"; mcp_server_name; cache_control; ... # 3 moreConfiguration for a group of tools from an MCP server.
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.
class BetaMemoryTool20250818: type: "memory_20250818"; name; allowed_callers; ... # 4 more
type BetaMemoryTool20250818Command = ...
class BetaMemoryTool20250818CreateCommand: command; file_text; path
command: Literal["create"]Command type identifier
Command type identifier
Content to write to the file
Path where the file should be created
class BetaMemoryTool20250818DeleteCommand: command; path
command: Literal["delete"]Command type identifier
Command type identifier
Path to the file or directory to delete
class BetaMemoryTool20250818InsertCommand: command; insert_line; insert_text; path
command: Literal["insert"]Command type identifier
Command type identifier
insert_line: intLine number where text should be inserted
Line number where text should be inserted
Text to insert at the specified line
Path to the file where text should be inserted
class BetaMemoryTool20250818RenameCommand: command; new_path; old_path
command: Literal["rename"]Command type identifier
Command type identifier
New path for the file or directory
Current path of the file or directory
class BetaMemoryTool20250818StrReplaceCommand: command; new_str; old_str; path
command: Literal["str_replace"]Command type identifier
Command type identifier
Text to replace with
Text to search for and replace
Path to the file where text should be replaced
class BetaMemoryTool20250818ViewCommand: command; path; view_range
command: Literal["view"]Command type identifier
Command type identifier
Path to directory or file to view
view_range: Optional[List[int]]Optional line range for viewing specific lines
Optional line range for viewing specific lines
class BetaMessage: type: "message"; id; container; ... # 10 more
class BetaMessageDeltaUsage: cache_creation_input_tokens; cache_read_input_tokens; fallback_credit; ... # 5 more
class BetaMessageIterationUsage: type: "message"; cache_creation; cache_creation_input_tokens; ... # 4 moreToken usage for a sampling iteration.
Token usage for a sampling iteration.
type: Literal["message"]Usage for a sampling iteration
Usage for a sampling iteration
cache_creation: Optional[BetaCacheCreation]Breakdown of cached tokens by TTL
Breakdown of cached tokens by TTL
ephemeral_1h_input_tokens: intThe number of input tokens used to create the 1 hour cache entry.
The number of input tokens used to create the 1 hour cache entry.
ephemeral_5m_input_tokens: intThe number of input tokens used to create the 5 minute cache entry.
The number of input tokens used to create the 5 minute cache entry.
cache_creation_input_tokens: intThe number of input tokens used to create the cache entry.
The number of input tokens used to create the cache entry.
cache_read_input_tokens: intThe number of input tokens read from the cache.
The number of input tokens read from the cache.
input_tokens: intThe number of input tokens which were used.
The number of input tokens which were used.
output_tokens: intThe number of output tokens which were used.
The number of output tokens which were used.
class BetaMessageParam: content; role; clear_at; output_config
class BetaMessageTokensCount: context_management; input_tokens
context_management: Optional[BetaCountTokensContextManagementResponse]Information about context management applied to the message.
Information about context management applied to the message.
The original token count before context management was applied
The total number of tokens across the provided list of messages, system prompt, and tools.
class BetaMetadata: user_id
user_id: Optional[str]An external identifier for the user who is associated with the request.
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.
class BetaOutputConfig: effort; format; task_budget
class BetaOutputTokensDetails: thinking_tokens
thinking_tokens: intNumber of output tokens the model generated as internal reasoning, including
the thinking-block delimiter tokens.
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.
class BetaPlainTextSource: type: "text"; data; media_type
type BetaRawContentBlockDelta = ...
class BetaRawContentBlockDeltaEvent: type: "content_block_delta"; delta; index
type: Literal["content_block_delta"]
delta: BetaRawContentBlockDelta
class BetaRawContentBlockStartEvent: type: "content_block_start"; content_block; index
class BetaRawContentBlockStopEvent: type: "content_block_stop"; index
type: Literal["content_block_stop"]
class BetaRawMessageDeltaEvent: type: "message_delta"; context_management; delta; ... # 2 more
class BetaRawMessageStartEvent: type: "message_start"; message
type: Literal["message_start"]
message: BetaMessage
class BetaRawMessageStopEvent: type: "message_stop"
type: Literal["message_stop"]
type BetaRawMessageStreamEvent = ...
class BetaRedactedThinkingBlock: type: "redacted_thinking"; data
type: Literal["redacted_thinking"]
data: strThe 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.
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.
class BetaRedactedThinkingBlockParam: type: "redacted_thinking"; data
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.
class BetaRefusalStopDetails: type: "refusal"; category; explanation; ... # 3 moreStructured information about a refusal.
Structured information about a refusal.
class BetaRequestDocumentBlock: type: "document"; source; cache_control; ... # 3 more
class BetaRequestMCPServerToolConfiguration: allowed_tools; enabled
class BetaRequestMCPServerURLDefinition: type: "url"; name; url; ... # 2 more
tool_configuration: Optional[BetaRequestMCPServerToolConfiguration]
class BetaRequestMCPToolResultBlockParam: type: "mcp_tool_result"; tool_use_id; cache_control; ... # 2 more
class BetaRequestToolAdditionBlock: type: "tool_addition"; tool; cache_controlMid-conversation directive to make a tool available.
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.
class BetaRequestToolRemovalBlock: type: "tool_removal"; tool; cache_controlMid-conversation directive to withdraw a tool.
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.
class BetaResponseTool: type; input_schema; name; ... # 6 moreA custom tool definition, as sent.
A custom tool definition, as sent.
class BetaResponseToolAdditionBlock: type: "tool_addition"; toolAn 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.
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.
class BetaResponseToolChangeMCPToolReference: type: "mcp_tool_reference"; name; server_nameReference 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.
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: Literal["mcp_tool_reference"]
class BetaResponseToolChangeMCPToolsetReference: type: "mcp_toolset_reference"; server_nameReference 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.
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: Literal["mcp_toolset_reference"]
class BetaResponseToolChangeToolReference: type: "tool_reference"; nameReference 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.
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: Literal["tool_reference"]
class BetaResponseToolInputSchema: type: "object"; properties; requiredJSON schema for this tool's input.
JSON schema for this tool's input.
This defines the shape of the input that your tool accepts and that the model will produce.
class BetaResponseToolRemovalBlock: type: "tool_removal"; toolAn 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.
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 = ...
class BetaSearchResultBlockParam: type: "search_result"; content; source; ... # 3 more
class BetaServerToolCaller: type: "code_execution_20250825"; tool_idTool invocation generated by a server-side tool.
Tool invocation generated by a server-side tool.
tool_id: str
class BetaServerToolCaller20260120: type: "code_execution_20260120"; tool_id
tool_id: str
class BetaServerToolUsage: web_fetch_requests; web_search_requests
web_fetch_requests: intThe number of web fetch tool requests.
The number of web fetch tool requests.
web_search_requests: intThe number of web search tool requests.
The number of web search tool requests.
class BetaServerToolUseBlock: type: "server_tool_use"; id; input; ... # 2 more
class BetaServerToolUseBlockParam: type: "server_tool_use"; id; input; ... # 3 more
class BetaSignatureDelta: type: "signature_delta"; signature
type: Literal["signature_delta"]
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.
class BetaSkillParams: type; skill_id; versionSpecification for a skill to be loaded in a container (request model).
Specification for a skill to be loaded in a container (request model).
type: Literal["anthropic", "custom"]Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined)
Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined)
skill_id: strSkill ID
Skill ID
version: Optional[str]Skill version or 'latest' for most recent version
Skill version or 'latest' for most recent version
type BetaStopReason = Literal["end_turn", "max_tokens", "stop_sequence", 5 more]
class BetaSummarizeCompaction: type: "summarize"; instructionsCompact 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.
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.
instructions: Optional[str]Replaces the server's default summarization prompt for this request. An empty or whitespace-only value counts as absent.
Replaces the server's default summarization prompt for this request. An empty or whitespace-only value counts as absent.
class BetaSystemMessageOutputConfig: effortPer-message output configuration on a role:"system" input message.
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: Optional[Literal["low", "medium", "high", 2 more]]How much effort the model should put into its response. Higher effort levels may result in more thorough analysis but take longer.
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.
class BetaTextBlock: type: "text"; citations; text
class BetaTextBlockParam: type: "text"; text; cache_control; citations
type BetaTextCitation = ...
type BetaTextCitationParam = ...
class BetaTextDelta: type: "text_delta"; text
type: Literal["text_delta"]
class BetaTextEditorCodeExecutionCreateResultBlock: type: "text_editor_code_execution_create_result"; is_file_update
type: Literal["text_editor_code_execution_create_result"]
class BetaTextEditorCodeExecutionCreateResultBlockParam: type: "text_editor_code_execution_create_result"; is_file_update
class BetaTextEditorCodeExecutionStrReplaceResultBlock: type: "text_editor_code_execution_str_replace_result"; lines; new_lines; ... # 3 more
type: Literal["text_editor_code_execution_str_replace_result"]
class BetaTextEditorCodeExecutionStrReplaceResultBlockParam: type: "text_editor_code_execution_str_replace_result"; lines; new_lines; ... # 3 more
class BetaTextEditorCodeExecutionToolResultBlock: type: "text_editor_code_execution_tool_result"; content; tool_use_id
class BetaTextEditorCodeExecutionToolResultBlockParam: type: "text_editor_code_execution_tool_result"; content; tool_use_id; cache_control
class BetaTextEditorCodeExecutionToolResultError: type: "text_editor_code_execution_tool_result_error"; error_code; error_message
type: Literal["text_editor_code_execution_tool_result_error"]
error_code: Literal["invalid_tool_input", "unavailable", "too_many_requests", 2 more]
class BetaTextEditorCodeExecutionToolResultErrorParam: type: "text_editor_code_execution_tool_result_error"; error_code; error_message
error_code: Literal["invalid_tool_input", "unavailable", "too_many_requests", 2 more]
class BetaTextEditorCodeExecutionViewResultBlock: type: "text_editor_code_execution_view_result"; content; file_type; ... # 3 more
type: Literal["text_editor_code_execution_view_result"]
file_type: Literal["text", "image", "pdf"]
class BetaTextEditorCodeExecutionViewResultBlockParam: type: "text_editor_code_execution_view_result"; content; file_type; ... # 3 more
file_type: Literal["text", "image", "pdf"]
class BetaThinkingBlock: type: "thinking"; signature; thinking
type: Literal["thinking"]
signature: strA value used to verify that this thinking block was generated by Claude when it is passed back to the API.
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.
The text of Claude's thinking process for this block.
class BetaThinkingBlockBinding: prefix_mismatch_behaviorControls 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.
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: Optional[BetaThinkingPrefixMismatchBehavior]"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.
"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.
class BetaThinkingBlockParam: type: "thinking"; signature; thinking
signature: strThe 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.
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.
The thinking text of this block as returned by the API.
class BetaThinkingConfigAdaptive: type: "adaptive"; block_binding; display
block_binding: Optional[BetaThinkingBlockBinding]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.
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: Optional[BetaThinkingPrefixMismatchBehavior]"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.
"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.
display: Optional[Literal["summarized", "omitted", "updates"]]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.
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.
class BetaThinkingConfigBetweenTools: type: "between_tools"
class BetaThinkingConfigDisabled: type: "disabled"
class BetaThinkingConfigEnabled: type: "enabled"; budget_tokens; block_binding; display
type BetaThinkingConfigParam = ...Configuration for Claude's thinking.
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.
class BetaThinkingDelta: type: "thinking_delta"; estimated_tokens; thinking
type: Literal["thinking_delta"]
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.
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.
class BetaThinkingDroppedInputTransformation: type: "thinking_dropped"; path; reason
type: Literal["thinking_dropped"]Always thinking_dropped for this entry type.
Always thinking_dropped for this entry type.
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: Literal["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.
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.
class BetaThinkingMismatchAllowedInputTransformation: type: "thinking_mismatch_allowed"; path; reason
type: Literal["thinking_mismatch_allowed"]Always thinking_mismatch_allowed for this entry type.
Always thinking_mismatch_allowed for this entry type.
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: Literal["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.
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.
type BetaThinkingPrefixMismatchBehavior = Literal["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.
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.
class BetaThinkingTurns: type: "thinking_turns"; value
value: int
class BetaTokenTaskBudget: type: "tokens"; total; remainingUser-configurable total token budget across contexts.
User-configurable total token budget across contexts.
The budget type. Currently only 'tokens' is supported.
total: intTotal token budget across all contexts in the session.
Total token budget across all contexts in the session.
remaining: Optional[int]Remaining tokens in the budget. Use this to track usage across contexts when implementing compaction client-side. Defaults to total if not provided.
Remaining tokens in the budget. Use this to track usage across contexts when implementing compaction client-side. Defaults to total if not provided.
class BetaTool: type; input_schema; name; ... # 7 more
class BetaToolBash20241022: type: "bash_20241022"; name; allowed_callers; ... # 4 more
class BetaToolBash20250124: type: "bash_20250124"; name; allowed_callers; ... # 4 more
class BetaToolChangeMCPToolReference: type: "mcp_tool_reference"; name; server_nameReference to a single MCP tool by its server and remote name; the
same server_name/name pair mcp_tool_use carries.
Reference to a single MCP tool by its server and remote name; the
same server_name/name pair mcp_tool_use carries.
class BetaToolChangeMCPToolsetReference: type: "mcp_toolset_reference"; server_nameReference to every tool in the named MCP server's toolset.
Reference to every tool in the named MCP server's toolset.
class BetaToolChangeToolDefinition: type: "tool_definition"; definitionA 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.
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: Literal["tool_definition"]
definition: BetaResponseToolUnion
class BetaToolChangeToolDefinitionParam: type: "tool_definition"; definitionA 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.
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.
definition: BetaToolUnion
class BetaToolChangeToolReference: type: "tool_reference"; nameReference 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.
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.
name: str
type BetaToolChoice = ...How the model should use the provided tools. The model can use a specific tool, any available tool, decide by itself, or not use tools at all.
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.
class BetaToolChoiceAny: type: "any"; disable_parallel_tool_useThe model will use any available tools.
The model will use any available tools.
disable_parallel_tool_use: Optional[bool]Whether to disable parallel tool use.
Whether to disable parallel tool use.
Defaults to false. If set to true, the model will output exactly one tool use.
class BetaToolChoiceAuto: type: "auto"; disable_parallel_tool_useThe model will automatically decide whether to use tools.
The model will automatically decide whether to use tools.
disable_parallel_tool_use: Optional[bool]Whether to disable parallel tool use.
Whether to disable parallel tool use.
Defaults to false. If set to true, the model will output at most one tool use.
class BetaToolChoiceNone: type: "none"The model will not be allowed to use tools.
The model will not be allowed to use tools.
class BetaToolChoiceTool: type: "tool"; name; disable_parallel_tool_useThe model will use the specified tool with tool_choice.name.
The model will use the specified tool with tool_choice.name.
The name of the tool to use.
disable_parallel_tool_use: Optional[bool]Whether to disable parallel tool use.
Whether to disable parallel tool use.
Defaults to false. If set to true, the model will output exactly one tool use.
class BetaToolComputerUse20241022: type: "computer_20241022"; display_height_px; display_width_px; ... # 7 more
class BetaToolComputerUse20250124: type: "computer_20250124"; display_height_px; display_width_px; ... # 7 more
class BetaToolComputerUse20251124: type: "computer_20251124"; display_height_px; display_width_px; ... # 8 more
class BetaToolReferenceBlock: type: "tool_reference"; tool_name
type: Literal["tool_reference"]
tool_name: str
class BetaToolReferenceBlockParam: type: "tool_reference"; tool_name; cache_controlTool reference block that can be included in tool_result content.
Tool reference block that can be included in tool_result content.
tool_name: str
cache_control: Optional[BetaCacheControlEphemeral]Create a cache control breakpoint at this content block.
Create a cache control breakpoint at this content block.
ttl: Optional[Literal["5m", "1h"]]The time-to-live for the cache control breakpoint.
The time-to-live for the cache control breakpoint.
This may be one the following values:
5m: 5 minutes1h: 1 hour
Defaults to 5m. See prompt caching pricing for details.
class BetaToolResultBlockParam: type: "tool_result"; tool_use_id; cache_control; ... # 3 more
class BetaToolSearchToolBm25_20251119: type; name; allowed_callers; ... # 3 more
class BetaToolSearchToolRegex20251119: type; name; allowed_callers; ... # 3 more
class BetaToolSearchToolResultBlock: type: "tool_search_tool_result"; content; tool_use_id
class BetaToolSearchToolResultBlockParam: type: "tool_search_tool_result"; content; tool_use_id; cache_control
class BetaToolSearchToolResultError: type: "tool_search_tool_result_error"; error_code; error_message
type: Literal["tool_search_tool_result_error"]
error_code: Literal["invalid_tool_input", "unavailable", "too_many_requests", "execution_time_exceeded"]
class BetaToolSearchToolResultErrorParam: type: "tool_search_tool_result_error"; error_code; error_message
error_code: Literal["invalid_tool_input", "unavailable", "too_many_requests", "execution_time_exceeded"]
class BetaToolSearchToolSearchResultBlock: type: "tool_search_tool_search_result"; tool_references
type: Literal["tool_search_tool_search_result"]
tool_references: List[BetaToolReferenceBlock]
type: Literal["tool_reference"]
tool_name: str
class BetaToolSearchToolSearchResultBlockParam: type: "tool_search_tool_search_result"; tool_references
class BetaToolTextEditor20241022: type: "text_editor_20241022"; name; allowed_callers; ... # 4 more
class BetaToolTextEditor20250124: type: "text_editor_20250124"; name; allowed_callers; ... # 4 more
class BetaToolTextEditor20250429: type: "text_editor_20250429"; name; allowed_callers; ... # 4 more
class BetaToolTextEditor20250728: type: "text_editor_20250728"; name; allowed_callers; ... # 5 more
type BetaToolUnion = ...
class BetaToolUseBlock: type: "tool_use"; id; input; ... # 3 more
class BetaToolUseBlockParam: type: "tool_use"; id; input; ... # 4 more
type BetaToolUseCaller = ...Which party invoked the tool call: the model directly, or a server tool on its behalf.
Which party invoked the tool call: the model directly, or a server tool on its behalf.
class BetaDirectCaller: type: "direct"Tool invocation directly from the model.
Tool invocation directly from the model.
class BetaServerToolCaller: type: "code_execution_20250825"; tool_idTool invocation generated by a server-side tool.
Tool invocation generated by a server-side tool.
tool_id: str
class BetaServerToolCaller20260120: type: "code_execution_20260120"; tool_id
tool_id: str
class BetaToolUsesKeep: type: "tool_uses"; value
value: int
class BetaToolUsesTrigger: type: "tool_uses"; value
value: int
type BetaToolsetToolUseBlock = ...
type BetaBrowserToolUseBlock = ...
type BetaComputerToolUseBlock = ...
class BetaToolUseBlock: type: "tool_use"; id; input; ... # 3 more
class BetaURLImageSource: type: "url"; url
class BetaURLPDFSource: type: "url"; url
class BetaUsage: cache_creation; cache_creation_input_tokens; cache_read_input_tokens; ... # 9 more
class BetaUserLocation: type: "approximate"; city; country; ... # 2 more
city: Optional[str]The city of the user.
The city of the user.
country: Optional[str]The two letter ISO country code of the user.
The two letter ISO country code of the user.
region: Optional[str]The region of the user.
The region of the user.
timezone: Optional[str]The IANA timezone of the user.
The IANA timezone of the user.
class BetaWebFetchBlock: type: "web_fetch_result"; content; retrieved_at; url
type: Literal["web_fetch_result"]
content: BetaDocumentBlock
ISO 8601 timestamp when the content was retrieved
Fetched content URL
class BetaWebFetchBlockParam: type: "web_fetch_result"; content; url; retrieved_at
content: BetaRequestDocumentBlock
Fetched content URL
ISO 8601 timestamp when the content was retrieved
class BetaWebFetchTool20250910: type: "web_fetch_20250910"; name; allowed_callers; ... # 9 more
class BetaWebFetchTool20260209: type: "web_fetch_20260209"; name; allowed_callers; ... # 9 more
class BetaWebFetchTool20260309: type: "web_fetch_20260309"; name; allowed_callers; ... # 10 moreWeb fetch tool with use_cache parameter for bypassing cached content.
Web fetch tool with use_cache parameter for bypassing cached content.
class BetaWebFetchTool20260318: type: "web_fetch_20260318"; name; allowed_callers; ... # 11 more
class BetaWebFetchToolResultBlock: type: "web_fetch_tool_result"; content; tool_use_id; caller
class BetaWebFetchToolResultBlockParam: type: "web_fetch_tool_result"; content; tool_use_id; ... # 2 more
class BetaWebFetchToolResultErrorBlock: type: "web_fetch_tool_result_error"; error_code
type: Literal["web_fetch_tool_result_error"]
error_code: BetaWebFetchToolResultErrorCode
class BetaWebFetchToolResultErrorBlockParam: type: "web_fetch_tool_result_error"; error_code
error_code: BetaWebFetchToolResultErrorCode
type BetaWebFetchToolResultErrorCode = Literal["invalid_tool_input", "url_too_long", "url_not_allowed", 7 more]
class 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.
The url_sources variant under which a source contributes in
full: every result of the tool filter's source, or all user input.
class BetaWebFetchURLSourceExcept: type: "except"; toolsThe tool filter variant under which every result but the named
tools' contributes.
The tool filter variant under which every result but the named tools' contributes.
tools: List[BetaWebFetchURLSourceToolReference]
class 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.
The url_sources variant under which a source contributes nothing:
no result of the tool filter's source, or no user input.
class BetaWebFetchURLSourceOnly: type: "only"; toolsThe tool filter variant under which only the named tools' results
contribute.
The tool filter variant under which only the named tools' results contribute.
tools: List[BetaWebFetchURLSourceToolReference]
class BetaWebFetchURLSourceToolReference: type: "tool_reference"; nameOne entry of a tool filter's tools: it must name a tool declared
in this request's tools[].
One entry of a tool filter's tools: it must name a tool declared
in this request's tools[].
class BetaWebFetchURLSources: client_tool_results; server_tool_results; user_inputWhich sources contribute to the set of URLs web fetch may fetch.
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[].
class BetaWebSearchResultBlock: type: "web_search_result"; encrypted_content; page_age; ... # 2 more
type: Literal["web_search_result"]
class BetaWebSearchResultBlockParam: type: "web_search_result"; encrypted_content; title; ... # 2 more
class BetaWebSearchTool20250305: type: "web_search_20250305"; name; allowed_callers; ... # 7 more
class BetaWebSearchTool20260209: type: "web_search_20260209"; name; allowed_callers; ... # 7 more
class BetaWebSearchTool20260318: type: "web_search_20260318"; name; allowed_callers; ... # 8 more
class BetaWebSearchToolRequestError: type: "web_search_tool_result_error"; error_code
error_code: BetaWebSearchToolResultErrorCode
class BetaWebSearchToolResultBlock: type: "web_search_tool_result"; content; tool_use_id; caller
type BetaWebSearchToolResultBlockContent = ...
class BetaWebSearchToolResultBlockParam: type: "web_search_tool_result"; content; tool_use_id; ... # 2 more
type BetaWebSearchToolResultBlockParamContent = ...
class BetaWebSearchToolResultError: type: "web_search_tool_result_error"; error_code
type: Literal["web_search_tool_result_error"]
error_code: BetaWebSearchToolResultErrorCode
type BetaWebSearchToolResultErrorCode = Literal["invalid_tool_input", "unavailable", "max_uses_exceeded", 3 more]
MessagesBatches
Create a Message Batch
beta.messages.batches.create(**kwargs) -> BetaMessageBatchSend a batch of Message creation requests.
Retrieve a Message Batch
beta.messages.batches.retrieve(message_batch_id, **kwargs) -> BetaMessageBatchThis endpoint is idempotent and can be used to poll for Message Batch completion. To access the results of a Message Batch, make a request to the results_url field in the response.
List Message Batches
beta.messages.batches.list(**kwargs) -> SyncPage[BetaMessageBatch]List all Message Batches within a Workspace. Most recently created batches are returned first.
Cancel a Message Batch
beta.messages.batches.cancel(message_batch_id, **kwargs) -> BetaMessageBatchBatches may be canceled any time before processing ends. Once cancellation is initiated, the batch enters a canceling state, at which time the system may complete any in-progress, non-interruptible requests before finalizing cancellation.
Delete a Message Batch
beta.messages.batches.delete(message_batch_id, **kwargs) -> BetaDeletedMessageBatchRetrieve Message Batch results
beta.messages.batches.results(message_batch_id, **kwargs) -> BetaMessageBatchIndividualResponseStreams the results of a Message Batch as a .jsonl file.