Messages

Create a Message

BetaMessage beta().messages().create(params, requestOptions = RequestOptions.none())

POST/v1/messages

Count tokens in a Message

BetaMessageTokensCount beta().messages().countTokens(params, requestOptions = RequestOptions.none())

POST/v1/messages/count_tokens

Models

class BetaAdvisorMessageIterationUsage:

Token usage for an advisor sub-inference iteration.

Optional<BetaCacheCreation> cacheCreation

Breakdown of cached tokens by TTL

long ephemeral1hInputTokens

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

minimum0

long ephemeral5mInputTokens

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

minimum0

long cacheCreationInputTokens

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

minimum0

long cacheReadInputTokens

The number of input tokens read from the cache.

minimum0

long inputTokens

The number of input tokens which were used.

minimum0

Model model

The model that will complete your prompt.

See models for additional details and options.

One of the following:

long outputTokens

The number of output tokens which were used.

minimum0

JsonValue type = "advisor_message"

Usage for an advisor sub-inference iteration

class BetaAdvisorRedactedResultBlock:

String encryptedContent

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

Optional<String> stopReason

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

JsonValue type = "advisor_redacted_result"

class BetaAdvisorRedactedResultBlockParam:

String encryptedContent

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

JsonValue type = "advisor_redacted_result"

Optional<String> stopReason

class BetaAdvisorResultBlock:

Optional<String> stopReason

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.

String text

JsonValue type = "advisor_result"

class BetaAdvisorResultBlockParam:

String text

JsonValue type = "advisor_result"

Optional<String> stopReason

class BetaAdvisorTool20260301:

class BetaAdvisorToolResultBlock:

class BetaAdvisorToolResultBlockParam:

class BetaAdvisorToolResultError:

ErrorCode errorCode

One of the following:

MAX_USES_EXCEEDED("max_uses_exceeded")

PROMPT_TOO_LONG("prompt_too_long")

TOO_MANY_REQUESTS("too_many_requests")

OVERLOADED("overloaded")

UNAVAILABLE("unavailable")

EXECUTION_TIME_EXCEEDED("execution_time_exceeded")

MODEL_NOT_FOUND("model_not_found")

JsonValue type = "advisor_tool_result_error"

class BetaAdvisorToolResultErrorParam:

ErrorCode errorCode

One of the following:

MAX_USES_EXCEEDED("max_uses_exceeded")

PROMPT_TOO_LONG("prompt_too_long")

TOO_MANY_REQUESTS("too_many_requests")

OVERLOADED("overloaded")

UNAVAILABLE("unavailable")

EXECUTION_TIME_EXCEEDED("execution_time_exceeded")

MODEL_NOT_FOUND("model_not_found")

JsonValue type = "advisor_tool_result_error"

class BetaAllThinkingTurns:

JsonValue type = "all"

class BetaBase64ImageSource:

String data

formatbyte

MediaType mediaType

One of the following:

IMAGE_JPEG("image/jpeg")

IMAGE_PNG("image/png")

IMAGE_GIF("image/gif")

IMAGE_WEBP("image/webp")

JsonValue type = "base64"

class BetaBase64PdfSource:

String data

formatbyte

JsonValue mediaType = "application/pdf"

JsonValue type = "base64"

class BetaBashCodeExecutionOutputBlock:

String fileId

JsonValue type = "bash_code_execution_output"

class BetaBashCodeExecutionOutputBlockParam:

String fileId

JsonValue type = "bash_code_execution_output"

class BetaBashCodeExecutionResultBlock:

List<BetaBashCodeExecutionOutputBlock> content

String fileId

JsonValue type = "bash_code_execution_output"

long returnCode

String stderr

String stdout

JsonValue type = "bash_code_execution_result"

class BetaBashCodeExecutionResultBlockParam:

List<BetaBashCodeExecutionOutputBlockParam> content

String fileId

JsonValue type = "bash_code_execution_output"

long returnCode

String stderr

String stdout

JsonValue type = "bash_code_execution_result"

class BetaBashCodeExecutionToolResultBlock:

class BetaBashCodeExecutionToolResultBlockParam:

class BetaBashCodeExecutionToolResultError:

ErrorCode errorCode

One of the following:

INVALID_TOOL_INPUT("invalid_tool_input")

UNAVAILABLE("unavailable")

TOO_MANY_REQUESTS("too_many_requests")

EXECUTION_TIME_EXCEEDED("execution_time_exceeded")

OUTPUT_FILE_TOO_LARGE("output_file_too_large")

JsonValue type = "bash_code_execution_tool_result_error"

class BetaBashCodeExecutionToolResultErrorParam:

ErrorCode errorCode

One of the following:

INVALID_TOOL_INPUT("invalid_tool_input")

UNAVAILABLE("unavailable")

TOO_MANY_REQUESTS("too_many_requests")

EXECUTION_TIME_EXCEEDED("execution_time_exceeded")

OUTPUT_FILE_TOO_LARGE("output_file_too_large")

JsonValue type = "bash_code_execution_tool_result_error"

class BetaBrowserCloseTabConfig:

close_tab's config overrides.

Optional<Boolean> deferLoading

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

Optional<Boolean> enabled

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 BetaBrowserDoubleClickConfig:

double_click's config overrides.

Optional<Boolean> deferLoading

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

Optional<Boolean> enabled

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 BetaBrowserFileUploadConfig:

file_upload's config overrides.

Optional<Boolean> deferLoading

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

Optional<Boolean> enabled

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 BetaBrowserFindConfig:

find's config overrides.

Optional<Boolean> deferLoading

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

Optional<Boolean> enabled

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 BetaBrowserFormInputConfig:

form_input's config overrides.

Optional<Boolean> deferLoading

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

Optional<Boolean> enabled

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 BetaBrowserGetPageTextConfig:

get_page_text's config overrides.

Optional<Boolean> deferLoading

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

Optional<Boolean> enabled

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 BetaBrowserHoldKeyConfig:

hold_key's config overrides.

Optional<Boolean> deferLoading

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

Optional<Boolean> enabled

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 BetaBrowserHoverConfig:

hover's config overrides.

Optional<Boolean> deferLoading

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

Optional<Boolean> enabled

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 BetaBrowserJavascriptExecConfig:

javascript_exec's config overrides.

Optional<Boolean> deferLoading

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

Optional<Boolean> enabled

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 BetaBrowserKeyConfig:

key's config overrides.

Optional<Boolean> deferLoading

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

Optional<Boolean> enabled

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 BetaBrowserLeftClickConfig:

left_click's config overrides.

Optional<Boolean> deferLoading

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

Optional<Boolean> enabled

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:

left_click_drag's config overrides.

Optional<Boolean> deferLoading

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

Optional<Boolean> enabled

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 BetaBrowserLeftMouseDownConfig:

left_mouse_down's config overrides.

Optional<Boolean> deferLoading

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

Optional<Boolean> enabled

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 BetaBrowserLeftMouseUpConfig:

left_mouse_up's config overrides.

Optional<Boolean> deferLoading

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

Optional<Boolean> enabled

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 BetaBrowserListTabsConfig:

list_tabs's config overrides.

Optional<Boolean> deferLoading

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

Optional<Boolean> enabled

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 BetaBrowserMiddleClickConfig:

middle_click's config overrides.

Optional<Boolean> deferLoading

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

Optional<Boolean> enabled

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 BetaBrowserMouseMoveConfig:

mouse_move's config overrides.

Optional<Boolean> deferLoading

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

Optional<Boolean> enabled

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 BetaBrowserNavigateConfig:

navigate's config overrides.

Optional<Boolean> deferLoading

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

Optional<Boolean> enabled

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 BetaBrowserNewTabConfig:

new_tab's config overrides.

Optional<Boolean> deferLoading

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

Optional<Boolean> enabled

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 BetaBrowserReadConsoleConfig:

read_console's config overrides.

Optional<Boolean> deferLoading

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

Optional<Boolean> enabled

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 BetaBrowserReadNetworkConfig:

read_network's config overrides.

Optional<Boolean> deferLoading

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

Optional<Boolean> enabled

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 BetaBrowserReadPageConfig:

read_page's config overrides.

Optional<Boolean> deferLoading

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

Optional<Boolean> enabled

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 BetaBrowserRightClickConfig:

right_click's config overrides.

Optional<Boolean> deferLoading

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

Optional<Boolean> enabled

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 BetaBrowserScreenshotConfig:

screenshot's config overrides.

Optional<Boolean> deferLoading

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

Optional<Boolean> enabled

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 BetaBrowserScrollConfig:

scroll's config overrides.

Optional<Boolean> deferLoading

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

Optional<Boolean> enabled

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 BetaBrowserScrollToConfig:

scroll_to's config overrides.

Optional<Boolean> deferLoading

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

Optional<Boolean> enabled

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 BetaBrowserStateBlockParam:

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.

class BetaBrowserStateChange: union

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.

class BetaBrowserStateChangeDownloadCompleted:

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).

String downloadId

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

maxLength4096

minLength1

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

JsonValue type = "download_completed"

String url

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

maxLength4096

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

Optional<String> 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.

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

maxLength4096

Optional<Long> sizeBytes

The completed download's size.

minimum0

class BetaBrowserStateChangeDownloadFailed:

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

String downloadId

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

maxLength4096

minLength1

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

JsonValue type = "download_failed"

String url

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

maxLength4096

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

Optional<String> error

The failure or cancellation detail, when known.

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

maxLength4096

class BetaBrowserStateChangeDownloadStarted:

A file download that started during this call.

String downloadId

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

maxLength4096

minLength1

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

JsonValue type = "download_started"

String url

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

maxLength4096

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

class BetaBrowserStateChangeTabOpened:

A tab this call's execution opened that remains open at its end — the creation delta of the tabs inventory, not an event log.

String tabId

The tab_id of the opened tab, present in tabs.

maxLength4096

minLength1

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

JsonValue type = "tab_opened"

class BetaBrowserStateTabEntry:

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.

String tabId

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

maxLength4096

minLength1

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

String title

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

maxLength4096

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

String url

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

maxLength4096

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

Optional<Boolean> active

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

class BetaBrowserSwitchTabConfig:

switch_tab's config overrides.

Optional<Boolean> deferLoading

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

Optional<Boolean> enabled

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 BetaBrowserToolset20260801:

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.

JsonValue type = "browser_toolset_20260801"

Optional<BetaCacheControlEphemeral> cacheControl

Create a cache control breakpoint at this content block.

JsonValue type = "ephemeral"

Optional<Ttl> ttl

The time-to-live for the cache control breakpoint.

This may be one the following values:

5m: 5 minutes
1h: 1 hour

Defaults to 5m. See prompt caching pricing for details.

One of the following:

TTL_5M("5m")

TTL_1H("1h")

Optional<BetaBrowserToolsetConfigs> configs

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 BetaBrowserToolsetConfigs:

class BetaBrowserTripleClickConfig:

triple_click's config overrides.

Optional<Boolean> deferLoading

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

Optional<Boolean> enabled

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 BetaBrowserTypeConfig:

type's config overrides.

Optional<Boolean> deferLoading

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

Optional<Boolean> enabled

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 BetaBrowserWaitConfig:

wait's config overrides.

Optional<Boolean> deferLoading

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

Optional<Boolean> enabled

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 BetaBrowserZoomConfig:

zoom's config overrides.

Optional<Boolean> deferLoading

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

Optional<Boolean> enabled

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 BetaCacheControlEphemeral:

JsonValue type = "ephemeral"

Optional<Ttl> ttl

The time-to-live for the cache control breakpoint.

This may be one the following values:

5m: 5 minutes
1h: 1 hour

Defaults to 5m. See prompt caching pricing for details.

One of the following:

TTL_5M("5m")

TTL_1H("1h")

class BetaCacheCreation:

long ephemeral1hInputTokens

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

minimum0

long ephemeral5mInputTokens

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

minimum0

class BetaCacheMissMessagesChanged:

long cacheMissedInputTokens

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

JsonValue type = "messages_changed"

class BetaCacheMissModelChanged:

long cacheMissedInputTokens

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

JsonValue type = "model_changed"

class BetaCacheMissPreviousMessageNotFound:

JsonValue type = "previous_message_not_found"

class BetaCacheMissSystemChanged:

long cacheMissedInputTokens

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

JsonValue type = "system_changed"

class BetaCacheMissToolsChanged:

long cacheMissedInputTokens

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

JsonValue type = "tools_changed"

class BetaCacheMissUnavailable:

JsonValue type = "unavailable"

class BetaCitationCharLocation:

String citedText

long documentIndex

minimum0

Optional<String> documentTitle

long endCharIndex

Optional<String> fileId

long startCharIndex

minimum0

JsonValue type = "char_location"

class BetaCitationCharLocationParam:

String citedText

long documentIndex

minimum0

Optional<String> documentTitle

maxLength500

minLength1

long endCharIndex

long startCharIndex

minimum0

JsonValue type = "char_location"

class BetaCitationConfig:

boolean enabled

class BetaCitationContentBlockLocation:

String citedText

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.

long documentIndex

minimum0

Optional<String> documentTitle

long endBlockIndex

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.

Optional<String> fileId

long startBlockIndex

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

minimum0

JsonValue type = "content_block_location"

class BetaCitationContentBlockLocationParam:

String citedText

The full text of the cited block range, concatenated.

long documentIndex

minimum0

Optional<String> documentTitle

maxLength500

minLength1

long endBlockIndex

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.

long startBlockIndex

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

minimum0

JsonValue type = "content_block_location"

class BetaCitationPageLocation:

String citedText

long documentIndex

minimum0

Optional<String> documentTitle

long endPageNumber

Optional<String> fileId

long startPageNumber

minimum1

JsonValue type = "page_location"

class BetaCitationPageLocationParam:

String citedText

long documentIndex

minimum0

Optional<String> documentTitle

maxLength500

minLength1

long endPageNumber

long startPageNumber

minimum1

JsonValue type = "page_location"

class BetaCitationSearchResultLocation:

String citedText

The full text of the cited block range, concatenated.

long endBlockIndex

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.

long searchResultIndex

0-based index of the cited search result among all search_result content blocks in the request, in the order they appear across messages and tool results.

Counted separately from document_index; server-side web search results are not included in this count.

minimum0

String source

long startBlockIndex

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

minimum0

Optional<String> title

JsonValue type = "search_result_location"

class BetaCitationSearchResultLocationParam:

String citedText

The full text of the cited block range, concatenated.

long endBlockIndex

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.

long searchResultIndex

0-based index of the cited search result among all search_result content blocks in the request, in the order they appear across messages and tool results.

Counted separately from document_index; server-side web search results are not included in this count.

minimum0

String source

long startBlockIndex

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

minimum0

Optional<String> title

JsonValue type = "search_result_location"

class BetaCitationWebSearchResultLocationParam:

String citedText

String encryptedIndex

Optional<String> title

maxLength512

minLength1

JsonValue type = "web_search_result_location"

String url

minLength1

class BetaCitationsConfigParam:

Optional<Boolean> enabled

class BetaCitationsDelta:

class BetaCitationsWebSearchResultLocation:

String citedText

String encryptedIndex

Optional<String> title

maxLength512

JsonValue type = "web_search_result_location"

String url

class BetaClearThinking20251015Edit:

JsonValue type = "clear_thinking_20251015"

Optional<Keep> keep

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

One of the following:

class BetaThinkingTurns:

JsonValue type = "thinking_turns"

long value

minimum1

class BetaAllThinkingTurns:

JsonValue type = "all"

JsonValue

class BetaClearThinking20251015EditResponse:

long clearedInputTokens

Number of input tokens cleared by this edit.

minimum0

long clearedThinkingTurns

Number of thinking turns that were cleared.

minimum0

JsonValue type = "clear_thinking_20251015"

The type of context management edit applied.

class BetaClearToolUses20250919Edit:

class BetaClearToolUses20250919EditResponse:

long clearedInputTokens

Number of input tokens cleared by this edit.

minimum0

long clearedToolUses

Number of tool uses that were cleared.

minimum0

JsonValue type = "clear_tool_uses_20250919"

The type of context management edit applied.

class BetaCodeExecutionOutputBlock:

String fileId

JsonValue type = "code_execution_output"

class BetaCodeExecutionOutputBlockParam:

String fileId

JsonValue type = "code_execution_output"

class BetaCodeExecutionResultBlock:

List<BetaCodeExecutionOutputBlock> content

String fileId

JsonValue type = "code_execution_output"

long returnCode

String stderr

String stdout

JsonValue type = "code_execution_result"

class BetaCodeExecutionResultBlockParam:

List<BetaCodeExecutionOutputBlockParam> content

String fileId

JsonValue type = "code_execution_output"

long returnCode

String stderr

String stdout

JsonValue type = "code_execution_result"

class BetaCodeExecutionTool20250522:

class BetaCodeExecutionTool20250825:

class BetaCodeExecutionTool20260120:

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

class BetaCodeExecutionTool20260521:

Code execution tool with REPL state persistence.

class BetaCodeExecutionToolResultBlock:

BetaCodeExecutionToolResultBlockContent content

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

One of the following:

String toolUseId

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

JsonValue type = "code_execution_tool_result"

class BetaCodeExecutionToolResultBlockContent: union

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

class BetaCodeExecutionToolResultBlockParam:

BetaCodeExecutionToolResultBlockParamContent content

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

One of the following:

String toolUseId

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

JsonValue type = "code_execution_tool_result"

Optional<BetaCacheControlEphemeral> cacheControl

Create a cache control breakpoint at this content block.

JsonValue type = "ephemeral"

Optional<Ttl> ttl

The time-to-live for the cache control breakpoint.

This may be one the following values:

5m: 5 minutes
1h: 1 hour

Defaults to 5m. See prompt caching pricing for details.

One of the following:

TTL_5M("5m")

TTL_1H("1h")

class BetaCodeExecutionToolResultBlockParamContent: union

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

class BetaCodeExecutionToolResultError:

BetaCodeExecutionToolResultErrorCode errorCode

One of the following:

INVALID_TOOL_INPUT("invalid_tool_input")

UNAVAILABLE("unavailable")

TOO_MANY_REQUESTS("too_many_requests")

EXECUTION_TIME_EXCEEDED("execution_time_exceeded")

JsonValue type = "code_execution_tool_result_error"

enum BetaCodeExecutionToolResultErrorCode:

INVALID_TOOL_INPUT("invalid_tool_input")

UNAVAILABLE("unavailable")

TOO_MANY_REQUESTS("too_many_requests")

EXECUTION_TIME_EXCEEDED("execution_time_exceeded")

class BetaCodeExecutionToolResultErrorParam:

BetaCodeExecutionToolResultErrorCode errorCode

One of the following:

INVALID_TOOL_INPUT("invalid_tool_input")

UNAVAILABLE("unavailable")

TOO_MANY_REQUESTS("too_many_requests")

EXECUTION_TIME_EXCEEDED("execution_time_exceeded")

JsonValue type = "code_execution_tool_result_error"

class BetaCompact20260112Edit:

Automatically compact older context when reaching the configured trigger threshold.

JsonValue type = "compact_20260112"

Optional<String> instructions

Additional instructions for summarization.

Optional<Boolean> pauseAfterCompaction

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

Optional<BetaInputTokensTrigger> trigger

When to trigger compaction. Defaults to 150000 input tokens.

JsonValue type = "input_tokens"

long value

minimum1

class BetaCompactionBlock:

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.

Optional<String> content

Summary of compacted content, or null if compaction failed

Optional<String> encryptedContent

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

JsonValue type = "compaction"

class BetaCompactionBlockParam:

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.

JsonValue type = "compaction"

Optional<BetaCacheControlEphemeral> cacheControl

Create a cache control breakpoint at this content block.

JsonValue type = "ephemeral"

Optional<Ttl> ttl

The time-to-live for the cache control breakpoint.

This may be one the following values:

5m: 5 minutes
1h: 1 hour

Defaults to 5m. See prompt caching pricing for details.

One of the following:

TTL_5M("5m")

TTL_1H("1h")

Optional<String> content

Summary of previously compacted content, or null if compaction failed

Optional<String> encryptedContent

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

class BetaCompactionContentBlockDelta:

Optional<String> content

Optional<String> encryptedContent

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

JsonValue type = "compaction_delta"

class BetaCompactionIterationUsage:

Token usage for a compaction iteration.

Optional<BetaCacheCreation> cacheCreation

Breakdown of cached tokens by TTL

long ephemeral1hInputTokens

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

minimum0

long ephemeral5mInputTokens

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

minimum0

long cacheCreationInputTokens

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

minimum0

long cacheReadInputTokens

The number of input tokens read from the cache.

minimum0

long inputTokens

The number of input tokens which were used.

minimum0

long outputTokens

The number of output tokens which were used.

minimum0

JsonValue type = "compaction"

Usage for a compaction iteration

class BetaComputerCursorPositionConfig:

cursor_position's config overrides.

Optional<Boolean> deferLoading

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

Optional<Boolean> enabled

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 BetaComputerDoubleClickConfig:

double_click's config overrides.

Optional<Boolean> deferLoading

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

Optional<Boolean> enabled

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 BetaComputerHoldKeyConfig:

hold_key's config overrides.

Optional<Boolean> deferLoading

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

Optional<Boolean> enabled

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 BetaComputerKeyConfig:

key's config overrides.

Optional<Boolean> deferLoading

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

Optional<Boolean> enabled

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 BetaComputerLeftClickConfig:

left_click's config overrides.

Optional<Boolean> deferLoading

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

Optional<Boolean> enabled

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:

left_click_drag's config overrides.

Optional<Boolean> deferLoading

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

Optional<Boolean> enabled

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 BetaComputerLeftMouseDownConfig:

left_mouse_down's config overrides.

Optional<Boolean> deferLoading

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

Optional<Boolean> enabled

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 BetaComputerLeftMouseUpConfig:

left_mouse_up's config overrides.

Optional<Boolean> deferLoading

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

Optional<Boolean> enabled

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 BetaComputerMiddleClickConfig:

middle_click's config overrides.

Optional<Boolean> deferLoading

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

Optional<Boolean> enabled

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 BetaComputerMouseMoveConfig:

mouse_move's config overrides.

Optional<Boolean> deferLoading

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

Optional<Boolean> enabled

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 BetaComputerRightClickConfig:

right_click's config overrides.

Optional<Boolean> deferLoading

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

Optional<Boolean> enabled

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 BetaComputerScreenshotConfig:

screenshot's config overrides.

Optional<Boolean> deferLoading

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

Optional<Boolean> enabled

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 BetaComputerScrollConfig:

scroll's config overrides.

Optional<Boolean> deferLoading

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

Optional<Boolean> enabled

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 BetaComputerToolset20260801:

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.

JsonValue type = "computer_toolset_20260801"

Optional<BetaCacheControlEphemeral> cacheControl

Create a cache control breakpoint at this content block.

JsonValue type = "ephemeral"

Optional<Ttl> ttl

The time-to-live for the cache control breakpoint.

This may be one the following values:

5m: 5 minutes
1h: 1 hour

Defaults to 5m. See prompt caching pricing for details.

One of the following:

TTL_5M("5m")

TTL_1H("1h")

Optional<BetaComputerToolsetConfigs> configs

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 BetaComputerToolsetConfigs:

class BetaComputerTripleClickConfig:

triple_click's config overrides.

Optional<Boolean> deferLoading

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

Optional<Boolean> enabled

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 BetaComputerTypeConfig:

type's config overrides.

Optional<Boolean> deferLoading

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

Optional<Boolean> enabled

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 BetaComputerWaitConfig:

wait's config overrides.

Optional<Boolean> deferLoading

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

Optional<Boolean> enabled

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 BetaComputerZoomConfig:

zoom's config overrides.

Optional<Boolean> deferLoading

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

Optional<Boolean> enabled

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 BetaContainer:

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

String id

Identifier for the container used in this request

LocalDateTime expiresAt

The time at which the container will expire.

formatdate-time

Optional<List<BetaContainerSkill>> skills

Skills loaded in the container

String skillId

Skill ID

maxLength64

minLength1

Type type

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

One of the following:

ANTHROPIC("anthropic")

CUSTOM("custom")

String version

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

maxLength64

minLength1

class BetaContainerParams:

Container parameters with skills to be loaded.

Optional<String> id

Container id

Optional<List<BetaSkillParams>> skills

List of skills to load in the container

maxItems20

String skillId

Skill ID

maxLength64

minLength1

Type type

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

One of the following:

ANTHROPIC("anthropic")

CUSTOM("custom")

Optional<String> version

Skill version or 'latest' for most recent version

maxLength64

minLength1

class BetaContainerSkill:

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

String skillId

Skill ID

maxLength64

minLength1

Type type

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

One of the following:

ANTHROPIC("anthropic")

CUSTOM("custom")

String version

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

maxLength64

minLength1

class BetaContainerUploadBlock:

Response model for a file uploaded to the container.

String fileId

JsonValue type = "container_upload"

class BetaContainerUploadBlockParam:

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.

String fileId

JsonValue type = "container_upload"

Optional<BetaCacheControlEphemeral> cacheControl

Create a cache control breakpoint at this content block.

JsonValue type = "ephemeral"

Optional<Ttl> ttl

The time-to-live for the cache control breakpoint.

This may be one the following values:

5m: 5 minutes
1h: 1 hour

Defaults to 5m. See prompt caching pricing for details.

One of the following:

TTL_5M("5m")

TTL_1H("1h")

class BetaContentBlock: union

Response model for a file uploaded to the container.

class BetaContentBlockParam: union

Regular text content.

class BetaContentBlockSource:

Content content

One of the following:

String

List<BetaContentBlockSourceContent>

One of the following:

class BetaTextBlockParam:

class BetaImageBlockParam:

JsonValue type = "content"

class BetaContentBlockSourceContent: union

class BetaTextBlockParam:

class BetaImageBlockParam:

class BetaContextManagementConfig:

class BetaContextManagementResponse:

List<AppliedEdit> appliedEdits

List of context management edits that were applied.

One of the following:

class BetaClearToolUses20250919EditResponse:

long clearedInputTokens

Number of input tokens cleared by this edit.

minimum0

long clearedToolUses

Number of tool uses that were cleared.

minimum0

JsonValue type = "clear_tool_uses_20250919"

The type of context management edit applied.

class BetaClearThinking20251015EditResponse:

long clearedInputTokens

Number of input tokens cleared by this edit.

minimum0

long clearedThinkingTurns

Number of thinking turns that were cleared.

minimum0

JsonValue type = "clear_thinking_20251015"

The type of context management edit applied.

class BetaCountTokensContextManagementResponse:

long originalInputTokens

The original token count before context management was applied

class BetaDiagnostics:

Response envelope for request-level diagnostics. Present (possibly null) whenever the caller supplied diagnostics on the request.

class BetaDiagnosticsParam:

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

Optional<String> previousMessageId

The id (msg_...) from this client's previous /v1/messages response. The server compares that request's prompt fingerprint against this one and returns diagnostics.cache_miss_reason when the prompt-cache prefix could not be reused. Pass null on the first turn to opt in without a prior message to compare.

maxLength256

class BetaDirectCaller:

Tool invocation directly from the model.

JsonValue type = "direct"

class BetaDocumentBlock:

Optional<BetaCitationConfig> citations

Citation configuration for the document

boolean enabled

Source source

One of the following:

class BetaBase64PdfSource:

String data

formatbyte

JsonValue mediaType = "application/pdf"

JsonValue type = "base64"

class BetaPlainTextSource:

String data

JsonValue mediaType = "text/plain"

JsonValue type = "text"

Optional<String> title

The title of the document

JsonValue type = "document"

class BetaEncryptedCodeExecutionResultBlock:

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

List<BetaCodeExecutionOutputBlock> content

String fileId

JsonValue type = "code_execution_output"

String encryptedStdout

long returnCode

String stderr

JsonValue type = "encrypted_code_execution_result"

class BetaEncryptedCodeExecutionResultBlockParam:

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

List<BetaCodeExecutionOutputBlockParam> content

String fileId

JsonValue type = "code_execution_output"

String encryptedStdout

long returnCode

String stderr

JsonValue type = "encrypted_code_execution_result"

class BetaFallbackBlock:

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:

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.

BetaFallbackInfoParam from

Identifies one hop of a fallback transition.

Model model

The model that will complete your prompt.

See models for additional details and options.

One of the following:

BetaFallbackInfoParam to

Identifies one hop of a fallback transition.

Model model

The model that will complete your prompt.

See models for additional details and options.

One of the following:

JsonValue type = "fallback"

Optional<JsonValue> trigger

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

class BetaFallbackCreditNotApplied:

No reprice was applied; reason says why.

Reason reason

Why the reprice was not applied.

A closed enum; additions to the redemption-check vocabulary arrive as deliberate schema updates.

One of the following:

BODY_MISMATCH("body_mismatch")

CONTINUATION_EXCLUDED("continuation_excluded")

CONTINUATION_ONLY("continuation_only")

EXPIRED("expired")

INVALID_TARGET_MODEL("invalid_target_model")

NOT_ENABLED("not_enabled")

REPRICE_UNAVAILABLE("reprice_unavailable")

TEMPORARILY_UNAVAILABLE("temporarily_unavailable")

VARIANT_FIELDS_PRESENT("variant_fields_present")

WRONG_ORGANIZATION("wrong_organization")

WRONG_PLATFORM("wrong_platform")

WRONG_WORKSPACE("wrong_workspace")

JsonValue type = "not_applied"

Optional<List<String>> removeToRedeem

Request fields to remove before retrying, so the retry can redeem this token.

Present exactly when reason is variant_fields_present — never null, never an empty array; absent otherwise. Fields are named only from your own request, and only after the sealed variant hash matched. A served best-effort retry has already been billed at normal price; nothing redeems retroactively, but a corrected re-send inside the token's five-minute window can still redeem.

class BetaFallbackCreditRedeemed:

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

JsonValue type = "redeemed"

class BetaFallbackCreditTokenParam:

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.

String token

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

maxLength2048

minLength1

Optional<Mode> mode

How a failing token affects the retry. strict (the default, and the bare-string behavior): a failing redemption is a 400 and the retry is not served. best_effort: the retry is served either way — a token-layer failure no longer rejects the request; the retry proceeds at normal price and the outcome is reported on the response's usage.fallback_credit. Two failures stay hard in both modes: a malformed token, and combining fallback_credit_token with fallbacks.

One of the following:

STRICT("strict")

BEST_EFFORT("best_effort")

class BetaFallbackCreditUsage:

Outcome of the fallback_credit_token presented on this request.

class BetaFallbackInfo:

Identifies one hop of a fallback transition.

Model model

The model that will complete your prompt.

See models for additional details and options.

One of the following:

class BetaFallbackInfoParam:

Identifies one hop of a fallback transition.

Model model

The model that will complete your prompt.

See models for additional details and options.

One of the following:

class BetaFallbackMessageIterationUsage:

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

Produced in place of a message entry for whichever hop served the response. A declined hop produces the existing message entry. Whether a fallback model served the response is signalled by the presence of this entry in usage.iterations.

Optional<BetaCacheCreation> cacheCreation

Breakdown of cached tokens by TTL

long ephemeral1hInputTokens

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

minimum0

long ephemeral5mInputTokens

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

minimum0

long cacheCreationInputTokens

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

minimum0

long cacheReadInputTokens

The number of input tokens read from the cache.

minimum0

long inputTokens

The number of input tokens which were used.

minimum0

Model model

The model that will complete your prompt.

See models for additional details and options.

One of the following:

long outputTokens

The number of output tokens which were used.

minimum0

JsonValue type = "fallback_message"

Usage for the fallback-model attempt that served the response

class BetaFallbackParam:

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:

The from model declined for policy reasons.

Optional<Category> category

The policy category that triggered a refusal.

One of the following:

CYBER("cyber")

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

BIO("bio")

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

FRONTIER_LLM("frontier_llm")

The request could assist the development of competing AI models, which is restricted under Anthropic's commercial terms. Benign machine learning work can also trigger this category.

REASONING_EXTRACTION("reasoning_extraction")

The request asks the model to reproduce its internal reasoning in the response text. To get reasoning in a structured form instead, use adaptive thinking.

GENERAL_HARMS("general_harms")

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

JsonValue type = "refusal"

class BetaFallbacksParam: union

Opt-in server-side retry on one or more substitute models when the requested model declines for policy reasons. Tried in order: if the first entry also declines, the second is tried, and so on. The string "default" requests the requested model's server-defined default fallback configuration.

class BetaFileDocumentSource:

String fileId

JsonValue type = "file"

class BetaFileImageSource:

String fileId

JsonValue type = "file"

class BetaImageBlockParam:

class BetaImageTransformationsParam:

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.

Optional<OversizedImage> oversizedImage

What the server does when this image exceeds the model's maximum image size. "downsize" (the default) scales the image down to fit, which changes the dimensions the model observes without telling you. "error" instead rejects the request with a 400 error naming the image's dimensions and the largest dimensions that fit, so you can scale the image deliberately — your image is never silently scaled down.

One of the following:

DOWNSIZE("downsize")

ERROR("error")

class BetaInputJsonDelta:

String partialJson

JsonValue type = "input_json_delta"

class BetaInputTokensClearAtLeast:

JsonValue type = "input_tokens"

long value

minimum0

class BetaInputTokensTrigger:

JsonValue type = "input_tokens"

long value

minimum1

class BetaJsonOutputFormat:

Schema schema

The JSON schema of the format

JsonValue type = "json_schema"

class BetaMcpToolConfig:

Configuration for a specific tool in an MCP toolset.

Optional<Boolean> deferLoading

Optional<Boolean> enabled

class BetaMcpToolDefaultConfig:

Default configuration for tools in an MCP toolset.

Optional<Boolean> deferLoading

Optional<Boolean> enabled

class BetaMcpToolResultBlock:

class BetaMcpToolUseBlock:

String id

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

Input input

String name

The name of the MCP tool

String serverName

The name of the MCP server

JsonValue type = "mcp_tool_use"

class BetaMcpToolUseBlockParam:

String id

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

Input input

String name

String serverName

The name of the MCP server

JsonValue type = "mcp_tool_use"

Optional<BetaCacheControlEphemeral> cacheControl

Create a cache control breakpoint at this content block.

JsonValue type = "ephemeral"

Optional<Ttl> ttl

The time-to-live for the cache control breakpoint.

This may be one the following values:

5m: 5 minutes
1h: 1 hour

Defaults to 5m. See prompt caching pricing for details.

One of the following:

TTL_5M("5m")

TTL_1H("1h")

class BetaMcpToolset:

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:

class BetaMemoryTool20250818Command: union

class BetaMemoryTool20250818CreateCommand:

JsonValue command = "create"

Command type identifier

String fileText

Content to write to the file

String path

Path where the file should be created

class BetaMemoryTool20250818DeleteCommand:

JsonValue command = "delete"

Command type identifier

String path

Path to the file or directory to delete

class BetaMemoryTool20250818InsertCommand:

JsonValue command = "insert"

Command type identifier

long insertLine

Line number where text should be inserted

minimum1

String insertText

Text to insert at the specified line

String path

Path to the file where text should be inserted

class BetaMemoryTool20250818RenameCommand:

JsonValue command = "rename"

Command type identifier

String newPath

New path for the file or directory

String oldPath

Current path of the file or directory

class BetaMemoryTool20250818StrReplaceCommand:

JsonValue command = "str_replace"

Command type identifier

String newStr

Text to replace with

String oldStr

Text to search for and replace

String path

Path to the file where text should be replaced

class BetaMemoryTool20250818ViewCommand:

JsonValue command = "view"

Command type identifier

String path

Path to directory or file to view

Optional<List<Long>> viewRange

Optional line range for viewing specific lines

minItems2

maxItems2

class BetaMessage:

class BetaMessageDeltaUsage:

class BetaMessageIterationUsage:

Token usage for a sampling iteration.

Optional<BetaCacheCreation> cacheCreation

Breakdown of cached tokens by TTL

long ephemeral1hInputTokens

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

minimum0

long ephemeral5mInputTokens

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

minimum0

long cacheCreationInputTokens

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

minimum0

long cacheReadInputTokens

The number of input tokens read from the cache.

minimum0

long inputTokens

The number of input tokens which were used.

minimum0

Model model

The model that will complete your prompt.

See models for additional details and options.

One of the following:

long outputTokens

The number of output tokens which were used.

minimum0

JsonValue type = "message"

Usage for a sampling iteration

class BetaMessageParam:

class BetaMessageTokensCount:

Optional<BetaCountTokensContextManagementResponse> contextManagement

Information about context management applied to the message.

long originalInputTokens

The original token count before context management was applied

long inputTokens

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

class BetaMetadata:

Optional<String> userId

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

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

maxLength512

class BetaOutputConfig:

Optional<Effort> effort

All possible effort levels.

One of the following:

LOW("low")

MEDIUM("medium")

HIGH("high")

XHIGH("xhigh")

MAX("max")

Optional<BetaJsonOutputFormat> format

A schema to specify Claude's output format in responses. See structured outputs

Schema schema

The JSON schema of the format

JsonValue type = "json_schema"

Optional<BetaTokenTaskBudget> taskBudget

User-configurable total token budget across contexts.

long total

Total token budget across all contexts in the session.

minimum1024

JsonValue type = "tokens"

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

Optional<Long> remaining

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

minimum0

class BetaOutputTokensDetails:

long thinkingTokens

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.

minimum0

class BetaPlainTextSource:

String data

JsonValue mediaType = "text/plain"

JsonValue type = "text"

class BetaRawContentBlockDelta: union

class BetaRawContentBlockDeltaEvent:

BetaRawContentBlockDelta delta

One of the following:

long index

JsonValue type = "content_block_delta"

class BetaRawContentBlockStartEvent:

class BetaRawContentBlockStopEvent:

long index

JsonValue type = "content_block_stop"

class BetaRawMessageDeltaEvent:

class BetaRawMessageStartEvent:

BetaMessage message

JsonValue type = "message_start"

class BetaRawMessageStopEvent:

JsonValue type = "message_stop"

class BetaRawMessageStreamEvent: union

class BetaRawMessageStartEvent:

BetaMessage message

JsonValue type = "message_start"

class BetaRawMessageDeltaEvent:

class BetaRawMessageStopEvent:

JsonValue type = "message_stop"

class BetaRawContentBlockStartEvent:

class BetaRawContentBlockDeltaEvent:

BetaRawContentBlockDelta delta

One of the following:

long index

JsonValue type = "content_block_delta"

class BetaRawContentBlockStopEvent:

long index

JsonValue type = "content_block_stop"

class BetaRedactedThinkingBlock:

String data

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.

JsonValue type = "redacted_thinking"

class BetaRedactedThinkingBlockParam:

String 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.

JsonValue type = "redacted_thinking"

class BetaRefusalStopDetails:

Structured information about a refusal.

class BetaRequestDocumentBlock:

class BetaRequestMcpServerToolConfiguration:

Optional<List<String>> allowedTools

Optional<Boolean> enabled

class BetaRequestMcpServerUrlDefinition:

String name

JsonValue type = "url"

String url

Optional<String> authorizationToken

Optional<BetaRequestMcpServerToolConfiguration> toolConfiguration

Optional<List<String>> allowedTools

Optional<Boolean> enabled

class BetaRequestMcpToolResultBlockParam:

class BetaRequestToolAdditionBlock:

Mid-conversation directive to surface a declared tool.

tool references a tool (or MCP toolset) by name from the request's tools; it is offered to the model from this point in the conversation onward.

class BetaRequestToolRemovalBlock:

Mid-conversation directive to withdraw a tool.

tool references a tool (or MCP toolset) by name from the request's tools; it is no longer offered to the model from this point in the conversation onward.

class BetaSearchResultBlockParam:

class BetaServerToolCaller:

Tool invocation generated by a server-side tool.

String toolId

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

JsonValue type = "code_execution_20250825"

class BetaServerToolCaller20260120:

String toolId

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

JsonValue type = "code_execution_20260120"

class BetaServerToolUsage:

long webFetchRequests

The number of web fetch tool requests.

minimum0

long webSearchRequests

The number of web search tool requests.

minimum0

class BetaServerToolUseBlock:

class BetaServerToolUseBlockParam:

class BetaSignatureDelta:

String signature

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.

JsonValue type = "signature_delta"

class BetaSkillParams:

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

String skillId

Skill ID

maxLength64

minLength1

Type type

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

One of the following:

ANTHROPIC("anthropic")

CUSTOM("custom")

Optional<String> version

Skill version or 'latest' for most recent version

maxLength64

minLength1

enum BetaStopReason:

END_TURN("end_turn")

MAX_TOKENS("max_tokens")

STOP_SEQUENCE("stop_sequence")

TOOL_USE("tool_use")

PAUSE_TURN("pause_turn")

COMPACTION("compaction")

REFUSAL("refusal")

MODEL_CONTEXT_WINDOW_EXCEEDED("model_context_window_exceeded")

class BetaSystemMessageOutputConfig:

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.

Optional<Effort> effort

All possible effort levels.

One of the following:

LOW("low")

MEDIUM("medium")

HIGH("high")

XHIGH("xhigh")

MAX("max")

class BetaTextBlock:

class BetaTextBlockParam:

class BetaTextCitation: union

class BetaTextCitationParam: union

class BetaTextDelta:

String text

JsonValue type = "text_delta"

class BetaTextEditorCodeExecutionCreateResultBlock:

boolean isFileUpdate

JsonValue type = "text_editor_code_execution_create_result"

class BetaTextEditorCodeExecutionCreateResultBlockParam:

boolean isFileUpdate

JsonValue type = "text_editor_code_execution_create_result"

class BetaTextEditorCodeExecutionStrReplaceResultBlock:

Optional<List<String>> lines

Optional<Long> newLines

Optional<Long> newStart

Optional<Long> oldLines

Optional<Long> oldStart

JsonValue type = "text_editor_code_execution_str_replace_result"

class BetaTextEditorCodeExecutionStrReplaceResultBlockParam:

JsonValue type = "text_editor_code_execution_str_replace_result"

Optional<List<String>> lines

Optional<Long> newLines

Optional<Long> newStart

Optional<Long> oldLines

Optional<Long> oldStart

class BetaTextEditorCodeExecutionToolResultBlock:

class BetaTextEditorCodeExecutionToolResultBlockParam:

class BetaTextEditorCodeExecutionToolResultError:

ErrorCode errorCode

One of the following:

INVALID_TOOL_INPUT("invalid_tool_input")

UNAVAILABLE("unavailable")

TOO_MANY_REQUESTS("too_many_requests")

EXECUTION_TIME_EXCEEDED("execution_time_exceeded")

FILE_NOT_FOUND("file_not_found")

Optional<String> errorMessage

JsonValue type = "text_editor_code_execution_tool_result_error"

class BetaTextEditorCodeExecutionToolResultErrorParam:

ErrorCode errorCode

One of the following:

INVALID_TOOL_INPUT("invalid_tool_input")

UNAVAILABLE("unavailable")

TOO_MANY_REQUESTS("too_many_requests")

EXECUTION_TIME_EXCEEDED("execution_time_exceeded")

FILE_NOT_FOUND("file_not_found")

JsonValue type = "text_editor_code_execution_tool_result_error"

Optional<String> errorMessage

class BetaTextEditorCodeExecutionViewResultBlock:

String content

FileType fileType

One of the following:

TEXT("text")

IMAGE("image")

PDF("pdf")

Optional<Long> numLines

Optional<Long> startLine

Optional<Long> totalLines

JsonValue type = "text_editor_code_execution_view_result"

class BetaTextEditorCodeExecutionViewResultBlockParam:

String content

FileType fileType

One of the following:

TEXT("text")

IMAGE("image")

PDF("pdf")

JsonValue type = "text_editor_code_execution_view_result"

Optional<Long> numLines

Optional<Long> startLine

Optional<Long> totalLines

class BetaThinkingBlock:

String signature

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.

String thinking

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

JsonValue type = "thinking"

class BetaThinkingBlockBinding:

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.

Optional<BetaThinkingPrefixMismatchBehavior> prefixMismatchBehavior

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

One of the following:

ERROR("error")

DROP_BLOCK("drop_block")

class BetaThinkingBlockParam:

String signature

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.

String thinking

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

JsonValue type = "thinking"

class BetaThinkingConfigAdaptive:

JsonValue type = "adaptive"

Optional<BetaThinkingBlockBinding> blockBinding

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.

Optional<BetaThinkingPrefixMismatchBehavior> prefixMismatchBehavior

One of the following:

ERROR("error")

DROP_BLOCK("drop_block")

Optional<Display> 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. Defaults to summarized.

One of the following:

SUMMARIZED("summarized")

OMITTED("omitted")

UPDATES("updates")

class BetaThinkingConfigDisabled:

JsonValue type = "disabled"

class BetaThinkingConfigEnabled:

long budgetTokens

Determines how many tokens Claude can use for its internal reasoning process. Larger budgets can enable more thorough analysis for complex problems, improving response quality.

Must be ≥1024 and less than max_tokens.

See extended thinking for details.

minimum1024

JsonValue type = "enabled"

Optional<BetaThinkingBlockBinding> blockBinding

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.

Optional<BetaThinkingPrefixMismatchBehavior> prefixMismatchBehavior

One of the following:

ERROR("error")

DROP_BLOCK("drop_block")

Optional<Display> display

One of the following:

SUMMARIZED("summarized")

OMITTED("omitted")

UPDATES("updates")

class BetaThinkingConfigParam: union

Configuration for enabling Claude's extended thinking.

When enabled, responses include thinking content blocks showing Claude's thinking process before the final answer. Requires a minimum budget of 1,024 tokens and counts towards your max_tokens limit.

See extended thinking for details.

class BetaThinkingDelta:

Optional<Long> estimatedTokens

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.

String thinking

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.

JsonValue type = "thinking_delta"

class BetaThinkingDroppedInputTransformation:

String path

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 reason

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

One of the following:

MODEL_BINDING_MISMATCH("model_binding_mismatch")

PREFIX_BINDING_MISMATCH("prefix_binding_mismatch")

ORGANIZATION_BINDING_MISMATCH("organization_binding_mismatch")

END_USER_BINDING_MISMATCH("end_user_binding_mismatch")

JsonValue type = "thinking_dropped"

Always thinking_dropped for this entry type.

enum BetaThinkingPrefixMismatchBehavior:

ERROR("error")

DROP_BLOCK("drop_block")

class BetaThinkingTurns:

JsonValue type = "thinking_turns"

long value

minimum1

class BetaTokenTaskBudget:

User-configurable total token budget across contexts.

long total

Total token budget across all contexts in the session.

minimum1024

JsonValue type = "tokens"

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

Optional<Long> remaining

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

minimum0

class BetaTool:

class BetaToolBash20241022:

class BetaToolBash20250124:

class BetaToolChangeMcpToolReference:

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

String name

String serverName

JsonValue type = "mcp_tool_reference"

class BetaToolChangeMcpToolsetReference:

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

String serverName

JsonValue type = "mcp_toolset_reference"

class BetaToolChangeToolReference:

Reference to a single tool the caller declared directly in tools[]. Does not accept the composed {server}_{name} form the server assigns to MCP-resolved tools — use mcp_tool_reference or mcp_toolset_reference for those.

String name

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

JsonValue type = "tool_reference"

class BetaToolChoice: union

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 BetaToolChoiceAuto:

The model will automatically decide whether to use tools.

JsonValue type = "auto"

Optional<Boolean> disableParallelToolUse

Whether to disable parallel tool use.

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

class BetaToolChoiceAny:

The model will use any available tools.

JsonValue type = "any"

Optional<Boolean> disableParallelToolUse

Whether to disable parallel tool use.

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

class BetaToolChoiceTool:

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

String name

The name of the tool to use.

JsonValue type = "tool"

Optional<Boolean> disableParallelToolUse

Whether to disable parallel tool use.

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

class BetaToolChoiceNone:

The model will not be allowed to use tools.

JsonValue type = "none"

class BetaToolChoiceAny:

The model will use any available tools.

JsonValue type = "any"

Optional<Boolean> disableParallelToolUse

Whether to disable parallel tool use.

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

class BetaToolChoiceAuto:

The model will automatically decide whether to use tools.

JsonValue type = "auto"

Optional<Boolean> disableParallelToolUse

Whether to disable parallel tool use.

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

class BetaToolChoiceNone:

The model will not be allowed to use tools.

JsonValue type = "none"

class BetaToolChoiceTool:

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

String name

The name of the tool to use.

JsonValue type = "tool"

Optional<Boolean> disableParallelToolUse

Whether to disable parallel tool use.

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

class BetaToolComputerUse20241022:

class BetaToolComputerUse20250124:

class BetaToolComputerUse20251124:

class BetaToolReferenceBlock:

String toolName

maxLength256

minLength1

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

JsonValue type = "tool_reference"

class BetaToolReferenceBlockParam:

Tool reference block that can be included in tool_result content.

String toolName

maxLength256

minLength1

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

JsonValue type = "tool_reference"

Optional<BetaCacheControlEphemeral> cacheControl

Create a cache control breakpoint at this content block.

JsonValue type = "ephemeral"

Optional<Ttl> ttl

The time-to-live for the cache control breakpoint.

This may be one the following values:

5m: 5 minutes
1h: 1 hour

Defaults to 5m. See prompt caching pricing for details.

One of the following:

TTL_5M("5m")

TTL_1H("1h")

class BetaToolResultBlockParam:

class BetaToolSearchToolBm25_20251119:

class BetaToolSearchToolRegex20251119:

class BetaToolSearchToolResultBlock:

class BetaToolSearchToolResultBlockParam:

class BetaToolSearchToolResultError:

ErrorCode errorCode

One of the following:

INVALID_TOOL_INPUT("invalid_tool_input")

UNAVAILABLE("unavailable")

TOO_MANY_REQUESTS("too_many_requests")

EXECUTION_TIME_EXCEEDED("execution_time_exceeded")

Optional<String> errorMessage

JsonValue type = "tool_search_tool_result_error"

class BetaToolSearchToolResultErrorParam:

ErrorCode errorCode

One of the following:

INVALID_TOOL_INPUT("invalid_tool_input")

UNAVAILABLE("unavailable")

TOO_MANY_REQUESTS("too_many_requests")

EXECUTION_TIME_EXCEEDED("execution_time_exceeded")

JsonValue type = "tool_search_tool_result_error"

Optional<String> errorMessage

class BetaToolSearchToolSearchResultBlock:

List<BetaToolReferenceBlock> toolReferences

String toolName

maxLength256

minLength1

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

JsonValue type = "tool_reference"

JsonValue type = "tool_search_tool_search_result"

class BetaToolSearchToolSearchResultBlockParam:

List<BetaToolReferenceBlockParam> toolReferences

String toolName

maxLength256

minLength1

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

JsonValue type = "tool_reference"

Optional<BetaCacheControlEphemeral> cacheControl

Create a cache control breakpoint at this content block.

JsonValue type = "ephemeral"

Optional<Ttl> ttl

The time-to-live for the cache control breakpoint.

This may be one the following values:

5m: 5 minutes
1h: 1 hour

Defaults to 5m. See prompt caching pricing for details.

One of the following:

TTL_5M("5m")

TTL_1H("1h")

JsonValue type = "tool_search_tool_search_result"

class BetaToolTextEditor20241022:

class BetaToolTextEditor20250124:

class BetaToolTextEditor20250429:

class BetaToolTextEditor20250728:

class BetaToolUnion: union

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

class BetaToolUseBlock:

String id

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

Input input

String name

minLength1

JsonValue type = "tool_use"

Optional<Caller> caller

Tool invocation directly from the model.

One of the following:

class BetaDirectCaller:

Tool invocation directly from the model.

JsonValue type = "direct"

class BetaServerToolCaller:

Tool invocation generated by a server-side tool.

String toolId

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

JsonValue type = "code_execution_20250825"

class BetaServerToolCaller20260120:

String toolId

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

JsonValue type = "code_execution_20260120"

Optional<String> toolsetName

For a toolset member tool_use, the toolset family.

maxLength64

minLength1

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

class BetaToolUseBlockParam:

class BetaToolUsesKeep:

JsonValue type = "tool_uses"

long value

minimum0

class BetaToolUsesTrigger:

JsonValue type = "tool_uses"

long value

minimum1

class BetaUrlImageSource:

JsonValue type = "url"

String url

class BetaUrlPdfSource:

JsonValue type = "url"

String url

class BetaUsage:

class BetaUserLocation:

JsonValue type = "approximate"

Optional<String> city

The city of the user.

maxLength255

minLength1

Optional<String> country

The two letter ISO country code of the user.

maxLength2

minLength2

Optional<String> region

The region of the user.

maxLength255

minLength1

Optional<String> timezone

The IANA timezone of the user.

maxLength255

minLength1

class BetaWebFetchBlock:

class BetaWebFetchBlockParam:

BetaRequestDocumentBlock content

JsonValue type = "web_fetch_result"

String url

Fetched content URL

Optional<String> retrievedAt

ISO 8601 timestamp when the content was retrieved

class BetaWebFetchTool20250910:

class BetaWebFetchTool20260209:

class BetaWebFetchTool20260309:

Web fetch tool with use_cache parameter for bypassing cached content.

class BetaWebFetchTool20260318:

class BetaWebFetchToolResultBlock:

class BetaWebFetchToolResultBlockParam:

class BetaWebFetchToolResultErrorBlock:

BetaWebFetchToolResultErrorCode errorCode

One of the following:

INVALID_TOOL_INPUT("invalid_tool_input")

URL_TOO_LONG("url_too_long")

URL_NOT_ALLOWED("url_not_allowed")

URL_NOT_IN_PRIOR_CONTEXT("url_not_in_prior_context")

URL_NOT_ACCESSIBLE("url_not_accessible")

UNSUPPORTED_CONTENT_TYPE("unsupported_content_type")

TOO_MANY_REQUESTS("too_many_requests")

MAX_USES_EXCEEDED("max_uses_exceeded")

UNAVAILABLE("unavailable")

JsonValue type = "web_fetch_tool_result_error"

class BetaWebFetchToolResultErrorBlockParam:

BetaWebFetchToolResultErrorCode errorCode

One of the following:

INVALID_TOOL_INPUT("invalid_tool_input")

URL_TOO_LONG("url_too_long")

URL_NOT_ALLOWED("url_not_allowed")

URL_NOT_IN_PRIOR_CONTEXT("url_not_in_prior_context")

URL_NOT_ACCESSIBLE("url_not_accessible")

UNSUPPORTED_CONTENT_TYPE("unsupported_content_type")

TOO_MANY_REQUESTS("too_many_requests")

MAX_USES_EXCEEDED("max_uses_exceeded")

UNAVAILABLE("unavailable")

JsonValue type = "web_fetch_tool_result_error"

enum BetaWebFetchToolResultErrorCode:

INVALID_TOOL_INPUT("invalid_tool_input")

URL_TOO_LONG("url_too_long")

URL_NOT_ALLOWED("url_not_allowed")

URL_NOT_IN_PRIOR_CONTEXT("url_not_in_prior_context")

URL_NOT_ACCESSIBLE("url_not_accessible")

UNSUPPORTED_CONTENT_TYPE("unsupported_content_type")

TOO_MANY_REQUESTS("too_many_requests")

MAX_USES_EXCEEDED("max_uses_exceeded")

UNAVAILABLE("unavailable")

class BetaWebSearchResultBlock:

String encryptedContent

Optional<String> pageAge

String title

JsonValue type = "web_search_result"

String url

class BetaWebSearchResultBlockParam:

String encryptedContent

String title

JsonValue type = "web_search_result"

String url

Optional<String> pageAge

class BetaWebSearchTool20250305:

class BetaWebSearchTool20260209:

class BetaWebSearchTool20260318:

class BetaWebSearchToolRequestError:

BetaWebSearchToolResultErrorCode errorCode

One of the following:

INVALID_TOOL_INPUT("invalid_tool_input")

UNAVAILABLE("unavailable")

MAX_USES_EXCEEDED("max_uses_exceeded")

TOO_MANY_REQUESTS("too_many_requests")

QUERY_TOO_LONG("query_too_long")

REQUEST_TOO_LARGE("request_too_large")

JsonValue type = "web_search_tool_result_error"

class BetaWebSearchToolResultBlock:

class BetaWebSearchToolResultBlockContent: union

class BetaWebSearchToolResultError:

BetaWebSearchToolResultErrorCode errorCode

One of the following:

INVALID_TOOL_INPUT("invalid_tool_input")

UNAVAILABLE("unavailable")

MAX_USES_EXCEEDED("max_uses_exceeded")

TOO_MANY_REQUESTS("too_many_requests")

QUERY_TOO_LONG("query_too_long")

REQUEST_TOO_LARGE("request_too_large")

JsonValue type = "web_search_tool_result_error"

List<BetaWebSearchResultBlock>

String encryptedContent

Optional<String> pageAge

String title

JsonValue type = "web_search_result"

String url

class BetaWebSearchToolResultBlockParam:

class BetaWebSearchToolResultBlockParamContent: union

List<BetaWebSearchResultBlockParam>

String encryptedContent

String title

JsonValue type = "web_search_result"

String url

Optional<String> pageAge

class BetaWebSearchToolRequestError:

BetaWebSearchToolResultErrorCode errorCode

One of the following:

INVALID_TOOL_INPUT("invalid_tool_input")

UNAVAILABLE("unavailable")

MAX_USES_EXCEEDED("max_uses_exceeded")

TOO_MANY_REQUESTS("too_many_requests")

QUERY_TOO_LONG("query_too_long")

REQUEST_TOO_LARGE("request_too_large")

JsonValue type = "web_search_tool_result_error"

class BetaWebSearchToolResultError:

BetaWebSearchToolResultErrorCode errorCode

One of the following:

INVALID_TOOL_INPUT("invalid_tool_input")

UNAVAILABLE("unavailable")

MAX_USES_EXCEEDED("max_uses_exceeded")

TOO_MANY_REQUESTS("too_many_requests")

QUERY_TOO_LONG("query_too_long")

REQUEST_TOO_LARGE("request_too_large")

JsonValue type = "web_search_tool_result_error"

enum BetaWebSearchToolResultErrorCode:

INVALID_TOOL_INPUT("invalid_tool_input")

UNAVAILABLE("unavailable")

MAX_USES_EXCEEDED("max_uses_exceeded")

TOO_MANY_REQUESTS("too_many_requests")

QUERY_TOO_LONG("query_too_long")

REQUEST_TOO_LARGE("request_too_large")

Messages

Create a Message

Count tokens in a Message

Models

MessagesBatches

Create a Message Batch

Retrieve a Message Batch

List Message Batches

Cancel a Message Batch

Delete a Message Batch

Retrieve Message Batch results

Messages

Models

MessagesBatches

MessagesBatches