Messages

Create a Message

client.beta.messages.create(, ?): BetaMessage { id, container, content, 7 more } | Stream<BetaRawMessageStreamEvent>

POST/v1/messages

Count tokens in a Message

client.beta.messages.countTokens(, ?): BetaMessageTokensCount { context_management, input_tokens }

POST/v1/messages/count_tokens

ModelsExpand Collapse

BetaAllThinkingTurns { type }

type: "all"

BetaBase64ImageSource { data, media_type, type }

data: string

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

Accepts one of the following:

"image/jpeg"

"image/png"

"image/gif"

"image/webp"

type: "base64"

BetaBase64PDFSource { data, media_type, type }

data: string

media_type: "application/pdf"

type: "base64"

BetaBashCodeExecutionOutputBlock { file_id, type }

file_id: string

type: "bash_code_execution_output"

BetaBashCodeExecutionOutputBlockParam { file_id, type }

file_id: string

type: "bash_code_execution_output"

BetaBashCodeExecutionResultBlock { content, return_code, stderr, 2 more }

content: Array<BetaBashCodeExecutionOutputBlock { file_id, type } >

file_id: string

type: "bash_code_execution_output"

return_code: number

stderr: string

stdout: string

type: "bash_code_execution_result"

BetaBashCodeExecutionResultBlockParam { content, return_code, stderr, 2 more }

content: Array<BetaBashCodeExecutionOutputBlockParam { file_id, type } >

file_id: string

type: "bash_code_execution_output"

return_code: number

stderr: string

stdout: string

type: "bash_code_execution_result"

BetaBashCodeExecutionToolResultBlock { content, tool_use_id, type }

content: BetaBashCodeExecutionToolResultError { error_code, type } | BetaBashCodeExecutionResultBlock { content, return_code, stderr, 2 more }

Accepts one of the following:

BetaBashCodeExecutionToolResultError { error_code, type }

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

Accepts one of the following:

"invalid_tool_input"

"unavailable"

"too_many_requests"

"execution_time_exceeded"

"output_file_too_large"

type: "bash_code_execution_tool_result_error"

BetaBashCodeExecutionResultBlock { content, return_code, stderr, 2 more }

content: Array<BetaBashCodeExecutionOutputBlock { file_id, type } >

file_id: string

type: "bash_code_execution_output"

return_code: number

stderr: string

stdout: string

type: "bash_code_execution_result"

tool_use_id: string

type: "bash_code_execution_tool_result"

BetaBashCodeExecutionToolResultBlockParam { content, tool_use_id, type, cache_control }

content: BetaBashCodeExecutionToolResultErrorParam { error_code, type } | BetaBashCodeExecutionResultBlockParam { content, return_code, stderr, 2 more }

Accepts one of the following:

BetaBashCodeExecutionToolResultErrorParam { error_code, type }

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

Accepts one of the following:

"invalid_tool_input"

"unavailable"

"too_many_requests"

"execution_time_exceeded"

"output_file_too_large"

type: "bash_code_execution_tool_result_error"

BetaBashCodeExecutionResultBlockParam { content, return_code, stderr, 2 more }

content: Array<BetaBashCodeExecutionOutputBlockParam { file_id, type } >

file_id: string

type: "bash_code_execution_output"

return_code: number

stderr: string

stdout: string

type: "bash_code_execution_result"

tool_use_id: string

type: "bash_code_execution_tool_result"

cache_control?: BetaCacheControlEphemeral { type, ttl } | null

Create a cache control breakpoint at this content block.

type: "ephemeral"

ttl?: "5m" | "1h"

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

This may be one the following values:

5m: 5 minutes
1h: 1 hour

Defaults to 5m.

Accepts one of the following:

"5m"

"1h"

BetaBashCodeExecutionToolResultError { error_code, type }

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

Accepts one of the following:

"invalid_tool_input"

"unavailable"

"too_many_requests"

"execution_time_exceeded"

"output_file_too_large"

type: "bash_code_execution_tool_result_error"

BetaBashCodeExecutionToolResultErrorParam { error_code, type }

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

Accepts one of the following:

"invalid_tool_input"

"unavailable"

"too_many_requests"

"execution_time_exceeded"

"output_file_too_large"

type: "bash_code_execution_tool_result_error"

BetaCacheControlEphemeral { type, ttl }

type: "ephemeral"

ttl?: "5m" | "1h"

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

This may be one the following values:

5m: 5 minutes
1h: 1 hour

Defaults to 5m.

Accepts one of the following:

"5m"

"1h"

BetaCacheCreation { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }

ephemeral_1h_input_tokens: number

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

ephemeral_5m_input_tokens: number

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

BetaCitationCharLocation { cited_text, document_index, document_title, 4 more }

cited_text: string

document_index: number

document_title: string | null

end_char_index: number

file_id: string | null

start_char_index: number

type: "char_location"

BetaCitationCharLocationParam { cited_text, document_index, document_title, 3 more }

cited_text: string

document_index: number

document_title: string | null

end_char_index: number

start_char_index: number

type: "char_location"

BetaCitationConfig { enabled }

enabled: boolean

BetaCitationContentBlockLocation { cited_text, document_index, document_title, 4 more }

cited_text: string

document_index: number

document_title: string | null

end_block_index: number

file_id: string | null

start_block_index: number

type: "content_block_location"

BetaCitationContentBlockLocationParam { cited_text, document_index, document_title, 3 more }

cited_text: string

document_index: number

document_title: string | null

end_block_index: number

start_block_index: number

type: "content_block_location"

BetaCitationPageLocation { cited_text, document_index, document_title, 4 more }

cited_text: string

document_index: number

document_title: string | null

end_page_number: number

file_id: string | null

start_page_number: number

type: "page_location"

BetaCitationPageLocationParam { cited_text, document_index, document_title, 3 more }

cited_text: string

document_index: number

document_title: string | null

end_page_number: number

start_page_number: number

type: "page_location"

BetaCitationSearchResultLocation { cited_text, end_block_index, search_result_index, 4 more }

cited_text: string

end_block_index: number

search_result_index: number

source: string

start_block_index: number

title: string | null

type: "search_result_location"

BetaCitationSearchResultLocationParam { cited_text, end_block_index, search_result_index, 4 more }

cited_text: string

end_block_index: number

search_result_index: number

source: string

start_block_index: number

title: string | null

type: "search_result_location"

BetaCitationWebSearchResultLocationParam { cited_text, encrypted_index, title, 2 more }

cited_text: string

encrypted_index: string

title: string | null

type: "web_search_result_location"

url: string

BetaCitationsConfigParam { enabled }

enabled?: boolean

BetaCitationsDelta { citation, type }

citation: BetaCitationCharLocation { cited_text, document_index, document_title, 4 more } | BetaCitationPageLocation { cited_text, document_index, document_title, 4 more } | BetaCitationContentBlockLocation { cited_text, document_index, document_title, 4 more } | 2 more

Accepts one of the following:

BetaCitationCharLocation { cited_text, document_index, document_title, 4 more }

cited_text: string

document_index: number

document_title: string | null

end_char_index: number

file_id: string | null

start_char_index: number

type: "char_location"

BetaCitationPageLocation { cited_text, document_index, document_title, 4 more }

cited_text: string

document_index: number

document_title: string | null

end_page_number: number

file_id: string | null

start_page_number: number

type: "page_location"

BetaCitationContentBlockLocation { cited_text, document_index, document_title, 4 more }

cited_text: string

document_index: number

document_title: string | null

end_block_index: number

file_id: string | null

start_block_index: number

type: "content_block_location"

BetaCitationsWebSearchResultLocation { cited_text, encrypted_index, title, 2 more }

cited_text: string

encrypted_index: string

title: string | null

type: "web_search_result_location"

url: string

BetaCitationSearchResultLocation { cited_text, end_block_index, search_result_index, 4 more }

cited_text: string

end_block_index: number

search_result_index: number

source: string

start_block_index: number

title: string | null

type: "search_result_location"

type: "citations_delta"

BetaCitationsWebSearchResultLocation { cited_text, encrypted_index, title, 2 more }

cited_text: string

encrypted_index: string

title: string | null

type: "web_search_result_location"

url: string

BetaClearThinking20251015Edit { type, keep }

type: "clear_thinking_20251015"

keep?: BetaThinkingTurns { type, value } | BetaAllThinkingTurns { type } | "all"

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

Accepts one of the following:

BetaThinkingTurns { type, value }

type: "thinking_turns"

value: number

BetaAllThinkingTurns { type }

type: "all"

"all"

BetaClearThinking20251015EditResponse { cleared_input_tokens, cleared_thinking_turns, type }

cleared_input_tokens: number

Number of input tokens cleared by this edit.

cleared_thinking_turns: number

Number of thinking turns that were cleared.

type: "clear_thinking_20251015"

The type of context management edit applied.

BetaClearToolUses20250919Edit { type, clear_at_least, clear_tool_inputs, 3 more }

type: "clear_tool_uses_20250919"

clear_at_least?: BetaInputTokensClearAtLeast { type, value } | null

Minimum number of tokens that must be cleared when triggered. Context will only be modified if at least this many tokens can be removed.

type: "input_tokens"

value: number

clear_tool_inputs?: boolean | Array<string> | null

Whether to clear all tool inputs (bool) or specific tool inputs to clear (list)

Accepts one of the following:

boolean

Array<string>

exclude_tools?: Array<string> | null

Tool names whose uses are preserved from clearing

keep?: BetaToolUsesKeep { type, value }

Number of tool uses to retain in the conversation

type: "tool_uses"

value: number

trigger?: BetaInputTokensTrigger { type, value } | BetaToolUsesTrigger { type, value }

Condition that triggers the context management strategy

Accepts one of the following:

BetaInputTokensTrigger { type, value }

type: "input_tokens"

value: number

BetaToolUsesTrigger { type, value }

type: "tool_uses"

value: number

BetaClearToolUses20250919EditResponse { cleared_input_tokens, cleared_tool_uses, type }

cleared_input_tokens: number

Number of input tokens cleared by this edit.

cleared_tool_uses: number

Number of tool uses that were cleared.

type: "clear_tool_uses_20250919"

The type of context management edit applied.

BetaCodeExecutionOutputBlock { file_id, type }

file_id: string

type: "code_execution_output"

BetaCodeExecutionOutputBlockParam { file_id, type }

file_id: string

type: "code_execution_output"

BetaCodeExecutionResultBlock { content, return_code, stderr, 2 more }

content: Array<BetaCodeExecutionOutputBlock { file_id, type } >

file_id: string

type: "code_execution_output"

return_code: number

stderr: string

stdout: string

type: "code_execution_result"

BetaCodeExecutionResultBlockParam { content, return_code, stderr, 2 more }

content: Array<BetaCodeExecutionOutputBlockParam { file_id, type } >

file_id: string

type: "code_execution_output"

return_code: number

stderr: string

stdout: string

type: "code_execution_result"

BetaCodeExecutionTool20250522 { name, type, allowed_callers, 3 more }

Name of the tool.

This is how the tool will be called by the model and in tool_use blocks.

type: "code_execution_20250522"

allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">

Accepts one of the following:

"direct"

"code_execution_20250825"

"code_execution_20260120"

cache_control?: BetaCacheControlEphemeral { type, ttl } | null

Create a cache control breakpoint at this content block.

type: "ephemeral"

ttl?: "5m" | "1h"

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

This may be one the following values:

5m: 5 minutes
1h: 1 hour

Defaults to 5m.

Accepts one of the following:

"5m"

"1h"

defer_loading?: boolean

If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

strict?: boolean

When true, guarantees schema validation on tool names and inputs

BetaCodeExecutionTool20250825 { name, type, allowed_callers, 3 more }

Name of the tool.

This is how the tool will be called by the model and in tool_use blocks.

type: "code_execution_20250825"

allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">

Accepts one of the following:

"direct"

"code_execution_20250825"

"code_execution_20260120"

cache_control?: BetaCacheControlEphemeral { type, ttl } | null

Create a cache control breakpoint at this content block.

type: "ephemeral"

ttl?: "5m" | "1h"

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

This may be one the following values:

5m: 5 minutes
1h: 1 hour

Defaults to 5m.

Accepts one of the following:

"5m"

"1h"

defer_loading?: boolean

If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

strict?: boolean

When true, guarantees schema validation on tool names and inputs

BetaCodeExecutionTool20260120 { name, type, allowed_callers, 3 more }

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

Name of the tool.

This is how the tool will be called by the model and in tool_use blocks.

type: "code_execution_20260120"

allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">

Accepts one of the following:

"direct"

"code_execution_20250825"

"code_execution_20260120"

cache_control?: BetaCacheControlEphemeral { type, ttl } | null

Create a cache control breakpoint at this content block.

type: "ephemeral"

ttl?: "5m" | "1h"

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

This may be one the following values:

5m: 5 minutes
1h: 1 hour

Defaults to 5m.

Accepts one of the following:

"5m"

"1h"

defer_loading?: boolean

If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search.

strict?: boolean

When true, guarantees schema validation on tool names and inputs

BetaCodeExecutionToolResultBlock { content, tool_use_id, type }

content: BetaCodeExecutionToolResultBlockContent

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

Accepts one of the following:

BetaCodeExecutionToolResultError { error_code, type }

error_code: BetaCodeExecutionToolResultErrorCode

Accepts one of the following:

"invalid_tool_input"

"unavailable"

"too_many_requests"

"execution_time_exceeded"

type: "code_execution_tool_result_error"

BetaCodeExecutionResultBlock { content, return_code, stderr, 2 more }

content: Array<BetaCodeExecutionOutputBlock { file_id, type } >

file_id: string

type: "code_execution_output"

return_code: number

stderr: string

stdout: string

type: "code_execution_result"

BetaEncryptedCodeExecutionResultBlock { content, encrypted_stdout, return_code, 2 more }

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

content: Array<BetaCodeExecutionOutputBlock { file_id, type } >

file_id: string

type: "code_execution_output"

encrypted_stdout: string

return_code: number

stderr: string

type: "encrypted_code_execution_result"

tool_use_id: string

type: "code_execution_tool_result"

BetaCodeExecutionToolResultBlockContent = BetaCodeExecutionToolResultError { error_code, type } | BetaCodeExecutionResultBlock { content, return_code, stderr, 2 more } | BetaEncryptedCodeExecutionResultBlock { content, encrypted_stdout, return_code, 2 more }

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

Accepts one of the following:

BetaCodeExecutionToolResultError { error_code, type }

error_code: BetaCodeExecutionToolResultErrorCode

Accepts one of the following:

"invalid_tool_input"

"unavailable"

"too_many_requests"

"execution_time_exceeded"

type: "code_execution_tool_result_error"

BetaCodeExecutionResultBlock { content, return_code, stderr, 2 more }

content: Array<BetaCodeExecutionOutputBlock { file_id, type } >

file_id: string

type: "code_execution_output"

return_code: number

stderr: string

stdout: string

type: "code_execution_result"

BetaEncryptedCodeExecutionResultBlock { content, encrypted_stdout, return_code, 2 more }

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

content: Array<BetaCodeExecutionOutputBlock { file_id, type } >

file_id: string

type: "code_execution_output"

encrypted_stdout: string

return_code: number

stderr: string

type: "encrypted_code_execution_result"

BetaCodeExecutionToolResultBlockParam { content, tool_use_id, type, cache_control }

content: BetaCodeExecutionToolResultBlockParamContent

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

Accepts one of the following:

BetaCodeExecutionToolResultErrorParam { error_code, type }

error_code: BetaCodeExecutionToolResultErrorCode

Accepts one of the following:

"invalid_tool_input"

"unavailable"

"too_many_requests"

"execution_time_exceeded"

type: "code_execution_tool_result_error"

BetaCodeExecutionResultBlockParam { content, return_code, stderr, 2 more }

content: Array<BetaCodeExecutionOutputBlockParam { file_id, type } >

file_id: string

type: "code_execution_output"

return_code: number

stderr: string

stdout: string

type: "code_execution_result"

BetaEncryptedCodeExecutionResultBlockParam { content, encrypted_stdout, return_code, 2 more }

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

content: Array<BetaCodeExecutionOutputBlockParam { file_id, type } >

file_id: string

type: "code_execution_output"

encrypted_stdout: string

return_code: number

stderr: string

type: "encrypted_code_execution_result"

tool_use_id: string

type: "code_execution_tool_result"

cache_control?: BetaCacheControlEphemeral { type, ttl } | null

Create a cache control breakpoint at this content block.

type: "ephemeral"

ttl?: "5m" | "1h"

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

This may be one the following values:

5m: 5 minutes
1h: 1 hour

Defaults to 5m.

Accepts one of the following:

"5m"

"1h"

BetaCodeExecutionToolResultBlockParamContent = BetaCodeExecutionToolResultErrorParam { error_code, type } | BetaCodeExecutionResultBlockParam { content, return_code, stderr, 2 more } | BetaEncryptedCodeExecutionResultBlockParam { content, encrypted_stdout, return_code, 2 more }

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

Accepts one of the following:

BetaCodeExecutionToolResultErrorParam { error_code, type }

error_code: BetaCodeExecutionToolResultErrorCode

Accepts one of the following:

"invalid_tool_input"

"unavailable"

"too_many_requests"

"execution_time_exceeded"

type: "code_execution_tool_result_error"

BetaCodeExecutionResultBlockParam { content, return_code, stderr, 2 more }

content: Array<BetaCodeExecutionOutputBlockParam { file_id, type } >

file_id: string

type: "code_execution_output"

return_code: number

stderr: string

stdout: string

type: "code_execution_result"

BetaEncryptedCodeExecutionResultBlockParam { content, encrypted_stdout, return_code, 2 more }

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

content: Array<BetaCodeExecutionOutputBlockParam { file_id, type } >

file_id: string

type: "code_execution_output"

encrypted_stdout: string

return_code: number

stderr: string

type: "encrypted_code_execution_result"

BetaCodeExecutionToolResultError { error_code, type }

error_code: BetaCodeExecutionToolResultErrorCode

Accepts one of the following:

"invalid_tool_input"

"unavailable"

"too_many_requests"

"execution_time_exceeded"

type: "code_execution_tool_result_error"

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

Accepts one of the following:

"invalid_tool_input"

"unavailable"

"too_many_requests"

"execution_time_exceeded"

BetaCodeExecutionToolResultErrorParam { error_code, type }

error_code: BetaCodeExecutionToolResultErrorCode

Accepts one of the following:

"invalid_tool_input"

"unavailable"

"too_many_requests"

"execution_time_exceeded"

type: "code_execution_tool_result_error"

BetaCompact20260112Edit { type, instructions, pause_after_compaction, trigger }

Automatically compact older context when reaching the configured trigger threshold.

type: "compact_20260112"

instructions?: string | null

Additional instructions for summarization.

pause_after_compaction?: boolean

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

trigger?: BetaInputTokensTrigger { type, value } | null

When to trigger compaction. Defaults to 150000 input tokens.

type: "input_tokens"

value: number

BetaCompactionBlock { content, type }

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.

content: string | null

Summary of compacted content, or null if compaction failed

type: "compaction"

BetaCompactionBlockParam { content, type, cache_control }

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.

content: string | null

Summary of previously compacted content, or null if compaction failed

type: "compaction"

cache_control?: BetaCacheControlEphemeral { type, ttl } | null

Create a cache control breakpoint at this content block.

type: "ephemeral"

ttl?: "5m" | "1h"

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

This may be one the following values:

5m: 5 minutes
1h: 1 hour

Defaults to 5m.

Accepts one of the following:

"5m"

"1h"

BetaCompactionContentBlockDelta { content, type }

content: string | null

type: "compaction_delta"

BetaCompactionIterationUsage { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }

Token usage for a compaction iteration.

cache_creation: BetaCacheCreation { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens } | null

Breakdown of cached tokens by TTL

ephemeral_1h_input_tokens: number

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

ephemeral_5m_input_tokens: number

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

cache_creation_input_tokens: number

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

cache_read_input_tokens: number

The number of input tokens read from the cache.

input_tokens: number

The number of input tokens which were used.

output_tokens: number

The number of output tokens which were used.

type: "compaction"

Usage for a compaction iteration

BetaContainer { id, expires_at, skills }

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

id: string

Identifier for the container used in this request

expires_at: string

The time at which the container will expire.

skills: Array<BetaSkill { skill_id, type, version } > | null

Skills loaded in the container

skill_id: string

Skill ID

type: "anthropic" | "custom"

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

Accepts one of the following:

"anthropic"

"custom"

version: string

Skill version or 'latest' for most recent version

BetaContainerParams { id, skills }

Container parameters with skills to be loaded.

id?: string | null

Container id

skills?: Array<BetaSkillParams { skill_id, type, version } > | null

List of skills to load in the container

skill_id: string

Skill ID

type: "anthropic" | "custom"

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

Accepts one of the following:

"anthropic"

"custom"

version?: string

Skill version or 'latest' for most recent version

BetaContainerUploadBlock { file_id, type }

Response model for a file uploaded to the container.

file_id: string

type: "container_upload"

BetaContainerUploadBlockParam { file_id, type, cache_control }

A content block that represents a file to be uploaded to the container Files uploaded via this block will be available in the container's input directory.

file_id: string

type: "container_upload"

cache_control?: BetaCacheControlEphemeral { type, ttl } | null

Create a cache control breakpoint at this content block.

type: "ephemeral"

ttl?: "5m" | "1h"

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

This may be one the following values:

5m: 5 minutes
1h: 1 hour

Defaults to 5m.

Accepts one of the following:

"5m"

"1h"

BetaContentBlock = BetaTextBlock { citations, text, type } | BetaThinkingBlock { signature, thinking, type } | BetaRedactedThinkingBlock { data, type } | 12 more

Response model for a file uploaded to the container.

Accepts one of the following:

BetaTextBlock { citations, text, type }

citations: Array<BetaTextCitation> | null

Citations supporting the text block.

The type of citation returned will depend on the type of document being cited. Citing a PDF results in page_location, plain text results in char_location, and content document results in content_block_location.

Accepts one of the following:

BetaCitationCharLocation { cited_text, document_index, document_title, 4 more }

cited_text: string

document_index: number

document_title: string | null

end_char_index: number

file_id: string | null

start_char_index: number

type: "char_location"

BetaCitationPageLocation { cited_text, document_index, document_title, 4 more }

cited_text: string

document_index: number

document_title: string | null

end_page_number: number

file_id: string | null

start_page_number: number

type: "page_location"

BetaCitationContentBlockLocation { cited_text, document_index, document_title, 4 more }

cited_text: string

document_index: number

document_title: string | null

end_block_index: number

file_id: string | null

start_block_index: number

type: "content_block_location"

BetaCitationsWebSearchResultLocation { cited_text, encrypted_index, title, 2 more }

cited_text: string

encrypted_index: string

title: string | null

type: "web_search_result_location"

url: string

BetaCitationSearchResultLocation { cited_text, end_block_index, search_result_index, 4 more }

cited_text: string

end_block_index: number

search_result_index: number

source: string

start_block_index: number

title: string | null

type: "search_result_location"

text: string

type: "text"

BetaThinkingBlock { signature, thinking, type }

signature: string

thinking: string

type: "thinking"

BetaRedactedThinkingBlock { data, type }

data: string

type: "redacted_thinking"

BetaToolUseBlock { id, input, name, 2 more }

id: string

input: Record<string, unknown>

type: "tool_use"

caller?: BetaDirectCaller { type } | BetaServerToolCaller { tool_id, type } | BetaServerToolCaller20260120 { tool_id, type }

Tool invocation directly from the model.

Accepts one of the following:

BetaDirectCaller { type }

Tool invocation directly from the model.

type: "direct"

BetaServerToolCaller { tool_id, type }

Tool invocation generated by a server-side tool.

tool_id: string

type: "code_execution_20250825"

BetaServerToolCaller20260120 { tool_id, type }

tool_id: string

type: "code_execution_20260120"

BetaServerToolUseBlock { id, input, name, 2 more }

id: string

input: Record<string, unknown>

Accepts one of the following:

"web_search"

"web_fetch"

"code_execution"

"bash_code_execution"

"text_editor_code_execution"

"tool_search_tool_regex"

"tool_search_tool_bm25"

type: "server_tool_use"

caller?: BetaDirectCaller { type } | BetaServerToolCaller { tool_id, type } | BetaServerToolCaller20260120 { tool_id, type }

Tool invocation directly from the model.

Accepts one of the following:

BetaDirectCaller { type }

Tool invocation directly from the model.

type: "direct"

BetaServerToolCaller { tool_id, type }

Tool invocation generated by a server-side tool.

tool_id: string

type: "code_execution_20250825"

BetaServerToolCaller20260120 { tool_id, type }

tool_id: string

type: "code_execution_20260120"

BetaWebSearchToolResultBlock { content, tool_use_id, type, caller }

content: BetaWebSearchToolResultBlockContent

Accepts one of the following:

BetaWebSearchToolResultError { error_code, type }

error_code: BetaWebSearchToolResultErrorCode

Accepts one of the following:

"invalid_tool_input"

"unavailable"

"max_uses_exceeded"

"too_many_requests"

"query_too_long"

"request_too_large"

type: "web_search_tool_result_error"

Array<BetaWebSearchResultBlock { encrypted_content, page_age, title, 2 more } >

encrypted_content: string

page_age: string | null

title: string

type: "web_search_result"

url: string

tool_use_id: string

type: "web_search_tool_result"

caller?: BetaDirectCaller { type } | BetaServerToolCaller { tool_id, type } | BetaServerToolCaller20260120 { tool_id, type }

Tool invocation directly from the model.

Accepts one of the following:

BetaDirectCaller { type }

Tool invocation directly from the model.

type: "direct"

BetaServerToolCaller { tool_id, type }

Tool invocation generated by a server-side tool.

tool_id: string

type: "code_execution_20250825"

BetaServerToolCaller20260120 { tool_id, type }

tool_id: string

type: "code_execution_20260120"

BetaWebFetchToolResultBlock { content, tool_use_id, type, caller }

content: BetaWebFetchToolResultErrorBlock { error_code, type } | BetaWebFetchBlock { content, retrieved_at, type, url }

Accepts one of the following:

BetaWebFetchToolResultErrorBlock { error_code, type }

error_code: BetaWebFetchToolResultErrorCode

Accepts one of the following:

"invalid_tool_input"

"url_too_long"

"url_not_allowed"

"url_not_accessible"

"unsupported_content_type"

"too_many_requests"

"max_uses_exceeded"

"unavailable"

type: "web_fetch_tool_result_error"

BetaWebFetchBlock { content, retrieved_at, type, url }

content: BetaDocumentBlock { citations, source, title, type }

citations: BetaCitationConfig { enabled } | null

Citation configuration for the document

enabled: boolean

source: BetaBase64PDFSource { data, media_type, type } | BetaPlainTextSource { data, media_type, type }

Accepts one of the following:

BetaBase64PDFSource { data, media_type, type }

data: string

media_type: "application/pdf"

type: "base64"

BetaPlainTextSource { data, media_type, type }

data: string

media_type: "text/plain"

type: "text"

title: string | null

The title of the document

type: "document"

retrieved_at: string | null

ISO 8601 timestamp when the content was retrieved

type: "web_fetch_result"

url: string

Fetched content URL

tool_use_id: string

type: "web_fetch_tool_result"

caller?: BetaDirectCaller { type } | BetaServerToolCaller { tool_id, type } | BetaServerToolCaller20260120 { tool_id, type }

Tool invocation directly from the model.

Accepts one of the following:

BetaDirectCaller { type }

Tool invocation directly from the model.

type: "direct"

BetaServerToolCaller { tool_id, type }

Tool invocation generated by a server-side tool.

tool_id: string

type: "code_execution_20250825"

BetaServerToolCaller20260120 { tool_id, type }

tool_id: string

type: "code_execution_20260120"

BetaCodeExecutionToolResultBlock { content, tool_use_id, type }

content: BetaCodeExecutionToolResultBlockContent

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

Accepts one of the following:

BetaCodeExecutionToolResultError { error_code, type }

error_code: BetaCodeExecutionToolResultErrorCode

Accepts one of the following:

"invalid_tool_input"

"unavailable"

"too_many_requests"

"execution_time_exceeded"

type: "code_execution_tool_result_error"

BetaCodeExecutionResultBlock { content, return_code, stderr, 2 more }

content: Array<BetaCodeExecutionOutputBlock { file_id, type } >

file_id: string

type: "code_execution_output"

return_code: number

stderr: string

stdout: string

type: "code_execution_result"

BetaEncryptedCodeExecutionResultBlock { content, encrypted_stdout, return_code, 2 more }

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

content: Array<BetaCodeExecutionOutputBlock { file_id, type } >

file_id: string

type: "code_execution_output"

encrypted_stdout: string

return_code: number

stderr: string

type: "encrypted_code_execution_result"

tool_use_id: string

type: "code_execution_tool_result"

BetaBashCodeExecutionToolResultBlock { content, tool_use_id, type }

content: BetaBashCodeExecutionToolResultError { error_code, type } | BetaBashCodeExecutionResultBlock { content, return_code, stderr, 2 more }

Accepts one of the following:

BetaBashCodeExecutionToolResultError { error_code, type }

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

Accepts one of the following:

"invalid_tool_input"

"unavailable"

"too_many_requests"

"execution_time_exceeded"

"output_file_too_large"

type: "bash_code_execution_tool_result_error"

BetaBashCodeExecutionResultBlock { content, return_code, stderr, 2 more }

content: Array<BetaBashCodeExecutionOutputBlock { file_id, type } >

file_id: string

type: "bash_code_execution_output"

return_code: number

stderr: string

stdout: string

type: "bash_code_execution_result"

tool_use_id: string

type: "bash_code_execution_tool_result"

BetaTextEditorCodeExecutionToolResultBlock { content, tool_use_id, type }

content: BetaTextEditorCodeExecutionToolResultError { error_code, error_message, type } | BetaTextEditorCodeExecutionViewResultBlock { content, file_type, num_lines, 3 more } | BetaTextEditorCodeExecutionCreateResultBlock { is_file_update, type } | BetaTextEditorCodeExecutionStrReplaceResultBlock { lines, new_lines, new_start, 3 more }

Accepts one of the following:

BetaTextEditorCodeExecutionToolResultError { error_code, error_message, type }

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

Accepts one of the following:

"invalid_tool_input"

"unavailable"

"too_many_requests"

"execution_time_exceeded"

"file_not_found"

error_message: string | null

type: "text_editor_code_execution_tool_result_error"

BetaTextEditorCodeExecutionViewResultBlock { content, file_type, num_lines, 3 more }

content: string

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

Accepts one of the following:

"text"

"image"

"pdf"

num_lines: number | null

start_line: number | null

total_lines: number | null

type: "text_editor_code_execution_view_result"

BetaTextEditorCodeExecutionCreateResultBlock { is_file_update, type }

is_file_update: boolean

type: "text_editor_code_execution_create_result"

BetaTextEditorCodeExecutionStrReplaceResultBlock { lines, new_lines, new_start, 3 more }

lines: Array<string> | null

new_lines: number | null

new_start: number | null

old_lines: number | null

old_start: number | null

type: "text_editor_code_execution_str_replace_result"

tool_use_id: string

type: "text_editor_code_execution_tool_result"

BetaToolSearchToolResultBlock { content, tool_use_id, type }

content: BetaToolSearchToolResultError { error_code, error_message, type } | BetaToolSearchToolSearchResultBlock { tool_references, type }

Accepts one of the following:

BetaToolSearchToolResultError { error_code, error_message, type }

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

Accepts one of the following:

"invalid_tool_input"

"unavailable"

"too_many_requests"

"execution_time_exceeded"

error_message: string | null

type: "tool_search_tool_result_error"

BetaToolSearchToolSearchResultBlock { tool_references, type }

tool_references: Array<BetaToolReferenceBlock { tool_name, type } >

tool_name: string

type: "tool_reference"

type: "tool_search_tool_search_result"

tool_use_id: string

type: "tool_search_tool_result"

BetaMCPToolUseBlock { id, input, name, 2 more }

id: string

input: Record<string, unknown>

The name of the MCP tool

server_name: string

The name of the MCP server

type: "mcp_tool_use"

BetaMCPToolResultBlock { content, is_error, tool_use_id, type }

content: string | Array<BetaTextBlock { citations, text, type } >

Accepts one of the following:

string

Array<BetaTextBlock { citations, text, type } >

citations: Array<BetaTextCitation> | null

Citations supporting the text block.

Accepts one of the following:

BetaCitationCharLocation { cited_text, document_index, document_title, 4 more }

cited_text: string

document_index: number

document_title: string | null

end_char_index: number

file_id: string | null

start_char_index: number

type: "char_location"

BetaCitationPageLocation { cited_text, document_index, document_title, 4 more }

cited_text: string

document_index: number

document_title: string | null

end_page_number: number

file_id: string | null

start_page_number: number

type: "page_location"

BetaCitationContentBlockLocation { cited_text, document_index, document_title, 4 more }

cited_text: string

document_index: number

document_title: string | null

end_block_index: number

file_id: string | null

start_block_index: number

type: "content_block_location"

BetaCitationsWebSearchResultLocation { cited_text, encrypted_index, title, 2 more }

cited_text: string

encrypted_index: string

title: string | null

type: "web_search_result_location"

url: string

BetaCitationSearchResultLocation { cited_text, end_block_index, search_result_index, 4 more }

cited_text: string

end_block_index: number

search_result_index: number

source: string

start_block_index: number

title: string | null

type: "search_result_location"

text: string

type: "text"

is_error: boolean

tool_use_id: string

type: "mcp_tool_result"

BetaContainerUploadBlock { file_id, type }

Response model for a file uploaded to the container.

file_id: string

type: "container_upload"

BetaCompactionBlock { content, type }

A compaction block returned when autocompact is triggered.

content: string | null

Summary of compacted content, or null if compaction failed

type: "compaction"

BetaContentBlockParam = BetaTextBlockParam { text, type, cache_control, citations } | BetaImageBlockParam { source, type, cache_control } | BetaRequestDocumentBlock { source, type, cache_control, 3 more } | 16 more

Regular text content.

Accepts one of the following:

BetaTextBlockParam { text, type, cache_control, citations }

text: string

type: "text"

cache_control?: BetaCacheControlEphemeral { type, ttl } | null

Create a cache control breakpoint at this content block.

type: "ephemeral"

ttl?: "5m" | "1h"

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

This may be one the following values:

5m: 5 minutes
1h: 1 hour

Defaults to 5m.

Accepts one of the following:

"5m"

"1h"

citations?: Array<BetaTextCitationParam> | null

Accepts one of the following:

BetaCitationCharLocationParam { cited_text, document_index, document_title, 3 more }

cited_text: string

document_index: number

document_title: string | null

end_char_index: number

start_char_index: number

type: "char_location"

BetaCitationPageLocationParam { cited_text, document_index, document_title, 3 more }

cited_text: string

document_index: number

document_title: string | null

end_page_number: number

start_page_number: number

type: "page_location"

BetaCitationContentBlockLocationParam { cited_text, document_index, document_title, 3 more }

cited_text: string

document_index: number

document_title: string | null

end_block_index: number

start_block_index: number

type: "content_block_location"

BetaCitationWebSearchResultLocationParam { cited_text, encrypted_index, title, 2 more }

cited_text: string

encrypted_index: string

title: string | null

type: "web_search_result_location"

url: string

BetaCitationSearchResultLocationParam { cited_text, end_block_index, search_result_index, 4 more }

cited_text: string

end_block_index: number

search_result_index: number

source: string

start_block_index: number

title: string | null

type: "search_result_location"

BetaImageBlockParam { source, type, cache_control }

source: BetaBase64ImageSource { data, media_type, type } | BetaURLImageSource { type, url } | BetaFileImageSource { file_id, type }

Accepts one of the following:

BetaBase64ImageSource { data, media_type, type }

data: string

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

Accepts one of the following:

"image/jpeg"

"image/png"

"image/gif"

"image/webp"

type: "base64"

BetaURLImageSource { type, url }

type: "url"

url: string

BetaFileImageSource { file_id, type }

file_id: string

type: "file"

type: "image"

cache_control?: BetaCacheControlEphemeral { type, ttl } | null

Create a cache control breakpoint at this content block.

type: "ephemeral"

ttl?: "5m" | "1h"

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

This may be one the following values:

5m: 5 minutes
1h: 1 hour

Defaults to 5m.

Accepts one of the following:

"5m"

"1h"

BetaRequestDocumentBlock { source, type, cache_control, 3 more }

source: BetaBase64PDFSource { data, media_type, type } | BetaPlainTextSource { data, media_type, type } | BetaContentBlockSource { content, type } | 2 more

Accepts one of the following:

BetaBase64PDFSource { data, media_type, type }

data: string

media_type: "application/pdf"

type: "base64"

BetaPlainTextSource { data, media_type, type }

data: string

media_type: "text/plain"

type: "text"

BetaContentBlockSource { content, type }

content: string | Array<BetaContentBlockSourceContent>

Accepts one of the following:

string

Array<BetaContentBlockSourceContent>

BetaTextBlockParam { text, type, cache_control, citations }

text: string

type: "text"

cache_control?: BetaCacheControlEphemeral { type, ttl } | null

Create a cache control breakpoint at this content block.

type: "ephemeral"

ttl?: "5m" | "1h"

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

This may be one the following values:

5m: 5 minutes
1h: 1 hour

Defaults to 5m.

Accepts one of the following:

"5m"

"1h"

citations?: Array<BetaTextCitationParam> | null

Accepts one of the following:

BetaCitationCharLocationParam { cited_text, document_index, document_title, 3 more }

cited_text: string

document_index: number

document_title: string | null

end_char_index: number

start_char_index: number

type: "char_location"

BetaCitationPageLocationParam { cited_text, document_index, document_title, 3 more }

cited_text: string

document_index: number

document_title: string | null

end_page_number: number

start_page_number: number

type: "page_location"

BetaCitationContentBlockLocationParam { cited_text, document_index, document_title, 3 more }

cited_text: string

document_index: number

document_title: string | null

end_block_index: number

start_block_index: number

type: "content_block_location"

BetaCitationWebSearchResultLocationParam { cited_text, encrypted_index, title, 2 more }

cited_text: string

encrypted_index: string

title: string | null

type: "web_search_result_location"

url: string

BetaCitationSearchResultLocationParam { cited_text, end_block_index, search_result_index, 4 more }

cited_text: string

end_block_index: number

search_result_index: number

source: string

start_block_index: number

title: string | null

type: "search_result_location"

BetaImageBlockParam { source, type, cache_control }

source: BetaBase64ImageSource { data, media_type, type } | BetaURLImageSource { type, url } | BetaFileImageSource { file_id, type }

Accepts one of the following:

BetaBase64ImageSource { data, media_type, type }

data: string

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

Accepts one of the following:

"image/jpeg"

"image/png"

"image/gif"

"image/webp"

type: "base64"

BetaURLImageSource { type, url }

type: "url"

url: string

BetaFileImageSource { file_id, type }

file_id: string

type: "file"

type: "image"

cache_control?: BetaCacheControlEphemeral { type, ttl } | null

Create a cache control breakpoint at this content block.

type: "ephemeral"

ttl?: "5m" | "1h"

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

This may be one the following values:

5m: 5 minutes
1h: 1 hour

Defaults to 5m.

Accepts one of the following:

"5m"

"1h"

type: "content"

BetaURLPDFSource { type, url }

type: "url"

url: string

BetaFileDocumentSource { file_id, type }

file_id: string

type: "file"

type: "document"

cache_control?: BetaCacheControlEphemeral { type, ttl } | null

Create a cache control breakpoint at this content block.

type: "ephemeral"

ttl?: "5m" | "1h"

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

This may be one the following values:

5m: 5 minutes
1h: 1 hour

Defaults to 5m.

Accepts one of the following:

"5m"

"1h"

citations?: BetaCitationsConfigParam { enabled } | null

enabled?: boolean

context?: string | null

title?: string | null

BetaSearchResultBlockParam { content, source, title, 3 more }

content: Array<BetaTextBlockParam { text, type, cache_control, citations } >

text: string

type: "text"

cache_control?: BetaCacheControlEphemeral { type, ttl } | null

Create a cache control breakpoint at this content block.

type: "ephemeral"

ttl?: "5m" | "1h"

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

This may be one the following values:

5m: 5 minutes
1h: 1 hour

Defaults to 5m.

Accepts one of the following:

"5m"

"1h"

citations?: Array<BetaTextCitationParam> | null

Accepts one of the following:

BetaCitationCharLocationParam { cited_text, document_index, document_title, 3 more }

cited_text: string

document_index: number

document_title: string | null

end_char_index: number

start_char_index: number

type: "char_location"

BetaCitationPageLocationParam { cited_text, document_index, document_title, 3 more }

cited_text: string

document_index: number

document_title: string | null

end_page_number: number

start_page_number: number

type: "page_location"

BetaCitationContentBlockLocationParam { cited_text, document_index, document_title, 3 more }

cited_text: string

document_index: number

document_title: string | null

end_block_index: number

start_block_index: number

type: "content_block_location"

BetaCitationWebSearchResultLocationParam { cited_text, encrypted_index, title, 2 more }

cited_text: string

encrypted_index: string

title: string | null

type: "web_search_result_location"

url: string

BetaCitationSearchResultLocationParam { cited_text, end_block_index, search_result_index, 4 more }

cited_text: string

end_block_index: number

search_result_index: number

source: string

start_block_index: number

title: string | null

type: "search_result_location"

source: string

title: string

type: "search_result"

cache_control?: BetaCacheControlEphemeral { type, ttl } | null

Create a cache control breakpoint at this content block.

type: "ephemeral"

ttl?: "5m" | "1h"

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

This may be one the following values:

5m: 5 minutes
1h: 1 hour

Defaults to 5m.

Accepts one of the following:

"5m"

"1h"

citations?: BetaCitationsConfigParam { enabled }

enabled?: boolean

BetaThinkingBlockParam { signature, thinking, type }

signature: string

thinking: string

type: "thinking"

BetaRedactedThinkingBlockParam { data, type }

data: string

type: "redacted_thinking"

BetaToolUseBlockParam { id, input, name, 3 more }

id: string

input: Record<string, unknown>

type: "tool_use"

cache_control?: BetaCacheControlEphemeral { type, ttl } | null

Create a cache control breakpoint at this content block.

type: "ephemeral"

ttl?: "5m" | "1h"

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

This may be one the following values:

5m: 5 minutes
1h: 1 hour

Defaults to 5m.

Accepts one of the following:

"5m"

"1h"

caller?: BetaDirectCaller { type } | BetaServerToolCaller { tool_id, type } | BetaServerToolCaller20260120 { tool_id, type }

Tool invocation directly from the model.

Accepts one of the following:

BetaDirectCaller { type }

Tool invocation directly from the model.

type: "direct"

BetaServerToolCaller { tool_id, type }

Tool invocation generated by a server-side tool.

tool_id: string

type: "code_execution_20250825"

BetaServerToolCaller20260120 { tool_id, type }

tool_id: string

type: "code_execution_20260120"

BetaToolResultBlockParam { tool_use_id, type, cache_control, 2 more }

tool_use_id: string

type: "tool_result"

cache_control?: BetaCacheControlEphemeral { type, ttl } | null

Create a cache control breakpoint at this content block.

type: "ephemeral"

ttl?: "5m" | "1h"

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

This may be one the following values:

5m: 5 minutes
1h: 1 hour

Defaults to 5m.

Accepts one of the following:

"5m"

"1h"

content?: string | Array<BetaTextBlockParam { text, type, cache_control, citations } | BetaImageBlockParam { source, type, cache_control } | BetaSearchResultBlockParam { content, source, title, 3 more } | 2 more>

Accepts one of the following:

string

Array<BetaTextBlockParam { text, type, cache_control, citations } | BetaImageBlockParam { source, type, cache_control } | BetaSearchResultBlockParam { content, source, title, 3 more } | 2 more>

BetaTextBlockParam { text, type, cache_control, citations }

text: string

type: "text"

cache_control?: BetaCacheControlEphemeral { type, ttl } | null

Create a cache control breakpoint at this content block.

type: "ephemeral"

ttl?: "5m" | "1h"

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

This may be one the following values:

5m: 5 minutes
1h: 1 hour

Defaults to 5m.

Accepts one of the following:

"5m"

"1h"

citations?: Array<BetaTextCitationParam> | null

Accepts one of the following:

BetaCitationCharLocationParam { cited_text, document_index, document_title, 3 more }

cited_text: string

document_index: number

document_title: string | null

end_char_index: number

start_char_index: number

type: "char_location"

BetaCitationPageLocationParam { cited_text, document_index, document_title, 3 more }

cited_text: string

document_index: number

document_title: string | null

end_page_number: number

start_page_number: number

type: "page_location"

BetaCitationContentBlockLocationParam { cited_text, document_index, document_title, 3 more }

cited_text: string

document_index: number

document_title: string | null

end_block_index: number

start_block_index: number

type: "content_block_location"

BetaCitationWebSearchResultLocationParam { cited_text, encrypted_index, title, 2 more }

cited_text: string

encrypted_index: string

title: string | null

type: "web_search_result_location"

url: string

BetaCitationSearchResultLocationParam { cited_text, end_block_index, search_result_index, 4 more }

cited_text: string

end_block_index: number

search_result_index: number

source: string

start_block_index: number

title: string | null

type: "search_result_location"

BetaImageBlockParam { source, type, cache_control }

source: BetaBase64ImageSource { data, media_type, type } | BetaURLImageSource { type, url } | BetaFileImageSource { file_id, type }

Accepts one of the following:

BetaBase64ImageSource { data, media_type, type }

data: string

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

Accepts one of the following:

"image/jpeg"

"image/png"

"image/gif"

"image/webp"

type: "base64"

BetaURLImageSource { type, url }

type: "url"

url: string

BetaFileImageSource { file_id, type }

file_id: string

type: "file"

type: "image"

cache_control?: BetaCacheControlEphemeral { type, ttl } | null

Create a cache control breakpoint at this content block.

type: "ephemeral"

ttl?: "5m" | "1h"

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

This may be one the following values:

5m: 5 minutes
1h: 1 hour

Defaults to 5m.

Accepts one of the following:

"5m"

"1h"

BetaSearchResultBlockParam { content, source, title, 3 more }

content: Array<BetaTextBlockParam { text, type, cache_control, citations } >

text: string

type: "text"

cache_control?: BetaCacheControlEphemeral { type, ttl } | null

Create a cache control breakpoint at this content block.

type: "ephemeral"

ttl?: "5m" | "1h"

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

This may be one the following values:

5m: 5 minutes
1h: 1 hour

Defaults to 5m.

Accepts one of the following:

"5m"

"1h"

citations?: Array<BetaTextCitationParam> | null

Accepts one of the following:

BetaCitationCharLocationParam { cited_text, document_index, document_title, 3 more }

cited_text: string

document_index: number

document_title: string | null

end_char_index: number

start_char_index: number

type: "char_location"

BetaCitationPageLocationParam { cited_text, document_index, document_title, 3 more }

cited_text: string

document_index: number

document_title: string | null

end_page_number: number

start_page_number: number

type: "page_location"

BetaCitationContentBlockLocationParam { cited_text, document_index, document_title, 3 more }

cited_text: string

document_index: number

document_title: string | null

end_block_index: number

start_block_index: number

type: "content_block_location"

BetaCitationWebSearchResultLocationParam { cited_text, encrypted_index, title, 2 more }

cited_text: string

encrypted_index: string

title: string | null

type: "web_search_result_location"

url: string

BetaCitationSearchResultLocationParam { cited_text, end_block_index, search_result_index, 4 more }

cited_text: string

end_block_index: number

search_result_index: number

source: string

start_block_index: number

title: string | null

type: "search_result_location"

source: string

title: string

type: "search_result"

cache_control?: BetaCacheControlEphemeral { type, ttl } | null

Create a cache control breakpoint at this content block.

type: "ephemeral"

ttl?: "5m" | "1h"

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

This may be one the following values:

5m: 5 minutes
1h: 1 hour

Defaults to 5m.

Accepts one of the following:

"5m"

"1h"

citations?: BetaCitationsConfigParam { enabled }

enabled?: boolean

BetaRequestDocumentBlock { source, type, cache_control, 3 more }

source: BetaBase64PDFSource { data, media_type, type } | BetaPlainTextSource { data, media_type, type } | BetaContentBlockSource { content, type } | 2 more

Accepts one of the following:

BetaBase64PDFSource { data, media_type, type }

data: string

media_type: "application/pdf"

type: "base64"

BetaPlainTextSource { data, media_type, type }

data: string

media_type: "text/plain"

type: "text"

BetaContentBlockSource { content, type }

content: string | Array<BetaContentBlockSourceContent>

Accepts one of the following:

string

Array<BetaContentBlockSourceContent>

BetaTextBlockParam { text, type, cache_control, citations }

text: string

type: "text"

cache_control?: BetaCacheControlEphemeral { type, ttl } | null

Create a cache control breakpoint at this content block.

type: "ephemeral"

ttl?: "5m" | "1h"

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

This may be one the following values:

5m: 5 minutes
1h: 1 hour

Defaults to 5m.

Accepts one of the following:

"5m"

"1h"

citations?: Array<BetaTextCitationParam> | null

Accepts one of the following:

BetaCitationCharLocationParam { cited_text, document_index, document_title, 3 more }

cited_text: string

document_index: number

document_title: string | null

end_char_index: number

start_char_index: number

type: "char_location"

BetaCitationPageLocationParam { cited_text, document_index, document_title, 3 more }

cited_text: string

document_index: number

document_title: string | null

end_page_number: number

start_page_number: number

type: "page_location"

BetaCitationContentBlockLocationParam { cited_text, document_index, document_title, 3 more }

cited_text: string

document_index: number

document_title: string | null

end_block_index: number

start_block_index: number

type: "content_block_location"

BetaCitationWebSearchResultLocationParam { cited_text, encrypted_index, title, 2 more }

cited_text: string

encrypted_index: string

title: string | null

type: "web_search_result_location"

url: string

BetaCitationSearchResultLocationParam { cited_text, end_block_index, search_result_index, 4 more }

cited_text: string

end_block_index: number

search_result_index: number

source: string

start_block_index: number

title: string | null

type: "search_result_location"

BetaImageBlockParam { source, type, cache_control }

source: BetaBase64ImageSource { data, media_type, type } | BetaURLImageSource { type, url } | BetaFileImageSource { file_id, type }

Accepts one of the following:

BetaBase64ImageSource { data, media_type, type }

data: string

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

Accepts one of the following:

"image/jpeg"

"image/png"

"image/gif"

"image/webp"

type: "base64"

BetaURLImageSource { type, url }

type: "url"

url: string

BetaFileImageSource { file_id, type }

file_id: string

type: "file"

type: "image"

cache_control?: BetaCacheControlEphemeral { type, ttl } | null

Create a cache control breakpoint at this content block.

type: "ephemeral"

ttl?: "5m" | "1h"

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

This may be one the following values:

5m: 5 minutes
1h: 1 hour

Defaults to 5m.

Accepts one of the following:

"5m"

"1h"

type: "content"

BetaURLPDFSource { type, url }

type: "url"

url: string

BetaFileDocumentSource { file_id, type }

file_id: string

type: "file"

type: "document"

cache_control?: BetaCacheControlEphemeral { type, ttl } | null

Create a cache control breakpoint at this content block.

type: "ephemeral"

ttl?: "5m" | "1h"

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

This may be one the following values:

5m: 5 minutes
1h: 1 hour

Defaults to 5m.

Accepts one of the following:

"5m"

"1h"

citations?: BetaCitationsConfigParam { enabled } | null

enabled?: boolean

context?: string | null

title?: string | null

BetaToolReferenceBlockParam { tool_name, type, cache_control }

Tool reference block that can be included in tool_result content.

tool_name: string

type: "tool_reference"

cache_control?: BetaCacheControlEphemeral { type, ttl } | null

Create a cache control breakpoint at this content block.

type: "ephemeral"

ttl?: "5m" | "1h"

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

This may be one the following values:

5m: 5 minutes
1h: 1 hour

Defaults to 5m.

Accepts one of the following:

"5m"

"1h"

is_error?: boolean

BetaServerToolUseBlockParam { id, input, name, 3 more }

id: string

input: Record<string, unknown>

Accepts one of the following:

"web_search"

"web_fetch"

"code_execution"

"bash_code_execution"

"text_editor_code_execution"

"tool_search_tool_regex"

"tool_search_tool_bm25"

type: "server_tool_use"

cache_control?: BetaCacheControlEphemeral { type, ttl } | null

Create a cache control breakpoint at this content block.

type: "ephemeral"

ttl?: "5m" | "1h"

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

This may be one the following values:

5m: 5 minutes
1h: 1 hour

Defaults to 5m.

Accepts one of the following:

"5m"

"1h"

caller?: BetaDirectCaller { type } | BetaServerToolCaller { tool_id, type } | BetaServerToolCaller20260120 { tool_id, type }

Tool invocation directly from the model.

Accepts one of the following:

BetaDirectCaller { type }

Tool invocation directly from the model.

type: "direct"

BetaServerToolCaller { tool_id, type }

Tool invocation generated by a server-side tool.

tool_id: string

type: "code_execution_20250825"

BetaServerToolCaller20260120 { tool_id, type }

tool_id: string

type: "code_execution_20260120"

BetaWebSearchToolResultBlockParam { content, tool_use_id, type, 2 more }

content: BetaWebSearchToolResultBlockParamContent

Accepts one of the following:

Array<BetaWebSearchResultBlockParam { encrypted_content, title, type, 2 more } >

encrypted_content: string

title: string

type: "web_search_result"

url: string

page_age?: string | null

BetaWebSearchToolRequestError { error_code, type }

error_code: BetaWebSearchToolResultErrorCode

Accepts one of the following:

"invalid_tool_input"

"unavailable"

"max_uses_exceeded"

"too_many_requests"

"query_too_long"

"request_too_large"

type: "web_search_tool_result_error"

tool_use_id: string

type: "web_search_tool_result"

cache_control?: BetaCacheControlEphemeral { type, ttl } | null

Create a cache control breakpoint at this content block.

type: "ephemeral"

ttl?: "5m" | "1h"

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

This may be one the following values:

5m: 5 minutes
1h: 1 hour

Defaults to 5m.

Accepts one of the following:

"5m"

"1h"

caller?: BetaDirectCaller { type } | BetaServerToolCaller { tool_id, type } | BetaServerToolCaller20260120 { tool_id, type }

Tool invocation directly from the model.

Accepts one of the following:

BetaDirectCaller { type }

Tool invocation directly from the model.

type: "direct"

BetaServerToolCaller { tool_id, type }

Tool invocation generated by a server-side tool.

tool_id: string

type: "code_execution_20250825"

BetaServerToolCaller20260120 { tool_id, type }

tool_id: string

type: "code_execution_20260120"

BetaWebFetchToolResultBlockParam { content, tool_use_id, type, 2 more }

content: BetaWebFetchToolResultErrorBlockParam { error_code, type } | BetaWebFetchBlockParam { content, type, url, retrieved_at }

Accepts one of the following:

BetaWebFetchToolResultErrorBlockParam { error_code, type }

error_code: BetaWebFetchToolResultErrorCode

Accepts one of the following:

"invalid_tool_input"

"url_too_long"

"url_not_allowed"

"url_not_accessible"

"unsupported_content_type"

"too_many_requests"

"max_uses_exceeded"

"unavailable"

type: "web_fetch_tool_result_error"

BetaWebFetchBlockParam { content, type, url, retrieved_at }

content: BetaRequestDocumentBlock { source, type, cache_control, 3 more }

source: BetaBase64PDFSource { data, media_type, type } | BetaPlainTextSource { data, media_type, type } | BetaContentBlockSource { content, type } | 2 more

Accepts one of the following:

BetaBase64PDFSource { data, media_type, type }

data: string

media_type: "application/pdf"

type: "base64"

BetaPlainTextSource { data, media_type, type }

data: string

media_type: "text/plain"

type: "text"

BetaContentBlockSource { content, type }

content: string | Array<BetaContentBlockSourceContent>

Accepts one of the following:

string

Array<BetaContentBlockSourceContent>

BetaTextBlockParam { text, type, cache_control, citations }

text: string

type: "text"

cache_control?: BetaCacheControlEphemeral { type, ttl } | null

Create a cache control breakpoint at this content block.

type: "ephemeral"

ttl?: "5m" | "1h"

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

This may be one the following values:

5m: 5 minutes
1h: 1 hour

Defaults to 5m.

Accepts one of the following:

"5m"

"1h"

citations?: Array<BetaTextCitationParam> | null

Accepts one of the following:

BetaCitationCharLocationParam { cited_text, document_index, document_title, 3 more }

cited_text: string

document_index: number

document_title: string | null

end_char_index: number

start_char_index: number

type: "char_location"

BetaCitationPageLocationParam { cited_text, document_index, document_title, 3 more }

cited_text: string

document_index: number

document_title: string | null

end_page_number: number

start_page_number: number

type: "page_location"

BetaCitationContentBlockLocationParam { cited_text, document_index, document_title, 3 more }

cited_text: string

document_index: number

document_title: string | null

end_block_index: number

start_block_index: number

type: "content_block_location"

BetaCitationWebSearchResultLocationParam { cited_text, encrypted_index, title, 2 more }

cited_text: string

encrypted_index: string

title: string | null

type: "web_search_result_location"

url: string

BetaCitationSearchResultLocationParam { cited_text, end_block_index, search_result_index, 4 more }

cited_text: string

end_block_index: number

search_result_index: number

source: string

start_block_index: number

title: string | null

type: "search_result_location"

BetaImageBlockParam { source, type, cache_control }

source: BetaBase64ImageSource { data, media_type, type } | BetaURLImageSource { type, url } | BetaFileImageSource { file_id, type }

Accepts one of the following:

BetaBase64ImageSource { data, media_type, type }

data: string

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

Accepts one of the following:

"image/jpeg"

"image/png"

"image/gif"

"image/webp"

type: "base64"

BetaURLImageSource { type, url }

type: "url"

url: string

BetaFileImageSource { file_id, type }

file_id: string

type: "file"

type: "image"

cache_control?: BetaCacheControlEphemeral { type, ttl } | null

Create a cache control breakpoint at this content block.

type: "ephemeral"

ttl?: "5m" | "1h"

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

This may be one the following values:

5m: 5 minutes
1h: 1 hour

Defaults to 5m.

Accepts one of the following:

"5m"

"1h"

type: "content"

BetaURLPDFSource { type, url }

type: "url"

url: string

BetaFileDocumentSource { file_id, type }

file_id: string

type: "file"

type: "document"

cache_control?: BetaCacheControlEphemeral { type, ttl } | null

Create a cache control breakpoint at this content block.

type: "ephemeral"

ttl?: "5m" | "1h"

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

This may be one the following values:

5m: 5 minutes
1h: 1 hour

Defaults to 5m.

Accepts one of the following:

"5m"

"1h"

citations?: BetaCitationsConfigParam { enabled } | null

enabled?: boolean

context?: string | null

title?: string | null

type: "web_fetch_result"

url: string

Fetched content URL

retrieved_at?: string | null

ISO 8601 timestamp when the content was retrieved

tool_use_id: string

type: "web_fetch_tool_result"

cache_control?: BetaCacheControlEphemeral { type, ttl } | null

Create a cache control breakpoint at this content block.

type: "ephemeral"

ttl?: "5m" | "1h"

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

This may be one the following values:

5m: 5 minutes
1h: 1 hour

Defaults to 5m.

Accepts one of the following:

"5m"

"1h"

caller?: BetaDirectCaller { type } | BetaServerToolCaller { tool_id, type } | BetaServerToolCaller20260120 { tool_id, type }

Tool invocation directly from the model.

Accepts one of the following:

BetaDirectCaller { type }

Tool invocation directly from the model.

type: "direct"

BetaServerToolCaller { tool_id, type }

Tool invocation generated by a server-side tool.

tool_id: string

type: "code_execution_20250825"

BetaServerToolCaller20260120 { tool_id, type }

tool_id: string

type: "code_execution_20260120"

BetaCodeExecutionToolResultBlockParam { content, tool_use_id, type, cache_control }

content: BetaCodeExecutionToolResultBlockParamContent

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

Accepts one of the following:

BetaCodeExecutionToolResultErrorParam { error_code, type }

error_code: BetaCodeExecutionToolResultErrorCode

Accepts one of the following:

"invalid_tool_input"

"unavailable"

"too_many_requests"

"execution_time_exceeded"

type: "code_execution_tool_result_error"

BetaCodeExecutionResultBlockParam { content, return_code, stderr, 2 more }

content: Array<BetaCodeExecutionOutputBlockParam { file_id, type } >

file_id: string

type: "code_execution_output"

return_code: number

stderr: string

stdout: string

type: "code_execution_result"

BetaEncryptedCodeExecutionResultBlockParam { content, encrypted_stdout, return_code, 2 more }

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

content: Array<BetaCodeExecutionOutputBlockParam { file_id, type } >

file_id: string

type: "code_execution_output"

encrypted_stdout: string

return_code: number

stderr: string

type: "encrypted_code_execution_result"

tool_use_id: string

type: "code_execution_tool_result"

cache_control?: BetaCacheControlEphemeral { type, ttl } | null

Create a cache control breakpoint at this content block.

type: "ephemeral"

ttl?: "5m" | "1h"

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

This may be one the following values:

5m: 5 minutes
1h: 1 hour

Defaults to 5m.

Accepts one of the following:

"5m"

"1h"

BetaBashCodeExecutionToolResultBlockParam { content, tool_use_id, type, cache_control }

content: BetaBashCodeExecutionToolResultErrorParam { error_code, type } | BetaBashCodeExecutionResultBlockParam { content, return_code, stderr, 2 more }

Accepts one of the following:

BetaBashCodeExecutionToolResultErrorParam { error_code, type }

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

Accepts one of the following:

"invalid_tool_input"

"unavailable"

"too_many_requests"

"execution_time_exceeded"

"output_file_too_large"

type: "bash_code_execution_tool_result_error"

BetaBashCodeExecutionResultBlockParam { content, return_code, stderr, 2 more }

content: Array<BetaBashCodeExecutionOutputBlockParam { file_id, type } >

file_id: string

type: "bash_code_execution_output"

return_code: number

stderr: string

stdout: string

type: "bash_code_execution_result"

tool_use_id: string

type: "bash_code_execution_tool_result"

cache_control?: BetaCacheControlEphemeral { type, ttl } | null

Create a cache control breakpoint at this content block.

type: "ephemeral"

ttl?: "5m" | "1h"

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

This may be one the following values:

5m: 5 minutes
1h: 1 hour

Defaults to 5m.

Accepts one of the following:

"5m"

"1h"

BetaTextEditorCodeExecutionToolResultBlockParam { content, tool_use_id, type, cache_control }

content: BetaTextEditorCodeExecutionToolResultErrorParam { error_code, type, error_message } | BetaTextEditorCodeExecutionViewResultBlockParam { content, file_type, type, 3 more } | BetaTextEditorCodeExecutionCreateResultBlockParam { is_file_update, type } | BetaTextEditorCodeExecutionStrReplaceResultBlockParam { type, lines, new_lines, 3 more }

Accepts one of the following:

BetaTextEditorCodeExecutionToolResultErrorParam { error_code, type, error_message }

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

Accepts one of the following:

"invalid_tool_input"

"unavailable"

"too_many_requests"

"execution_time_exceeded"

"file_not_found"

type: "text_editor_code_execution_tool_result_error"

error_message?: string | null

BetaTextEditorCodeExecutionViewResultBlockParam { content, file_type, type, 3 more }

content: string

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

Accepts one of the following:

"text"

"image"

"pdf"

type: "text_editor_code_execution_view_result"

num_lines?: number | null

start_line?: number | null

total_lines?: number | null

BetaTextEditorCodeExecutionCreateResultBlockParam { is_file_update, type }

is_file_update: boolean

type: "text_editor_code_execution_create_result"

BetaTextEditorCodeExecutionStrReplaceResultBlockParam { type, lines, new_lines, 3 more }

type: "text_editor_code_execution_str_replace_result"

lines?: Array<string> | null

new_lines?: number | null

new_start?: number | null

old_lines?: number | null

old_start?: number | null

tool_use_id: string

type: "text_editor_code_execution_tool_result"

cache_control?: BetaCacheControlEphemeral { type, ttl } | null

Create a cache control breakpoint at this content block.

type: "ephemeral"

ttl?: "5m" | "1h"

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

This may be one the following values:

5m: 5 minutes
1h: 1 hour

Defaults to 5m.

Accepts one of the following:

"5m"

"1h"

BetaToolSearchToolResultBlockParam { content, tool_use_id, type, cache_control }

content: BetaToolSearchToolResultErrorParam { error_code, type } | BetaToolSearchToolSearchResultBlockParam { tool_references, type }

Accepts one of the following:

BetaToolSearchToolResultErrorParam { error_code, type }

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

Accepts one of the following:

"invalid_tool_input"

"unavailable"

"too_many_requests"