# Beta ## Domain Types ### Anthropic Beta - `AnthropicBeta = (string & {}) | "message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Beta API Error - `BetaAPIError` - `message: string` - `type: "api_error"` - `"api_error"` ### Beta Authentication Error - `BetaAuthenticationError` - `message: string` - `type: "authentication_error"` - `"authentication_error"` ### Beta Billing Error - `BetaBillingError` - `message: string` - `type: "billing_error"` - `"billing_error"` ### Beta Error - `BetaError = BetaInvalidRequestError | BetaAuthenticationError | BetaBillingError | 6 more` - `BetaInvalidRequestError` - `message: string` - `type: "invalid_request_error"` - `"invalid_request_error"` - `BetaAuthenticationError` - `message: string` - `type: "authentication_error"` - `"authentication_error"` - `BetaBillingError` - `message: string` - `type: "billing_error"` - `"billing_error"` - `BetaPermissionError` - `message: string` - `type: "permission_error"` - `"permission_error"` - `BetaNotFoundError` - `message: string` - `type: "not_found_error"` - `"not_found_error"` - `BetaRateLimitError` - `message: string` - `type: "rate_limit_error"` - `"rate_limit_error"` - `BetaGatewayTimeoutError` - `message: string` - `type: "timeout_error"` - `"timeout_error"` - `BetaAPIError` - `message: string` - `type: "api_error"` - `"api_error"` - `BetaOverloadedError` - `message: string` - `type: "overloaded_error"` - `"overloaded_error"` ### Beta Error Response - `BetaErrorResponse` - `error: BetaError` - `BetaInvalidRequestError` - `message: string` - `type: "invalid_request_error"` - `"invalid_request_error"` - `BetaAuthenticationError` - `message: string` - `type: "authentication_error"` - `"authentication_error"` - `BetaBillingError` - `message: string` - `type: "billing_error"` - `"billing_error"` - `BetaPermissionError` - `message: string` - `type: "permission_error"` - `"permission_error"` - `BetaNotFoundError` - `message: string` - `type: "not_found_error"` - `"not_found_error"` - `BetaRateLimitError` - `message: string` - `type: "rate_limit_error"` - `"rate_limit_error"` - `BetaGatewayTimeoutError` - `message: string` - `type: "timeout_error"` - `"timeout_error"` - `BetaAPIError` - `message: string` - `type: "api_error"` - `"api_error"` - `BetaOverloadedError` - `message: string` - `type: "overloaded_error"` - `"overloaded_error"` - `request_id: string | null` - `type: "error"` - `"error"` ### Beta Gateway Timeout Error - `BetaGatewayTimeoutError` - `message: string` - `type: "timeout_error"` - `"timeout_error"` ### Beta Invalid Request Error - `BetaInvalidRequestError` - `message: string` - `type: "invalid_request_error"` - `"invalid_request_error"` ### Beta Not Found Error - `BetaNotFoundError` - `message: string` - `type: "not_found_error"` - `"not_found_error"` ### Beta Overloaded Error - `BetaOverloadedError` - `message: string` - `type: "overloaded_error"` - `"overloaded_error"` ### Beta Permission Error - `BetaPermissionError` - `message: string` - `type: "permission_error"` - `"permission_error"` ### Beta Rate Limit Error - `BetaRateLimitError` - `message: string` - `type: "rate_limit_error"` - `"rate_limit_error"` # Models ## List Models `client.beta.models.list(ModelListParamsparams?, RequestOptionsoptions?): Page` **get** `/v1/models` List available models. The Models API response can be used to determine which models are available for use in the API. More recently released models are listed first. ### Parameters - `params: ModelListParams` - `after_id?: string` Query param: ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object. - `before_id?: string` Query param: ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object. - `limit?: number` Query param: Number of items to return per page. Defaults to `20`. Ranges from `1` to `1000`. - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaModelInfo` - `id: string` Unique model identifier. - `capabilities: BetaModelCapabilities | null` Model capability information. - `batch: BetaCapabilitySupport` Whether the model supports the Batch API. - `supported: boolean` Whether this capability is supported by the model. - `citations: BetaCapabilitySupport` Whether the model supports citation generation. - `code_execution: BetaCapabilitySupport` Whether the model supports code execution tools. - `context_management: BetaContextManagementCapability` Context management support and available strategies. - `clear_thinking_20251015: BetaCapabilitySupport | null` Indicates whether a capability is supported. - `clear_tool_uses_20250919: BetaCapabilitySupport | null` Indicates whether a capability is supported. - `compact_20260112: BetaCapabilitySupport | null` Indicates whether a capability is supported. - `supported: boolean` Whether this capability is supported by the model. - `effort: BetaEffortCapability` Effort (reasoning_effort) support and available levels. - `high: BetaCapabilitySupport` Whether the model supports high effort level. - `low: BetaCapabilitySupport` Whether the model supports low effort level. - `max: BetaCapabilitySupport` Whether the model supports max effort level. - `medium: BetaCapabilitySupport` Whether the model supports medium effort level. - `supported: boolean` Whether this capability is supported by the model. - `xhigh: BetaCapabilitySupport | null` Indicates whether a capability is supported. - `image_input: BetaCapabilitySupport` Whether the model accepts image content blocks. - `pdf_input: BetaCapabilitySupport` Whether the model accepts PDF content blocks. - `structured_outputs: BetaCapabilitySupport` Whether the model supports structured output / JSON mode / strict tool schemas. - `thinking: BetaThinkingCapability` Thinking capability and supported type configurations. - `supported: boolean` Whether this capability is supported by the model. - `types: BetaThinkingTypes` Supported thinking type configurations. - `adaptive: BetaCapabilitySupport` Whether the model supports thinking with type 'adaptive' (auto). - `enabled: BetaCapabilitySupport` Whether the model supports thinking with type 'enabled'. - `created_at: string` RFC 3339 datetime string representing the time at which the model was released. May be set to an epoch value if the release date is unknown. - `display_name: string` A human-readable name for the model. - `max_input_tokens: number | null` Maximum input context window size in tokens for this model. - `max_tokens: number | null` Maximum value for the `max_tokens` parameter when using this model. - `type: "model"` Object type. For Models, this is always `"model"`. - `"model"` ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); // Automatically fetches more pages as needed. for await (const betaModelInfo of client.beta.models.list()) { console.log(betaModelInfo.id); } ``` #### Response ```json { "data": [ { "id": "claude-opus-4-6", "capabilities": { "batch": { "supported": true }, "citations": { "supported": true }, "code_execution": { "supported": true }, "context_management": { "clear_thinking_20251015": { "supported": true }, "clear_tool_uses_20250919": { "supported": true }, "compact_20260112": { "supported": true }, "supported": true }, "effort": { "high": { "supported": true }, "low": { "supported": true }, "max": { "supported": true }, "medium": { "supported": true }, "supported": true, "xhigh": { "supported": true } }, "image_input": { "supported": true }, "pdf_input": { "supported": true }, "structured_outputs": { "supported": true }, "thinking": { "supported": true, "types": { "adaptive": { "supported": true }, "enabled": { "supported": true } } } }, "created_at": "2026-02-04T00:00:00Z", "display_name": "Claude Opus 4.6", "max_input_tokens": 0, "max_tokens": 0, "type": "model" } ], "first_id": "first_id", "has_more": true, "last_id": "last_id" } ``` ## Get a Model `client.beta.models.retrieve(stringmodelID, ModelRetrieveParamsparams?, RequestOptionsoptions?): BetaModelInfo` **get** `/v1/models/{model_id}` Get a specific model. The Models API response can be used to determine information about a specific model or resolve a model alias to a model ID. ### Parameters - `modelID: string` Model identifier or alias. - `params: ModelRetrieveParams` - `betas?: Array` Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaModelInfo` - `id: string` Unique model identifier. - `capabilities: BetaModelCapabilities | null` Model capability information. - `batch: BetaCapabilitySupport` Whether the model supports the Batch API. - `supported: boolean` Whether this capability is supported by the model. - `citations: BetaCapabilitySupport` Whether the model supports citation generation. - `code_execution: BetaCapabilitySupport` Whether the model supports code execution tools. - `context_management: BetaContextManagementCapability` Context management support and available strategies. - `clear_thinking_20251015: BetaCapabilitySupport | null` Indicates whether a capability is supported. - `clear_tool_uses_20250919: BetaCapabilitySupport | null` Indicates whether a capability is supported. - `compact_20260112: BetaCapabilitySupport | null` Indicates whether a capability is supported. - `supported: boolean` Whether this capability is supported by the model. - `effort: BetaEffortCapability` Effort (reasoning_effort) support and available levels. - `high: BetaCapabilitySupport` Whether the model supports high effort level. - `low: BetaCapabilitySupport` Whether the model supports low effort level. - `max: BetaCapabilitySupport` Whether the model supports max effort level. - `medium: BetaCapabilitySupport` Whether the model supports medium effort level. - `supported: boolean` Whether this capability is supported by the model. - `xhigh: BetaCapabilitySupport | null` Indicates whether a capability is supported. - `image_input: BetaCapabilitySupport` Whether the model accepts image content blocks. - `pdf_input: BetaCapabilitySupport` Whether the model accepts PDF content blocks. - `structured_outputs: BetaCapabilitySupport` Whether the model supports structured output / JSON mode / strict tool schemas. - `thinking: BetaThinkingCapability` Thinking capability and supported type configurations. - `supported: boolean` Whether this capability is supported by the model. - `types: BetaThinkingTypes` Supported thinking type configurations. - `adaptive: BetaCapabilitySupport` Whether the model supports thinking with type 'adaptive' (auto). - `enabled: BetaCapabilitySupport` Whether the model supports thinking with type 'enabled'. - `created_at: string` RFC 3339 datetime string representing the time at which the model was released. May be set to an epoch value if the release date is unknown. - `display_name: string` A human-readable name for the model. - `max_input_tokens: number | null` Maximum input context window size in tokens for this model. - `max_tokens: number | null` Maximum value for the `max_tokens` parameter when using this model. - `type: "model"` Object type. For Models, this is always `"model"`. - `"model"` ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const betaModelInfo = await client.beta.models.retrieve('model_id'); console.log(betaModelInfo.id); ``` #### Response ```json { "id": "claude-opus-4-6", "capabilities": { "batch": { "supported": true }, "citations": { "supported": true }, "code_execution": { "supported": true }, "context_management": { "clear_thinking_20251015": { "supported": true }, "clear_tool_uses_20250919": { "supported": true }, "compact_20260112": { "supported": true }, "supported": true }, "effort": { "high": { "supported": true }, "low": { "supported": true }, "max": { "supported": true }, "medium": { "supported": true }, "supported": true, "xhigh": { "supported": true } }, "image_input": { "supported": true }, "pdf_input": { "supported": true }, "structured_outputs": { "supported": true }, "thinking": { "supported": true, "types": { "adaptive": { "supported": true }, "enabled": { "supported": true } } } }, "created_at": "2026-02-04T00:00:00Z", "display_name": "Claude Opus 4.6", "max_input_tokens": 0, "max_tokens": 0, "type": "model" } ``` ## Domain Types ### Beta Capability Support - `BetaCapabilitySupport` Indicates whether a capability is supported. - `supported: boolean` Whether this capability is supported by the model. ### Beta Context Management Capability - `BetaContextManagementCapability` Context management capability details. - `clear_thinking_20251015: BetaCapabilitySupport | null` Indicates whether a capability is supported. - `supported: boolean` Whether this capability is supported by the model. - `clear_tool_uses_20250919: BetaCapabilitySupport | null` Indicates whether a capability is supported. - `compact_20260112: BetaCapabilitySupport | null` Indicates whether a capability is supported. - `supported: boolean` Whether this capability is supported by the model. ### Beta Effort Capability - `BetaEffortCapability` Effort (reasoning_effort) capability details. - `high: BetaCapabilitySupport` Whether the model supports high effort level. - `supported: boolean` Whether this capability is supported by the model. - `low: BetaCapabilitySupport` Whether the model supports low effort level. - `max: BetaCapabilitySupport` Whether the model supports max effort level. - `medium: BetaCapabilitySupport` Whether the model supports medium effort level. - `supported: boolean` Whether this capability is supported by the model. - `xhigh: BetaCapabilitySupport | null` Indicates whether a capability is supported. ### Beta Model Capabilities - `BetaModelCapabilities` Model capability information. - `batch: BetaCapabilitySupport` Whether the model supports the Batch API. - `supported: boolean` Whether this capability is supported by the model. - `citations: BetaCapabilitySupport` Whether the model supports citation generation. - `code_execution: BetaCapabilitySupport` Whether the model supports code execution tools. - `context_management: BetaContextManagementCapability` Context management support and available strategies. - `clear_thinking_20251015: BetaCapabilitySupport | null` Indicates whether a capability is supported. - `clear_tool_uses_20250919: BetaCapabilitySupport | null` Indicates whether a capability is supported. - `compact_20260112: BetaCapabilitySupport | null` Indicates whether a capability is supported. - `supported: boolean` Whether this capability is supported by the model. - `effort: BetaEffortCapability` Effort (reasoning_effort) support and available levels. - `high: BetaCapabilitySupport` Whether the model supports high effort level. - `low: BetaCapabilitySupport` Whether the model supports low effort level. - `max: BetaCapabilitySupport` Whether the model supports max effort level. - `medium: BetaCapabilitySupport` Whether the model supports medium effort level. - `supported: boolean` Whether this capability is supported by the model. - `xhigh: BetaCapabilitySupport | null` Indicates whether a capability is supported. - `image_input: BetaCapabilitySupport` Whether the model accepts image content blocks. - `pdf_input: BetaCapabilitySupport` Whether the model accepts PDF content blocks. - `structured_outputs: BetaCapabilitySupport` Whether the model supports structured output / JSON mode / strict tool schemas. - `thinking: BetaThinkingCapability` Thinking capability and supported type configurations. - `supported: boolean` Whether this capability is supported by the model. - `types: BetaThinkingTypes` Supported thinking type configurations. - `adaptive: BetaCapabilitySupport` Whether the model supports thinking with type 'adaptive' (auto). - `enabled: BetaCapabilitySupport` Whether the model supports thinking with type 'enabled'. ### Beta Model Info - `BetaModelInfo` - `id: string` Unique model identifier. - `capabilities: BetaModelCapabilities | null` Model capability information. - `batch: BetaCapabilitySupport` Whether the model supports the Batch API. - `supported: boolean` Whether this capability is supported by the model. - `citations: BetaCapabilitySupport` Whether the model supports citation generation. - `code_execution: BetaCapabilitySupport` Whether the model supports code execution tools. - `context_management: BetaContextManagementCapability` Context management support and available strategies. - `clear_thinking_20251015: BetaCapabilitySupport | null` Indicates whether a capability is supported. - `clear_tool_uses_20250919: BetaCapabilitySupport | null` Indicates whether a capability is supported. - `compact_20260112: BetaCapabilitySupport | null` Indicates whether a capability is supported. - `supported: boolean` Whether this capability is supported by the model. - `effort: BetaEffortCapability` Effort (reasoning_effort) support and available levels. - `high: BetaCapabilitySupport` Whether the model supports high effort level. - `low: BetaCapabilitySupport` Whether the model supports low effort level. - `max: BetaCapabilitySupport` Whether the model supports max effort level. - `medium: BetaCapabilitySupport` Whether the model supports medium effort level. - `supported: boolean` Whether this capability is supported by the model. - `xhigh: BetaCapabilitySupport | null` Indicates whether a capability is supported. - `image_input: BetaCapabilitySupport` Whether the model accepts image content blocks. - `pdf_input: BetaCapabilitySupport` Whether the model accepts PDF content blocks. - `structured_outputs: BetaCapabilitySupport` Whether the model supports structured output / JSON mode / strict tool schemas. - `thinking: BetaThinkingCapability` Thinking capability and supported type configurations. - `supported: boolean` Whether this capability is supported by the model. - `types: BetaThinkingTypes` Supported thinking type configurations. - `adaptive: BetaCapabilitySupport` Whether the model supports thinking with type 'adaptive' (auto). - `enabled: BetaCapabilitySupport` Whether the model supports thinking with type 'enabled'. - `created_at: string` RFC 3339 datetime string representing the time at which the model was released. May be set to an epoch value if the release date is unknown. - `display_name: string` A human-readable name for the model. - `max_input_tokens: number | null` Maximum input context window size in tokens for this model. - `max_tokens: number | null` Maximum value for the `max_tokens` parameter when using this model. - `type: "model"` Object type. For Models, this is always `"model"`. - `"model"` ### Beta Thinking Capability - `BetaThinkingCapability` Thinking capability details. - `supported: boolean` Whether this capability is supported by the model. - `types: BetaThinkingTypes` Supported thinking type configurations. - `adaptive: BetaCapabilitySupport` Whether the model supports thinking with type 'adaptive' (auto). - `supported: boolean` Whether this capability is supported by the model. - `enabled: BetaCapabilitySupport` Whether the model supports thinking with type 'enabled'. ### Beta Thinking Types - `BetaThinkingTypes` Supported thinking type configurations. - `adaptive: BetaCapabilitySupport` Whether the model supports thinking with type 'adaptive' (auto). - `supported: boolean` Whether this capability is supported by the model. - `enabled: BetaCapabilitySupport` Whether the model supports thinking with type 'enabled'. # Messages ## Create a Message `client.beta.messages.create(MessageCreateParamsparams, RequestOptionsoptions?): BetaMessage | Stream` **post** `/v1/messages` Send a structured list of input messages with text and/or image content, and the model will generate the next message in the conversation. The Messages API can be used for either single queries or stateless multi-turn conversations. Learn more about the Messages API in our [user guide](https://docs.claude.com/en/docs/initial-setup) ### Parameters - `MessageCreateParams = MessageCreateParamsNonStreaming | MessageCreateParamsStreaming` - `MessageCreateParamsBase` - `max_tokens: number` Body param: The maximum number of tokens to generate before stopping. Note that our models may stop _before_ reaching this maximum. This parameter only specifies the absolute maximum number of tokens to generate. Set to `0` to populate the [prompt cache](https://docs.claude.com/en/docs/build-with-claude/prompt-caching#pre-warming-the-cache) without generating a response. Different models have different maximum values for this parameter. See [models](https://docs.claude.com/en/docs/models-overview) for details. - `messages: Array` Body param: Input messages. Our models are trained to operate on alternating `user` and `assistant` conversational turns. When creating a new `Message`, you specify the prior conversational turns with the `messages` parameter, and the model then generates the next `Message` in the conversation. Consecutive `user` or `assistant` turns in your request will be combined into a single turn. Each input message must be an object with a `role` and `content`. You can specify a single `user`-role message, or you can include multiple `user` and `assistant` messages. If the final message uses the `assistant` role, the response content will continue immediately from the content in that message. This can be used to constrain part of the model's response. Example with a single `user` message: ```json [{"role": "user", "content": "Hello, Claude"}] ``` Example with multiple conversational turns: ```json [ {"role": "user", "content": "Hello there."}, {"role": "assistant", "content": "Hi, I'm Claude. How can I help you?"}, {"role": "user", "content": "Can you explain LLMs in plain English?"}, ] ``` Example with a partially-filled response from Claude: ```json [ {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, {"role": "assistant", "content": "The best answer is ("}, ] ``` Each input message `content` may be either a single `string` or an array of content blocks, where each block has a specific `type`. Using a `string` for `content` is shorthand for an array of one content block of type `"text"`. The following input messages are equivalent: ```json {"role": "user", "content": "Hello, Claude"} ``` ```json {"role": "user", "content": [{"type": "text", "text": "Hello, Claude"}]} ``` See [input examples](https://docs.claude.com/en/api/messages-examples). Note that if you want to include a [system prompt](https://docs.claude.com/en/docs/system-prompts), you can use the top-level `system` parameter — there is no `"system"` role for input messages in the Messages API. There is a limit of 100,000 messages in a single request. - `content: string | Array` - `string` - `Array` - `BetaTextBlockParam` - `text: string` - `type: "text"` - `"text"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `"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`. - `"5m"` - `"1h"` - `citations?: Array | null` - `BetaCitationCharLocationParam` - `cited_text: string` - `document_index: number` - `document_title: string | null` - `end_char_index: number` - `start_char_index: number` - `type: "char_location"` - `"char_location"` - `BetaCitationPageLocationParam` - `cited_text: string` - `document_index: number` - `document_title: string | null` - `end_page_number: number` - `start_page_number: number` - `type: "page_location"` - `"page_location"` - `BetaCitationContentBlockLocationParam` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `document_index: number` - `document_title: string | null` - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. - `type: "content_block_location"` - `"content_block_location"` - `BetaCitationWebSearchResultLocationParam` - `cited_text: string` - `encrypted_index: string` - `title: string | null` - `type: "web_search_result_location"` - `"web_search_result_location"` - `url: string` - `BetaCitationSearchResultLocationParam` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `search_result_index: number` 0-based index of the cited search result among all `search_result` content blocks in the request, in the order they appear across messages and tool results. Counted separately from `document_index`; server-side web search results are not included in this count. - `source: string` - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. - `title: string | null` - `type: "search_result_location"` - `"search_result_location"` - `BetaImageBlockParam` - `source: BetaBase64ImageSource | BetaURLImageSource | BetaFileImageSource` - `BetaBase64ImageSource` - `data: string` - `media_type: "image/jpeg" | "image/png" | "image/gif" | "image/webp"` - `"image/jpeg"` - `"image/png"` - `"image/gif"` - `"image/webp"` - `type: "base64"` - `"base64"` - `BetaURLImageSource` - `type: "url"` - `"url"` - `url: string` - `BetaFileImageSource` - `file_id: string` - `type: "file"` - `"file"` - `type: "image"` - `"image"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `BetaRequestDocumentBlock` - `source: BetaBase64PDFSource | BetaPlainTextSource | BetaContentBlockSource | 2 more` - `BetaBase64PDFSource` - `data: string` - `media_type: "application/pdf"` - `"application/pdf"` - `type: "base64"` - `"base64"` - `BetaPlainTextSource` - `data: string` - `media_type: "text/plain"` - `"text/plain"` - `type: "text"` - `"text"` - `BetaContentBlockSource` - `content: string | Array` - `string` - `Array` - `BetaTextBlockParam` - `BetaImageBlockParam` - `type: "content"` - `"content"` - `BetaURLPDFSource` - `type: "url"` - `"url"` - `url: string` - `BetaFileDocumentSource` - `file_id: string` - `type: "file"` - `"file"` - `type: "document"` - `"document"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `citations?: BetaCitationsConfigParam | null` - `enabled?: boolean` - `context?: string | null` - `title?: string | null` - `BetaSearchResultBlockParam` - `content: Array` - `text: string` - `type: "text"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `citations?: Array | null` - `source: string` - `title: string` - `type: "search_result"` - `"search_result"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `citations?: BetaCitationsConfigParam` - `BetaThinkingBlockParam` - `signature: string` - `thinking: string` - `type: "thinking"` - `"thinking"` - `BetaRedactedThinkingBlockParam` - `data: string` - `type: "redacted_thinking"` - `"redacted_thinking"` - `BetaToolUseBlockParam` - `id: string` - `input: Record` - `name: string` - `type: "tool_use"` - `"tool_use"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `caller?: BetaDirectCaller | BetaServerToolCaller | BetaServerToolCaller20260120` Tool invocation directly from the model. - `BetaDirectCaller` Tool invocation directly from the model. - `type: "direct"` - `"direct"` - `BetaServerToolCaller` Tool invocation generated by a server-side tool. - `tool_id: string` - `type: "code_execution_20250825"` - `"code_execution_20250825"` - `BetaServerToolCaller20260120` - `tool_id: string` - `type: "code_execution_20260120"` - `"code_execution_20260120"` - `BetaToolResultBlockParam` - `tool_use_id: string` - `type: "tool_result"` - `"tool_result"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `content?: string | Array` - `string` - `Array` - `BetaTextBlockParam` - `BetaImageBlockParam` - `BetaSearchResultBlockParam` - `BetaRequestDocumentBlock` - `BetaToolReferenceBlockParam` Tool reference block that can be included in tool_result content. - `tool_name: string` - `type: "tool_reference"` - `"tool_reference"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `is_error?: boolean` - `BetaServerToolUseBlockParam` - `id: string` - `input: Record` - `name: "advisor" | "web_search" | "web_fetch" | 5 more` - `"advisor"` - `"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"` - `"server_tool_use"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `caller?: BetaDirectCaller | BetaServerToolCaller | BetaServerToolCaller20260120` Tool invocation directly from the model. - `BetaDirectCaller` Tool invocation directly from the model. - `BetaServerToolCaller` Tool invocation generated by a server-side tool. - `BetaServerToolCaller20260120` - `BetaWebSearchToolResultBlockParam` - `content: BetaWebSearchToolResultBlockParamContent` - `Array` - `encrypted_content: string` - `title: string` - `type: "web_search_result"` - `"web_search_result"` - `url: string` - `page_age?: string | null` - `BetaWebSearchToolRequestError` - `error_code: BetaWebSearchToolResultErrorCode` - `"invalid_tool_input"` - `"unavailable"` - `"max_uses_exceeded"` - `"too_many_requests"` - `"query_too_long"` - `"request_too_large"` - `type: "web_search_tool_result_error"` - `"web_search_tool_result_error"` - `tool_use_id: string` - `type: "web_search_tool_result"` - `"web_search_tool_result"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `caller?: BetaDirectCaller | BetaServerToolCaller | BetaServerToolCaller20260120` Tool invocation directly from the model. - `BetaDirectCaller` Tool invocation directly from the model. - `BetaServerToolCaller` Tool invocation generated by a server-side tool. - `BetaServerToolCaller20260120` - `BetaWebFetchToolResultBlockParam` - `content: BetaWebFetchToolResultErrorBlockParam | BetaWebFetchBlockParam` - `BetaWebFetchToolResultErrorBlockParam` - `error_code: BetaWebFetchToolResultErrorCode` - `"invalid_tool_input"` - `"url_too_long"` - `"url_not_allowed"` - `"url_not_in_prior_context"` - `"url_not_accessible"` - `"unsupported_content_type"` - `"too_many_requests"` - `"max_uses_exceeded"` - `"unavailable"` - `type: "web_fetch_tool_result_error"` - `"web_fetch_tool_result_error"` - `BetaWebFetchBlockParam` - `content: BetaRequestDocumentBlock` - `type: "web_fetch_result"` - `"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"` - `"web_fetch_tool_result"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `caller?: BetaDirectCaller | BetaServerToolCaller | BetaServerToolCaller20260120` Tool invocation directly from the model. - `BetaDirectCaller` Tool invocation directly from the model. - `BetaServerToolCaller` Tool invocation generated by a server-side tool. - `BetaServerToolCaller20260120` - `BetaAdvisorToolResultBlockParam` - `content: BetaAdvisorToolResultErrorParam | BetaAdvisorResultBlockParam | BetaAdvisorRedactedResultBlockParam` - `BetaAdvisorToolResultErrorParam` - `error_code: "max_uses_exceeded" | "prompt_too_long" | "too_many_requests" | 3 more` - `"max_uses_exceeded"` - `"prompt_too_long"` - `"too_many_requests"` - `"overloaded"` - `"unavailable"` - `"execution_time_exceeded"` - `type: "advisor_tool_result_error"` - `"advisor_tool_result_error"` - `BetaAdvisorResultBlockParam` - `text: string` - `type: "advisor_result"` - `"advisor_result"` - `stop_reason?: string | null` - `BetaAdvisorRedactedResultBlockParam` - `encrypted_content: string` Opaque blob produced by a prior response; must be round-tripped verbatim. - `type: "advisor_redacted_result"` - `"advisor_redacted_result"` - `stop_reason?: string | null` - `tool_use_id: string` - `type: "advisor_tool_result"` - `"advisor_tool_result"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `BetaCodeExecutionToolResultBlockParam` - `content: BetaCodeExecutionToolResultBlockParamContent` Code execution result with encrypted stdout for PFC + web_search results. - `BetaCodeExecutionToolResultErrorParam` - `error_code: BetaCodeExecutionToolResultErrorCode` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `type: "code_execution_tool_result_error"` - `"code_execution_tool_result_error"` - `BetaCodeExecutionResultBlockParam` - `content: Array` - `file_id: string` - `type: "code_execution_output"` - `"code_execution_output"` - `return_code: number` - `stderr: string` - `stdout: string` - `type: "code_execution_result"` - `"code_execution_result"` - `BetaEncryptedCodeExecutionResultBlockParam` Code execution result with encrypted stdout for PFC + web_search results. - `content: Array` - `file_id: string` - `type: "code_execution_output"` - `encrypted_stdout: string` - `return_code: number` - `stderr: string` - `type: "encrypted_code_execution_result"` - `"encrypted_code_execution_result"` - `tool_use_id: string` - `type: "code_execution_tool_result"` - `"code_execution_tool_result"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `BetaBashCodeExecutionToolResultBlockParam` - `content: BetaBashCodeExecutionToolResultErrorParam | BetaBashCodeExecutionResultBlockParam` - `BetaBashCodeExecutionToolResultErrorParam` - `error_code: "invalid_tool_input" | "unavailable" | "too_many_requests" | 2 more` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `"output_file_too_large"` - `type: "bash_code_execution_tool_result_error"` - `"bash_code_execution_tool_result_error"` - `BetaBashCodeExecutionResultBlockParam` - `content: Array` - `file_id: string` - `type: "bash_code_execution_output"` - `"bash_code_execution_output"` - `return_code: number` - `stderr: string` - `stdout: string` - `type: "bash_code_execution_result"` - `"bash_code_execution_result"` - `tool_use_id: string` - `type: "bash_code_execution_tool_result"` - `"bash_code_execution_tool_result"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `BetaTextEditorCodeExecutionToolResultBlockParam` - `content: BetaTextEditorCodeExecutionToolResultErrorParam | BetaTextEditorCodeExecutionViewResultBlockParam | BetaTextEditorCodeExecutionCreateResultBlockParam | BetaTextEditorCodeExecutionStrReplaceResultBlockParam` - `BetaTextEditorCodeExecutionToolResultErrorParam` - `error_code: "invalid_tool_input" | "unavailable" | "too_many_requests" | 2 more` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `"file_not_found"` - `type: "text_editor_code_execution_tool_result_error"` - `"text_editor_code_execution_tool_result_error"` - `error_message?: string | null` - `BetaTextEditorCodeExecutionViewResultBlockParam` - `content: string` - `file_type: "text" | "image" | "pdf"` - `"text"` - `"image"` - `"pdf"` - `type: "text_editor_code_execution_view_result"` - `"text_editor_code_execution_view_result"` - `num_lines?: number | null` - `start_line?: number | null` - `total_lines?: number | null` - `BetaTextEditorCodeExecutionCreateResultBlockParam` - `is_file_update: boolean` - `type: "text_editor_code_execution_create_result"` - `"text_editor_code_execution_create_result"` - `BetaTextEditorCodeExecutionStrReplaceResultBlockParam` - `type: "text_editor_code_execution_str_replace_result"` - `"text_editor_code_execution_str_replace_result"` - `lines?: Array | 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"` - `"text_editor_code_execution_tool_result"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `BetaToolSearchToolResultBlockParam` - `content: BetaToolSearchToolResultErrorParam | BetaToolSearchToolSearchResultBlockParam` - `BetaToolSearchToolResultErrorParam` - `error_code: "invalid_tool_input" | "unavailable" | "too_many_requests" | "execution_time_exceeded"` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `type: "tool_search_tool_result_error"` - `"tool_search_tool_result_error"` - `BetaToolSearchToolSearchResultBlockParam` - `tool_references: Array` - `tool_name: string` - `type: "tool_reference"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `type: "tool_search_tool_search_result"` - `"tool_search_tool_search_result"` - `tool_use_id: string` - `type: "tool_search_tool_result"` - `"tool_search_tool_result"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `BetaMCPToolUseBlockParam` - `id: string` - `input: Record` - `name: string` - `server_name: string` The name of the MCP server - `type: "mcp_tool_use"` - `"mcp_tool_use"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `BetaRequestMCPToolResultBlockParam` - `tool_use_id: string` - `type: "mcp_tool_result"` - `"mcp_tool_result"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `content?: string | Array` - `string` - `Array` - `text: string` - `type: "text"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `citations?: Array | null` - `is_error?: boolean` - `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. - `file_id: string` - `type: "container_upload"` - `"container_upload"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `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. - `type: "compaction"` - `"compaction"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `content?: string | null` Summary of previously compacted content, or null if compaction failed - `encrypted_content?: string | null` Opaque metadata from prior compaction, to be round-tripped verbatim - `BetaMidConversationSystemBlockParam` System instructions that appear mid-conversation. Use this block to provide or update system-level instructions at a specific point in the conversation, rather than only via the top-level `system` parameter. - `content: Array` System instruction text blocks. - `text: string` - `type: "text"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `citations?: Array | null` - `type: "mid_conv_system"` - `"mid_conv_system"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `role: "user" | "assistant" | "system"` - `"user"` - `"assistant"` - `"system"` - `model: Model` Body param: The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-opus-4-8" | "claude-opus-4-7" | "claude-mythos-preview" | 15 more` - `"claude-opus-4-8"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-7"` Frontier intelligence for long-running agents and coding - `"claude-mythos-preview"` New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` Fastest model with near-frontier intelligence - `"claude-haiku-4-5-20251001"` Fastest model with near-frontier intelligence - `"claude-opus-4-5"` Premium model combining maximum intelligence with practical performance - `"claude-opus-4-5-20251101"` Premium model combining maximum intelligence with practical performance - `"claude-sonnet-4-5"` High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` High-performance model for agents and coding - `"claude-opus-4-1"` Exceptional model for specialized complex tasks - `"claude-opus-4-1-20250805"` Exceptional model for specialized complex tasks - `"claude-opus-4-0"` Powerful model for complex tasks - `"claude-opus-4-20250514"` Powerful model for complex tasks - `"claude-sonnet-4-0"` High-performance model with extended thinking - `"claude-sonnet-4-20250514"` High-performance model with extended thinking - `"claude-3-haiku-20240307"` Fast and cost-effective model - `(string & {})` - `cache_control?: BetaCacheControlEphemeral | null` Body param: Top-level cache control automatically applies a cache_control marker to the last cacheable block in the request. - `container?: BetaContainerParams | string | null` Body param: Container identifier for reuse across requests. - `BetaContainerParams` Container parameters with skills to be loaded. - `id?: string | null` Container id - `skills?: Array | 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) - `"anthropic"` - `"custom"` - `version?: string` Skill version or 'latest' for most recent version - `string` - `context_management?: BetaContextManagementConfig | null` Body param: Context management configuration. This allows you to control how Claude manages context across multiple requests, such as whether to clear function results or not. - `edits?: Array` List of context management edits to apply - `BetaClearToolUses20250919Edit` - `type: "clear_tool_uses_20250919"` - `"clear_tool_uses_20250919"` - `clear_at_least?: BetaInputTokensClearAtLeast | 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"` - `"input_tokens"` - `value: number` - `clear_tool_inputs?: boolean | Array | null` Whether to clear all tool inputs (bool) or specific tool inputs to clear (list) - `boolean` - `Array` - `exclude_tools?: Array | null` Tool names whose uses are preserved from clearing - `keep?: BetaToolUsesKeep` Number of tool uses to retain in the conversation - `type: "tool_uses"` - `"tool_uses"` - `value: number` - `trigger?: BetaInputTokensTrigger | BetaToolUsesTrigger` Condition that triggers the context management strategy - `BetaInputTokensTrigger` - `type: "input_tokens"` - `"input_tokens"` - `value: number` - `BetaToolUsesTrigger` - `type: "tool_uses"` - `"tool_uses"` - `value: number` - `BetaClearThinking20251015Edit` - `type: "clear_thinking_20251015"` - `"clear_thinking_20251015"` - `keep?: BetaThinkingTurns | BetaAllThinkingTurns | "all"` Number of most recent assistant turns to keep thinking blocks for. Older turns will have their thinking blocks removed. - `BetaThinkingTurns` - `type: "thinking_turns"` - `"thinking_turns"` - `value: number` - `BetaAllThinkingTurns` - `type: "all"` - `"all"` - `"all"` - `"all"` - `BetaCompact20260112Edit` Automatically compact older context when reaching the configured trigger threshold. - `type: "compact_20260112"` - `"compact_20260112"` - `instructions?: string | null` Additional instructions for summarization. - `pause_after_compaction?: boolean` Whether to pause after compaction and return the compaction block to the user. - `trigger?: BetaInputTokensTrigger | null` When to trigger compaction. Defaults to 150000 input tokens. - `diagnostics?: BetaDiagnosticsParam | null` Body param: Request-level diagnostics. Currently carries the previous response id for prompt-cache divergence reporting. - `previous_message_id?: string | null` The `id` (`msg_...`) from this client's previous /v1/messages response. The server compares that request's prompt fingerprint against this one and returns `diagnostics.cache_miss_reason` when the prompt-cache prefix could not be reused. Pass `null` on the first turn to opt in without a prior message to compare. - `inference_geo?: string | null` Body param: Specifies the geographic region for inference processing. If not specified, the workspace's `default_inference_geo` is used. - `mcp_servers?: Array` Body param: MCP servers to be utilized in this request - `name: string` - `type: "url"` - `"url"` - `url: string` - `authorization_token?: string | null` - `tool_configuration?: BetaRequestMCPServerToolConfiguration | null` - `allowed_tools?: Array | null` - `enabled?: boolean | null` - `metadata?: BetaMetadata` Body param: An object describing metadata about the request. - `user_id?: string | null` An external identifier for the user who is associated with the request. This should be a uuid, hash value, or other opaque identifier. Anthropic may use this id to help detect abuse. Do not include any identifying information such as name, email address, or phone number. - `output_config?: BetaOutputConfig` Body param: Configuration options for the model's output, such as the output format. - `effort?: "low" | "medium" | "high" | 2 more | null` All possible effort levels. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `format?: BetaJSONOutputFormat | null` A schema to specify Claude's output format in responses. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) - `schema: Record` The JSON schema of the format - `type: "json_schema"` - `"json_schema"` - `task_budget?: BetaTokenTaskBudget | null` User-configurable total token budget across contexts. - `total: number` Total token budget across all contexts in the session. - `type: "tokens"` The budget type. Currently only 'tokens' is supported. - `"tokens"` - `remaining?: number | null` Remaining tokens in the budget. Use this to track usage across contexts when implementing compaction client-side. Defaults to total if not provided. - `output_format?: BetaJSONOutputFormat | null` Body param: Deprecated: Use `output_config.format` instead. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) A schema to specify Claude's output format in responses. This parameter will be removed in a future release. - `service_tier?: "auto" | "standard_only"` Body param: Determines whether to use priority capacity (if available) or standard capacity for this request. Anthropic offers different levels of service for your API requests. See [service-tiers](https://docs.claude.com/en/api/service-tiers) for details. - `"auto"` - `"standard_only"` - `speed?: "standard" | "fast" | null` Body param: The inference speed mode for this request. `"fast"` enables high output-tokens-per-second inference. - `"standard"` - `"fast"` - `stop_sequences?: Array` Body param: Custom text sequences that will cause the model to stop generating. Our models will normally stop when they have naturally completed their turn, which will result in a response `stop_reason` of `"end_turn"`. If you want the model to stop generating when it encounters custom strings of text, you can use the `stop_sequences` parameter. If the model encounters one of the custom sequences, the response `stop_reason` value will be `"stop_sequence"` and the response `stop_sequence` value will contain the matched stop sequence. - `stream?: false` Body param: Whether to incrementally stream the response using server-sent events. See [streaming](https://docs.claude.com/en/api/messages-streaming) for details. - `false` - `system?: string | Array` Body param: System prompt. A system prompt is a way of providing context and instructions to Claude, such as specifying a particular goal or role. See our [guide to system prompts](https://docs.claude.com/en/docs/system-prompts). - `string` - `Array` - `text: string` - `type: "text"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `citations?: Array | null` - `temperature?: number` Body param: Amount of randomness injected into the response. Defaults to `1.0`. Ranges from `0.0` to `1.0`. Use `temperature` closer to `0.0` for analytical / multiple choice, and closer to `1.0` for creative and generative tasks. Note that even with `temperature` of `0.0`, the results will not be fully deterministic. - `thinking?: BetaThinkingConfigParam` Body param: 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](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) for details. - `BetaThinkingConfigEnabled` - `budget_tokens: number` 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](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) for details. - `type: "enabled"` - `"enabled"` - `display?: "summarized" | "omitted" | null` Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. Defaults to `summarized`. - `"summarized"` - `"omitted"` - `BetaThinkingConfigDisabled` - `type: "disabled"` - `"disabled"` - `BetaThinkingConfigAdaptive` - `type: "adaptive"` - `"adaptive"` - `display?: "summarized" | "omitted" | null` Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. Defaults to `summarized`. - `"summarized"` - `"omitted"` - `tool_choice?: BetaToolChoice` Body param: 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. - `BetaToolChoiceAuto` The model will automatically decide whether to use tools. - `type: "auto"` - `"auto"` - `disable_parallel_tool_use?: boolean` Whether to disable parallel tool use. Defaults to `false`. If set to `true`, the model will output at most one tool use. - `BetaToolChoiceAny` The model will use any available tools. - `type: "any"` - `"any"` - `disable_parallel_tool_use?: boolean` Whether to disable parallel tool use. Defaults to `false`. If set to `true`, the model will output exactly one tool use. - `BetaToolChoiceTool` The model will use the specified tool with `tool_choice.name`. - `name: string` The name of the tool to use. - `type: "tool"` - `"tool"` - `disable_parallel_tool_use?: boolean` Whether to disable parallel tool use. Defaults to `false`. If set to `true`, the model will output exactly one tool use. - `BetaToolChoiceNone` The model will not be allowed to use tools. - `type: "none"` - `"none"` - `tools?: Array` Body param: Definitions of tools that the model may use. If you include `tools` in your API request, the model may return `tool_use` content blocks that represent the model's use of those tools. You can then run those tools using the tool input generated by the model and then optionally return results back to the model using `tool_result` content blocks. There are two types of tools: **client tools** and **server tools**. The behavior described below applies to client tools. For [server tools](https://docs.claude.com/en/docs/agents-and-tools/tool-use/overview#server-tools), see their individual documentation as each has its own behavior (e.g., the [web search tool](https://docs.claude.com/en/docs/agents-and-tools/tool-use/web-search-tool)). Each tool definition includes: * `name`: Name of the tool. * `description`: Optional, but strongly-recommended description of the tool. * `input_schema`: [JSON schema](https://json-schema.org/draft/2020-12) for the tool `input` shape that the model will produce in `tool_use` output content blocks. For example, if you defined `tools` as: ```json [ { "name": "get_stock_price", "description": "Get the current stock price for a given ticker symbol.", "input_schema": { "type": "object", "properties": { "ticker": { "type": "string", "description": "The stock ticker symbol, e.g. AAPL for Apple Inc." } }, "required": ["ticker"] } } ] ``` And then asked the model "What's the S&P 500 at today?", the model might produce `tool_use` content blocks in the response like this: ```json [ { "type": "tool_use", "id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", "name": "get_stock_price", "input": { "ticker": "^GSPC" } } ] ``` You might then run your `get_stock_price` tool with `{"ticker": "^GSPC"}` as an input, and return the following back to the model in a subsequent `user` message: ```json [ { "type": "tool_result", "tool_use_id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", "content": "259.75 USD" } ] ``` Tools can be used for workflows that include running client-side tools and functions, or more generally whenever you want the model to produce a particular JSON structure of output. See our [guide](https://docs.claude.com/en/docs/tool-use) for more details. - `BetaTool` - `input_schema: InputSchema` [JSON schema](https://json-schema.org/draft/2020-12) for this tool's input. This defines the shape of the `input` that your tool accepts and that the model will produce. - `type: "object"` - `"object"` - `properties?: Record | null` - `required?: Array | null` - `name: string` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `defer_loading?: boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `description?: string` Description of what this tool does. Tool descriptions should be as detailed as possible. The more information that the model has about what the tool is and how to use it, the better it will perform. You can use natural language descriptions to reinforce important aspects of the tool input JSON schema. - `eager_input_streaming?: boolean | null` Enable eager input streaming for this tool. When true, tool input parameters will be streamed incrementally as they are generated, and types will be inferred on-the-fly rather than buffering the full JSON output. When false, streaming is disabled for this tool even if the fine-grained-tool-streaming beta is active. When null (default), uses the default behavior based on beta headers. - `input_examples?: Array>` - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `type?: "custom" | null` - `"custom"` - `BetaToolBash20241022` - `name: "bash"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"bash"` - `type: "bash_20241022"` - `"bash_20241022"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `defer_loading?: boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `input_examples?: Array>` - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `BetaToolBash20250124` - `name: "bash"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"bash"` - `type: "bash_20250124"` - `"bash_20250124"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `defer_loading?: boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `input_examples?: Array>` - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `BetaCodeExecutionTool20250522` - `name: "code_execution"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"code_execution"` - `type: "code_execution_20250522"` - `"code_execution_20250522"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `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: "code_execution"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"code_execution"` - `type: "code_execution_20250825"` - `"code_execution_20250825"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `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` Code execution tool with REPL state persistence (daemon mode + gVisor checkpoint). - `name: "code_execution"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"code_execution"` - `type: "code_execution_20260120"` - `"code_execution_20260120"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `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 - `BetaToolComputerUse20241022` - `display_height_px: number` The height of the display in pixels. - `display_width_px: number` The width of the display in pixels. - `name: "computer"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"computer"` - `type: "computer_20241022"` - `"computer_20241022"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `defer_loading?: boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `display_number?: number | null` The X11 display number (e.g. 0, 1) for the display. - `input_examples?: Array>` - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `BetaMemoryTool20250818` - `name: "memory"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"memory"` - `type: "memory_20250818"` - `"memory_20250818"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `defer_loading?: boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `input_examples?: Array>` - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `BetaToolComputerUse20250124` - `display_height_px: number` The height of the display in pixels. - `display_width_px: number` The width of the display in pixels. - `name: "computer"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"computer"` - `type: "computer_20250124"` - `"computer_20250124"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `defer_loading?: boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `display_number?: number | null` The X11 display number (e.g. 0, 1) for the display. - `input_examples?: Array>` - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `BetaToolTextEditor20241022` - `name: "str_replace_editor"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"str_replace_editor"` - `type: "text_editor_20241022"` - `"text_editor_20241022"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `defer_loading?: boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `input_examples?: Array>` - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `BetaToolComputerUse20251124` - `display_height_px: number` The height of the display in pixels. - `display_width_px: number` The width of the display in pixels. - `name: "computer"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"computer"` - `type: "computer_20251124"` - `"computer_20251124"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `defer_loading?: boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `display_number?: number | null` The X11 display number (e.g. 0, 1) for the display. - `enable_zoom?: boolean` Whether to enable an action to take a zoomed-in screenshot of the screen. - `input_examples?: Array>` - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `BetaToolTextEditor20250124` - `name: "str_replace_editor"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"str_replace_editor"` - `type: "text_editor_20250124"` - `"text_editor_20250124"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `defer_loading?: boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `input_examples?: Array>` - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `BetaToolTextEditor20250429` - `name: "str_replace_based_edit_tool"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"str_replace_based_edit_tool"` - `type: "text_editor_20250429"` - `"text_editor_20250429"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `defer_loading?: boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `input_examples?: Array>` - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `BetaToolTextEditor20250728` - `name: "str_replace_based_edit_tool"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"str_replace_based_edit_tool"` - `type: "text_editor_20250728"` - `"text_editor_20250728"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `defer_loading?: boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `input_examples?: Array>` - `max_characters?: number | null` Maximum number of characters to display when viewing a file. If not specified, defaults to displaying the full file. - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `BetaWebSearchTool20250305` - `name: "web_search"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"web_search"` - `type: "web_search_20250305"` - `"web_search_20250305"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `allowed_domains?: Array | null` If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`. - `blocked_domains?: Array | null` If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`. - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `defer_loading?: boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `max_uses?: number | null` Maximum number of times the tool can be used in the API request. - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `user_location?: BetaUserLocation | null` Parameters for the user's location. Used to provide more relevant search results. - `type: "approximate"` - `"approximate"` - `city?: string | null` The city of the user. - `country?: string | null` The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user. - `region?: string | null` The region of the user. - `timezone?: string | null` The [IANA timezone](https://nodatime.org/TimeZones) of the user. - `BetaWebFetchTool20250910` - `name: "web_fetch"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"web_fetch"` - `type: "web_fetch_20250910"` - `"web_fetch_20250910"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `allowed_domains?: Array | null` List of domains to allow fetching from - `blocked_domains?: Array | null` List of domains to block fetching from - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `citations?: BetaCitationsConfigParam | null` Citations configuration for fetched documents. Citations are disabled by default. - `defer_loading?: boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `max_content_tokens?: number | null` Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. - `max_uses?: number | null` Maximum number of times the tool can be used in the API request. - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `BetaWebSearchTool20260209` - `name: "web_search"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"web_search"` - `type: "web_search_20260209"` - `"web_search_20260209"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `allowed_domains?: Array | null` If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`. - `blocked_domains?: Array | null` If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`. - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `defer_loading?: boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `max_uses?: number | null` Maximum number of times the tool can be used in the API request. - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `user_location?: BetaUserLocation | null` Parameters for the user's location. Used to provide more relevant search results. - `BetaWebFetchTool20260209` - `name: "web_fetch"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"web_fetch"` - `type: "web_fetch_20260209"` - `"web_fetch_20260209"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `allowed_domains?: Array | null` List of domains to allow fetching from - `blocked_domains?: Array | null` List of domains to block fetching from - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `citations?: BetaCitationsConfigParam | null` Citations configuration for fetched documents. Citations are disabled by default. - `defer_loading?: boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `max_content_tokens?: number | null` Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. - `max_uses?: number | null` Maximum number of times the tool can be used in the API request. - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `BetaWebFetchTool20260309` Web fetch tool with use_cache parameter for bypassing cached content. - `name: "web_fetch"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"web_fetch"` - `type: "web_fetch_20260309"` - `"web_fetch_20260309"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `allowed_domains?: Array | null` List of domains to allow fetching from - `blocked_domains?: Array | null` List of domains to block fetching from - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `citations?: BetaCitationsConfigParam | null` Citations configuration for fetched documents. Citations are disabled by default. - `defer_loading?: boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `max_content_tokens?: number | null` Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. - `max_uses?: number | null` Maximum number of times the tool can be used in the API request. - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `use_cache?: boolean` Whether to use cached content. Set to false to bypass the cache and fetch fresh content. Only set to false when the user explicitly requests fresh content or when fetching rapidly-changing sources. - `BetaAdvisorTool20260301` - `model: Model` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `name: "advisor"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"advisor"` - `type: "advisor_20260301"` - `"advisor_20260301"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `caching?: BetaCacheControlEphemeral | null` Caching for the advisor's own prompt. When set, each advisor call writes a cache entry at the given TTL so subsequent calls in the same conversation read the stable prefix. When omitted, the advisor prompt is not cached. - `defer_loading?: boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `max_uses?: number | null` Maximum number of times the tool can be used in the API request. - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `BetaToolSearchToolBm25_20251119` - `name: "tool_search_tool_bm25"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"tool_search_tool_bm25"` - `type: "tool_search_tool_bm25_20251119" | "tool_search_tool_bm25"` - `"tool_search_tool_bm25_20251119"` - `"tool_search_tool_bm25"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `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 - `BetaToolSearchToolRegex20251119` - `name: "tool_search_tool_regex"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"tool_search_tool_regex"` - `type: "tool_search_tool_regex_20251119" | "tool_search_tool_regex"` - `"tool_search_tool_regex_20251119"` - `"tool_search_tool_regex"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `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 - `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. - `mcp_server_name: string` Name of the MCP server to configure tools for - `type: "mcp_toolset"` - `"mcp_toolset"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `configs?: Record | null` Configuration overrides for specific tools, keyed by tool name - `defer_loading?: boolean` - `enabled?: boolean` - `default_config?: BetaMCPToolDefaultConfig` Default configuration applied to all tools from this server - `defer_loading?: boolean` - `enabled?: boolean` - `top_k?: number` Body param: Only sample from the top K options for each subsequent token. Used to remove "long tail" low probability responses. [Learn more technical details here](https://towardsdatascience.com/how-to-sample-from-language-models-682bceb97277). Recommended for advanced use cases only. - `top_p?: number` Body param: Use nucleus sampling. In nucleus sampling, we compute the cumulative distribution over all the options for each subsequent token in decreasing probability order and cut it off once it reaches a particular probability specified by `top_p`. Recommended for advanced use cases only. - `user_profile_id?: string | null` Body param: The user profile ID to attribute this request to. Use when acting on behalf of a party other than your organization. - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` - `MessageCreateParamsNonStreaming extends MessageCreateParamsBase` - `stream?: false` Body param: Whether to incrementally stream the response using server-sent events. See [streaming](https://docs.claude.com/en/api/messages-streaming) for details. - `MessageCreateParamsStreaming extends MessageCreateParamsBase` - `stream: true` Body param: Whether to incrementally stream the response using server-sent events. See [streaming](https://docs.claude.com/en/api/messages-streaming) for details. - `true` ### Returns - `BetaMessage` - `id: string` Unique object identifier. The format and length of IDs may change over time. - `container: BetaContainer | null` 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 | 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) - `"anthropic"` - `"custom"` - `version: string` Skill version or 'latest' for most recent version - `content: Array` Content generated by the model. This is an array of content blocks, each of which has a `type` that determines its shape. Example: ```json [{"type": "text", "text": "Hi, I'm Claude."}] ``` If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. For example, if the input `messages` were: ```json [ {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, {"role": "assistant", "content": "The best answer is ("} ] ``` Then the response `content` might be: ```json [{"type": "text", "text": "B)"}] ``` - `BetaTextBlock` - `citations: Array | 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`. - `BetaCitationCharLocation` - `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"` - `"char_location"` - `BetaCitationPageLocation` - `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"` - `"page_location"` - `BetaCitationContentBlockLocation` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `document_index: number` - `document_title: string | null` - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `file_id: string | null` - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. - `type: "content_block_location"` - `"content_block_location"` - `BetaCitationsWebSearchResultLocation` - `cited_text: string` - `encrypted_index: string` - `title: string | null` - `type: "web_search_result_location"` - `"web_search_result_location"` - `url: string` - `BetaCitationSearchResultLocation` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `search_result_index: number` 0-based index of the cited search result among all `search_result` content blocks in the request, in the order they appear across messages and tool results. Counted separately from `document_index`; server-side web search results are not included in this count. - `source: string` - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. - `title: string | null` - `type: "search_result_location"` - `"search_result_location"` - `text: string` - `type: "text"` - `"text"` - `BetaThinkingBlock` - `signature: string` - `thinking: string` - `type: "thinking"` - `"thinking"` - `BetaRedactedThinkingBlock` - `data: string` - `type: "redacted_thinking"` - `"redacted_thinking"` - `BetaToolUseBlock` - `id: string` - `input: Record` - `name: string` - `type: "tool_use"` - `"tool_use"` - `caller?: BetaDirectCaller | BetaServerToolCaller | BetaServerToolCaller20260120` Tool invocation directly from the model. - `BetaDirectCaller` Tool invocation directly from the model. - `type: "direct"` - `"direct"` - `BetaServerToolCaller` Tool invocation generated by a server-side tool. - `tool_id: string` - `type: "code_execution_20250825"` - `"code_execution_20250825"` - `BetaServerToolCaller20260120` - `tool_id: string` - `type: "code_execution_20260120"` - `"code_execution_20260120"` - `BetaServerToolUseBlock` - `id: string` - `input: Record` - `name: "advisor" | "web_search" | "web_fetch" | 5 more` - `"advisor"` - `"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"` - `"server_tool_use"` - `caller?: BetaDirectCaller | BetaServerToolCaller | BetaServerToolCaller20260120` Tool invocation directly from the model. - `BetaDirectCaller` Tool invocation directly from the model. - `BetaServerToolCaller` Tool invocation generated by a server-side tool. - `BetaServerToolCaller20260120` - `BetaWebSearchToolResultBlock` - `content: BetaWebSearchToolResultBlockContent` - `BetaWebSearchToolResultError` - `error_code: BetaWebSearchToolResultErrorCode` - `"invalid_tool_input"` - `"unavailable"` - `"max_uses_exceeded"` - `"too_many_requests"` - `"query_too_long"` - `"request_too_large"` - `type: "web_search_tool_result_error"` - `"web_search_tool_result_error"` - `Array` - `encrypted_content: string` - `page_age: string | null` - `title: string` - `type: "web_search_result"` - `"web_search_result"` - `url: string` - `tool_use_id: string` - `type: "web_search_tool_result"` - `"web_search_tool_result"` - `caller?: BetaDirectCaller | BetaServerToolCaller | BetaServerToolCaller20260120` Tool invocation directly from the model. - `BetaDirectCaller` Tool invocation directly from the model. - `BetaServerToolCaller` Tool invocation generated by a server-side tool. - `BetaServerToolCaller20260120` - `BetaWebFetchToolResultBlock` - `content: BetaWebFetchToolResultErrorBlock | BetaWebFetchBlock` - `BetaWebFetchToolResultErrorBlock` - `error_code: BetaWebFetchToolResultErrorCode` - `"invalid_tool_input"` - `"url_too_long"` - `"url_not_allowed"` - `"url_not_in_prior_context"` - `"url_not_accessible"` - `"unsupported_content_type"` - `"too_many_requests"` - `"max_uses_exceeded"` - `"unavailable"` - `type: "web_fetch_tool_result_error"` - `"web_fetch_tool_result_error"` - `BetaWebFetchBlock` - `content: BetaDocumentBlock` - `citations: BetaCitationConfig | null` Citation configuration for the document - `enabled: boolean` - `source: BetaBase64PDFSource | BetaPlainTextSource` - `BetaBase64PDFSource` - `data: string` - `media_type: "application/pdf"` - `"application/pdf"` - `type: "base64"` - `"base64"` - `BetaPlainTextSource` - `data: string` - `media_type: "text/plain"` - `"text/plain"` - `type: "text"` - `"text"` - `title: string | null` The title of the document - `type: "document"` - `"document"` - `retrieved_at: string | null` ISO 8601 timestamp when the content was retrieved - `type: "web_fetch_result"` - `"web_fetch_result"` - `url: string` Fetched content URL - `tool_use_id: string` - `type: "web_fetch_tool_result"` - `"web_fetch_tool_result"` - `caller?: BetaDirectCaller | BetaServerToolCaller | BetaServerToolCaller20260120` Tool invocation directly from the model. - `BetaDirectCaller` Tool invocation directly from the model. - `BetaServerToolCaller` Tool invocation generated by a server-side tool. - `BetaServerToolCaller20260120` - `BetaAdvisorToolResultBlock` - `content: BetaAdvisorToolResultError | BetaAdvisorResultBlock | BetaAdvisorRedactedResultBlock` - `BetaAdvisorToolResultError` - `error_code: "max_uses_exceeded" | "prompt_too_long" | "too_many_requests" | 3 more` - `"max_uses_exceeded"` - `"prompt_too_long"` - `"too_many_requests"` - `"overloaded"` - `"unavailable"` - `"execution_time_exceeded"` - `type: "advisor_tool_result_error"` - `"advisor_tool_result_error"` - `BetaAdvisorResultBlock` - `stop_reason: string | null` The advisor sub-inference's stop reason (same values as the top-level message `stop_reason`). `max_tokens` indicates the advisor's output was truncated at the tool's `max_tokens` value or the advisor model's policy cap. - `text: string` - `type: "advisor_result"` - `"advisor_result"` - `BetaAdvisorRedactedResultBlock` - `encrypted_content: string` Opaque blob containing the advisor's output. Round-trip verbatim; do not inspect or modify. - `stop_reason: string | null` The advisor sub-inference's stop reason (same values as the top-level message `stop_reason`). - `type: "advisor_redacted_result"` - `"advisor_redacted_result"` - `tool_use_id: string` - `type: "advisor_tool_result"` - `"advisor_tool_result"` - `BetaCodeExecutionToolResultBlock` - `content: BetaCodeExecutionToolResultBlockContent` Code execution result with encrypted stdout for PFC + web_search results. - `BetaCodeExecutionToolResultError` - `error_code: BetaCodeExecutionToolResultErrorCode` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `type: "code_execution_tool_result_error"` - `"code_execution_tool_result_error"` - `BetaCodeExecutionResultBlock` - `content: Array` - `file_id: string` - `type: "code_execution_output"` - `"code_execution_output"` - `return_code: number` - `stderr: string` - `stdout: string` - `type: "code_execution_result"` - `"code_execution_result"` - `BetaEncryptedCodeExecutionResultBlock` Code execution result with encrypted stdout for PFC + web_search results. - `content: Array` - `file_id: string` - `type: "code_execution_output"` - `encrypted_stdout: string` - `return_code: number` - `stderr: string` - `type: "encrypted_code_execution_result"` - `"encrypted_code_execution_result"` - `tool_use_id: string` - `type: "code_execution_tool_result"` - `"code_execution_tool_result"` - `BetaBashCodeExecutionToolResultBlock` - `content: BetaBashCodeExecutionToolResultError | BetaBashCodeExecutionResultBlock` - `BetaBashCodeExecutionToolResultError` - `error_code: "invalid_tool_input" | "unavailable" | "too_many_requests" | 2 more` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `"output_file_too_large"` - `type: "bash_code_execution_tool_result_error"` - `"bash_code_execution_tool_result_error"` - `BetaBashCodeExecutionResultBlock` - `content: Array` - `file_id: string` - `type: "bash_code_execution_output"` - `"bash_code_execution_output"` - `return_code: number` - `stderr: string` - `stdout: string` - `type: "bash_code_execution_result"` - `"bash_code_execution_result"` - `tool_use_id: string` - `type: "bash_code_execution_tool_result"` - `"bash_code_execution_tool_result"` - `BetaTextEditorCodeExecutionToolResultBlock` - `content: BetaTextEditorCodeExecutionToolResultError | BetaTextEditorCodeExecutionViewResultBlock | BetaTextEditorCodeExecutionCreateResultBlock | BetaTextEditorCodeExecutionStrReplaceResultBlock` - `BetaTextEditorCodeExecutionToolResultError` - `error_code: "invalid_tool_input" | "unavailable" | "too_many_requests" | 2 more` - `"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"` - `"text_editor_code_execution_tool_result_error"` - `BetaTextEditorCodeExecutionViewResultBlock` - `content: string` - `file_type: "text" | "image" | "pdf"` - `"text"` - `"image"` - `"pdf"` - `num_lines: number | null` - `start_line: number | null` - `total_lines: number | null` - `type: "text_editor_code_execution_view_result"` - `"text_editor_code_execution_view_result"` - `BetaTextEditorCodeExecutionCreateResultBlock` - `is_file_update: boolean` - `type: "text_editor_code_execution_create_result"` - `"text_editor_code_execution_create_result"` - `BetaTextEditorCodeExecutionStrReplaceResultBlock` - `lines: Array | 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"` - `"text_editor_code_execution_str_replace_result"` - `tool_use_id: string` - `type: "text_editor_code_execution_tool_result"` - `"text_editor_code_execution_tool_result"` - `BetaToolSearchToolResultBlock` - `content: BetaToolSearchToolResultError | BetaToolSearchToolSearchResultBlock` - `BetaToolSearchToolResultError` - `error_code: "invalid_tool_input" | "unavailable" | "too_many_requests" | "execution_time_exceeded"` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `error_message: string | null` - `type: "tool_search_tool_result_error"` - `"tool_search_tool_result_error"` - `BetaToolSearchToolSearchResultBlock` - `tool_references: Array` - `tool_name: string` - `type: "tool_reference"` - `"tool_reference"` - `type: "tool_search_tool_search_result"` - `"tool_search_tool_search_result"` - `tool_use_id: string` - `type: "tool_search_tool_result"` - `"tool_search_tool_result"` - `BetaMCPToolUseBlock` - `id: string` - `input: Record` - `name: string` The name of the MCP tool - `server_name: string` The name of the MCP server - `type: "mcp_tool_use"` - `"mcp_tool_use"` - `BetaMCPToolResultBlock` - `content: string | Array` - `string` - `Array` - `citations: Array | 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`. - `text: string` - `type: "text"` - `is_error: boolean` - `tool_use_id: string` - `type: "mcp_tool_result"` - `"mcp_tool_result"` - `BetaContainerUploadBlock` Response model for a file uploaded to the container. - `file_id: string` - `type: "container_upload"` - `"container_upload"` - `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. - `content: string | null` Summary of compacted content, or null if compaction failed - `encrypted_content: string | null` Opaque metadata from prior compaction, to be round-tripped verbatim - `type: "compaction"` - `"compaction"` - `context_management: BetaContextManagementResponse | null` Context management response. Information about context management strategies applied during the request. - `applied_edits: Array` List of context management edits that were applied. - `BetaClearToolUses20250919EditResponse` - `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. - `"clear_tool_uses_20250919"` - `BetaClearThinking20251015EditResponse` - `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. - `"clear_thinking_20251015"` - `diagnostics: BetaDiagnostics | null` Response envelope for request-level diagnostics. Present (possibly null) whenever the caller supplied `diagnostics` on the request. - `cache_miss_reason: BetaCacheMissModelChanged | BetaCacheMissSystemChanged | BetaCacheMissToolsChanged | 3 more | null` Explains why the prompt cache could not fully reuse the prefix from the request identified by `diagnostics.previous_message_id`. `null` means diagnosis is still pending — the response was serialized before the background comparison completed. - `BetaCacheMissModelChanged` - `cache_missed_input_tokens: number` Approximate number of input tokens that would have been read from cache had the prefix matched the previous request. - `type: "model_changed"` - `"model_changed"` - `BetaCacheMissSystemChanged` - `cache_missed_input_tokens: number` Approximate number of input tokens that would have been read from cache had the prefix matched the previous request. - `type: "system_changed"` - `"system_changed"` - `BetaCacheMissToolsChanged` - `cache_missed_input_tokens: number` Approximate number of input tokens that would have been read from cache had the prefix matched the previous request. - `type: "tools_changed"` - `"tools_changed"` - `BetaCacheMissMessagesChanged` - `cache_missed_input_tokens: number` Approximate number of input tokens that would have been read from cache had the prefix matched the previous request. - `type: "messages_changed"` - `"messages_changed"` - `BetaCacheMissPreviousMessageNotFound` - `type: "previous_message_not_found"` - `"previous_message_not_found"` - `BetaCacheMissUnavailable` - `type: "unavailable"` - `"unavailable"` - `model: Model` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-opus-4-8" | "claude-opus-4-7" | "claude-mythos-preview" | 15 more` - `"claude-opus-4-8"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-7"` Frontier intelligence for long-running agents and coding - `"claude-mythos-preview"` New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` Fastest model with near-frontier intelligence - `"claude-haiku-4-5-20251001"` Fastest model with near-frontier intelligence - `"claude-opus-4-5"` Premium model combining maximum intelligence with practical performance - `"claude-opus-4-5-20251101"` Premium model combining maximum intelligence with practical performance - `"claude-sonnet-4-5"` High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` High-performance model for agents and coding - `"claude-opus-4-1"` Exceptional model for specialized complex tasks - `"claude-opus-4-1-20250805"` Exceptional model for specialized complex tasks - `"claude-opus-4-0"` Powerful model for complex tasks - `"claude-opus-4-20250514"` Powerful model for complex tasks - `"claude-sonnet-4-0"` High-performance model with extended thinking - `"claude-sonnet-4-20250514"` High-performance model with extended thinking - `"claude-3-haiku-20240307"` Fast and cost-effective model - `(string & {})` - `role: "assistant"` Conversational role of the generated message. This will always be `"assistant"`. - `"assistant"` - `stop_details: BetaRefusalStopDetails | null` Structured information about a refusal. - `category: "cyber" | "bio" | null` The policy category that triggered the refusal. `null` when the refusal doesn't map to a named category. - `"cyber"` - `"bio"` - `explanation: string | null` Human-readable explanation of the refusal. This text is not guaranteed to be stable. `null` when no explanation is available for the category. - `type: "refusal"` - `"refusal"` - `stop_reason: BetaStopReason | null` The reason that we stopped. This may be one the following values: * `"end_turn"`: the model reached a natural stopping point * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated * `"tool_use"`: the model invoked one or more tools * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. * `"refusal"`: when streaming classifiers intervene to handle potential policy violations In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. - `"end_turn"` - `"max_tokens"` - `"stop_sequence"` - `"tool_use"` - `"pause_turn"` - `"compaction"` - `"refusal"` - `"model_context_window_exceeded"` - `stop_sequence: string | null` Which custom stop sequence was generated, if any. This value will be a non-null string if one of your custom stop sequences was generated. - `type: "message"` Object type. For Messages, this is always `"message"`. - `"message"` - `usage: BetaUsage` Billing and rate-limit usage. Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. For example, `output_tokens` will be non-zero, even for an empty string response from Claude. Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. - `cache_creation: BetaCacheCreation | null` Breakdown of cached tokens by TTL - `ephemeral_1h_input_tokens: number` The number of input tokens used to create the 1 hour cache entry. - `ephemeral_5m_input_tokens: number` The number of input tokens used to create the 5 minute cache entry. - `cache_creation_input_tokens: number | null` The number of input tokens used to create the cache entry. - `cache_read_input_tokens: number | null` The number of input tokens read from the cache. - `inference_geo: string | null` The geographic region where inference was performed for this request. - `input_tokens: number` The number of input tokens which were used. - `iterations: BetaIterationsUsage | null` Per-iteration token usage breakdown. Each entry represents one sampling iteration, with its own input/output token counts and cache statistics. This allows you to: - Determine which iterations exceeded long context thresholds (>=200k tokens) - Calculate the true context window size from the last iteration - Understand token accumulation across server-side tool use loops - `BetaMessageIterationUsage` Token usage for a sampling iteration. - `cache_creation: BetaCacheCreation | null` Breakdown of cached tokens by TTL - `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: "message"` Usage for a sampling iteration - `"message"` - `BetaCompactionIterationUsage` Token usage for a compaction iteration. - `cache_creation: BetaCacheCreation | null` Breakdown of cached tokens by TTL - `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 - `"compaction"` - `BetaAdvisorMessageIterationUsage` Token usage for an advisor sub-inference iteration. - `cache_creation: BetaCacheCreation | null` Breakdown of cached tokens by TTL - `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. - `model: Model` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `output_tokens: number` The number of output tokens which were used. - `type: "advisor_message"` Usage for an advisor sub-inference iteration - `"advisor_message"` - `output_tokens: number` The number of output tokens which were used. - `output_tokens_details: BetaOutputTokensDetails | null` Breakdown of output tokens by category. `output_tokens` remains the inclusive, authoritative total used for billing. This object provides a read-only decomposition for observability — for example, how many of the billed output tokens were spent on internal reasoning that may have been summarized before being returned to you. - `thinking_tokens: number` Number of output tokens the model generated as internal reasoning, including the thinking-block delimiter tokens. Reflects the raw reasoning the model produced, not the (possibly shorter) summarized thinking text returned in the response body. Computed by re-tokenizing the raw reasoning text, so it may differ from the model's exact generation count by a small number of tokens. Always ≤ `output_tokens`; `output_tokens - thinking_tokens` approximates the non-reasoning output. - `server_tool_use: BetaServerToolUsage | null` The number of server tool requests. - `web_fetch_requests: number` The number of web fetch tool requests. - `web_search_requests: number` The number of web search tool requests. - `service_tier: "standard" | "priority" | "batch" | null` If the request used the priority, standard, or batch tier. - `"standard"` - `"priority"` - `"batch"` - `speed: "standard" | "fast" | null` The inference speed mode used for this request. - `"standard"` - `"fast"` ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const betaMessage = await client.beta.messages.create({ max_tokens: 1024, messages: [{ content: 'Hello, world', role: 'user' }], model: 'claude-opus-4-6', }); console.log(betaMessage.id); ``` #### Response ```json { "id": "msg_013Zva2CMHLNnXjNJJKqJ2EF", "container": { "id": "id", "expires_at": "2019-12-27T18:11:19.117Z", "skills": [ { "skill_id": "pdf", "type": "anthropic", "version": "latest" } ] }, "content": [ { "citations": [ { "cited_text": "cited_text", "document_index": 0, "document_title": "document_title", "end_char_index": 0, "file_id": "file_id", "start_char_index": 0, "type": "char_location" } ], "text": "Hi! My name is Claude.", "type": "text" } ], "context_management": { "applied_edits": [ { "cleared_input_tokens": 0, "cleared_tool_uses": 0, "type": "clear_tool_uses_20250919" } ] }, "diagnostics": { "cache_miss_reason": { "cache_missed_input_tokens": 0, "type": "model_changed" } }, "model": "claude-opus-4-6", "role": "assistant", "stop_details": { "category": "cyber", "explanation": "explanation", "type": "refusal" }, "stop_reason": "end_turn", "stop_sequence": null, "type": "message", "usage": { "cache_creation": { "ephemeral_1h_input_tokens": 0, "ephemeral_5m_input_tokens": 0 }, "cache_creation_input_tokens": 2051, "cache_read_input_tokens": 2051, "inference_geo": "inference_geo", "input_tokens": 2095, "iterations": [ { "cache_creation": { "ephemeral_1h_input_tokens": 0, "ephemeral_5m_input_tokens": 0 }, "cache_creation_input_tokens": 0, "cache_read_input_tokens": 0, "input_tokens": 0, "output_tokens": 0, "type": "message" } ], "output_tokens": 503, "output_tokens_details": { "thinking_tokens": 0 }, "server_tool_use": { "web_fetch_requests": 2, "web_search_requests": 0 }, "service_tier": "standard", "speed": "standard" } } ``` ## Count tokens in a Message `client.beta.messages.countTokens(MessageCountTokensParamsparams, RequestOptionsoptions?): BetaMessageTokensCount` **post** `/v1/messages/count_tokens` Count the number of tokens in a Message. The Token Count API can be used to count the number of tokens in a Message, including tools, images, and documents, without creating it. Learn more about token counting in our [user guide](https://docs.claude.com/en/docs/build-with-claude/token-counting) ### Parameters - `params: MessageCountTokensParams` - `messages: Array` Body param: Input messages. Our models are trained to operate on alternating `user` and `assistant` conversational turns. When creating a new `Message`, you specify the prior conversational turns with the `messages` parameter, and the model then generates the next `Message` in the conversation. Consecutive `user` or `assistant` turns in your request will be combined into a single turn. Each input message must be an object with a `role` and `content`. You can specify a single `user`-role message, or you can include multiple `user` and `assistant` messages. If the final message uses the `assistant` role, the response content will continue immediately from the content in that message. This can be used to constrain part of the model's response. Example with a single `user` message: ```json [{"role": "user", "content": "Hello, Claude"}] ``` Example with multiple conversational turns: ```json [ {"role": "user", "content": "Hello there."}, {"role": "assistant", "content": "Hi, I'm Claude. How can I help you?"}, {"role": "user", "content": "Can you explain LLMs in plain English?"}, ] ``` Example with a partially-filled response from Claude: ```json [ {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, {"role": "assistant", "content": "The best answer is ("}, ] ``` Each input message `content` may be either a single `string` or an array of content blocks, where each block has a specific `type`. Using a `string` for `content` is shorthand for an array of one content block of type `"text"`. The following input messages are equivalent: ```json {"role": "user", "content": "Hello, Claude"} ``` ```json {"role": "user", "content": [{"type": "text", "text": "Hello, Claude"}]} ``` See [input examples](https://docs.claude.com/en/api/messages-examples). Note that if you want to include a [system prompt](https://docs.claude.com/en/docs/system-prompts), you can use the top-level `system` parameter — there is no `"system"` role for input messages in the Messages API. There is a limit of 100,000 messages in a single request. - `content: string | Array` - `string` - `Array` - `BetaTextBlockParam` - `text: string` - `type: "text"` - `"text"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `"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`. - `"5m"` - `"1h"` - `citations?: Array | null` - `BetaCitationCharLocationParam` - `cited_text: string` - `document_index: number` - `document_title: string | null` - `end_char_index: number` - `start_char_index: number` - `type: "char_location"` - `"char_location"` - `BetaCitationPageLocationParam` - `cited_text: string` - `document_index: number` - `document_title: string | null` - `end_page_number: number` - `start_page_number: number` - `type: "page_location"` - `"page_location"` - `BetaCitationContentBlockLocationParam` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `document_index: number` - `document_title: string | null` - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. - `type: "content_block_location"` - `"content_block_location"` - `BetaCitationWebSearchResultLocationParam` - `cited_text: string` - `encrypted_index: string` - `title: string | null` - `type: "web_search_result_location"` - `"web_search_result_location"` - `url: string` - `BetaCitationSearchResultLocationParam` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `search_result_index: number` 0-based index of the cited search result among all `search_result` content blocks in the request, in the order they appear across messages and tool results. Counted separately from `document_index`; server-side web search results are not included in this count. - `source: string` - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. - `title: string | null` - `type: "search_result_location"` - `"search_result_location"` - `BetaImageBlockParam` - `source: BetaBase64ImageSource | BetaURLImageSource | BetaFileImageSource` - `BetaBase64ImageSource` - `data: string` - `media_type: "image/jpeg" | "image/png" | "image/gif" | "image/webp"` - `"image/jpeg"` - `"image/png"` - `"image/gif"` - `"image/webp"` - `type: "base64"` - `"base64"` - `BetaURLImageSource` - `type: "url"` - `"url"` - `url: string` - `BetaFileImageSource` - `file_id: string` - `type: "file"` - `"file"` - `type: "image"` - `"image"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `BetaRequestDocumentBlock` - `source: BetaBase64PDFSource | BetaPlainTextSource | BetaContentBlockSource | 2 more` - `BetaBase64PDFSource` - `data: string` - `media_type: "application/pdf"` - `"application/pdf"` - `type: "base64"` - `"base64"` - `BetaPlainTextSource` - `data: string` - `media_type: "text/plain"` - `"text/plain"` - `type: "text"` - `"text"` - `BetaContentBlockSource` - `content: string | Array` - `string` - `Array` - `BetaTextBlockParam` - `BetaImageBlockParam` - `type: "content"` - `"content"` - `BetaURLPDFSource` - `type: "url"` - `"url"` - `url: string` - `BetaFileDocumentSource` - `file_id: string` - `type: "file"` - `"file"` - `type: "document"` - `"document"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `citations?: BetaCitationsConfigParam | null` - `enabled?: boolean` - `context?: string | null` - `title?: string | null` - `BetaSearchResultBlockParam` - `content: Array` - `text: string` - `type: "text"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `citations?: Array | null` - `source: string` - `title: string` - `type: "search_result"` - `"search_result"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `citations?: BetaCitationsConfigParam` - `BetaThinkingBlockParam` - `signature: string` - `thinking: string` - `type: "thinking"` - `"thinking"` - `BetaRedactedThinkingBlockParam` - `data: string` - `type: "redacted_thinking"` - `"redacted_thinking"` - `BetaToolUseBlockParam` - `id: string` - `input: Record` - `name: string` - `type: "tool_use"` - `"tool_use"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `caller?: BetaDirectCaller | BetaServerToolCaller | BetaServerToolCaller20260120` Tool invocation directly from the model. - `BetaDirectCaller` Tool invocation directly from the model. - `type: "direct"` - `"direct"` - `BetaServerToolCaller` Tool invocation generated by a server-side tool. - `tool_id: string` - `type: "code_execution_20250825"` - `"code_execution_20250825"` - `BetaServerToolCaller20260120` - `tool_id: string` - `type: "code_execution_20260120"` - `"code_execution_20260120"` - `BetaToolResultBlockParam` - `tool_use_id: string` - `type: "tool_result"` - `"tool_result"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `content?: string | Array` - `string` - `Array` - `BetaTextBlockParam` - `BetaImageBlockParam` - `BetaSearchResultBlockParam` - `BetaRequestDocumentBlock` - `BetaToolReferenceBlockParam` Tool reference block that can be included in tool_result content. - `tool_name: string` - `type: "tool_reference"` - `"tool_reference"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `is_error?: boolean` - `BetaServerToolUseBlockParam` - `id: string` - `input: Record` - `name: "advisor" | "web_search" | "web_fetch" | 5 more` - `"advisor"` - `"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"` - `"server_tool_use"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `caller?: BetaDirectCaller | BetaServerToolCaller | BetaServerToolCaller20260120` Tool invocation directly from the model. - `BetaDirectCaller` Tool invocation directly from the model. - `BetaServerToolCaller` Tool invocation generated by a server-side tool. - `BetaServerToolCaller20260120` - `BetaWebSearchToolResultBlockParam` - `content: BetaWebSearchToolResultBlockParamContent` - `Array` - `encrypted_content: string` - `title: string` - `type: "web_search_result"` - `"web_search_result"` - `url: string` - `page_age?: string | null` - `BetaWebSearchToolRequestError` - `error_code: BetaWebSearchToolResultErrorCode` - `"invalid_tool_input"` - `"unavailable"` - `"max_uses_exceeded"` - `"too_many_requests"` - `"query_too_long"` - `"request_too_large"` - `type: "web_search_tool_result_error"` - `"web_search_tool_result_error"` - `tool_use_id: string` - `type: "web_search_tool_result"` - `"web_search_tool_result"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `caller?: BetaDirectCaller | BetaServerToolCaller | BetaServerToolCaller20260120` Tool invocation directly from the model. - `BetaDirectCaller` Tool invocation directly from the model. - `BetaServerToolCaller` Tool invocation generated by a server-side tool. - `BetaServerToolCaller20260120` - `BetaWebFetchToolResultBlockParam` - `content: BetaWebFetchToolResultErrorBlockParam | BetaWebFetchBlockParam` - `BetaWebFetchToolResultErrorBlockParam` - `error_code: BetaWebFetchToolResultErrorCode` - `"invalid_tool_input"` - `"url_too_long"` - `"url_not_allowed"` - `"url_not_in_prior_context"` - `"url_not_accessible"` - `"unsupported_content_type"` - `"too_many_requests"` - `"max_uses_exceeded"` - `"unavailable"` - `type: "web_fetch_tool_result_error"` - `"web_fetch_tool_result_error"` - `BetaWebFetchBlockParam` - `content: BetaRequestDocumentBlock` - `type: "web_fetch_result"` - `"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"` - `"web_fetch_tool_result"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `caller?: BetaDirectCaller | BetaServerToolCaller | BetaServerToolCaller20260120` Tool invocation directly from the model. - `BetaDirectCaller` Tool invocation directly from the model. - `BetaServerToolCaller` Tool invocation generated by a server-side tool. - `BetaServerToolCaller20260120` - `BetaAdvisorToolResultBlockParam` - `content: BetaAdvisorToolResultErrorParam | BetaAdvisorResultBlockParam | BetaAdvisorRedactedResultBlockParam` - `BetaAdvisorToolResultErrorParam` - `error_code: "max_uses_exceeded" | "prompt_too_long" | "too_many_requests" | 3 more` - `"max_uses_exceeded"` - `"prompt_too_long"` - `"too_many_requests"` - `"overloaded"` - `"unavailable"` - `"execution_time_exceeded"` - `type: "advisor_tool_result_error"` - `"advisor_tool_result_error"` - `BetaAdvisorResultBlockParam` - `text: string` - `type: "advisor_result"` - `"advisor_result"` - `stop_reason?: string | null` - `BetaAdvisorRedactedResultBlockParam` - `encrypted_content: string` Opaque blob produced by a prior response; must be round-tripped verbatim. - `type: "advisor_redacted_result"` - `"advisor_redacted_result"` - `stop_reason?: string | null` - `tool_use_id: string` - `type: "advisor_tool_result"` - `"advisor_tool_result"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `BetaCodeExecutionToolResultBlockParam` - `content: BetaCodeExecutionToolResultBlockParamContent` Code execution result with encrypted stdout for PFC + web_search results. - `BetaCodeExecutionToolResultErrorParam` - `error_code: BetaCodeExecutionToolResultErrorCode` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `type: "code_execution_tool_result_error"` - `"code_execution_tool_result_error"` - `BetaCodeExecutionResultBlockParam` - `content: Array` - `file_id: string` - `type: "code_execution_output"` - `"code_execution_output"` - `return_code: number` - `stderr: string` - `stdout: string` - `type: "code_execution_result"` - `"code_execution_result"` - `BetaEncryptedCodeExecutionResultBlockParam` Code execution result with encrypted stdout for PFC + web_search results. - `content: Array` - `file_id: string` - `type: "code_execution_output"` - `encrypted_stdout: string` - `return_code: number` - `stderr: string` - `type: "encrypted_code_execution_result"` - `"encrypted_code_execution_result"` - `tool_use_id: string` - `type: "code_execution_tool_result"` - `"code_execution_tool_result"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `BetaBashCodeExecutionToolResultBlockParam` - `content: BetaBashCodeExecutionToolResultErrorParam | BetaBashCodeExecutionResultBlockParam` - `BetaBashCodeExecutionToolResultErrorParam` - `error_code: "invalid_tool_input" | "unavailable" | "too_many_requests" | 2 more` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `"output_file_too_large"` - `type: "bash_code_execution_tool_result_error"` - `"bash_code_execution_tool_result_error"` - `BetaBashCodeExecutionResultBlockParam` - `content: Array` - `file_id: string` - `type: "bash_code_execution_output"` - `"bash_code_execution_output"` - `return_code: number` - `stderr: string` - `stdout: string` - `type: "bash_code_execution_result"` - `"bash_code_execution_result"` - `tool_use_id: string` - `type: "bash_code_execution_tool_result"` - `"bash_code_execution_tool_result"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `BetaTextEditorCodeExecutionToolResultBlockParam` - `content: BetaTextEditorCodeExecutionToolResultErrorParam | BetaTextEditorCodeExecutionViewResultBlockParam | BetaTextEditorCodeExecutionCreateResultBlockParam | BetaTextEditorCodeExecutionStrReplaceResultBlockParam` - `BetaTextEditorCodeExecutionToolResultErrorParam` - `error_code: "invalid_tool_input" | "unavailable" | "too_many_requests" | 2 more` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `"file_not_found"` - `type: "text_editor_code_execution_tool_result_error"` - `"text_editor_code_execution_tool_result_error"` - `error_message?: string | null` - `BetaTextEditorCodeExecutionViewResultBlockParam` - `content: string` - `file_type: "text" | "image" | "pdf"` - `"text"` - `"image"` - `"pdf"` - `type: "text_editor_code_execution_view_result"` - `"text_editor_code_execution_view_result"` - `num_lines?: number | null` - `start_line?: number | null` - `total_lines?: number | null` - `BetaTextEditorCodeExecutionCreateResultBlockParam` - `is_file_update: boolean` - `type: "text_editor_code_execution_create_result"` - `"text_editor_code_execution_create_result"` - `BetaTextEditorCodeExecutionStrReplaceResultBlockParam` - `type: "text_editor_code_execution_str_replace_result"` - `"text_editor_code_execution_str_replace_result"` - `lines?: Array | 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"` - `"text_editor_code_execution_tool_result"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `BetaToolSearchToolResultBlockParam` - `content: BetaToolSearchToolResultErrorParam | BetaToolSearchToolSearchResultBlockParam` - `BetaToolSearchToolResultErrorParam` - `error_code: "invalid_tool_input" | "unavailable" | "too_many_requests" | "execution_time_exceeded"` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `type: "tool_search_tool_result_error"` - `"tool_search_tool_result_error"` - `BetaToolSearchToolSearchResultBlockParam` - `tool_references: Array` - `tool_name: string` - `type: "tool_reference"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `type: "tool_search_tool_search_result"` - `"tool_search_tool_search_result"` - `tool_use_id: string` - `type: "tool_search_tool_result"` - `"tool_search_tool_result"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `BetaMCPToolUseBlockParam` - `id: string` - `input: Record` - `name: string` - `server_name: string` The name of the MCP server - `type: "mcp_tool_use"` - `"mcp_tool_use"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `BetaRequestMCPToolResultBlockParam` - `tool_use_id: string` - `type: "mcp_tool_result"` - `"mcp_tool_result"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `content?: string | Array` - `string` - `Array` - `text: string` - `type: "text"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `citations?: Array | null` - `is_error?: boolean` - `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. - `file_id: string` - `type: "container_upload"` - `"container_upload"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `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. - `type: "compaction"` - `"compaction"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `content?: string | null` Summary of previously compacted content, or null if compaction failed - `encrypted_content?: string | null` Opaque metadata from prior compaction, to be round-tripped verbatim - `BetaMidConversationSystemBlockParam` System instructions that appear mid-conversation. Use this block to provide or update system-level instructions at a specific point in the conversation, rather than only via the top-level `system` parameter. - `content: Array` System instruction text blocks. - `text: string` - `type: "text"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `citations?: Array | null` - `type: "mid_conv_system"` - `"mid_conv_system"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `role: "user" | "assistant" | "system"` - `"user"` - `"assistant"` - `"system"` - `model: Model` Body param: The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-opus-4-8" | "claude-opus-4-7" | "claude-mythos-preview" | 15 more` - `"claude-opus-4-8"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-7"` Frontier intelligence for long-running agents and coding - `"claude-mythos-preview"` New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` Fastest model with near-frontier intelligence - `"claude-haiku-4-5-20251001"` Fastest model with near-frontier intelligence - `"claude-opus-4-5"` Premium model combining maximum intelligence with practical performance - `"claude-opus-4-5-20251101"` Premium model combining maximum intelligence with practical performance - `"claude-sonnet-4-5"` High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` High-performance model for agents and coding - `"claude-opus-4-1"` Exceptional model for specialized complex tasks - `"claude-opus-4-1-20250805"` Exceptional model for specialized complex tasks - `"claude-opus-4-0"` Powerful model for complex tasks - `"claude-opus-4-20250514"` Powerful model for complex tasks - `"claude-sonnet-4-0"` High-performance model with extended thinking - `"claude-sonnet-4-20250514"` High-performance model with extended thinking - `"claude-3-haiku-20240307"` Fast and cost-effective model - `(string & {})` - `cache_control?: BetaCacheControlEphemeral | null` Body param: Top-level cache control automatically applies a cache_control marker to the last cacheable block in the request. - `context_management?: BetaContextManagementConfig | null` Body param: Context management configuration. This allows you to control how Claude manages context across multiple requests, such as whether to clear function results or not. - `edits?: Array` List of context management edits to apply - `BetaClearToolUses20250919Edit` - `type: "clear_tool_uses_20250919"` - `"clear_tool_uses_20250919"` - `clear_at_least?: BetaInputTokensClearAtLeast | 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"` - `"input_tokens"` - `value: number` - `clear_tool_inputs?: boolean | Array | null` Whether to clear all tool inputs (bool) or specific tool inputs to clear (list) - `boolean` - `Array` - `exclude_tools?: Array | null` Tool names whose uses are preserved from clearing - `keep?: BetaToolUsesKeep` Number of tool uses to retain in the conversation - `type: "tool_uses"` - `"tool_uses"` - `value: number` - `trigger?: BetaInputTokensTrigger | BetaToolUsesTrigger` Condition that triggers the context management strategy - `BetaInputTokensTrigger` - `type: "input_tokens"` - `"input_tokens"` - `value: number` - `BetaToolUsesTrigger` - `type: "tool_uses"` - `"tool_uses"` - `value: number` - `BetaClearThinking20251015Edit` - `type: "clear_thinking_20251015"` - `"clear_thinking_20251015"` - `keep?: BetaThinkingTurns | BetaAllThinkingTurns | "all"` Number of most recent assistant turns to keep thinking blocks for. Older turns will have their thinking blocks removed. - `BetaThinkingTurns` - `type: "thinking_turns"` - `"thinking_turns"` - `value: number` - `BetaAllThinkingTurns` - `type: "all"` - `"all"` - `"all"` - `"all"` - `BetaCompact20260112Edit` Automatically compact older context when reaching the configured trigger threshold. - `type: "compact_20260112"` - `"compact_20260112"` - `instructions?: string | null` Additional instructions for summarization. - `pause_after_compaction?: boolean` Whether to pause after compaction and return the compaction block to the user. - `trigger?: BetaInputTokensTrigger | null` When to trigger compaction. Defaults to 150000 input tokens. - `mcp_servers?: Array` Body param: MCP servers to be utilized in this request - `name: string` - `type: "url"` - `"url"` - `url: string` - `authorization_token?: string | null` - `tool_configuration?: BetaRequestMCPServerToolConfiguration | null` - `allowed_tools?: Array | null` - `enabled?: boolean | null` - `output_config?: BetaOutputConfig` Body param: Configuration options for the model's output, such as the output format. - `effort?: "low" | "medium" | "high" | 2 more | null` All possible effort levels. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `format?: BetaJSONOutputFormat | null` A schema to specify Claude's output format in responses. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) - `schema: Record` The JSON schema of the format - `type: "json_schema"` - `"json_schema"` - `task_budget?: BetaTokenTaskBudget | null` User-configurable total token budget across contexts. - `total: number` Total token budget across all contexts in the session. - `type: "tokens"` The budget type. Currently only 'tokens' is supported. - `"tokens"` - `remaining?: number | null` Remaining tokens in the budget. Use this to track usage across contexts when implementing compaction client-side. Defaults to total if not provided. - `output_format?: BetaJSONOutputFormat | null` Body param: Deprecated: Use `output_config.format` instead. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) A schema to specify Claude's output format in responses. This parameter will be removed in a future release. - `speed?: "standard" | "fast" | null` Body param: The inference speed mode for this request. `"fast"` enables high output-tokens-per-second inference. - `"standard"` - `"fast"` - `system?: string | Array` Body param: System prompt. A system prompt is a way of providing context and instructions to Claude, such as specifying a particular goal or role. See our [guide to system prompts](https://docs.claude.com/en/docs/system-prompts). - `string` - `Array` - `text: string` - `type: "text"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `citations?: Array | null` - `thinking?: BetaThinkingConfigParam` Body param: 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](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) for details. - `BetaThinkingConfigEnabled` - `budget_tokens: number` 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](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) for details. - `type: "enabled"` - `"enabled"` - `display?: "summarized" | "omitted" | null` Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. Defaults to `summarized`. - `"summarized"` - `"omitted"` - `BetaThinkingConfigDisabled` - `type: "disabled"` - `"disabled"` - `BetaThinkingConfigAdaptive` - `type: "adaptive"` - `"adaptive"` - `display?: "summarized" | "omitted" | null` Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. Defaults to `summarized`. - `"summarized"` - `"omitted"` - `tool_choice?: BetaToolChoice` Body param: 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. - `BetaToolChoiceAuto` The model will automatically decide whether to use tools. - `type: "auto"` - `"auto"` - `disable_parallel_tool_use?: boolean` Whether to disable parallel tool use. Defaults to `false`. If set to `true`, the model will output at most one tool use. - `BetaToolChoiceAny` The model will use any available tools. - `type: "any"` - `"any"` - `disable_parallel_tool_use?: boolean` Whether to disable parallel tool use. Defaults to `false`. If set to `true`, the model will output exactly one tool use. - `BetaToolChoiceTool` The model will use the specified tool with `tool_choice.name`. - `name: string` The name of the tool to use. - `type: "tool"` - `"tool"` - `disable_parallel_tool_use?: boolean` Whether to disable parallel tool use. Defaults to `false`. If set to `true`, the model will output exactly one tool use. - `BetaToolChoiceNone` The model will not be allowed to use tools. - `type: "none"` - `"none"` - `tools?: Array` Body param: Definitions of tools that the model may use. If you include `tools` in your API request, the model may return `tool_use` content blocks that represent the model's use of those tools. You can then run those tools using the tool input generated by the model and then optionally return results back to the model using `tool_result` content blocks. There are two types of tools: **client tools** and **server tools**. The behavior described below applies to client tools. For [server tools](https://docs.claude.com/en/docs/agents-and-tools/tool-use/overview#server-tools), see their individual documentation as each has its own behavior (e.g., the [web search tool](https://docs.claude.com/en/docs/agents-and-tools/tool-use/web-search-tool)). Each tool definition includes: * `name`: Name of the tool. * `description`: Optional, but strongly-recommended description of the tool. * `input_schema`: [JSON schema](https://json-schema.org/draft/2020-12) for the tool `input` shape that the model will produce in `tool_use` output content blocks. For example, if you defined `tools` as: ```json [ { "name": "get_stock_price", "description": "Get the current stock price for a given ticker symbol.", "input_schema": { "type": "object", "properties": { "ticker": { "type": "string", "description": "The stock ticker symbol, e.g. AAPL for Apple Inc." } }, "required": ["ticker"] } } ] ``` And then asked the model "What's the S&P 500 at today?", the model might produce `tool_use` content blocks in the response like this: ```json [ { "type": "tool_use", "id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", "name": "get_stock_price", "input": { "ticker": "^GSPC" } } ] ``` You might then run your `get_stock_price` tool with `{"ticker": "^GSPC"}` as an input, and return the following back to the model in a subsequent `user` message: ```json [ { "type": "tool_result", "tool_use_id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", "content": "259.75 USD" } ] ``` Tools can be used for workflows that include running client-side tools and functions, or more generally whenever you want the model to produce a particular JSON structure of output. See our [guide](https://docs.claude.com/en/docs/tool-use) for more details. - `BetaTool` - `input_schema: InputSchema` [JSON schema](https://json-schema.org/draft/2020-12) for this tool's input. This defines the shape of the `input` that your tool accepts and that the model will produce. - `type: "object"` - `"object"` - `properties?: Record | null` - `required?: Array | null` - `name: string` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `defer_loading?: boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `description?: string` Description of what this tool does. Tool descriptions should be as detailed as possible. The more information that the model has about what the tool is and how to use it, the better it will perform. You can use natural language descriptions to reinforce important aspects of the tool input JSON schema. - `eager_input_streaming?: boolean | null` Enable eager input streaming for this tool. When true, tool input parameters will be streamed incrementally as they are generated, and types will be inferred on-the-fly rather than buffering the full JSON output. When false, streaming is disabled for this tool even if the fine-grained-tool-streaming beta is active. When null (default), uses the default behavior based on beta headers. - `input_examples?: Array>` - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `type?: "custom" | null` - `"custom"` - `BetaToolBash20241022` - `name: "bash"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"bash"` - `type: "bash_20241022"` - `"bash_20241022"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `defer_loading?: boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `input_examples?: Array>` - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `BetaToolBash20250124` - `name: "bash"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"bash"` - `type: "bash_20250124"` - `"bash_20250124"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `defer_loading?: boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `input_examples?: Array>` - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `BetaCodeExecutionTool20250522` - `name: "code_execution"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"code_execution"` - `type: "code_execution_20250522"` - `"code_execution_20250522"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `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: "code_execution"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"code_execution"` - `type: "code_execution_20250825"` - `"code_execution_20250825"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `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` Code execution tool with REPL state persistence (daemon mode + gVisor checkpoint). - `name: "code_execution"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"code_execution"` - `type: "code_execution_20260120"` - `"code_execution_20260120"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `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 - `BetaToolComputerUse20241022` - `display_height_px: number` The height of the display in pixels. - `display_width_px: number` The width of the display in pixels. - `name: "computer"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"computer"` - `type: "computer_20241022"` - `"computer_20241022"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `defer_loading?: boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `display_number?: number | null` The X11 display number (e.g. 0, 1) for the display. - `input_examples?: Array>` - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `BetaMemoryTool20250818` - `name: "memory"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"memory"` - `type: "memory_20250818"` - `"memory_20250818"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `defer_loading?: boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `input_examples?: Array>` - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `BetaToolComputerUse20250124` - `display_height_px: number` The height of the display in pixels. - `display_width_px: number` The width of the display in pixels. - `name: "computer"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"computer"` - `type: "computer_20250124"` - `"computer_20250124"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `defer_loading?: boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `display_number?: number | null` The X11 display number (e.g. 0, 1) for the display. - `input_examples?: Array>` - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `BetaToolTextEditor20241022` - `name: "str_replace_editor"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"str_replace_editor"` - `type: "text_editor_20241022"` - `"text_editor_20241022"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `defer_loading?: boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `input_examples?: Array>` - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `BetaToolComputerUse20251124` - `display_height_px: number` The height of the display in pixels. - `display_width_px: number` The width of the display in pixels. - `name: "computer"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"computer"` - `type: "computer_20251124"` - `"computer_20251124"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `defer_loading?: boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `display_number?: number | null` The X11 display number (e.g. 0, 1) for the display. - `enable_zoom?: boolean` Whether to enable an action to take a zoomed-in screenshot of the screen. - `input_examples?: Array>` - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `BetaToolTextEditor20250124` - `name: "str_replace_editor"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"str_replace_editor"` - `type: "text_editor_20250124"` - `"text_editor_20250124"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `defer_loading?: boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `input_examples?: Array>` - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `BetaToolTextEditor20250429` - `name: "str_replace_based_edit_tool"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"str_replace_based_edit_tool"` - `type: "text_editor_20250429"` - `"text_editor_20250429"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `defer_loading?: boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `input_examples?: Array>` - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `BetaToolTextEditor20250728` - `name: "str_replace_based_edit_tool"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"str_replace_based_edit_tool"` - `type: "text_editor_20250728"` - `"text_editor_20250728"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `defer_loading?: boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `input_examples?: Array>` - `max_characters?: number | null` Maximum number of characters to display when viewing a file. If not specified, defaults to displaying the full file. - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `BetaWebSearchTool20250305` - `name: "web_search"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"web_search"` - `type: "web_search_20250305"` - `"web_search_20250305"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `allowed_domains?: Array | null` If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`. - `blocked_domains?: Array | null` If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`. - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `defer_loading?: boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `max_uses?: number | null` Maximum number of times the tool can be used in the API request. - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `user_location?: BetaUserLocation | null` Parameters for the user's location. Used to provide more relevant search results. - `type: "approximate"` - `"approximate"` - `city?: string | null` The city of the user. - `country?: string | null` The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user. - `region?: string | null` The region of the user. - `timezone?: string | null` The [IANA timezone](https://nodatime.org/TimeZones) of the user. - `BetaWebFetchTool20250910` - `name: "web_fetch"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"web_fetch"` - `type: "web_fetch_20250910"` - `"web_fetch_20250910"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `allowed_domains?: Array | null` List of domains to allow fetching from - `blocked_domains?: Array | null` List of domains to block fetching from - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `citations?: BetaCitationsConfigParam | null` Citations configuration for fetched documents. Citations are disabled by default. - `defer_loading?: boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `max_content_tokens?: number | null` Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. - `max_uses?: number | null` Maximum number of times the tool can be used in the API request. - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `BetaWebSearchTool20260209` - `name: "web_search"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"web_search"` - `type: "web_search_20260209"` - `"web_search_20260209"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `allowed_domains?: Array | null` If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`. - `blocked_domains?: Array | null` If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`. - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `defer_loading?: boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `max_uses?: number | null` Maximum number of times the tool can be used in the API request. - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `user_location?: BetaUserLocation | null` Parameters for the user's location. Used to provide more relevant search results. - `BetaWebFetchTool20260209` - `name: "web_fetch"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"web_fetch"` - `type: "web_fetch_20260209"` - `"web_fetch_20260209"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `allowed_domains?: Array | null` List of domains to allow fetching from - `blocked_domains?: Array | null` List of domains to block fetching from - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `citations?: BetaCitationsConfigParam | null` Citations configuration for fetched documents. Citations are disabled by default. - `defer_loading?: boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `max_content_tokens?: number | null` Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. - `max_uses?: number | null` Maximum number of times the tool can be used in the API request. - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `BetaWebFetchTool20260309` Web fetch tool with use_cache parameter for bypassing cached content. - `name: "web_fetch"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"web_fetch"` - `type: "web_fetch_20260309"` - `"web_fetch_20260309"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `allowed_domains?: Array | null` List of domains to allow fetching from - `blocked_domains?: Array | null` List of domains to block fetching from - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `citations?: BetaCitationsConfigParam | null` Citations configuration for fetched documents. Citations are disabled by default. - `defer_loading?: boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `max_content_tokens?: number | null` Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. - `max_uses?: number | null` Maximum number of times the tool can be used in the API request. - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `use_cache?: boolean` Whether to use cached content. Set to false to bypass the cache and fetch fresh content. Only set to false when the user explicitly requests fresh content or when fetching rapidly-changing sources. - `BetaAdvisorTool20260301` - `model: Model` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `name: "advisor"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"advisor"` - `type: "advisor_20260301"` - `"advisor_20260301"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `caching?: BetaCacheControlEphemeral | null` Caching for the advisor's own prompt. When set, each advisor call writes a cache entry at the given TTL so subsequent calls in the same conversation read the stable prefix. When omitted, the advisor prompt is not cached. - `defer_loading?: boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `max_uses?: number | null` Maximum number of times the tool can be used in the API request. - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `BetaToolSearchToolBm25_20251119` - `name: "tool_search_tool_bm25"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"tool_search_tool_bm25"` - `type: "tool_search_tool_bm25_20251119" | "tool_search_tool_bm25"` - `"tool_search_tool_bm25_20251119"` - `"tool_search_tool_bm25"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `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 - `BetaToolSearchToolRegex20251119` - `name: "tool_search_tool_regex"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"tool_search_tool_regex"` - `type: "tool_search_tool_regex_20251119" | "tool_search_tool_regex"` - `"tool_search_tool_regex_20251119"` - `"tool_search_tool_regex"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `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 - `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. - `mcp_server_name: string` Name of the MCP server to configure tools for - `type: "mcp_toolset"` - `"mcp_toolset"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `configs?: Record | null` Configuration overrides for specific tools, keyed by tool name - `defer_loading?: boolean` - `enabled?: boolean` - `default_config?: BetaMCPToolDefaultConfig` Default configuration applied to all tools from this server - `defer_loading?: boolean` - `enabled?: boolean` - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaMessageTokensCount` - `context_management: BetaCountTokensContextManagementResponse | null` Information about context management applied to the message. - `original_input_tokens: number` The original token count before context management was applied - `input_tokens: number` The total number of tokens across the provided list of messages, system prompt, and tools. ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const betaMessageTokensCount = await client.beta.messages.countTokens({ messages: [{ content: 'Hello, world', role: 'user' }], model: 'claude-opus-4-6', }); console.log(betaMessageTokensCount.context_management); ``` #### Response ```json { "context_management": { "original_input_tokens": 0 }, "input_tokens": 2095 } ``` ## Domain Types ### Beta Advisor Message Iteration Usage - `BetaAdvisorMessageIterationUsage` Token usage for an advisor sub-inference iteration. - `cache_creation: BetaCacheCreation | null` Breakdown of cached tokens by TTL - `ephemeral_1h_input_tokens: number` The number of input tokens used to create the 1 hour cache entry. - `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. - `model: Model` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-opus-4-8" | "claude-opus-4-7" | "claude-mythos-preview" | 15 more` - `"claude-opus-4-8"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-7"` Frontier intelligence for long-running agents and coding - `"claude-mythos-preview"` New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` Fastest model with near-frontier intelligence - `"claude-haiku-4-5-20251001"` Fastest model with near-frontier intelligence - `"claude-opus-4-5"` Premium model combining maximum intelligence with practical performance - `"claude-opus-4-5-20251101"` Premium model combining maximum intelligence with practical performance - `"claude-sonnet-4-5"` High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` High-performance model for agents and coding - `"claude-opus-4-1"` Exceptional model for specialized complex tasks - `"claude-opus-4-1-20250805"` Exceptional model for specialized complex tasks - `"claude-opus-4-0"` Powerful model for complex tasks - `"claude-opus-4-20250514"` Powerful model for complex tasks - `"claude-sonnet-4-0"` High-performance model with extended thinking - `"claude-sonnet-4-20250514"` High-performance model with extended thinking - `"claude-3-haiku-20240307"` Fast and cost-effective model - `(string & {})` - `output_tokens: number` The number of output tokens which were used. - `type: "advisor_message"` Usage for an advisor sub-inference iteration - `"advisor_message"` ### Beta Advisor Redacted Result Block - `BetaAdvisorRedactedResultBlock` - `encrypted_content: string` Opaque blob containing the advisor's output. Round-trip verbatim; do not inspect or modify. - `stop_reason: string | null` The advisor sub-inference's stop reason (same values as the top-level message `stop_reason`). - `type: "advisor_redacted_result"` - `"advisor_redacted_result"` ### Beta Advisor Redacted Result Block Param - `BetaAdvisorRedactedResultBlockParam` - `encrypted_content: string` Opaque blob produced by a prior response; must be round-tripped verbatim. - `type: "advisor_redacted_result"` - `"advisor_redacted_result"` - `stop_reason?: string | null` ### Beta Advisor Result Block - `BetaAdvisorResultBlock` - `stop_reason: string | null` The advisor sub-inference's stop reason (same values as the top-level message `stop_reason`). `max_tokens` indicates the advisor's output was truncated at the tool's `max_tokens` value or the advisor model's policy cap. - `text: string` - `type: "advisor_result"` - `"advisor_result"` ### Beta Advisor Result Block Param - `BetaAdvisorResultBlockParam` - `text: string` - `type: "advisor_result"` - `"advisor_result"` - `stop_reason?: string | null` ### Beta Advisor Tool 20260301 - `BetaAdvisorTool20260301` - `model: Model` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-opus-4-8" | "claude-opus-4-7" | "claude-mythos-preview" | 15 more` - `"claude-opus-4-8"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-7"` Frontier intelligence for long-running agents and coding - `"claude-mythos-preview"` New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` Fastest model with near-frontier intelligence - `"claude-haiku-4-5-20251001"` Fastest model with near-frontier intelligence - `"claude-opus-4-5"` Premium model combining maximum intelligence with practical performance - `"claude-opus-4-5-20251101"` Premium model combining maximum intelligence with practical performance - `"claude-sonnet-4-5"` High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` High-performance model for agents and coding - `"claude-opus-4-1"` Exceptional model for specialized complex tasks - `"claude-opus-4-1-20250805"` Exceptional model for specialized complex tasks - `"claude-opus-4-0"` Powerful model for complex tasks - `"claude-opus-4-20250514"` Powerful model for complex tasks - `"claude-sonnet-4-0"` High-performance model with extended thinking - `"claude-sonnet-4-20250514"` High-performance model with extended thinking - `"claude-3-haiku-20240307"` Fast and cost-effective model - `(string & {})` - `name: "advisor"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"advisor"` - `type: "advisor_20260301"` - `"advisor_20260301"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `"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`. - `"5m"` - `"1h"` - `caching?: BetaCacheControlEphemeral | null` Caching for the advisor's own prompt. When set, each advisor call writes a cache entry at the given TTL so subsequent calls in the same conversation read the stable prefix. When omitted, the advisor prompt is not cached. - `defer_loading?: boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `max_uses?: number | null` Maximum number of times the tool can be used in the API request. - `strict?: boolean` When true, guarantees schema validation on tool names and inputs ### Beta Advisor Tool Result Block - `BetaAdvisorToolResultBlock` - `content: BetaAdvisorToolResultError | BetaAdvisorResultBlock | BetaAdvisorRedactedResultBlock` - `BetaAdvisorToolResultError` - `error_code: "max_uses_exceeded" | "prompt_too_long" | "too_many_requests" | 3 more` - `"max_uses_exceeded"` - `"prompt_too_long"` - `"too_many_requests"` - `"overloaded"` - `"unavailable"` - `"execution_time_exceeded"` - `type: "advisor_tool_result_error"` - `"advisor_tool_result_error"` - `BetaAdvisorResultBlock` - `stop_reason: string | null` The advisor sub-inference's stop reason (same values as the top-level message `stop_reason`). `max_tokens` indicates the advisor's output was truncated at the tool's `max_tokens` value or the advisor model's policy cap. - `text: string` - `type: "advisor_result"` - `"advisor_result"` - `BetaAdvisorRedactedResultBlock` - `encrypted_content: string` Opaque blob containing the advisor's output. Round-trip verbatim; do not inspect or modify. - `stop_reason: string | null` The advisor sub-inference's stop reason (same values as the top-level message `stop_reason`). - `type: "advisor_redacted_result"` - `"advisor_redacted_result"` - `tool_use_id: string` - `type: "advisor_tool_result"` - `"advisor_tool_result"` ### Beta Advisor Tool Result Block Param - `BetaAdvisorToolResultBlockParam` - `content: BetaAdvisorToolResultErrorParam | BetaAdvisorResultBlockParam | BetaAdvisorRedactedResultBlockParam` - `BetaAdvisorToolResultErrorParam` - `error_code: "max_uses_exceeded" | "prompt_too_long" | "too_many_requests" | 3 more` - `"max_uses_exceeded"` - `"prompt_too_long"` - `"too_many_requests"` - `"overloaded"` - `"unavailable"` - `"execution_time_exceeded"` - `type: "advisor_tool_result_error"` - `"advisor_tool_result_error"` - `BetaAdvisorResultBlockParam` - `text: string` - `type: "advisor_result"` - `"advisor_result"` - `stop_reason?: string | null` - `BetaAdvisorRedactedResultBlockParam` - `encrypted_content: string` Opaque blob produced by a prior response; must be round-tripped verbatim. - `type: "advisor_redacted_result"` - `"advisor_redacted_result"` - `stop_reason?: string | null` - `tool_use_id: string` - `type: "advisor_tool_result"` - `"advisor_tool_result"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `"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`. - `"5m"` - `"1h"` ### Beta Advisor Tool Result Error - `BetaAdvisorToolResultError` - `error_code: "max_uses_exceeded" | "prompt_too_long" | "too_many_requests" | 3 more` - `"max_uses_exceeded"` - `"prompt_too_long"` - `"too_many_requests"` - `"overloaded"` - `"unavailable"` - `"execution_time_exceeded"` - `type: "advisor_tool_result_error"` - `"advisor_tool_result_error"` ### Beta Advisor Tool Result Error Param - `BetaAdvisorToolResultErrorParam` - `error_code: "max_uses_exceeded" | "prompt_too_long" | "too_many_requests" | 3 more` - `"max_uses_exceeded"` - `"prompt_too_long"` - `"too_many_requests"` - `"overloaded"` - `"unavailable"` - `"execution_time_exceeded"` - `type: "advisor_tool_result_error"` - `"advisor_tool_result_error"` ### Beta All Thinking Turns - `BetaAllThinkingTurns` - `type: "all"` - `"all"` ### Beta Base64 Image Source - `BetaBase64ImageSource` - `data: string` - `media_type: "image/jpeg" | "image/png" | "image/gif" | "image/webp"` - `"image/jpeg"` - `"image/png"` - `"image/gif"` - `"image/webp"` - `type: "base64"` - `"base64"` ### Beta Base64 PDF Source - `BetaBase64PDFSource` - `data: string` - `media_type: "application/pdf"` - `"application/pdf"` - `type: "base64"` - `"base64"` ### Beta Bash Code Execution Output Block - `BetaBashCodeExecutionOutputBlock` - `file_id: string` - `type: "bash_code_execution_output"` - `"bash_code_execution_output"` ### Beta Bash Code Execution Output Block Param - `BetaBashCodeExecutionOutputBlockParam` - `file_id: string` - `type: "bash_code_execution_output"` - `"bash_code_execution_output"` ### Beta Bash Code Execution Result Block - `BetaBashCodeExecutionResultBlock` - `content: Array` - `file_id: string` - `type: "bash_code_execution_output"` - `"bash_code_execution_output"` - `return_code: number` - `stderr: string` - `stdout: string` - `type: "bash_code_execution_result"` - `"bash_code_execution_result"` ### Beta Bash Code Execution Result Block Param - `BetaBashCodeExecutionResultBlockParam` - `content: Array` - `file_id: string` - `type: "bash_code_execution_output"` - `"bash_code_execution_output"` - `return_code: number` - `stderr: string` - `stdout: string` - `type: "bash_code_execution_result"` - `"bash_code_execution_result"` ### Beta Bash Code Execution Tool Result Block - `BetaBashCodeExecutionToolResultBlock` - `content: BetaBashCodeExecutionToolResultError | BetaBashCodeExecutionResultBlock` - `BetaBashCodeExecutionToolResultError` - `error_code: "invalid_tool_input" | "unavailable" | "too_many_requests" | 2 more` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `"output_file_too_large"` - `type: "bash_code_execution_tool_result_error"` - `"bash_code_execution_tool_result_error"` - `BetaBashCodeExecutionResultBlock` - `content: Array` - `file_id: string` - `type: "bash_code_execution_output"` - `"bash_code_execution_output"` - `return_code: number` - `stderr: string` - `stdout: string` - `type: "bash_code_execution_result"` - `"bash_code_execution_result"` - `tool_use_id: string` - `type: "bash_code_execution_tool_result"` - `"bash_code_execution_tool_result"` ### Beta Bash Code Execution Tool Result Block Param - `BetaBashCodeExecutionToolResultBlockParam` - `content: BetaBashCodeExecutionToolResultErrorParam | BetaBashCodeExecutionResultBlockParam` - `BetaBashCodeExecutionToolResultErrorParam` - `error_code: "invalid_tool_input" | "unavailable" | "too_many_requests" | 2 more` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `"output_file_too_large"` - `type: "bash_code_execution_tool_result_error"` - `"bash_code_execution_tool_result_error"` - `BetaBashCodeExecutionResultBlockParam` - `content: Array` - `file_id: string` - `type: "bash_code_execution_output"` - `"bash_code_execution_output"` - `return_code: number` - `stderr: string` - `stdout: string` - `type: "bash_code_execution_result"` - `"bash_code_execution_result"` - `tool_use_id: string` - `type: "bash_code_execution_tool_result"` - `"bash_code_execution_tool_result"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `"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`. - `"5m"` - `"1h"` ### Beta Bash Code Execution Tool Result Error - `BetaBashCodeExecutionToolResultError` - `error_code: "invalid_tool_input" | "unavailable" | "too_many_requests" | 2 more` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `"output_file_too_large"` - `type: "bash_code_execution_tool_result_error"` - `"bash_code_execution_tool_result_error"` ### Beta Bash Code Execution Tool Result Error Param - `BetaBashCodeExecutionToolResultErrorParam` - `error_code: "invalid_tool_input" | "unavailable" | "too_many_requests" | 2 more` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `"output_file_too_large"` - `type: "bash_code_execution_tool_result_error"` - `"bash_code_execution_tool_result_error"` ### Beta Cache Control Ephemeral - `BetaCacheControlEphemeral` - `type: "ephemeral"` - `"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`. - `"5m"` - `"1h"` ### Beta Cache Creation - `BetaCacheCreation` - `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. ### Beta Cache Miss Messages Changed - `BetaCacheMissMessagesChanged` - `cache_missed_input_tokens: number` Approximate number of input tokens that would have been read from cache had the prefix matched the previous request. - `type: "messages_changed"` - `"messages_changed"` ### Beta Cache Miss Model Changed - `BetaCacheMissModelChanged` - `cache_missed_input_tokens: number` Approximate number of input tokens that would have been read from cache had the prefix matched the previous request. - `type: "model_changed"` - `"model_changed"` ### Beta Cache Miss Previous Message Not Found - `BetaCacheMissPreviousMessageNotFound` - `type: "previous_message_not_found"` - `"previous_message_not_found"` ### Beta Cache Miss System Changed - `BetaCacheMissSystemChanged` - `cache_missed_input_tokens: number` Approximate number of input tokens that would have been read from cache had the prefix matched the previous request. - `type: "system_changed"` - `"system_changed"` ### Beta Cache Miss Tools Changed - `BetaCacheMissToolsChanged` - `cache_missed_input_tokens: number` Approximate number of input tokens that would have been read from cache had the prefix matched the previous request. - `type: "tools_changed"` - `"tools_changed"` ### Beta Cache Miss Unavailable - `BetaCacheMissUnavailable` - `type: "unavailable"` - `"unavailable"` ### Beta Citation Char Location - `BetaCitationCharLocation` - `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"` - `"char_location"` ### Beta Citation Char Location Param - `BetaCitationCharLocationParam` - `cited_text: string` - `document_index: number` - `document_title: string | null` - `end_char_index: number` - `start_char_index: number` - `type: "char_location"` - `"char_location"` ### Beta Citation Config - `BetaCitationConfig` - `enabled: boolean` ### Beta Citation Content Block Location - `BetaCitationContentBlockLocation` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `document_index: number` - `document_title: string | null` - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `file_id: string | null` - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. - `type: "content_block_location"` - `"content_block_location"` ### Beta Citation Content Block Location Param - `BetaCitationContentBlockLocationParam` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `document_index: number` - `document_title: string | null` - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. - `type: "content_block_location"` - `"content_block_location"` ### Beta Citation Page Location - `BetaCitationPageLocation` - `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"` - `"page_location"` ### Beta Citation Page Location Param - `BetaCitationPageLocationParam` - `cited_text: string` - `document_index: number` - `document_title: string | null` - `end_page_number: number` - `start_page_number: number` - `type: "page_location"` - `"page_location"` ### Beta Citation Search Result Location - `BetaCitationSearchResultLocation` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `search_result_index: number` 0-based index of the cited search result among all `search_result` content blocks in the request, in the order they appear across messages and tool results. Counted separately from `document_index`; server-side web search results are not included in this count. - `source: string` - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. - `title: string | null` - `type: "search_result_location"` - `"search_result_location"` ### Beta Citation Search Result Location Param - `BetaCitationSearchResultLocationParam` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `search_result_index: number` 0-based index of the cited search result among all `search_result` content blocks in the request, in the order they appear across messages and tool results. Counted separately from `document_index`; server-side web search results are not included in this count. - `source: string` - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. - `title: string | null` - `type: "search_result_location"` - `"search_result_location"` ### Beta Citation Web Search Result Location Param - `BetaCitationWebSearchResultLocationParam` - `cited_text: string` - `encrypted_index: string` - `title: string | null` - `type: "web_search_result_location"` - `"web_search_result_location"` - `url: string` ### Beta Citations Config Param - `BetaCitationsConfigParam` - `enabled?: boolean` ### Beta Citations Delta - `BetaCitationsDelta` - `citation: BetaCitationCharLocation | BetaCitationPageLocation | BetaCitationContentBlockLocation | 2 more` - `BetaCitationCharLocation` - `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"` - `"char_location"` - `BetaCitationPageLocation` - `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"` - `"page_location"` - `BetaCitationContentBlockLocation` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `document_index: number` - `document_title: string | null` - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `file_id: string | null` - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. - `type: "content_block_location"` - `"content_block_location"` - `BetaCitationsWebSearchResultLocation` - `cited_text: string` - `encrypted_index: string` - `title: string | null` - `type: "web_search_result_location"` - `"web_search_result_location"` - `url: string` - `BetaCitationSearchResultLocation` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `search_result_index: number` 0-based index of the cited search result among all `search_result` content blocks in the request, in the order they appear across messages and tool results. Counted separately from `document_index`; server-side web search results are not included in this count. - `source: string` - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. - `title: string | null` - `type: "search_result_location"` - `"search_result_location"` - `type: "citations_delta"` - `"citations_delta"` ### Beta Citations Web Search Result Location - `BetaCitationsWebSearchResultLocation` - `cited_text: string` - `encrypted_index: string` - `title: string | null` - `type: "web_search_result_location"` - `"web_search_result_location"` - `url: string` ### Beta Clear Thinking 20251015 Edit - `BetaClearThinking20251015Edit` - `type: "clear_thinking_20251015"` - `"clear_thinking_20251015"` - `keep?: BetaThinkingTurns | BetaAllThinkingTurns | "all"` Number of most recent assistant turns to keep thinking blocks for. Older turns will have their thinking blocks removed. - `BetaThinkingTurns` - `type: "thinking_turns"` - `"thinking_turns"` - `value: number` - `BetaAllThinkingTurns` - `type: "all"` - `"all"` - `"all"` - `"all"` ### Beta Clear Thinking 20251015 Edit Response - `BetaClearThinking20251015EditResponse` - `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. - `"clear_thinking_20251015"` ### Beta Clear Tool Uses 20250919 Edit - `BetaClearToolUses20250919Edit` - `type: "clear_tool_uses_20250919"` - `"clear_tool_uses_20250919"` - `clear_at_least?: BetaInputTokensClearAtLeast | 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"` - `"input_tokens"` - `value: number` - `clear_tool_inputs?: boolean | Array | null` Whether to clear all tool inputs (bool) or specific tool inputs to clear (list) - `boolean` - `Array` - `exclude_tools?: Array | null` Tool names whose uses are preserved from clearing - `keep?: BetaToolUsesKeep` Number of tool uses to retain in the conversation - `type: "tool_uses"` - `"tool_uses"` - `value: number` - `trigger?: BetaInputTokensTrigger | BetaToolUsesTrigger` Condition that triggers the context management strategy - `BetaInputTokensTrigger` - `type: "input_tokens"` - `"input_tokens"` - `value: number` - `BetaToolUsesTrigger` - `type: "tool_uses"` - `"tool_uses"` - `value: number` ### Beta Clear Tool Uses 20250919 Edit Response - `BetaClearToolUses20250919EditResponse` - `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. - `"clear_tool_uses_20250919"` ### Beta Code Execution Output Block - `BetaCodeExecutionOutputBlock` - `file_id: string` - `type: "code_execution_output"` - `"code_execution_output"` ### Beta Code Execution Output Block Param - `BetaCodeExecutionOutputBlockParam` - `file_id: string` - `type: "code_execution_output"` - `"code_execution_output"` ### Beta Code Execution Result Block - `BetaCodeExecutionResultBlock` - `content: Array` - `file_id: string` - `type: "code_execution_output"` - `"code_execution_output"` - `return_code: number` - `stderr: string` - `stdout: string` - `type: "code_execution_result"` - `"code_execution_result"` ### Beta Code Execution Result Block Param - `BetaCodeExecutionResultBlockParam` - `content: Array` - `file_id: string` - `type: "code_execution_output"` - `"code_execution_output"` - `return_code: number` - `stderr: string` - `stdout: string` - `type: "code_execution_result"` - `"code_execution_result"` ### Beta Code Execution Tool 20250522 - `BetaCodeExecutionTool20250522` - `name: "code_execution"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"code_execution"` - `type: "code_execution_20250522"` - `"code_execution_20250522"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `"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`. - `"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 ### Beta Code Execution Tool 20250825 - `BetaCodeExecutionTool20250825` - `name: "code_execution"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"code_execution"` - `type: "code_execution_20250825"` - `"code_execution_20250825"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `"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`. - `"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 ### Beta Code Execution Tool 20260120 - `BetaCodeExecutionTool20260120` Code execution tool with REPL state persistence (daemon mode + gVisor checkpoint). - `name: "code_execution"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"code_execution"` - `type: "code_execution_20260120"` - `"code_execution_20260120"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `"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`. - `"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 ### Beta Code Execution Tool Result Block - `BetaCodeExecutionToolResultBlock` - `content: BetaCodeExecutionToolResultBlockContent` Code execution result with encrypted stdout for PFC + web_search results. - `BetaCodeExecutionToolResultError` - `error_code: BetaCodeExecutionToolResultErrorCode` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `type: "code_execution_tool_result_error"` - `"code_execution_tool_result_error"` - `BetaCodeExecutionResultBlock` - `content: Array` - `file_id: string` - `type: "code_execution_output"` - `"code_execution_output"` - `return_code: number` - `stderr: string` - `stdout: string` - `type: "code_execution_result"` - `"code_execution_result"` - `BetaEncryptedCodeExecutionResultBlock` Code execution result with encrypted stdout for PFC + web_search results. - `content: Array` - `file_id: string` - `type: "code_execution_output"` - `encrypted_stdout: string` - `return_code: number` - `stderr: string` - `type: "encrypted_code_execution_result"` - `"encrypted_code_execution_result"` - `tool_use_id: string` - `type: "code_execution_tool_result"` - `"code_execution_tool_result"` ### Beta Code Execution Tool Result Block Content - `BetaCodeExecutionToolResultBlockContent = BetaCodeExecutionToolResultError | BetaCodeExecutionResultBlock | BetaEncryptedCodeExecutionResultBlock` Code execution result with encrypted stdout for PFC + web_search results. - `BetaCodeExecutionToolResultError` - `error_code: BetaCodeExecutionToolResultErrorCode` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `type: "code_execution_tool_result_error"` - `"code_execution_tool_result_error"` - `BetaCodeExecutionResultBlock` - `content: Array` - `file_id: string` - `type: "code_execution_output"` - `"code_execution_output"` - `return_code: number` - `stderr: string` - `stdout: string` - `type: "code_execution_result"` - `"code_execution_result"` - `BetaEncryptedCodeExecutionResultBlock` Code execution result with encrypted stdout for PFC + web_search results. - `content: Array` - `file_id: string` - `type: "code_execution_output"` - `encrypted_stdout: string` - `return_code: number` - `stderr: string` - `type: "encrypted_code_execution_result"` - `"encrypted_code_execution_result"` ### Beta Code Execution Tool Result Block Param - `BetaCodeExecutionToolResultBlockParam` - `content: BetaCodeExecutionToolResultBlockParamContent` Code execution result with encrypted stdout for PFC + web_search results. - `BetaCodeExecutionToolResultErrorParam` - `error_code: BetaCodeExecutionToolResultErrorCode` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `type: "code_execution_tool_result_error"` - `"code_execution_tool_result_error"` - `BetaCodeExecutionResultBlockParam` - `content: Array` - `file_id: string` - `type: "code_execution_output"` - `"code_execution_output"` - `return_code: number` - `stderr: string` - `stdout: string` - `type: "code_execution_result"` - `"code_execution_result"` - `BetaEncryptedCodeExecutionResultBlockParam` Code execution result with encrypted stdout for PFC + web_search results. - `content: Array` - `file_id: string` - `type: "code_execution_output"` - `encrypted_stdout: string` - `return_code: number` - `stderr: string` - `type: "encrypted_code_execution_result"` - `"encrypted_code_execution_result"` - `tool_use_id: string` - `type: "code_execution_tool_result"` - `"code_execution_tool_result"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `"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`. - `"5m"` - `"1h"` ### Beta Code Execution Tool Result Block Param Content - `BetaCodeExecutionToolResultBlockParamContent = BetaCodeExecutionToolResultErrorParam | BetaCodeExecutionResultBlockParam | BetaEncryptedCodeExecutionResultBlockParam` Code execution result with encrypted stdout for PFC + web_search results. - `BetaCodeExecutionToolResultErrorParam` - `error_code: BetaCodeExecutionToolResultErrorCode` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `type: "code_execution_tool_result_error"` - `"code_execution_tool_result_error"` - `BetaCodeExecutionResultBlockParam` - `content: Array` - `file_id: string` - `type: "code_execution_output"` - `"code_execution_output"` - `return_code: number` - `stderr: string` - `stdout: string` - `type: "code_execution_result"` - `"code_execution_result"` - `BetaEncryptedCodeExecutionResultBlockParam` Code execution result with encrypted stdout for PFC + web_search results. - `content: Array` - `file_id: string` - `type: "code_execution_output"` - `encrypted_stdout: string` - `return_code: number` - `stderr: string` - `type: "encrypted_code_execution_result"` - `"encrypted_code_execution_result"` ### Beta Code Execution Tool Result Error - `BetaCodeExecutionToolResultError` - `error_code: BetaCodeExecutionToolResultErrorCode` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `type: "code_execution_tool_result_error"` - `"code_execution_tool_result_error"` ### Beta Code Execution Tool Result Error Code - `BetaCodeExecutionToolResultErrorCode = "invalid_tool_input" | "unavailable" | "too_many_requests" | "execution_time_exceeded"` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` ### Beta Code Execution Tool Result Error Param - `BetaCodeExecutionToolResultErrorParam` - `error_code: BetaCodeExecutionToolResultErrorCode` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `type: "code_execution_tool_result_error"` - `"code_execution_tool_result_error"` ### Beta Compact 20260112 Edit - `BetaCompact20260112Edit` Automatically compact older context when reaching the configured trigger threshold. - `type: "compact_20260112"` - `"compact_20260112"` - `instructions?: string | null` Additional instructions for summarization. - `pause_after_compaction?: boolean` Whether to pause after compaction and return the compaction block to the user. - `trigger?: BetaInputTokensTrigger | null` When to trigger compaction. Defaults to 150000 input tokens. - `type: "input_tokens"` - `"input_tokens"` - `value: number` ### Beta Compaction Block - `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. - `content: string | null` Summary of compacted content, or null if compaction failed - `encrypted_content: string | null` Opaque metadata from prior compaction, to be round-tripped verbatim - `type: "compaction"` - `"compaction"` ### Beta Compaction Block Param - `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. - `type: "compaction"` - `"compaction"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `"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`. - `"5m"` - `"1h"` - `content?: string | null` Summary of previously compacted content, or null if compaction failed - `encrypted_content?: string | null` Opaque metadata from prior compaction, to be round-tripped verbatim ### Beta Compaction Content Block Delta - `BetaCompactionContentBlockDelta` - `content: string | null` - `encrypted_content: string | null` Opaque metadata from prior compaction, to be round-tripped verbatim - `type: "compaction_delta"` - `"compaction_delta"` ### Beta Compaction Iteration Usage - `BetaCompactionIterationUsage` Token usage for a compaction iteration. - `cache_creation: BetaCacheCreation | null` Breakdown of cached tokens by TTL - `ephemeral_1h_input_tokens: number` The number of input tokens used to create the 1 hour cache entry. - `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 - `"compaction"` ### Beta Container - `BetaContainer` 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 | 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) - `"anthropic"` - `"custom"` - `version: string` Skill version or 'latest' for most recent version ### Beta Container Params - `BetaContainerParams` Container parameters with skills to be loaded. - `id?: string | null` Container id - `skills?: Array | 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) - `"anthropic"` - `"custom"` - `version?: string` Skill version or 'latest' for most recent version ### Beta Container Upload Block - `BetaContainerUploadBlock` Response model for a file uploaded to the container. - `file_id: string` - `type: "container_upload"` - `"container_upload"` ### Beta Container Upload Block Param - `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. - `file_id: string` - `type: "container_upload"` - `"container_upload"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `"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`. - `"5m"` - `"1h"` ### Beta Content Block - `BetaContentBlock = BetaTextBlock | BetaThinkingBlock | BetaRedactedThinkingBlock | 13 more` Response model for a file uploaded to the container. - `BetaTextBlock` - `citations: Array | 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`. - `BetaCitationCharLocation` - `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"` - `"char_location"` - `BetaCitationPageLocation` - `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"` - `"page_location"` - `BetaCitationContentBlockLocation` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `document_index: number` - `document_title: string | null` - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `file_id: string | null` - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. - `type: "content_block_location"` - `"content_block_location"` - `BetaCitationsWebSearchResultLocation` - `cited_text: string` - `encrypted_index: string` - `title: string | null` - `type: "web_search_result_location"` - `"web_search_result_location"` - `url: string` - `BetaCitationSearchResultLocation` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `search_result_index: number` 0-based index of the cited search result among all `search_result` content blocks in the request, in the order they appear across messages and tool results. Counted separately from `document_index`; server-side web search results are not included in this count. - `source: string` - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. - `title: string | null` - `type: "search_result_location"` - `"search_result_location"` - `text: string` - `type: "text"` - `"text"` - `BetaThinkingBlock` - `signature: string` - `thinking: string` - `type: "thinking"` - `"thinking"` - `BetaRedactedThinkingBlock` - `data: string` - `type: "redacted_thinking"` - `"redacted_thinking"` - `BetaToolUseBlock` - `id: string` - `input: Record` - `name: string` - `type: "tool_use"` - `"tool_use"` - `caller?: BetaDirectCaller | BetaServerToolCaller | BetaServerToolCaller20260120` Tool invocation directly from the model. - `BetaDirectCaller` Tool invocation directly from the model. - `type: "direct"` - `"direct"` - `BetaServerToolCaller` Tool invocation generated by a server-side tool. - `tool_id: string` - `type: "code_execution_20250825"` - `"code_execution_20250825"` - `BetaServerToolCaller20260120` - `tool_id: string` - `type: "code_execution_20260120"` - `"code_execution_20260120"` - `BetaServerToolUseBlock` - `id: string` - `input: Record` - `name: "advisor" | "web_search" | "web_fetch" | 5 more` - `"advisor"` - `"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"` - `"server_tool_use"` - `caller?: BetaDirectCaller | BetaServerToolCaller | BetaServerToolCaller20260120` Tool invocation directly from the model. - `BetaDirectCaller` Tool invocation directly from the model. - `BetaServerToolCaller` Tool invocation generated by a server-side tool. - `BetaServerToolCaller20260120` - `BetaWebSearchToolResultBlock` - `content: BetaWebSearchToolResultBlockContent` - `BetaWebSearchToolResultError` - `error_code: BetaWebSearchToolResultErrorCode` - `"invalid_tool_input"` - `"unavailable"` - `"max_uses_exceeded"` - `"too_many_requests"` - `"query_too_long"` - `"request_too_large"` - `type: "web_search_tool_result_error"` - `"web_search_tool_result_error"` - `Array` - `encrypted_content: string` - `page_age: string | null` - `title: string` - `type: "web_search_result"` - `"web_search_result"` - `url: string` - `tool_use_id: string` - `type: "web_search_tool_result"` - `"web_search_tool_result"` - `caller?: BetaDirectCaller | BetaServerToolCaller | BetaServerToolCaller20260120` Tool invocation directly from the model. - `BetaDirectCaller` Tool invocation directly from the model. - `BetaServerToolCaller` Tool invocation generated by a server-side tool. - `BetaServerToolCaller20260120` - `BetaWebFetchToolResultBlock` - `content: BetaWebFetchToolResultErrorBlock | BetaWebFetchBlock` - `BetaWebFetchToolResultErrorBlock` - `error_code: BetaWebFetchToolResultErrorCode` - `"invalid_tool_input"` - `"url_too_long"` - `"url_not_allowed"` - `"url_not_in_prior_context"` - `"url_not_accessible"` - `"unsupported_content_type"` - `"too_many_requests"` - `"max_uses_exceeded"` - `"unavailable"` - `type: "web_fetch_tool_result_error"` - `"web_fetch_tool_result_error"` - `BetaWebFetchBlock` - `content: BetaDocumentBlock` - `citations: BetaCitationConfig | null` Citation configuration for the document - `enabled: boolean` - `source: BetaBase64PDFSource | BetaPlainTextSource` - `BetaBase64PDFSource` - `data: string` - `media_type: "application/pdf"` - `"application/pdf"` - `type: "base64"` - `"base64"` - `BetaPlainTextSource` - `data: string` - `media_type: "text/plain"` - `"text/plain"` - `type: "text"` - `"text"` - `title: string | null` The title of the document - `type: "document"` - `"document"` - `retrieved_at: string | null` ISO 8601 timestamp when the content was retrieved - `type: "web_fetch_result"` - `"web_fetch_result"` - `url: string` Fetched content URL - `tool_use_id: string` - `type: "web_fetch_tool_result"` - `"web_fetch_tool_result"` - `caller?: BetaDirectCaller | BetaServerToolCaller | BetaServerToolCaller20260120` Tool invocation directly from the model. - `BetaDirectCaller` Tool invocation directly from the model. - `BetaServerToolCaller` Tool invocation generated by a server-side tool. - `BetaServerToolCaller20260120` - `BetaAdvisorToolResultBlock` - `content: BetaAdvisorToolResultError | BetaAdvisorResultBlock | BetaAdvisorRedactedResultBlock` - `BetaAdvisorToolResultError` - `error_code: "max_uses_exceeded" | "prompt_too_long" | "too_many_requests" | 3 more` - `"max_uses_exceeded"` - `"prompt_too_long"` - `"too_many_requests"` - `"overloaded"` - `"unavailable"` - `"execution_time_exceeded"` - `type: "advisor_tool_result_error"` - `"advisor_tool_result_error"` - `BetaAdvisorResultBlock` - `stop_reason: string | null` The advisor sub-inference's stop reason (same values as the top-level message `stop_reason`). `max_tokens` indicates the advisor's output was truncated at the tool's `max_tokens` value or the advisor model's policy cap. - `text: string` - `type: "advisor_result"` - `"advisor_result"` - `BetaAdvisorRedactedResultBlock` - `encrypted_content: string` Opaque blob containing the advisor's output. Round-trip verbatim; do not inspect or modify. - `stop_reason: string | null` The advisor sub-inference's stop reason (same values as the top-level message `stop_reason`). - `type: "advisor_redacted_result"` - `"advisor_redacted_result"` - `tool_use_id: string` - `type: "advisor_tool_result"` - `"advisor_tool_result"` - `BetaCodeExecutionToolResultBlock` - `content: BetaCodeExecutionToolResultBlockContent` Code execution result with encrypted stdout for PFC + web_search results. - `BetaCodeExecutionToolResultError` - `error_code: BetaCodeExecutionToolResultErrorCode` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `type: "code_execution_tool_result_error"` - `"code_execution_tool_result_error"` - `BetaCodeExecutionResultBlock` - `content: Array` - `file_id: string` - `type: "code_execution_output"` - `"code_execution_output"` - `return_code: number` - `stderr: string` - `stdout: string` - `type: "code_execution_result"` - `"code_execution_result"` - `BetaEncryptedCodeExecutionResultBlock` Code execution result with encrypted stdout for PFC + web_search results. - `content: Array` - `file_id: string` - `type: "code_execution_output"` - `encrypted_stdout: string` - `return_code: number` - `stderr: string` - `type: "encrypted_code_execution_result"` - `"encrypted_code_execution_result"` - `tool_use_id: string` - `type: "code_execution_tool_result"` - `"code_execution_tool_result"` - `BetaBashCodeExecutionToolResultBlock` - `content: BetaBashCodeExecutionToolResultError | BetaBashCodeExecutionResultBlock` - `BetaBashCodeExecutionToolResultError` - `error_code: "invalid_tool_input" | "unavailable" | "too_many_requests" | 2 more` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `"output_file_too_large"` - `type: "bash_code_execution_tool_result_error"` - `"bash_code_execution_tool_result_error"` - `BetaBashCodeExecutionResultBlock` - `content: Array` - `file_id: string` - `type: "bash_code_execution_output"` - `"bash_code_execution_output"` - `return_code: number` - `stderr: string` - `stdout: string` - `type: "bash_code_execution_result"` - `"bash_code_execution_result"` - `tool_use_id: string` - `type: "bash_code_execution_tool_result"` - `"bash_code_execution_tool_result"` - `BetaTextEditorCodeExecutionToolResultBlock` - `content: BetaTextEditorCodeExecutionToolResultError | BetaTextEditorCodeExecutionViewResultBlock | BetaTextEditorCodeExecutionCreateResultBlock | BetaTextEditorCodeExecutionStrReplaceResultBlock` - `BetaTextEditorCodeExecutionToolResultError` - `error_code: "invalid_tool_input" | "unavailable" | "too_many_requests" | 2 more` - `"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"` - `"text_editor_code_execution_tool_result_error"` - `BetaTextEditorCodeExecutionViewResultBlock` - `content: string` - `file_type: "text" | "image" | "pdf"` - `"text"` - `"image"` - `"pdf"` - `num_lines: number | null` - `start_line: number | null` - `total_lines: number | null` - `type: "text_editor_code_execution_view_result"` - `"text_editor_code_execution_view_result"` - `BetaTextEditorCodeExecutionCreateResultBlock` - `is_file_update: boolean` - `type: "text_editor_code_execution_create_result"` - `"text_editor_code_execution_create_result"` - `BetaTextEditorCodeExecutionStrReplaceResultBlock` - `lines: Array | 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"` - `"text_editor_code_execution_str_replace_result"` - `tool_use_id: string` - `type: "text_editor_code_execution_tool_result"` - `"text_editor_code_execution_tool_result"` - `BetaToolSearchToolResultBlock` - `content: BetaToolSearchToolResultError | BetaToolSearchToolSearchResultBlock` - `BetaToolSearchToolResultError` - `error_code: "invalid_tool_input" | "unavailable" | "too_many_requests" | "execution_time_exceeded"` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `error_message: string | null` - `type: "tool_search_tool_result_error"` - `"tool_search_tool_result_error"` - `BetaToolSearchToolSearchResultBlock` - `tool_references: Array` - `tool_name: string` - `type: "tool_reference"` - `"tool_reference"` - `type: "tool_search_tool_search_result"` - `"tool_search_tool_search_result"` - `tool_use_id: string` - `type: "tool_search_tool_result"` - `"tool_search_tool_result"` - `BetaMCPToolUseBlock` - `id: string` - `input: Record` - `name: string` The name of the MCP tool - `server_name: string` The name of the MCP server - `type: "mcp_tool_use"` - `"mcp_tool_use"` - `BetaMCPToolResultBlock` - `content: string | Array` - `string` - `Array` - `citations: Array | 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`. - `text: string` - `type: "text"` - `is_error: boolean` - `tool_use_id: string` - `type: "mcp_tool_result"` - `"mcp_tool_result"` - `BetaContainerUploadBlock` Response model for a file uploaded to the container. - `file_id: string` - `type: "container_upload"` - `"container_upload"` - `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. - `content: string | null` Summary of compacted content, or null if compaction failed - `encrypted_content: string | null` Opaque metadata from prior compaction, to be round-tripped verbatim - `type: "compaction"` - `"compaction"` ### Beta Content Block Param - `BetaContentBlockParam = BetaTextBlockParam | BetaImageBlockParam | BetaRequestDocumentBlock | 18 more` Regular text content. - `BetaTextBlockParam` - `text: string` - `type: "text"` - `"text"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `"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`. - `"5m"` - `"1h"` - `citations?: Array | null` - `BetaCitationCharLocationParam` - `cited_text: string` - `document_index: number` - `document_title: string | null` - `end_char_index: number` - `start_char_index: number` - `type: "char_location"` - `"char_location"` - `BetaCitationPageLocationParam` - `cited_text: string` - `document_index: number` - `document_title: string | null` - `end_page_number: number` - `start_page_number: number` - `type: "page_location"` - `"page_location"` - `BetaCitationContentBlockLocationParam` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `document_index: number` - `document_title: string | null` - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. - `type: "content_block_location"` - `"content_block_location"` - `BetaCitationWebSearchResultLocationParam` - `cited_text: string` - `encrypted_index: string` - `title: string | null` - `type: "web_search_result_location"` - `"web_search_result_location"` - `url: string` - `BetaCitationSearchResultLocationParam` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `search_result_index: number` 0-based index of the cited search result among all `search_result` content blocks in the request, in the order they appear across messages and tool results. Counted separately from `document_index`; server-side web search results are not included in this count. - `source: string` - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. - `title: string | null` - `type: "search_result_location"` - `"search_result_location"` - `BetaImageBlockParam` - `source: BetaBase64ImageSource | BetaURLImageSource | BetaFileImageSource` - `BetaBase64ImageSource` - `data: string` - `media_type: "image/jpeg" | "image/png" | "image/gif" | "image/webp"` - `"image/jpeg"` - `"image/png"` - `"image/gif"` - `"image/webp"` - `type: "base64"` - `"base64"` - `BetaURLImageSource` - `type: "url"` - `"url"` - `url: string` - `BetaFileImageSource` - `file_id: string` - `type: "file"` - `"file"` - `type: "image"` - `"image"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `BetaRequestDocumentBlock` - `source: BetaBase64PDFSource | BetaPlainTextSource | BetaContentBlockSource | 2 more` - `BetaBase64PDFSource` - `data: string` - `media_type: "application/pdf"` - `"application/pdf"` - `type: "base64"` - `"base64"` - `BetaPlainTextSource` - `data: string` - `media_type: "text/plain"` - `"text/plain"` - `type: "text"` - `"text"` - `BetaContentBlockSource` - `content: string | Array` - `string` - `Array` - `BetaTextBlockParam` - `BetaImageBlockParam` - `type: "content"` - `"content"` - `BetaURLPDFSource` - `type: "url"` - `"url"` - `url: string` - `BetaFileDocumentSource` - `file_id: string` - `type: "file"` - `"file"` - `type: "document"` - `"document"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `citations?: BetaCitationsConfigParam | null` - `enabled?: boolean` - `context?: string | null` - `title?: string | null` - `BetaSearchResultBlockParam` - `content: Array` - `text: string` - `type: "text"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `citations?: Array | null` - `source: string` - `title: string` - `type: "search_result"` - `"search_result"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `citations?: BetaCitationsConfigParam` - `BetaThinkingBlockParam` - `signature: string` - `thinking: string` - `type: "thinking"` - `"thinking"` - `BetaRedactedThinkingBlockParam` - `data: string` - `type: "redacted_thinking"` - `"redacted_thinking"` - `BetaToolUseBlockParam` - `id: string` - `input: Record` - `name: string` - `type: "tool_use"` - `"tool_use"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `caller?: BetaDirectCaller | BetaServerToolCaller | BetaServerToolCaller20260120` Tool invocation directly from the model. - `BetaDirectCaller` Tool invocation directly from the model. - `type: "direct"` - `"direct"` - `BetaServerToolCaller` Tool invocation generated by a server-side tool. - `tool_id: string` - `type: "code_execution_20250825"` - `"code_execution_20250825"` - `BetaServerToolCaller20260120` - `tool_id: string` - `type: "code_execution_20260120"` - `"code_execution_20260120"` - `BetaToolResultBlockParam` - `tool_use_id: string` - `type: "tool_result"` - `"tool_result"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `content?: string | Array` - `string` - `Array` - `BetaTextBlockParam` - `BetaImageBlockParam` - `BetaSearchResultBlockParam` - `BetaRequestDocumentBlock` - `BetaToolReferenceBlockParam` Tool reference block that can be included in tool_result content. - `tool_name: string` - `type: "tool_reference"` - `"tool_reference"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `is_error?: boolean` - `BetaServerToolUseBlockParam` - `id: string` - `input: Record` - `name: "advisor" | "web_search" | "web_fetch" | 5 more` - `"advisor"` - `"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"` - `"server_tool_use"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `caller?: BetaDirectCaller | BetaServerToolCaller | BetaServerToolCaller20260120` Tool invocation directly from the model. - `BetaDirectCaller` Tool invocation directly from the model. - `BetaServerToolCaller` Tool invocation generated by a server-side tool. - `BetaServerToolCaller20260120` - `BetaWebSearchToolResultBlockParam` - `content: BetaWebSearchToolResultBlockParamContent` - `Array` - `encrypted_content: string` - `title: string` - `type: "web_search_result"` - `"web_search_result"` - `url: string` - `page_age?: string | null` - `BetaWebSearchToolRequestError` - `error_code: BetaWebSearchToolResultErrorCode` - `"invalid_tool_input"` - `"unavailable"` - `"max_uses_exceeded"` - `"too_many_requests"` - `"query_too_long"` - `"request_too_large"` - `type: "web_search_tool_result_error"` - `"web_search_tool_result_error"` - `tool_use_id: string` - `type: "web_search_tool_result"` - `"web_search_tool_result"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `caller?: BetaDirectCaller | BetaServerToolCaller | BetaServerToolCaller20260120` Tool invocation directly from the model. - `BetaDirectCaller` Tool invocation directly from the model. - `BetaServerToolCaller` Tool invocation generated by a server-side tool. - `BetaServerToolCaller20260120` - `BetaWebFetchToolResultBlockParam` - `content: BetaWebFetchToolResultErrorBlockParam | BetaWebFetchBlockParam` - `BetaWebFetchToolResultErrorBlockParam` - `error_code: BetaWebFetchToolResultErrorCode` - `"invalid_tool_input"` - `"url_too_long"` - `"url_not_allowed"` - `"url_not_in_prior_context"` - `"url_not_accessible"` - `"unsupported_content_type"` - `"too_many_requests"` - `"max_uses_exceeded"` - `"unavailable"` - `type: "web_fetch_tool_result_error"` - `"web_fetch_tool_result_error"` - `BetaWebFetchBlockParam` - `content: BetaRequestDocumentBlock` - `type: "web_fetch_result"` - `"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"` - `"web_fetch_tool_result"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `caller?: BetaDirectCaller | BetaServerToolCaller | BetaServerToolCaller20260120` Tool invocation directly from the model. - `BetaDirectCaller` Tool invocation directly from the model. - `BetaServerToolCaller` Tool invocation generated by a server-side tool. - `BetaServerToolCaller20260120` - `BetaAdvisorToolResultBlockParam` - `content: BetaAdvisorToolResultErrorParam | BetaAdvisorResultBlockParam | BetaAdvisorRedactedResultBlockParam` - `BetaAdvisorToolResultErrorParam` - `error_code: "max_uses_exceeded" | "prompt_too_long" | "too_many_requests" | 3 more` - `"max_uses_exceeded"` - `"prompt_too_long"` - `"too_many_requests"` - `"overloaded"` - `"unavailable"` - `"execution_time_exceeded"` - `type: "advisor_tool_result_error"` - `"advisor_tool_result_error"` - `BetaAdvisorResultBlockParam` - `text: string` - `type: "advisor_result"` - `"advisor_result"` - `stop_reason?: string | null` - `BetaAdvisorRedactedResultBlockParam` - `encrypted_content: string` Opaque blob produced by a prior response; must be round-tripped verbatim. - `type: "advisor_redacted_result"` - `"advisor_redacted_result"` - `stop_reason?: string | null` - `tool_use_id: string` - `type: "advisor_tool_result"` - `"advisor_tool_result"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `BetaCodeExecutionToolResultBlockParam` - `content: BetaCodeExecutionToolResultBlockParamContent` Code execution result with encrypted stdout for PFC + web_search results. - `BetaCodeExecutionToolResultErrorParam` - `error_code: BetaCodeExecutionToolResultErrorCode` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `type: "code_execution_tool_result_error"` - `"code_execution_tool_result_error"` - `BetaCodeExecutionResultBlockParam` - `content: Array` - `file_id: string` - `type: "code_execution_output"` - `"code_execution_output"` - `return_code: number` - `stderr: string` - `stdout: string` - `type: "code_execution_result"` - `"code_execution_result"` - `BetaEncryptedCodeExecutionResultBlockParam` Code execution result with encrypted stdout for PFC + web_search results. - `content: Array` - `file_id: string` - `type: "code_execution_output"` - `encrypted_stdout: string` - `return_code: number` - `stderr: string` - `type: "encrypted_code_execution_result"` - `"encrypted_code_execution_result"` - `tool_use_id: string` - `type: "code_execution_tool_result"` - `"code_execution_tool_result"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `BetaBashCodeExecutionToolResultBlockParam` - `content: BetaBashCodeExecutionToolResultErrorParam | BetaBashCodeExecutionResultBlockParam` - `BetaBashCodeExecutionToolResultErrorParam` - `error_code: "invalid_tool_input" | "unavailable" | "too_many_requests" | 2 more` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `"output_file_too_large"` - `type: "bash_code_execution_tool_result_error"` - `"bash_code_execution_tool_result_error"` - `BetaBashCodeExecutionResultBlockParam` - `content: Array` - `file_id: string` - `type: "bash_code_execution_output"` - `"bash_code_execution_output"` - `return_code: number` - `stderr: string` - `stdout: string` - `type: "bash_code_execution_result"` - `"bash_code_execution_result"` - `tool_use_id: string` - `type: "bash_code_execution_tool_result"` - `"bash_code_execution_tool_result"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `BetaTextEditorCodeExecutionToolResultBlockParam` - `content: BetaTextEditorCodeExecutionToolResultErrorParam | BetaTextEditorCodeExecutionViewResultBlockParam | BetaTextEditorCodeExecutionCreateResultBlockParam | BetaTextEditorCodeExecutionStrReplaceResultBlockParam` - `BetaTextEditorCodeExecutionToolResultErrorParam` - `error_code: "invalid_tool_input" | "unavailable" | "too_many_requests" | 2 more` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `"file_not_found"` - `type: "text_editor_code_execution_tool_result_error"` - `"text_editor_code_execution_tool_result_error"` - `error_message?: string | null` - `BetaTextEditorCodeExecutionViewResultBlockParam` - `content: string` - `file_type: "text" | "image" | "pdf"` - `"text"` - `"image"` - `"pdf"` - `type: "text_editor_code_execution_view_result"` - `"text_editor_code_execution_view_result"` - `num_lines?: number | null` - `start_line?: number | null` - `total_lines?: number | null` - `BetaTextEditorCodeExecutionCreateResultBlockParam` - `is_file_update: boolean` - `type: "text_editor_code_execution_create_result"` - `"text_editor_code_execution_create_result"` - `BetaTextEditorCodeExecutionStrReplaceResultBlockParam` - `type: "text_editor_code_execution_str_replace_result"` - `"text_editor_code_execution_str_replace_result"` - `lines?: Array | 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"` - `"text_editor_code_execution_tool_result"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `BetaToolSearchToolResultBlockParam` - `content: BetaToolSearchToolResultErrorParam | BetaToolSearchToolSearchResultBlockParam` - `BetaToolSearchToolResultErrorParam` - `error_code: "invalid_tool_input" | "unavailable" | "too_many_requests" | "execution_time_exceeded"` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `type: "tool_search_tool_result_error"` - `"tool_search_tool_result_error"` - `BetaToolSearchToolSearchResultBlockParam` - `tool_references: Array` - `tool_name: string` - `type: "tool_reference"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `type: "tool_search_tool_search_result"` - `"tool_search_tool_search_result"` - `tool_use_id: string` - `type: "tool_search_tool_result"` - `"tool_search_tool_result"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `BetaMCPToolUseBlockParam` - `id: string` - `input: Record` - `name: string` - `server_name: string` The name of the MCP server - `type: "mcp_tool_use"` - `"mcp_tool_use"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `BetaRequestMCPToolResultBlockParam` - `tool_use_id: string` - `type: "mcp_tool_result"` - `"mcp_tool_result"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `content?: string | Array` - `string` - `Array` - `text: string` - `type: "text"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `citations?: Array | null` - `is_error?: boolean` - `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. - `file_id: string` - `type: "container_upload"` - `"container_upload"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `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. - `type: "compaction"` - `"compaction"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `content?: string | null` Summary of previously compacted content, or null if compaction failed - `encrypted_content?: string | null` Opaque metadata from prior compaction, to be round-tripped verbatim - `BetaMidConversationSystemBlockParam` System instructions that appear mid-conversation. Use this block to provide or update system-level instructions at a specific point in the conversation, rather than only via the top-level `system` parameter. - `content: Array` System instruction text blocks. - `text: string` - `type: "text"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `citations?: Array | null` - `type: "mid_conv_system"` - `"mid_conv_system"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. ### Beta Content Block Source - `BetaContentBlockSource` - `content: string | Array` - `string` - `Array` - `BetaTextBlockParam` - `text: string` - `type: "text"` - `"text"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `"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`. - `"5m"` - `"1h"` - `citations?: Array | null` - `BetaCitationCharLocationParam` - `cited_text: string` - `document_index: number` - `document_title: string | null` - `end_char_index: number` - `start_char_index: number` - `type: "char_location"` - `"char_location"` - `BetaCitationPageLocationParam` - `cited_text: string` - `document_index: number` - `document_title: string | null` - `end_page_number: number` - `start_page_number: number` - `type: "page_location"` - `"page_location"` - `BetaCitationContentBlockLocationParam` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `document_index: number` - `document_title: string | null` - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. - `type: "content_block_location"` - `"content_block_location"` - `BetaCitationWebSearchResultLocationParam` - `cited_text: string` - `encrypted_index: string` - `title: string | null` - `type: "web_search_result_location"` - `"web_search_result_location"` - `url: string` - `BetaCitationSearchResultLocationParam` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `search_result_index: number` 0-based index of the cited search result among all `search_result` content blocks in the request, in the order they appear across messages and tool results. Counted separately from `document_index`; server-side web search results are not included in this count. - `source: string` - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. - `title: string | null` - `type: "search_result_location"` - `"search_result_location"` - `BetaImageBlockParam` - `source: BetaBase64ImageSource | BetaURLImageSource | BetaFileImageSource` - `BetaBase64ImageSource` - `data: string` - `media_type: "image/jpeg" | "image/png" | "image/gif" | "image/webp"` - `"image/jpeg"` - `"image/png"` - `"image/gif"` - `"image/webp"` - `type: "base64"` - `"base64"` - `BetaURLImageSource` - `type: "url"` - `"url"` - `url: string` - `BetaFileImageSource` - `file_id: string` - `type: "file"` - `"file"` - `type: "image"` - `"image"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `type: "content"` - `"content"` ### Beta Content Block Source Content - `BetaContentBlockSourceContent = BetaTextBlockParam | BetaImageBlockParam` - `BetaTextBlockParam` - `text: string` - `type: "text"` - `"text"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `"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`. - `"5m"` - `"1h"` - `citations?: Array | null` - `BetaCitationCharLocationParam` - `cited_text: string` - `document_index: number` - `document_title: string | null` - `end_char_index: number` - `start_char_index: number` - `type: "char_location"` - `"char_location"` - `BetaCitationPageLocationParam` - `cited_text: string` - `document_index: number` - `document_title: string | null` - `end_page_number: number` - `start_page_number: number` - `type: "page_location"` - `"page_location"` - `BetaCitationContentBlockLocationParam` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `document_index: number` - `document_title: string | null` - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. - `type: "content_block_location"` - `"content_block_location"` - `BetaCitationWebSearchResultLocationParam` - `cited_text: string` - `encrypted_index: string` - `title: string | null` - `type: "web_search_result_location"` - `"web_search_result_location"` - `url: string` - `BetaCitationSearchResultLocationParam` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `search_result_index: number` 0-based index of the cited search result among all `search_result` content blocks in the request, in the order they appear across messages and tool results. Counted separately from `document_index`; server-side web search results are not included in this count. - `source: string` - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. - `title: string | null` - `type: "search_result_location"` - `"search_result_location"` - `BetaImageBlockParam` - `source: BetaBase64ImageSource | BetaURLImageSource | BetaFileImageSource` - `BetaBase64ImageSource` - `data: string` - `media_type: "image/jpeg" | "image/png" | "image/gif" | "image/webp"` - `"image/jpeg"` - `"image/png"` - `"image/gif"` - `"image/webp"` - `type: "base64"` - `"base64"` - `BetaURLImageSource` - `type: "url"` - `"url"` - `url: string` - `BetaFileImageSource` - `file_id: string` - `type: "file"` - `"file"` - `type: "image"` - `"image"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. ### Beta Context Management Config - `BetaContextManagementConfig` - `edits?: Array` List of context management edits to apply - `BetaClearToolUses20250919Edit` - `type: "clear_tool_uses_20250919"` - `"clear_tool_uses_20250919"` - `clear_at_least?: BetaInputTokensClearAtLeast | 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"` - `"input_tokens"` - `value: number` - `clear_tool_inputs?: boolean | Array | null` Whether to clear all tool inputs (bool) or specific tool inputs to clear (list) - `boolean` - `Array` - `exclude_tools?: Array | null` Tool names whose uses are preserved from clearing - `keep?: BetaToolUsesKeep` Number of tool uses to retain in the conversation - `type: "tool_uses"` - `"tool_uses"` - `value: number` - `trigger?: BetaInputTokensTrigger | BetaToolUsesTrigger` Condition that triggers the context management strategy - `BetaInputTokensTrigger` - `type: "input_tokens"` - `"input_tokens"` - `value: number` - `BetaToolUsesTrigger` - `type: "tool_uses"` - `"tool_uses"` - `value: number` - `BetaClearThinking20251015Edit` - `type: "clear_thinking_20251015"` - `"clear_thinking_20251015"` - `keep?: BetaThinkingTurns | BetaAllThinkingTurns | "all"` Number of most recent assistant turns to keep thinking blocks for. Older turns will have their thinking blocks removed. - `BetaThinkingTurns` - `type: "thinking_turns"` - `"thinking_turns"` - `value: number` - `BetaAllThinkingTurns` - `type: "all"` - `"all"` - `"all"` - `"all"` - `BetaCompact20260112Edit` Automatically compact older context when reaching the configured trigger threshold. - `type: "compact_20260112"` - `"compact_20260112"` - `instructions?: string | null` Additional instructions for summarization. - `pause_after_compaction?: boolean` Whether to pause after compaction and return the compaction block to the user. - `trigger?: BetaInputTokensTrigger | null` When to trigger compaction. Defaults to 150000 input tokens. ### Beta Context Management Response - `BetaContextManagementResponse` - `applied_edits: Array` List of context management edits that were applied. - `BetaClearToolUses20250919EditResponse` - `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. - `"clear_tool_uses_20250919"` - `BetaClearThinking20251015EditResponse` - `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. - `"clear_thinking_20251015"` ### Beta Count Tokens Context Management Response - `BetaCountTokensContextManagementResponse` - `original_input_tokens: number` The original token count before context management was applied ### Beta Diagnostics - `BetaDiagnostics` Response envelope for request-level diagnostics. Present (possibly null) whenever the caller supplied `diagnostics` on the request. - `cache_miss_reason: BetaCacheMissModelChanged | BetaCacheMissSystemChanged | BetaCacheMissToolsChanged | 3 more | null` Explains why the prompt cache could not fully reuse the prefix from the request identified by `diagnostics.previous_message_id`. `null` means diagnosis is still pending — the response was serialized before the background comparison completed. - `BetaCacheMissModelChanged` - `cache_missed_input_tokens: number` Approximate number of input tokens that would have been read from cache had the prefix matched the previous request. - `type: "model_changed"` - `"model_changed"` - `BetaCacheMissSystemChanged` - `cache_missed_input_tokens: number` Approximate number of input tokens that would have been read from cache had the prefix matched the previous request. - `type: "system_changed"` - `"system_changed"` - `BetaCacheMissToolsChanged` - `cache_missed_input_tokens: number` Approximate number of input tokens that would have been read from cache had the prefix matched the previous request. - `type: "tools_changed"` - `"tools_changed"` - `BetaCacheMissMessagesChanged` - `cache_missed_input_tokens: number` Approximate number of input tokens that would have been read from cache had the prefix matched the previous request. - `type: "messages_changed"` - `"messages_changed"` - `BetaCacheMissPreviousMessageNotFound` - `type: "previous_message_not_found"` - `"previous_message_not_found"` - `BetaCacheMissUnavailable` - `type: "unavailable"` - `"unavailable"` ### Beta Diagnostics Param - `BetaDiagnosticsParam` Request-level diagnostics. Currently carries the previous response id for prompt-cache divergence reporting. - `previous_message_id?: string | null` The `id` (`msg_...`) from this client's previous /v1/messages response. The server compares that request's prompt fingerprint against this one and returns `diagnostics.cache_miss_reason` when the prompt-cache prefix could not be reused. Pass `null` on the first turn to opt in without a prior message to compare. ### Beta Direct Caller - `BetaDirectCaller` Tool invocation directly from the model. - `type: "direct"` - `"direct"` ### Beta Document Block - `BetaDocumentBlock` - `citations: BetaCitationConfig | null` Citation configuration for the document - `enabled: boolean` - `source: BetaBase64PDFSource | BetaPlainTextSource` - `BetaBase64PDFSource` - `data: string` - `media_type: "application/pdf"` - `"application/pdf"` - `type: "base64"` - `"base64"` - `BetaPlainTextSource` - `data: string` - `media_type: "text/plain"` - `"text/plain"` - `type: "text"` - `"text"` - `title: string | null` The title of the document - `type: "document"` - `"document"` ### Beta Encrypted Code Execution Result Block - `BetaEncryptedCodeExecutionResultBlock` Code execution result with encrypted stdout for PFC + web_search results. - `content: Array` - `file_id: string` - `type: "code_execution_output"` - `"code_execution_output"` - `encrypted_stdout: string` - `return_code: number` - `stderr: string` - `type: "encrypted_code_execution_result"` - `"encrypted_code_execution_result"` ### Beta Encrypted Code Execution Result Block Param - `BetaEncryptedCodeExecutionResultBlockParam` Code execution result with encrypted stdout for PFC + web_search results. - `content: Array` - `file_id: string` - `type: "code_execution_output"` - `"code_execution_output"` - `encrypted_stdout: string` - `return_code: number` - `stderr: string` - `type: "encrypted_code_execution_result"` - `"encrypted_code_execution_result"` ### Beta File Document Source - `BetaFileDocumentSource` - `file_id: string` - `type: "file"` - `"file"` ### Beta File Image Source - `BetaFileImageSource` - `file_id: string` - `type: "file"` - `"file"` ### Beta Image Block Param - `BetaImageBlockParam` - `source: BetaBase64ImageSource | BetaURLImageSource | BetaFileImageSource` - `BetaBase64ImageSource` - `data: string` - `media_type: "image/jpeg" | "image/png" | "image/gif" | "image/webp"` - `"image/jpeg"` - `"image/png"` - `"image/gif"` - `"image/webp"` - `type: "base64"` - `"base64"` - `BetaURLImageSource` - `type: "url"` - `"url"` - `url: string` - `BetaFileImageSource` - `file_id: string` - `type: "file"` - `"file"` - `type: "image"` - `"image"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `"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`. - `"5m"` - `"1h"` ### Beta Input JSON Delta - `BetaInputJSONDelta` - `partial_json: string` - `type: "input_json_delta"` - `"input_json_delta"` ### Beta Input Tokens Clear At Least - `BetaInputTokensClearAtLeast` - `type: "input_tokens"` - `"input_tokens"` - `value: number` ### Beta Input Tokens Trigger - `BetaInputTokensTrigger` - `type: "input_tokens"` - `"input_tokens"` - `value: number` ### Beta Iterations Usage - `BetaIterationsUsage = Array | null` Per-iteration token usage breakdown. Each entry represents one sampling iteration, with its own input/output token counts and cache statistics. This allows you to: - Determine which iterations exceeded long context thresholds (>=200k tokens) - Calculate the true context window size from the last iteration - Understand token accumulation across server-side tool use loops - `BetaMessageIterationUsage` Token usage for a sampling iteration. - `cache_creation: BetaCacheCreation | null` Breakdown of cached tokens by TTL - `ephemeral_1h_input_tokens: number` The number of input tokens used to create the 1 hour cache entry. - `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: "message"` Usage for a sampling iteration - `"message"` - `BetaCompactionIterationUsage` Token usage for a compaction iteration. - `cache_creation: BetaCacheCreation | null` Breakdown of cached tokens by TTL - `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 - `"compaction"` - `BetaAdvisorMessageIterationUsage` Token usage for an advisor sub-inference iteration. - `cache_creation: BetaCacheCreation | null` Breakdown of cached tokens by TTL - `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. - `model: Model` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-opus-4-8" | "claude-opus-4-7" | "claude-mythos-preview" | 15 more` - `"claude-opus-4-8"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-7"` Frontier intelligence for long-running agents and coding - `"claude-mythos-preview"` New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` Fastest model with near-frontier intelligence - `"claude-haiku-4-5-20251001"` Fastest model with near-frontier intelligence - `"claude-opus-4-5"` Premium model combining maximum intelligence with practical performance - `"claude-opus-4-5-20251101"` Premium model combining maximum intelligence with practical performance - `"claude-sonnet-4-5"` High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` High-performance model for agents and coding - `"claude-opus-4-1"` Exceptional model for specialized complex tasks - `"claude-opus-4-1-20250805"` Exceptional model for specialized complex tasks - `"claude-opus-4-0"` Powerful model for complex tasks - `"claude-opus-4-20250514"` Powerful model for complex tasks - `"claude-sonnet-4-0"` High-performance model with extended thinking - `"claude-sonnet-4-20250514"` High-performance model with extended thinking - `"claude-3-haiku-20240307"` Fast and cost-effective model - `(string & {})` - `output_tokens: number` The number of output tokens which were used. - `type: "advisor_message"` Usage for an advisor sub-inference iteration - `"advisor_message"` ### Beta JSON Output Format - `BetaJSONOutputFormat` - `schema: Record` The JSON schema of the format - `type: "json_schema"` - `"json_schema"` ### Beta MCP Tool Config - `BetaMCPToolConfig` Configuration for a specific tool in an MCP toolset. - `defer_loading?: boolean` - `enabled?: boolean` ### Beta MCP Tool Default Config - `BetaMCPToolDefaultConfig` Default configuration for tools in an MCP toolset. - `defer_loading?: boolean` - `enabled?: boolean` ### Beta MCP Tool Result Block - `BetaMCPToolResultBlock` - `content: string | Array` - `string` - `Array` - `citations: Array | 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`. - `BetaCitationCharLocation` - `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"` - `"char_location"` - `BetaCitationPageLocation` - `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"` - `"page_location"` - `BetaCitationContentBlockLocation` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `document_index: number` - `document_title: string | null` - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `file_id: string | null` - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. - `type: "content_block_location"` - `"content_block_location"` - `BetaCitationsWebSearchResultLocation` - `cited_text: string` - `encrypted_index: string` - `title: string | null` - `type: "web_search_result_location"` - `"web_search_result_location"` - `url: string` - `BetaCitationSearchResultLocation` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `search_result_index: number` 0-based index of the cited search result among all `search_result` content blocks in the request, in the order they appear across messages and tool results. Counted separately from `document_index`; server-side web search results are not included in this count. - `source: string` - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. - `title: string | null` - `type: "search_result_location"` - `"search_result_location"` - `text: string` - `type: "text"` - `"text"` - `is_error: boolean` - `tool_use_id: string` - `type: "mcp_tool_result"` - `"mcp_tool_result"` ### Beta MCP Tool Use Block - `BetaMCPToolUseBlock` - `id: string` - `input: Record` - `name: string` The name of the MCP tool - `server_name: string` The name of the MCP server - `type: "mcp_tool_use"` - `"mcp_tool_use"` ### Beta MCP Tool Use Block Param - `BetaMCPToolUseBlockParam` - `id: string` - `input: Record` - `name: string` - `server_name: string` The name of the MCP server - `type: "mcp_tool_use"` - `"mcp_tool_use"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `"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`. - `"5m"` - `"1h"` ### Beta MCP Toolset - `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. - `mcp_server_name: string` Name of the MCP server to configure tools for - `type: "mcp_toolset"` - `"mcp_toolset"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `"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`. - `"5m"` - `"1h"` - `configs?: Record | null` Configuration overrides for specific tools, keyed by tool name - `defer_loading?: boolean` - `enabled?: boolean` - `default_config?: BetaMCPToolDefaultConfig` Default configuration applied to all tools from this server - `defer_loading?: boolean` - `enabled?: boolean` ### Beta Memory Tool 20250818 - `BetaMemoryTool20250818` - `name: "memory"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"memory"` - `type: "memory_20250818"` - `"memory_20250818"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `"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`. - `"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. - `input_examples?: Array>` - `strict?: boolean` When true, guarantees schema validation on tool names and inputs ### Beta Memory Tool 20250818 Command - `BetaMemoryTool20250818Command = BetaMemoryTool20250818ViewCommand | BetaMemoryTool20250818CreateCommand | BetaMemoryTool20250818StrReplaceCommand | 3 more` - `BetaMemoryTool20250818ViewCommand` - `command: "view"` Command type identifier - `"view"` - `path: string` Path to directory or file to view - `view_range?: Array` Optional line range for viewing specific lines - `BetaMemoryTool20250818CreateCommand` - `command: "create"` Command type identifier - `"create"` - `file_text: string` Content to write to the file - `path: string` Path where the file should be created - `BetaMemoryTool20250818StrReplaceCommand` - `command: "str_replace"` Command type identifier - `"str_replace"` - `new_str: string` Text to replace with - `old_str: string` Text to search for and replace - `path: string` Path to the file where text should be replaced - `BetaMemoryTool20250818InsertCommand` - `command: "insert"` Command type identifier - `"insert"` - `insert_line: number` Line number where text should be inserted - `insert_text: string` Text to insert at the specified line - `path: string` Path to the file where text should be inserted - `BetaMemoryTool20250818DeleteCommand` - `command: "delete"` Command type identifier - `"delete"` - `path: string` Path to the file or directory to delete - `BetaMemoryTool20250818RenameCommand` - `command: "rename"` Command type identifier - `"rename"` - `new_path: string` New path for the file or directory - `old_path: string` Current path of the file or directory ### Beta Memory Tool 20250818 Create Command - `BetaMemoryTool20250818CreateCommand` - `command: "create"` Command type identifier - `"create"` - `file_text: string` Content to write to the file - `path: string` Path where the file should be created ### Beta Memory Tool 20250818 Delete Command - `BetaMemoryTool20250818DeleteCommand` - `command: "delete"` Command type identifier - `"delete"` - `path: string` Path to the file or directory to delete ### Beta Memory Tool 20250818 Insert Command - `BetaMemoryTool20250818InsertCommand` - `command: "insert"` Command type identifier - `"insert"` - `insert_line: number` Line number where text should be inserted - `insert_text: string` Text to insert at the specified line - `path: string` Path to the file where text should be inserted ### Beta Memory Tool 20250818 Rename Command - `BetaMemoryTool20250818RenameCommand` - `command: "rename"` Command type identifier - `"rename"` - `new_path: string` New path for the file or directory - `old_path: string` Current path of the file or directory ### Beta Memory Tool 20250818 Str Replace Command - `BetaMemoryTool20250818StrReplaceCommand` - `command: "str_replace"` Command type identifier - `"str_replace"` - `new_str: string` Text to replace with - `old_str: string` Text to search for and replace - `path: string` Path to the file where text should be replaced ### Beta Memory Tool 20250818 View Command - `BetaMemoryTool20250818ViewCommand` - `command: "view"` Command type identifier - `"view"` - `path: string` Path to directory or file to view - `view_range?: Array` Optional line range for viewing specific lines ### Beta Message - `BetaMessage` - `id: string` Unique object identifier. The format and length of IDs may change over time. - `container: BetaContainer | null` 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 | 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) - `"anthropic"` - `"custom"` - `version: string` Skill version or 'latest' for most recent version - `content: Array` Content generated by the model. This is an array of content blocks, each of which has a `type` that determines its shape. Example: ```json [{"type": "text", "text": "Hi, I'm Claude."}] ``` If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. For example, if the input `messages` were: ```json [ {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, {"role": "assistant", "content": "The best answer is ("} ] ``` Then the response `content` might be: ```json [{"type": "text", "text": "B)"}] ``` - `BetaTextBlock` - `citations: Array | 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`. - `BetaCitationCharLocation` - `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"` - `"char_location"` - `BetaCitationPageLocation` - `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"` - `"page_location"` - `BetaCitationContentBlockLocation` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `document_index: number` - `document_title: string | null` - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `file_id: string | null` - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. - `type: "content_block_location"` - `"content_block_location"` - `BetaCitationsWebSearchResultLocation` - `cited_text: string` - `encrypted_index: string` - `title: string | null` - `type: "web_search_result_location"` - `"web_search_result_location"` - `url: string` - `BetaCitationSearchResultLocation` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `search_result_index: number` 0-based index of the cited search result among all `search_result` content blocks in the request, in the order they appear across messages and tool results. Counted separately from `document_index`; server-side web search results are not included in this count. - `source: string` - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. - `title: string | null` - `type: "search_result_location"` - `"search_result_location"` - `text: string` - `type: "text"` - `"text"` - `BetaThinkingBlock` - `signature: string` - `thinking: string` - `type: "thinking"` - `"thinking"` - `BetaRedactedThinkingBlock` - `data: string` - `type: "redacted_thinking"` - `"redacted_thinking"` - `BetaToolUseBlock` - `id: string` - `input: Record` - `name: string` - `type: "tool_use"` - `"tool_use"` - `caller?: BetaDirectCaller | BetaServerToolCaller | BetaServerToolCaller20260120` Tool invocation directly from the model. - `BetaDirectCaller` Tool invocation directly from the model. - `type: "direct"` - `"direct"` - `BetaServerToolCaller` Tool invocation generated by a server-side tool. - `tool_id: string` - `type: "code_execution_20250825"` - `"code_execution_20250825"` - `BetaServerToolCaller20260120` - `tool_id: string` - `type: "code_execution_20260120"` - `"code_execution_20260120"` - `BetaServerToolUseBlock` - `id: string` - `input: Record` - `name: "advisor" | "web_search" | "web_fetch" | 5 more` - `"advisor"` - `"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"` - `"server_tool_use"` - `caller?: BetaDirectCaller | BetaServerToolCaller | BetaServerToolCaller20260120` Tool invocation directly from the model. - `BetaDirectCaller` Tool invocation directly from the model. - `BetaServerToolCaller` Tool invocation generated by a server-side tool. - `BetaServerToolCaller20260120` - `BetaWebSearchToolResultBlock` - `content: BetaWebSearchToolResultBlockContent` - `BetaWebSearchToolResultError` - `error_code: BetaWebSearchToolResultErrorCode` - `"invalid_tool_input"` - `"unavailable"` - `"max_uses_exceeded"` - `"too_many_requests"` - `"query_too_long"` - `"request_too_large"` - `type: "web_search_tool_result_error"` - `"web_search_tool_result_error"` - `Array` - `encrypted_content: string` - `page_age: string | null` - `title: string` - `type: "web_search_result"` - `"web_search_result"` - `url: string` - `tool_use_id: string` - `type: "web_search_tool_result"` - `"web_search_tool_result"` - `caller?: BetaDirectCaller | BetaServerToolCaller | BetaServerToolCaller20260120` Tool invocation directly from the model. - `BetaDirectCaller` Tool invocation directly from the model. - `BetaServerToolCaller` Tool invocation generated by a server-side tool. - `BetaServerToolCaller20260120` - `BetaWebFetchToolResultBlock` - `content: BetaWebFetchToolResultErrorBlock | BetaWebFetchBlock` - `BetaWebFetchToolResultErrorBlock` - `error_code: BetaWebFetchToolResultErrorCode` - `"invalid_tool_input"` - `"url_too_long"` - `"url_not_allowed"` - `"url_not_in_prior_context"` - `"url_not_accessible"` - `"unsupported_content_type"` - `"too_many_requests"` - `"max_uses_exceeded"` - `"unavailable"` - `type: "web_fetch_tool_result_error"` - `"web_fetch_tool_result_error"` - `BetaWebFetchBlock` - `content: BetaDocumentBlock` - `citations: BetaCitationConfig | null` Citation configuration for the document - `enabled: boolean` - `source: BetaBase64PDFSource | BetaPlainTextSource` - `BetaBase64PDFSource` - `data: string` - `media_type: "application/pdf"` - `"application/pdf"` - `type: "base64"` - `"base64"` - `BetaPlainTextSource` - `data: string` - `media_type: "text/plain"` - `"text/plain"` - `type: "text"` - `"text"` - `title: string | null` The title of the document - `type: "document"` - `"document"` - `retrieved_at: string | null` ISO 8601 timestamp when the content was retrieved - `type: "web_fetch_result"` - `"web_fetch_result"` - `url: string` Fetched content URL - `tool_use_id: string` - `type: "web_fetch_tool_result"` - `"web_fetch_tool_result"` - `caller?: BetaDirectCaller | BetaServerToolCaller | BetaServerToolCaller20260120` Tool invocation directly from the model. - `BetaDirectCaller` Tool invocation directly from the model. - `BetaServerToolCaller` Tool invocation generated by a server-side tool. - `BetaServerToolCaller20260120` - `BetaAdvisorToolResultBlock` - `content: BetaAdvisorToolResultError | BetaAdvisorResultBlock | BetaAdvisorRedactedResultBlock` - `BetaAdvisorToolResultError` - `error_code: "max_uses_exceeded" | "prompt_too_long" | "too_many_requests" | 3 more` - `"max_uses_exceeded"` - `"prompt_too_long"` - `"too_many_requests"` - `"overloaded"` - `"unavailable"` - `"execution_time_exceeded"` - `type: "advisor_tool_result_error"` - `"advisor_tool_result_error"` - `BetaAdvisorResultBlock` - `stop_reason: string | null` The advisor sub-inference's stop reason (same values as the top-level message `stop_reason`). `max_tokens` indicates the advisor's output was truncated at the tool's `max_tokens` value or the advisor model's policy cap. - `text: string` - `type: "advisor_result"` - `"advisor_result"` - `BetaAdvisorRedactedResultBlock` - `encrypted_content: string` Opaque blob containing the advisor's output. Round-trip verbatim; do not inspect or modify. - `stop_reason: string | null` The advisor sub-inference's stop reason (same values as the top-level message `stop_reason`). - `type: "advisor_redacted_result"` - `"advisor_redacted_result"` - `tool_use_id: string` - `type: "advisor_tool_result"` - `"advisor_tool_result"` - `BetaCodeExecutionToolResultBlock` - `content: BetaCodeExecutionToolResultBlockContent` Code execution result with encrypted stdout for PFC + web_search results. - `BetaCodeExecutionToolResultError` - `error_code: BetaCodeExecutionToolResultErrorCode` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `type: "code_execution_tool_result_error"` - `"code_execution_tool_result_error"` - `BetaCodeExecutionResultBlock` - `content: Array` - `file_id: string` - `type: "code_execution_output"` - `"code_execution_output"` - `return_code: number` - `stderr: string` - `stdout: string` - `type: "code_execution_result"` - `"code_execution_result"` - `BetaEncryptedCodeExecutionResultBlock` Code execution result with encrypted stdout for PFC + web_search results. - `content: Array` - `file_id: string` - `type: "code_execution_output"` - `encrypted_stdout: string` - `return_code: number` - `stderr: string` - `type: "encrypted_code_execution_result"` - `"encrypted_code_execution_result"` - `tool_use_id: string` - `type: "code_execution_tool_result"` - `"code_execution_tool_result"` - `BetaBashCodeExecutionToolResultBlock` - `content: BetaBashCodeExecutionToolResultError | BetaBashCodeExecutionResultBlock` - `BetaBashCodeExecutionToolResultError` - `error_code: "invalid_tool_input" | "unavailable" | "too_many_requests" | 2 more` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `"output_file_too_large"` - `type: "bash_code_execution_tool_result_error"` - `"bash_code_execution_tool_result_error"` - `BetaBashCodeExecutionResultBlock` - `content: Array` - `file_id: string` - `type: "bash_code_execution_output"` - `"bash_code_execution_output"` - `return_code: number` - `stderr: string` - `stdout: string` - `type: "bash_code_execution_result"` - `"bash_code_execution_result"` - `tool_use_id: string` - `type: "bash_code_execution_tool_result"` - `"bash_code_execution_tool_result"` - `BetaTextEditorCodeExecutionToolResultBlock` - `content: BetaTextEditorCodeExecutionToolResultError | BetaTextEditorCodeExecutionViewResultBlock | BetaTextEditorCodeExecutionCreateResultBlock | BetaTextEditorCodeExecutionStrReplaceResultBlock` - `BetaTextEditorCodeExecutionToolResultError` - `error_code: "invalid_tool_input" | "unavailable" | "too_many_requests" | 2 more` - `"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"` - `"text_editor_code_execution_tool_result_error"` - `BetaTextEditorCodeExecutionViewResultBlock` - `content: string` - `file_type: "text" | "image" | "pdf"` - `"text"` - `"image"` - `"pdf"` - `num_lines: number | null` - `start_line: number | null` - `total_lines: number | null` - `type: "text_editor_code_execution_view_result"` - `"text_editor_code_execution_view_result"` - `BetaTextEditorCodeExecutionCreateResultBlock` - `is_file_update: boolean` - `type: "text_editor_code_execution_create_result"` - `"text_editor_code_execution_create_result"` - `BetaTextEditorCodeExecutionStrReplaceResultBlock` - `lines: Array | 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"` - `"text_editor_code_execution_str_replace_result"` - `tool_use_id: string` - `type: "text_editor_code_execution_tool_result"` - `"text_editor_code_execution_tool_result"` - `BetaToolSearchToolResultBlock` - `content: BetaToolSearchToolResultError | BetaToolSearchToolSearchResultBlock` - `BetaToolSearchToolResultError` - `error_code: "invalid_tool_input" | "unavailable" | "too_many_requests" | "execution_time_exceeded"` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `error_message: string | null` - `type: "tool_search_tool_result_error"` - `"tool_search_tool_result_error"` - `BetaToolSearchToolSearchResultBlock` - `tool_references: Array` - `tool_name: string` - `type: "tool_reference"` - `"tool_reference"` - `type: "tool_search_tool_search_result"` - `"tool_search_tool_search_result"` - `tool_use_id: string` - `type: "tool_search_tool_result"` - `"tool_search_tool_result"` - `BetaMCPToolUseBlock` - `id: string` - `input: Record` - `name: string` The name of the MCP tool - `server_name: string` The name of the MCP server - `type: "mcp_tool_use"` - `"mcp_tool_use"` - `BetaMCPToolResultBlock` - `content: string | Array` - `string` - `Array` - `citations: Array | 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`. - `text: string` - `type: "text"` - `is_error: boolean` - `tool_use_id: string` - `type: "mcp_tool_result"` - `"mcp_tool_result"` - `BetaContainerUploadBlock` Response model for a file uploaded to the container. - `file_id: string` - `type: "container_upload"` - `"container_upload"` - `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. - `content: string | null` Summary of compacted content, or null if compaction failed - `encrypted_content: string | null` Opaque metadata from prior compaction, to be round-tripped verbatim - `type: "compaction"` - `"compaction"` - `context_management: BetaContextManagementResponse | null` Context management response. Information about context management strategies applied during the request. - `applied_edits: Array` List of context management edits that were applied. - `BetaClearToolUses20250919EditResponse` - `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. - `"clear_tool_uses_20250919"` - `BetaClearThinking20251015EditResponse` - `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. - `"clear_thinking_20251015"` - `diagnostics: BetaDiagnostics | null` Response envelope for request-level diagnostics. Present (possibly null) whenever the caller supplied `diagnostics` on the request. - `cache_miss_reason: BetaCacheMissModelChanged | BetaCacheMissSystemChanged | BetaCacheMissToolsChanged | 3 more | null` Explains why the prompt cache could not fully reuse the prefix from the request identified by `diagnostics.previous_message_id`. `null` means diagnosis is still pending — the response was serialized before the background comparison completed. - `BetaCacheMissModelChanged` - `cache_missed_input_tokens: number` Approximate number of input tokens that would have been read from cache had the prefix matched the previous request. - `type: "model_changed"` - `"model_changed"` - `BetaCacheMissSystemChanged` - `cache_missed_input_tokens: number` Approximate number of input tokens that would have been read from cache had the prefix matched the previous request. - `type: "system_changed"` - `"system_changed"` - `BetaCacheMissToolsChanged` - `cache_missed_input_tokens: number` Approximate number of input tokens that would have been read from cache had the prefix matched the previous request. - `type: "tools_changed"` - `"tools_changed"` - `BetaCacheMissMessagesChanged` - `cache_missed_input_tokens: number` Approximate number of input tokens that would have been read from cache had the prefix matched the previous request. - `type: "messages_changed"` - `"messages_changed"` - `BetaCacheMissPreviousMessageNotFound` - `type: "previous_message_not_found"` - `"previous_message_not_found"` - `BetaCacheMissUnavailable` - `type: "unavailable"` - `"unavailable"` - `model: Model` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-opus-4-8" | "claude-opus-4-7" | "claude-mythos-preview" | 15 more` - `"claude-opus-4-8"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-7"` Frontier intelligence for long-running agents and coding - `"claude-mythos-preview"` New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` Fastest model with near-frontier intelligence - `"claude-haiku-4-5-20251001"` Fastest model with near-frontier intelligence - `"claude-opus-4-5"` Premium model combining maximum intelligence with practical performance - `"claude-opus-4-5-20251101"` Premium model combining maximum intelligence with practical performance - `"claude-sonnet-4-5"` High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` High-performance model for agents and coding - `"claude-opus-4-1"` Exceptional model for specialized complex tasks - `"claude-opus-4-1-20250805"` Exceptional model for specialized complex tasks - `"claude-opus-4-0"` Powerful model for complex tasks - `"claude-opus-4-20250514"` Powerful model for complex tasks - `"claude-sonnet-4-0"` High-performance model with extended thinking - `"claude-sonnet-4-20250514"` High-performance model with extended thinking - `"claude-3-haiku-20240307"` Fast and cost-effective model - `(string & {})` - `role: "assistant"` Conversational role of the generated message. This will always be `"assistant"`. - `"assistant"` - `stop_details: BetaRefusalStopDetails | null` Structured information about a refusal. - `category: "cyber" | "bio" | null` The policy category that triggered the refusal. `null` when the refusal doesn't map to a named category. - `"cyber"` - `"bio"` - `explanation: string | null` Human-readable explanation of the refusal. This text is not guaranteed to be stable. `null` when no explanation is available for the category. - `type: "refusal"` - `"refusal"` - `stop_reason: BetaStopReason | null` The reason that we stopped. This may be one the following values: * `"end_turn"`: the model reached a natural stopping point * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated * `"tool_use"`: the model invoked one or more tools * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. * `"refusal"`: when streaming classifiers intervene to handle potential policy violations In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. - `"end_turn"` - `"max_tokens"` - `"stop_sequence"` - `"tool_use"` - `"pause_turn"` - `"compaction"` - `"refusal"` - `"model_context_window_exceeded"` - `stop_sequence: string | null` Which custom stop sequence was generated, if any. This value will be a non-null string if one of your custom stop sequences was generated. - `type: "message"` Object type. For Messages, this is always `"message"`. - `"message"` - `usage: BetaUsage` Billing and rate-limit usage. Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. For example, `output_tokens` will be non-zero, even for an empty string response from Claude. Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. - `cache_creation: BetaCacheCreation | null` Breakdown of cached tokens by TTL - `ephemeral_1h_input_tokens: number` The number of input tokens used to create the 1 hour cache entry. - `ephemeral_5m_input_tokens: number` The number of input tokens used to create the 5 minute cache entry. - `cache_creation_input_tokens: number | null` The number of input tokens used to create the cache entry. - `cache_read_input_tokens: number | null` The number of input tokens read from the cache. - `inference_geo: string | null` The geographic region where inference was performed for this request. - `input_tokens: number` The number of input tokens which were used. - `iterations: BetaIterationsUsage | null` Per-iteration token usage breakdown. Each entry represents one sampling iteration, with its own input/output token counts and cache statistics. This allows you to: - Determine which iterations exceeded long context thresholds (>=200k tokens) - Calculate the true context window size from the last iteration - Understand token accumulation across server-side tool use loops - `BetaMessageIterationUsage` Token usage for a sampling iteration. - `cache_creation: BetaCacheCreation | null` Breakdown of cached tokens by TTL - `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: "message"` Usage for a sampling iteration - `"message"` - `BetaCompactionIterationUsage` Token usage for a compaction iteration. - `cache_creation: BetaCacheCreation | null` Breakdown of cached tokens by TTL - `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 - `"compaction"` - `BetaAdvisorMessageIterationUsage` Token usage for an advisor sub-inference iteration. - `cache_creation: BetaCacheCreation | null` Breakdown of cached tokens by TTL - `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. - `model: Model` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `output_tokens: number` The number of output tokens which were used. - `type: "advisor_message"` Usage for an advisor sub-inference iteration - `"advisor_message"` - `output_tokens: number` The number of output tokens which were used. - `output_tokens_details: BetaOutputTokensDetails | null` Breakdown of output tokens by category. `output_tokens` remains the inclusive, authoritative total used for billing. This object provides a read-only decomposition for observability — for example, how many of the billed output tokens were spent on internal reasoning that may have been summarized before being returned to you. - `thinking_tokens: number` Number of output tokens the model generated as internal reasoning, including the thinking-block delimiter tokens. Reflects the raw reasoning the model produced, not the (possibly shorter) summarized thinking text returned in the response body. Computed by re-tokenizing the raw reasoning text, so it may differ from the model's exact generation count by a small number of tokens. Always ≤ `output_tokens`; `output_tokens - thinking_tokens` approximates the non-reasoning output. - `server_tool_use: BetaServerToolUsage | null` The number of server tool requests. - `web_fetch_requests: number` The number of web fetch tool requests. - `web_search_requests: number` The number of web search tool requests. - `service_tier: "standard" | "priority" | "batch" | null` If the request used the priority, standard, or batch tier. - `"standard"` - `"priority"` - `"batch"` - `speed: "standard" | "fast" | null` The inference speed mode used for this request. - `"standard"` - `"fast"` ### Beta Message Delta Usage - `BetaMessageDeltaUsage` - `cache_creation_input_tokens: number | null` The cumulative number of input tokens used to create the cache entry. - `cache_read_input_tokens: number | null` The cumulative number of input tokens read from the cache. - `input_tokens: number | null` The cumulative number of input tokens which were used. - `iterations: BetaIterationsUsage | null` Per-iteration token usage breakdown. Each entry represents one sampling iteration, with its own input/output token counts and cache statistics. This allows you to: - Determine which iterations exceeded long context thresholds (>=200k tokens) - Calculate the true context window size from the last iteration - Understand token accumulation across server-side tool use loops - `BetaMessageIterationUsage` Token usage for a sampling iteration. - `cache_creation: BetaCacheCreation | null` Breakdown of cached tokens by TTL - `ephemeral_1h_input_tokens: number` The number of input tokens used to create the 1 hour cache entry. - `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: "message"` Usage for a sampling iteration - `"message"` - `BetaCompactionIterationUsage` Token usage for a compaction iteration. - `cache_creation: BetaCacheCreation | null` Breakdown of cached tokens by TTL - `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 - `"compaction"` - `BetaAdvisorMessageIterationUsage` Token usage for an advisor sub-inference iteration. - `cache_creation: BetaCacheCreation | null` Breakdown of cached tokens by TTL - `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. - `model: Model` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-opus-4-8" | "claude-opus-4-7" | "claude-mythos-preview" | 15 more` - `"claude-opus-4-8"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-7"` Frontier intelligence for long-running agents and coding - `"claude-mythos-preview"` New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` Fastest model with near-frontier intelligence - `"claude-haiku-4-5-20251001"` Fastest model with near-frontier intelligence - `"claude-opus-4-5"` Premium model combining maximum intelligence with practical performance - `"claude-opus-4-5-20251101"` Premium model combining maximum intelligence with practical performance - `"claude-sonnet-4-5"` High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` High-performance model for agents and coding - `"claude-opus-4-1"` Exceptional model for specialized complex tasks - `"claude-opus-4-1-20250805"` Exceptional model for specialized complex tasks - `"claude-opus-4-0"` Powerful model for complex tasks - `"claude-opus-4-20250514"` Powerful model for complex tasks - `"claude-sonnet-4-0"` High-performance model with extended thinking - `"claude-sonnet-4-20250514"` High-performance model with extended thinking - `"claude-3-haiku-20240307"` Fast and cost-effective model - `(string & {})` - `output_tokens: number` The number of output tokens which were used. - `type: "advisor_message"` Usage for an advisor sub-inference iteration - `"advisor_message"` - `output_tokens: number` The cumulative number of output tokens which were used. - `output_tokens_details: BetaOutputTokensDetails | null` Breakdown of output tokens by category. `output_tokens` remains the inclusive, authoritative total used for billing. This object provides a read-only decomposition for observability — for example, how many of the billed output tokens were spent on internal reasoning that may have been summarized before being returned to you. - `thinking_tokens: number` Number of output tokens the model generated as internal reasoning, including the thinking-block delimiter tokens. Reflects the raw reasoning the model produced, not the (possibly shorter) summarized thinking text returned in the response body. Computed by re-tokenizing the raw reasoning text, so it may differ from the model's exact generation count by a small number of tokens. Always ≤ `output_tokens`; `output_tokens - thinking_tokens` approximates the non-reasoning output. - `server_tool_use: BetaServerToolUsage | null` The number of server tool requests. - `web_fetch_requests: number` The number of web fetch tool requests. - `web_search_requests: number` The number of web search tool requests. ### Beta Message Iteration Usage - `BetaMessageIterationUsage` Token usage for a sampling iteration. - `cache_creation: BetaCacheCreation | null` Breakdown of cached tokens by TTL - `ephemeral_1h_input_tokens: number` The number of input tokens used to create the 1 hour cache entry. - `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: "message"` Usage for a sampling iteration - `"message"` ### Beta Message Param - `BetaMessageParam` - `content: string | Array` - `string` - `Array` - `BetaTextBlockParam` - `text: string` - `type: "text"` - `"text"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `"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`. - `"5m"` - `"1h"` - `citations?: Array | null` - `BetaCitationCharLocationParam` - `cited_text: string` - `document_index: number` - `document_title: string | null` - `end_char_index: number` - `start_char_index: number` - `type: "char_location"` - `"char_location"` - `BetaCitationPageLocationParam` - `cited_text: string` - `document_index: number` - `document_title: string | null` - `end_page_number: number` - `start_page_number: number` - `type: "page_location"` - `"page_location"` - `BetaCitationContentBlockLocationParam` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `document_index: number` - `document_title: string | null` - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. - `type: "content_block_location"` - `"content_block_location"` - `BetaCitationWebSearchResultLocationParam` - `cited_text: string` - `encrypted_index: string` - `title: string | null` - `type: "web_search_result_location"` - `"web_search_result_location"` - `url: string` - `BetaCitationSearchResultLocationParam` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `search_result_index: number` 0-based index of the cited search result among all `search_result` content blocks in the request, in the order they appear across messages and tool results. Counted separately from `document_index`; server-side web search results are not included in this count. - `source: string` - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. - `title: string | null` - `type: "search_result_location"` - `"search_result_location"` - `BetaImageBlockParam` - `source: BetaBase64ImageSource | BetaURLImageSource | BetaFileImageSource` - `BetaBase64ImageSource` - `data: string` - `media_type: "image/jpeg" | "image/png" | "image/gif" | "image/webp"` - `"image/jpeg"` - `"image/png"` - `"image/gif"` - `"image/webp"` - `type: "base64"` - `"base64"` - `BetaURLImageSource` - `type: "url"` - `"url"` - `url: string` - `BetaFileImageSource` - `file_id: string` - `type: "file"` - `"file"` - `type: "image"` - `"image"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `BetaRequestDocumentBlock` - `source: BetaBase64PDFSource | BetaPlainTextSource | BetaContentBlockSource | 2 more` - `BetaBase64PDFSource` - `data: string` - `media_type: "application/pdf"` - `"application/pdf"` - `type: "base64"` - `"base64"` - `BetaPlainTextSource` - `data: string` - `media_type: "text/plain"` - `"text/plain"` - `type: "text"` - `"text"` - `BetaContentBlockSource` - `content: string | Array` - `string` - `Array` - `BetaTextBlockParam` - `BetaImageBlockParam` - `type: "content"` - `"content"` - `BetaURLPDFSource` - `type: "url"` - `"url"` - `url: string` - `BetaFileDocumentSource` - `file_id: string` - `type: "file"` - `"file"` - `type: "document"` - `"document"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `citations?: BetaCitationsConfigParam | null` - `enabled?: boolean` - `context?: string | null` - `title?: string | null` - `BetaSearchResultBlockParam` - `content: Array` - `text: string` - `type: "text"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `citations?: Array | null` - `source: string` - `title: string` - `type: "search_result"` - `"search_result"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `citations?: BetaCitationsConfigParam` - `BetaThinkingBlockParam` - `signature: string` - `thinking: string` - `type: "thinking"` - `"thinking"` - `BetaRedactedThinkingBlockParam` - `data: string` - `type: "redacted_thinking"` - `"redacted_thinking"` - `BetaToolUseBlockParam` - `id: string` - `input: Record` - `name: string` - `type: "tool_use"` - `"tool_use"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `caller?: BetaDirectCaller | BetaServerToolCaller | BetaServerToolCaller20260120` Tool invocation directly from the model. - `BetaDirectCaller` Tool invocation directly from the model. - `type: "direct"` - `"direct"` - `BetaServerToolCaller` Tool invocation generated by a server-side tool. - `tool_id: string` - `type: "code_execution_20250825"` - `"code_execution_20250825"` - `BetaServerToolCaller20260120` - `tool_id: string` - `type: "code_execution_20260120"` - `"code_execution_20260120"` - `BetaToolResultBlockParam` - `tool_use_id: string` - `type: "tool_result"` - `"tool_result"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `content?: string | Array` - `string` - `Array` - `BetaTextBlockParam` - `BetaImageBlockParam` - `BetaSearchResultBlockParam` - `BetaRequestDocumentBlock` - `BetaToolReferenceBlockParam` Tool reference block that can be included in tool_result content. - `tool_name: string` - `type: "tool_reference"` - `"tool_reference"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `is_error?: boolean` - `BetaServerToolUseBlockParam` - `id: string` - `input: Record` - `name: "advisor" | "web_search" | "web_fetch" | 5 more` - `"advisor"` - `"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"` - `"server_tool_use"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `caller?: BetaDirectCaller | BetaServerToolCaller | BetaServerToolCaller20260120` Tool invocation directly from the model. - `BetaDirectCaller` Tool invocation directly from the model. - `BetaServerToolCaller` Tool invocation generated by a server-side tool. - `BetaServerToolCaller20260120` - `BetaWebSearchToolResultBlockParam` - `content: BetaWebSearchToolResultBlockParamContent` - `Array` - `encrypted_content: string` - `title: string` - `type: "web_search_result"` - `"web_search_result"` - `url: string` - `page_age?: string | null` - `BetaWebSearchToolRequestError` - `error_code: BetaWebSearchToolResultErrorCode` - `"invalid_tool_input"` - `"unavailable"` - `"max_uses_exceeded"` - `"too_many_requests"` - `"query_too_long"` - `"request_too_large"` - `type: "web_search_tool_result_error"` - `"web_search_tool_result_error"` - `tool_use_id: string` - `type: "web_search_tool_result"` - `"web_search_tool_result"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `caller?: BetaDirectCaller | BetaServerToolCaller | BetaServerToolCaller20260120` Tool invocation directly from the model. - `BetaDirectCaller` Tool invocation directly from the model. - `BetaServerToolCaller` Tool invocation generated by a server-side tool. - `BetaServerToolCaller20260120` - `BetaWebFetchToolResultBlockParam` - `content: BetaWebFetchToolResultErrorBlockParam | BetaWebFetchBlockParam` - `BetaWebFetchToolResultErrorBlockParam` - `error_code: BetaWebFetchToolResultErrorCode` - `"invalid_tool_input"` - `"url_too_long"` - `"url_not_allowed"` - `"url_not_in_prior_context"` - `"url_not_accessible"` - `"unsupported_content_type"` - `"too_many_requests"` - `"max_uses_exceeded"` - `"unavailable"` - `type: "web_fetch_tool_result_error"` - `"web_fetch_tool_result_error"` - `BetaWebFetchBlockParam` - `content: BetaRequestDocumentBlock` - `type: "web_fetch_result"` - `"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"` - `"web_fetch_tool_result"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `caller?: BetaDirectCaller | BetaServerToolCaller | BetaServerToolCaller20260120` Tool invocation directly from the model. - `BetaDirectCaller` Tool invocation directly from the model. - `BetaServerToolCaller` Tool invocation generated by a server-side tool. - `BetaServerToolCaller20260120` - `BetaAdvisorToolResultBlockParam` - `content: BetaAdvisorToolResultErrorParam | BetaAdvisorResultBlockParam | BetaAdvisorRedactedResultBlockParam` - `BetaAdvisorToolResultErrorParam` - `error_code: "max_uses_exceeded" | "prompt_too_long" | "too_many_requests" | 3 more` - `"max_uses_exceeded"` - `"prompt_too_long"` - `"too_many_requests"` - `"overloaded"` - `"unavailable"` - `"execution_time_exceeded"` - `type: "advisor_tool_result_error"` - `"advisor_tool_result_error"` - `BetaAdvisorResultBlockParam` - `text: string` - `type: "advisor_result"` - `"advisor_result"` - `stop_reason?: string | null` - `BetaAdvisorRedactedResultBlockParam` - `encrypted_content: string` Opaque blob produced by a prior response; must be round-tripped verbatim. - `type: "advisor_redacted_result"` - `"advisor_redacted_result"` - `stop_reason?: string | null` - `tool_use_id: string` - `type: "advisor_tool_result"` - `"advisor_tool_result"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `BetaCodeExecutionToolResultBlockParam` - `content: BetaCodeExecutionToolResultBlockParamContent` Code execution result with encrypted stdout for PFC + web_search results. - `BetaCodeExecutionToolResultErrorParam` - `error_code: BetaCodeExecutionToolResultErrorCode` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `type: "code_execution_tool_result_error"` - `"code_execution_tool_result_error"` - `BetaCodeExecutionResultBlockParam` - `content: Array` - `file_id: string` - `type: "code_execution_output"` - `"code_execution_output"` - `return_code: number` - `stderr: string` - `stdout: string` - `type: "code_execution_result"` - `"code_execution_result"` - `BetaEncryptedCodeExecutionResultBlockParam` Code execution result with encrypted stdout for PFC + web_search results. - `content: Array` - `file_id: string` - `type: "code_execution_output"` - `encrypted_stdout: string` - `return_code: number` - `stderr: string` - `type: "encrypted_code_execution_result"` - `"encrypted_code_execution_result"` - `tool_use_id: string` - `type: "code_execution_tool_result"` - `"code_execution_tool_result"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `BetaBashCodeExecutionToolResultBlockParam` - `content: BetaBashCodeExecutionToolResultErrorParam | BetaBashCodeExecutionResultBlockParam` - `BetaBashCodeExecutionToolResultErrorParam` - `error_code: "invalid_tool_input" | "unavailable" | "too_many_requests" | 2 more` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `"output_file_too_large"` - `type: "bash_code_execution_tool_result_error"` - `"bash_code_execution_tool_result_error"` - `BetaBashCodeExecutionResultBlockParam` - `content: Array` - `file_id: string` - `type: "bash_code_execution_output"` - `"bash_code_execution_output"` - `return_code: number` - `stderr: string` - `stdout: string` - `type: "bash_code_execution_result"` - `"bash_code_execution_result"` - `tool_use_id: string` - `type: "bash_code_execution_tool_result"` - `"bash_code_execution_tool_result"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `BetaTextEditorCodeExecutionToolResultBlockParam` - `content: BetaTextEditorCodeExecutionToolResultErrorParam | BetaTextEditorCodeExecutionViewResultBlockParam | BetaTextEditorCodeExecutionCreateResultBlockParam | BetaTextEditorCodeExecutionStrReplaceResultBlockParam` - `BetaTextEditorCodeExecutionToolResultErrorParam` - `error_code: "invalid_tool_input" | "unavailable" | "too_many_requests" | 2 more` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `"file_not_found"` - `type: "text_editor_code_execution_tool_result_error"` - `"text_editor_code_execution_tool_result_error"` - `error_message?: string | null` - `BetaTextEditorCodeExecutionViewResultBlockParam` - `content: string` - `file_type: "text" | "image" | "pdf"` - `"text"` - `"image"` - `"pdf"` - `type: "text_editor_code_execution_view_result"` - `"text_editor_code_execution_view_result"` - `num_lines?: number | null` - `start_line?: number | null` - `total_lines?: number | null` - `BetaTextEditorCodeExecutionCreateResultBlockParam` - `is_file_update: boolean` - `type: "text_editor_code_execution_create_result"` - `"text_editor_code_execution_create_result"` - `BetaTextEditorCodeExecutionStrReplaceResultBlockParam` - `type: "text_editor_code_execution_str_replace_result"` - `"text_editor_code_execution_str_replace_result"` - `lines?: Array | 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"` - `"text_editor_code_execution_tool_result"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `BetaToolSearchToolResultBlockParam` - `content: BetaToolSearchToolResultErrorParam | BetaToolSearchToolSearchResultBlockParam` - `BetaToolSearchToolResultErrorParam` - `error_code: "invalid_tool_input" | "unavailable" | "too_many_requests" | "execution_time_exceeded"` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `type: "tool_search_tool_result_error"` - `"tool_search_tool_result_error"` - `BetaToolSearchToolSearchResultBlockParam` - `tool_references: Array` - `tool_name: string` - `type: "tool_reference"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `type: "tool_search_tool_search_result"` - `"tool_search_tool_search_result"` - `tool_use_id: string` - `type: "tool_search_tool_result"` - `"tool_search_tool_result"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `BetaMCPToolUseBlockParam` - `id: string` - `input: Record` - `name: string` - `server_name: string` The name of the MCP server - `type: "mcp_tool_use"` - `"mcp_tool_use"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `BetaRequestMCPToolResultBlockParam` - `tool_use_id: string` - `type: "mcp_tool_result"` - `"mcp_tool_result"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `content?: string | Array` - `string` - `Array` - `text: string` - `type: "text"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `citations?: Array | null` - `is_error?: boolean` - `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. - `file_id: string` - `type: "container_upload"` - `"container_upload"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `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. - `type: "compaction"` - `"compaction"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `content?: string | null` Summary of previously compacted content, or null if compaction failed - `encrypted_content?: string | null` Opaque metadata from prior compaction, to be round-tripped verbatim - `BetaMidConversationSystemBlockParam` System instructions that appear mid-conversation. Use this block to provide or update system-level instructions at a specific point in the conversation, rather than only via the top-level `system` parameter. - `content: Array` System instruction text blocks. - `text: string` - `type: "text"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `citations?: Array | null` - `type: "mid_conv_system"` - `"mid_conv_system"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `role: "user" | "assistant" | "system"` - `"user"` - `"assistant"` - `"system"` ### Beta Message Tokens Count - `BetaMessageTokensCount` - `context_management: BetaCountTokensContextManagementResponse | null` Information about context management applied to the message. - `original_input_tokens: number` The original token count before context management was applied - `input_tokens: number` The total number of tokens across the provided list of messages, system prompt, and tools. ### Beta Metadata - `BetaMetadata` - `user_id?: string | null` An external identifier for the user who is associated with the request. This should be a uuid, hash value, or other opaque identifier. Anthropic may use this id to help detect abuse. Do not include any identifying information such as name, email address, or phone number. ### Beta Mid Conversation System Block Param - `BetaMidConversationSystemBlockParam` System instructions that appear mid-conversation. Use this block to provide or update system-level instructions at a specific point in the conversation, rather than only via the top-level `system` parameter. - `content: Array` System instruction text blocks. - `text: string` - `type: "text"` - `"text"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `"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`. - `"5m"` - `"1h"` - `citations?: Array | null` - `BetaCitationCharLocationParam` - `cited_text: string` - `document_index: number` - `document_title: string | null` - `end_char_index: number` - `start_char_index: number` - `type: "char_location"` - `"char_location"` - `BetaCitationPageLocationParam` - `cited_text: string` - `document_index: number` - `document_title: string | null` - `end_page_number: number` - `start_page_number: number` - `type: "page_location"` - `"page_location"` - `BetaCitationContentBlockLocationParam` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `document_index: number` - `document_title: string | null` - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. - `type: "content_block_location"` - `"content_block_location"` - `BetaCitationWebSearchResultLocationParam` - `cited_text: string` - `encrypted_index: string` - `title: string | null` - `type: "web_search_result_location"` - `"web_search_result_location"` - `url: string` - `BetaCitationSearchResultLocationParam` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `search_result_index: number` 0-based index of the cited search result among all `search_result` content blocks in the request, in the order they appear across messages and tool results. Counted separately from `document_index`; server-side web search results are not included in this count. - `source: string` - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. - `title: string | null` - `type: "search_result_location"` - `"search_result_location"` - `type: "mid_conv_system"` - `"mid_conv_system"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. ### Beta Output Config - `BetaOutputConfig` - `effort?: "low" | "medium" | "high" | 2 more | null` All possible effort levels. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `format?: BetaJSONOutputFormat | null` A schema to specify Claude's output format in responses. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) - `schema: Record` The JSON schema of the format - `type: "json_schema"` - `"json_schema"` - `task_budget?: BetaTokenTaskBudget | null` User-configurable total token budget across contexts. - `total: number` Total token budget across all contexts in the session. - `type: "tokens"` The budget type. Currently only 'tokens' is supported. - `"tokens"` - `remaining?: number | null` Remaining tokens in the budget. Use this to track usage across contexts when implementing compaction client-side. Defaults to total if not provided. ### Beta Output Tokens Details - `BetaOutputTokensDetails` - `thinking_tokens: number` Number of output tokens the model generated as internal reasoning, including the thinking-block delimiter tokens. Reflects the raw reasoning the model produced, not the (possibly shorter) summarized thinking text returned in the response body. Computed by re-tokenizing the raw reasoning text, so it may differ from the model's exact generation count by a small number of tokens. Always ≤ `output_tokens`; `output_tokens - thinking_tokens` approximates the non-reasoning output. ### Beta Plain Text Source - `BetaPlainTextSource` - `data: string` - `media_type: "text/plain"` - `"text/plain"` - `type: "text"` - `"text"` ### Beta Raw Content Block Delta - `BetaRawContentBlockDelta = BetaTextDelta | BetaInputJSONDelta | BetaCitationsDelta | 3 more` - `BetaTextDelta` - `text: string` - `type: "text_delta"` - `"text_delta"` - `BetaInputJSONDelta` - `partial_json: string` - `type: "input_json_delta"` - `"input_json_delta"` - `BetaCitationsDelta` - `citation: BetaCitationCharLocation | BetaCitationPageLocation | BetaCitationContentBlockLocation | 2 more` - `BetaCitationCharLocation` - `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"` - `"char_location"` - `BetaCitationPageLocation` - `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"` - `"page_location"` - `BetaCitationContentBlockLocation` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `document_index: number` - `document_title: string | null` - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `file_id: string | null` - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. - `type: "content_block_location"` - `"content_block_location"` - `BetaCitationsWebSearchResultLocation` - `cited_text: string` - `encrypted_index: string` - `title: string | null` - `type: "web_search_result_location"` - `"web_search_result_location"` - `url: string` - `BetaCitationSearchResultLocation` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `search_result_index: number` 0-based index of the cited search result among all `search_result` content blocks in the request, in the order they appear across messages and tool results. Counted separately from `document_index`; server-side web search results are not included in this count. - `source: string` - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. - `title: string | null` - `type: "search_result_location"` - `"search_result_location"` - `type: "citations_delta"` - `"citations_delta"` - `BetaThinkingDelta` - `estimated_tokens: number | null` Per-frame increment of a coarse, running estimate of the tokens this thinking block has produced so far. Present whenever the `thinking-token-count-2026-05-13` beta is set; `null` unless `thinking.display` resolves to `"omitted"` and a count is due this frame. Sum the increments across `thinking_delta` frames on this block for a progress indicator. Each increment is a non-negative multiple of a fixed quantum and the cadence is rate-limited, so this is a deliberately lossy display hint, not a billable count; `usage.output_tokens` remains authoritative. - `thinking: string` - `type: "thinking_delta"` - `"thinking_delta"` - `BetaSignatureDelta` - `signature: string` - `type: "signature_delta"` - `"signature_delta"` - `BetaCompactionContentBlockDelta` - `content: string | null` - `encrypted_content: string | null` Opaque metadata from prior compaction, to be round-tripped verbatim - `type: "compaction_delta"` - `"compaction_delta"` ### Beta Raw Content Block Delta Event - `BetaRawContentBlockDeltaEvent` - `delta: BetaRawContentBlockDelta` - `BetaTextDelta` - `text: string` - `type: "text_delta"` - `"text_delta"` - `BetaInputJSONDelta` - `partial_json: string` - `type: "input_json_delta"` - `"input_json_delta"` - `BetaCitationsDelta` - `citation: BetaCitationCharLocation | BetaCitationPageLocation | BetaCitationContentBlockLocation | 2 more` - `BetaCitationCharLocation` - `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"` - `"char_location"` - `BetaCitationPageLocation` - `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"` - `"page_location"` - `BetaCitationContentBlockLocation` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `document_index: number` - `document_title: string | null` - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `file_id: string | null` - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. - `type: "content_block_location"` - `"content_block_location"` - `BetaCitationsWebSearchResultLocation` - `cited_text: string` - `encrypted_index: string` - `title: string | null` - `type: "web_search_result_location"` - `"web_search_result_location"` - `url: string` - `BetaCitationSearchResultLocation` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `search_result_index: number` 0-based index of the cited search result among all `search_result` content blocks in the request, in the order they appear across messages and tool results. Counted separately from `document_index`; server-side web search results are not included in this count. - `source: string` - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. - `title: string | null` - `type: "search_result_location"` - `"search_result_location"` - `type: "citations_delta"` - `"citations_delta"` - `BetaThinkingDelta` - `estimated_tokens: number | null` Per-frame increment of a coarse, running estimate of the tokens this thinking block has produced so far. Present whenever the `thinking-token-count-2026-05-13` beta is set; `null` unless `thinking.display` resolves to `"omitted"` and a count is due this frame. Sum the increments across `thinking_delta` frames on this block for a progress indicator. Each increment is a non-negative multiple of a fixed quantum and the cadence is rate-limited, so this is a deliberately lossy display hint, not a billable count; `usage.output_tokens` remains authoritative. - `thinking: string` - `type: "thinking_delta"` - `"thinking_delta"` - `BetaSignatureDelta` - `signature: string` - `type: "signature_delta"` - `"signature_delta"` - `BetaCompactionContentBlockDelta` - `content: string | null` - `encrypted_content: string | null` Opaque metadata from prior compaction, to be round-tripped verbatim - `type: "compaction_delta"` - `"compaction_delta"` - `index: number` - `type: "content_block_delta"` - `"content_block_delta"` ### Beta Raw Content Block Start Event - `BetaRawContentBlockStartEvent` - `content_block: BetaTextBlock | BetaThinkingBlock | BetaRedactedThinkingBlock | 13 more` Response model for a file uploaded to the container. - `BetaTextBlock` - `citations: Array | 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`. - `BetaCitationCharLocation` - `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"` - `"char_location"` - `BetaCitationPageLocation` - `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"` - `"page_location"` - `BetaCitationContentBlockLocation` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `document_index: number` - `document_title: string | null` - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `file_id: string | null` - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. - `type: "content_block_location"` - `"content_block_location"` - `BetaCitationsWebSearchResultLocation` - `cited_text: string` - `encrypted_index: string` - `title: string | null` - `type: "web_search_result_location"` - `"web_search_result_location"` - `url: string` - `BetaCitationSearchResultLocation` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `search_result_index: number` 0-based index of the cited search result among all `search_result` content blocks in the request, in the order they appear across messages and tool results. Counted separately from `document_index`; server-side web search results are not included in this count. - `source: string` - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. - `title: string | null` - `type: "search_result_location"` - `"search_result_location"` - `text: string` - `type: "text"` - `"text"` - `BetaThinkingBlock` - `signature: string` - `thinking: string` - `type: "thinking"` - `"thinking"` - `BetaRedactedThinkingBlock` - `data: string` - `type: "redacted_thinking"` - `"redacted_thinking"` - `BetaToolUseBlock` - `id: string` - `input: Record` - `name: string` - `type: "tool_use"` - `"tool_use"` - `caller?: BetaDirectCaller | BetaServerToolCaller | BetaServerToolCaller20260120` Tool invocation directly from the model. - `BetaDirectCaller` Tool invocation directly from the model. - `type: "direct"` - `"direct"` - `BetaServerToolCaller` Tool invocation generated by a server-side tool. - `tool_id: string` - `type: "code_execution_20250825"` - `"code_execution_20250825"` - `BetaServerToolCaller20260120` - `tool_id: string` - `type: "code_execution_20260120"` - `"code_execution_20260120"` - `BetaServerToolUseBlock` - `id: string` - `input: Record` - `name: "advisor" | "web_search" | "web_fetch" | 5 more` - `"advisor"` - `"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"` - `"server_tool_use"` - `caller?: BetaDirectCaller | BetaServerToolCaller | BetaServerToolCaller20260120` Tool invocation directly from the model. - `BetaDirectCaller` Tool invocation directly from the model. - `BetaServerToolCaller` Tool invocation generated by a server-side tool. - `BetaServerToolCaller20260120` - `BetaWebSearchToolResultBlock` - `content: BetaWebSearchToolResultBlockContent` - `BetaWebSearchToolResultError` - `error_code: BetaWebSearchToolResultErrorCode` - `"invalid_tool_input"` - `"unavailable"` - `"max_uses_exceeded"` - `"too_many_requests"` - `"query_too_long"` - `"request_too_large"` - `type: "web_search_tool_result_error"` - `"web_search_tool_result_error"` - `Array` - `encrypted_content: string` - `page_age: string | null` - `title: string` - `type: "web_search_result"` - `"web_search_result"` - `url: string` - `tool_use_id: string` - `type: "web_search_tool_result"` - `"web_search_tool_result"` - `caller?: BetaDirectCaller | BetaServerToolCaller | BetaServerToolCaller20260120` Tool invocation directly from the model. - `BetaDirectCaller` Tool invocation directly from the model. - `BetaServerToolCaller` Tool invocation generated by a server-side tool. - `BetaServerToolCaller20260120` - `BetaWebFetchToolResultBlock` - `content: BetaWebFetchToolResultErrorBlock | BetaWebFetchBlock` - `BetaWebFetchToolResultErrorBlock` - `error_code: BetaWebFetchToolResultErrorCode` - `"invalid_tool_input"` - `"url_too_long"` - `"url_not_allowed"` - `"url_not_in_prior_context"` - `"url_not_accessible"` - `"unsupported_content_type"` - `"too_many_requests"` - `"max_uses_exceeded"` - `"unavailable"` - `type: "web_fetch_tool_result_error"` - `"web_fetch_tool_result_error"` - `BetaWebFetchBlock` - `content: BetaDocumentBlock` - `citations: BetaCitationConfig | null` Citation configuration for the document - `enabled: boolean` - `source: BetaBase64PDFSource | BetaPlainTextSource` - `BetaBase64PDFSource` - `data: string` - `media_type: "application/pdf"` - `"application/pdf"` - `type: "base64"` - `"base64"` - `BetaPlainTextSource` - `data: string` - `media_type: "text/plain"` - `"text/plain"` - `type: "text"` - `"text"` - `title: string | null` The title of the document - `type: "document"` - `"document"` - `retrieved_at: string | null` ISO 8601 timestamp when the content was retrieved - `type: "web_fetch_result"` - `"web_fetch_result"` - `url: string` Fetched content URL - `tool_use_id: string` - `type: "web_fetch_tool_result"` - `"web_fetch_tool_result"` - `caller?: BetaDirectCaller | BetaServerToolCaller | BetaServerToolCaller20260120` Tool invocation directly from the model. - `BetaDirectCaller` Tool invocation directly from the model. - `BetaServerToolCaller` Tool invocation generated by a server-side tool. - `BetaServerToolCaller20260120` - `BetaAdvisorToolResultBlock` - `content: BetaAdvisorToolResultError | BetaAdvisorResultBlock | BetaAdvisorRedactedResultBlock` - `BetaAdvisorToolResultError` - `error_code: "max_uses_exceeded" | "prompt_too_long" | "too_many_requests" | 3 more` - `"max_uses_exceeded"` - `"prompt_too_long"` - `"too_many_requests"` - `"overloaded"` - `"unavailable"` - `"execution_time_exceeded"` - `type: "advisor_tool_result_error"` - `"advisor_tool_result_error"` - `BetaAdvisorResultBlock` - `stop_reason: string | null` The advisor sub-inference's stop reason (same values as the top-level message `stop_reason`). `max_tokens` indicates the advisor's output was truncated at the tool's `max_tokens` value or the advisor model's policy cap. - `text: string` - `type: "advisor_result"` - `"advisor_result"` - `BetaAdvisorRedactedResultBlock` - `encrypted_content: string` Opaque blob containing the advisor's output. Round-trip verbatim; do not inspect or modify. - `stop_reason: string | null` The advisor sub-inference's stop reason (same values as the top-level message `stop_reason`). - `type: "advisor_redacted_result"` - `"advisor_redacted_result"` - `tool_use_id: string` - `type: "advisor_tool_result"` - `"advisor_tool_result"` - `BetaCodeExecutionToolResultBlock` - `content: BetaCodeExecutionToolResultBlockContent` Code execution result with encrypted stdout for PFC + web_search results. - `BetaCodeExecutionToolResultError` - `error_code: BetaCodeExecutionToolResultErrorCode` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `type: "code_execution_tool_result_error"` - `"code_execution_tool_result_error"` - `BetaCodeExecutionResultBlock` - `content: Array` - `file_id: string` - `type: "code_execution_output"` - `"code_execution_output"` - `return_code: number` - `stderr: string` - `stdout: string` - `type: "code_execution_result"` - `"code_execution_result"` - `BetaEncryptedCodeExecutionResultBlock` Code execution result with encrypted stdout for PFC + web_search results. - `content: Array` - `file_id: string` - `type: "code_execution_output"` - `encrypted_stdout: string` - `return_code: number` - `stderr: string` - `type: "encrypted_code_execution_result"` - `"encrypted_code_execution_result"` - `tool_use_id: string` - `type: "code_execution_tool_result"` - `"code_execution_tool_result"` - `BetaBashCodeExecutionToolResultBlock` - `content: BetaBashCodeExecutionToolResultError | BetaBashCodeExecutionResultBlock` - `BetaBashCodeExecutionToolResultError` - `error_code: "invalid_tool_input" | "unavailable" | "too_many_requests" | 2 more` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `"output_file_too_large"` - `type: "bash_code_execution_tool_result_error"` - `"bash_code_execution_tool_result_error"` - `BetaBashCodeExecutionResultBlock` - `content: Array` - `file_id: string` - `type: "bash_code_execution_output"` - `"bash_code_execution_output"` - `return_code: number` - `stderr: string` - `stdout: string` - `type: "bash_code_execution_result"` - `"bash_code_execution_result"` - `tool_use_id: string` - `type: "bash_code_execution_tool_result"` - `"bash_code_execution_tool_result"` - `BetaTextEditorCodeExecutionToolResultBlock` - `content: BetaTextEditorCodeExecutionToolResultError | BetaTextEditorCodeExecutionViewResultBlock | BetaTextEditorCodeExecutionCreateResultBlock | BetaTextEditorCodeExecutionStrReplaceResultBlock` - `BetaTextEditorCodeExecutionToolResultError` - `error_code: "invalid_tool_input" | "unavailable" | "too_many_requests" | 2 more` - `"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"` - `"text_editor_code_execution_tool_result_error"` - `BetaTextEditorCodeExecutionViewResultBlock` - `content: string` - `file_type: "text" | "image" | "pdf"` - `"text"` - `"image"` - `"pdf"` - `num_lines: number | null` - `start_line: number | null` - `total_lines: number | null` - `type: "text_editor_code_execution_view_result"` - `"text_editor_code_execution_view_result"` - `BetaTextEditorCodeExecutionCreateResultBlock` - `is_file_update: boolean` - `type: "text_editor_code_execution_create_result"` - `"text_editor_code_execution_create_result"` - `BetaTextEditorCodeExecutionStrReplaceResultBlock` - `lines: Array | 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"` - `"text_editor_code_execution_str_replace_result"` - `tool_use_id: string` - `type: "text_editor_code_execution_tool_result"` - `"text_editor_code_execution_tool_result"` - `BetaToolSearchToolResultBlock` - `content: BetaToolSearchToolResultError | BetaToolSearchToolSearchResultBlock` - `BetaToolSearchToolResultError` - `error_code: "invalid_tool_input" | "unavailable" | "too_many_requests" | "execution_time_exceeded"` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `error_message: string | null` - `type: "tool_search_tool_result_error"` - `"tool_search_tool_result_error"` - `BetaToolSearchToolSearchResultBlock` - `tool_references: Array` - `tool_name: string` - `type: "tool_reference"` - `"tool_reference"` - `type: "tool_search_tool_search_result"` - `"tool_search_tool_search_result"` - `tool_use_id: string` - `type: "tool_search_tool_result"` - `"tool_search_tool_result"` - `BetaMCPToolUseBlock` - `id: string` - `input: Record` - `name: string` The name of the MCP tool - `server_name: string` The name of the MCP server - `type: "mcp_tool_use"` - `"mcp_tool_use"` - `BetaMCPToolResultBlock` - `content: string | Array` - `string` - `Array` - `citations: Array | 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`. - `text: string` - `type: "text"` - `is_error: boolean` - `tool_use_id: string` - `type: "mcp_tool_result"` - `"mcp_tool_result"` - `BetaContainerUploadBlock` Response model for a file uploaded to the container. - `file_id: string` - `type: "container_upload"` - `"container_upload"` - `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. - `content: string | null` Summary of compacted content, or null if compaction failed - `encrypted_content: string | null` Opaque metadata from prior compaction, to be round-tripped verbatim - `type: "compaction"` - `"compaction"` - `index: number` - `type: "content_block_start"` - `"content_block_start"` ### Beta Raw Content Block Stop Event - `BetaRawContentBlockStopEvent` - `index: number` - `type: "content_block_stop"` - `"content_block_stop"` ### Beta Raw Message Delta Event - `BetaRawMessageDeltaEvent` - `context_management: BetaContextManagementResponse | null` Information about context management strategies applied during the request - `applied_edits: Array` List of context management edits that were applied. - `BetaClearToolUses20250919EditResponse` - `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. - `"clear_tool_uses_20250919"` - `BetaClearThinking20251015EditResponse` - `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. - `"clear_thinking_20251015"` - `delta: Delta` - `container: BetaContainer | null` 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 | 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) - `"anthropic"` - `"custom"` - `version: string` Skill version or 'latest' for most recent version - `stop_details: BetaRefusalStopDetails | null` Structured information about a refusal. - `category: "cyber" | "bio" | null` The policy category that triggered the refusal. `null` when the refusal doesn't map to a named category. - `"cyber"` - `"bio"` - `explanation: string | null` Human-readable explanation of the refusal. This text is not guaranteed to be stable. `null` when no explanation is available for the category. - `type: "refusal"` - `"refusal"` - `stop_reason: BetaStopReason | null` - `"end_turn"` - `"max_tokens"` - `"stop_sequence"` - `"tool_use"` - `"pause_turn"` - `"compaction"` - `"refusal"` - `"model_context_window_exceeded"` - `stop_sequence: string | null` - `type: "message_delta"` - `"message_delta"` - `usage: BetaMessageDeltaUsage` Billing and rate-limit usage. Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. For example, `output_tokens` will be non-zero, even for an empty string response from Claude. Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. - `cache_creation_input_tokens: number | null` The cumulative number of input tokens used to create the cache entry. - `cache_read_input_tokens: number | null` The cumulative number of input tokens read from the cache. - `input_tokens: number | null` The cumulative number of input tokens which were used. - `iterations: BetaIterationsUsage | null` Per-iteration token usage breakdown. Each entry represents one sampling iteration, with its own input/output token counts and cache statistics. This allows you to: - Determine which iterations exceeded long context thresholds (>=200k tokens) - Calculate the true context window size from the last iteration - Understand token accumulation across server-side tool use loops - `BetaMessageIterationUsage` Token usage for a sampling iteration. - `cache_creation: BetaCacheCreation | null` Breakdown of cached tokens by TTL - `ephemeral_1h_input_tokens: number` The number of input tokens used to create the 1 hour cache entry. - `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: "message"` Usage for a sampling iteration - `"message"` - `BetaCompactionIterationUsage` Token usage for a compaction iteration. - `cache_creation: BetaCacheCreation | null` Breakdown of cached tokens by TTL - `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 - `"compaction"` - `BetaAdvisorMessageIterationUsage` Token usage for an advisor sub-inference iteration. - `cache_creation: BetaCacheCreation | null` Breakdown of cached tokens by TTL - `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. - `model: Model` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-opus-4-8" | "claude-opus-4-7" | "claude-mythos-preview" | 15 more` - `"claude-opus-4-8"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-7"` Frontier intelligence for long-running agents and coding - `"claude-mythos-preview"` New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` Fastest model with near-frontier intelligence - `"claude-haiku-4-5-20251001"` Fastest model with near-frontier intelligence - `"claude-opus-4-5"` Premium model combining maximum intelligence with practical performance - `"claude-opus-4-5-20251101"` Premium model combining maximum intelligence with practical performance - `"claude-sonnet-4-5"` High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` High-performance model for agents and coding - `"claude-opus-4-1"` Exceptional model for specialized complex tasks - `"claude-opus-4-1-20250805"` Exceptional model for specialized complex tasks - `"claude-opus-4-0"` Powerful model for complex tasks - `"claude-opus-4-20250514"` Powerful model for complex tasks - `"claude-sonnet-4-0"` High-performance model with extended thinking - `"claude-sonnet-4-20250514"` High-performance model with extended thinking - `"claude-3-haiku-20240307"` Fast and cost-effective model - `(string & {})` - `output_tokens: number` The number of output tokens which were used. - `type: "advisor_message"` Usage for an advisor sub-inference iteration - `"advisor_message"` - `output_tokens: number` The cumulative number of output tokens which were used. - `output_tokens_details: BetaOutputTokensDetails | null` Breakdown of output tokens by category. `output_tokens` remains the inclusive, authoritative total used for billing. This object provides a read-only decomposition for observability — for example, how many of the billed output tokens were spent on internal reasoning that may have been summarized before being returned to you. - `thinking_tokens: number` Number of output tokens the model generated as internal reasoning, including the thinking-block delimiter tokens. Reflects the raw reasoning the model produced, not the (possibly shorter) summarized thinking text returned in the response body. Computed by re-tokenizing the raw reasoning text, so it may differ from the model's exact generation count by a small number of tokens. Always ≤ `output_tokens`; `output_tokens - thinking_tokens` approximates the non-reasoning output. - `server_tool_use: BetaServerToolUsage | null` The number of server tool requests. - `web_fetch_requests: number` The number of web fetch tool requests. - `web_search_requests: number` The number of web search tool requests. ### Beta Raw Message Start Event - `BetaRawMessageStartEvent` - `message: BetaMessage` - `id: string` Unique object identifier. The format and length of IDs may change over time. - `container: BetaContainer | null` 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 | 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) - `"anthropic"` - `"custom"` - `version: string` Skill version or 'latest' for most recent version - `content: Array` Content generated by the model. This is an array of content blocks, each of which has a `type` that determines its shape. Example: ```json [{"type": "text", "text": "Hi, I'm Claude."}] ``` If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. For example, if the input `messages` were: ```json [ {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, {"role": "assistant", "content": "The best answer is ("} ] ``` Then the response `content` might be: ```json [{"type": "text", "text": "B)"}] ``` - `BetaTextBlock` - `citations: Array | 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`. - `BetaCitationCharLocation` - `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"` - `"char_location"` - `BetaCitationPageLocation` - `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"` - `"page_location"` - `BetaCitationContentBlockLocation` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `document_index: number` - `document_title: string | null` - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `file_id: string | null` - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. - `type: "content_block_location"` - `"content_block_location"` - `BetaCitationsWebSearchResultLocation` - `cited_text: string` - `encrypted_index: string` - `title: string | null` - `type: "web_search_result_location"` - `"web_search_result_location"` - `url: string` - `BetaCitationSearchResultLocation` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `search_result_index: number` 0-based index of the cited search result among all `search_result` content blocks in the request, in the order they appear across messages and tool results. Counted separately from `document_index`; server-side web search results are not included in this count. - `source: string` - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. - `title: string | null` - `type: "search_result_location"` - `"search_result_location"` - `text: string` - `type: "text"` - `"text"` - `BetaThinkingBlock` - `signature: string` - `thinking: string` - `type: "thinking"` - `"thinking"` - `BetaRedactedThinkingBlock` - `data: string` - `type: "redacted_thinking"` - `"redacted_thinking"` - `BetaToolUseBlock` - `id: string` - `input: Record` - `name: string` - `type: "tool_use"` - `"tool_use"` - `caller?: BetaDirectCaller | BetaServerToolCaller | BetaServerToolCaller20260120` Tool invocation directly from the model. - `BetaDirectCaller` Tool invocation directly from the model. - `type: "direct"` - `"direct"` - `BetaServerToolCaller` Tool invocation generated by a server-side tool. - `tool_id: string` - `type: "code_execution_20250825"` - `"code_execution_20250825"` - `BetaServerToolCaller20260120` - `tool_id: string` - `type: "code_execution_20260120"` - `"code_execution_20260120"` - `BetaServerToolUseBlock` - `id: string` - `input: Record` - `name: "advisor" | "web_search" | "web_fetch" | 5 more` - `"advisor"` - `"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"` - `"server_tool_use"` - `caller?: BetaDirectCaller | BetaServerToolCaller | BetaServerToolCaller20260120` Tool invocation directly from the model. - `BetaDirectCaller` Tool invocation directly from the model. - `BetaServerToolCaller` Tool invocation generated by a server-side tool. - `BetaServerToolCaller20260120` - `BetaWebSearchToolResultBlock` - `content: BetaWebSearchToolResultBlockContent` - `BetaWebSearchToolResultError` - `error_code: BetaWebSearchToolResultErrorCode` - `"invalid_tool_input"` - `"unavailable"` - `"max_uses_exceeded"` - `"too_many_requests"` - `"query_too_long"` - `"request_too_large"` - `type: "web_search_tool_result_error"` - `"web_search_tool_result_error"` - `Array` - `encrypted_content: string` - `page_age: string | null` - `title: string` - `type: "web_search_result"` - `"web_search_result"` - `url: string` - `tool_use_id: string` - `type: "web_search_tool_result"` - `"web_search_tool_result"` - `caller?: BetaDirectCaller | BetaServerToolCaller | BetaServerToolCaller20260120` Tool invocation directly from the model. - `BetaDirectCaller` Tool invocation directly from the model. - `BetaServerToolCaller` Tool invocation generated by a server-side tool. - `BetaServerToolCaller20260120` - `BetaWebFetchToolResultBlock` - `content: BetaWebFetchToolResultErrorBlock | BetaWebFetchBlock` - `BetaWebFetchToolResultErrorBlock` - `error_code: BetaWebFetchToolResultErrorCode` - `"invalid_tool_input"` - `"url_too_long"` - `"url_not_allowed"` - `"url_not_in_prior_context"` - `"url_not_accessible"` - `"unsupported_content_type"` - `"too_many_requests"` - `"max_uses_exceeded"` - `"unavailable"` - `type: "web_fetch_tool_result_error"` - `"web_fetch_tool_result_error"` - `BetaWebFetchBlock` - `content: BetaDocumentBlock` - `citations: BetaCitationConfig | null` Citation configuration for the document - `enabled: boolean` - `source: BetaBase64PDFSource | BetaPlainTextSource` - `BetaBase64PDFSource` - `data: string` - `media_type: "application/pdf"` - `"application/pdf"` - `type: "base64"` - `"base64"` - `BetaPlainTextSource` - `data: string` - `media_type: "text/plain"` - `"text/plain"` - `type: "text"` - `"text"` - `title: string | null` The title of the document - `type: "document"` - `"document"` - `retrieved_at: string | null` ISO 8601 timestamp when the content was retrieved - `type: "web_fetch_result"` - `"web_fetch_result"` - `url: string` Fetched content URL - `tool_use_id: string` - `type: "web_fetch_tool_result"` - `"web_fetch_tool_result"` - `caller?: BetaDirectCaller | BetaServerToolCaller | BetaServerToolCaller20260120` Tool invocation directly from the model. - `BetaDirectCaller` Tool invocation directly from the model. - `BetaServerToolCaller` Tool invocation generated by a server-side tool. - `BetaServerToolCaller20260120` - `BetaAdvisorToolResultBlock` - `content: BetaAdvisorToolResultError | BetaAdvisorResultBlock | BetaAdvisorRedactedResultBlock` - `BetaAdvisorToolResultError` - `error_code: "max_uses_exceeded" | "prompt_too_long" | "too_many_requests" | 3 more` - `"max_uses_exceeded"` - `"prompt_too_long"` - `"too_many_requests"` - `"overloaded"` - `"unavailable"` - `"execution_time_exceeded"` - `type: "advisor_tool_result_error"` - `"advisor_tool_result_error"` - `BetaAdvisorResultBlock` - `stop_reason: string | null` The advisor sub-inference's stop reason (same values as the top-level message `stop_reason`). `max_tokens` indicates the advisor's output was truncated at the tool's `max_tokens` value or the advisor model's policy cap. - `text: string` - `type: "advisor_result"` - `"advisor_result"` - `BetaAdvisorRedactedResultBlock` - `encrypted_content: string` Opaque blob containing the advisor's output. Round-trip verbatim; do not inspect or modify. - `stop_reason: string | null` The advisor sub-inference's stop reason (same values as the top-level message `stop_reason`). - `type: "advisor_redacted_result"` - `"advisor_redacted_result"` - `tool_use_id: string` - `type: "advisor_tool_result"` - `"advisor_tool_result"` - `BetaCodeExecutionToolResultBlock` - `content: BetaCodeExecutionToolResultBlockContent` Code execution result with encrypted stdout for PFC + web_search results. - `BetaCodeExecutionToolResultError` - `error_code: BetaCodeExecutionToolResultErrorCode` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `type: "code_execution_tool_result_error"` - `"code_execution_tool_result_error"` - `BetaCodeExecutionResultBlock` - `content: Array` - `file_id: string` - `type: "code_execution_output"` - `"code_execution_output"` - `return_code: number` - `stderr: string` - `stdout: string` - `type: "code_execution_result"` - `"code_execution_result"` - `BetaEncryptedCodeExecutionResultBlock` Code execution result with encrypted stdout for PFC + web_search results. - `content: Array` - `file_id: string` - `type: "code_execution_output"` - `encrypted_stdout: string` - `return_code: number` - `stderr: string` - `type: "encrypted_code_execution_result"` - `"encrypted_code_execution_result"` - `tool_use_id: string` - `type: "code_execution_tool_result"` - `"code_execution_tool_result"` - `BetaBashCodeExecutionToolResultBlock` - `content: BetaBashCodeExecutionToolResultError | BetaBashCodeExecutionResultBlock` - `BetaBashCodeExecutionToolResultError` - `error_code: "invalid_tool_input" | "unavailable" | "too_many_requests" | 2 more` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `"output_file_too_large"` - `type: "bash_code_execution_tool_result_error"` - `"bash_code_execution_tool_result_error"` - `BetaBashCodeExecutionResultBlock` - `content: Array` - `file_id: string` - `type: "bash_code_execution_output"` - `"bash_code_execution_output"` - `return_code: number` - `stderr: string` - `stdout: string` - `type: "bash_code_execution_result"` - `"bash_code_execution_result"` - `tool_use_id: string` - `type: "bash_code_execution_tool_result"` - `"bash_code_execution_tool_result"` - `BetaTextEditorCodeExecutionToolResultBlock` - `content: BetaTextEditorCodeExecutionToolResultError | BetaTextEditorCodeExecutionViewResultBlock | BetaTextEditorCodeExecutionCreateResultBlock | BetaTextEditorCodeExecutionStrReplaceResultBlock` - `BetaTextEditorCodeExecutionToolResultError` - `error_code: "invalid_tool_input" | "unavailable" | "too_many_requests" | 2 more` - `"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"` - `"text_editor_code_execution_tool_result_error"` - `BetaTextEditorCodeExecutionViewResultBlock` - `content: string` - `file_type: "text" | "image" | "pdf"` - `"text"` - `"image"` - `"pdf"` - `num_lines: number | null` - `start_line: number | null` - `total_lines: number | null` - `type: "text_editor_code_execution_view_result"` - `"text_editor_code_execution_view_result"` - `BetaTextEditorCodeExecutionCreateResultBlock` - `is_file_update: boolean` - `type: "text_editor_code_execution_create_result"` - `"text_editor_code_execution_create_result"` - `BetaTextEditorCodeExecutionStrReplaceResultBlock` - `lines: Array | 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"` - `"text_editor_code_execution_str_replace_result"` - `tool_use_id: string` - `type: "text_editor_code_execution_tool_result"` - `"text_editor_code_execution_tool_result"` - `BetaToolSearchToolResultBlock` - `content: BetaToolSearchToolResultError | BetaToolSearchToolSearchResultBlock` - `BetaToolSearchToolResultError` - `error_code: "invalid_tool_input" | "unavailable" | "too_many_requests" | "execution_time_exceeded"` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `error_message: string | null` - `type: "tool_search_tool_result_error"` - `"tool_search_tool_result_error"` - `BetaToolSearchToolSearchResultBlock` - `tool_references: Array` - `tool_name: string` - `type: "tool_reference"` - `"tool_reference"` - `type: "tool_search_tool_search_result"` - `"tool_search_tool_search_result"` - `tool_use_id: string` - `type: "tool_search_tool_result"` - `"tool_search_tool_result"` - `BetaMCPToolUseBlock` - `id: string` - `input: Record` - `name: string` The name of the MCP tool - `server_name: string` The name of the MCP server - `type: "mcp_tool_use"` - `"mcp_tool_use"` - `BetaMCPToolResultBlock` - `content: string | Array` - `string` - `Array` - `citations: Array | 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`. - `text: string` - `type: "text"` - `is_error: boolean` - `tool_use_id: string` - `type: "mcp_tool_result"` - `"mcp_tool_result"` - `BetaContainerUploadBlock` Response model for a file uploaded to the container. - `file_id: string` - `type: "container_upload"` - `"container_upload"` - `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. - `content: string | null` Summary of compacted content, or null if compaction failed - `encrypted_content: string | null` Opaque metadata from prior compaction, to be round-tripped verbatim - `type: "compaction"` - `"compaction"` - `context_management: BetaContextManagementResponse | null` Context management response. Information about context management strategies applied during the request. - `applied_edits: Array` List of context management edits that were applied. - `BetaClearToolUses20250919EditResponse` - `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. - `"clear_tool_uses_20250919"` - `BetaClearThinking20251015EditResponse` - `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. - `"clear_thinking_20251015"` - `diagnostics: BetaDiagnostics | null` Response envelope for request-level diagnostics. Present (possibly null) whenever the caller supplied `diagnostics` on the request. - `cache_miss_reason: BetaCacheMissModelChanged | BetaCacheMissSystemChanged | BetaCacheMissToolsChanged | 3 more | null` Explains why the prompt cache could not fully reuse the prefix from the request identified by `diagnostics.previous_message_id`. `null` means diagnosis is still pending — the response was serialized before the background comparison completed. - `BetaCacheMissModelChanged` - `cache_missed_input_tokens: number` Approximate number of input tokens that would have been read from cache had the prefix matched the previous request. - `type: "model_changed"` - `"model_changed"` - `BetaCacheMissSystemChanged` - `cache_missed_input_tokens: number` Approximate number of input tokens that would have been read from cache had the prefix matched the previous request. - `type: "system_changed"` - `"system_changed"` - `BetaCacheMissToolsChanged` - `cache_missed_input_tokens: number` Approximate number of input tokens that would have been read from cache had the prefix matched the previous request. - `type: "tools_changed"` - `"tools_changed"` - `BetaCacheMissMessagesChanged` - `cache_missed_input_tokens: number` Approximate number of input tokens that would have been read from cache had the prefix matched the previous request. - `type: "messages_changed"` - `"messages_changed"` - `BetaCacheMissPreviousMessageNotFound` - `type: "previous_message_not_found"` - `"previous_message_not_found"` - `BetaCacheMissUnavailable` - `type: "unavailable"` - `"unavailable"` - `model: Model` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-opus-4-8" | "claude-opus-4-7" | "claude-mythos-preview" | 15 more` - `"claude-opus-4-8"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-7"` Frontier intelligence for long-running agents and coding - `"claude-mythos-preview"` New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` Fastest model with near-frontier intelligence - `"claude-haiku-4-5-20251001"` Fastest model with near-frontier intelligence - `"claude-opus-4-5"` Premium model combining maximum intelligence with practical performance - `"claude-opus-4-5-20251101"` Premium model combining maximum intelligence with practical performance - `"claude-sonnet-4-5"` High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` High-performance model for agents and coding - `"claude-opus-4-1"` Exceptional model for specialized complex tasks - `"claude-opus-4-1-20250805"` Exceptional model for specialized complex tasks - `"claude-opus-4-0"` Powerful model for complex tasks - `"claude-opus-4-20250514"` Powerful model for complex tasks - `"claude-sonnet-4-0"` High-performance model with extended thinking - `"claude-sonnet-4-20250514"` High-performance model with extended thinking - `"claude-3-haiku-20240307"` Fast and cost-effective model - `(string & {})` - `role: "assistant"` Conversational role of the generated message. This will always be `"assistant"`. - `"assistant"` - `stop_details: BetaRefusalStopDetails | null` Structured information about a refusal. - `category: "cyber" | "bio" | null` The policy category that triggered the refusal. `null` when the refusal doesn't map to a named category. - `"cyber"` - `"bio"` - `explanation: string | null` Human-readable explanation of the refusal. This text is not guaranteed to be stable. `null` when no explanation is available for the category. - `type: "refusal"` - `"refusal"` - `stop_reason: BetaStopReason | null` The reason that we stopped. This may be one the following values: * `"end_turn"`: the model reached a natural stopping point * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated * `"tool_use"`: the model invoked one or more tools * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. * `"refusal"`: when streaming classifiers intervene to handle potential policy violations In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. - `"end_turn"` - `"max_tokens"` - `"stop_sequence"` - `"tool_use"` - `"pause_turn"` - `"compaction"` - `"refusal"` - `"model_context_window_exceeded"` - `stop_sequence: string | null` Which custom stop sequence was generated, if any. This value will be a non-null string if one of your custom stop sequences was generated. - `type: "message"` Object type. For Messages, this is always `"message"`. - `"message"` - `usage: BetaUsage` Billing and rate-limit usage. Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. For example, `output_tokens` will be non-zero, even for an empty string response from Claude. Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. - `cache_creation: BetaCacheCreation | null` Breakdown of cached tokens by TTL - `ephemeral_1h_input_tokens: number` The number of input tokens used to create the 1 hour cache entry. - `ephemeral_5m_input_tokens: number` The number of input tokens used to create the 5 minute cache entry. - `cache_creation_input_tokens: number | null` The number of input tokens used to create the cache entry. - `cache_read_input_tokens: number | null` The number of input tokens read from the cache. - `inference_geo: string | null` The geographic region where inference was performed for this request. - `input_tokens: number` The number of input tokens which were used. - `iterations: BetaIterationsUsage | null` Per-iteration token usage breakdown. Each entry represents one sampling iteration, with its own input/output token counts and cache statistics. This allows you to: - Determine which iterations exceeded long context thresholds (>=200k tokens) - Calculate the true context window size from the last iteration - Understand token accumulation across server-side tool use loops - `BetaMessageIterationUsage` Token usage for a sampling iteration. - `cache_creation: BetaCacheCreation | null` Breakdown of cached tokens by TTL - `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: "message"` Usage for a sampling iteration - `"message"` - `BetaCompactionIterationUsage` Token usage for a compaction iteration. - `cache_creation: BetaCacheCreation | null` Breakdown of cached tokens by TTL - `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 - `"compaction"` - `BetaAdvisorMessageIterationUsage` Token usage for an advisor sub-inference iteration. - `cache_creation: BetaCacheCreation | null` Breakdown of cached tokens by TTL - `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. - `model: Model` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `output_tokens: number` The number of output tokens which were used. - `type: "advisor_message"` Usage for an advisor sub-inference iteration - `"advisor_message"` - `output_tokens: number` The number of output tokens which were used. - `output_tokens_details: BetaOutputTokensDetails | null` Breakdown of output tokens by category. `output_tokens` remains the inclusive, authoritative total used for billing. This object provides a read-only decomposition for observability — for example, how many of the billed output tokens were spent on internal reasoning that may have been summarized before being returned to you. - `thinking_tokens: number` Number of output tokens the model generated as internal reasoning, including the thinking-block delimiter tokens. Reflects the raw reasoning the model produced, not the (possibly shorter) summarized thinking text returned in the response body. Computed by re-tokenizing the raw reasoning text, so it may differ from the model's exact generation count by a small number of tokens. Always ≤ `output_tokens`; `output_tokens - thinking_tokens` approximates the non-reasoning output. - `server_tool_use: BetaServerToolUsage | null` The number of server tool requests. - `web_fetch_requests: number` The number of web fetch tool requests. - `web_search_requests: number` The number of web search tool requests. - `service_tier: "standard" | "priority" | "batch" | null` If the request used the priority, standard, or batch tier. - `"standard"` - `"priority"` - `"batch"` - `speed: "standard" | "fast" | null` The inference speed mode used for this request. - `"standard"` - `"fast"` - `type: "message_start"` - `"message_start"` ### Beta Raw Message Stop Event - `BetaRawMessageStopEvent` - `type: "message_stop"` - `"message_stop"` ### Beta Raw Message Stream Event - `BetaRawMessageStreamEvent = BetaRawMessageStartEvent | BetaRawMessageDeltaEvent | BetaRawMessageStopEvent | 3 more` - `BetaRawMessageStartEvent` - `message: BetaMessage` - `id: string` Unique object identifier. The format and length of IDs may change over time. - `container: BetaContainer | null` 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 | 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) - `"anthropic"` - `"custom"` - `version: string` Skill version or 'latest' for most recent version - `content: Array` Content generated by the model. This is an array of content blocks, each of which has a `type` that determines its shape. Example: ```json [{"type": "text", "text": "Hi, I'm Claude."}] ``` If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. For example, if the input `messages` were: ```json [ {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, {"role": "assistant", "content": "The best answer is ("} ] ``` Then the response `content` might be: ```json [{"type": "text", "text": "B)"}] ``` - `BetaTextBlock` - `citations: Array | 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`. - `BetaCitationCharLocation` - `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"` - `"char_location"` - `BetaCitationPageLocation` - `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"` - `"page_location"` - `BetaCitationContentBlockLocation` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `document_index: number` - `document_title: string | null` - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `file_id: string | null` - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. - `type: "content_block_location"` - `"content_block_location"` - `BetaCitationsWebSearchResultLocation` - `cited_text: string` - `encrypted_index: string` - `title: string | null` - `type: "web_search_result_location"` - `"web_search_result_location"` - `url: string` - `BetaCitationSearchResultLocation` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `search_result_index: number` 0-based index of the cited search result among all `search_result` content blocks in the request, in the order they appear across messages and tool results. Counted separately from `document_index`; server-side web search results are not included in this count. - `source: string` - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. - `title: string | null` - `type: "search_result_location"` - `"search_result_location"` - `text: string` - `type: "text"` - `"text"` - `BetaThinkingBlock` - `signature: string` - `thinking: string` - `type: "thinking"` - `"thinking"` - `BetaRedactedThinkingBlock` - `data: string` - `type: "redacted_thinking"` - `"redacted_thinking"` - `BetaToolUseBlock` - `id: string` - `input: Record` - `name: string` - `type: "tool_use"` - `"tool_use"` - `caller?: BetaDirectCaller | BetaServerToolCaller | BetaServerToolCaller20260120` Tool invocation directly from the model. - `BetaDirectCaller` Tool invocation directly from the model. - `type: "direct"` - `"direct"` - `BetaServerToolCaller` Tool invocation generated by a server-side tool. - `tool_id: string` - `type: "code_execution_20250825"` - `"code_execution_20250825"` - `BetaServerToolCaller20260120` - `tool_id: string` - `type: "code_execution_20260120"` - `"code_execution_20260120"` - `BetaServerToolUseBlock` - `id: string` - `input: Record` - `name: "advisor" | "web_search" | "web_fetch" | 5 more` - `"advisor"` - `"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"` - `"server_tool_use"` - `caller?: BetaDirectCaller | BetaServerToolCaller | BetaServerToolCaller20260120` Tool invocation directly from the model. - `BetaDirectCaller` Tool invocation directly from the model. - `BetaServerToolCaller` Tool invocation generated by a server-side tool. - `BetaServerToolCaller20260120` - `BetaWebSearchToolResultBlock` - `content: BetaWebSearchToolResultBlockContent` - `BetaWebSearchToolResultError` - `error_code: BetaWebSearchToolResultErrorCode` - `"invalid_tool_input"` - `"unavailable"` - `"max_uses_exceeded"` - `"too_many_requests"` - `"query_too_long"` - `"request_too_large"` - `type: "web_search_tool_result_error"` - `"web_search_tool_result_error"` - `Array` - `encrypted_content: string` - `page_age: string | null` - `title: string` - `type: "web_search_result"` - `"web_search_result"` - `url: string` - `tool_use_id: string` - `type: "web_search_tool_result"` - `"web_search_tool_result"` - `caller?: BetaDirectCaller | BetaServerToolCaller | BetaServerToolCaller20260120` Tool invocation directly from the model. - `BetaDirectCaller` Tool invocation directly from the model. - `BetaServerToolCaller` Tool invocation generated by a server-side tool. - `BetaServerToolCaller20260120` - `BetaWebFetchToolResultBlock` - `content: BetaWebFetchToolResultErrorBlock | BetaWebFetchBlock` - `BetaWebFetchToolResultErrorBlock` - `error_code: BetaWebFetchToolResultErrorCode` - `"invalid_tool_input"` - `"url_too_long"` - `"url_not_allowed"` - `"url_not_in_prior_context"` - `"url_not_accessible"` - `"unsupported_content_type"` - `"too_many_requests"` - `"max_uses_exceeded"` - `"unavailable"` - `type: "web_fetch_tool_result_error"` - `"web_fetch_tool_result_error"` - `BetaWebFetchBlock` - `content: BetaDocumentBlock` - `citations: BetaCitationConfig | null` Citation configuration for the document - `enabled: boolean` - `source: BetaBase64PDFSource | BetaPlainTextSource` - `BetaBase64PDFSource` - `data: string` - `media_type: "application/pdf"` - `"application/pdf"` - `type: "base64"` - `"base64"` - `BetaPlainTextSource` - `data: string` - `media_type: "text/plain"` - `"text/plain"` - `type: "text"` - `"text"` - `title: string | null` The title of the document - `type: "document"` - `"document"` - `retrieved_at: string | null` ISO 8601 timestamp when the content was retrieved - `type: "web_fetch_result"` - `"web_fetch_result"` - `url: string` Fetched content URL - `tool_use_id: string` - `type: "web_fetch_tool_result"` - `"web_fetch_tool_result"` - `caller?: BetaDirectCaller | BetaServerToolCaller | BetaServerToolCaller20260120` Tool invocation directly from the model. - `BetaDirectCaller` Tool invocation directly from the model. - `BetaServerToolCaller` Tool invocation generated by a server-side tool. - `BetaServerToolCaller20260120` - `BetaAdvisorToolResultBlock` - `content: BetaAdvisorToolResultError | BetaAdvisorResultBlock | BetaAdvisorRedactedResultBlock` - `BetaAdvisorToolResultError` - `error_code: "max_uses_exceeded" | "prompt_too_long" | "too_many_requests" | 3 more` - `"max_uses_exceeded"` - `"prompt_too_long"` - `"too_many_requests"` - `"overloaded"` - `"unavailable"` - `"execution_time_exceeded"` - `type: "advisor_tool_result_error"` - `"advisor_tool_result_error"` - `BetaAdvisorResultBlock` - `stop_reason: string | null` The advisor sub-inference's stop reason (same values as the top-level message `stop_reason`). `max_tokens` indicates the advisor's output was truncated at the tool's `max_tokens` value or the advisor model's policy cap. - `text: string` - `type: "advisor_result"` - `"advisor_result"` - `BetaAdvisorRedactedResultBlock` - `encrypted_content: string` Opaque blob containing the advisor's output. Round-trip verbatim; do not inspect or modify. - `stop_reason: string | null` The advisor sub-inference's stop reason (same values as the top-level message `stop_reason`). - `type: "advisor_redacted_result"` - `"advisor_redacted_result"` - `tool_use_id: string` - `type: "advisor_tool_result"` - `"advisor_tool_result"` - `BetaCodeExecutionToolResultBlock` - `content: BetaCodeExecutionToolResultBlockContent` Code execution result with encrypted stdout for PFC + web_search results. - `BetaCodeExecutionToolResultError` - `error_code: BetaCodeExecutionToolResultErrorCode` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `type: "code_execution_tool_result_error"` - `"code_execution_tool_result_error"` - `BetaCodeExecutionResultBlock` - `content: Array` - `file_id: string` - `type: "code_execution_output"` - `"code_execution_output"` - `return_code: number` - `stderr: string` - `stdout: string` - `type: "code_execution_result"` - `"code_execution_result"` - `BetaEncryptedCodeExecutionResultBlock` Code execution result with encrypted stdout for PFC + web_search results. - `content: Array` - `file_id: string` - `type: "code_execution_output"` - `encrypted_stdout: string` - `return_code: number` - `stderr: string` - `type: "encrypted_code_execution_result"` - `"encrypted_code_execution_result"` - `tool_use_id: string` - `type: "code_execution_tool_result"` - `"code_execution_tool_result"` - `BetaBashCodeExecutionToolResultBlock` - `content: BetaBashCodeExecutionToolResultError | BetaBashCodeExecutionResultBlock` - `BetaBashCodeExecutionToolResultError` - `error_code: "invalid_tool_input" | "unavailable" | "too_many_requests" | 2 more` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `"output_file_too_large"` - `type: "bash_code_execution_tool_result_error"` - `"bash_code_execution_tool_result_error"` - `BetaBashCodeExecutionResultBlock` - `content: Array` - `file_id: string` - `type: "bash_code_execution_output"` - `"bash_code_execution_output"` - `return_code: number` - `stderr: string` - `stdout: string` - `type: "bash_code_execution_result"` - `"bash_code_execution_result"` - `tool_use_id: string` - `type: "bash_code_execution_tool_result"` - `"bash_code_execution_tool_result"` - `BetaTextEditorCodeExecutionToolResultBlock` - `content: BetaTextEditorCodeExecutionToolResultError | BetaTextEditorCodeExecutionViewResultBlock | BetaTextEditorCodeExecutionCreateResultBlock | BetaTextEditorCodeExecutionStrReplaceResultBlock` - `BetaTextEditorCodeExecutionToolResultError` - `error_code: "invalid_tool_input" | "unavailable" | "too_many_requests" | 2 more` - `"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"` - `"text_editor_code_execution_tool_result_error"` - `BetaTextEditorCodeExecutionViewResultBlock` - `content: string` - `file_type: "text" | "image" | "pdf"` - `"text"` - `"image"` - `"pdf"` - `num_lines: number | null` - `start_line: number | null` - `total_lines: number | null` - `type: "text_editor_code_execution_view_result"` - `"text_editor_code_execution_view_result"` - `BetaTextEditorCodeExecutionCreateResultBlock` - `is_file_update: boolean` - `type: "text_editor_code_execution_create_result"` - `"text_editor_code_execution_create_result"` - `BetaTextEditorCodeExecutionStrReplaceResultBlock` - `lines: Array | 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"` - `"text_editor_code_execution_str_replace_result"` - `tool_use_id: string` - `type: "text_editor_code_execution_tool_result"` - `"text_editor_code_execution_tool_result"` - `BetaToolSearchToolResultBlock` - `content: BetaToolSearchToolResultError | BetaToolSearchToolSearchResultBlock` - `BetaToolSearchToolResultError` - `error_code: "invalid_tool_input" | "unavailable" | "too_many_requests" | "execution_time_exceeded"` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `error_message: string | null` - `type: "tool_search_tool_result_error"` - `"tool_search_tool_result_error"` - `BetaToolSearchToolSearchResultBlock` - `tool_references: Array` - `tool_name: string` - `type: "tool_reference"` - `"tool_reference"` - `type: "tool_search_tool_search_result"` - `"tool_search_tool_search_result"` - `tool_use_id: string` - `type: "tool_search_tool_result"` - `"tool_search_tool_result"` - `BetaMCPToolUseBlock` - `id: string` - `input: Record` - `name: string` The name of the MCP tool - `server_name: string` The name of the MCP server - `type: "mcp_tool_use"` - `"mcp_tool_use"` - `BetaMCPToolResultBlock` - `content: string | Array` - `string` - `Array` - `citations: Array | 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`. - `text: string` - `type: "text"` - `is_error: boolean` - `tool_use_id: string` - `type: "mcp_tool_result"` - `"mcp_tool_result"` - `BetaContainerUploadBlock` Response model for a file uploaded to the container. - `file_id: string` - `type: "container_upload"` - `"container_upload"` - `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. - `content: string | null` Summary of compacted content, or null if compaction failed - `encrypted_content: string | null` Opaque metadata from prior compaction, to be round-tripped verbatim - `type: "compaction"` - `"compaction"` - `context_management: BetaContextManagementResponse | null` Context management response. Information about context management strategies applied during the request. - `applied_edits: Array` List of context management edits that were applied. - `BetaClearToolUses20250919EditResponse` - `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. - `"clear_tool_uses_20250919"` - `BetaClearThinking20251015EditResponse` - `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. - `"clear_thinking_20251015"` - `diagnostics: BetaDiagnostics | null` Response envelope for request-level diagnostics. Present (possibly null) whenever the caller supplied `diagnostics` on the request. - `cache_miss_reason: BetaCacheMissModelChanged | BetaCacheMissSystemChanged | BetaCacheMissToolsChanged | 3 more | null` Explains why the prompt cache could not fully reuse the prefix from the request identified by `diagnostics.previous_message_id`. `null` means diagnosis is still pending — the response was serialized before the background comparison completed. - `BetaCacheMissModelChanged` - `cache_missed_input_tokens: number` Approximate number of input tokens that would have been read from cache had the prefix matched the previous request. - `type: "model_changed"` - `"model_changed"` - `BetaCacheMissSystemChanged` - `cache_missed_input_tokens: number` Approximate number of input tokens that would have been read from cache had the prefix matched the previous request. - `type: "system_changed"` - `"system_changed"` - `BetaCacheMissToolsChanged` - `cache_missed_input_tokens: number` Approximate number of input tokens that would have been read from cache had the prefix matched the previous request. - `type: "tools_changed"` - `"tools_changed"` - `BetaCacheMissMessagesChanged` - `cache_missed_input_tokens: number` Approximate number of input tokens that would have been read from cache had the prefix matched the previous request. - `type: "messages_changed"` - `"messages_changed"` - `BetaCacheMissPreviousMessageNotFound` - `type: "previous_message_not_found"` - `"previous_message_not_found"` - `BetaCacheMissUnavailable` - `type: "unavailable"` - `"unavailable"` - `model: Model` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-opus-4-8" | "claude-opus-4-7" | "claude-mythos-preview" | 15 more` - `"claude-opus-4-8"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-7"` Frontier intelligence for long-running agents and coding - `"claude-mythos-preview"` New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` Fastest model with near-frontier intelligence - `"claude-haiku-4-5-20251001"` Fastest model with near-frontier intelligence - `"claude-opus-4-5"` Premium model combining maximum intelligence with practical performance - `"claude-opus-4-5-20251101"` Premium model combining maximum intelligence with practical performance - `"claude-sonnet-4-5"` High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` High-performance model for agents and coding - `"claude-opus-4-1"` Exceptional model for specialized complex tasks - `"claude-opus-4-1-20250805"` Exceptional model for specialized complex tasks - `"claude-opus-4-0"` Powerful model for complex tasks - `"claude-opus-4-20250514"` Powerful model for complex tasks - `"claude-sonnet-4-0"` High-performance model with extended thinking - `"claude-sonnet-4-20250514"` High-performance model with extended thinking - `"claude-3-haiku-20240307"` Fast and cost-effective model - `(string & {})` - `role: "assistant"` Conversational role of the generated message. This will always be `"assistant"`. - `"assistant"` - `stop_details: BetaRefusalStopDetails | null` Structured information about a refusal. - `category: "cyber" | "bio" | null` The policy category that triggered the refusal. `null` when the refusal doesn't map to a named category. - `"cyber"` - `"bio"` - `explanation: string | null` Human-readable explanation of the refusal. This text is not guaranteed to be stable. `null` when no explanation is available for the category. - `type: "refusal"` - `"refusal"` - `stop_reason: BetaStopReason | null` The reason that we stopped. This may be one the following values: * `"end_turn"`: the model reached a natural stopping point * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated * `"tool_use"`: the model invoked one or more tools * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. * `"refusal"`: when streaming classifiers intervene to handle potential policy violations In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. - `"end_turn"` - `"max_tokens"` - `"stop_sequence"` - `"tool_use"` - `"pause_turn"` - `"compaction"` - `"refusal"` - `"model_context_window_exceeded"` - `stop_sequence: string | null` Which custom stop sequence was generated, if any. This value will be a non-null string if one of your custom stop sequences was generated. - `type: "message"` Object type. For Messages, this is always `"message"`. - `"message"` - `usage: BetaUsage` Billing and rate-limit usage. Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. For example, `output_tokens` will be non-zero, even for an empty string response from Claude. Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. - `cache_creation: BetaCacheCreation | null` Breakdown of cached tokens by TTL - `ephemeral_1h_input_tokens: number` The number of input tokens used to create the 1 hour cache entry. - `ephemeral_5m_input_tokens: number` The number of input tokens used to create the 5 minute cache entry. - `cache_creation_input_tokens: number | null` The number of input tokens used to create the cache entry. - `cache_read_input_tokens: number | null` The number of input tokens read from the cache. - `inference_geo: string | null` The geographic region where inference was performed for this request. - `input_tokens: number` The number of input tokens which were used. - `iterations: BetaIterationsUsage | null` Per-iteration token usage breakdown. Each entry represents one sampling iteration, with its own input/output token counts and cache statistics. This allows you to: - Determine which iterations exceeded long context thresholds (>=200k tokens) - Calculate the true context window size from the last iteration - Understand token accumulation across server-side tool use loops - `BetaMessageIterationUsage` Token usage for a sampling iteration. - `cache_creation: BetaCacheCreation | null` Breakdown of cached tokens by TTL - `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: "message"` Usage for a sampling iteration - `"message"` - `BetaCompactionIterationUsage` Token usage for a compaction iteration. - `cache_creation: BetaCacheCreation | null` Breakdown of cached tokens by TTL - `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 - `"compaction"` - `BetaAdvisorMessageIterationUsage` Token usage for an advisor sub-inference iteration. - `cache_creation: BetaCacheCreation | null` Breakdown of cached tokens by TTL - `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. - `model: Model` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `output_tokens: number` The number of output tokens which were used. - `type: "advisor_message"` Usage for an advisor sub-inference iteration - `"advisor_message"` - `output_tokens: number` The number of output tokens which were used. - `output_tokens_details: BetaOutputTokensDetails | null` Breakdown of output tokens by category. `output_tokens` remains the inclusive, authoritative total used for billing. This object provides a read-only decomposition for observability — for example, how many of the billed output tokens were spent on internal reasoning that may have been summarized before being returned to you. - `thinking_tokens: number` Number of output tokens the model generated as internal reasoning, including the thinking-block delimiter tokens. Reflects the raw reasoning the model produced, not the (possibly shorter) summarized thinking text returned in the response body. Computed by re-tokenizing the raw reasoning text, so it may differ from the model's exact generation count by a small number of tokens. Always ≤ `output_tokens`; `output_tokens - thinking_tokens` approximates the non-reasoning output. - `server_tool_use: BetaServerToolUsage | null` The number of server tool requests. - `web_fetch_requests: number` The number of web fetch tool requests. - `web_search_requests: number` The number of web search tool requests. - `service_tier: "standard" | "priority" | "batch" | null` If the request used the priority, standard, or batch tier. - `"standard"` - `"priority"` - `"batch"` - `speed: "standard" | "fast" | null` The inference speed mode used for this request. - `"standard"` - `"fast"` - `type: "message_start"` - `"message_start"` - `BetaRawMessageDeltaEvent` - `context_management: BetaContextManagementResponse | null` Information about context management strategies applied during the request - `delta: Delta` - `container: BetaContainer | null` Information about the container used in the request (for the code execution tool) - `stop_details: BetaRefusalStopDetails | null` Structured information about a refusal. - `stop_reason: BetaStopReason | null` - `stop_sequence: string | null` - `type: "message_delta"` - `"message_delta"` - `usage: BetaMessageDeltaUsage` Billing and rate-limit usage. Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. For example, `output_tokens` will be non-zero, even for an empty string response from Claude. Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. - `cache_creation_input_tokens: number | null` The cumulative number of input tokens used to create the cache entry. - `cache_read_input_tokens: number | null` The cumulative number of input tokens read from the cache. - `input_tokens: number | null` The cumulative number of input tokens which were used. - `iterations: BetaIterationsUsage | null` Per-iteration token usage breakdown. Each entry represents one sampling iteration, with its own input/output token counts and cache statistics. This allows you to: - Determine which iterations exceeded long context thresholds (>=200k tokens) - Calculate the true context window size from the last iteration - Understand token accumulation across server-side tool use loops - `output_tokens: number` The cumulative number of output tokens which were used. - `output_tokens_details: BetaOutputTokensDetails | null` Breakdown of output tokens by category. `output_tokens` remains the inclusive, authoritative total used for billing. This object provides a read-only decomposition for observability — for example, how many of the billed output tokens were spent on internal reasoning that may have been summarized before being returned to you. - `server_tool_use: BetaServerToolUsage | null` The number of server tool requests. - `BetaRawMessageStopEvent` - `type: "message_stop"` - `"message_stop"` - `BetaRawContentBlockStartEvent` - `content_block: BetaTextBlock | BetaThinkingBlock | BetaRedactedThinkingBlock | 13 more` Response model for a file uploaded to the container. - `BetaTextBlock` - `BetaThinkingBlock` - `BetaRedactedThinkingBlock` - `BetaToolUseBlock` - `BetaServerToolUseBlock` - `BetaWebSearchToolResultBlock` - `BetaWebFetchToolResultBlock` - `BetaAdvisorToolResultBlock` - `BetaCodeExecutionToolResultBlock` - `BetaBashCodeExecutionToolResultBlock` - `BetaTextEditorCodeExecutionToolResultBlock` - `BetaToolSearchToolResultBlock` - `BetaMCPToolUseBlock` - `BetaMCPToolResultBlock` - `BetaContainerUploadBlock` Response model for a file uploaded to the container. - `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. - `index: number` - `type: "content_block_start"` - `"content_block_start"` - `BetaRawContentBlockDeltaEvent` - `delta: BetaRawContentBlockDelta` - `BetaTextDelta` - `text: string` - `type: "text_delta"` - `"text_delta"` - `BetaInputJSONDelta` - `partial_json: string` - `type: "input_json_delta"` - `"input_json_delta"` - `BetaCitationsDelta` - `citation: BetaCitationCharLocation | BetaCitationPageLocation | BetaCitationContentBlockLocation | 2 more` - `BetaCitationCharLocation` - `BetaCitationPageLocation` - `BetaCitationContentBlockLocation` - `BetaCitationsWebSearchResultLocation` - `BetaCitationSearchResultLocation` - `type: "citations_delta"` - `"citations_delta"` - `BetaThinkingDelta` - `estimated_tokens: number | null` Per-frame increment of a coarse, running estimate of the tokens this thinking block has produced so far. Present whenever the `thinking-token-count-2026-05-13` beta is set; `null` unless `thinking.display` resolves to `"omitted"` and a count is due this frame. Sum the increments across `thinking_delta` frames on this block for a progress indicator. Each increment is a non-negative multiple of a fixed quantum and the cadence is rate-limited, so this is a deliberately lossy display hint, not a billable count; `usage.output_tokens` remains authoritative. - `thinking: string` - `type: "thinking_delta"` - `"thinking_delta"` - `BetaSignatureDelta` - `signature: string` - `type: "signature_delta"` - `"signature_delta"` - `BetaCompactionContentBlockDelta` - `content: string | null` - `encrypted_content: string | null` Opaque metadata from prior compaction, to be round-tripped verbatim - `type: "compaction_delta"` - `"compaction_delta"` - `index: number` - `type: "content_block_delta"` - `"content_block_delta"` - `BetaRawContentBlockStopEvent` - `index: number` - `type: "content_block_stop"` - `"content_block_stop"` ### Beta Redacted Thinking Block - `BetaRedactedThinkingBlock` - `data: string` - `type: "redacted_thinking"` - `"redacted_thinking"` ### Beta Redacted Thinking Block Param - `BetaRedactedThinkingBlockParam` - `data: string` - `type: "redacted_thinking"` - `"redacted_thinking"` ### Beta Refusal Stop Details - `BetaRefusalStopDetails` Structured information about a refusal. - `category: "cyber" | "bio" | null` The policy category that triggered the refusal. `null` when the refusal doesn't map to a named category. - `"cyber"` - `"bio"` - `explanation: string | null` Human-readable explanation of the refusal. This text is not guaranteed to be stable. `null` when no explanation is available for the category. - `type: "refusal"` - `"refusal"` ### Beta Request Document Block - `BetaRequestDocumentBlock` - `source: BetaBase64PDFSource | BetaPlainTextSource | BetaContentBlockSource | 2 more` - `BetaBase64PDFSource` - `data: string` - `media_type: "application/pdf"` - `"application/pdf"` - `type: "base64"` - `"base64"` - `BetaPlainTextSource` - `data: string` - `media_type: "text/plain"` - `"text/plain"` - `type: "text"` - `"text"` - `BetaContentBlockSource` - `content: string | Array` - `string` - `Array` - `BetaTextBlockParam` - `text: string` - `type: "text"` - `"text"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `"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`. - `"5m"` - `"1h"` - `citations?: Array | null` - `BetaCitationCharLocationParam` - `cited_text: string` - `document_index: number` - `document_title: string | null` - `end_char_index: number` - `start_char_index: number` - `type: "char_location"` - `"char_location"` - `BetaCitationPageLocationParam` - `cited_text: string` - `document_index: number` - `document_title: string | null` - `end_page_number: number` - `start_page_number: number` - `type: "page_location"` - `"page_location"` - `BetaCitationContentBlockLocationParam` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `document_index: number` - `document_title: string | null` - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. - `type: "content_block_location"` - `"content_block_location"` - `BetaCitationWebSearchResultLocationParam` - `cited_text: string` - `encrypted_index: string` - `title: string | null` - `type: "web_search_result_location"` - `"web_search_result_location"` - `url: string` - `BetaCitationSearchResultLocationParam` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `search_result_index: number` 0-based index of the cited search result among all `search_result` content blocks in the request, in the order they appear across messages and tool results. Counted separately from `document_index`; server-side web search results are not included in this count. - `source: string` - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. - `title: string | null` - `type: "search_result_location"` - `"search_result_location"` - `BetaImageBlockParam` - `source: BetaBase64ImageSource | BetaURLImageSource | BetaFileImageSource` - `BetaBase64ImageSource` - `data: string` - `media_type: "image/jpeg" | "image/png" | "image/gif" | "image/webp"` - `"image/jpeg"` - `"image/png"` - `"image/gif"` - `"image/webp"` - `type: "base64"` - `"base64"` - `BetaURLImageSource` - `type: "url"` - `"url"` - `url: string` - `BetaFileImageSource` - `file_id: string` - `type: "file"` - `"file"` - `type: "image"` - `"image"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `type: "content"` - `"content"` - `BetaURLPDFSource` - `type: "url"` - `"url"` - `url: string` - `BetaFileDocumentSource` - `file_id: string` - `type: "file"` - `"file"` - `type: "document"` - `"document"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `citations?: BetaCitationsConfigParam | null` - `enabled?: boolean` - `context?: string | null` - `title?: string | null` ### Beta Request MCP Server Tool Configuration - `BetaRequestMCPServerToolConfiguration` - `allowed_tools?: Array | null` - `enabled?: boolean | null` ### Beta Request MCP Server URL Definition - `BetaRequestMCPServerURLDefinition` - `name: string` - `type: "url"` - `"url"` - `url: string` - `authorization_token?: string | null` - `tool_configuration?: BetaRequestMCPServerToolConfiguration | null` - `allowed_tools?: Array | null` - `enabled?: boolean | null` ### Beta Request MCP Tool Result Block Param - `BetaRequestMCPToolResultBlockParam` - `tool_use_id: string` - `type: "mcp_tool_result"` - `"mcp_tool_result"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `"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`. - `"5m"` - `"1h"` - `content?: string | Array` - `string` - `Array` - `text: string` - `type: "text"` - `"text"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `citations?: Array | null` - `BetaCitationCharLocationParam` - `cited_text: string` - `document_index: number` - `document_title: string | null` - `end_char_index: number` - `start_char_index: number` - `type: "char_location"` - `"char_location"` - `BetaCitationPageLocationParam` - `cited_text: string` - `document_index: number` - `document_title: string | null` - `end_page_number: number` - `start_page_number: number` - `type: "page_location"` - `"page_location"` - `BetaCitationContentBlockLocationParam` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `document_index: number` - `document_title: string | null` - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. - `type: "content_block_location"` - `"content_block_location"` - `BetaCitationWebSearchResultLocationParam` - `cited_text: string` - `encrypted_index: string` - `title: string | null` - `type: "web_search_result_location"` - `"web_search_result_location"` - `url: string` - `BetaCitationSearchResultLocationParam` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `search_result_index: number` 0-based index of the cited search result among all `search_result` content blocks in the request, in the order they appear across messages and tool results. Counted separately from `document_index`; server-side web search results are not included in this count. - `source: string` - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. - `title: string | null` - `type: "search_result_location"` - `"search_result_location"` - `is_error?: boolean` ### Beta Search Result Block Param - `BetaSearchResultBlockParam` - `content: Array` - `text: string` - `type: "text"` - `"text"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `"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`. - `"5m"` - `"1h"` - `citations?: Array | null` - `BetaCitationCharLocationParam` - `cited_text: string` - `document_index: number` - `document_title: string | null` - `end_char_index: number` - `start_char_index: number` - `type: "char_location"` - `"char_location"` - `BetaCitationPageLocationParam` - `cited_text: string` - `document_index: number` - `document_title: string | null` - `end_page_number: number` - `start_page_number: number` - `type: "page_location"` - `"page_location"` - `BetaCitationContentBlockLocationParam` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `document_index: number` - `document_title: string | null` - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. - `type: "content_block_location"` - `"content_block_location"` - `BetaCitationWebSearchResultLocationParam` - `cited_text: string` - `encrypted_index: string` - `title: string | null` - `type: "web_search_result_location"` - `"web_search_result_location"` - `url: string` - `BetaCitationSearchResultLocationParam` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `search_result_index: number` 0-based index of the cited search result among all `search_result` content blocks in the request, in the order they appear across messages and tool results. Counted separately from `document_index`; server-side web search results are not included in this count. - `source: string` - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. - `title: string | null` - `type: "search_result_location"` - `"search_result_location"` - `source: string` - `title: string` - `type: "search_result"` - `"search_result"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `citations?: BetaCitationsConfigParam` - `enabled?: boolean` ### Beta Server Tool Caller - `BetaServerToolCaller` Tool invocation generated by a server-side tool. - `tool_id: string` - `type: "code_execution_20250825"` - `"code_execution_20250825"` ### Beta Server Tool Caller 20260120 - `BetaServerToolCaller20260120` - `tool_id: string` - `type: "code_execution_20260120"` - `"code_execution_20260120"` ### Beta Server Tool Usage - `BetaServerToolUsage` - `web_fetch_requests: number` The number of web fetch tool requests. - `web_search_requests: number` The number of web search tool requests. ### Beta Server Tool Use Block - `BetaServerToolUseBlock` - `id: string` - `input: Record` - `name: "advisor" | "web_search" | "web_fetch" | 5 more` - `"advisor"` - `"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"` - `"server_tool_use"` - `caller?: BetaDirectCaller | BetaServerToolCaller | BetaServerToolCaller20260120` Tool invocation directly from the model. - `BetaDirectCaller` Tool invocation directly from the model. - `type: "direct"` - `"direct"` - `BetaServerToolCaller` Tool invocation generated by a server-side tool. - `tool_id: string` - `type: "code_execution_20250825"` - `"code_execution_20250825"` - `BetaServerToolCaller20260120` - `tool_id: string` - `type: "code_execution_20260120"` - `"code_execution_20260120"` ### Beta Server Tool Use Block Param - `BetaServerToolUseBlockParam` - `id: string` - `input: Record` - `name: "advisor" | "web_search" | "web_fetch" | 5 more` - `"advisor"` - `"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"` - `"server_tool_use"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `"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`. - `"5m"` - `"1h"` - `caller?: BetaDirectCaller | BetaServerToolCaller | BetaServerToolCaller20260120` Tool invocation directly from the model. - `BetaDirectCaller` Tool invocation directly from the model. - `type: "direct"` - `"direct"` - `BetaServerToolCaller` Tool invocation generated by a server-side tool. - `tool_id: string` - `type: "code_execution_20250825"` - `"code_execution_20250825"` - `BetaServerToolCaller20260120` - `tool_id: string` - `type: "code_execution_20260120"` - `"code_execution_20260120"` ### Beta Signature Delta - `BetaSignatureDelta` - `signature: string` - `type: "signature_delta"` - `"signature_delta"` ### Beta Skill - `BetaSkill` A skill that was loaded in a container (response model). - `skill_id: string` Skill ID - `type: "anthropic" | "custom"` Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined) - `"anthropic"` - `"custom"` - `version: string` Skill version or 'latest' for most recent version ### Beta Skill Params - `BetaSkillParams` Specification for a skill to be loaded in a container (request model). - `skill_id: string` Skill ID - `type: "anthropic" | "custom"` Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined) - `"anthropic"` - `"custom"` - `version?: string` Skill version or 'latest' for most recent version ### Beta Stop Reason - `BetaStopReason = "end_turn" | "max_tokens" | "stop_sequence" | 5 more` - `"end_turn"` - `"max_tokens"` - `"stop_sequence"` - `"tool_use"` - `"pause_turn"` - `"compaction"` - `"refusal"` - `"model_context_window_exceeded"` ### Beta Text Block - `BetaTextBlock` - `citations: Array | 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`. - `BetaCitationCharLocation` - `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"` - `"char_location"` - `BetaCitationPageLocation` - `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"` - `"page_location"` - `BetaCitationContentBlockLocation` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `document_index: number` - `document_title: string | null` - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `file_id: string | null` - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. - `type: "content_block_location"` - `"content_block_location"` - `BetaCitationsWebSearchResultLocation` - `cited_text: string` - `encrypted_index: string` - `title: string | null` - `type: "web_search_result_location"` - `"web_search_result_location"` - `url: string` - `BetaCitationSearchResultLocation` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `search_result_index: number` 0-based index of the cited search result among all `search_result` content blocks in the request, in the order they appear across messages and tool results. Counted separately from `document_index`; server-side web search results are not included in this count. - `source: string` - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. - `title: string | null` - `type: "search_result_location"` - `"search_result_location"` - `text: string` - `type: "text"` - `"text"` ### Beta Text Block Param - `BetaTextBlockParam` - `text: string` - `type: "text"` - `"text"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `"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`. - `"5m"` - `"1h"` - `citations?: Array | null` - `BetaCitationCharLocationParam` - `cited_text: string` - `document_index: number` - `document_title: string | null` - `end_char_index: number` - `start_char_index: number` - `type: "char_location"` - `"char_location"` - `BetaCitationPageLocationParam` - `cited_text: string` - `document_index: number` - `document_title: string | null` - `end_page_number: number` - `start_page_number: number` - `type: "page_location"` - `"page_location"` - `BetaCitationContentBlockLocationParam` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `document_index: number` - `document_title: string | null` - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. - `type: "content_block_location"` - `"content_block_location"` - `BetaCitationWebSearchResultLocationParam` - `cited_text: string` - `encrypted_index: string` - `title: string | null` - `type: "web_search_result_location"` - `"web_search_result_location"` - `url: string` - `BetaCitationSearchResultLocationParam` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `search_result_index: number` 0-based index of the cited search result among all `search_result` content blocks in the request, in the order they appear across messages and tool results. Counted separately from `document_index`; server-side web search results are not included in this count. - `source: string` - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. - `title: string | null` - `type: "search_result_location"` - `"search_result_location"` ### Beta Text Citation - `BetaTextCitation = BetaCitationCharLocation | BetaCitationPageLocation | BetaCitationContentBlockLocation | 2 more` - `BetaCitationCharLocation` - `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"` - `"char_location"` - `BetaCitationPageLocation` - `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"` - `"page_location"` - `BetaCitationContentBlockLocation` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `document_index: number` - `document_title: string | null` - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `file_id: string | null` - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. - `type: "content_block_location"` - `"content_block_location"` - `BetaCitationsWebSearchResultLocation` - `cited_text: string` - `encrypted_index: string` - `title: string | null` - `type: "web_search_result_location"` - `"web_search_result_location"` - `url: string` - `BetaCitationSearchResultLocation` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `search_result_index: number` 0-based index of the cited search result among all `search_result` content blocks in the request, in the order they appear across messages and tool results. Counted separately from `document_index`; server-side web search results are not included in this count. - `source: string` - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. - `title: string | null` - `type: "search_result_location"` - `"search_result_location"` ### Beta Text Citation Param - `BetaTextCitationParam = BetaCitationCharLocationParam | BetaCitationPageLocationParam | BetaCitationContentBlockLocationParam | 2 more` - `BetaCitationCharLocationParam` - `cited_text: string` - `document_index: number` - `document_title: string | null` - `end_char_index: number` - `start_char_index: number` - `type: "char_location"` - `"char_location"` - `BetaCitationPageLocationParam` - `cited_text: string` - `document_index: number` - `document_title: string | null` - `end_page_number: number` - `start_page_number: number` - `type: "page_location"` - `"page_location"` - `BetaCitationContentBlockLocationParam` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `document_index: number` - `document_title: string | null` - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. - `type: "content_block_location"` - `"content_block_location"` - `BetaCitationWebSearchResultLocationParam` - `cited_text: string` - `encrypted_index: string` - `title: string | null` - `type: "web_search_result_location"` - `"web_search_result_location"` - `url: string` - `BetaCitationSearchResultLocationParam` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `search_result_index: number` 0-based index of the cited search result among all `search_result` content blocks in the request, in the order they appear across messages and tool results. Counted separately from `document_index`; server-side web search results are not included in this count. - `source: string` - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. - `title: string | null` - `type: "search_result_location"` - `"search_result_location"` ### Beta Text Delta - `BetaTextDelta` - `text: string` - `type: "text_delta"` - `"text_delta"` ### Beta Text Editor Code Execution Create Result Block - `BetaTextEditorCodeExecutionCreateResultBlock` - `is_file_update: boolean` - `type: "text_editor_code_execution_create_result"` - `"text_editor_code_execution_create_result"` ### Beta Text Editor Code Execution Create Result Block Param - `BetaTextEditorCodeExecutionCreateResultBlockParam` - `is_file_update: boolean` - `type: "text_editor_code_execution_create_result"` - `"text_editor_code_execution_create_result"` ### Beta Text Editor Code Execution Str Replace Result Block - `BetaTextEditorCodeExecutionStrReplaceResultBlock` - `lines: Array | 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"` - `"text_editor_code_execution_str_replace_result"` ### Beta Text Editor Code Execution Str Replace Result Block Param - `BetaTextEditorCodeExecutionStrReplaceResultBlockParam` - `type: "text_editor_code_execution_str_replace_result"` - `"text_editor_code_execution_str_replace_result"` - `lines?: Array | null` - `new_lines?: number | null` - `new_start?: number | null` - `old_lines?: number | null` - `old_start?: number | null` ### Beta Text Editor Code Execution Tool Result Block - `BetaTextEditorCodeExecutionToolResultBlock` - `content: BetaTextEditorCodeExecutionToolResultError | BetaTextEditorCodeExecutionViewResultBlock | BetaTextEditorCodeExecutionCreateResultBlock | BetaTextEditorCodeExecutionStrReplaceResultBlock` - `BetaTextEditorCodeExecutionToolResultError` - `error_code: "invalid_tool_input" | "unavailable" | "too_many_requests" | 2 more` - `"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"` - `"text_editor_code_execution_tool_result_error"` - `BetaTextEditorCodeExecutionViewResultBlock` - `content: string` - `file_type: "text" | "image" | "pdf"` - `"text"` - `"image"` - `"pdf"` - `num_lines: number | null` - `start_line: number | null` - `total_lines: number | null` - `type: "text_editor_code_execution_view_result"` - `"text_editor_code_execution_view_result"` - `BetaTextEditorCodeExecutionCreateResultBlock` - `is_file_update: boolean` - `type: "text_editor_code_execution_create_result"` - `"text_editor_code_execution_create_result"` - `BetaTextEditorCodeExecutionStrReplaceResultBlock` - `lines: Array | 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"` - `"text_editor_code_execution_str_replace_result"` - `tool_use_id: string` - `type: "text_editor_code_execution_tool_result"` - `"text_editor_code_execution_tool_result"` ### Beta Text Editor Code Execution Tool Result Block Param - `BetaTextEditorCodeExecutionToolResultBlockParam` - `content: BetaTextEditorCodeExecutionToolResultErrorParam | BetaTextEditorCodeExecutionViewResultBlockParam | BetaTextEditorCodeExecutionCreateResultBlockParam | BetaTextEditorCodeExecutionStrReplaceResultBlockParam` - `BetaTextEditorCodeExecutionToolResultErrorParam` - `error_code: "invalid_tool_input" | "unavailable" | "too_many_requests" | 2 more` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `"file_not_found"` - `type: "text_editor_code_execution_tool_result_error"` - `"text_editor_code_execution_tool_result_error"` - `error_message?: string | null` - `BetaTextEditorCodeExecutionViewResultBlockParam` - `content: string` - `file_type: "text" | "image" | "pdf"` - `"text"` - `"image"` - `"pdf"` - `type: "text_editor_code_execution_view_result"` - `"text_editor_code_execution_view_result"` - `num_lines?: number | null` - `start_line?: number | null` - `total_lines?: number | null` - `BetaTextEditorCodeExecutionCreateResultBlockParam` - `is_file_update: boolean` - `type: "text_editor_code_execution_create_result"` - `"text_editor_code_execution_create_result"` - `BetaTextEditorCodeExecutionStrReplaceResultBlockParam` - `type: "text_editor_code_execution_str_replace_result"` - `"text_editor_code_execution_str_replace_result"` - `lines?: Array | 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"` - `"text_editor_code_execution_tool_result"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `"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`. - `"5m"` - `"1h"` ### Beta Text Editor Code Execution Tool Result Error - `BetaTextEditorCodeExecutionToolResultError` - `error_code: "invalid_tool_input" | "unavailable" | "too_many_requests" | 2 more` - `"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"` - `"text_editor_code_execution_tool_result_error"` ### Beta Text Editor Code Execution Tool Result Error Param - `BetaTextEditorCodeExecutionToolResultErrorParam` - `error_code: "invalid_tool_input" | "unavailable" | "too_many_requests" | 2 more` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `"file_not_found"` - `type: "text_editor_code_execution_tool_result_error"` - `"text_editor_code_execution_tool_result_error"` - `error_message?: string | null` ### Beta Text Editor Code Execution View Result Block - `BetaTextEditorCodeExecutionViewResultBlock` - `content: string` - `file_type: "text" | "image" | "pdf"` - `"text"` - `"image"` - `"pdf"` - `num_lines: number | null` - `start_line: number | null` - `total_lines: number | null` - `type: "text_editor_code_execution_view_result"` - `"text_editor_code_execution_view_result"` ### Beta Text Editor Code Execution View Result Block Param - `BetaTextEditorCodeExecutionViewResultBlockParam` - `content: string` - `file_type: "text" | "image" | "pdf"` - `"text"` - `"image"` - `"pdf"` - `type: "text_editor_code_execution_view_result"` - `"text_editor_code_execution_view_result"` - `num_lines?: number | null` - `start_line?: number | null` - `total_lines?: number | null` ### Beta Thinking Block - `BetaThinkingBlock` - `signature: string` - `thinking: string` - `type: "thinking"` - `"thinking"` ### Beta Thinking Block Param - `BetaThinkingBlockParam` - `signature: string` - `thinking: string` - `type: "thinking"` - `"thinking"` ### Beta Thinking Config Adaptive - `BetaThinkingConfigAdaptive` - `type: "adaptive"` - `"adaptive"` - `display?: "summarized" | "omitted" | null` Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. Defaults to `summarized`. - `"summarized"` - `"omitted"` ### Beta Thinking Config Disabled - `BetaThinkingConfigDisabled` - `type: "disabled"` - `"disabled"` ### Beta Thinking Config Enabled - `BetaThinkingConfigEnabled` - `budget_tokens: number` 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](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) for details. - `type: "enabled"` - `"enabled"` - `display?: "summarized" | "omitted" | null` Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. Defaults to `summarized`. - `"summarized"` - `"omitted"` ### Beta Thinking Config Param - `BetaThinkingConfigParam = BetaThinkingConfigEnabled | BetaThinkingConfigDisabled | BetaThinkingConfigAdaptive` 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](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) for details. - `BetaThinkingConfigEnabled` - `budget_tokens: number` 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](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) for details. - `type: "enabled"` - `"enabled"` - `display?: "summarized" | "omitted" | null` Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. Defaults to `summarized`. - `"summarized"` - `"omitted"` - `BetaThinkingConfigDisabled` - `type: "disabled"` - `"disabled"` - `BetaThinkingConfigAdaptive` - `type: "adaptive"` - `"adaptive"` - `display?: "summarized" | "omitted" | null` Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. Defaults to `summarized`. - `"summarized"` - `"omitted"` ### Beta Thinking Delta - `BetaThinkingDelta` - `estimated_tokens: number | null` Per-frame increment of a coarse, running estimate of the tokens this thinking block has produced so far. Present whenever the `thinking-token-count-2026-05-13` beta is set; `null` unless `thinking.display` resolves to `"omitted"` and a count is due this frame. Sum the increments across `thinking_delta` frames on this block for a progress indicator. Each increment is a non-negative multiple of a fixed quantum and the cadence is rate-limited, so this is a deliberately lossy display hint, not a billable count; `usage.output_tokens` remains authoritative. - `thinking: string` - `type: "thinking_delta"` - `"thinking_delta"` ### Beta Thinking Turns - `BetaThinkingTurns` - `type: "thinking_turns"` - `"thinking_turns"` - `value: number` ### Beta Token Task Budget - `BetaTokenTaskBudget` User-configurable total token budget across contexts. - `total: number` Total token budget across all contexts in the session. - `type: "tokens"` The budget type. Currently only 'tokens' is supported. - `"tokens"` - `remaining?: number | null` Remaining tokens in the budget. Use this to track usage across contexts when implementing compaction client-side. Defaults to total if not provided. ### Beta Tool - `BetaTool` - `input_schema: InputSchema` [JSON schema](https://json-schema.org/draft/2020-12) for this tool's input. This defines the shape of the `input` that your tool accepts and that the model will produce. - `type: "object"` - `"object"` - `properties?: Record | null` - `required?: Array | null` - `name: string` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `"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`. - `"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. - `description?: string` Description of what this tool does. Tool descriptions should be as detailed as possible. The more information that the model has about what the tool is and how to use it, the better it will perform. You can use natural language descriptions to reinforce important aspects of the tool input JSON schema. - `eager_input_streaming?: boolean | null` Enable eager input streaming for this tool. When true, tool input parameters will be streamed incrementally as they are generated, and types will be inferred on-the-fly rather than buffering the full JSON output. When false, streaming is disabled for this tool even if the fine-grained-tool-streaming beta is active. When null (default), uses the default behavior based on beta headers. - `input_examples?: Array>` - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `type?: "custom" | null` - `"custom"` ### Beta Tool Bash 20241022 - `BetaToolBash20241022` - `name: "bash"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"bash"` - `type: "bash_20241022"` - `"bash_20241022"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `"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`. - `"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. - `input_examples?: Array>` - `strict?: boolean` When true, guarantees schema validation on tool names and inputs ### Beta Tool Bash 20250124 - `BetaToolBash20250124` - `name: "bash"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"bash"` - `type: "bash_20250124"` - `"bash_20250124"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `"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`. - `"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. - `input_examples?: Array>` - `strict?: boolean` When true, guarantees schema validation on tool names and inputs ### Beta Tool Choice - `BetaToolChoice = BetaToolChoiceAuto | BetaToolChoiceAny | BetaToolChoiceTool | BetaToolChoiceNone` How the model should use the provided tools. The model can use a specific tool, any available tool, decide by itself, or not use tools at all. - `BetaToolChoiceAuto` The model will automatically decide whether to use tools. - `type: "auto"` - `"auto"` - `disable_parallel_tool_use?: boolean` Whether to disable parallel tool use. Defaults to `false`. If set to `true`, the model will output at most one tool use. - `BetaToolChoiceAny` The model will use any available tools. - `type: "any"` - `"any"` - `disable_parallel_tool_use?: boolean` Whether to disable parallel tool use. Defaults to `false`. If set to `true`, the model will output exactly one tool use. - `BetaToolChoiceTool` The model will use the specified tool with `tool_choice.name`. - `name: string` The name of the tool to use. - `type: "tool"` - `"tool"` - `disable_parallel_tool_use?: boolean` Whether to disable parallel tool use. Defaults to `false`. If set to `true`, the model will output exactly one tool use. - `BetaToolChoiceNone` The model will not be allowed to use tools. - `type: "none"` - `"none"` ### Beta Tool Choice Any - `BetaToolChoiceAny` The model will use any available tools. - `type: "any"` - `"any"` - `disable_parallel_tool_use?: boolean` Whether to disable parallel tool use. Defaults to `false`. If set to `true`, the model will output exactly one tool use. ### Beta Tool Choice Auto - `BetaToolChoiceAuto` The model will automatically decide whether to use tools. - `type: "auto"` - `"auto"` - `disable_parallel_tool_use?: boolean` Whether to disable parallel tool use. Defaults to `false`. If set to `true`, the model will output at most one tool use. ### Beta Tool Choice None - `BetaToolChoiceNone` The model will not be allowed to use tools. - `type: "none"` - `"none"` ### Beta Tool Choice Tool - `BetaToolChoiceTool` The model will use the specified tool with `tool_choice.name`. - `name: string` The name of the tool to use. - `type: "tool"` - `"tool"` - `disable_parallel_tool_use?: boolean` Whether to disable parallel tool use. Defaults to `false`. If set to `true`, the model will output exactly one tool use. ### Beta Tool Computer Use 20241022 - `BetaToolComputerUse20241022` - `display_height_px: number` The height of the display in pixels. - `display_width_px: number` The width of the display in pixels. - `name: "computer"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"computer"` - `type: "computer_20241022"` - `"computer_20241022"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `"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`. - `"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. - `display_number?: number | null` The X11 display number (e.g. 0, 1) for the display. - `input_examples?: Array>` - `strict?: boolean` When true, guarantees schema validation on tool names and inputs ### Beta Tool Computer Use 20250124 - `BetaToolComputerUse20250124` - `display_height_px: number` The height of the display in pixels. - `display_width_px: number` The width of the display in pixels. - `name: "computer"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"computer"` - `type: "computer_20250124"` - `"computer_20250124"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `"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`. - `"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. - `display_number?: number | null` The X11 display number (e.g. 0, 1) for the display. - `input_examples?: Array>` - `strict?: boolean` When true, guarantees schema validation on tool names and inputs ### Beta Tool Computer Use 20251124 - `BetaToolComputerUse20251124` - `display_height_px: number` The height of the display in pixels. - `display_width_px: number` The width of the display in pixels. - `name: "computer"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"computer"` - `type: "computer_20251124"` - `"computer_20251124"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `"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`. - `"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. - `display_number?: number | null` The X11 display number (e.g. 0, 1) for the display. - `enable_zoom?: boolean` Whether to enable an action to take a zoomed-in screenshot of the screen. - `input_examples?: Array>` - `strict?: boolean` When true, guarantees schema validation on tool names and inputs ### Beta Tool Reference Block - `BetaToolReferenceBlock` - `tool_name: string` - `type: "tool_reference"` - `"tool_reference"` ### Beta Tool Reference Block Param - `BetaToolReferenceBlockParam` Tool reference block that can be included in tool_result content. - `tool_name: string` - `type: "tool_reference"` - `"tool_reference"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `"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`. - `"5m"` - `"1h"` ### Beta Tool Result Block Param - `BetaToolResultBlockParam` - `tool_use_id: string` - `type: "tool_result"` - `"tool_result"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `"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`. - `"5m"` - `"1h"` - `content?: string | Array` - `string` - `Array` - `BetaTextBlockParam` - `text: string` - `type: "text"` - `"text"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `citations?: Array | null` - `BetaCitationCharLocationParam` - `cited_text: string` - `document_index: number` - `document_title: string | null` - `end_char_index: number` - `start_char_index: number` - `type: "char_location"` - `"char_location"` - `BetaCitationPageLocationParam` - `cited_text: string` - `document_index: number` - `document_title: string | null` - `end_page_number: number` - `start_page_number: number` - `type: "page_location"` - `"page_location"` - `BetaCitationContentBlockLocationParam` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `document_index: number` - `document_title: string | null` - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. - `type: "content_block_location"` - `"content_block_location"` - `BetaCitationWebSearchResultLocationParam` - `cited_text: string` - `encrypted_index: string` - `title: string | null` - `type: "web_search_result_location"` - `"web_search_result_location"` - `url: string` - `BetaCitationSearchResultLocationParam` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `search_result_index: number` 0-based index of the cited search result among all `search_result` content blocks in the request, in the order they appear across messages and tool results. Counted separately from `document_index`; server-side web search results are not included in this count. - `source: string` - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. - `title: string | null` - `type: "search_result_location"` - `"search_result_location"` - `BetaImageBlockParam` - `source: BetaBase64ImageSource | BetaURLImageSource | BetaFileImageSource` - `BetaBase64ImageSource` - `data: string` - `media_type: "image/jpeg" | "image/png" | "image/gif" | "image/webp"` - `"image/jpeg"` - `"image/png"` - `"image/gif"` - `"image/webp"` - `type: "base64"` - `"base64"` - `BetaURLImageSource` - `type: "url"` - `"url"` - `url: string` - `BetaFileImageSource` - `file_id: string` - `type: "file"` - `"file"` - `type: "image"` - `"image"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `BetaSearchResultBlockParam` - `content: Array` - `text: string` - `type: "text"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `citations?: Array | null` - `source: string` - `title: string` - `type: "search_result"` - `"search_result"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `citations?: BetaCitationsConfigParam` - `enabled?: boolean` - `BetaRequestDocumentBlock` - `source: BetaBase64PDFSource | BetaPlainTextSource | BetaContentBlockSource | 2 more` - `BetaBase64PDFSource` - `data: string` - `media_type: "application/pdf"` - `"application/pdf"` - `type: "base64"` - `"base64"` - `BetaPlainTextSource` - `data: string` - `media_type: "text/plain"` - `"text/plain"` - `type: "text"` - `"text"` - `BetaContentBlockSource` - `content: string | Array` - `string` - `Array` - `BetaTextBlockParam` - `BetaImageBlockParam` - `type: "content"` - `"content"` - `BetaURLPDFSource` - `type: "url"` - `"url"` - `url: string` - `BetaFileDocumentSource` - `file_id: string` - `type: "file"` - `"file"` - `type: "document"` - `"document"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `citations?: BetaCitationsConfigParam | null` - `context?: string | null` - `title?: string | null` - `BetaToolReferenceBlockParam` Tool reference block that can be included in tool_result content. - `tool_name: string` - `type: "tool_reference"` - `"tool_reference"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `is_error?: boolean` ### Beta Tool Search Tool Bm25 20251119 - `BetaToolSearchToolBm25_20251119` - `name: "tool_search_tool_bm25"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"tool_search_tool_bm25"` - `type: "tool_search_tool_bm25_20251119" | "tool_search_tool_bm25"` - `"tool_search_tool_bm25_20251119"` - `"tool_search_tool_bm25"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `"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`. - `"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 ### Beta Tool Search Tool Regex 20251119 - `BetaToolSearchToolRegex20251119` - `name: "tool_search_tool_regex"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"tool_search_tool_regex"` - `type: "tool_search_tool_regex_20251119" | "tool_search_tool_regex"` - `"tool_search_tool_regex_20251119"` - `"tool_search_tool_regex"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `"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`. - `"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 ### Beta Tool Search Tool Result Block - `BetaToolSearchToolResultBlock` - `content: BetaToolSearchToolResultError | BetaToolSearchToolSearchResultBlock` - `BetaToolSearchToolResultError` - `error_code: "invalid_tool_input" | "unavailable" | "too_many_requests" | "execution_time_exceeded"` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `error_message: string | null` - `type: "tool_search_tool_result_error"` - `"tool_search_tool_result_error"` - `BetaToolSearchToolSearchResultBlock` - `tool_references: Array` - `tool_name: string` - `type: "tool_reference"` - `"tool_reference"` - `type: "tool_search_tool_search_result"` - `"tool_search_tool_search_result"` - `tool_use_id: string` - `type: "tool_search_tool_result"` - `"tool_search_tool_result"` ### Beta Tool Search Tool Result Block Param - `BetaToolSearchToolResultBlockParam` - `content: BetaToolSearchToolResultErrorParam | BetaToolSearchToolSearchResultBlockParam` - `BetaToolSearchToolResultErrorParam` - `error_code: "invalid_tool_input" | "unavailable" | "too_many_requests" | "execution_time_exceeded"` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `type: "tool_search_tool_result_error"` - `"tool_search_tool_result_error"` - `BetaToolSearchToolSearchResultBlockParam` - `tool_references: Array` - `tool_name: string` - `type: "tool_reference"` - `"tool_reference"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `"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`. - `"5m"` - `"1h"` - `type: "tool_search_tool_search_result"` - `"tool_search_tool_search_result"` - `tool_use_id: string` - `type: "tool_search_tool_result"` - `"tool_search_tool_result"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. ### Beta Tool Search Tool Result Error - `BetaToolSearchToolResultError` - `error_code: "invalid_tool_input" | "unavailable" | "too_many_requests" | "execution_time_exceeded"` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `error_message: string | null` - `type: "tool_search_tool_result_error"` - `"tool_search_tool_result_error"` ### Beta Tool Search Tool Result Error Param - `BetaToolSearchToolResultErrorParam` - `error_code: "invalid_tool_input" | "unavailable" | "too_many_requests" | "execution_time_exceeded"` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `type: "tool_search_tool_result_error"` - `"tool_search_tool_result_error"` ### Beta Tool Search Tool Search Result Block - `BetaToolSearchToolSearchResultBlock` - `tool_references: Array` - `tool_name: string` - `type: "tool_reference"` - `"tool_reference"` - `type: "tool_search_tool_search_result"` - `"tool_search_tool_search_result"` ### Beta Tool Search Tool Search Result Block Param - `BetaToolSearchToolSearchResultBlockParam` - `tool_references: Array` - `tool_name: string` - `type: "tool_reference"` - `"tool_reference"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `"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`. - `"5m"` - `"1h"` - `type: "tool_search_tool_search_result"` - `"tool_search_tool_search_result"` ### Beta Tool Text Editor 20241022 - `BetaToolTextEditor20241022` - `name: "str_replace_editor"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"str_replace_editor"` - `type: "text_editor_20241022"` - `"text_editor_20241022"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `"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`. - `"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. - `input_examples?: Array>` - `strict?: boolean` When true, guarantees schema validation on tool names and inputs ### Beta Tool Text Editor 20250124 - `BetaToolTextEditor20250124` - `name: "str_replace_editor"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"str_replace_editor"` - `type: "text_editor_20250124"` - `"text_editor_20250124"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `"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`. - `"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. - `input_examples?: Array>` - `strict?: boolean` When true, guarantees schema validation on tool names and inputs ### Beta Tool Text Editor 20250429 - `BetaToolTextEditor20250429` - `name: "str_replace_based_edit_tool"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"str_replace_based_edit_tool"` - `type: "text_editor_20250429"` - `"text_editor_20250429"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `"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`. - `"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. - `input_examples?: Array>` - `strict?: boolean` When true, guarantees schema validation on tool names and inputs ### Beta Tool Text Editor 20250728 - `BetaToolTextEditor20250728` - `name: "str_replace_based_edit_tool"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"str_replace_based_edit_tool"` - `type: "text_editor_20250728"` - `"text_editor_20250728"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `"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`. - `"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. - `input_examples?: Array>` - `max_characters?: number | null` Maximum number of characters to display when viewing a file. If not specified, defaults to displaying the full file. - `strict?: boolean` When true, guarantees schema validation on tool names and inputs ### Beta Tool Union - `BetaToolUnion = BetaTool | BetaToolBash20241022 | BetaToolBash20250124 | 20 more` Code execution tool with REPL state persistence (daemon mode + gVisor checkpoint). - `BetaTool` - `input_schema: InputSchema` [JSON schema](https://json-schema.org/draft/2020-12) for this tool's input. This defines the shape of the `input` that your tool accepts and that the model will produce. - `type: "object"` - `"object"` - `properties?: Record | null` - `required?: Array | null` - `name: string` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `"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`. - `"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. - `description?: string` Description of what this tool does. Tool descriptions should be as detailed as possible. The more information that the model has about what the tool is and how to use it, the better it will perform. You can use natural language descriptions to reinforce important aspects of the tool input JSON schema. - `eager_input_streaming?: boolean | null` Enable eager input streaming for this tool. When true, tool input parameters will be streamed incrementally as they are generated, and types will be inferred on-the-fly rather than buffering the full JSON output. When false, streaming is disabled for this tool even if the fine-grained-tool-streaming beta is active. When null (default), uses the default behavior based on beta headers. - `input_examples?: Array>` - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `type?: "custom" | null` - `"custom"` - `BetaToolBash20241022` - `name: "bash"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"bash"` - `type: "bash_20241022"` - `"bash_20241022"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `defer_loading?: boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `input_examples?: Array>` - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `BetaToolBash20250124` - `name: "bash"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"bash"` - `type: "bash_20250124"` - `"bash_20250124"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `defer_loading?: boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `input_examples?: Array>` - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `BetaCodeExecutionTool20250522` - `name: "code_execution"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"code_execution"` - `type: "code_execution_20250522"` - `"code_execution_20250522"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `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: "code_execution"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"code_execution"` - `type: "code_execution_20250825"` - `"code_execution_20250825"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `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` Code execution tool with REPL state persistence (daemon mode + gVisor checkpoint). - `name: "code_execution"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"code_execution"` - `type: "code_execution_20260120"` - `"code_execution_20260120"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `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 - `BetaToolComputerUse20241022` - `display_height_px: number` The height of the display in pixels. - `display_width_px: number` The width of the display in pixels. - `name: "computer"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"computer"` - `type: "computer_20241022"` - `"computer_20241022"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `defer_loading?: boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `display_number?: number | null` The X11 display number (e.g. 0, 1) for the display. - `input_examples?: Array>` - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `BetaMemoryTool20250818` - `name: "memory"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"memory"` - `type: "memory_20250818"` - `"memory_20250818"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `defer_loading?: boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `input_examples?: Array>` - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `BetaToolComputerUse20250124` - `display_height_px: number` The height of the display in pixels. - `display_width_px: number` The width of the display in pixels. - `name: "computer"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"computer"` - `type: "computer_20250124"` - `"computer_20250124"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `defer_loading?: boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `display_number?: number | null` The X11 display number (e.g. 0, 1) for the display. - `input_examples?: Array>` - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `BetaToolTextEditor20241022` - `name: "str_replace_editor"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"str_replace_editor"` - `type: "text_editor_20241022"` - `"text_editor_20241022"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `defer_loading?: boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `input_examples?: Array>` - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `BetaToolComputerUse20251124` - `display_height_px: number` The height of the display in pixels. - `display_width_px: number` The width of the display in pixels. - `name: "computer"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"computer"` - `type: "computer_20251124"` - `"computer_20251124"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `defer_loading?: boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `display_number?: number | null` The X11 display number (e.g. 0, 1) for the display. - `enable_zoom?: boolean` Whether to enable an action to take a zoomed-in screenshot of the screen. - `input_examples?: Array>` - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `BetaToolTextEditor20250124` - `name: "str_replace_editor"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"str_replace_editor"` - `type: "text_editor_20250124"` - `"text_editor_20250124"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `defer_loading?: boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `input_examples?: Array>` - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `BetaToolTextEditor20250429` - `name: "str_replace_based_edit_tool"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"str_replace_based_edit_tool"` - `type: "text_editor_20250429"` - `"text_editor_20250429"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `defer_loading?: boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `input_examples?: Array>` - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `BetaToolTextEditor20250728` - `name: "str_replace_based_edit_tool"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"str_replace_based_edit_tool"` - `type: "text_editor_20250728"` - `"text_editor_20250728"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `defer_loading?: boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `input_examples?: Array>` - `max_characters?: number | null` Maximum number of characters to display when viewing a file. If not specified, defaults to displaying the full file. - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `BetaWebSearchTool20250305` - `name: "web_search"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"web_search"` - `type: "web_search_20250305"` - `"web_search_20250305"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `allowed_domains?: Array | null` If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`. - `blocked_domains?: Array | null` If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`. - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `defer_loading?: boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `max_uses?: number | null` Maximum number of times the tool can be used in the API request. - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `user_location?: BetaUserLocation | null` Parameters for the user's location. Used to provide more relevant search results. - `type: "approximate"` - `"approximate"` - `city?: string | null` The city of the user. - `country?: string | null` The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user. - `region?: string | null` The region of the user. - `timezone?: string | null` The [IANA timezone](https://nodatime.org/TimeZones) of the user. - `BetaWebFetchTool20250910` - `name: "web_fetch"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"web_fetch"` - `type: "web_fetch_20250910"` - `"web_fetch_20250910"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `allowed_domains?: Array | null` List of domains to allow fetching from - `blocked_domains?: Array | null` List of domains to block fetching from - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `citations?: BetaCitationsConfigParam | null` Citations configuration for fetched documents. Citations are disabled by default. - `enabled?: boolean` - `defer_loading?: boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `max_content_tokens?: number | null` Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. - `max_uses?: number | null` Maximum number of times the tool can be used in the API request. - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `BetaWebSearchTool20260209` - `name: "web_search"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"web_search"` - `type: "web_search_20260209"` - `"web_search_20260209"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `allowed_domains?: Array | null` If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`. - `blocked_domains?: Array | null` If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`. - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `defer_loading?: boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `max_uses?: number | null` Maximum number of times the tool can be used in the API request. - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `user_location?: BetaUserLocation | null` Parameters for the user's location. Used to provide more relevant search results. - `BetaWebFetchTool20260209` - `name: "web_fetch"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"web_fetch"` - `type: "web_fetch_20260209"` - `"web_fetch_20260209"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `allowed_domains?: Array | null` List of domains to allow fetching from - `blocked_domains?: Array | null` List of domains to block fetching from - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `citations?: BetaCitationsConfigParam | null` Citations configuration for fetched documents. Citations are disabled by default. - `defer_loading?: boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `max_content_tokens?: number | null` Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. - `max_uses?: number | null` Maximum number of times the tool can be used in the API request. - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `BetaWebFetchTool20260309` Web fetch tool with use_cache parameter for bypassing cached content. - `name: "web_fetch"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"web_fetch"` - `type: "web_fetch_20260309"` - `"web_fetch_20260309"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `allowed_domains?: Array | null` List of domains to allow fetching from - `blocked_domains?: Array | null` List of domains to block fetching from - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `citations?: BetaCitationsConfigParam | null` Citations configuration for fetched documents. Citations are disabled by default. - `defer_loading?: boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `max_content_tokens?: number | null` Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. - `max_uses?: number | null` Maximum number of times the tool can be used in the API request. - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `use_cache?: boolean` Whether to use cached content. Set to false to bypass the cache and fetch fresh content. Only set to false when the user explicitly requests fresh content or when fetching rapidly-changing sources. - `BetaAdvisorTool20260301` - `model: Model` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-opus-4-8" | "claude-opus-4-7" | "claude-mythos-preview" | 15 more` - `"claude-opus-4-8"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-7"` Frontier intelligence for long-running agents and coding - `"claude-mythos-preview"` New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` Fastest model with near-frontier intelligence - `"claude-haiku-4-5-20251001"` Fastest model with near-frontier intelligence - `"claude-opus-4-5"` Premium model combining maximum intelligence with practical performance - `"claude-opus-4-5-20251101"` Premium model combining maximum intelligence with practical performance - `"claude-sonnet-4-5"` High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` High-performance model for agents and coding - `"claude-opus-4-1"` Exceptional model for specialized complex tasks - `"claude-opus-4-1-20250805"` Exceptional model for specialized complex tasks - `"claude-opus-4-0"` Powerful model for complex tasks - `"claude-opus-4-20250514"` Powerful model for complex tasks - `"claude-sonnet-4-0"` High-performance model with extended thinking - `"claude-sonnet-4-20250514"` High-performance model with extended thinking - `"claude-3-haiku-20240307"` Fast and cost-effective model - `(string & {})` - `name: "advisor"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"advisor"` - `type: "advisor_20260301"` - `"advisor_20260301"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `caching?: BetaCacheControlEphemeral | null` Caching for the advisor's own prompt. When set, each advisor call writes a cache entry at the given TTL so subsequent calls in the same conversation read the stable prefix. When omitted, the advisor prompt is not cached. - `defer_loading?: boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `max_uses?: number | null` Maximum number of times the tool can be used in the API request. - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `BetaToolSearchToolBm25_20251119` - `name: "tool_search_tool_bm25"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"tool_search_tool_bm25"` - `type: "tool_search_tool_bm25_20251119" | "tool_search_tool_bm25"` - `"tool_search_tool_bm25_20251119"` - `"tool_search_tool_bm25"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `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 - `BetaToolSearchToolRegex20251119` - `name: "tool_search_tool_regex"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"tool_search_tool_regex"` - `type: "tool_search_tool_regex_20251119" | "tool_search_tool_regex"` - `"tool_search_tool_regex_20251119"` - `"tool_search_tool_regex"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `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 - `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. - `mcp_server_name: string` Name of the MCP server to configure tools for - `type: "mcp_toolset"` - `"mcp_toolset"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `configs?: Record | null` Configuration overrides for specific tools, keyed by tool name - `defer_loading?: boolean` - `enabled?: boolean` - `default_config?: BetaMCPToolDefaultConfig` Default configuration applied to all tools from this server - `defer_loading?: boolean` - `enabled?: boolean` ### Beta Tool Use Block - `BetaToolUseBlock` - `id: string` - `input: Record` - `name: string` - `type: "tool_use"` - `"tool_use"` - `caller?: BetaDirectCaller | BetaServerToolCaller | BetaServerToolCaller20260120` Tool invocation directly from the model. - `BetaDirectCaller` Tool invocation directly from the model. - `type: "direct"` - `"direct"` - `BetaServerToolCaller` Tool invocation generated by a server-side tool. - `tool_id: string` - `type: "code_execution_20250825"` - `"code_execution_20250825"` - `BetaServerToolCaller20260120` - `tool_id: string` - `type: "code_execution_20260120"` - `"code_execution_20260120"` ### Beta Tool Use Block Param - `BetaToolUseBlockParam` - `id: string` - `input: Record` - `name: string` - `type: "tool_use"` - `"tool_use"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `"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`. - `"5m"` - `"1h"` - `caller?: BetaDirectCaller | BetaServerToolCaller | BetaServerToolCaller20260120` Tool invocation directly from the model. - `BetaDirectCaller` Tool invocation directly from the model. - `type: "direct"` - `"direct"` - `BetaServerToolCaller` Tool invocation generated by a server-side tool. - `tool_id: string` - `type: "code_execution_20250825"` - `"code_execution_20250825"` - `BetaServerToolCaller20260120` - `tool_id: string` - `type: "code_execution_20260120"` - `"code_execution_20260120"` ### Beta Tool Uses Keep - `BetaToolUsesKeep` - `type: "tool_uses"` - `"tool_uses"` - `value: number` ### Beta Tool Uses Trigger - `BetaToolUsesTrigger` - `type: "tool_uses"` - `"tool_uses"` - `value: number` ### Beta URL Image Source - `BetaURLImageSource` - `type: "url"` - `"url"` - `url: string` ### Beta URL PDF Source - `BetaURLPDFSource` - `type: "url"` - `"url"` - `url: string` ### Beta Usage - `BetaUsage` - `cache_creation: BetaCacheCreation | null` Breakdown of cached tokens by TTL - `ephemeral_1h_input_tokens: number` The number of input tokens used to create the 1 hour cache entry. - `ephemeral_5m_input_tokens: number` The number of input tokens used to create the 5 minute cache entry. - `cache_creation_input_tokens: number | null` The number of input tokens used to create the cache entry. - `cache_read_input_tokens: number | null` The number of input tokens read from the cache. - `inference_geo: string | null` The geographic region where inference was performed for this request. - `input_tokens: number` The number of input tokens which were used. - `iterations: BetaIterationsUsage | null` Per-iteration token usage breakdown. Each entry represents one sampling iteration, with its own input/output token counts and cache statistics. This allows you to: - Determine which iterations exceeded long context thresholds (>=200k tokens) - Calculate the true context window size from the last iteration - Understand token accumulation across server-side tool use loops - `BetaMessageIterationUsage` Token usage for a sampling iteration. - `cache_creation: BetaCacheCreation | null` Breakdown of cached tokens by TTL - `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: "message"` Usage for a sampling iteration - `"message"` - `BetaCompactionIterationUsage` Token usage for a compaction iteration. - `cache_creation: BetaCacheCreation | null` Breakdown of cached tokens by TTL - `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 - `"compaction"` - `BetaAdvisorMessageIterationUsage` Token usage for an advisor sub-inference iteration. - `cache_creation: BetaCacheCreation | null` Breakdown of cached tokens by TTL - `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. - `model: Model` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-opus-4-8" | "claude-opus-4-7" | "claude-mythos-preview" | 15 more` - `"claude-opus-4-8"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-7"` Frontier intelligence for long-running agents and coding - `"claude-mythos-preview"` New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` Fastest model with near-frontier intelligence - `"claude-haiku-4-5-20251001"` Fastest model with near-frontier intelligence - `"claude-opus-4-5"` Premium model combining maximum intelligence with practical performance - `"claude-opus-4-5-20251101"` Premium model combining maximum intelligence with practical performance - `"claude-sonnet-4-5"` High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` High-performance model for agents and coding - `"claude-opus-4-1"` Exceptional model for specialized complex tasks - `"claude-opus-4-1-20250805"` Exceptional model for specialized complex tasks - `"claude-opus-4-0"` Powerful model for complex tasks - `"claude-opus-4-20250514"` Powerful model for complex tasks - `"claude-sonnet-4-0"` High-performance model with extended thinking - `"claude-sonnet-4-20250514"` High-performance model with extended thinking - `"claude-3-haiku-20240307"` Fast and cost-effective model - `(string & {})` - `output_tokens: number` The number of output tokens which were used. - `type: "advisor_message"` Usage for an advisor sub-inference iteration - `"advisor_message"` - `output_tokens: number` The number of output tokens which were used. - `output_tokens_details: BetaOutputTokensDetails | null` Breakdown of output tokens by category. `output_tokens` remains the inclusive, authoritative total used for billing. This object provides a read-only decomposition for observability — for example, how many of the billed output tokens were spent on internal reasoning that may have been summarized before being returned to you. - `thinking_tokens: number` Number of output tokens the model generated as internal reasoning, including the thinking-block delimiter tokens. Reflects the raw reasoning the model produced, not the (possibly shorter) summarized thinking text returned in the response body. Computed by re-tokenizing the raw reasoning text, so it may differ from the model's exact generation count by a small number of tokens. Always ≤ `output_tokens`; `output_tokens - thinking_tokens` approximates the non-reasoning output. - `server_tool_use: BetaServerToolUsage | null` The number of server tool requests. - `web_fetch_requests: number` The number of web fetch tool requests. - `web_search_requests: number` The number of web search tool requests. - `service_tier: "standard" | "priority" | "batch" | null` If the request used the priority, standard, or batch tier. - `"standard"` - `"priority"` - `"batch"` - `speed: "standard" | "fast" | null` The inference speed mode used for this request. - `"standard"` - `"fast"` ### Beta User Location - `BetaUserLocation` - `type: "approximate"` - `"approximate"` - `city?: string | null` The city of the user. - `country?: string | null` The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user. - `region?: string | null` The region of the user. - `timezone?: string | null` The [IANA timezone](https://nodatime.org/TimeZones) of the user. ### Beta Web Fetch Block - `BetaWebFetchBlock` - `content: BetaDocumentBlock` - `citations: BetaCitationConfig | null` Citation configuration for the document - `enabled: boolean` - `source: BetaBase64PDFSource | BetaPlainTextSource` - `BetaBase64PDFSource` - `data: string` - `media_type: "application/pdf"` - `"application/pdf"` - `type: "base64"` - `"base64"` - `BetaPlainTextSource` - `data: string` - `media_type: "text/plain"` - `"text/plain"` - `type: "text"` - `"text"` - `title: string | null` The title of the document - `type: "document"` - `"document"` - `retrieved_at: string | null` ISO 8601 timestamp when the content was retrieved - `type: "web_fetch_result"` - `"web_fetch_result"` - `url: string` Fetched content URL ### Beta Web Fetch Block Param - `BetaWebFetchBlockParam` - `content: BetaRequestDocumentBlock` - `source: BetaBase64PDFSource | BetaPlainTextSource | BetaContentBlockSource | 2 more` - `BetaBase64PDFSource` - `data: string` - `media_type: "application/pdf"` - `"application/pdf"` - `type: "base64"` - `"base64"` - `BetaPlainTextSource` - `data: string` - `media_type: "text/plain"` - `"text/plain"` - `type: "text"` - `"text"` - `BetaContentBlockSource` - `content: string | Array` - `string` - `Array` - `BetaTextBlockParam` - `text: string` - `type: "text"` - `"text"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `"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`. - `"5m"` - `"1h"` - `citations?: Array | null` - `BetaCitationCharLocationParam` - `cited_text: string` - `document_index: number` - `document_title: string | null` - `end_char_index: number` - `start_char_index: number` - `type: "char_location"` - `"char_location"` - `BetaCitationPageLocationParam` - `cited_text: string` - `document_index: number` - `document_title: string | null` - `end_page_number: number` - `start_page_number: number` - `type: "page_location"` - `"page_location"` - `BetaCitationContentBlockLocationParam` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `document_index: number` - `document_title: string | null` - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. - `type: "content_block_location"` - `"content_block_location"` - `BetaCitationWebSearchResultLocationParam` - `cited_text: string` - `encrypted_index: string` - `title: string | null` - `type: "web_search_result_location"` - `"web_search_result_location"` - `url: string` - `BetaCitationSearchResultLocationParam` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `search_result_index: number` 0-based index of the cited search result among all `search_result` content blocks in the request, in the order they appear across messages and tool results. Counted separately from `document_index`; server-side web search results are not included in this count. - `source: string` - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. - `title: string | null` - `type: "search_result_location"` - `"search_result_location"` - `BetaImageBlockParam` - `source: BetaBase64ImageSource | BetaURLImageSource | BetaFileImageSource` - `BetaBase64ImageSource` - `data: string` - `media_type: "image/jpeg" | "image/png" | "image/gif" | "image/webp"` - `"image/jpeg"` - `"image/png"` - `"image/gif"` - `"image/webp"` - `type: "base64"` - `"base64"` - `BetaURLImageSource` - `type: "url"` - `"url"` - `url: string` - `BetaFileImageSource` - `file_id: string` - `type: "file"` - `"file"` - `type: "image"` - `"image"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `type: "content"` - `"content"` - `BetaURLPDFSource` - `type: "url"` - `"url"` - `url: string` - `BetaFileDocumentSource` - `file_id: string` - `type: "file"` - `"file"` - `type: "document"` - `"document"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `citations?: BetaCitationsConfigParam | null` - `enabled?: boolean` - `context?: string | null` - `title?: string | null` - `type: "web_fetch_result"` - `"web_fetch_result"` - `url: string` Fetched content URL - `retrieved_at?: string | null` ISO 8601 timestamp when the content was retrieved ### Beta Web Fetch Tool 20250910 - `BetaWebFetchTool20250910` - `name: "web_fetch"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"web_fetch"` - `type: "web_fetch_20250910"` - `"web_fetch_20250910"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `allowed_domains?: Array | null` List of domains to allow fetching from - `blocked_domains?: Array | null` List of domains to block fetching from - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `"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`. - `"5m"` - `"1h"` - `citations?: BetaCitationsConfigParam | null` Citations configuration for fetched documents. Citations are disabled by default. - `enabled?: boolean` - `defer_loading?: boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `max_content_tokens?: number | null` Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. - `max_uses?: number | null` Maximum number of times the tool can be used in the API request. - `strict?: boolean` When true, guarantees schema validation on tool names and inputs ### Beta Web Fetch Tool 20260209 - `BetaWebFetchTool20260209` - `name: "web_fetch"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"web_fetch"` - `type: "web_fetch_20260209"` - `"web_fetch_20260209"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `allowed_domains?: Array | null` List of domains to allow fetching from - `blocked_domains?: Array | null` List of domains to block fetching from - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `"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`. - `"5m"` - `"1h"` - `citations?: BetaCitationsConfigParam | null` Citations configuration for fetched documents. Citations are disabled by default. - `enabled?: boolean` - `defer_loading?: boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `max_content_tokens?: number | null` Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. - `max_uses?: number | null` Maximum number of times the tool can be used in the API request. - `strict?: boolean` When true, guarantees schema validation on tool names and inputs ### Beta Web Fetch Tool 20260309 - `BetaWebFetchTool20260309` Web fetch tool with use_cache parameter for bypassing cached content. - `name: "web_fetch"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"web_fetch"` - `type: "web_fetch_20260309"` - `"web_fetch_20260309"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `allowed_domains?: Array | null` List of domains to allow fetching from - `blocked_domains?: Array | null` List of domains to block fetching from - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `"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`. - `"5m"` - `"1h"` - `citations?: BetaCitationsConfigParam | null` Citations configuration for fetched documents. Citations are disabled by default. - `enabled?: boolean` - `defer_loading?: boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `max_content_tokens?: number | null` Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. - `max_uses?: number | null` Maximum number of times the tool can be used in the API request. - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `use_cache?: boolean` Whether to use cached content. Set to false to bypass the cache and fetch fresh content. Only set to false when the user explicitly requests fresh content or when fetching rapidly-changing sources. ### Beta Web Fetch Tool Result Block - `BetaWebFetchToolResultBlock` - `content: BetaWebFetchToolResultErrorBlock | BetaWebFetchBlock` - `BetaWebFetchToolResultErrorBlock` - `error_code: BetaWebFetchToolResultErrorCode` - `"invalid_tool_input"` - `"url_too_long"` - `"url_not_allowed"` - `"url_not_in_prior_context"` - `"url_not_accessible"` - `"unsupported_content_type"` - `"too_many_requests"` - `"max_uses_exceeded"` - `"unavailable"` - `type: "web_fetch_tool_result_error"` - `"web_fetch_tool_result_error"` - `BetaWebFetchBlock` - `content: BetaDocumentBlock` - `citations: BetaCitationConfig | null` Citation configuration for the document - `enabled: boolean` - `source: BetaBase64PDFSource | BetaPlainTextSource` - `BetaBase64PDFSource` - `data: string` - `media_type: "application/pdf"` - `"application/pdf"` - `type: "base64"` - `"base64"` - `BetaPlainTextSource` - `data: string` - `media_type: "text/plain"` - `"text/plain"` - `type: "text"` - `"text"` - `title: string | null` The title of the document - `type: "document"` - `"document"` - `retrieved_at: string | null` ISO 8601 timestamp when the content was retrieved - `type: "web_fetch_result"` - `"web_fetch_result"` - `url: string` Fetched content URL - `tool_use_id: string` - `type: "web_fetch_tool_result"` - `"web_fetch_tool_result"` - `caller?: BetaDirectCaller | BetaServerToolCaller | BetaServerToolCaller20260120` Tool invocation directly from the model. - `BetaDirectCaller` Tool invocation directly from the model. - `type: "direct"` - `"direct"` - `BetaServerToolCaller` Tool invocation generated by a server-side tool. - `tool_id: string` - `type: "code_execution_20250825"` - `"code_execution_20250825"` - `BetaServerToolCaller20260120` - `tool_id: string` - `type: "code_execution_20260120"` - `"code_execution_20260120"` ### Beta Web Fetch Tool Result Block Param - `BetaWebFetchToolResultBlockParam` - `content: BetaWebFetchToolResultErrorBlockParam | BetaWebFetchBlockParam` - `BetaWebFetchToolResultErrorBlockParam` - `error_code: BetaWebFetchToolResultErrorCode` - `"invalid_tool_input"` - `"url_too_long"` - `"url_not_allowed"` - `"url_not_in_prior_context"` - `"url_not_accessible"` - `"unsupported_content_type"` - `"too_many_requests"` - `"max_uses_exceeded"` - `"unavailable"` - `type: "web_fetch_tool_result_error"` - `"web_fetch_tool_result_error"` - `BetaWebFetchBlockParam` - `content: BetaRequestDocumentBlock` - `source: BetaBase64PDFSource | BetaPlainTextSource | BetaContentBlockSource | 2 more` - `BetaBase64PDFSource` - `data: string` - `media_type: "application/pdf"` - `"application/pdf"` - `type: "base64"` - `"base64"` - `BetaPlainTextSource` - `data: string` - `media_type: "text/plain"` - `"text/plain"` - `type: "text"` - `"text"` - `BetaContentBlockSource` - `content: string | Array` - `string` - `Array` - `BetaTextBlockParam` - `text: string` - `type: "text"` - `"text"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `"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`. - `"5m"` - `"1h"` - `citations?: Array | null` - `BetaCitationCharLocationParam` - `cited_text: string` - `document_index: number` - `document_title: string | null` - `end_char_index: number` - `start_char_index: number` - `type: "char_location"` - `"char_location"` - `BetaCitationPageLocationParam` - `cited_text: string` - `document_index: number` - `document_title: string | null` - `end_page_number: number` - `start_page_number: number` - `type: "page_location"` - `"page_location"` - `BetaCitationContentBlockLocationParam` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `document_index: number` - `document_title: string | null` - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. - `type: "content_block_location"` - `"content_block_location"` - `BetaCitationWebSearchResultLocationParam` - `cited_text: string` - `encrypted_index: string` - `title: string | null` - `type: "web_search_result_location"` - `"web_search_result_location"` - `url: string` - `BetaCitationSearchResultLocationParam` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `search_result_index: number` 0-based index of the cited search result among all `search_result` content blocks in the request, in the order they appear across messages and tool results. Counted separately from `document_index`; server-side web search results are not included in this count. - `source: string` - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. - `title: string | null` - `type: "search_result_location"` - `"search_result_location"` - `BetaImageBlockParam` - `source: BetaBase64ImageSource | BetaURLImageSource | BetaFileImageSource` - `BetaBase64ImageSource` - `data: string` - `media_type: "image/jpeg" | "image/png" | "image/gif" | "image/webp"` - `"image/jpeg"` - `"image/png"` - `"image/gif"` - `"image/webp"` - `type: "base64"` - `"base64"` - `BetaURLImageSource` - `type: "url"` - `"url"` - `url: string` - `BetaFileImageSource` - `file_id: string` - `type: "file"` - `"file"` - `type: "image"` - `"image"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `type: "content"` - `"content"` - `BetaURLPDFSource` - `type: "url"` - `"url"` - `url: string` - `BetaFileDocumentSource` - `file_id: string` - `type: "file"` - `"file"` - `type: "document"` - `"document"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `citations?: BetaCitationsConfigParam | null` - `enabled?: boolean` - `context?: string | null` - `title?: string | null` - `type: "web_fetch_result"` - `"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"` - `"web_fetch_tool_result"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `caller?: BetaDirectCaller | BetaServerToolCaller | BetaServerToolCaller20260120` Tool invocation directly from the model. - `BetaDirectCaller` Tool invocation directly from the model. - `type: "direct"` - `"direct"` - `BetaServerToolCaller` Tool invocation generated by a server-side tool. - `tool_id: string` - `type: "code_execution_20250825"` - `"code_execution_20250825"` - `BetaServerToolCaller20260120` - `tool_id: string` - `type: "code_execution_20260120"` - `"code_execution_20260120"` ### Beta Web Fetch Tool Result Error Block - `BetaWebFetchToolResultErrorBlock` - `error_code: BetaWebFetchToolResultErrorCode` - `"invalid_tool_input"` - `"url_too_long"` - `"url_not_allowed"` - `"url_not_in_prior_context"` - `"url_not_accessible"` - `"unsupported_content_type"` - `"too_many_requests"` - `"max_uses_exceeded"` - `"unavailable"` - `type: "web_fetch_tool_result_error"` - `"web_fetch_tool_result_error"` ### Beta Web Fetch Tool Result Error Block Param - `BetaWebFetchToolResultErrorBlockParam` - `error_code: BetaWebFetchToolResultErrorCode` - `"invalid_tool_input"` - `"url_too_long"` - `"url_not_allowed"` - `"url_not_in_prior_context"` - `"url_not_accessible"` - `"unsupported_content_type"` - `"too_many_requests"` - `"max_uses_exceeded"` - `"unavailable"` - `type: "web_fetch_tool_result_error"` - `"web_fetch_tool_result_error"` ### Beta Web Fetch Tool Result Error Code - `BetaWebFetchToolResultErrorCode = "invalid_tool_input" | "url_too_long" | "url_not_allowed" | 6 more` - `"invalid_tool_input"` - `"url_too_long"` - `"url_not_allowed"` - `"url_not_in_prior_context"` - `"url_not_accessible"` - `"unsupported_content_type"` - `"too_many_requests"` - `"max_uses_exceeded"` - `"unavailable"` ### Beta Web Search Result Block - `BetaWebSearchResultBlock` - `encrypted_content: string` - `page_age: string | null` - `title: string` - `type: "web_search_result"` - `"web_search_result"` - `url: string` ### Beta Web Search Result Block Param - `BetaWebSearchResultBlockParam` - `encrypted_content: string` - `title: string` - `type: "web_search_result"` - `"web_search_result"` - `url: string` - `page_age?: string | null` ### Beta Web Search Tool 20250305 - `BetaWebSearchTool20250305` - `name: "web_search"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"web_search"` - `type: "web_search_20250305"` - `"web_search_20250305"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `allowed_domains?: Array | null` If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`. - `blocked_domains?: Array | null` If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`. - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `"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`. - `"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. - `max_uses?: number | null` Maximum number of times the tool can be used in the API request. - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `user_location?: BetaUserLocation | null` Parameters for the user's location. Used to provide more relevant search results. - `type: "approximate"` - `"approximate"` - `city?: string | null` The city of the user. - `country?: string | null` The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user. - `region?: string | null` The region of the user. - `timezone?: string | null` The [IANA timezone](https://nodatime.org/TimeZones) of the user. ### Beta Web Search Tool 20260209 - `BetaWebSearchTool20260209` - `name: "web_search"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"web_search"` - `type: "web_search_20260209"` - `"web_search_20260209"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `allowed_domains?: Array | null` If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`. - `blocked_domains?: Array | null` If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`. - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `"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`. - `"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. - `max_uses?: number | null` Maximum number of times the tool can be used in the API request. - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `user_location?: BetaUserLocation | null` Parameters for the user's location. Used to provide more relevant search results. - `type: "approximate"` - `"approximate"` - `city?: string | null` The city of the user. - `country?: string | null` The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user. - `region?: string | null` The region of the user. - `timezone?: string | null` The [IANA timezone](https://nodatime.org/TimeZones) of the user. ### Beta Web Search Tool Request Error - `BetaWebSearchToolRequestError` - `error_code: BetaWebSearchToolResultErrorCode` - `"invalid_tool_input"` - `"unavailable"` - `"max_uses_exceeded"` - `"too_many_requests"` - `"query_too_long"` - `"request_too_large"` - `type: "web_search_tool_result_error"` - `"web_search_tool_result_error"` ### Beta Web Search Tool Result Block - `BetaWebSearchToolResultBlock` - `content: BetaWebSearchToolResultBlockContent` - `BetaWebSearchToolResultError` - `error_code: BetaWebSearchToolResultErrorCode` - `"invalid_tool_input"` - `"unavailable"` - `"max_uses_exceeded"` - `"too_many_requests"` - `"query_too_long"` - `"request_too_large"` - `type: "web_search_tool_result_error"` - `"web_search_tool_result_error"` - `Array` - `encrypted_content: string` - `page_age: string | null` - `title: string` - `type: "web_search_result"` - `"web_search_result"` - `url: string` - `tool_use_id: string` - `type: "web_search_tool_result"` - `"web_search_tool_result"` - `caller?: BetaDirectCaller | BetaServerToolCaller | BetaServerToolCaller20260120` Tool invocation directly from the model. - `BetaDirectCaller` Tool invocation directly from the model. - `type: "direct"` - `"direct"` - `BetaServerToolCaller` Tool invocation generated by a server-side tool. - `tool_id: string` - `type: "code_execution_20250825"` - `"code_execution_20250825"` - `BetaServerToolCaller20260120` - `tool_id: string` - `type: "code_execution_20260120"` - `"code_execution_20260120"` ### Beta Web Search Tool Result Block Content - `BetaWebSearchToolResultBlockContent = BetaWebSearchToolResultError | Array` - `BetaWebSearchToolResultError` - `error_code: BetaWebSearchToolResultErrorCode` - `"invalid_tool_input"` - `"unavailable"` - `"max_uses_exceeded"` - `"too_many_requests"` - `"query_too_long"` - `"request_too_large"` - `type: "web_search_tool_result_error"` - `"web_search_tool_result_error"` - `Array` - `encrypted_content: string` - `page_age: string | null` - `title: string` - `type: "web_search_result"` - `"web_search_result"` - `url: string` ### Beta Web Search Tool Result Block Param - `BetaWebSearchToolResultBlockParam` - `content: BetaWebSearchToolResultBlockParamContent` - `Array` - `encrypted_content: string` - `title: string` - `type: "web_search_result"` - `"web_search_result"` - `url: string` - `page_age?: string | null` - `BetaWebSearchToolRequestError` - `error_code: BetaWebSearchToolResultErrorCode` - `"invalid_tool_input"` - `"unavailable"` - `"max_uses_exceeded"` - `"too_many_requests"` - `"query_too_long"` - `"request_too_large"` - `type: "web_search_tool_result_error"` - `"web_search_tool_result_error"` - `tool_use_id: string` - `type: "web_search_tool_result"` - `"web_search_tool_result"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `"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`. - `"5m"` - `"1h"` - `caller?: BetaDirectCaller | BetaServerToolCaller | BetaServerToolCaller20260120` Tool invocation directly from the model. - `BetaDirectCaller` Tool invocation directly from the model. - `type: "direct"` - `"direct"` - `BetaServerToolCaller` Tool invocation generated by a server-side tool. - `tool_id: string` - `type: "code_execution_20250825"` - `"code_execution_20250825"` - `BetaServerToolCaller20260120` - `tool_id: string` - `type: "code_execution_20260120"` - `"code_execution_20260120"` ### Beta Web Search Tool Result Block Param Content - `BetaWebSearchToolResultBlockParamContent = Array | BetaWebSearchToolRequestError` - `Array` - `encrypted_content: string` - `title: string` - `type: "web_search_result"` - `"web_search_result"` - `url: string` - `page_age?: string | null` - `BetaWebSearchToolRequestError` - `error_code: BetaWebSearchToolResultErrorCode` - `"invalid_tool_input"` - `"unavailable"` - `"max_uses_exceeded"` - `"too_many_requests"` - `"query_too_long"` - `"request_too_large"` - `type: "web_search_tool_result_error"` - `"web_search_tool_result_error"` ### Beta Web Search Tool Result Error - `BetaWebSearchToolResultError` - `error_code: BetaWebSearchToolResultErrorCode` - `"invalid_tool_input"` - `"unavailable"` - `"max_uses_exceeded"` - `"too_many_requests"` - `"query_too_long"` - `"request_too_large"` - `type: "web_search_tool_result_error"` - `"web_search_tool_result_error"` ### Beta Web Search Tool Result Error Code - `BetaWebSearchToolResultErrorCode = "invalid_tool_input" | "unavailable" | "max_uses_exceeded" | 3 more` - `"invalid_tool_input"` - `"unavailable"` - `"max_uses_exceeded"` - `"too_many_requests"` - `"query_too_long"` - `"request_too_large"` # Batches ## Create a Message Batch `client.beta.messages.batches.create(BatchCreateParamsparams, RequestOptionsoptions?): BetaMessageBatch` **post** `/v1/messages/batches` Send a batch of Message creation requests. The Message Batches API can be used to process multiple Messages API requests at once. Once a Message Batch is created, it begins processing immediately. Batches can take up to 24 hours to complete. Learn more about the Message Batches API in our [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing) ### Parameters - `params: BatchCreateParams` - `requests: Array` Body param: List of requests for prompt completion. Each is an individual request to create a Message. - `custom_id: string` Developer-provided ID created for each request in a Message Batch. Useful for matching results to requests, as results may be given out of request order. Must be unique for each request within the Message Batch. - `params: Params` Messages API creation parameters for the individual request. See the [Messages API reference](https://docs.claude.com/en/api/messages) for full documentation on available parameters. - `max_tokens: number` The maximum number of tokens to generate before stopping. Note that our models may stop _before_ reaching this maximum. This parameter only specifies the absolute maximum number of tokens to generate. Set to `0` to populate the [prompt cache](https://docs.claude.com/en/docs/build-with-claude/prompt-caching#pre-warming-the-cache) without generating a response. Different models have different maximum values for this parameter. See [models](https://docs.claude.com/en/docs/models-overview) for details. - `messages: Array` Input messages. Our models are trained to operate on alternating `user` and `assistant` conversational turns. When creating a new `Message`, you specify the prior conversational turns with the `messages` parameter, and the model then generates the next `Message` in the conversation. Consecutive `user` or `assistant` turns in your request will be combined into a single turn. Each input message must be an object with a `role` and `content`. You can specify a single `user`-role message, or you can include multiple `user` and `assistant` messages. If the final message uses the `assistant` role, the response content will continue immediately from the content in that message. This can be used to constrain part of the model's response. Example with a single `user` message: ```json [{"role": "user", "content": "Hello, Claude"}] ``` Example with multiple conversational turns: ```json [ {"role": "user", "content": "Hello there."}, {"role": "assistant", "content": "Hi, I'm Claude. How can I help you?"}, {"role": "user", "content": "Can you explain LLMs in plain English?"}, ] ``` Example with a partially-filled response from Claude: ```json [ {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, {"role": "assistant", "content": "The best answer is ("}, ] ``` Each input message `content` may be either a single `string` or an array of content blocks, where each block has a specific `type`. Using a `string` for `content` is shorthand for an array of one content block of type `"text"`. The following input messages are equivalent: ```json {"role": "user", "content": "Hello, Claude"} ``` ```json {"role": "user", "content": [{"type": "text", "text": "Hello, Claude"}]} ``` See [input examples](https://docs.claude.com/en/api/messages-examples). Note that if you want to include a [system prompt](https://docs.claude.com/en/docs/system-prompts), you can use the top-level `system` parameter — there is no `"system"` role for input messages in the Messages API. There is a limit of 100,000 messages in a single request. - `content: string | Array` - `string` - `Array` - `BetaTextBlockParam` - `text: string` - `type: "text"` - `"text"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `type: "ephemeral"` - `"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`. - `"5m"` - `"1h"` - `citations?: Array | null` - `BetaCitationCharLocationParam` - `cited_text: string` - `document_index: number` - `document_title: string | null` - `end_char_index: number` - `start_char_index: number` - `type: "char_location"` - `"char_location"` - `BetaCitationPageLocationParam` - `cited_text: string` - `document_index: number` - `document_title: string | null` - `end_page_number: number` - `start_page_number: number` - `type: "page_location"` - `"page_location"` - `BetaCitationContentBlockLocationParam` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `document_index: number` - `document_title: string | null` - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. - `type: "content_block_location"` - `"content_block_location"` - `BetaCitationWebSearchResultLocationParam` - `cited_text: string` - `encrypted_index: string` - `title: string | null` - `type: "web_search_result_location"` - `"web_search_result_location"` - `url: string` - `BetaCitationSearchResultLocationParam` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `search_result_index: number` 0-based index of the cited search result among all `search_result` content blocks in the request, in the order they appear across messages and tool results. Counted separately from `document_index`; server-side web search results are not included in this count. - `source: string` - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. - `title: string | null` - `type: "search_result_location"` - `"search_result_location"` - `BetaImageBlockParam` - `source: BetaBase64ImageSource | BetaURLImageSource | BetaFileImageSource` - `BetaBase64ImageSource` - `data: string` - `media_type: "image/jpeg" | "image/png" | "image/gif" | "image/webp"` - `"image/jpeg"` - `"image/png"` - `"image/gif"` - `"image/webp"` - `type: "base64"` - `"base64"` - `BetaURLImageSource` - `type: "url"` - `"url"` - `url: string` - `BetaFileImageSource` - `file_id: string` - `type: "file"` - `"file"` - `type: "image"` - `"image"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `BetaRequestDocumentBlock` - `source: BetaBase64PDFSource | BetaPlainTextSource | BetaContentBlockSource | 2 more` - `BetaBase64PDFSource` - `data: string` - `media_type: "application/pdf"` - `"application/pdf"` - `type: "base64"` - `"base64"` - `BetaPlainTextSource` - `data: string` - `media_type: "text/plain"` - `"text/plain"` - `type: "text"` - `"text"` - `BetaContentBlockSource` - `content: string | Array` - `string` - `Array` - `BetaTextBlockParam` - `BetaImageBlockParam` - `type: "content"` - `"content"` - `BetaURLPDFSource` - `type: "url"` - `"url"` - `url: string` - `BetaFileDocumentSource` - `file_id: string` - `type: "file"` - `"file"` - `type: "document"` - `"document"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `citations?: BetaCitationsConfigParam | null` - `enabled?: boolean` - `context?: string | null` - `title?: string | null` - `BetaSearchResultBlockParam` - `content: Array` - `text: string` - `type: "text"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `citations?: Array | null` - `source: string` - `title: string` - `type: "search_result"` - `"search_result"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `citations?: BetaCitationsConfigParam` - `BetaThinkingBlockParam` - `signature: string` - `thinking: string` - `type: "thinking"` - `"thinking"` - `BetaRedactedThinkingBlockParam` - `data: string` - `type: "redacted_thinking"` - `"redacted_thinking"` - `BetaToolUseBlockParam` - `id: string` - `input: Record` - `name: string` - `type: "tool_use"` - `"tool_use"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `caller?: BetaDirectCaller | BetaServerToolCaller | BetaServerToolCaller20260120` Tool invocation directly from the model. - `BetaDirectCaller` Tool invocation directly from the model. - `type: "direct"` - `"direct"` - `BetaServerToolCaller` Tool invocation generated by a server-side tool. - `tool_id: string` - `type: "code_execution_20250825"` - `"code_execution_20250825"` - `BetaServerToolCaller20260120` - `tool_id: string` - `type: "code_execution_20260120"` - `"code_execution_20260120"` - `BetaToolResultBlockParam` - `tool_use_id: string` - `type: "tool_result"` - `"tool_result"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `content?: string | Array` - `string` - `Array` - `BetaTextBlockParam` - `BetaImageBlockParam` - `BetaSearchResultBlockParam` - `BetaRequestDocumentBlock` - `BetaToolReferenceBlockParam` Tool reference block that can be included in tool_result content. - `tool_name: string` - `type: "tool_reference"` - `"tool_reference"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `is_error?: boolean` - `BetaServerToolUseBlockParam` - `id: string` - `input: Record` - `name: "advisor" | "web_search" | "web_fetch" | 5 more` - `"advisor"` - `"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"` - `"server_tool_use"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `caller?: BetaDirectCaller | BetaServerToolCaller | BetaServerToolCaller20260120` Tool invocation directly from the model. - `BetaDirectCaller` Tool invocation directly from the model. - `BetaServerToolCaller` Tool invocation generated by a server-side tool. - `BetaServerToolCaller20260120` - `BetaWebSearchToolResultBlockParam` - `content: BetaWebSearchToolResultBlockParamContent` - `Array` - `encrypted_content: string` - `title: string` - `type: "web_search_result"` - `"web_search_result"` - `url: string` - `page_age?: string | null` - `BetaWebSearchToolRequestError` - `error_code: BetaWebSearchToolResultErrorCode` - `"invalid_tool_input"` - `"unavailable"` - `"max_uses_exceeded"` - `"too_many_requests"` - `"query_too_long"` - `"request_too_large"` - `type: "web_search_tool_result_error"` - `"web_search_tool_result_error"` - `tool_use_id: string` - `type: "web_search_tool_result"` - `"web_search_tool_result"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `caller?: BetaDirectCaller | BetaServerToolCaller | BetaServerToolCaller20260120` Tool invocation directly from the model. - `BetaDirectCaller` Tool invocation directly from the model. - `BetaServerToolCaller` Tool invocation generated by a server-side tool. - `BetaServerToolCaller20260120` - `BetaWebFetchToolResultBlockParam` - `content: BetaWebFetchToolResultErrorBlockParam | BetaWebFetchBlockParam` - `BetaWebFetchToolResultErrorBlockParam` - `error_code: BetaWebFetchToolResultErrorCode` - `"invalid_tool_input"` - `"url_too_long"` - `"url_not_allowed"` - `"url_not_in_prior_context"` - `"url_not_accessible"` - `"unsupported_content_type"` - `"too_many_requests"` - `"max_uses_exceeded"` - `"unavailable"` - `type: "web_fetch_tool_result_error"` - `"web_fetch_tool_result_error"` - `BetaWebFetchBlockParam` - `content: BetaRequestDocumentBlock` - `type: "web_fetch_result"` - `"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"` - `"web_fetch_tool_result"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `caller?: BetaDirectCaller | BetaServerToolCaller | BetaServerToolCaller20260120` Tool invocation directly from the model. - `BetaDirectCaller` Tool invocation directly from the model. - `BetaServerToolCaller` Tool invocation generated by a server-side tool. - `BetaServerToolCaller20260120` - `BetaAdvisorToolResultBlockParam` - `content: BetaAdvisorToolResultErrorParam | BetaAdvisorResultBlockParam | BetaAdvisorRedactedResultBlockParam` - `BetaAdvisorToolResultErrorParam` - `error_code: "max_uses_exceeded" | "prompt_too_long" | "too_many_requests" | 3 more` - `"max_uses_exceeded"` - `"prompt_too_long"` - `"too_many_requests"` - `"overloaded"` - `"unavailable"` - `"execution_time_exceeded"` - `type: "advisor_tool_result_error"` - `"advisor_tool_result_error"` - `BetaAdvisorResultBlockParam` - `text: string` - `type: "advisor_result"` - `"advisor_result"` - `stop_reason?: string | null` - `BetaAdvisorRedactedResultBlockParam` - `encrypted_content: string` Opaque blob produced by a prior response; must be round-tripped verbatim. - `type: "advisor_redacted_result"` - `"advisor_redacted_result"` - `stop_reason?: string | null` - `tool_use_id: string` - `type: "advisor_tool_result"` - `"advisor_tool_result"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `BetaCodeExecutionToolResultBlockParam` - `content: BetaCodeExecutionToolResultBlockParamContent` Code execution result with encrypted stdout for PFC + web_search results. - `BetaCodeExecutionToolResultErrorParam` - `error_code: BetaCodeExecutionToolResultErrorCode` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `type: "code_execution_tool_result_error"` - `"code_execution_tool_result_error"` - `BetaCodeExecutionResultBlockParam` - `content: Array` - `file_id: string` - `type: "code_execution_output"` - `"code_execution_output"` - `return_code: number` - `stderr: string` - `stdout: string` - `type: "code_execution_result"` - `"code_execution_result"` - `BetaEncryptedCodeExecutionResultBlockParam` Code execution result with encrypted stdout for PFC + web_search results. - `content: Array` - `file_id: string` - `type: "code_execution_output"` - `encrypted_stdout: string` - `return_code: number` - `stderr: string` - `type: "encrypted_code_execution_result"` - `"encrypted_code_execution_result"` - `tool_use_id: string` - `type: "code_execution_tool_result"` - `"code_execution_tool_result"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `BetaBashCodeExecutionToolResultBlockParam` - `content: BetaBashCodeExecutionToolResultErrorParam | BetaBashCodeExecutionResultBlockParam` - `BetaBashCodeExecutionToolResultErrorParam` - `error_code: "invalid_tool_input" | "unavailable" | "too_many_requests" | 2 more` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `"output_file_too_large"` - `type: "bash_code_execution_tool_result_error"` - `"bash_code_execution_tool_result_error"` - `BetaBashCodeExecutionResultBlockParam` - `content: Array` - `file_id: string` - `type: "bash_code_execution_output"` - `"bash_code_execution_output"` - `return_code: number` - `stderr: string` - `stdout: string` - `type: "bash_code_execution_result"` - `"bash_code_execution_result"` - `tool_use_id: string` - `type: "bash_code_execution_tool_result"` - `"bash_code_execution_tool_result"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `BetaTextEditorCodeExecutionToolResultBlockParam` - `content: BetaTextEditorCodeExecutionToolResultErrorParam | BetaTextEditorCodeExecutionViewResultBlockParam | BetaTextEditorCodeExecutionCreateResultBlockParam | BetaTextEditorCodeExecutionStrReplaceResultBlockParam` - `BetaTextEditorCodeExecutionToolResultErrorParam` - `error_code: "invalid_tool_input" | "unavailable" | "too_many_requests" | 2 more` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `"file_not_found"` - `type: "text_editor_code_execution_tool_result_error"` - `"text_editor_code_execution_tool_result_error"` - `error_message?: string | null` - `BetaTextEditorCodeExecutionViewResultBlockParam` - `content: string` - `file_type: "text" | "image" | "pdf"` - `"text"` - `"image"` - `"pdf"` - `type: "text_editor_code_execution_view_result"` - `"text_editor_code_execution_view_result"` - `num_lines?: number | null` - `start_line?: number | null` - `total_lines?: number | null` - `BetaTextEditorCodeExecutionCreateResultBlockParam` - `is_file_update: boolean` - `type: "text_editor_code_execution_create_result"` - `"text_editor_code_execution_create_result"` - `BetaTextEditorCodeExecutionStrReplaceResultBlockParam` - `type: "text_editor_code_execution_str_replace_result"` - `"text_editor_code_execution_str_replace_result"` - `lines?: Array | 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"` - `"text_editor_code_execution_tool_result"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `BetaToolSearchToolResultBlockParam` - `content: BetaToolSearchToolResultErrorParam | BetaToolSearchToolSearchResultBlockParam` - `BetaToolSearchToolResultErrorParam` - `error_code: "invalid_tool_input" | "unavailable" | "too_many_requests" | "execution_time_exceeded"` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `type: "tool_search_tool_result_error"` - `"tool_search_tool_result_error"` - `BetaToolSearchToolSearchResultBlockParam` - `tool_references: Array` - `tool_name: string` - `type: "tool_reference"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `type: "tool_search_tool_search_result"` - `"tool_search_tool_search_result"` - `tool_use_id: string` - `type: "tool_search_tool_result"` - `"tool_search_tool_result"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `BetaMCPToolUseBlockParam` - `id: string` - `input: Record` - `name: string` - `server_name: string` The name of the MCP server - `type: "mcp_tool_use"` - `"mcp_tool_use"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `BetaRequestMCPToolResultBlockParam` - `tool_use_id: string` - `type: "mcp_tool_result"` - `"mcp_tool_result"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `content?: string | Array` - `string` - `Array` - `text: string` - `type: "text"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `citations?: Array | null` - `is_error?: boolean` - `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. - `file_id: string` - `type: "container_upload"` - `"container_upload"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `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. - `type: "compaction"` - `"compaction"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `content?: string | null` Summary of previously compacted content, or null if compaction failed - `encrypted_content?: string | null` Opaque metadata from prior compaction, to be round-tripped verbatim - `BetaMidConversationSystemBlockParam` System instructions that appear mid-conversation. Use this block to provide or update system-level instructions at a specific point in the conversation, rather than only via the top-level `system` parameter. - `content: Array` System instruction text blocks. - `text: string` - `type: "text"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `citations?: Array | null` - `type: "mid_conv_system"` - `"mid_conv_system"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `role: "user" | "assistant" | "system"` - `"user"` - `"assistant"` - `"system"` - `model: Model` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-opus-4-8" | "claude-opus-4-7" | "claude-mythos-preview" | 15 more` - `"claude-opus-4-8"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-7"` Frontier intelligence for long-running agents and coding - `"claude-mythos-preview"` New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` Fastest model with near-frontier intelligence - `"claude-haiku-4-5-20251001"` Fastest model with near-frontier intelligence - `"claude-opus-4-5"` Premium model combining maximum intelligence with practical performance - `"claude-opus-4-5-20251101"` Premium model combining maximum intelligence with practical performance - `"claude-sonnet-4-5"` High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` High-performance model for agents and coding - `"claude-opus-4-1"` Exceptional model for specialized complex tasks - `"claude-opus-4-1-20250805"` Exceptional model for specialized complex tasks - `"claude-opus-4-0"` Powerful model for complex tasks - `"claude-opus-4-20250514"` Powerful model for complex tasks - `"claude-sonnet-4-0"` High-performance model with extended thinking - `"claude-sonnet-4-20250514"` High-performance model with extended thinking - `"claude-3-haiku-20240307"` Fast and cost-effective model - `(string & {})` - `cache_control?: BetaCacheControlEphemeral | null` Top-level cache control automatically applies a cache_control marker to the last cacheable block in the request. - `container?: BetaContainerParams | string | null` Container identifier for reuse across requests. - `BetaContainerParams` Container parameters with skills to be loaded. - `id?: string | null` Container id - `skills?: Array | 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) - `"anthropic"` - `"custom"` - `version?: string` Skill version or 'latest' for most recent version - `string` - `context_management?: BetaContextManagementConfig | null` Context management configuration. This allows you to control how Claude manages context across multiple requests, such as whether to clear function results or not. - `edits?: Array` List of context management edits to apply - `BetaClearToolUses20250919Edit` - `type: "clear_tool_uses_20250919"` - `"clear_tool_uses_20250919"` - `clear_at_least?: BetaInputTokensClearAtLeast | 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"` - `"input_tokens"` - `value: number` - `clear_tool_inputs?: boolean | Array | null` Whether to clear all tool inputs (bool) or specific tool inputs to clear (list) - `boolean` - `Array` - `exclude_tools?: Array | null` Tool names whose uses are preserved from clearing - `keep?: BetaToolUsesKeep` Number of tool uses to retain in the conversation - `type: "tool_uses"` - `"tool_uses"` - `value: number` - `trigger?: BetaInputTokensTrigger | BetaToolUsesTrigger` Condition that triggers the context management strategy - `BetaInputTokensTrigger` - `type: "input_tokens"` - `"input_tokens"` - `value: number` - `BetaToolUsesTrigger` - `type: "tool_uses"` - `"tool_uses"` - `value: number` - `BetaClearThinking20251015Edit` - `type: "clear_thinking_20251015"` - `"clear_thinking_20251015"` - `keep?: BetaThinkingTurns | BetaAllThinkingTurns | "all"` Number of most recent assistant turns to keep thinking blocks for. Older turns will have their thinking blocks removed. - `BetaThinkingTurns` - `type: "thinking_turns"` - `"thinking_turns"` - `value: number` - `BetaAllThinkingTurns` - `type: "all"` - `"all"` - `"all"` - `"all"` - `BetaCompact20260112Edit` Automatically compact older context when reaching the configured trigger threshold. - `type: "compact_20260112"` - `"compact_20260112"` - `instructions?: string | null` Additional instructions for summarization. - `pause_after_compaction?: boolean` Whether to pause after compaction and return the compaction block to the user. - `trigger?: BetaInputTokensTrigger | null` When to trigger compaction. Defaults to 150000 input tokens. - `diagnostics?: BetaDiagnosticsParam | null` Request-level diagnostics. Currently carries the previous response id for prompt-cache divergence reporting. - `previous_message_id?: string | null` The `id` (`msg_...`) from this client's previous /v1/messages response. The server compares that request's prompt fingerprint against this one and returns `diagnostics.cache_miss_reason` when the prompt-cache prefix could not be reused. Pass `null` on the first turn to opt in without a prior message to compare. - `inference_geo?: string | null` Specifies the geographic region for inference processing. If not specified, the workspace's `default_inference_geo` is used. - `mcp_servers?: Array` MCP servers to be utilized in this request - `name: string` - `type: "url"` - `"url"` - `url: string` - `authorization_token?: string | null` - `tool_configuration?: BetaRequestMCPServerToolConfiguration | null` - `allowed_tools?: Array | null` - `enabled?: boolean | null` - `metadata?: BetaMetadata` An object describing metadata about the request. - `user_id?: string | null` An external identifier for the user who is associated with the request. This should be a uuid, hash value, or other opaque identifier. Anthropic may use this id to help detect abuse. Do not include any identifying information such as name, email address, or phone number. - `output_config?: BetaOutputConfig` Configuration options for the model's output, such as the output format. - `effort?: "low" | "medium" | "high" | 2 more | null` All possible effort levels. - `"low"` - `"medium"` - `"high"` - `"xhigh"` - `"max"` - `format?: BetaJSONOutputFormat | null` A schema to specify Claude's output format in responses. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) - `schema: Record` The JSON schema of the format - `type: "json_schema"` - `"json_schema"` - `task_budget?: BetaTokenTaskBudget | null` User-configurable total token budget across contexts. - `total: number` Total token budget across all contexts in the session. - `type: "tokens"` The budget type. Currently only 'tokens' is supported. - `"tokens"` - `remaining?: number | null` Remaining tokens in the budget. Use this to track usage across contexts when implementing compaction client-side. Defaults to total if not provided. - `output_format?: BetaJSONOutputFormat | null` Deprecated: Use `output_config.format` instead. See [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) A schema to specify Claude's output format in responses. This parameter will be removed in a future release. - `service_tier?: "auto" | "standard_only"` Determines whether to use priority capacity (if available) or standard capacity for this request. Anthropic offers different levels of service for your API requests. See [service-tiers](https://docs.claude.com/en/api/service-tiers) for details. - `"auto"` - `"standard_only"` - `speed?: "standard" | "fast" | null` The inference speed mode for this request. `"fast"` enables high output-tokens-per-second inference. - `"standard"` - `"fast"` - `stop_sequences?: Array` Custom text sequences that will cause the model to stop generating. Our models will normally stop when they have naturally completed their turn, which will result in a response `stop_reason` of `"end_turn"`. If you want the model to stop generating when it encounters custom strings of text, you can use the `stop_sequences` parameter. If the model encounters one of the custom sequences, the response `stop_reason` value will be `"stop_sequence"` and the response `stop_sequence` value will contain the matched stop sequence. - `stream?: boolean` Whether to incrementally stream the response using server-sent events. See [streaming](https://docs.claude.com/en/api/messages-streaming) for details. - `system?: string | Array` System prompt. A system prompt is a way of providing context and instructions to Claude, such as specifying a particular goal or role. See our [guide to system prompts](https://docs.claude.com/en/docs/system-prompts). - `string` - `Array` - `text: string` - `type: "text"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `citations?: Array | null` - `temperature?: number` Amount of randomness injected into the response. Defaults to `1.0`. Ranges from `0.0` to `1.0`. Use `temperature` closer to `0.0` for analytical / multiple choice, and closer to `1.0` for creative and generative tasks. Note that even with `temperature` of `0.0`, the results will not be fully deterministic. - `thinking?: BetaThinkingConfigParam` 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](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) for details. - `BetaThinkingConfigEnabled` - `budget_tokens: number` 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](https://docs.claude.com/en/docs/build-with-claude/extended-thinking) for details. - `type: "enabled"` - `"enabled"` - `display?: "summarized" | "omitted" | null` Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. Defaults to `summarized`. - `"summarized"` - `"omitted"` - `BetaThinkingConfigDisabled` - `type: "disabled"` - `"disabled"` - `BetaThinkingConfigAdaptive` - `type: "adaptive"` - `"adaptive"` - `display?: "summarized" | "omitted" | null` Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. Defaults to `summarized`. - `"summarized"` - `"omitted"` - `tool_choice?: BetaToolChoice` How the model should use the provided tools. The model can use a specific tool, any available tool, decide by itself, or not use tools at all. - `BetaToolChoiceAuto` The model will automatically decide whether to use tools. - `type: "auto"` - `"auto"` - `disable_parallel_tool_use?: boolean` Whether to disable parallel tool use. Defaults to `false`. If set to `true`, the model will output at most one tool use. - `BetaToolChoiceAny` The model will use any available tools. - `type: "any"` - `"any"` - `disable_parallel_tool_use?: boolean` Whether to disable parallel tool use. Defaults to `false`. If set to `true`, the model will output exactly one tool use. - `BetaToolChoiceTool` The model will use the specified tool with `tool_choice.name`. - `name: string` The name of the tool to use. - `type: "tool"` - `"tool"` - `disable_parallel_tool_use?: boolean` Whether to disable parallel tool use. Defaults to `false`. If set to `true`, the model will output exactly one tool use. - `BetaToolChoiceNone` The model will not be allowed to use tools. - `type: "none"` - `"none"` - `tools?: Array` Definitions of tools that the model may use. If you include `tools` in your API request, the model may return `tool_use` content blocks that represent the model's use of those tools. You can then run those tools using the tool input generated by the model and then optionally return results back to the model using `tool_result` content blocks. There are two types of tools: **client tools** and **server tools**. The behavior described below applies to client tools. For [server tools](https://docs.claude.com/en/docs/agents-and-tools/tool-use/overview#server-tools), see their individual documentation as each has its own behavior (e.g., the [web search tool](https://docs.claude.com/en/docs/agents-and-tools/tool-use/web-search-tool)). Each tool definition includes: * `name`: Name of the tool. * `description`: Optional, but strongly-recommended description of the tool. * `input_schema`: [JSON schema](https://json-schema.org/draft/2020-12) for the tool `input` shape that the model will produce in `tool_use` output content blocks. For example, if you defined `tools` as: ```json [ { "name": "get_stock_price", "description": "Get the current stock price for a given ticker symbol.", "input_schema": { "type": "object", "properties": { "ticker": { "type": "string", "description": "The stock ticker symbol, e.g. AAPL for Apple Inc." } }, "required": ["ticker"] } } ] ``` And then asked the model "What's the S&P 500 at today?", the model might produce `tool_use` content blocks in the response like this: ```json [ { "type": "tool_use", "id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", "name": "get_stock_price", "input": { "ticker": "^GSPC" } } ] ``` You might then run your `get_stock_price` tool with `{"ticker": "^GSPC"}` as an input, and return the following back to the model in a subsequent `user` message: ```json [ { "type": "tool_result", "tool_use_id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", "content": "259.75 USD" } ] ``` Tools can be used for workflows that include running client-side tools and functions, or more generally whenever you want the model to produce a particular JSON structure of output. See our [guide](https://docs.claude.com/en/docs/tool-use) for more details. - `BetaTool` - `input_schema: InputSchema` [JSON schema](https://json-schema.org/draft/2020-12) for this tool's input. This defines the shape of the `input` that your tool accepts and that the model will produce. - `type: "object"` - `"object"` - `properties?: Record | null` - `required?: Array | null` - `name: string` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `defer_loading?: boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `description?: string` Description of what this tool does. Tool descriptions should be as detailed as possible. The more information that the model has about what the tool is and how to use it, the better it will perform. You can use natural language descriptions to reinforce important aspects of the tool input JSON schema. - `eager_input_streaming?: boolean | null` Enable eager input streaming for this tool. When true, tool input parameters will be streamed incrementally as they are generated, and types will be inferred on-the-fly rather than buffering the full JSON output. When false, streaming is disabled for this tool even if the fine-grained-tool-streaming beta is active. When null (default), uses the default behavior based on beta headers. - `input_examples?: Array>` - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `type?: "custom" | null` - `"custom"` - `BetaToolBash20241022` - `name: "bash"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"bash"` - `type: "bash_20241022"` - `"bash_20241022"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `defer_loading?: boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `input_examples?: Array>` - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `BetaToolBash20250124` - `name: "bash"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"bash"` - `type: "bash_20250124"` - `"bash_20250124"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `defer_loading?: boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `input_examples?: Array>` - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `BetaCodeExecutionTool20250522` - `name: "code_execution"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"code_execution"` - `type: "code_execution_20250522"` - `"code_execution_20250522"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `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: "code_execution"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"code_execution"` - `type: "code_execution_20250825"` - `"code_execution_20250825"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `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` Code execution tool with REPL state persistence (daemon mode + gVisor checkpoint). - `name: "code_execution"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"code_execution"` - `type: "code_execution_20260120"` - `"code_execution_20260120"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `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 - `BetaToolComputerUse20241022` - `display_height_px: number` The height of the display in pixels. - `display_width_px: number` The width of the display in pixels. - `name: "computer"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"computer"` - `type: "computer_20241022"` - `"computer_20241022"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `defer_loading?: boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `display_number?: number | null` The X11 display number (e.g. 0, 1) for the display. - `input_examples?: Array>` - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `BetaMemoryTool20250818` - `name: "memory"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"memory"` - `type: "memory_20250818"` - `"memory_20250818"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `defer_loading?: boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `input_examples?: Array>` - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `BetaToolComputerUse20250124` - `display_height_px: number` The height of the display in pixels. - `display_width_px: number` The width of the display in pixels. - `name: "computer"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"computer"` - `type: "computer_20250124"` - `"computer_20250124"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `defer_loading?: boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `display_number?: number | null` The X11 display number (e.g. 0, 1) for the display. - `input_examples?: Array>` - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `BetaToolTextEditor20241022` - `name: "str_replace_editor"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"str_replace_editor"` - `type: "text_editor_20241022"` - `"text_editor_20241022"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `defer_loading?: boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `input_examples?: Array>` - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `BetaToolComputerUse20251124` - `display_height_px: number` The height of the display in pixels. - `display_width_px: number` The width of the display in pixels. - `name: "computer"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"computer"` - `type: "computer_20251124"` - `"computer_20251124"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `defer_loading?: boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `display_number?: number | null` The X11 display number (e.g. 0, 1) for the display. - `enable_zoom?: boolean` Whether to enable an action to take a zoomed-in screenshot of the screen. - `input_examples?: Array>` - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `BetaToolTextEditor20250124` - `name: "str_replace_editor"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"str_replace_editor"` - `type: "text_editor_20250124"` - `"text_editor_20250124"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `defer_loading?: boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `input_examples?: Array>` - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `BetaToolTextEditor20250429` - `name: "str_replace_based_edit_tool"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"str_replace_based_edit_tool"` - `type: "text_editor_20250429"` - `"text_editor_20250429"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `defer_loading?: boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `input_examples?: Array>` - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `BetaToolTextEditor20250728` - `name: "str_replace_based_edit_tool"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"str_replace_based_edit_tool"` - `type: "text_editor_20250728"` - `"text_editor_20250728"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `defer_loading?: boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `input_examples?: Array>` - `max_characters?: number | null` Maximum number of characters to display when viewing a file. If not specified, defaults to displaying the full file. - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `BetaWebSearchTool20250305` - `name: "web_search"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"web_search"` - `type: "web_search_20250305"` - `"web_search_20250305"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `allowed_domains?: Array | null` If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`. - `blocked_domains?: Array | null` If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`. - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `defer_loading?: boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `max_uses?: number | null` Maximum number of times the tool can be used in the API request. - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `user_location?: BetaUserLocation | null` Parameters for the user's location. Used to provide more relevant search results. - `type: "approximate"` - `"approximate"` - `city?: string | null` The city of the user. - `country?: string | null` The two letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) of the user. - `region?: string | null` The region of the user. - `timezone?: string | null` The [IANA timezone](https://nodatime.org/TimeZones) of the user. - `BetaWebFetchTool20250910` - `name: "web_fetch"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"web_fetch"` - `type: "web_fetch_20250910"` - `"web_fetch_20250910"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `allowed_domains?: Array | null` List of domains to allow fetching from - `blocked_domains?: Array | null` List of domains to block fetching from - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `citations?: BetaCitationsConfigParam | null` Citations configuration for fetched documents. Citations are disabled by default. - `defer_loading?: boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `max_content_tokens?: number | null` Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. - `max_uses?: number | null` Maximum number of times the tool can be used in the API request. - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `BetaWebSearchTool20260209` - `name: "web_search"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"web_search"` - `type: "web_search_20260209"` - `"web_search_20260209"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `allowed_domains?: Array | null` If provided, only these domains will be included in results. Cannot be used alongside `blocked_domains`. - `blocked_domains?: Array | null` If provided, these domains will never appear in results. Cannot be used alongside `allowed_domains`. - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `defer_loading?: boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `max_uses?: number | null` Maximum number of times the tool can be used in the API request. - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `user_location?: BetaUserLocation | null` Parameters for the user's location. Used to provide more relevant search results. - `BetaWebFetchTool20260209` - `name: "web_fetch"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"web_fetch"` - `type: "web_fetch_20260209"` - `"web_fetch_20260209"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `allowed_domains?: Array | null` List of domains to allow fetching from - `blocked_domains?: Array | null` List of domains to block fetching from - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `citations?: BetaCitationsConfigParam | null` Citations configuration for fetched documents. Citations are disabled by default. - `defer_loading?: boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `max_content_tokens?: number | null` Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. - `max_uses?: number | null` Maximum number of times the tool can be used in the API request. - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `BetaWebFetchTool20260309` Web fetch tool with use_cache parameter for bypassing cached content. - `name: "web_fetch"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"web_fetch"` - `type: "web_fetch_20260309"` - `"web_fetch_20260309"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `allowed_domains?: Array | null` List of domains to allow fetching from - `blocked_domains?: Array | null` List of domains to block fetching from - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `citations?: BetaCitationsConfigParam | null` Citations configuration for fetched documents. Citations are disabled by default. - `defer_loading?: boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `max_content_tokens?: number | null` Maximum number of tokens used by including web page text content in the context. The limit is approximate and does not apply to binary content such as PDFs. - `max_uses?: number | null` Maximum number of times the tool can be used in the API request. - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `use_cache?: boolean` Whether to use cached content. Set to false to bypass the cache and fetch fresh content. Only set to false when the user explicitly requests fresh content or when fetching rapidly-changing sources. - `BetaAdvisorTool20260301` - `model: Model` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `name: "advisor"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"advisor"` - `type: "advisor_20260301"` - `"advisor_20260301"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `caching?: BetaCacheControlEphemeral | null` Caching for the advisor's own prompt. When set, each advisor call writes a cache entry at the given TTL so subsequent calls in the same conversation read the stable prefix. When omitted, the advisor prompt is not cached. - `defer_loading?: boolean` If true, tool will not be included in initial system prompt. Only loaded when returned via tool_reference from tool search. - `max_uses?: number | null` Maximum number of times the tool can be used in the API request. - `strict?: boolean` When true, guarantees schema validation on tool names and inputs - `BetaToolSearchToolBm25_20251119` - `name: "tool_search_tool_bm25"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"tool_search_tool_bm25"` - `type: "tool_search_tool_bm25_20251119" | "tool_search_tool_bm25"` - `"tool_search_tool_bm25_20251119"` - `"tool_search_tool_bm25"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `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 - `BetaToolSearchToolRegex20251119` - `name: "tool_search_tool_regex"` Name of the tool. This is how the tool will be called by the model and in `tool_use` blocks. - `"tool_search_tool_regex"` - `type: "tool_search_tool_regex_20251119" | "tool_search_tool_regex"` - `"tool_search_tool_regex_20251119"` - `"tool_search_tool_regex"` - `allowed_callers?: Array<"direct" | "code_execution_20250825" | "code_execution_20260120">` - `"direct"` - `"code_execution_20250825"` - `"code_execution_20260120"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `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 - `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. - `mcp_server_name: string` Name of the MCP server to configure tools for - `type: "mcp_toolset"` - `"mcp_toolset"` - `cache_control?: BetaCacheControlEphemeral | null` Create a cache control breakpoint at this content block. - `configs?: Record | null` Configuration overrides for specific tools, keyed by tool name - `defer_loading?: boolean` - `enabled?: boolean` - `default_config?: BetaMCPToolDefaultConfig` Default configuration applied to all tools from this server - `defer_loading?: boolean` - `enabled?: boolean` - `top_k?: number` Only sample from the top K options for each subsequent token. Used to remove "long tail" low probability responses. [Learn more technical details here](https://towardsdatascience.com/how-to-sample-from-language-models-682bceb97277). Recommended for advanced use cases only. - `top_p?: number` Use nucleus sampling. In nucleus sampling, we compute the cumulative distribution over all the options for each subsequent token in decreasing probability order and cut it off once it reaches a particular probability specified by `top_p`. Recommended for advanced use cases only. - `user_profile_id?: string | null` The user profile ID to attribute this request to. Use when acting on behalf of a party other than your organization. - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaMessageBatch` - `id: string` Unique object identifier. The format and length of IDs may change over time. - `archived_at: string | null` RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable. - `cancel_initiated_at: string | null` RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated. - `created_at: string` RFC 3339 datetime string representing the time at which the Message Batch was created. - `ended_at: string | null` RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends. Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired. - `expires_at: string` RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation. - `processing_status: "in_progress" | "canceling" | "ended"` Processing status of the Message Batch. - `"in_progress"` - `"canceling"` - `"ended"` - `request_counts: BetaMessageBatchRequestCounts` Tallies requests within the Message Batch, categorized by their status. Requests start as `processing` and move to one of the other statuses only once processing of the entire batch ends. The sum of all values always matches the total number of requests in the batch. - `canceled: number` Number of requests in the Message Batch that have been canceled. This is zero until processing of the entire Message Batch has ended. - `errored: number` Number of requests in the Message Batch that encountered an error. This is zero until processing of the entire Message Batch has ended. - `expired: number` Number of requests in the Message Batch that have expired. This is zero until processing of the entire Message Batch has ended. - `processing: number` Number of requests in the Message Batch that are processing. - `succeeded: number` Number of requests in the Message Batch that have completed successfully. This is zero until processing of the entire Message Batch has ended. - `results_url: string | null` URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends. Results in the file are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests. - `type: "message_batch"` Object type. For Message Batches, this is always `"message_batch"`. - `"message_batch"` ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const betaMessageBatch = await client.beta.messages.batches.create({ requests: [ { custom_id: 'my-custom-id-1', params: { max_tokens: 1024, messages: [{ content: 'Hello, world', role: 'user' }], model: 'claude-opus-4-6', }, }, ], }); console.log(betaMessageBatch.id); ``` #### Response ```json { "id": "msgbatch_013Zva2CMHLNnXjNJJKqJ2EF", "archived_at": "2024-08-20T18:37:24.100435Z", "cancel_initiated_at": "2024-08-20T18:37:24.100435Z", "created_at": "2024-08-20T18:37:24.100435Z", "ended_at": "2024-08-20T18:37:24.100435Z", "expires_at": "2024-08-20T18:37:24.100435Z", "processing_status": "in_progress", "request_counts": { "canceled": 10, "errored": 30, "expired": 10, "processing": 100, "succeeded": 50 }, "results_url": "https://api.anthropic.com/v1/messages/batches/msgbatch_013Zva2CMHLNnXjNJJKqJ2EF/results", "type": "message_batch" } ``` ## Retrieve a Message Batch `client.beta.messages.batches.retrieve(stringmessageBatchID, BatchRetrieveParamsparams?, RequestOptionsoptions?): BetaMessageBatch` **get** `/v1/messages/batches/{message_batch_id}` This endpoint is idempotent and can be used to poll for Message Batch completion. To access the results of a Message Batch, make a request to the `results_url` field in the response. Learn more about the Message Batches API in our [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing) ### Parameters - `messageBatchID: string` ID of the Message Batch. - `params: BatchRetrieveParams` - `betas?: Array` Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaMessageBatch` - `id: string` Unique object identifier. The format and length of IDs may change over time. - `archived_at: string | null` RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable. - `cancel_initiated_at: string | null` RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated. - `created_at: string` RFC 3339 datetime string representing the time at which the Message Batch was created. - `ended_at: string | null` RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends. Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired. - `expires_at: string` RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation. - `processing_status: "in_progress" | "canceling" | "ended"` Processing status of the Message Batch. - `"in_progress"` - `"canceling"` - `"ended"` - `request_counts: BetaMessageBatchRequestCounts` Tallies requests within the Message Batch, categorized by their status. Requests start as `processing` and move to one of the other statuses only once processing of the entire batch ends. The sum of all values always matches the total number of requests in the batch. - `canceled: number` Number of requests in the Message Batch that have been canceled. This is zero until processing of the entire Message Batch has ended. - `errored: number` Number of requests in the Message Batch that encountered an error. This is zero until processing of the entire Message Batch has ended. - `expired: number` Number of requests in the Message Batch that have expired. This is zero until processing of the entire Message Batch has ended. - `processing: number` Number of requests in the Message Batch that are processing. - `succeeded: number` Number of requests in the Message Batch that have completed successfully. This is zero until processing of the entire Message Batch has ended. - `results_url: string | null` URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends. Results in the file are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests. - `type: "message_batch"` Object type. For Message Batches, this is always `"message_batch"`. - `"message_batch"` ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const betaMessageBatch = await client.beta.messages.batches.retrieve('message_batch_id'); console.log(betaMessageBatch.id); ``` #### Response ```json { "id": "msgbatch_013Zva2CMHLNnXjNJJKqJ2EF", "archived_at": "2024-08-20T18:37:24.100435Z", "cancel_initiated_at": "2024-08-20T18:37:24.100435Z", "created_at": "2024-08-20T18:37:24.100435Z", "ended_at": "2024-08-20T18:37:24.100435Z", "expires_at": "2024-08-20T18:37:24.100435Z", "processing_status": "in_progress", "request_counts": { "canceled": 10, "errored": 30, "expired": 10, "processing": 100, "succeeded": 50 }, "results_url": "https://api.anthropic.com/v1/messages/batches/msgbatch_013Zva2CMHLNnXjNJJKqJ2EF/results", "type": "message_batch" } ``` ## List Message Batches `client.beta.messages.batches.list(BatchListParamsparams?, RequestOptionsoptions?): Page` **get** `/v1/messages/batches` List all Message Batches within a Workspace. Most recently created batches are returned first. Learn more about the Message Batches API in our [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing) ### Parameters - `params: BatchListParams` - `after_id?: string` Query param: ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object. - `before_id?: string` Query param: ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object. - `limit?: number` Query param: Number of items to return per page. Defaults to `20`. Ranges from `1` to `1000`. - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaMessageBatch` - `id: string` Unique object identifier. The format and length of IDs may change over time. - `archived_at: string | null` RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable. - `cancel_initiated_at: string | null` RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated. - `created_at: string` RFC 3339 datetime string representing the time at which the Message Batch was created. - `ended_at: string | null` RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends. Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired. - `expires_at: string` RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation. - `processing_status: "in_progress" | "canceling" | "ended"` Processing status of the Message Batch. - `"in_progress"` - `"canceling"` - `"ended"` - `request_counts: BetaMessageBatchRequestCounts` Tallies requests within the Message Batch, categorized by their status. Requests start as `processing` and move to one of the other statuses only once processing of the entire batch ends. The sum of all values always matches the total number of requests in the batch. - `canceled: number` Number of requests in the Message Batch that have been canceled. This is zero until processing of the entire Message Batch has ended. - `errored: number` Number of requests in the Message Batch that encountered an error. This is zero until processing of the entire Message Batch has ended. - `expired: number` Number of requests in the Message Batch that have expired. This is zero until processing of the entire Message Batch has ended. - `processing: number` Number of requests in the Message Batch that are processing. - `succeeded: number` Number of requests in the Message Batch that have completed successfully. This is zero until processing of the entire Message Batch has ended. - `results_url: string | null` URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends. Results in the file are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests. - `type: "message_batch"` Object type. For Message Batches, this is always `"message_batch"`. - `"message_batch"` ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); // Automatically fetches more pages as needed. for await (const betaMessageBatch of client.beta.messages.batches.list()) { console.log(betaMessageBatch.id); } ``` #### Response ```json { "data": [ { "id": "msgbatch_013Zva2CMHLNnXjNJJKqJ2EF", "archived_at": "2024-08-20T18:37:24.100435Z", "cancel_initiated_at": "2024-08-20T18:37:24.100435Z", "created_at": "2024-08-20T18:37:24.100435Z", "ended_at": "2024-08-20T18:37:24.100435Z", "expires_at": "2024-08-20T18:37:24.100435Z", "processing_status": "in_progress", "request_counts": { "canceled": 10, "errored": 30, "expired": 10, "processing": 100, "succeeded": 50 }, "results_url": "https://api.anthropic.com/v1/messages/batches/msgbatch_013Zva2CMHLNnXjNJJKqJ2EF/results", "type": "message_batch" } ], "first_id": "first_id", "has_more": true, "last_id": "last_id" } ``` ## Cancel a Message Batch `client.beta.messages.batches.cancel(stringmessageBatchID, BatchCancelParamsparams?, RequestOptionsoptions?): BetaMessageBatch` **post** `/v1/messages/batches/{message_batch_id}/cancel` Batches may be canceled any time before processing ends. Once cancellation is initiated, the batch enters a `canceling` state, at which time the system may complete any in-progress, non-interruptible requests before finalizing cancellation. The number of canceled requests is specified in `request_counts`. To determine which requests were canceled, check the individual results within the batch. Note that cancellation may not result in any canceled requests if they were non-interruptible. Learn more about the Message Batches API in our [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing) ### Parameters - `messageBatchID: string` ID of the Message Batch. - `params: BatchCancelParams` - `betas?: Array` Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaMessageBatch` - `id: string` Unique object identifier. The format and length of IDs may change over time. - `archived_at: string | null` RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable. - `cancel_initiated_at: string | null` RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated. - `created_at: string` RFC 3339 datetime string representing the time at which the Message Batch was created. - `ended_at: string | null` RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends. Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired. - `expires_at: string` RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation. - `processing_status: "in_progress" | "canceling" | "ended"` Processing status of the Message Batch. - `"in_progress"` - `"canceling"` - `"ended"` - `request_counts: BetaMessageBatchRequestCounts` Tallies requests within the Message Batch, categorized by their status. Requests start as `processing` and move to one of the other statuses only once processing of the entire batch ends. The sum of all values always matches the total number of requests in the batch. - `canceled: number` Number of requests in the Message Batch that have been canceled. This is zero until processing of the entire Message Batch has ended. - `errored: number` Number of requests in the Message Batch that encountered an error. This is zero until processing of the entire Message Batch has ended. - `expired: number` Number of requests in the Message Batch that have expired. This is zero until processing of the entire Message Batch has ended. - `processing: number` Number of requests in the Message Batch that are processing. - `succeeded: number` Number of requests in the Message Batch that have completed successfully. This is zero until processing of the entire Message Batch has ended. - `results_url: string | null` URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends. Results in the file are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests. - `type: "message_batch"` Object type. For Message Batches, this is always `"message_batch"`. - `"message_batch"` ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const betaMessageBatch = await client.beta.messages.batches.cancel('message_batch_id'); console.log(betaMessageBatch.id); ``` #### Response ```json { "id": "msgbatch_013Zva2CMHLNnXjNJJKqJ2EF", "archived_at": "2024-08-20T18:37:24.100435Z", "cancel_initiated_at": "2024-08-20T18:37:24.100435Z", "created_at": "2024-08-20T18:37:24.100435Z", "ended_at": "2024-08-20T18:37:24.100435Z", "expires_at": "2024-08-20T18:37:24.100435Z", "processing_status": "in_progress", "request_counts": { "canceled": 10, "errored": 30, "expired": 10, "processing": 100, "succeeded": 50 }, "results_url": "https://api.anthropic.com/v1/messages/batches/msgbatch_013Zva2CMHLNnXjNJJKqJ2EF/results", "type": "message_batch" } ``` ## Delete a Message Batch `client.beta.messages.batches.delete(stringmessageBatchID, BatchDeleteParamsparams?, RequestOptionsoptions?): BetaDeletedMessageBatch` **delete** `/v1/messages/batches/{message_batch_id}` Delete a Message Batch. Message Batches can only be deleted once they've finished processing. If you'd like to delete an in-progress batch, you must first cancel it. Learn more about the Message Batches API in our [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing) ### Parameters - `messageBatchID: string` ID of the Message Batch. - `params: BatchDeleteParams` - `betas?: Array` Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaDeletedMessageBatch` - `id: string` ID of the Message Batch. - `type: "message_batch_deleted"` Deleted object type. For Message Batches, this is always `"message_batch_deleted"`. - `"message_batch_deleted"` ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const betaDeletedMessageBatch = await client.beta.messages.batches.delete('message_batch_id'); console.log(betaDeletedMessageBatch.id); ``` #### Response ```json { "id": "msgbatch_013Zva2CMHLNnXjNJJKqJ2EF", "type": "message_batch_deleted" } ``` ## Retrieve Message Batch results `client.beta.messages.batches.results(stringmessageBatchID, BatchResultsParamsparams?, RequestOptionsoptions?): BetaMessageBatchIndividualResponse | Stream` **get** `/v1/messages/batches/{message_batch_id}/results` Streams the results of a Message Batch as a `.jsonl` file. Each line in the file is a JSON object containing the result of a single request in the Message Batch. Results are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests. Learn more about the Message Batches API in our [user guide](https://docs.claude.com/en/docs/build-with-claude/batch-processing) ### Parameters - `messageBatchID: string` ID of the Message Batch. - `params: BatchResultsParams` - `betas?: Array` Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaMessageBatchIndividualResponse` This is a single line in the response `.jsonl` file and does not represent the response as a whole. - `custom_id: string` Developer-provided ID created for each request in a Message Batch. Useful for matching results to requests, as results may be given out of request order. Must be unique for each request within the Message Batch. - `result: BetaMessageBatchResult` Processing result for this request. Contains a Message output if processing was successful, an error response if processing failed, or the reason why processing was not attempted, such as cancellation or expiration. - `BetaMessageBatchSucceededResult` - `message: BetaMessage` - `id: string` Unique object identifier. The format and length of IDs may change over time. - `container: BetaContainer | null` 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 | 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) - `"anthropic"` - `"custom"` - `version: string` Skill version or 'latest' for most recent version - `content: Array` Content generated by the model. This is an array of content blocks, each of which has a `type` that determines its shape. Example: ```json [{"type": "text", "text": "Hi, I'm Claude."}] ``` If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. For example, if the input `messages` were: ```json [ {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, {"role": "assistant", "content": "The best answer is ("} ] ``` Then the response `content` might be: ```json [{"type": "text", "text": "B)"}] ``` - `BetaTextBlock` - `citations: Array | 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`. - `BetaCitationCharLocation` - `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"` - `"char_location"` - `BetaCitationPageLocation` - `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"` - `"page_location"` - `BetaCitationContentBlockLocation` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `document_index: number` - `document_title: string | null` - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `file_id: string | null` - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. - `type: "content_block_location"` - `"content_block_location"` - `BetaCitationsWebSearchResultLocation` - `cited_text: string` - `encrypted_index: string` - `title: string | null` - `type: "web_search_result_location"` - `"web_search_result_location"` - `url: string` - `BetaCitationSearchResultLocation` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `search_result_index: number` 0-based index of the cited search result among all `search_result` content blocks in the request, in the order they appear across messages and tool results. Counted separately from `document_index`; server-side web search results are not included in this count. - `source: string` - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. - `title: string | null` - `type: "search_result_location"` - `"search_result_location"` - `text: string` - `type: "text"` - `"text"` - `BetaThinkingBlock` - `signature: string` - `thinking: string` - `type: "thinking"` - `"thinking"` - `BetaRedactedThinkingBlock` - `data: string` - `type: "redacted_thinking"` - `"redacted_thinking"` - `BetaToolUseBlock` - `id: string` - `input: Record` - `name: string` - `type: "tool_use"` - `"tool_use"` - `caller?: BetaDirectCaller | BetaServerToolCaller | BetaServerToolCaller20260120` Tool invocation directly from the model. - `BetaDirectCaller` Tool invocation directly from the model. - `type: "direct"` - `"direct"` - `BetaServerToolCaller` Tool invocation generated by a server-side tool. - `tool_id: string` - `type: "code_execution_20250825"` - `"code_execution_20250825"` - `BetaServerToolCaller20260120` - `tool_id: string` - `type: "code_execution_20260120"` - `"code_execution_20260120"` - `BetaServerToolUseBlock` - `id: string` - `input: Record` - `name: "advisor" | "web_search" | "web_fetch" | 5 more` - `"advisor"` - `"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"` - `"server_tool_use"` - `caller?: BetaDirectCaller | BetaServerToolCaller | BetaServerToolCaller20260120` Tool invocation directly from the model. - `BetaDirectCaller` Tool invocation directly from the model. - `BetaServerToolCaller` Tool invocation generated by a server-side tool. - `BetaServerToolCaller20260120` - `BetaWebSearchToolResultBlock` - `content: BetaWebSearchToolResultBlockContent` - `BetaWebSearchToolResultError` - `error_code: BetaWebSearchToolResultErrorCode` - `"invalid_tool_input"` - `"unavailable"` - `"max_uses_exceeded"` - `"too_many_requests"` - `"query_too_long"` - `"request_too_large"` - `type: "web_search_tool_result_error"` - `"web_search_tool_result_error"` - `Array` - `encrypted_content: string` - `page_age: string | null` - `title: string` - `type: "web_search_result"` - `"web_search_result"` - `url: string` - `tool_use_id: string` - `type: "web_search_tool_result"` - `"web_search_tool_result"` - `caller?: BetaDirectCaller | BetaServerToolCaller | BetaServerToolCaller20260120` Tool invocation directly from the model. - `BetaDirectCaller` Tool invocation directly from the model. - `BetaServerToolCaller` Tool invocation generated by a server-side tool. - `BetaServerToolCaller20260120` - `BetaWebFetchToolResultBlock` - `content: BetaWebFetchToolResultErrorBlock | BetaWebFetchBlock` - `BetaWebFetchToolResultErrorBlock` - `error_code: BetaWebFetchToolResultErrorCode` - `"invalid_tool_input"` - `"url_too_long"` - `"url_not_allowed"` - `"url_not_in_prior_context"` - `"url_not_accessible"` - `"unsupported_content_type"` - `"too_many_requests"` - `"max_uses_exceeded"` - `"unavailable"` - `type: "web_fetch_tool_result_error"` - `"web_fetch_tool_result_error"` - `BetaWebFetchBlock` - `content: BetaDocumentBlock` - `citations: BetaCitationConfig | null` Citation configuration for the document - `enabled: boolean` - `source: BetaBase64PDFSource | BetaPlainTextSource` - `BetaBase64PDFSource` - `data: string` - `media_type: "application/pdf"` - `"application/pdf"` - `type: "base64"` - `"base64"` - `BetaPlainTextSource` - `data: string` - `media_type: "text/plain"` - `"text/plain"` - `type: "text"` - `"text"` - `title: string | null` The title of the document - `type: "document"` - `"document"` - `retrieved_at: string | null` ISO 8601 timestamp when the content was retrieved - `type: "web_fetch_result"` - `"web_fetch_result"` - `url: string` Fetched content URL - `tool_use_id: string` - `type: "web_fetch_tool_result"` - `"web_fetch_tool_result"` - `caller?: BetaDirectCaller | BetaServerToolCaller | BetaServerToolCaller20260120` Tool invocation directly from the model. - `BetaDirectCaller` Tool invocation directly from the model. - `BetaServerToolCaller` Tool invocation generated by a server-side tool. - `BetaServerToolCaller20260120` - `BetaAdvisorToolResultBlock` - `content: BetaAdvisorToolResultError | BetaAdvisorResultBlock | BetaAdvisorRedactedResultBlock` - `BetaAdvisorToolResultError` - `error_code: "max_uses_exceeded" | "prompt_too_long" | "too_many_requests" | 3 more` - `"max_uses_exceeded"` - `"prompt_too_long"` - `"too_many_requests"` - `"overloaded"` - `"unavailable"` - `"execution_time_exceeded"` - `type: "advisor_tool_result_error"` - `"advisor_tool_result_error"` - `BetaAdvisorResultBlock` - `stop_reason: string | null` The advisor sub-inference's stop reason (same values as the top-level message `stop_reason`). `max_tokens` indicates the advisor's output was truncated at the tool's `max_tokens` value or the advisor model's policy cap. - `text: string` - `type: "advisor_result"` - `"advisor_result"` - `BetaAdvisorRedactedResultBlock` - `encrypted_content: string` Opaque blob containing the advisor's output. Round-trip verbatim; do not inspect or modify. - `stop_reason: string | null` The advisor sub-inference's stop reason (same values as the top-level message `stop_reason`). - `type: "advisor_redacted_result"` - `"advisor_redacted_result"` - `tool_use_id: string` - `type: "advisor_tool_result"` - `"advisor_tool_result"` - `BetaCodeExecutionToolResultBlock` - `content: BetaCodeExecutionToolResultBlockContent` Code execution result with encrypted stdout for PFC + web_search results. - `BetaCodeExecutionToolResultError` - `error_code: BetaCodeExecutionToolResultErrorCode` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `type: "code_execution_tool_result_error"` - `"code_execution_tool_result_error"` - `BetaCodeExecutionResultBlock` - `content: Array` - `file_id: string` - `type: "code_execution_output"` - `"code_execution_output"` - `return_code: number` - `stderr: string` - `stdout: string` - `type: "code_execution_result"` - `"code_execution_result"` - `BetaEncryptedCodeExecutionResultBlock` Code execution result with encrypted stdout for PFC + web_search results. - `content: Array` - `file_id: string` - `type: "code_execution_output"` - `encrypted_stdout: string` - `return_code: number` - `stderr: string` - `type: "encrypted_code_execution_result"` - `"encrypted_code_execution_result"` - `tool_use_id: string` - `type: "code_execution_tool_result"` - `"code_execution_tool_result"` - `BetaBashCodeExecutionToolResultBlock` - `content: BetaBashCodeExecutionToolResultError | BetaBashCodeExecutionResultBlock` - `BetaBashCodeExecutionToolResultError` - `error_code: "invalid_tool_input" | "unavailable" | "too_many_requests" | 2 more` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `"output_file_too_large"` - `type: "bash_code_execution_tool_result_error"` - `"bash_code_execution_tool_result_error"` - `BetaBashCodeExecutionResultBlock` - `content: Array` - `file_id: string` - `type: "bash_code_execution_output"` - `"bash_code_execution_output"` - `return_code: number` - `stderr: string` - `stdout: string` - `type: "bash_code_execution_result"` - `"bash_code_execution_result"` - `tool_use_id: string` - `type: "bash_code_execution_tool_result"` - `"bash_code_execution_tool_result"` - `BetaTextEditorCodeExecutionToolResultBlock` - `content: BetaTextEditorCodeExecutionToolResultError | BetaTextEditorCodeExecutionViewResultBlock | BetaTextEditorCodeExecutionCreateResultBlock | BetaTextEditorCodeExecutionStrReplaceResultBlock` - `BetaTextEditorCodeExecutionToolResultError` - `error_code: "invalid_tool_input" | "unavailable" | "too_many_requests" | 2 more` - `"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"` - `"text_editor_code_execution_tool_result_error"` - `BetaTextEditorCodeExecutionViewResultBlock` - `content: string` - `file_type: "text" | "image" | "pdf"` - `"text"` - `"image"` - `"pdf"` - `num_lines: number | null` - `start_line: number | null` - `total_lines: number | null` - `type: "text_editor_code_execution_view_result"` - `"text_editor_code_execution_view_result"` - `BetaTextEditorCodeExecutionCreateResultBlock` - `is_file_update: boolean` - `type: "text_editor_code_execution_create_result"` - `"text_editor_code_execution_create_result"` - `BetaTextEditorCodeExecutionStrReplaceResultBlock` - `lines: Array | 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"` - `"text_editor_code_execution_str_replace_result"` - `tool_use_id: string` - `type: "text_editor_code_execution_tool_result"` - `"text_editor_code_execution_tool_result"` - `BetaToolSearchToolResultBlock` - `content: BetaToolSearchToolResultError | BetaToolSearchToolSearchResultBlock` - `BetaToolSearchToolResultError` - `error_code: "invalid_tool_input" | "unavailable" | "too_many_requests" | "execution_time_exceeded"` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `error_message: string | null` - `type: "tool_search_tool_result_error"` - `"tool_search_tool_result_error"` - `BetaToolSearchToolSearchResultBlock` - `tool_references: Array` - `tool_name: string` - `type: "tool_reference"` - `"tool_reference"` - `type: "tool_search_tool_search_result"` - `"tool_search_tool_search_result"` - `tool_use_id: string` - `type: "tool_search_tool_result"` - `"tool_search_tool_result"` - `BetaMCPToolUseBlock` - `id: string` - `input: Record` - `name: string` The name of the MCP tool - `server_name: string` The name of the MCP server - `type: "mcp_tool_use"` - `"mcp_tool_use"` - `BetaMCPToolResultBlock` - `content: string | Array` - `string` - `Array` - `citations: Array | 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`. - `text: string` - `type: "text"` - `is_error: boolean` - `tool_use_id: string` - `type: "mcp_tool_result"` - `"mcp_tool_result"` - `BetaContainerUploadBlock` Response model for a file uploaded to the container. - `file_id: string` - `type: "container_upload"` - `"container_upload"` - `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. - `content: string | null` Summary of compacted content, or null if compaction failed - `encrypted_content: string | null` Opaque metadata from prior compaction, to be round-tripped verbatim - `type: "compaction"` - `"compaction"` - `context_management: BetaContextManagementResponse | null` Context management response. Information about context management strategies applied during the request. - `applied_edits: Array` List of context management edits that were applied. - `BetaClearToolUses20250919EditResponse` - `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. - `"clear_tool_uses_20250919"` - `BetaClearThinking20251015EditResponse` - `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. - `"clear_thinking_20251015"` - `diagnostics: BetaDiagnostics | null` Response envelope for request-level diagnostics. Present (possibly null) whenever the caller supplied `diagnostics` on the request. - `cache_miss_reason: BetaCacheMissModelChanged | BetaCacheMissSystemChanged | BetaCacheMissToolsChanged | 3 more | null` Explains why the prompt cache could not fully reuse the prefix from the request identified by `diagnostics.previous_message_id`. `null` means diagnosis is still pending — the response was serialized before the background comparison completed. - `BetaCacheMissModelChanged` - `cache_missed_input_tokens: number` Approximate number of input tokens that would have been read from cache had the prefix matched the previous request. - `type: "model_changed"` - `"model_changed"` - `BetaCacheMissSystemChanged` - `cache_missed_input_tokens: number` Approximate number of input tokens that would have been read from cache had the prefix matched the previous request. - `type: "system_changed"` - `"system_changed"` - `BetaCacheMissToolsChanged` - `cache_missed_input_tokens: number` Approximate number of input tokens that would have been read from cache had the prefix matched the previous request. - `type: "tools_changed"` - `"tools_changed"` - `BetaCacheMissMessagesChanged` - `cache_missed_input_tokens: number` Approximate number of input tokens that would have been read from cache had the prefix matched the previous request. - `type: "messages_changed"` - `"messages_changed"` - `BetaCacheMissPreviousMessageNotFound` - `type: "previous_message_not_found"` - `"previous_message_not_found"` - `BetaCacheMissUnavailable` - `type: "unavailable"` - `"unavailable"` - `model: Model` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-opus-4-8" | "claude-opus-4-7" | "claude-mythos-preview" | 15 more` - `"claude-opus-4-8"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-7"` Frontier intelligence for long-running agents and coding - `"claude-mythos-preview"` New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` Fastest model with near-frontier intelligence - `"claude-haiku-4-5-20251001"` Fastest model with near-frontier intelligence - `"claude-opus-4-5"` Premium model combining maximum intelligence with practical performance - `"claude-opus-4-5-20251101"` Premium model combining maximum intelligence with practical performance - `"claude-sonnet-4-5"` High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` High-performance model for agents and coding - `"claude-opus-4-1"` Exceptional model for specialized complex tasks - `"claude-opus-4-1-20250805"` Exceptional model for specialized complex tasks - `"claude-opus-4-0"` Powerful model for complex tasks - `"claude-opus-4-20250514"` Powerful model for complex tasks - `"claude-sonnet-4-0"` High-performance model with extended thinking - `"claude-sonnet-4-20250514"` High-performance model with extended thinking - `"claude-3-haiku-20240307"` Fast and cost-effective model - `(string & {})` - `role: "assistant"` Conversational role of the generated message. This will always be `"assistant"`. - `"assistant"` - `stop_details: BetaRefusalStopDetails | null` Structured information about a refusal. - `category: "cyber" | "bio" | null` The policy category that triggered the refusal. `null` when the refusal doesn't map to a named category. - `"cyber"` - `"bio"` - `explanation: string | null` Human-readable explanation of the refusal. This text is not guaranteed to be stable. `null` when no explanation is available for the category. - `type: "refusal"` - `"refusal"` - `stop_reason: BetaStopReason | null` The reason that we stopped. This may be one the following values: * `"end_turn"`: the model reached a natural stopping point * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated * `"tool_use"`: the model invoked one or more tools * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. * `"refusal"`: when streaming classifiers intervene to handle potential policy violations In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. - `"end_turn"` - `"max_tokens"` - `"stop_sequence"` - `"tool_use"` - `"pause_turn"` - `"compaction"` - `"refusal"` - `"model_context_window_exceeded"` - `stop_sequence: string | null` Which custom stop sequence was generated, if any. This value will be a non-null string if one of your custom stop sequences was generated. - `type: "message"` Object type. For Messages, this is always `"message"`. - `"message"` - `usage: BetaUsage` Billing and rate-limit usage. Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. For example, `output_tokens` will be non-zero, even for an empty string response from Claude. Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. - `cache_creation: BetaCacheCreation | null` Breakdown of cached tokens by TTL - `ephemeral_1h_input_tokens: number` The number of input tokens used to create the 1 hour cache entry. - `ephemeral_5m_input_tokens: number` The number of input tokens used to create the 5 minute cache entry. - `cache_creation_input_tokens: number | null` The number of input tokens used to create the cache entry. - `cache_read_input_tokens: number | null` The number of input tokens read from the cache. - `inference_geo: string | null` The geographic region where inference was performed for this request. - `input_tokens: number` The number of input tokens which were used. - `iterations: BetaIterationsUsage | null` Per-iteration token usage breakdown. Each entry represents one sampling iteration, with its own input/output token counts and cache statistics. This allows you to: - Determine which iterations exceeded long context thresholds (>=200k tokens) - Calculate the true context window size from the last iteration - Understand token accumulation across server-side tool use loops - `BetaMessageIterationUsage` Token usage for a sampling iteration. - `cache_creation: BetaCacheCreation | null` Breakdown of cached tokens by TTL - `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: "message"` Usage for a sampling iteration - `"message"` - `BetaCompactionIterationUsage` Token usage for a compaction iteration. - `cache_creation: BetaCacheCreation | null` Breakdown of cached tokens by TTL - `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 - `"compaction"` - `BetaAdvisorMessageIterationUsage` Token usage for an advisor sub-inference iteration. - `cache_creation: BetaCacheCreation | null` Breakdown of cached tokens by TTL - `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. - `model: Model` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `output_tokens: number` The number of output tokens which were used. - `type: "advisor_message"` Usage for an advisor sub-inference iteration - `"advisor_message"` - `output_tokens: number` The number of output tokens which were used. - `output_tokens_details: BetaOutputTokensDetails | null` Breakdown of output tokens by category. `output_tokens` remains the inclusive, authoritative total used for billing. This object provides a read-only decomposition for observability — for example, how many of the billed output tokens were spent on internal reasoning that may have been summarized before being returned to you. - `thinking_tokens: number` Number of output tokens the model generated as internal reasoning, including the thinking-block delimiter tokens. Reflects the raw reasoning the model produced, not the (possibly shorter) summarized thinking text returned in the response body. Computed by re-tokenizing the raw reasoning text, so it may differ from the model's exact generation count by a small number of tokens. Always ≤ `output_tokens`; `output_tokens - thinking_tokens` approximates the non-reasoning output. - `server_tool_use: BetaServerToolUsage | null` The number of server tool requests. - `web_fetch_requests: number` The number of web fetch tool requests. - `web_search_requests: number` The number of web search tool requests. - `service_tier: "standard" | "priority" | "batch" | null` If the request used the priority, standard, or batch tier. - `"standard"` - `"priority"` - `"batch"` - `speed: "standard" | "fast" | null` The inference speed mode used for this request. - `"standard"` - `"fast"` - `type: "succeeded"` - `"succeeded"` - `BetaMessageBatchErroredResult` - `error: BetaErrorResponse` - `error: BetaError` - `BetaInvalidRequestError` - `message: string` - `type: "invalid_request_error"` - `"invalid_request_error"` - `BetaAuthenticationError` - `message: string` - `type: "authentication_error"` - `"authentication_error"` - `BetaBillingError` - `message: string` - `type: "billing_error"` - `"billing_error"` - `BetaPermissionError` - `message: string` - `type: "permission_error"` - `"permission_error"` - `BetaNotFoundError` - `message: string` - `type: "not_found_error"` - `"not_found_error"` - `BetaRateLimitError` - `message: string` - `type: "rate_limit_error"` - `"rate_limit_error"` - `BetaGatewayTimeoutError` - `message: string` - `type: "timeout_error"` - `"timeout_error"` - `BetaAPIError` - `message: string` - `type: "api_error"` - `"api_error"` - `BetaOverloadedError` - `message: string` - `type: "overloaded_error"` - `"overloaded_error"` - `request_id: string | null` - `type: "error"` - `"error"` - `type: "errored"` - `"errored"` - `BetaMessageBatchCanceledResult` - `type: "canceled"` - `"canceled"` - `BetaMessageBatchExpiredResult` - `type: "expired"` - `"expired"` ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const betaMessageBatchIndividualResponse = await client.beta.messages.batches.results( 'message_batch_id', ); console.log(betaMessageBatchIndividualResponse.custom_id); ``` ## Domain Types ### Beta Deleted Message Batch - `BetaDeletedMessageBatch` - `id: string` ID of the Message Batch. - `type: "message_batch_deleted"` Deleted object type. For Message Batches, this is always `"message_batch_deleted"`. - `"message_batch_deleted"` ### Beta Message Batch - `BetaMessageBatch` - `id: string` Unique object identifier. The format and length of IDs may change over time. - `archived_at: string | null` RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable. - `cancel_initiated_at: string | null` RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated. - `created_at: string` RFC 3339 datetime string representing the time at which the Message Batch was created. - `ended_at: string | null` RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends. Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired. - `expires_at: string` RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation. - `processing_status: "in_progress" | "canceling" | "ended"` Processing status of the Message Batch. - `"in_progress"` - `"canceling"` - `"ended"` - `request_counts: BetaMessageBatchRequestCounts` Tallies requests within the Message Batch, categorized by their status. Requests start as `processing` and move to one of the other statuses only once processing of the entire batch ends. The sum of all values always matches the total number of requests in the batch. - `canceled: number` Number of requests in the Message Batch that have been canceled. This is zero until processing of the entire Message Batch has ended. - `errored: number` Number of requests in the Message Batch that encountered an error. This is zero until processing of the entire Message Batch has ended. - `expired: number` Number of requests in the Message Batch that have expired. This is zero until processing of the entire Message Batch has ended. - `processing: number` Number of requests in the Message Batch that are processing. - `succeeded: number` Number of requests in the Message Batch that have completed successfully. This is zero until processing of the entire Message Batch has ended. - `results_url: string | null` URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends. Results in the file are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests. - `type: "message_batch"` Object type. For Message Batches, this is always `"message_batch"`. - `"message_batch"` ### Beta Message Batch Canceled Result - `BetaMessageBatchCanceledResult` - `type: "canceled"` - `"canceled"` ### Beta Message Batch Errored Result - `BetaMessageBatchErroredResult` - `error: BetaErrorResponse` - `error: BetaError` - `BetaInvalidRequestError` - `message: string` - `type: "invalid_request_error"` - `"invalid_request_error"` - `BetaAuthenticationError` - `message: string` - `type: "authentication_error"` - `"authentication_error"` - `BetaBillingError` - `message: string` - `type: "billing_error"` - `"billing_error"` - `BetaPermissionError` - `message: string` - `type: "permission_error"` - `"permission_error"` - `BetaNotFoundError` - `message: string` - `type: "not_found_error"` - `"not_found_error"` - `BetaRateLimitError` - `message: string` - `type: "rate_limit_error"` - `"rate_limit_error"` - `BetaGatewayTimeoutError` - `message: string` - `type: "timeout_error"` - `"timeout_error"` - `BetaAPIError` - `message: string` - `type: "api_error"` - `"api_error"` - `BetaOverloadedError` - `message: string` - `type: "overloaded_error"` - `"overloaded_error"` - `request_id: string | null` - `type: "error"` - `"error"` - `type: "errored"` - `"errored"` ### Beta Message Batch Expired Result - `BetaMessageBatchExpiredResult` - `type: "expired"` - `"expired"` ### Beta Message Batch Individual Response - `BetaMessageBatchIndividualResponse` This is a single line in the response `.jsonl` file and does not represent the response as a whole. - `custom_id: string` Developer-provided ID created for each request in a Message Batch. Useful for matching results to requests, as results may be given out of request order. Must be unique for each request within the Message Batch. - `result: BetaMessageBatchResult` Processing result for this request. Contains a Message output if processing was successful, an error response if processing failed, or the reason why processing was not attempted, such as cancellation or expiration. - `BetaMessageBatchSucceededResult` - `message: BetaMessage` - `id: string` Unique object identifier. The format and length of IDs may change over time. - `container: BetaContainer | null` 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 | 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) - `"anthropic"` - `"custom"` - `version: string` Skill version or 'latest' for most recent version - `content: Array` Content generated by the model. This is an array of content blocks, each of which has a `type` that determines its shape. Example: ```json [{"type": "text", "text": "Hi, I'm Claude."}] ``` If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. For example, if the input `messages` were: ```json [ {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, {"role": "assistant", "content": "The best answer is ("} ] ``` Then the response `content` might be: ```json [{"type": "text", "text": "B)"}] ``` - `BetaTextBlock` - `citations: Array | 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`. - `BetaCitationCharLocation` - `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"` - `"char_location"` - `BetaCitationPageLocation` - `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"` - `"page_location"` - `BetaCitationContentBlockLocation` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `document_index: number` - `document_title: string | null` - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `file_id: string | null` - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. - `type: "content_block_location"` - `"content_block_location"` - `BetaCitationsWebSearchResultLocation` - `cited_text: string` - `encrypted_index: string` - `title: string | null` - `type: "web_search_result_location"` - `"web_search_result_location"` - `url: string` - `BetaCitationSearchResultLocation` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `search_result_index: number` 0-based index of the cited search result among all `search_result` content blocks in the request, in the order they appear across messages and tool results. Counted separately from `document_index`; server-side web search results are not included in this count. - `source: string` - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. - `title: string | null` - `type: "search_result_location"` - `"search_result_location"` - `text: string` - `type: "text"` - `"text"` - `BetaThinkingBlock` - `signature: string` - `thinking: string` - `type: "thinking"` - `"thinking"` - `BetaRedactedThinkingBlock` - `data: string` - `type: "redacted_thinking"` - `"redacted_thinking"` - `BetaToolUseBlock` - `id: string` - `input: Record` - `name: string` - `type: "tool_use"` - `"tool_use"` - `caller?: BetaDirectCaller | BetaServerToolCaller | BetaServerToolCaller20260120` Tool invocation directly from the model. - `BetaDirectCaller` Tool invocation directly from the model. - `type: "direct"` - `"direct"` - `BetaServerToolCaller` Tool invocation generated by a server-side tool. - `tool_id: string` - `type: "code_execution_20250825"` - `"code_execution_20250825"` - `BetaServerToolCaller20260120` - `tool_id: string` - `type: "code_execution_20260120"` - `"code_execution_20260120"` - `BetaServerToolUseBlock` - `id: string` - `input: Record` - `name: "advisor" | "web_search" | "web_fetch" | 5 more` - `"advisor"` - `"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"` - `"server_tool_use"` - `caller?: BetaDirectCaller | BetaServerToolCaller | BetaServerToolCaller20260120` Tool invocation directly from the model. - `BetaDirectCaller` Tool invocation directly from the model. - `BetaServerToolCaller` Tool invocation generated by a server-side tool. - `BetaServerToolCaller20260120` - `BetaWebSearchToolResultBlock` - `content: BetaWebSearchToolResultBlockContent` - `BetaWebSearchToolResultError` - `error_code: BetaWebSearchToolResultErrorCode` - `"invalid_tool_input"` - `"unavailable"` - `"max_uses_exceeded"` - `"too_many_requests"` - `"query_too_long"` - `"request_too_large"` - `type: "web_search_tool_result_error"` - `"web_search_tool_result_error"` - `Array` - `encrypted_content: string` - `page_age: string | null` - `title: string` - `type: "web_search_result"` - `"web_search_result"` - `url: string` - `tool_use_id: string` - `type: "web_search_tool_result"` - `"web_search_tool_result"` - `caller?: BetaDirectCaller | BetaServerToolCaller | BetaServerToolCaller20260120` Tool invocation directly from the model. - `BetaDirectCaller` Tool invocation directly from the model. - `BetaServerToolCaller` Tool invocation generated by a server-side tool. - `BetaServerToolCaller20260120` - `BetaWebFetchToolResultBlock` - `content: BetaWebFetchToolResultErrorBlock | BetaWebFetchBlock` - `BetaWebFetchToolResultErrorBlock` - `error_code: BetaWebFetchToolResultErrorCode` - `"invalid_tool_input"` - `"url_too_long"` - `"url_not_allowed"` - `"url_not_in_prior_context"` - `"url_not_accessible"` - `"unsupported_content_type"` - `"too_many_requests"` - `"max_uses_exceeded"` - `"unavailable"` - `type: "web_fetch_tool_result_error"` - `"web_fetch_tool_result_error"` - `BetaWebFetchBlock` - `content: BetaDocumentBlock` - `citations: BetaCitationConfig | null` Citation configuration for the document - `enabled: boolean` - `source: BetaBase64PDFSource | BetaPlainTextSource` - `BetaBase64PDFSource` - `data: string` - `media_type: "application/pdf"` - `"application/pdf"` - `type: "base64"` - `"base64"` - `BetaPlainTextSource` - `data: string` - `media_type: "text/plain"` - `"text/plain"` - `type: "text"` - `"text"` - `title: string | null` The title of the document - `type: "document"` - `"document"` - `retrieved_at: string | null` ISO 8601 timestamp when the content was retrieved - `type: "web_fetch_result"` - `"web_fetch_result"` - `url: string` Fetched content URL - `tool_use_id: string` - `type: "web_fetch_tool_result"` - `"web_fetch_tool_result"` - `caller?: BetaDirectCaller | BetaServerToolCaller | BetaServerToolCaller20260120` Tool invocation directly from the model. - `BetaDirectCaller` Tool invocation directly from the model. - `BetaServerToolCaller` Tool invocation generated by a server-side tool. - `BetaServerToolCaller20260120` - `BetaAdvisorToolResultBlock` - `content: BetaAdvisorToolResultError | BetaAdvisorResultBlock | BetaAdvisorRedactedResultBlock` - `BetaAdvisorToolResultError` - `error_code: "max_uses_exceeded" | "prompt_too_long" | "too_many_requests" | 3 more` - `"max_uses_exceeded"` - `"prompt_too_long"` - `"too_many_requests"` - `"overloaded"` - `"unavailable"` - `"execution_time_exceeded"` - `type: "advisor_tool_result_error"` - `"advisor_tool_result_error"` - `BetaAdvisorResultBlock` - `stop_reason: string | null` The advisor sub-inference's stop reason (same values as the top-level message `stop_reason`). `max_tokens` indicates the advisor's output was truncated at the tool's `max_tokens` value or the advisor model's policy cap. - `text: string` - `type: "advisor_result"` - `"advisor_result"` - `BetaAdvisorRedactedResultBlock` - `encrypted_content: string` Opaque blob containing the advisor's output. Round-trip verbatim; do not inspect or modify. - `stop_reason: string | null` The advisor sub-inference's stop reason (same values as the top-level message `stop_reason`). - `type: "advisor_redacted_result"` - `"advisor_redacted_result"` - `tool_use_id: string` - `type: "advisor_tool_result"` - `"advisor_tool_result"` - `BetaCodeExecutionToolResultBlock` - `content: BetaCodeExecutionToolResultBlockContent` Code execution result with encrypted stdout for PFC + web_search results. - `BetaCodeExecutionToolResultError` - `error_code: BetaCodeExecutionToolResultErrorCode` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `type: "code_execution_tool_result_error"` - `"code_execution_tool_result_error"` - `BetaCodeExecutionResultBlock` - `content: Array` - `file_id: string` - `type: "code_execution_output"` - `"code_execution_output"` - `return_code: number` - `stderr: string` - `stdout: string` - `type: "code_execution_result"` - `"code_execution_result"` - `BetaEncryptedCodeExecutionResultBlock` Code execution result with encrypted stdout for PFC + web_search results. - `content: Array` - `file_id: string` - `type: "code_execution_output"` - `encrypted_stdout: string` - `return_code: number` - `stderr: string` - `type: "encrypted_code_execution_result"` - `"encrypted_code_execution_result"` - `tool_use_id: string` - `type: "code_execution_tool_result"` - `"code_execution_tool_result"` - `BetaBashCodeExecutionToolResultBlock` - `content: BetaBashCodeExecutionToolResultError | BetaBashCodeExecutionResultBlock` - `BetaBashCodeExecutionToolResultError` - `error_code: "invalid_tool_input" | "unavailable" | "too_many_requests" | 2 more` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `"output_file_too_large"` - `type: "bash_code_execution_tool_result_error"` - `"bash_code_execution_tool_result_error"` - `BetaBashCodeExecutionResultBlock` - `content: Array` - `file_id: string` - `type: "bash_code_execution_output"` - `"bash_code_execution_output"` - `return_code: number` - `stderr: string` - `stdout: string` - `type: "bash_code_execution_result"` - `"bash_code_execution_result"` - `tool_use_id: string` - `type: "bash_code_execution_tool_result"` - `"bash_code_execution_tool_result"` - `BetaTextEditorCodeExecutionToolResultBlock` - `content: BetaTextEditorCodeExecutionToolResultError | BetaTextEditorCodeExecutionViewResultBlock | BetaTextEditorCodeExecutionCreateResultBlock | BetaTextEditorCodeExecutionStrReplaceResultBlock` - `BetaTextEditorCodeExecutionToolResultError` - `error_code: "invalid_tool_input" | "unavailable" | "too_many_requests" | 2 more` - `"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"` - `"text_editor_code_execution_tool_result_error"` - `BetaTextEditorCodeExecutionViewResultBlock` - `content: string` - `file_type: "text" | "image" | "pdf"` - `"text"` - `"image"` - `"pdf"` - `num_lines: number | null` - `start_line: number | null` - `total_lines: number | null` - `type: "text_editor_code_execution_view_result"` - `"text_editor_code_execution_view_result"` - `BetaTextEditorCodeExecutionCreateResultBlock` - `is_file_update: boolean` - `type: "text_editor_code_execution_create_result"` - `"text_editor_code_execution_create_result"` - `BetaTextEditorCodeExecutionStrReplaceResultBlock` - `lines: Array | 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"` - `"text_editor_code_execution_str_replace_result"` - `tool_use_id: string` - `type: "text_editor_code_execution_tool_result"` - `"text_editor_code_execution_tool_result"` - `BetaToolSearchToolResultBlock` - `content: BetaToolSearchToolResultError | BetaToolSearchToolSearchResultBlock` - `BetaToolSearchToolResultError` - `error_code: "invalid_tool_input" | "unavailable" | "too_many_requests" | "execution_time_exceeded"` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `error_message: string | null` - `type: "tool_search_tool_result_error"` - `"tool_search_tool_result_error"` - `BetaToolSearchToolSearchResultBlock` - `tool_references: Array` - `tool_name: string` - `type: "tool_reference"` - `"tool_reference"` - `type: "tool_search_tool_search_result"` - `"tool_search_tool_search_result"` - `tool_use_id: string` - `type: "tool_search_tool_result"` - `"tool_search_tool_result"` - `BetaMCPToolUseBlock` - `id: string` - `input: Record` - `name: string` The name of the MCP tool - `server_name: string` The name of the MCP server - `type: "mcp_tool_use"` - `"mcp_tool_use"` - `BetaMCPToolResultBlock` - `content: string | Array` - `string` - `Array` - `citations: Array | 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`. - `text: string` - `type: "text"` - `is_error: boolean` - `tool_use_id: string` - `type: "mcp_tool_result"` - `"mcp_tool_result"` - `BetaContainerUploadBlock` Response model for a file uploaded to the container. - `file_id: string` - `type: "container_upload"` - `"container_upload"` - `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. - `content: string | null` Summary of compacted content, or null if compaction failed - `encrypted_content: string | null` Opaque metadata from prior compaction, to be round-tripped verbatim - `type: "compaction"` - `"compaction"` - `context_management: BetaContextManagementResponse | null` Context management response. Information about context management strategies applied during the request. - `applied_edits: Array` List of context management edits that were applied. - `BetaClearToolUses20250919EditResponse` - `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. - `"clear_tool_uses_20250919"` - `BetaClearThinking20251015EditResponse` - `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. - `"clear_thinking_20251015"` - `diagnostics: BetaDiagnostics | null` Response envelope for request-level diagnostics. Present (possibly null) whenever the caller supplied `diagnostics` on the request. - `cache_miss_reason: BetaCacheMissModelChanged | BetaCacheMissSystemChanged | BetaCacheMissToolsChanged | 3 more | null` Explains why the prompt cache could not fully reuse the prefix from the request identified by `diagnostics.previous_message_id`. `null` means diagnosis is still pending — the response was serialized before the background comparison completed. - `BetaCacheMissModelChanged` - `cache_missed_input_tokens: number` Approximate number of input tokens that would have been read from cache had the prefix matched the previous request. - `type: "model_changed"` - `"model_changed"` - `BetaCacheMissSystemChanged` - `cache_missed_input_tokens: number` Approximate number of input tokens that would have been read from cache had the prefix matched the previous request. - `type: "system_changed"` - `"system_changed"` - `BetaCacheMissToolsChanged` - `cache_missed_input_tokens: number` Approximate number of input tokens that would have been read from cache had the prefix matched the previous request. - `type: "tools_changed"` - `"tools_changed"` - `BetaCacheMissMessagesChanged` - `cache_missed_input_tokens: number` Approximate number of input tokens that would have been read from cache had the prefix matched the previous request. - `type: "messages_changed"` - `"messages_changed"` - `BetaCacheMissPreviousMessageNotFound` - `type: "previous_message_not_found"` - `"previous_message_not_found"` - `BetaCacheMissUnavailable` - `type: "unavailable"` - `"unavailable"` - `model: Model` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-opus-4-8" | "claude-opus-4-7" | "claude-mythos-preview" | 15 more` - `"claude-opus-4-8"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-7"` Frontier intelligence for long-running agents and coding - `"claude-mythos-preview"` New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` Fastest model with near-frontier intelligence - `"claude-haiku-4-5-20251001"` Fastest model with near-frontier intelligence - `"claude-opus-4-5"` Premium model combining maximum intelligence with practical performance - `"claude-opus-4-5-20251101"` Premium model combining maximum intelligence with practical performance - `"claude-sonnet-4-5"` High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` High-performance model for agents and coding - `"claude-opus-4-1"` Exceptional model for specialized complex tasks - `"claude-opus-4-1-20250805"` Exceptional model for specialized complex tasks - `"claude-opus-4-0"` Powerful model for complex tasks - `"claude-opus-4-20250514"` Powerful model for complex tasks - `"claude-sonnet-4-0"` High-performance model with extended thinking - `"claude-sonnet-4-20250514"` High-performance model with extended thinking - `"claude-3-haiku-20240307"` Fast and cost-effective model - `(string & {})` - `role: "assistant"` Conversational role of the generated message. This will always be `"assistant"`. - `"assistant"` - `stop_details: BetaRefusalStopDetails | null` Structured information about a refusal. - `category: "cyber" | "bio" | null` The policy category that triggered the refusal. `null` when the refusal doesn't map to a named category. - `"cyber"` - `"bio"` - `explanation: string | null` Human-readable explanation of the refusal. This text is not guaranteed to be stable. `null` when no explanation is available for the category. - `type: "refusal"` - `"refusal"` - `stop_reason: BetaStopReason | null` The reason that we stopped. This may be one the following values: * `"end_turn"`: the model reached a natural stopping point * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated * `"tool_use"`: the model invoked one or more tools * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. * `"refusal"`: when streaming classifiers intervene to handle potential policy violations In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. - `"end_turn"` - `"max_tokens"` - `"stop_sequence"` - `"tool_use"` - `"pause_turn"` - `"compaction"` - `"refusal"` - `"model_context_window_exceeded"` - `stop_sequence: string | null` Which custom stop sequence was generated, if any. This value will be a non-null string if one of your custom stop sequences was generated. - `type: "message"` Object type. For Messages, this is always `"message"`. - `"message"` - `usage: BetaUsage` Billing and rate-limit usage. Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. For example, `output_tokens` will be non-zero, even for an empty string response from Claude. Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. - `cache_creation: BetaCacheCreation | null` Breakdown of cached tokens by TTL - `ephemeral_1h_input_tokens: number` The number of input tokens used to create the 1 hour cache entry. - `ephemeral_5m_input_tokens: number` The number of input tokens used to create the 5 minute cache entry. - `cache_creation_input_tokens: number | null` The number of input tokens used to create the cache entry. - `cache_read_input_tokens: number | null` The number of input tokens read from the cache. - `inference_geo: string | null` The geographic region where inference was performed for this request. - `input_tokens: number` The number of input tokens which were used. - `iterations: BetaIterationsUsage | null` Per-iteration token usage breakdown. Each entry represents one sampling iteration, with its own input/output token counts and cache statistics. This allows you to: - Determine which iterations exceeded long context thresholds (>=200k tokens) - Calculate the true context window size from the last iteration - Understand token accumulation across server-side tool use loops - `BetaMessageIterationUsage` Token usage for a sampling iteration. - `cache_creation: BetaCacheCreation | null` Breakdown of cached tokens by TTL - `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: "message"` Usage for a sampling iteration - `"message"` - `BetaCompactionIterationUsage` Token usage for a compaction iteration. - `cache_creation: BetaCacheCreation | null` Breakdown of cached tokens by TTL - `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 - `"compaction"` - `BetaAdvisorMessageIterationUsage` Token usage for an advisor sub-inference iteration. - `cache_creation: BetaCacheCreation | null` Breakdown of cached tokens by TTL - `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. - `model: Model` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `output_tokens: number` The number of output tokens which were used. - `type: "advisor_message"` Usage for an advisor sub-inference iteration - `"advisor_message"` - `output_tokens: number` The number of output tokens which were used. - `output_tokens_details: BetaOutputTokensDetails | null` Breakdown of output tokens by category. `output_tokens` remains the inclusive, authoritative total used for billing. This object provides a read-only decomposition for observability — for example, how many of the billed output tokens were spent on internal reasoning that may have been summarized before being returned to you. - `thinking_tokens: number` Number of output tokens the model generated as internal reasoning, including the thinking-block delimiter tokens. Reflects the raw reasoning the model produced, not the (possibly shorter) summarized thinking text returned in the response body. Computed by re-tokenizing the raw reasoning text, so it may differ from the model's exact generation count by a small number of tokens. Always ≤ `output_tokens`; `output_tokens - thinking_tokens` approximates the non-reasoning output. - `server_tool_use: BetaServerToolUsage | null` The number of server tool requests. - `web_fetch_requests: number` The number of web fetch tool requests. - `web_search_requests: number` The number of web search tool requests. - `service_tier: "standard" | "priority" | "batch" | null` If the request used the priority, standard, or batch tier. - `"standard"` - `"priority"` - `"batch"` - `speed: "standard" | "fast" | null` The inference speed mode used for this request. - `"standard"` - `"fast"` - `type: "succeeded"` - `"succeeded"` - `BetaMessageBatchErroredResult` - `error: BetaErrorResponse` - `error: BetaError` - `BetaInvalidRequestError` - `message: string` - `type: "invalid_request_error"` - `"invalid_request_error"` - `BetaAuthenticationError` - `message: string` - `type: "authentication_error"` - `"authentication_error"` - `BetaBillingError` - `message: string` - `type: "billing_error"` - `"billing_error"` - `BetaPermissionError` - `message: string` - `type: "permission_error"` - `"permission_error"` - `BetaNotFoundError` - `message: string` - `type: "not_found_error"` - `"not_found_error"` - `BetaRateLimitError` - `message: string` - `type: "rate_limit_error"` - `"rate_limit_error"` - `BetaGatewayTimeoutError` - `message: string` - `type: "timeout_error"` - `"timeout_error"` - `BetaAPIError` - `message: string` - `type: "api_error"` - `"api_error"` - `BetaOverloadedError` - `message: string` - `type: "overloaded_error"` - `"overloaded_error"` - `request_id: string | null` - `type: "error"` - `"error"` - `type: "errored"` - `"errored"` - `BetaMessageBatchCanceledResult` - `type: "canceled"` - `"canceled"` - `BetaMessageBatchExpiredResult` - `type: "expired"` - `"expired"` ### Beta Message Batch Request Counts - `BetaMessageBatchRequestCounts` - `canceled: number` Number of requests in the Message Batch that have been canceled. This is zero until processing of the entire Message Batch has ended. - `errored: number` Number of requests in the Message Batch that encountered an error. This is zero until processing of the entire Message Batch has ended. - `expired: number` Number of requests in the Message Batch that have expired. This is zero until processing of the entire Message Batch has ended. - `processing: number` Number of requests in the Message Batch that are processing. - `succeeded: number` Number of requests in the Message Batch that have completed successfully. This is zero until processing of the entire Message Batch has ended. ### Beta Message Batch Result - `BetaMessageBatchResult = BetaMessageBatchSucceededResult | BetaMessageBatchErroredResult | BetaMessageBatchCanceledResult | BetaMessageBatchExpiredResult` Processing result for this request. Contains a Message output if processing was successful, an error response if processing failed, or the reason why processing was not attempted, such as cancellation or expiration. - `BetaMessageBatchSucceededResult` - `message: BetaMessage` - `id: string` Unique object identifier. The format and length of IDs may change over time. - `container: BetaContainer | null` 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 | 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) - `"anthropic"` - `"custom"` - `version: string` Skill version or 'latest' for most recent version - `content: Array` Content generated by the model. This is an array of content blocks, each of which has a `type` that determines its shape. Example: ```json [{"type": "text", "text": "Hi, I'm Claude."}] ``` If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. For example, if the input `messages` were: ```json [ {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, {"role": "assistant", "content": "The best answer is ("} ] ``` Then the response `content` might be: ```json [{"type": "text", "text": "B)"}] ``` - `BetaTextBlock` - `citations: Array | 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`. - `BetaCitationCharLocation` - `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"` - `"char_location"` - `BetaCitationPageLocation` - `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"` - `"page_location"` - `BetaCitationContentBlockLocation` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `document_index: number` - `document_title: string | null` - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `file_id: string | null` - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. - `type: "content_block_location"` - `"content_block_location"` - `BetaCitationsWebSearchResultLocation` - `cited_text: string` - `encrypted_index: string` - `title: string | null` - `type: "web_search_result_location"` - `"web_search_result_location"` - `url: string` - `BetaCitationSearchResultLocation` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `search_result_index: number` 0-based index of the cited search result among all `search_result` content blocks in the request, in the order they appear across messages and tool results. Counted separately from `document_index`; server-side web search results are not included in this count. - `source: string` - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. - `title: string | null` - `type: "search_result_location"` - `"search_result_location"` - `text: string` - `type: "text"` - `"text"` - `BetaThinkingBlock` - `signature: string` - `thinking: string` - `type: "thinking"` - `"thinking"` - `BetaRedactedThinkingBlock` - `data: string` - `type: "redacted_thinking"` - `"redacted_thinking"` - `BetaToolUseBlock` - `id: string` - `input: Record` - `name: string` - `type: "tool_use"` - `"tool_use"` - `caller?: BetaDirectCaller | BetaServerToolCaller | BetaServerToolCaller20260120` Tool invocation directly from the model. - `BetaDirectCaller` Tool invocation directly from the model. - `type: "direct"` - `"direct"` - `BetaServerToolCaller` Tool invocation generated by a server-side tool. - `tool_id: string` - `type: "code_execution_20250825"` - `"code_execution_20250825"` - `BetaServerToolCaller20260120` - `tool_id: string` - `type: "code_execution_20260120"` - `"code_execution_20260120"` - `BetaServerToolUseBlock` - `id: string` - `input: Record` - `name: "advisor" | "web_search" | "web_fetch" | 5 more` - `"advisor"` - `"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"` - `"server_tool_use"` - `caller?: BetaDirectCaller | BetaServerToolCaller | BetaServerToolCaller20260120` Tool invocation directly from the model. - `BetaDirectCaller` Tool invocation directly from the model. - `BetaServerToolCaller` Tool invocation generated by a server-side tool. - `BetaServerToolCaller20260120` - `BetaWebSearchToolResultBlock` - `content: BetaWebSearchToolResultBlockContent` - `BetaWebSearchToolResultError` - `error_code: BetaWebSearchToolResultErrorCode` - `"invalid_tool_input"` - `"unavailable"` - `"max_uses_exceeded"` - `"too_many_requests"` - `"query_too_long"` - `"request_too_large"` - `type: "web_search_tool_result_error"` - `"web_search_tool_result_error"` - `Array` - `encrypted_content: string` - `page_age: string | null` - `title: string` - `type: "web_search_result"` - `"web_search_result"` - `url: string` - `tool_use_id: string` - `type: "web_search_tool_result"` - `"web_search_tool_result"` - `caller?: BetaDirectCaller | BetaServerToolCaller | BetaServerToolCaller20260120` Tool invocation directly from the model. - `BetaDirectCaller` Tool invocation directly from the model. - `BetaServerToolCaller` Tool invocation generated by a server-side tool. - `BetaServerToolCaller20260120` - `BetaWebFetchToolResultBlock` - `content: BetaWebFetchToolResultErrorBlock | BetaWebFetchBlock` - `BetaWebFetchToolResultErrorBlock` - `error_code: BetaWebFetchToolResultErrorCode` - `"invalid_tool_input"` - `"url_too_long"` - `"url_not_allowed"` - `"url_not_in_prior_context"` - `"url_not_accessible"` - `"unsupported_content_type"` - `"too_many_requests"` - `"max_uses_exceeded"` - `"unavailable"` - `type: "web_fetch_tool_result_error"` - `"web_fetch_tool_result_error"` - `BetaWebFetchBlock` - `content: BetaDocumentBlock` - `citations: BetaCitationConfig | null` Citation configuration for the document - `enabled: boolean` - `source: BetaBase64PDFSource | BetaPlainTextSource` - `BetaBase64PDFSource` - `data: string` - `media_type: "application/pdf"` - `"application/pdf"` - `type: "base64"` - `"base64"` - `BetaPlainTextSource` - `data: string` - `media_type: "text/plain"` - `"text/plain"` - `type: "text"` - `"text"` - `title: string | null` The title of the document - `type: "document"` - `"document"` - `retrieved_at: string | null` ISO 8601 timestamp when the content was retrieved - `type: "web_fetch_result"` - `"web_fetch_result"` - `url: string` Fetched content URL - `tool_use_id: string` - `type: "web_fetch_tool_result"` - `"web_fetch_tool_result"` - `caller?: BetaDirectCaller | BetaServerToolCaller | BetaServerToolCaller20260120` Tool invocation directly from the model. - `BetaDirectCaller` Tool invocation directly from the model. - `BetaServerToolCaller` Tool invocation generated by a server-side tool. - `BetaServerToolCaller20260120` - `BetaAdvisorToolResultBlock` - `content: BetaAdvisorToolResultError | BetaAdvisorResultBlock | BetaAdvisorRedactedResultBlock` - `BetaAdvisorToolResultError` - `error_code: "max_uses_exceeded" | "prompt_too_long" | "too_many_requests" | 3 more` - `"max_uses_exceeded"` - `"prompt_too_long"` - `"too_many_requests"` - `"overloaded"` - `"unavailable"` - `"execution_time_exceeded"` - `type: "advisor_tool_result_error"` - `"advisor_tool_result_error"` - `BetaAdvisorResultBlock` - `stop_reason: string | null` The advisor sub-inference's stop reason (same values as the top-level message `stop_reason`). `max_tokens` indicates the advisor's output was truncated at the tool's `max_tokens` value or the advisor model's policy cap. - `text: string` - `type: "advisor_result"` - `"advisor_result"` - `BetaAdvisorRedactedResultBlock` - `encrypted_content: string` Opaque blob containing the advisor's output. Round-trip verbatim; do not inspect or modify. - `stop_reason: string | null` The advisor sub-inference's stop reason (same values as the top-level message `stop_reason`). - `type: "advisor_redacted_result"` - `"advisor_redacted_result"` - `tool_use_id: string` - `type: "advisor_tool_result"` - `"advisor_tool_result"` - `BetaCodeExecutionToolResultBlock` - `content: BetaCodeExecutionToolResultBlockContent` Code execution result with encrypted stdout for PFC + web_search results. - `BetaCodeExecutionToolResultError` - `error_code: BetaCodeExecutionToolResultErrorCode` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `type: "code_execution_tool_result_error"` - `"code_execution_tool_result_error"` - `BetaCodeExecutionResultBlock` - `content: Array` - `file_id: string` - `type: "code_execution_output"` - `"code_execution_output"` - `return_code: number` - `stderr: string` - `stdout: string` - `type: "code_execution_result"` - `"code_execution_result"` - `BetaEncryptedCodeExecutionResultBlock` Code execution result with encrypted stdout for PFC + web_search results. - `content: Array` - `file_id: string` - `type: "code_execution_output"` - `encrypted_stdout: string` - `return_code: number` - `stderr: string` - `type: "encrypted_code_execution_result"` - `"encrypted_code_execution_result"` - `tool_use_id: string` - `type: "code_execution_tool_result"` - `"code_execution_tool_result"` - `BetaBashCodeExecutionToolResultBlock` - `content: BetaBashCodeExecutionToolResultError | BetaBashCodeExecutionResultBlock` - `BetaBashCodeExecutionToolResultError` - `error_code: "invalid_tool_input" | "unavailable" | "too_many_requests" | 2 more` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `"output_file_too_large"` - `type: "bash_code_execution_tool_result_error"` - `"bash_code_execution_tool_result_error"` - `BetaBashCodeExecutionResultBlock` - `content: Array` - `file_id: string` - `type: "bash_code_execution_output"` - `"bash_code_execution_output"` - `return_code: number` - `stderr: string` - `stdout: string` - `type: "bash_code_execution_result"` - `"bash_code_execution_result"` - `tool_use_id: string` - `type: "bash_code_execution_tool_result"` - `"bash_code_execution_tool_result"` - `BetaTextEditorCodeExecutionToolResultBlock` - `content: BetaTextEditorCodeExecutionToolResultError | BetaTextEditorCodeExecutionViewResultBlock | BetaTextEditorCodeExecutionCreateResultBlock | BetaTextEditorCodeExecutionStrReplaceResultBlock` - `BetaTextEditorCodeExecutionToolResultError` - `error_code: "invalid_tool_input" | "unavailable" | "too_many_requests" | 2 more` - `"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"` - `"text_editor_code_execution_tool_result_error"` - `BetaTextEditorCodeExecutionViewResultBlock` - `content: string` - `file_type: "text" | "image" | "pdf"` - `"text"` - `"image"` - `"pdf"` - `num_lines: number | null` - `start_line: number | null` - `total_lines: number | null` - `type: "text_editor_code_execution_view_result"` - `"text_editor_code_execution_view_result"` - `BetaTextEditorCodeExecutionCreateResultBlock` - `is_file_update: boolean` - `type: "text_editor_code_execution_create_result"` - `"text_editor_code_execution_create_result"` - `BetaTextEditorCodeExecutionStrReplaceResultBlock` - `lines: Array | 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"` - `"text_editor_code_execution_str_replace_result"` - `tool_use_id: string` - `type: "text_editor_code_execution_tool_result"` - `"text_editor_code_execution_tool_result"` - `BetaToolSearchToolResultBlock` - `content: BetaToolSearchToolResultError | BetaToolSearchToolSearchResultBlock` - `BetaToolSearchToolResultError` - `error_code: "invalid_tool_input" | "unavailable" | "too_many_requests" | "execution_time_exceeded"` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `error_message: string | null` - `type: "tool_search_tool_result_error"` - `"tool_search_tool_result_error"` - `BetaToolSearchToolSearchResultBlock` - `tool_references: Array` - `tool_name: string` - `type: "tool_reference"` - `"tool_reference"` - `type: "tool_search_tool_search_result"` - `"tool_search_tool_search_result"` - `tool_use_id: string` - `type: "tool_search_tool_result"` - `"tool_search_tool_result"` - `BetaMCPToolUseBlock` - `id: string` - `input: Record` - `name: string` The name of the MCP tool - `server_name: string` The name of the MCP server - `type: "mcp_tool_use"` - `"mcp_tool_use"` - `BetaMCPToolResultBlock` - `content: string | Array` - `string` - `Array` - `citations: Array | 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`. - `text: string` - `type: "text"` - `is_error: boolean` - `tool_use_id: string` - `type: "mcp_tool_result"` - `"mcp_tool_result"` - `BetaContainerUploadBlock` Response model for a file uploaded to the container. - `file_id: string` - `type: "container_upload"` - `"container_upload"` - `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. - `content: string | null` Summary of compacted content, or null if compaction failed - `encrypted_content: string | null` Opaque metadata from prior compaction, to be round-tripped verbatim - `type: "compaction"` - `"compaction"` - `context_management: BetaContextManagementResponse | null` Context management response. Information about context management strategies applied during the request. - `applied_edits: Array` List of context management edits that were applied. - `BetaClearToolUses20250919EditResponse` - `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. - `"clear_tool_uses_20250919"` - `BetaClearThinking20251015EditResponse` - `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. - `"clear_thinking_20251015"` - `diagnostics: BetaDiagnostics | null` Response envelope for request-level diagnostics. Present (possibly null) whenever the caller supplied `diagnostics` on the request. - `cache_miss_reason: BetaCacheMissModelChanged | BetaCacheMissSystemChanged | BetaCacheMissToolsChanged | 3 more | null` Explains why the prompt cache could not fully reuse the prefix from the request identified by `diagnostics.previous_message_id`. `null` means diagnosis is still pending — the response was serialized before the background comparison completed. - `BetaCacheMissModelChanged` - `cache_missed_input_tokens: number` Approximate number of input tokens that would have been read from cache had the prefix matched the previous request. - `type: "model_changed"` - `"model_changed"` - `BetaCacheMissSystemChanged` - `cache_missed_input_tokens: number` Approximate number of input tokens that would have been read from cache had the prefix matched the previous request. - `type: "system_changed"` - `"system_changed"` - `BetaCacheMissToolsChanged` - `cache_missed_input_tokens: number` Approximate number of input tokens that would have been read from cache had the prefix matched the previous request. - `type: "tools_changed"` - `"tools_changed"` - `BetaCacheMissMessagesChanged` - `cache_missed_input_tokens: number` Approximate number of input tokens that would have been read from cache had the prefix matched the previous request. - `type: "messages_changed"` - `"messages_changed"` - `BetaCacheMissPreviousMessageNotFound` - `type: "previous_message_not_found"` - `"previous_message_not_found"` - `BetaCacheMissUnavailable` - `type: "unavailable"` - `"unavailable"` - `model: Model` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-opus-4-8" | "claude-opus-4-7" | "claude-mythos-preview" | 15 more` - `"claude-opus-4-8"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-7"` Frontier intelligence for long-running agents and coding - `"claude-mythos-preview"` New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` Fastest model with near-frontier intelligence - `"claude-haiku-4-5-20251001"` Fastest model with near-frontier intelligence - `"claude-opus-4-5"` Premium model combining maximum intelligence with practical performance - `"claude-opus-4-5-20251101"` Premium model combining maximum intelligence with practical performance - `"claude-sonnet-4-5"` High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` High-performance model for agents and coding - `"claude-opus-4-1"` Exceptional model for specialized complex tasks - `"claude-opus-4-1-20250805"` Exceptional model for specialized complex tasks - `"claude-opus-4-0"` Powerful model for complex tasks - `"claude-opus-4-20250514"` Powerful model for complex tasks - `"claude-sonnet-4-0"` High-performance model with extended thinking - `"claude-sonnet-4-20250514"` High-performance model with extended thinking - `"claude-3-haiku-20240307"` Fast and cost-effective model - `(string & {})` - `role: "assistant"` Conversational role of the generated message. This will always be `"assistant"`. - `"assistant"` - `stop_details: BetaRefusalStopDetails | null` Structured information about a refusal. - `category: "cyber" | "bio" | null` The policy category that triggered the refusal. `null` when the refusal doesn't map to a named category. - `"cyber"` - `"bio"` - `explanation: string | null` Human-readable explanation of the refusal. This text is not guaranteed to be stable. `null` when no explanation is available for the category. - `type: "refusal"` - `"refusal"` - `stop_reason: BetaStopReason | null` The reason that we stopped. This may be one the following values: * `"end_turn"`: the model reached a natural stopping point * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated * `"tool_use"`: the model invoked one or more tools * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. * `"refusal"`: when streaming classifiers intervene to handle potential policy violations In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. - `"end_turn"` - `"max_tokens"` - `"stop_sequence"` - `"tool_use"` - `"pause_turn"` - `"compaction"` - `"refusal"` - `"model_context_window_exceeded"` - `stop_sequence: string | null` Which custom stop sequence was generated, if any. This value will be a non-null string if one of your custom stop sequences was generated. - `type: "message"` Object type. For Messages, this is always `"message"`. - `"message"` - `usage: BetaUsage` Billing and rate-limit usage. Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. For example, `output_tokens` will be non-zero, even for an empty string response from Claude. Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. - `cache_creation: BetaCacheCreation | null` Breakdown of cached tokens by TTL - `ephemeral_1h_input_tokens: number` The number of input tokens used to create the 1 hour cache entry. - `ephemeral_5m_input_tokens: number` The number of input tokens used to create the 5 minute cache entry. - `cache_creation_input_tokens: number | null` The number of input tokens used to create the cache entry. - `cache_read_input_tokens: number | null` The number of input tokens read from the cache. - `inference_geo: string | null` The geographic region where inference was performed for this request. - `input_tokens: number` The number of input tokens which were used. - `iterations: BetaIterationsUsage | null` Per-iteration token usage breakdown. Each entry represents one sampling iteration, with its own input/output token counts and cache statistics. This allows you to: - Determine which iterations exceeded long context thresholds (>=200k tokens) - Calculate the true context window size from the last iteration - Understand token accumulation across server-side tool use loops - `BetaMessageIterationUsage` Token usage for a sampling iteration. - `cache_creation: BetaCacheCreation | null` Breakdown of cached tokens by TTL - `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: "message"` Usage for a sampling iteration - `"message"` - `BetaCompactionIterationUsage` Token usage for a compaction iteration. - `cache_creation: BetaCacheCreation | null` Breakdown of cached tokens by TTL - `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 - `"compaction"` - `BetaAdvisorMessageIterationUsage` Token usage for an advisor sub-inference iteration. - `cache_creation: BetaCacheCreation | null` Breakdown of cached tokens by TTL - `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. - `model: Model` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `output_tokens: number` The number of output tokens which were used. - `type: "advisor_message"` Usage for an advisor sub-inference iteration - `"advisor_message"` - `output_tokens: number` The number of output tokens which were used. - `output_tokens_details: BetaOutputTokensDetails | null` Breakdown of output tokens by category. `output_tokens` remains the inclusive, authoritative total used for billing. This object provides a read-only decomposition for observability — for example, how many of the billed output tokens were spent on internal reasoning that may have been summarized before being returned to you. - `thinking_tokens: number` Number of output tokens the model generated as internal reasoning, including the thinking-block delimiter tokens. Reflects the raw reasoning the model produced, not the (possibly shorter) summarized thinking text returned in the response body. Computed by re-tokenizing the raw reasoning text, so it may differ from the model's exact generation count by a small number of tokens. Always ≤ `output_tokens`; `output_tokens - thinking_tokens` approximates the non-reasoning output. - `server_tool_use: BetaServerToolUsage | null` The number of server tool requests. - `web_fetch_requests: number` The number of web fetch tool requests. - `web_search_requests: number` The number of web search tool requests. - `service_tier: "standard" | "priority" | "batch" | null` If the request used the priority, standard, or batch tier. - `"standard"` - `"priority"` - `"batch"` - `speed: "standard" | "fast" | null` The inference speed mode used for this request. - `"standard"` - `"fast"` - `type: "succeeded"` - `"succeeded"` - `BetaMessageBatchErroredResult` - `error: BetaErrorResponse` - `error: BetaError` - `BetaInvalidRequestError` - `message: string` - `type: "invalid_request_error"` - `"invalid_request_error"` - `BetaAuthenticationError` - `message: string` - `type: "authentication_error"` - `"authentication_error"` - `BetaBillingError` - `message: string` - `type: "billing_error"` - `"billing_error"` - `BetaPermissionError` - `message: string` - `type: "permission_error"` - `"permission_error"` - `BetaNotFoundError` - `message: string` - `type: "not_found_error"` - `"not_found_error"` - `BetaRateLimitError` - `message: string` - `type: "rate_limit_error"` - `"rate_limit_error"` - `BetaGatewayTimeoutError` - `message: string` - `type: "timeout_error"` - `"timeout_error"` - `BetaAPIError` - `message: string` - `type: "api_error"` - `"api_error"` - `BetaOverloadedError` - `message: string` - `type: "overloaded_error"` - `"overloaded_error"` - `request_id: string | null` - `type: "error"` - `"error"` - `type: "errored"` - `"errored"` - `BetaMessageBatchCanceledResult` - `type: "canceled"` - `"canceled"` - `BetaMessageBatchExpiredResult` - `type: "expired"` - `"expired"` ### Beta Message Batch Succeeded Result - `BetaMessageBatchSucceededResult` - `message: BetaMessage` - `id: string` Unique object identifier. The format and length of IDs may change over time. - `container: BetaContainer | null` 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 | 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) - `"anthropic"` - `"custom"` - `version: string` Skill version or 'latest' for most recent version - `content: Array` Content generated by the model. This is an array of content blocks, each of which has a `type` that determines its shape. Example: ```json [{"type": "text", "text": "Hi, I'm Claude."}] ``` If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output. For example, if the input `messages` were: ```json [ {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"}, {"role": "assistant", "content": "The best answer is ("} ] ``` Then the response `content` might be: ```json [{"type": "text", "text": "B)"}] ``` - `BetaTextBlock` - `citations: Array | 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`. - `BetaCitationCharLocation` - `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"` - `"char_location"` - `BetaCitationPageLocation` - `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"` - `"page_location"` - `BetaCitationContentBlockLocation` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `document_index: number` - `document_title: string | null` - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `file_id: string | null` - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. - `type: "content_block_location"` - `"content_block_location"` - `BetaCitationsWebSearchResultLocation` - `cited_text: string` - `encrypted_index: string` - `title: string | null` - `type: "web_search_result_location"` - `"web_search_result_location"` - `url: string` - `BetaCitationSearchResultLocation` - `cited_text: string` The full text of the cited block range, concatenated. Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns. - `end_block_index: number` Exclusive 0-based end index of the cited block range in the source's `content` array. Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`. - `search_result_index: number` 0-based index of the cited search result among all `search_result` content blocks in the request, in the order they appear across messages and tool results. Counted separately from `document_index`; server-side web search results are not included in this count. - `source: string` - `start_block_index: number` 0-based index of the first cited block in the source's `content` array. - `title: string | null` - `type: "search_result_location"` - `"search_result_location"` - `text: string` - `type: "text"` - `"text"` - `BetaThinkingBlock` - `signature: string` - `thinking: string` - `type: "thinking"` - `"thinking"` - `BetaRedactedThinkingBlock` - `data: string` - `type: "redacted_thinking"` - `"redacted_thinking"` - `BetaToolUseBlock` - `id: string` - `input: Record` - `name: string` - `type: "tool_use"` - `"tool_use"` - `caller?: BetaDirectCaller | BetaServerToolCaller | BetaServerToolCaller20260120` Tool invocation directly from the model. - `BetaDirectCaller` Tool invocation directly from the model. - `type: "direct"` - `"direct"` - `BetaServerToolCaller` Tool invocation generated by a server-side tool. - `tool_id: string` - `type: "code_execution_20250825"` - `"code_execution_20250825"` - `BetaServerToolCaller20260120` - `tool_id: string` - `type: "code_execution_20260120"` - `"code_execution_20260120"` - `BetaServerToolUseBlock` - `id: string` - `input: Record` - `name: "advisor" | "web_search" | "web_fetch" | 5 more` - `"advisor"` - `"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"` - `"server_tool_use"` - `caller?: BetaDirectCaller | BetaServerToolCaller | BetaServerToolCaller20260120` Tool invocation directly from the model. - `BetaDirectCaller` Tool invocation directly from the model. - `BetaServerToolCaller` Tool invocation generated by a server-side tool. - `BetaServerToolCaller20260120` - `BetaWebSearchToolResultBlock` - `content: BetaWebSearchToolResultBlockContent` - `BetaWebSearchToolResultError` - `error_code: BetaWebSearchToolResultErrorCode` - `"invalid_tool_input"` - `"unavailable"` - `"max_uses_exceeded"` - `"too_many_requests"` - `"query_too_long"` - `"request_too_large"` - `type: "web_search_tool_result_error"` - `"web_search_tool_result_error"` - `Array` - `encrypted_content: string` - `page_age: string | null` - `title: string` - `type: "web_search_result"` - `"web_search_result"` - `url: string` - `tool_use_id: string` - `type: "web_search_tool_result"` - `"web_search_tool_result"` - `caller?: BetaDirectCaller | BetaServerToolCaller | BetaServerToolCaller20260120` Tool invocation directly from the model. - `BetaDirectCaller` Tool invocation directly from the model. - `BetaServerToolCaller` Tool invocation generated by a server-side tool. - `BetaServerToolCaller20260120` - `BetaWebFetchToolResultBlock` - `content: BetaWebFetchToolResultErrorBlock | BetaWebFetchBlock` - `BetaWebFetchToolResultErrorBlock` - `error_code: BetaWebFetchToolResultErrorCode` - `"invalid_tool_input"` - `"url_too_long"` - `"url_not_allowed"` - `"url_not_in_prior_context"` - `"url_not_accessible"` - `"unsupported_content_type"` - `"too_many_requests"` - `"max_uses_exceeded"` - `"unavailable"` - `type: "web_fetch_tool_result_error"` - `"web_fetch_tool_result_error"` - `BetaWebFetchBlock` - `content: BetaDocumentBlock` - `citations: BetaCitationConfig | null` Citation configuration for the document - `enabled: boolean` - `source: BetaBase64PDFSource | BetaPlainTextSource` - `BetaBase64PDFSource` - `data: string` - `media_type: "application/pdf"` - `"application/pdf"` - `type: "base64"` - `"base64"` - `BetaPlainTextSource` - `data: string` - `media_type: "text/plain"` - `"text/plain"` - `type: "text"` - `"text"` - `title: string | null` The title of the document - `type: "document"` - `"document"` - `retrieved_at: string | null` ISO 8601 timestamp when the content was retrieved - `type: "web_fetch_result"` - `"web_fetch_result"` - `url: string` Fetched content URL - `tool_use_id: string` - `type: "web_fetch_tool_result"` - `"web_fetch_tool_result"` - `caller?: BetaDirectCaller | BetaServerToolCaller | BetaServerToolCaller20260120` Tool invocation directly from the model. - `BetaDirectCaller` Tool invocation directly from the model. - `BetaServerToolCaller` Tool invocation generated by a server-side tool. - `BetaServerToolCaller20260120` - `BetaAdvisorToolResultBlock` - `content: BetaAdvisorToolResultError | BetaAdvisorResultBlock | BetaAdvisorRedactedResultBlock` - `BetaAdvisorToolResultError` - `error_code: "max_uses_exceeded" | "prompt_too_long" | "too_many_requests" | 3 more` - `"max_uses_exceeded"` - `"prompt_too_long"` - `"too_many_requests"` - `"overloaded"` - `"unavailable"` - `"execution_time_exceeded"` - `type: "advisor_tool_result_error"` - `"advisor_tool_result_error"` - `BetaAdvisorResultBlock` - `stop_reason: string | null` The advisor sub-inference's stop reason (same values as the top-level message `stop_reason`). `max_tokens` indicates the advisor's output was truncated at the tool's `max_tokens` value or the advisor model's policy cap. - `text: string` - `type: "advisor_result"` - `"advisor_result"` - `BetaAdvisorRedactedResultBlock` - `encrypted_content: string` Opaque blob containing the advisor's output. Round-trip verbatim; do not inspect or modify. - `stop_reason: string | null` The advisor sub-inference's stop reason (same values as the top-level message `stop_reason`). - `type: "advisor_redacted_result"` - `"advisor_redacted_result"` - `tool_use_id: string` - `type: "advisor_tool_result"` - `"advisor_tool_result"` - `BetaCodeExecutionToolResultBlock` - `content: BetaCodeExecutionToolResultBlockContent` Code execution result with encrypted stdout for PFC + web_search results. - `BetaCodeExecutionToolResultError` - `error_code: BetaCodeExecutionToolResultErrorCode` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `type: "code_execution_tool_result_error"` - `"code_execution_tool_result_error"` - `BetaCodeExecutionResultBlock` - `content: Array` - `file_id: string` - `type: "code_execution_output"` - `"code_execution_output"` - `return_code: number` - `stderr: string` - `stdout: string` - `type: "code_execution_result"` - `"code_execution_result"` - `BetaEncryptedCodeExecutionResultBlock` Code execution result with encrypted stdout for PFC + web_search results. - `content: Array` - `file_id: string` - `type: "code_execution_output"` - `encrypted_stdout: string` - `return_code: number` - `stderr: string` - `type: "encrypted_code_execution_result"` - `"encrypted_code_execution_result"` - `tool_use_id: string` - `type: "code_execution_tool_result"` - `"code_execution_tool_result"` - `BetaBashCodeExecutionToolResultBlock` - `content: BetaBashCodeExecutionToolResultError | BetaBashCodeExecutionResultBlock` - `BetaBashCodeExecutionToolResultError` - `error_code: "invalid_tool_input" | "unavailable" | "too_many_requests" | 2 more` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `"output_file_too_large"` - `type: "bash_code_execution_tool_result_error"` - `"bash_code_execution_tool_result_error"` - `BetaBashCodeExecutionResultBlock` - `content: Array` - `file_id: string` - `type: "bash_code_execution_output"` - `"bash_code_execution_output"` - `return_code: number` - `stderr: string` - `stdout: string` - `type: "bash_code_execution_result"` - `"bash_code_execution_result"` - `tool_use_id: string` - `type: "bash_code_execution_tool_result"` - `"bash_code_execution_tool_result"` - `BetaTextEditorCodeExecutionToolResultBlock` - `content: BetaTextEditorCodeExecutionToolResultError | BetaTextEditorCodeExecutionViewResultBlock | BetaTextEditorCodeExecutionCreateResultBlock | BetaTextEditorCodeExecutionStrReplaceResultBlock` - `BetaTextEditorCodeExecutionToolResultError` - `error_code: "invalid_tool_input" | "unavailable" | "too_many_requests" | 2 more` - `"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"` - `"text_editor_code_execution_tool_result_error"` - `BetaTextEditorCodeExecutionViewResultBlock` - `content: string` - `file_type: "text" | "image" | "pdf"` - `"text"` - `"image"` - `"pdf"` - `num_lines: number | null` - `start_line: number | null` - `total_lines: number | null` - `type: "text_editor_code_execution_view_result"` - `"text_editor_code_execution_view_result"` - `BetaTextEditorCodeExecutionCreateResultBlock` - `is_file_update: boolean` - `type: "text_editor_code_execution_create_result"` - `"text_editor_code_execution_create_result"` - `BetaTextEditorCodeExecutionStrReplaceResultBlock` - `lines: Array | 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"` - `"text_editor_code_execution_str_replace_result"` - `tool_use_id: string` - `type: "text_editor_code_execution_tool_result"` - `"text_editor_code_execution_tool_result"` - `BetaToolSearchToolResultBlock` - `content: BetaToolSearchToolResultError | BetaToolSearchToolSearchResultBlock` - `BetaToolSearchToolResultError` - `error_code: "invalid_tool_input" | "unavailable" | "too_many_requests" | "execution_time_exceeded"` - `"invalid_tool_input"` - `"unavailable"` - `"too_many_requests"` - `"execution_time_exceeded"` - `error_message: string | null` - `type: "tool_search_tool_result_error"` - `"tool_search_tool_result_error"` - `BetaToolSearchToolSearchResultBlock` - `tool_references: Array` - `tool_name: string` - `type: "tool_reference"` - `"tool_reference"` - `type: "tool_search_tool_search_result"` - `"tool_search_tool_search_result"` - `tool_use_id: string` - `type: "tool_search_tool_result"` - `"tool_search_tool_result"` - `BetaMCPToolUseBlock` - `id: string` - `input: Record` - `name: string` The name of the MCP tool - `server_name: string` The name of the MCP server - `type: "mcp_tool_use"` - `"mcp_tool_use"` - `BetaMCPToolResultBlock` - `content: string | Array` - `string` - `Array` - `citations: Array | 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`. - `text: string` - `type: "text"` - `is_error: boolean` - `tool_use_id: string` - `type: "mcp_tool_result"` - `"mcp_tool_result"` - `BetaContainerUploadBlock` Response model for a file uploaded to the container. - `file_id: string` - `type: "container_upload"` - `"container_upload"` - `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. - `content: string | null` Summary of compacted content, or null if compaction failed - `encrypted_content: string | null` Opaque metadata from prior compaction, to be round-tripped verbatim - `type: "compaction"` - `"compaction"` - `context_management: BetaContextManagementResponse | null` Context management response. Information about context management strategies applied during the request. - `applied_edits: Array` List of context management edits that were applied. - `BetaClearToolUses20250919EditResponse` - `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. - `"clear_tool_uses_20250919"` - `BetaClearThinking20251015EditResponse` - `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. - `"clear_thinking_20251015"` - `diagnostics: BetaDiagnostics | null` Response envelope for request-level diagnostics. Present (possibly null) whenever the caller supplied `diagnostics` on the request. - `cache_miss_reason: BetaCacheMissModelChanged | BetaCacheMissSystemChanged | BetaCacheMissToolsChanged | 3 more | null` Explains why the prompt cache could not fully reuse the prefix from the request identified by `diagnostics.previous_message_id`. `null` means diagnosis is still pending — the response was serialized before the background comparison completed. - `BetaCacheMissModelChanged` - `cache_missed_input_tokens: number` Approximate number of input tokens that would have been read from cache had the prefix matched the previous request. - `type: "model_changed"` - `"model_changed"` - `BetaCacheMissSystemChanged` - `cache_missed_input_tokens: number` Approximate number of input tokens that would have been read from cache had the prefix matched the previous request. - `type: "system_changed"` - `"system_changed"` - `BetaCacheMissToolsChanged` - `cache_missed_input_tokens: number` Approximate number of input tokens that would have been read from cache had the prefix matched the previous request. - `type: "tools_changed"` - `"tools_changed"` - `BetaCacheMissMessagesChanged` - `cache_missed_input_tokens: number` Approximate number of input tokens that would have been read from cache had the prefix matched the previous request. - `type: "messages_changed"` - `"messages_changed"` - `BetaCacheMissPreviousMessageNotFound` - `type: "previous_message_not_found"` - `"previous_message_not_found"` - `BetaCacheMissUnavailable` - `type: "unavailable"` - `"unavailable"` - `model: Model` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-opus-4-8" | "claude-opus-4-7" | "claude-mythos-preview" | 15 more` - `"claude-opus-4-8"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-7"` Frontier intelligence for long-running agents and coding - `"claude-mythos-preview"` New class of intelligence, strongest in coding and cybersecurity - `"claude-opus-4-6"` Frontier intelligence for long-running agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` Fastest model with near-frontier intelligence - `"claude-haiku-4-5-20251001"` Fastest model with near-frontier intelligence - `"claude-opus-4-5"` Premium model combining maximum intelligence with practical performance - `"claude-opus-4-5-20251101"` Premium model combining maximum intelligence with practical performance - `"claude-sonnet-4-5"` High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` High-performance model for agents and coding - `"claude-opus-4-1"` Exceptional model for specialized complex tasks - `"claude-opus-4-1-20250805"` Exceptional model for specialized complex tasks - `"claude-opus-4-0"` Powerful model for complex tasks - `"claude-opus-4-20250514"` Powerful model for complex tasks - `"claude-sonnet-4-0"` High-performance model with extended thinking - `"claude-sonnet-4-20250514"` High-performance model with extended thinking - `"claude-3-haiku-20240307"` Fast and cost-effective model - `(string & {})` - `role: "assistant"` Conversational role of the generated message. This will always be `"assistant"`. - `"assistant"` - `stop_details: BetaRefusalStopDetails | null` Structured information about a refusal. - `category: "cyber" | "bio" | null` The policy category that triggered the refusal. `null` when the refusal doesn't map to a named category. - `"cyber"` - `"bio"` - `explanation: string | null` Human-readable explanation of the refusal. This text is not guaranteed to be stable. `null` when no explanation is available for the category. - `type: "refusal"` - `"refusal"` - `stop_reason: BetaStopReason | null` The reason that we stopped. This may be one the following values: * `"end_turn"`: the model reached a natural stopping point * `"max_tokens"`: we exceeded the requested `max_tokens` or the model's maximum * `"stop_sequence"`: one of your provided custom `stop_sequences` was generated * `"tool_use"`: the model invoked one or more tools * `"pause_turn"`: we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue. * `"refusal"`: when streaming classifiers intervene to handle potential policy violations In non-streaming mode this value is always non-null. In streaming mode, it is null in the `message_start` event and non-null otherwise. - `"end_turn"` - `"max_tokens"` - `"stop_sequence"` - `"tool_use"` - `"pause_turn"` - `"compaction"` - `"refusal"` - `"model_context_window_exceeded"` - `stop_sequence: string | null` Which custom stop sequence was generated, if any. This value will be a non-null string if one of your custom stop sequences was generated. - `type: "message"` Object type. For Messages, this is always `"message"`. - `"message"` - `usage: BetaUsage` Billing and rate-limit usage. Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems. Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in `usage` will not match one-to-one with the exact visible content of an API request or response. For example, `output_tokens` will be non-zero, even for an empty string response from Claude. Total input tokens in a request is the summation of `input_tokens`, `cache_creation_input_tokens`, and `cache_read_input_tokens`. - `cache_creation: BetaCacheCreation | null` Breakdown of cached tokens by TTL - `ephemeral_1h_input_tokens: number` The number of input tokens used to create the 1 hour cache entry. - `ephemeral_5m_input_tokens: number` The number of input tokens used to create the 5 minute cache entry. - `cache_creation_input_tokens: number | null` The number of input tokens used to create the cache entry. - `cache_read_input_tokens: number | null` The number of input tokens read from the cache. - `inference_geo: string | null` The geographic region where inference was performed for this request. - `input_tokens: number` The number of input tokens which were used. - `iterations: BetaIterationsUsage | null` Per-iteration token usage breakdown. Each entry represents one sampling iteration, with its own input/output token counts and cache statistics. This allows you to: - Determine which iterations exceeded long context thresholds (>=200k tokens) - Calculate the true context window size from the last iteration - Understand token accumulation across server-side tool use loops - `BetaMessageIterationUsage` Token usage for a sampling iteration. - `cache_creation: BetaCacheCreation | null` Breakdown of cached tokens by TTL - `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: "message"` Usage for a sampling iteration - `"message"` - `BetaCompactionIterationUsage` Token usage for a compaction iteration. - `cache_creation: BetaCacheCreation | null` Breakdown of cached tokens by TTL - `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 - `"compaction"` - `BetaAdvisorMessageIterationUsage` Token usage for an advisor sub-inference iteration. - `cache_creation: BetaCacheCreation | null` Breakdown of cached tokens by TTL - `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. - `model: Model` The model that will complete your prompt. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `output_tokens: number` The number of output tokens which were used. - `type: "advisor_message"` Usage for an advisor sub-inference iteration - `"advisor_message"` - `output_tokens: number` The number of output tokens which were used. - `output_tokens_details: BetaOutputTokensDetails | null` Breakdown of output tokens by category. `output_tokens` remains the inclusive, authoritative total used for billing. This object provides a read-only decomposition for observability — for example, how many of the billed output tokens were spent on internal reasoning that may have been summarized before being returned to you. - `thinking_tokens: number` Number of output tokens the model generated as internal reasoning, including the thinking-block delimiter tokens. Reflects the raw reasoning the model produced, not the (possibly shorter) summarized thinking text returned in the response body. Computed by re-tokenizing the raw reasoning text, so it may differ from the model's exact generation count by a small number of tokens. Always ≤ `output_tokens`; `output_tokens - thinking_tokens` approximates the non-reasoning output. - `server_tool_use: BetaServerToolUsage | null` The number of server tool requests. - `web_fetch_requests: number` The number of web fetch tool requests. - `web_search_requests: number` The number of web search tool requests. - `service_tier: "standard" | "priority" | "batch" | null` If the request used the priority, standard, or batch tier. - `"standard"` - `"priority"` - `"batch"` - `speed: "standard" | "fast" | null` The inference speed mode used for this request. - `"standard"` - `"fast"` - `type: "succeeded"` - `"succeeded"` # Agents ## Create Agent `client.beta.agents.create(AgentCreateParamsparams, RequestOptionsoptions?): BetaManagedAgentsAgent` **post** `/v1/agents` Create Agent ### Parameters - `params: AgentCreateParams` - `model: BetaManagedAgentsModel | BetaManagedAgentsModelConfigParams` Body param: Model identifier. Accepts the [model string](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison), e.g. `claude-opus-4-6`, or a `model_config` object for additional configuration control - `BetaManagedAgentsModel = "claude-opus-4-8" | "claude-opus-4-7" | "claude-opus-4-6" | 7 more | (string & {})` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-opus-4-8" | "claude-opus-4-7" | "claude-opus-4-6" | 7 more` - `"claude-opus-4-8"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-7"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-6"` Most intelligent model for building agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` Fastest model with near-frontier intelligence - `"claude-haiku-4-5-20251001"` Fastest model with near-frontier intelligence - `"claude-opus-4-5"` Premium model combining maximum intelligence with practical performance - `"claude-opus-4-5-20251101"` Premium model combining maximum intelligence with practical performance - `"claude-sonnet-4-5"` High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` High-performance model for agents and coding - `(string & {})` - `BetaManagedAgentsModelConfigParams` An object that defines additional configuration control over model use - `id: BetaManagedAgentsModel` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `speed?: "standard" | "fast" | null` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `name: string` Body param: Human-readable name for the agent. 1-256 characters. - `description?: string | null` Body param: Description of what the agent does. Up to 2048 characters. - `mcp_servers?: Array` Body param: MCP servers this agent connects to. Maximum 20. Names must be unique within the array. - `name: string` Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters. - `type: "url"` - `"url"` - `url: string` Endpoint URL for the MCP server. - `metadata?: Record` Body param: Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars. - `multiagent?: BetaManagedAgentsMultiagentParams | null` Body param: A coordinator topology: the session's primary thread orchestrates work by spawning session threads, each running an agent drawn from the `agents` roster. - `agents: Array` Agents the coordinator may spawn as session threads. 1–20 entries. Each entry is an agent ID string, a versioned `{"type":"agent","id","version"}` reference, or `{"type":"self"}` to allow recursive self-invocation. Entries must reference distinct agents (after resolving `self` and string forms); at most one `self`. Referenced agents must exist, must not be archived, and must not themselves have `multiagent` set (depth limit 1). - `string` - `BetaManagedAgentsAgentParams` Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version - `id: string` The `agent` ID. - `type: "agent"` - `"agent"` - `version?: number` The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified. - `BetaManagedAgentsMultiagentSelfParams` Sentinel roster entry meaning "the agent that owns this configuration". Resolved server-side to a concrete agent reference. - `type: "self"` - `"self"` - `type: "coordinator"` - `"coordinator"` - `skills?: Array` Body param: Skills available to the agent. Maximum 20. - `BetaManagedAgentsAnthropicSkillParams` An Anthropic-managed skill. - `skill_id: string` Identifier of the Anthropic skill (e.g., "xlsx"). - `type: "anthropic"` - `"anthropic"` - `version?: string | null` Version to pin. Defaults to latest if omitted. - `BetaManagedAgentsCustomSkillParams` A user-created custom skill. - `skill_id: string` Tagged ID of the custom skill (e.g., "skill_01XJ5..."). - `type: "custom"` - `"custom"` - `version?: string | null` Version to pin. Defaults to latest if omitted. - `system?: string | null` Body param: System prompt for the agent. Up to 100,000 characters. - `tools?: Array` Body param: Tool configurations available to the agent. Maximum of 128 tools across all toolsets allowed. - `BetaManagedAgentsAgentToolset20260401Params` Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent. - `type: "agent_toolset_20260401"` - `"agent_toolset_20260401"` - `configs?: Array` Per-tool configuration overrides. - `name: "bash" | "edit" | "read" | 5 more` Built-in agent tool identifier. - `"bash"` - `"edit"` - `"read"` - `"write"` - `"glob"` - `"grep"` - `"web_fetch"` - `"web_search"` - `enabled?: boolean | null` Whether this tool is enabled and available to Claude. Overrides the default_config setting. - `permission_policy?: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy | null` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `"always_allow"` - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "always_ask"` - `"always_ask"` - `default_config?: BetaManagedAgentsAgentToolsetDefaultConfigParams | null` Default configuration for all tools in a toolset. - `enabled?: boolean | null` Whether tools are enabled and available to Claude by default. Defaults to true if not specified. - `permission_policy?: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy | null` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `BetaManagedAgentsMCPToolsetParams` Configuration for tools from an MCP server defined in `mcp_servers`. - `mcp_server_name: string` Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters. - `type: "mcp_toolset"` - `"mcp_toolset"` - `configs?: Array` Per-tool configuration overrides. - `name: string` Name of the MCP tool to configure. 1-128 characters. - `enabled?: boolean | null` Whether this tool is enabled. Overrides the `default_config` setting. - `permission_policy?: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy | null` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `default_config?: BetaManagedAgentsMCPToolsetDefaultConfigParams | null` Default configuration for all tools from an MCP server. - `enabled?: boolean | null` Whether tools are enabled by default. Defaults to true if not specified. - `permission_policy?: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy | null` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `BetaManagedAgentsCustomToolParams` A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an `agent.custom_tool_use` event is emitted and the session goes idle, waiting for the client to provide the result via a `user.custom_tool_result` event. - `description: string` Description of what the tool does, shown to the agent to help it decide when to use the tool. 1-1024 characters. - `input_schema: BetaManagedAgentsCustomToolInputSchema` JSON Schema for custom tool input parameters. - `properties?: Record | null` JSON Schema properties defining the tool's input parameters. - `required?: Array` List of required property names. - `type?: "object"` Must be 'object' for tool input schemas. - `"object"` - `name: string` Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens. - `type: "custom"` - `"custom"` - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaManagedAgentsAgent` A Managed Agents `agent`. - `id: string` - `archived_at: string | null` A timestamp in RFC 3339 format - `created_at: string` A timestamp in RFC 3339 format - `description: string | null` - `mcp_servers: Array` - `name: string` - `type: "url"` - `"url"` - `url: string` - `metadata: Record` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `id: BetaManagedAgentsModel` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-opus-4-8" | "claude-opus-4-7" | "claude-opus-4-6" | 7 more` - `"claude-opus-4-8"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-7"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-6"` Most intelligent model for building agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` Fastest model with near-frontier intelligence - `"claude-haiku-4-5-20251001"` Fastest model with near-frontier intelligence - `"claude-opus-4-5"` Premium model combining maximum intelligence with practical performance - `"claude-opus-4-5-20251101"` Premium model combining maximum intelligence with practical performance - `"claude-sonnet-4-5"` High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` High-performance model for agents and coding - `(string & {})` - `speed?: "standard" | "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `multiagent: BetaManagedAgentsMultiagent | null` Resolved coordinator topology with a concrete agent roster. - `agents: Array` Agents the coordinator may spawn as session threads, each resolved to a specific version. - `id: string` - `type: "agent"` - `"agent"` - `version: number` - `type: "coordinator"` - `"coordinator"` - `name: string` - `skills: Array` - `BetaManagedAgentsAnthropicSkill` A resolved Anthropic-managed skill. - `skill_id: string` - `type: "anthropic"` - `"anthropic"` - `version: string` - `BetaManagedAgentsCustomSkill` A resolved user-created custom skill. - `skill_id: string` - `type: "custom"` - `"custom"` - `version: string` - `system: string | null` - `tools: Array` - `BetaManagedAgentsAgentToolset20260401` - `configs: Array` - `enabled: boolean` - `name: "bash" | "edit" | "read" | 5 more` Built-in agent tool identifier. - `"bash"` - `"edit"` - `"read"` - `"write"` - `"glob"` - `"grep"` - `"web_fetch"` - `"web_search"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `"always_allow"` - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "always_ask"` - `"always_ask"` - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` Resolved default configuration for agent tools. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "agent_toolset_20260401"` - `"agent_toolset_20260401"` - `BetaManagedAgentsMCPToolset` - `configs: Array` - `enabled: boolean` - `name: string` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` Resolved default configuration for all tools from an MCP server. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `mcp_server_name: string` - `type: "mcp_toolset"` - `"mcp_toolset"` - `BetaManagedAgentsCustomTool` A custom tool as returned in API responses. - `description: string` - `input_schema: BetaManagedAgentsCustomToolInputSchema` JSON Schema for custom tool input parameters. - `properties?: Record | null` JSON Schema properties defining the tool's input parameters. - `required?: Array` List of required property names. - `type?: "object"` Must be 'object' for tool input schemas. - `"object"` - `name: string` - `type: "custom"` - `"custom"` - `type: "agent"` - `"agent"` - `updated_at: string` A timestamp in RFC 3339 format - `version: number` The agent's current version. Starts at 1 and increments when the agent is modified. ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const betaManagedAgentsAgent = await client.beta.agents.create({ model: 'claude-sonnet-4-6', name: 'My First Agent', }); console.log(betaManagedAgentsAgent.id); ``` #### Response ```json { "id": "agent_011CZkYpogX7uDKUyvBTophP", "archived_at": null, "created_at": "2026-03-15T10:00:00Z", "description": "A general-purpose starter agent.", "mcp_servers": [ { "name": "example-mcp", "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse" } ], "metadata": { "foo": "bar" }, "model": { "id": "claude-sonnet-4-6", "speed": "standard" }, "multiagent": { "agents": [ { "id": "agent_011CZkYqphY8vELVzwCUpqiQ", "type": "agent", "version": 1 } ], "type": "coordinator" }, "name": "My First Agent", "skills": [ { "skill_id": "xlsx", "type": "anthropic", "version": "1" }, { "skill_id": "skill_011CZkZFNu9hAbo3jZPRgTlx", "type": "custom", "version": "2" } ], "system": "You are a general-purpose agent that can research, write code, run commands, and use connected tools to complete the user's task end to end.", "tools": [ { "configs": [ { "enabled": true, "name": "bash", "permission_policy": { "type": "always_allow" } } ], "default_config": { "enabled": true, "permission_policy": { "type": "always_ask" } }, "type": "agent_toolset_20260401" } ], "type": "agent", "updated_at": "2026-03-15T10:00:00Z", "version": 1 } ``` ## List Agents `client.beta.agents.list(AgentListParamsparams?, RequestOptionsoptions?): PageCursor` **get** `/v1/agents` List Agents ### Parameters - `params: AgentListParams` - `"created_at[gte]"?: string` Query param: Return agents created at or after this time (inclusive). - `"created_at[lte]"?: string` Query param: Return agents created at or before this time (inclusive). - `include_archived?: boolean` Query param: Include archived agents in results. Defaults to false. - `limit?: number` Query param: Maximum results per page. Default 20, maximum 100. - `page?: string` Query param: Opaque pagination cursor from a previous response. - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaManagedAgentsAgent` A Managed Agents `agent`. - `id: string` - `archived_at: string | null` A timestamp in RFC 3339 format - `created_at: string` A timestamp in RFC 3339 format - `description: string | null` - `mcp_servers: Array` - `name: string` - `type: "url"` - `"url"` - `url: string` - `metadata: Record` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `id: BetaManagedAgentsModel` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-opus-4-8" | "claude-opus-4-7" | "claude-opus-4-6" | 7 more` - `"claude-opus-4-8"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-7"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-6"` Most intelligent model for building agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` Fastest model with near-frontier intelligence - `"claude-haiku-4-5-20251001"` Fastest model with near-frontier intelligence - `"claude-opus-4-5"` Premium model combining maximum intelligence with practical performance - `"claude-opus-4-5-20251101"` Premium model combining maximum intelligence with practical performance - `"claude-sonnet-4-5"` High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` High-performance model for agents and coding - `(string & {})` - `speed?: "standard" | "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `multiagent: BetaManagedAgentsMultiagent | null` Resolved coordinator topology with a concrete agent roster. - `agents: Array` Agents the coordinator may spawn as session threads, each resolved to a specific version. - `id: string` - `type: "agent"` - `"agent"` - `version: number` - `type: "coordinator"` - `"coordinator"` - `name: string` - `skills: Array` - `BetaManagedAgentsAnthropicSkill` A resolved Anthropic-managed skill. - `skill_id: string` - `type: "anthropic"` - `"anthropic"` - `version: string` - `BetaManagedAgentsCustomSkill` A resolved user-created custom skill. - `skill_id: string` - `type: "custom"` - `"custom"` - `version: string` - `system: string | null` - `tools: Array` - `BetaManagedAgentsAgentToolset20260401` - `configs: Array` - `enabled: boolean` - `name: "bash" | "edit" | "read" | 5 more` Built-in agent tool identifier. - `"bash"` - `"edit"` - `"read"` - `"write"` - `"glob"` - `"grep"` - `"web_fetch"` - `"web_search"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `"always_allow"` - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "always_ask"` - `"always_ask"` - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` Resolved default configuration for agent tools. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "agent_toolset_20260401"` - `"agent_toolset_20260401"` - `BetaManagedAgentsMCPToolset` - `configs: Array` - `enabled: boolean` - `name: string` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` Resolved default configuration for all tools from an MCP server. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `mcp_server_name: string` - `type: "mcp_toolset"` - `"mcp_toolset"` - `BetaManagedAgentsCustomTool` A custom tool as returned in API responses. - `description: string` - `input_schema: BetaManagedAgentsCustomToolInputSchema` JSON Schema for custom tool input parameters. - `properties?: Record | null` JSON Schema properties defining the tool's input parameters. - `required?: Array` List of required property names. - `type?: "object"` Must be 'object' for tool input schemas. - `"object"` - `name: string` - `type: "custom"` - `"custom"` - `type: "agent"` - `"agent"` - `updated_at: string` A timestamp in RFC 3339 format - `version: number` The agent's current version. Starts at 1 and increments when the agent is modified. ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); // Automatically fetches more pages as needed. for await (const betaManagedAgentsAgent of client.beta.agents.list()) { console.log(betaManagedAgentsAgent.id); } ``` #### Response ```json { "data": [ { "id": "agent_011CZkYpogX7uDKUyvBTophP", "archived_at": null, "created_at": "2026-03-15T10:00:00Z", "description": "A general-purpose starter agent.", "mcp_servers": [ { "name": "example-mcp", "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse" } ], "metadata": { "foo": "bar" }, "model": { "id": "claude-sonnet-4-6", "speed": "standard" }, "multiagent": { "agents": [ { "id": "agent_011CZkYqphY8vELVzwCUpqiQ", "type": "agent", "version": 1 } ], "type": "coordinator" }, "name": "My First Agent", "skills": [ { "skill_id": "xlsx", "type": "anthropic", "version": "1" }, { "skill_id": "skill_011CZkZFNu9hAbo3jZPRgTlx", "type": "custom", "version": "2" } ], "system": "You are a general-purpose agent that can research, write code, run commands, and use connected tools to complete the user's task end to end.", "tools": [ { "configs": [ { "enabled": true, "name": "bash", "permission_policy": { "type": "always_allow" } } ], "default_config": { "enabled": true, "permission_policy": { "type": "always_ask" } }, "type": "agent_toolset_20260401" } ], "type": "agent", "updated_at": "2026-03-15T10:00:00Z", "version": 1 } ], "next_page": "next_page" } ``` ## Get Agent `client.beta.agents.retrieve(stringagentID, AgentRetrieveParamsparams?, RequestOptionsoptions?): BetaManagedAgentsAgent` **get** `/v1/agents/{agent_id}` Get Agent ### Parameters - `agentID: string` - `params: AgentRetrieveParams` - `version?: number` Query param: Agent version. Omit for the most recent version. Must be at least 1 if specified. - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaManagedAgentsAgent` A Managed Agents `agent`. - `id: string` - `archived_at: string | null` A timestamp in RFC 3339 format - `created_at: string` A timestamp in RFC 3339 format - `description: string | null` - `mcp_servers: Array` - `name: string` - `type: "url"` - `"url"` - `url: string` - `metadata: Record` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `id: BetaManagedAgentsModel` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-opus-4-8" | "claude-opus-4-7" | "claude-opus-4-6" | 7 more` - `"claude-opus-4-8"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-7"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-6"` Most intelligent model for building agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` Fastest model with near-frontier intelligence - `"claude-haiku-4-5-20251001"` Fastest model with near-frontier intelligence - `"claude-opus-4-5"` Premium model combining maximum intelligence with practical performance - `"claude-opus-4-5-20251101"` Premium model combining maximum intelligence with practical performance - `"claude-sonnet-4-5"` High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` High-performance model for agents and coding - `(string & {})` - `speed?: "standard" | "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `multiagent: BetaManagedAgentsMultiagent | null` Resolved coordinator topology with a concrete agent roster. - `agents: Array` Agents the coordinator may spawn as session threads, each resolved to a specific version. - `id: string` - `type: "agent"` - `"agent"` - `version: number` - `type: "coordinator"` - `"coordinator"` - `name: string` - `skills: Array` - `BetaManagedAgentsAnthropicSkill` A resolved Anthropic-managed skill. - `skill_id: string` - `type: "anthropic"` - `"anthropic"` - `version: string` - `BetaManagedAgentsCustomSkill` A resolved user-created custom skill. - `skill_id: string` - `type: "custom"` - `"custom"` - `version: string` - `system: string | null` - `tools: Array` - `BetaManagedAgentsAgentToolset20260401` - `configs: Array` - `enabled: boolean` - `name: "bash" | "edit" | "read" | 5 more` Built-in agent tool identifier. - `"bash"` - `"edit"` - `"read"` - `"write"` - `"glob"` - `"grep"` - `"web_fetch"` - `"web_search"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `"always_allow"` - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "always_ask"` - `"always_ask"` - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` Resolved default configuration for agent tools. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "agent_toolset_20260401"` - `"agent_toolset_20260401"` - `BetaManagedAgentsMCPToolset` - `configs: Array` - `enabled: boolean` - `name: string` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` Resolved default configuration for all tools from an MCP server. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `mcp_server_name: string` - `type: "mcp_toolset"` - `"mcp_toolset"` - `BetaManagedAgentsCustomTool` A custom tool as returned in API responses. - `description: string` - `input_schema: BetaManagedAgentsCustomToolInputSchema` JSON Schema for custom tool input parameters. - `properties?: Record | null` JSON Schema properties defining the tool's input parameters. - `required?: Array` List of required property names. - `type?: "object"` Must be 'object' for tool input schemas. - `"object"` - `name: string` - `type: "custom"` - `"custom"` - `type: "agent"` - `"agent"` - `updated_at: string` A timestamp in RFC 3339 format - `version: number` The agent's current version. Starts at 1 and increments when the agent is modified. ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const betaManagedAgentsAgent = await client.beta.agents.retrieve('agent_011CZkYpogX7uDKUyvBTophP'); console.log(betaManagedAgentsAgent.id); ``` #### Response ```json { "id": "agent_011CZkYpogX7uDKUyvBTophP", "archived_at": null, "created_at": "2026-03-15T10:00:00Z", "description": "A general-purpose starter agent.", "mcp_servers": [ { "name": "example-mcp", "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse" } ], "metadata": { "foo": "bar" }, "model": { "id": "claude-sonnet-4-6", "speed": "standard" }, "multiagent": { "agents": [ { "id": "agent_011CZkYqphY8vELVzwCUpqiQ", "type": "agent", "version": 1 } ], "type": "coordinator" }, "name": "My First Agent", "skills": [ { "skill_id": "xlsx", "type": "anthropic", "version": "1" }, { "skill_id": "skill_011CZkZFNu9hAbo3jZPRgTlx", "type": "custom", "version": "2" } ], "system": "You are a general-purpose agent that can research, write code, run commands, and use connected tools to complete the user's task end to end.", "tools": [ { "configs": [ { "enabled": true, "name": "bash", "permission_policy": { "type": "always_allow" } } ], "default_config": { "enabled": true, "permission_policy": { "type": "always_ask" } }, "type": "agent_toolset_20260401" } ], "type": "agent", "updated_at": "2026-03-15T10:00:00Z", "version": 1 } ``` ## Update Agent `client.beta.agents.update(stringagentID, AgentUpdateParamsparams, RequestOptionsoptions?): BetaManagedAgentsAgent` **post** `/v1/agents/{agent_id}` Update Agent ### Parameters - `agentID: string` - `params: AgentUpdateParams` - `version: number` Body param: The agent's current version, used to prevent concurrent overwrites. Obtain this value from a create or retrieve response. The request fails if this does not match the server's current version. - `description?: string | null` Body param: Description. Up to 2048 characters. Omit to preserve; send empty string or null to clear. - `mcp_servers?: Array | null` Body param: MCP servers. Full replacement. Omit to preserve; send empty array or null to clear. Names must be unique. Maximum 20. - `name: string` Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters. - `type: "url"` - `"url"` - `url: string` Endpoint URL for the MCP server. - `metadata?: Record | null` Body param: Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve. The stored bag is limited to 16 keys (up to 64 chars each) with values up to 512 chars. - `model?: BetaManagedAgentsModel | BetaManagedAgentsModelConfigParams` Body param: Model identifier. Accepts the [model string](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison), e.g. `claude-opus-4-6`, or a `model_config` object for additional configuration control. Omit to preserve. Cannot be cleared. - `BetaManagedAgentsModel = "claude-opus-4-8" | "claude-opus-4-7" | "claude-opus-4-6" | 7 more | (string & {})` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-opus-4-8" | "claude-opus-4-7" | "claude-opus-4-6" | 7 more` - `"claude-opus-4-8"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-7"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-6"` Most intelligent model for building agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` Fastest model with near-frontier intelligence - `"claude-haiku-4-5-20251001"` Fastest model with near-frontier intelligence - `"claude-opus-4-5"` Premium model combining maximum intelligence with practical performance - `"claude-opus-4-5-20251101"` Premium model combining maximum intelligence with practical performance - `"claude-sonnet-4-5"` High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` High-performance model for agents and coding - `(string & {})` - `BetaManagedAgentsModelConfigParams` An object that defines additional configuration control over model use - `id: BetaManagedAgentsModel` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `speed?: "standard" | "fast" | null` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `multiagent?: BetaManagedAgentsMultiagentParams | null` Body param: A coordinator topology: the session's primary thread orchestrates work by spawning session threads, each running an agent drawn from the `agents` roster. - `agents: Array` Agents the coordinator may spawn as session threads. 1–20 entries. Each entry is an agent ID string, a versioned `{"type":"agent","id","version"}` reference, or `{"type":"self"}` to allow recursive self-invocation. Entries must reference distinct agents (after resolving `self` and string forms); at most one `self`. Referenced agents must exist, must not be archived, and must not themselves have `multiagent` set (depth limit 1). - `string` - `BetaManagedAgentsAgentParams` Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version - `id: string` The `agent` ID. - `type: "agent"` - `"agent"` - `version?: number` The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified. - `BetaManagedAgentsMultiagentSelfParams` Sentinel roster entry meaning "the agent that owns this configuration". Resolved server-side to a concrete agent reference. - `type: "self"` - `"self"` - `type: "coordinator"` - `"coordinator"` - `name?: string` Body param: Human-readable name. 1-256 characters. Omit to preserve. Cannot be cleared. - `skills?: Array | null` Body param: Skills. Full replacement. Omit to preserve; send empty array or null to clear. Maximum 20. - `BetaManagedAgentsAnthropicSkillParams` An Anthropic-managed skill. - `skill_id: string` Identifier of the Anthropic skill (e.g., "xlsx"). - `type: "anthropic"` - `"anthropic"` - `version?: string | null` Version to pin. Defaults to latest if omitted. - `BetaManagedAgentsCustomSkillParams` A user-created custom skill. - `skill_id: string` Tagged ID of the custom skill (e.g., "skill_01XJ5..."). - `type: "custom"` - `"custom"` - `version?: string | null` Version to pin. Defaults to latest if omitted. - `system?: string | null` Body param: System prompt. Up to 100,000 characters. Omit to preserve; send empty string or null to clear. - `tools?: Array | null` Body param: Tool configurations available to the agent. Full replacement. Omit to preserve; send empty array or null to clear. Maximum of 128 tools across all toolsets allowed. - `BetaManagedAgentsAgentToolset20260401Params` Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent. - `type: "agent_toolset_20260401"` - `"agent_toolset_20260401"` - `configs?: Array` Per-tool configuration overrides. - `name: "bash" | "edit" | "read" | 5 more` Built-in agent tool identifier. - `"bash"` - `"edit"` - `"read"` - `"write"` - `"glob"` - `"grep"` - `"web_fetch"` - `"web_search"` - `enabled?: boolean | null` Whether this tool is enabled and available to Claude. Overrides the default_config setting. - `permission_policy?: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy | null` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `"always_allow"` - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "always_ask"` - `"always_ask"` - `default_config?: BetaManagedAgentsAgentToolsetDefaultConfigParams | null` Default configuration for all tools in a toolset. - `enabled?: boolean | null` Whether tools are enabled and available to Claude by default. Defaults to true if not specified. - `permission_policy?: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy | null` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `BetaManagedAgentsMCPToolsetParams` Configuration for tools from an MCP server defined in `mcp_servers`. - `mcp_server_name: string` Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters. - `type: "mcp_toolset"` - `"mcp_toolset"` - `configs?: Array` Per-tool configuration overrides. - `name: string` Name of the MCP tool to configure. 1-128 characters. - `enabled?: boolean | null` Whether this tool is enabled. Overrides the `default_config` setting. - `permission_policy?: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy | null` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `default_config?: BetaManagedAgentsMCPToolsetDefaultConfigParams | null` Default configuration for all tools from an MCP server. - `enabled?: boolean | null` Whether tools are enabled by default. Defaults to true if not specified. - `permission_policy?: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy | null` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `BetaManagedAgentsCustomToolParams` A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an `agent.custom_tool_use` event is emitted and the session goes idle, waiting for the client to provide the result via a `user.custom_tool_result` event. - `description: string` Description of what the tool does, shown to the agent to help it decide when to use the tool. 1-1024 characters. - `input_schema: BetaManagedAgentsCustomToolInputSchema` JSON Schema for custom tool input parameters. - `properties?: Record | null` JSON Schema properties defining the tool's input parameters. - `required?: Array` List of required property names. - `type?: "object"` Must be 'object' for tool input schemas. - `"object"` - `name: string` Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens. - `type: "custom"` - `"custom"` - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaManagedAgentsAgent` A Managed Agents `agent`. - `id: string` - `archived_at: string | null` A timestamp in RFC 3339 format - `created_at: string` A timestamp in RFC 3339 format - `description: string | null` - `mcp_servers: Array` - `name: string` - `type: "url"` - `"url"` - `url: string` - `metadata: Record` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `id: BetaManagedAgentsModel` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-opus-4-8" | "claude-opus-4-7" | "claude-opus-4-6" | 7 more` - `"claude-opus-4-8"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-7"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-6"` Most intelligent model for building agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` Fastest model with near-frontier intelligence - `"claude-haiku-4-5-20251001"` Fastest model with near-frontier intelligence - `"claude-opus-4-5"` Premium model combining maximum intelligence with practical performance - `"claude-opus-4-5-20251101"` Premium model combining maximum intelligence with practical performance - `"claude-sonnet-4-5"` High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` High-performance model for agents and coding - `(string & {})` - `speed?: "standard" | "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `multiagent: BetaManagedAgentsMultiagent | null` Resolved coordinator topology with a concrete agent roster. - `agents: Array` Agents the coordinator may spawn as session threads, each resolved to a specific version. - `id: string` - `type: "agent"` - `"agent"` - `version: number` - `type: "coordinator"` - `"coordinator"` - `name: string` - `skills: Array` - `BetaManagedAgentsAnthropicSkill` A resolved Anthropic-managed skill. - `skill_id: string` - `type: "anthropic"` - `"anthropic"` - `version: string` - `BetaManagedAgentsCustomSkill` A resolved user-created custom skill. - `skill_id: string` - `type: "custom"` - `"custom"` - `version: string` - `system: string | null` - `tools: Array` - `BetaManagedAgentsAgentToolset20260401` - `configs: Array` - `enabled: boolean` - `name: "bash" | "edit" | "read" | 5 more` Built-in agent tool identifier. - `"bash"` - `"edit"` - `"read"` - `"write"` - `"glob"` - `"grep"` - `"web_fetch"` - `"web_search"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `"always_allow"` - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "always_ask"` - `"always_ask"` - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` Resolved default configuration for agent tools. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "agent_toolset_20260401"` - `"agent_toolset_20260401"` - `BetaManagedAgentsMCPToolset` - `configs: Array` - `enabled: boolean` - `name: string` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` Resolved default configuration for all tools from an MCP server. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `mcp_server_name: string` - `type: "mcp_toolset"` - `"mcp_toolset"` - `BetaManagedAgentsCustomTool` A custom tool as returned in API responses. - `description: string` - `input_schema: BetaManagedAgentsCustomToolInputSchema` JSON Schema for custom tool input parameters. - `properties?: Record | null` JSON Schema properties defining the tool's input parameters. - `required?: Array` List of required property names. - `type?: "object"` Must be 'object' for tool input schemas. - `"object"` - `name: string` - `type: "custom"` - `"custom"` - `type: "agent"` - `"agent"` - `updated_at: string` A timestamp in RFC 3339 format - `version: number` The agent's current version. Starts at 1 and increments when the agent is modified. ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const betaManagedAgentsAgent = await client.beta.agents.update('agent_011CZkYpogX7uDKUyvBTophP', { version: 1, }); console.log(betaManagedAgentsAgent.id); ``` #### Response ```json { "id": "agent_011CZkYpogX7uDKUyvBTophP", "archived_at": null, "created_at": "2026-03-15T10:00:00Z", "description": "A general-purpose starter agent.", "mcp_servers": [ { "name": "example-mcp", "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse" } ], "metadata": { "foo": "bar" }, "model": { "id": "claude-sonnet-4-6", "speed": "standard" }, "multiagent": { "agents": [ { "id": "agent_011CZkYqphY8vELVzwCUpqiQ", "type": "agent", "version": 1 } ], "type": "coordinator" }, "name": "My First Agent", "skills": [ { "skill_id": "xlsx", "type": "anthropic", "version": "1" }, { "skill_id": "skill_011CZkZFNu9hAbo3jZPRgTlx", "type": "custom", "version": "2" } ], "system": "You are a general-purpose agent that can research, write code, run commands, and use connected tools to complete the user's task end to end.", "tools": [ { "configs": [ { "enabled": true, "name": "bash", "permission_policy": { "type": "always_allow" } } ], "default_config": { "enabled": true, "permission_policy": { "type": "always_ask" } }, "type": "agent_toolset_20260401" } ], "type": "agent", "updated_at": "2026-03-15T10:00:00Z", "version": 1 } ``` ## Archive Agent `client.beta.agents.archive(stringagentID, AgentArchiveParamsparams?, RequestOptionsoptions?): BetaManagedAgentsAgent` **post** `/v1/agents/{agent_id}/archive` Archive Agent ### Parameters - `agentID: string` - `params: AgentArchiveParams` - `betas?: Array` Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaManagedAgentsAgent` A Managed Agents `agent`. - `id: string` - `archived_at: string | null` A timestamp in RFC 3339 format - `created_at: string` A timestamp in RFC 3339 format - `description: string | null` - `mcp_servers: Array` - `name: string` - `type: "url"` - `"url"` - `url: string` - `metadata: Record` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `id: BetaManagedAgentsModel` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-opus-4-8" | "claude-opus-4-7" | "claude-opus-4-6" | 7 more` - `"claude-opus-4-8"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-7"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-6"` Most intelligent model for building agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` Fastest model with near-frontier intelligence - `"claude-haiku-4-5-20251001"` Fastest model with near-frontier intelligence - `"claude-opus-4-5"` Premium model combining maximum intelligence with practical performance - `"claude-opus-4-5-20251101"` Premium model combining maximum intelligence with practical performance - `"claude-sonnet-4-5"` High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` High-performance model for agents and coding - `(string & {})` - `speed?: "standard" | "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `multiagent: BetaManagedAgentsMultiagent | null` Resolved coordinator topology with a concrete agent roster. - `agents: Array` Agents the coordinator may spawn as session threads, each resolved to a specific version. - `id: string` - `type: "agent"` - `"agent"` - `version: number` - `type: "coordinator"` - `"coordinator"` - `name: string` - `skills: Array` - `BetaManagedAgentsAnthropicSkill` A resolved Anthropic-managed skill. - `skill_id: string` - `type: "anthropic"` - `"anthropic"` - `version: string` - `BetaManagedAgentsCustomSkill` A resolved user-created custom skill. - `skill_id: string` - `type: "custom"` - `"custom"` - `version: string` - `system: string | null` - `tools: Array` - `BetaManagedAgentsAgentToolset20260401` - `configs: Array` - `enabled: boolean` - `name: "bash" | "edit" | "read" | 5 more` Built-in agent tool identifier. - `"bash"` - `"edit"` - `"read"` - `"write"` - `"glob"` - `"grep"` - `"web_fetch"` - `"web_search"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `"always_allow"` - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "always_ask"` - `"always_ask"` - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` Resolved default configuration for agent tools. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "agent_toolset_20260401"` - `"agent_toolset_20260401"` - `BetaManagedAgentsMCPToolset` - `configs: Array` - `enabled: boolean` - `name: string` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` Resolved default configuration for all tools from an MCP server. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `mcp_server_name: string` - `type: "mcp_toolset"` - `"mcp_toolset"` - `BetaManagedAgentsCustomTool` A custom tool as returned in API responses. - `description: string` - `input_schema: BetaManagedAgentsCustomToolInputSchema` JSON Schema for custom tool input parameters. - `properties?: Record | null` JSON Schema properties defining the tool's input parameters. - `required?: Array` List of required property names. - `type?: "object"` Must be 'object' for tool input schemas. - `"object"` - `name: string` - `type: "custom"` - `"custom"` - `type: "agent"` - `"agent"` - `updated_at: string` A timestamp in RFC 3339 format - `version: number` The agent's current version. Starts at 1 and increments when the agent is modified. ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const betaManagedAgentsAgent = await client.beta.agents.archive('agent_011CZkYpogX7uDKUyvBTophP'); console.log(betaManagedAgentsAgent.id); ``` #### Response ```json { "id": "agent_011CZkYpogX7uDKUyvBTophP", "archived_at": null, "created_at": "2026-03-15T10:00:00Z", "description": "A general-purpose starter agent.", "mcp_servers": [ { "name": "example-mcp", "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse" } ], "metadata": { "foo": "bar" }, "model": { "id": "claude-sonnet-4-6", "speed": "standard" }, "multiagent": { "agents": [ { "id": "agent_011CZkYqphY8vELVzwCUpqiQ", "type": "agent", "version": 1 } ], "type": "coordinator" }, "name": "My First Agent", "skills": [ { "skill_id": "xlsx", "type": "anthropic", "version": "1" }, { "skill_id": "skill_011CZkZFNu9hAbo3jZPRgTlx", "type": "custom", "version": "2" } ], "system": "You are a general-purpose agent that can research, write code, run commands, and use connected tools to complete the user's task end to end.", "tools": [ { "configs": [ { "enabled": true, "name": "bash", "permission_policy": { "type": "always_allow" } } ], "default_config": { "enabled": true, "permission_policy": { "type": "always_ask" } }, "type": "agent_toolset_20260401" } ], "type": "agent", "updated_at": "2026-03-15T10:00:00Z", "version": 1 } ``` ## Domain Types ### Beta Managed Agents Agent - `BetaManagedAgentsAgent` A Managed Agents `agent`. - `id: string` - `archived_at: string | null` A timestamp in RFC 3339 format - `created_at: string` A timestamp in RFC 3339 format - `description: string | null` - `mcp_servers: Array` - `name: string` - `type: "url"` - `"url"` - `url: string` - `metadata: Record` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `id: BetaManagedAgentsModel` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-opus-4-8" | "claude-opus-4-7" | "claude-opus-4-6" | 7 more` - `"claude-opus-4-8"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-7"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-6"` Most intelligent model for building agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` Fastest model with near-frontier intelligence - `"claude-haiku-4-5-20251001"` Fastest model with near-frontier intelligence - `"claude-opus-4-5"` Premium model combining maximum intelligence with practical performance - `"claude-opus-4-5-20251101"` Premium model combining maximum intelligence with practical performance - `"claude-sonnet-4-5"` High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` High-performance model for agents and coding - `(string & {})` - `speed?: "standard" | "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `multiagent: BetaManagedAgentsMultiagent | null` Resolved coordinator topology with a concrete agent roster. - `agents: Array` Agents the coordinator may spawn as session threads, each resolved to a specific version. - `id: string` - `type: "agent"` - `"agent"` - `version: number` - `type: "coordinator"` - `"coordinator"` - `name: string` - `skills: Array` - `BetaManagedAgentsAnthropicSkill` A resolved Anthropic-managed skill. - `skill_id: string` - `type: "anthropic"` - `"anthropic"` - `version: string` - `BetaManagedAgentsCustomSkill` A resolved user-created custom skill. - `skill_id: string` - `type: "custom"` - `"custom"` - `version: string` - `system: string | null` - `tools: Array` - `BetaManagedAgentsAgentToolset20260401` - `configs: Array` - `enabled: boolean` - `name: "bash" | "edit" | "read" | 5 more` Built-in agent tool identifier. - `"bash"` - `"edit"` - `"read"` - `"write"` - `"glob"` - `"grep"` - `"web_fetch"` - `"web_search"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `"always_allow"` - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "always_ask"` - `"always_ask"` - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` Resolved default configuration for agent tools. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "agent_toolset_20260401"` - `"agent_toolset_20260401"` - `BetaManagedAgentsMCPToolset` - `configs: Array` - `enabled: boolean` - `name: string` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` Resolved default configuration for all tools from an MCP server. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `mcp_server_name: string` - `type: "mcp_toolset"` - `"mcp_toolset"` - `BetaManagedAgentsCustomTool` A custom tool as returned in API responses. - `description: string` - `input_schema: BetaManagedAgentsCustomToolInputSchema` JSON Schema for custom tool input parameters. - `properties?: Record | null` JSON Schema properties defining the tool's input parameters. - `required?: Array` List of required property names. - `type?: "object"` Must be 'object' for tool input schemas. - `"object"` - `name: string` - `type: "custom"` - `"custom"` - `type: "agent"` - `"agent"` - `updated_at: string` A timestamp in RFC 3339 format - `version: number` The agent's current version. Starts at 1 and increments when the agent is modified. ### Beta Managed Agents Agent Reference - `BetaManagedAgentsAgentReference` A resolved agent reference with a concrete version. - `id: string` - `type: "agent"` - `"agent"` - `version: number` ### Beta Managed Agents Agent Tool Config - `BetaManagedAgentsAgentToolConfig` Configuration for a specific agent tool. - `enabled: boolean` - `name: "bash" | "edit" | "read" | 5 more` Built-in agent tool identifier. - `"bash"` - `"edit"` - `"read"` - `"write"` - `"glob"` - `"grep"` - `"web_fetch"` - `"web_search"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `"always_allow"` - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "always_ask"` - `"always_ask"` ### Beta Managed Agents Agent Tool Config Params - `BetaManagedAgentsAgentToolConfigParams` Configuration override for a specific tool within a toolset. - `name: "bash" | "edit" | "read" | 5 more` Built-in agent tool identifier. - `"bash"` - `"edit"` - `"read"` - `"write"` - `"glob"` - `"grep"` - `"web_fetch"` - `"web_search"` - `enabled?: boolean | null` Whether this tool is enabled and available to Claude. Overrides the default_config setting. - `permission_policy?: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy | null` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `"always_allow"` - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "always_ask"` - `"always_ask"` ### Beta Managed Agents Agent Toolset Default Config - `BetaManagedAgentsAgentToolsetDefaultConfig` Resolved default configuration for agent tools. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `"always_allow"` - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "always_ask"` - `"always_ask"` ### Beta Managed Agents Agent Toolset Default Config Params - `BetaManagedAgentsAgentToolsetDefaultConfigParams` Default configuration for all tools in a toolset. - `enabled?: boolean | null` Whether tools are enabled and available to Claude by default. Defaults to true if not specified. - `permission_policy?: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy | null` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `"always_allow"` - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "always_ask"` - `"always_ask"` ### Beta Managed Agents Agent Toolset20260401 - `BetaManagedAgentsAgentToolset20260401` - `configs: Array` - `enabled: boolean` - `name: "bash" | "edit" | "read" | 5 more` Built-in agent tool identifier. - `"bash"` - `"edit"` - `"read"` - `"write"` - `"glob"` - `"grep"` - `"web_fetch"` - `"web_search"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `"always_allow"` - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "always_ask"` - `"always_ask"` - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` Resolved default configuration for agent tools. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "agent_toolset_20260401"` - `"agent_toolset_20260401"` ### Beta Managed Agents Agent Toolset20260401 Bash Input - `BetaManagedAgentsAgentToolset20260401BashInput` Input payload for the `bash` tool of the `agent_toolset_20260401` toolset. All fields are optional; a normal invocation supplies `command`, while `restart=true` (with no `command`) reboots the runner-side bash session. - `command?: string` Shell command to execute. Omit only when `restart` is true. - `restart?: boolean` When true, restart the persistent bash session instead of running a command. Subsequent calls without `restart` will run against the fresh session. - `timeout_ms?: number` Per-call timeout in milliseconds. Defaults to the runner-wide tool timeout when omitted or zero. ### Beta Managed Agents Agent Toolset20260401 Edit Input - `BetaManagedAgentsAgentToolset20260401EditInput` Input payload for the `edit` tool. Performs a string replacement in the named file; by default `old_string` must occur exactly once. - `file_path: string` Path of the file to edit. - `new_string: string` Replacement text. - `old_string: string` Substring to find and replace. - `replace_all?: boolean` When true, replace every occurrence of `old_string` instead of requiring a unique match. ### Beta Managed Agents Agent Toolset20260401 Glob Input - `BetaManagedAgentsAgentToolset20260401GlobInput` Input payload for the `glob` tool. Returns paths matching a doublestar glob pattern, newest first. - `pattern: string` Doublestar glob pattern (e.g. `**/*.go`). Absolute patterns are only permitted when the runner is configured to allow them. - `path?: string` Optional directory root to search under. Defaults to the runner's working directory. ### Beta Managed Agents Agent Toolset20260401 Grep Input - `BetaManagedAgentsAgentToolset20260401GrepInput` Input payload for the `grep` tool. Searches file contents for a regular expression, returning matching lines. - `pattern: string` Regular expression to search for. - `path?: string` Optional directory root to search under. Defaults to the runner's working directory. ### Beta Managed Agents Agent Toolset20260401 Params - `BetaManagedAgentsAgentToolset20260401Params` Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent. - `type: "agent_toolset_20260401"` - `"agent_toolset_20260401"` - `configs?: Array` Per-tool configuration overrides. - `name: "bash" | "edit" | "read" | 5 more` Built-in agent tool identifier. - `"bash"` - `"edit"` - `"read"` - `"write"` - `"glob"` - `"grep"` - `"web_fetch"` - `"web_search"` - `enabled?: boolean | null` Whether this tool is enabled and available to Claude. Overrides the default_config setting. - `permission_policy?: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy | null` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `"always_allow"` - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "always_ask"` - `"always_ask"` - `default_config?: BetaManagedAgentsAgentToolsetDefaultConfigParams | null` Default configuration for all tools in a toolset. - `enabled?: boolean | null` Whether tools are enabled and available to Claude by default. Defaults to true if not specified. - `permission_policy?: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy | null` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. ### Beta Managed Agents Agent Toolset20260401 Read Input - `BetaManagedAgentsAgentToolset20260401ReadInput` Input payload for the `read` tool. Reads file contents relative to the runner's working directory (or absolute when the runner permits). - `file_path: string` Path of the file to read. - `view_range?: Array` Optional `[start_line, end_line]` 1-indexed inclusive range. When omitted the entire file is returned. `end_line` of 0 or negative means "to end of file". ### Beta Managed Agents Agent Toolset20260401 Write Input - `BetaManagedAgentsAgentToolset20260401WriteInput` Input payload for the `write` tool. Writes (overwriting) the entire file contents. - `content: string` Full file contents to write. - `file_path: string` Path of the file to write. ### Beta Managed Agents Always Allow Policy - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `"always_allow"` ### Beta Managed Agents Always Ask Policy - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "always_ask"` - `"always_ask"` ### Beta Managed Agents Anthropic Skill - `BetaManagedAgentsAnthropicSkill` A resolved Anthropic-managed skill. - `skill_id: string` - `type: "anthropic"` - `"anthropic"` - `version: string` ### Beta Managed Agents Anthropic Skill Params - `BetaManagedAgentsAnthropicSkillParams` An Anthropic-managed skill. - `skill_id: string` Identifier of the Anthropic skill (e.g., "xlsx"). - `type: "anthropic"` - `"anthropic"` - `version?: string | null` Version to pin. Defaults to latest if omitted. ### Beta Managed Agents Custom Skill - `BetaManagedAgentsCustomSkill` A resolved user-created custom skill. - `skill_id: string` - `type: "custom"` - `"custom"` - `version: string` ### Beta Managed Agents Custom Skill Params - `BetaManagedAgentsCustomSkillParams` A user-created custom skill. - `skill_id: string` Tagged ID of the custom skill (e.g., "skill_01XJ5..."). - `type: "custom"` - `"custom"` - `version?: string | null` Version to pin. Defaults to latest if omitted. ### Beta Managed Agents Custom Tool - `BetaManagedAgentsCustomTool` A custom tool as returned in API responses. - `description: string` - `input_schema: BetaManagedAgentsCustomToolInputSchema` JSON Schema for custom tool input parameters. - `properties?: Record | null` JSON Schema properties defining the tool's input parameters. - `required?: Array` List of required property names. - `type?: "object"` Must be 'object' for tool input schemas. - `"object"` - `name: string` - `type: "custom"` - `"custom"` ### Beta Managed Agents Custom Tool Input Schema - `BetaManagedAgentsCustomToolInputSchema` JSON Schema for custom tool input parameters. - `properties?: Record | null` JSON Schema properties defining the tool's input parameters. - `required?: Array` List of required property names. - `type?: "object"` Must be 'object' for tool input schemas. - `"object"` ### Beta Managed Agents Custom Tool Params - `BetaManagedAgentsCustomToolParams` A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an `agent.custom_tool_use` event is emitted and the session goes idle, waiting for the client to provide the result via a `user.custom_tool_result` event. - `description: string` Description of what the tool does, shown to the agent to help it decide when to use the tool. 1-1024 characters. - `input_schema: BetaManagedAgentsCustomToolInputSchema` JSON Schema for custom tool input parameters. - `properties?: Record | null` JSON Schema properties defining the tool's input parameters. - `required?: Array` List of required property names. - `type?: "object"` Must be 'object' for tool input schemas. - `"object"` - `name: string` Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens. - `type: "custom"` - `"custom"` ### Beta Managed Agents MCP Server URL Definition - `BetaManagedAgentsMCPServerURLDefinition` URL-based MCP server connection as returned in API responses. - `name: string` - `type: "url"` - `"url"` - `url: string` ### Beta Managed Agents MCP Tool Config - `BetaManagedAgentsMCPToolConfig` Resolved configuration for a specific MCP tool. - `enabled: boolean` - `name: string` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `"always_allow"` - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "always_ask"` - `"always_ask"` ### Beta Managed Agents MCP Tool Config Params - `BetaManagedAgentsMCPToolConfigParams` Configuration override for a specific MCP tool. - `name: string` Name of the MCP tool to configure. 1-128 characters. - `enabled?: boolean | null` Whether this tool is enabled. Overrides the `default_config` setting. - `permission_policy?: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy | null` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `"always_allow"` - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "always_ask"` - `"always_ask"` ### Beta Managed Agents MCP Toolset - `BetaManagedAgentsMCPToolset` - `configs: Array` - `enabled: boolean` - `name: string` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `"always_allow"` - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "always_ask"` - `"always_ask"` - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` Resolved default configuration for all tools from an MCP server. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `mcp_server_name: string` - `type: "mcp_toolset"` - `"mcp_toolset"` ### Beta Managed Agents MCP Toolset Default Config - `BetaManagedAgentsMCPToolsetDefaultConfig` Resolved default configuration for all tools from an MCP server. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `"always_allow"` - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "always_ask"` - `"always_ask"` ### Beta Managed Agents MCP Toolset Default Config Params - `BetaManagedAgentsMCPToolsetDefaultConfigParams` Default configuration for all tools from an MCP server. - `enabled?: boolean | null` Whether tools are enabled by default. Defaults to true if not specified. - `permission_policy?: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy | null` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `"always_allow"` - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "always_ask"` - `"always_ask"` ### Beta Managed Agents MCP Toolset Params - `BetaManagedAgentsMCPToolsetParams` Configuration for tools from an MCP server defined in `mcp_servers`. - `mcp_server_name: string` Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters. - `type: "mcp_toolset"` - `"mcp_toolset"` - `configs?: Array` Per-tool configuration overrides. - `name: string` Name of the MCP tool to configure. 1-128 characters. - `enabled?: boolean | null` Whether this tool is enabled. Overrides the `default_config` setting. - `permission_policy?: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy | null` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `"always_allow"` - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "always_ask"` - `"always_ask"` - `default_config?: BetaManagedAgentsMCPToolsetDefaultConfigParams | null` Default configuration for all tools from an MCP server. - `enabled?: boolean | null` Whether tools are enabled by default. Defaults to true if not specified. - `permission_policy?: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy | null` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. ### Beta Managed Agents Model - `BetaManagedAgentsModel = "claude-opus-4-8" | "claude-opus-4-7" | "claude-opus-4-6" | 7 more | (string & {})` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-opus-4-8" | "claude-opus-4-7" | "claude-opus-4-6" | 7 more` - `"claude-opus-4-8"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-7"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-6"` Most intelligent model for building agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` Fastest model with near-frontier intelligence - `"claude-haiku-4-5-20251001"` Fastest model with near-frontier intelligence - `"claude-opus-4-5"` Premium model combining maximum intelligence with practical performance - `"claude-opus-4-5-20251101"` Premium model combining maximum intelligence with practical performance - `"claude-sonnet-4-5"` High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` High-performance model for agents and coding - `(string & {})` ### Beta Managed Agents Model Config - `BetaManagedAgentsModelConfig` Model identifier and configuration. - `id: BetaManagedAgentsModel` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-opus-4-8" | "claude-opus-4-7" | "claude-opus-4-6" | 7 more` - `"claude-opus-4-8"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-7"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-6"` Most intelligent model for building agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` Fastest model with near-frontier intelligence - `"claude-haiku-4-5-20251001"` Fastest model with near-frontier intelligence - `"claude-opus-4-5"` Premium model combining maximum intelligence with practical performance - `"claude-opus-4-5-20251101"` Premium model combining maximum intelligence with practical performance - `"claude-sonnet-4-5"` High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` High-performance model for agents and coding - `(string & {})` - `speed?: "standard" | "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` ### Beta Managed Agents Model Config Params - `BetaManagedAgentsModelConfigParams` An object that defines additional configuration control over model use - `id: BetaManagedAgentsModel` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-opus-4-8" | "claude-opus-4-7" | "claude-opus-4-6" | 7 more` - `"claude-opus-4-8"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-7"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-6"` Most intelligent model for building agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` Fastest model with near-frontier intelligence - `"claude-haiku-4-5-20251001"` Fastest model with near-frontier intelligence - `"claude-opus-4-5"` Premium model combining maximum intelligence with practical performance - `"claude-opus-4-5-20251101"` Premium model combining maximum intelligence with practical performance - `"claude-sonnet-4-5"` High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` High-performance model for agents and coding - `(string & {})` - `speed?: "standard" | "fast" | null` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` ### Beta Managed Agents Multiagent Coordinator - `BetaManagedAgentsMultiagentCoordinator` Resolved coordinator topology with a concrete agent roster. - `agents: Array` Agents the coordinator may spawn as session threads, each resolved to a specific version. - `id: string` - `type: "agent"` - `"agent"` - `version: number` - `type: "coordinator"` - `"coordinator"` ### Beta Managed Agents Multiagent Coordinator Params - `BetaManagedAgentsMultiagentCoordinatorParams` A coordinator topology: the session's primary thread orchestrates work by spawning session threads, each running an agent drawn from the `agents` roster. - `agents: Array` Agents the coordinator may spawn as session threads. 1–20 entries. Each entry is an agent ID string, a versioned `{"type":"agent","id","version"}` reference, or `{"type":"self"}` to allow recursive self-invocation. Entries must reference distinct agents (after resolving `self` and string forms); at most one `self`. Referenced agents must exist, must not be archived, and must not themselves have `multiagent` set (depth limit 1). - `string` - `BetaManagedAgentsAgentParams` Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version - `id: string` The `agent` ID. - `type: "agent"` - `"agent"` - `version?: number` The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified. - `BetaManagedAgentsMultiagentSelfParams` Sentinel roster entry meaning "the agent that owns this configuration". Resolved server-side to a concrete agent reference. - `type: "self"` - `"self"` - `type: "coordinator"` - `"coordinator"` ### Beta Managed Agents Multiagent Self Params - `BetaManagedAgentsMultiagentSelfParams` Sentinel roster entry meaning "the agent that owns this configuration". Resolved server-side to a concrete agent reference. - `type: "self"` - `"self"` ### Beta Managed Agents Session Thread Agent - `BetaManagedAgentsSessionThreadAgent` Resolved `agent` definition for a single `session_thread`. Snapshot of the agent at thread creation time. The multiagent roster is not repeated here; read it from `Session.agent`. - `id: string` - `description: string | null` - `mcp_servers: Array` - `name: string` - `type: "url"` - `"url"` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `id: BetaManagedAgentsModel` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-opus-4-8" | "claude-opus-4-7" | "claude-opus-4-6" | 7 more` - `"claude-opus-4-8"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-7"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-6"` Most intelligent model for building agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` Fastest model with near-frontier intelligence - `"claude-haiku-4-5-20251001"` Fastest model with near-frontier intelligence - `"claude-opus-4-5"` Premium model combining maximum intelligence with practical performance - `"claude-opus-4-5-20251101"` Premium model combining maximum intelligence with practical performance - `"claude-sonnet-4-5"` High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` High-performance model for agents and coding - `(string & {})` - `speed?: "standard" | "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `name: string` - `skills: Array` - `BetaManagedAgentsAnthropicSkill` A resolved Anthropic-managed skill. - `skill_id: string` - `type: "anthropic"` - `"anthropic"` - `version: string` - `BetaManagedAgentsCustomSkill` A resolved user-created custom skill. - `skill_id: string` - `type: "custom"` - `"custom"` - `version: string` - `system: string | null` - `tools: Array` - `BetaManagedAgentsAgentToolset20260401` - `configs: Array` - `enabled: boolean` - `name: "bash" | "edit" | "read" | 5 more` Built-in agent tool identifier. - `"bash"` - `"edit"` - `"read"` - `"write"` - `"glob"` - `"grep"` - `"web_fetch"` - `"web_search"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `"always_allow"` - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "always_ask"` - `"always_ask"` - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` Resolved default configuration for agent tools. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "agent_toolset_20260401"` - `"agent_toolset_20260401"` - `BetaManagedAgentsMCPToolset` - `configs: Array` - `enabled: boolean` - `name: string` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` Resolved default configuration for all tools from an MCP server. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `mcp_server_name: string` - `type: "mcp_toolset"` - `"mcp_toolset"` - `BetaManagedAgentsCustomTool` A custom tool as returned in API responses. - `description: string` - `input_schema: BetaManagedAgentsCustomToolInputSchema` JSON Schema for custom tool input parameters. - `properties?: Record | null` JSON Schema properties defining the tool's input parameters. - `required?: Array` List of required property names. - `type?: "object"` Must be 'object' for tool input schemas. - `"object"` - `name: string` - `type: "custom"` - `"custom"` - `type: "agent"` - `"agent"` - `version: number` ### Beta Managed Agents Skill Params - `BetaManagedAgentsSkillParams = BetaManagedAgentsAnthropicSkillParams | BetaManagedAgentsCustomSkillParams` Skill to load in the session container. - `BetaManagedAgentsAnthropicSkillParams` An Anthropic-managed skill. - `skill_id: string` Identifier of the Anthropic skill (e.g., "xlsx"). - `type: "anthropic"` - `"anthropic"` - `version?: string | null` Version to pin. Defaults to latest if omitted. - `BetaManagedAgentsCustomSkillParams` A user-created custom skill. - `skill_id: string` Tagged ID of the custom skill (e.g., "skill_01XJ5..."). - `type: "custom"` - `"custom"` - `version?: string | null` Version to pin. Defaults to latest if omitted. ### Beta Managed Agents URL MCP Server Params - `BetaManagedAgentsURLMCPServerParams` URL-based MCP server connection. - `name: string` Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters. - `type: "url"` - `"url"` - `url: string` Endpoint URL for the MCP server. # Versions ## List Agent Versions `client.beta.agents.versions.list(stringagentID, VersionListParamsparams?, RequestOptionsoptions?): PageCursor` **get** `/v1/agents/{agent_id}/versions` List Agent Versions ### Parameters - `agentID: string` - `params: VersionListParams` - `limit?: number` Query param: Maximum results per page. Default 20, maximum 100. - `page?: string` Query param: Opaque pagination cursor. - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaManagedAgentsAgent` A Managed Agents `agent`. - `id: string` - `archived_at: string | null` A timestamp in RFC 3339 format - `created_at: string` A timestamp in RFC 3339 format - `description: string | null` - `mcp_servers: Array` - `name: string` - `type: "url"` - `"url"` - `url: string` - `metadata: Record` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `id: BetaManagedAgentsModel` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-opus-4-8" | "claude-opus-4-7" | "claude-opus-4-6" | 7 more` - `"claude-opus-4-8"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-7"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-6"` Most intelligent model for building agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` Fastest model with near-frontier intelligence - `"claude-haiku-4-5-20251001"` Fastest model with near-frontier intelligence - `"claude-opus-4-5"` Premium model combining maximum intelligence with practical performance - `"claude-opus-4-5-20251101"` Premium model combining maximum intelligence with practical performance - `"claude-sonnet-4-5"` High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` High-performance model for agents and coding - `(string & {})` - `speed?: "standard" | "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `multiagent: BetaManagedAgentsMultiagent | null` Resolved coordinator topology with a concrete agent roster. - `agents: Array` Agents the coordinator may spawn as session threads, each resolved to a specific version. - `id: string` - `type: "agent"` - `"agent"` - `version: number` - `type: "coordinator"` - `"coordinator"` - `name: string` - `skills: Array` - `BetaManagedAgentsAnthropicSkill` A resolved Anthropic-managed skill. - `skill_id: string` - `type: "anthropic"` - `"anthropic"` - `version: string` - `BetaManagedAgentsCustomSkill` A resolved user-created custom skill. - `skill_id: string` - `type: "custom"` - `"custom"` - `version: string` - `system: string | null` - `tools: Array` - `BetaManagedAgentsAgentToolset20260401` - `configs: Array` - `enabled: boolean` - `name: "bash" | "edit" | "read" | 5 more` Built-in agent tool identifier. - `"bash"` - `"edit"` - `"read"` - `"write"` - `"glob"` - `"grep"` - `"web_fetch"` - `"web_search"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `"always_allow"` - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "always_ask"` - `"always_ask"` - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` Resolved default configuration for agent tools. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "agent_toolset_20260401"` - `"agent_toolset_20260401"` - `BetaManagedAgentsMCPToolset` - `configs: Array` - `enabled: boolean` - `name: string` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` Resolved default configuration for all tools from an MCP server. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `mcp_server_name: string` - `type: "mcp_toolset"` - `"mcp_toolset"` - `BetaManagedAgentsCustomTool` A custom tool as returned in API responses. - `description: string` - `input_schema: BetaManagedAgentsCustomToolInputSchema` JSON Schema for custom tool input parameters. - `properties?: Record | null` JSON Schema properties defining the tool's input parameters. - `required?: Array` List of required property names. - `type?: "object"` Must be 'object' for tool input schemas. - `"object"` - `name: string` - `type: "custom"` - `"custom"` - `type: "agent"` - `"agent"` - `updated_at: string` A timestamp in RFC 3339 format - `version: number` The agent's current version. Starts at 1 and increments when the agent is modified. ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); // Automatically fetches more pages as needed. for await (const betaManagedAgentsAgent of client.beta.agents.versions.list( 'agent_011CZkYpogX7uDKUyvBTophP', )) { console.log(betaManagedAgentsAgent.id); } ``` #### Response ```json { "data": [ { "id": "agent_011CZkYpogX7uDKUyvBTophP", "archived_at": null, "created_at": "2026-03-15T10:00:00Z", "description": "A general-purpose starter agent.", "mcp_servers": [ { "name": "example-mcp", "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse" } ], "metadata": { "foo": "bar" }, "model": { "id": "claude-sonnet-4-6", "speed": "standard" }, "multiagent": { "agents": [ { "id": "agent_011CZkYqphY8vELVzwCUpqiQ", "type": "agent", "version": 1 } ], "type": "coordinator" }, "name": "My First Agent", "skills": [ { "skill_id": "xlsx", "type": "anthropic", "version": "1" }, { "skill_id": "skill_011CZkZFNu9hAbo3jZPRgTlx", "type": "custom", "version": "2" } ], "system": "You are a general-purpose agent that can research, write code, run commands, and use connected tools to complete the user's task end to end.", "tools": [ { "configs": [ { "enabled": true, "name": "bash", "permission_policy": { "type": "always_allow" } } ], "default_config": { "enabled": true, "permission_policy": { "type": "always_ask" } }, "type": "agent_toolset_20260401" } ], "type": "agent", "updated_at": "2026-03-15T10:00:00Z", "version": 1 } ], "next_page": "next_page" } ``` # Environments ## Create Environment `client.beta.environments.create(EnvironmentCreateParamsparams, RequestOptionsoptions?): BetaEnvironment` **post** `/v1/environments` Create a new environment with the specified configuration. ### Parameters - `params: EnvironmentCreateParams` - `name: string` Body param: Human-readable name for the environment - `config?: BetaCloudConfigParams | BetaSelfHostedConfigParams | null` Body param: Environment configuration - `BetaCloudConfigParams` Request params for `cloud` environment configuration. Fields default to null; on update, omitted fields preserve the existing value. - `type: "cloud"` Environment type - `"cloud"` - `networking?: BetaUnrestrictedNetwork | BetaLimitedNetworkParams | null` Network configuration policy. Omit on update to preserve the existing value. - `BetaUnrestrictedNetwork` Unrestricted network access. - `type: "unrestricted"` Network policy type - `"unrestricted"` - `BetaLimitedNetworkParams` Limited network request params. Fields default to null; on update, omitted fields preserve the existing value. - `type: "limited"` Network policy type - `"limited"` - `allow_mcp_servers?: boolean | null` Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. Defaults to `false`. - `allow_package_managers?: boolean | null` Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. Defaults to `false`. - `allowed_hosts?: Array | null` Specifies domains the container can reach. - `packages?: BetaPackagesParams | null` Specify packages (and optionally their versions) available in this environment. When versioning, use the version semantics relevant for the package manager, e.g. for `pip` use `package==1.0.0`. You are responsible for validating the package and version exist. Unversioned installs the latest. - `apt?: Array | null` Ubuntu/Debian packages to install - `cargo?: Array | null` Rust packages to install - `gem?: Array | null` Ruby packages to install - `go?: Array | null` Go packages to install - `npm?: Array | null` Node.js packages to install - `pip?: Array | null` Python packages to install - `type?: "packages"` Package configuration type - `"packages"` - `BetaSelfHostedConfigParams` Request params for `self_hosted` environment configuration. - `type: "self_hosted"` Environment type - `"self_hosted"` - `description?: string | null` Body param: Optional description of the environment - `metadata?: Record` Body param: User-provided metadata key-value pairs - `scope?: "organization" | "account" | null` Body param: The visibility scope for this environment. 'organization' makes the environment visible to all accounts. 'account' restricts visibility to the owning account only. Only applicable for self-hosted environments. If not specified, defaults based on organization type. - `"organization"` - `"account"` - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaEnvironment` Unified Environment resource for both cloud and self-hosted environments. - `id: string` Environment identifier (e.g., 'env_...') - `archived_at: string | null` RFC 3339 timestamp when environment was archived, or null if not archived - `config: BetaCloudConfig | BetaSelfHostedConfig` Environment configuration (either Anthropic Cloud or self-hosted) - `BetaCloudConfig` `cloud` environment configuration. - `networking: BetaUnrestrictedNetwork | BetaLimitedNetwork` Network configuration policy. - `BetaUnrestrictedNetwork` Unrestricted network access. - `type: "unrestricted"` Network policy type - `"unrestricted"` - `BetaLimitedNetwork` Limited network access. - `allow_mcp_servers: boolean` Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. - `allow_package_managers: boolean` Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. - `allowed_hosts: Array` Specifies domains the container can reach. - `type: "limited"` Network policy type - `"limited"` - `packages: BetaPackages` Package manager configuration. - `apt: Array` Ubuntu/Debian packages to install - `cargo: Array` Rust packages to install - `gem: Array` Ruby packages to install - `go: Array` Go packages to install - `npm: Array` Node.js packages to install - `pip: Array` Python packages to install - `type?: "packages"` Package configuration type - `"packages"` - `type: "cloud"` Environment type - `"cloud"` - `BetaSelfHostedConfig` Configuration for self-hosted environments. - `type: "self_hosted"` Environment type - `"self_hosted"` - `created_at: string` RFC 3339 timestamp when environment was created - `description: string` User-provided description for the environment - `metadata: Record` User-provided metadata key-value pairs - `name: string` Human-readable name for the environment - `type: "environment"` The type of object (always 'environment') - `"environment"` - `updated_at: string` RFC 3339 timestamp when environment was last updated - `scope?: "organization" | "account"` The visibility scope for this environment. 'organization' means visible to all accounts. 'account' means visible only to the owning account. - `"organization"` - `"account"` ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const betaEnvironment = await client.beta.environments.create({ name: 'python-data-analysis' }); console.log(betaEnvironment.id); ``` #### Response ```json { "id": "env_011CZkZ9X2dpNyB7HsEFoRfW", "archived_at": null, "config": { "networking": { "allow_mcp_servers": false, "allow_package_managers": true, "allowed_hosts": [ "api.example.com" ], "type": "limited" }, "packages": { "apt": [ "string" ], "cargo": [ "string" ], "gem": [ "string" ], "go": [ "string" ], "npm": [ "string" ], "pip": [ "pandas", "numpy" ], "type": "packages" }, "type": "cloud" }, "created_at": "2026-03-15T10:00:00Z", "description": "Python environment with data-analysis packages.", "metadata": {}, "name": "python-data-analysis", "type": "environment", "updated_at": "2026-03-15T10:00:00Z", "scope": "organization" } ``` ## List Environments `client.beta.environments.list(EnvironmentListParamsparams?, RequestOptionsoptions?): PageCursor` **get** `/v1/environments` List environments with pagination support. ### Parameters - `params: EnvironmentListParams` - `include_archived?: boolean` Query param: Include archived environments in the response - `limit?: number` Query param: Maximum number of environments to return - `page?: string | null` Query param: Opaque cursor from previous response for pagination. Pass the `next_page` value from the previous response. - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaEnvironment` Unified Environment resource for both cloud and self-hosted environments. - `id: string` Environment identifier (e.g., 'env_...') - `archived_at: string | null` RFC 3339 timestamp when environment was archived, or null if not archived - `config: BetaCloudConfig | BetaSelfHostedConfig` Environment configuration (either Anthropic Cloud or self-hosted) - `BetaCloudConfig` `cloud` environment configuration. - `networking: BetaUnrestrictedNetwork | BetaLimitedNetwork` Network configuration policy. - `BetaUnrestrictedNetwork` Unrestricted network access. - `type: "unrestricted"` Network policy type - `"unrestricted"` - `BetaLimitedNetwork` Limited network access. - `allow_mcp_servers: boolean` Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. - `allow_package_managers: boolean` Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. - `allowed_hosts: Array` Specifies domains the container can reach. - `type: "limited"` Network policy type - `"limited"` - `packages: BetaPackages` Package manager configuration. - `apt: Array` Ubuntu/Debian packages to install - `cargo: Array` Rust packages to install - `gem: Array` Ruby packages to install - `go: Array` Go packages to install - `npm: Array` Node.js packages to install - `pip: Array` Python packages to install - `type?: "packages"` Package configuration type - `"packages"` - `type: "cloud"` Environment type - `"cloud"` - `BetaSelfHostedConfig` Configuration for self-hosted environments. - `type: "self_hosted"` Environment type - `"self_hosted"` - `created_at: string` RFC 3339 timestamp when environment was created - `description: string` User-provided description for the environment - `metadata: Record` User-provided metadata key-value pairs - `name: string` Human-readable name for the environment - `type: "environment"` The type of object (always 'environment') - `"environment"` - `updated_at: string` RFC 3339 timestamp when environment was last updated - `scope?: "organization" | "account"` The visibility scope for this environment. 'organization' means visible to all accounts. 'account' means visible only to the owning account. - `"organization"` - `"account"` ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); // Automatically fetches more pages as needed. for await (const betaEnvironment of client.beta.environments.list()) { console.log(betaEnvironment.id); } ``` #### Response ```json { "data": [ { "id": "env_011CZkZ9X2dpNyB7HsEFoRfW", "archived_at": null, "config": { "networking": { "allow_mcp_servers": false, "allow_package_managers": true, "allowed_hosts": [ "api.example.com" ], "type": "limited" }, "packages": { "apt": [ "string" ], "cargo": [ "string" ], "gem": [ "string" ], "go": [ "string" ], "npm": [ "string" ], "pip": [ "pandas", "numpy" ], "type": "packages" }, "type": "cloud" }, "created_at": "2026-03-15T10:00:00Z", "description": "Python environment with data-analysis packages.", "metadata": {}, "name": "python-data-analysis", "type": "environment", "updated_at": "2026-03-15T10:00:00Z", "scope": "organization" } ], "next_page": "page_MjAyNS0wNS0xNFQwMDowMDowMFo=" } ``` ## Get Environment `client.beta.environments.retrieve(stringenvironmentID, EnvironmentRetrieveParamsparams?, RequestOptionsoptions?): BetaEnvironment` **get** `/v1/environments/{environment_id}` Retrieve a specific environment by ID. ### Parameters - `environmentID: string` - `params: EnvironmentRetrieveParams` - `betas?: Array` Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaEnvironment` Unified Environment resource for both cloud and self-hosted environments. - `id: string` Environment identifier (e.g., 'env_...') - `archived_at: string | null` RFC 3339 timestamp when environment was archived, or null if not archived - `config: BetaCloudConfig | BetaSelfHostedConfig` Environment configuration (either Anthropic Cloud or self-hosted) - `BetaCloudConfig` `cloud` environment configuration. - `networking: BetaUnrestrictedNetwork | BetaLimitedNetwork` Network configuration policy. - `BetaUnrestrictedNetwork` Unrestricted network access. - `type: "unrestricted"` Network policy type - `"unrestricted"` - `BetaLimitedNetwork` Limited network access. - `allow_mcp_servers: boolean` Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. - `allow_package_managers: boolean` Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. - `allowed_hosts: Array` Specifies domains the container can reach. - `type: "limited"` Network policy type - `"limited"` - `packages: BetaPackages` Package manager configuration. - `apt: Array` Ubuntu/Debian packages to install - `cargo: Array` Rust packages to install - `gem: Array` Ruby packages to install - `go: Array` Go packages to install - `npm: Array` Node.js packages to install - `pip: Array` Python packages to install - `type?: "packages"` Package configuration type - `"packages"` - `type: "cloud"` Environment type - `"cloud"` - `BetaSelfHostedConfig` Configuration for self-hosted environments. - `type: "self_hosted"` Environment type - `"self_hosted"` - `created_at: string` RFC 3339 timestamp when environment was created - `description: string` User-provided description for the environment - `metadata: Record` User-provided metadata key-value pairs - `name: string` Human-readable name for the environment - `type: "environment"` The type of object (always 'environment') - `"environment"` - `updated_at: string` RFC 3339 timestamp when environment was last updated - `scope?: "organization" | "account"` The visibility scope for this environment. 'organization' means visible to all accounts. 'account' means visible only to the owning account. - `"organization"` - `"account"` ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const betaEnvironment = await client.beta.environments.retrieve('env_011CZkZ9X2dpNyB7HsEFoRfW'); console.log(betaEnvironment.id); ``` #### Response ```json { "id": "env_011CZkZ9X2dpNyB7HsEFoRfW", "archived_at": null, "config": { "networking": { "allow_mcp_servers": false, "allow_package_managers": true, "allowed_hosts": [ "api.example.com" ], "type": "limited" }, "packages": { "apt": [ "string" ], "cargo": [ "string" ], "gem": [ "string" ], "go": [ "string" ], "npm": [ "string" ], "pip": [ "pandas", "numpy" ], "type": "packages" }, "type": "cloud" }, "created_at": "2026-03-15T10:00:00Z", "description": "Python environment with data-analysis packages.", "metadata": {}, "name": "python-data-analysis", "type": "environment", "updated_at": "2026-03-15T10:00:00Z", "scope": "organization" } ``` ## Update Environment `client.beta.environments.update(stringenvironmentID, EnvironmentUpdateParamsparams, RequestOptionsoptions?): BetaEnvironment` **post** `/v1/environments/{environment_id}` Update an existing environment's configuration. ### Parameters - `environmentID: string` - `params: EnvironmentUpdateParams` - `config?: BetaCloudConfigParams | BetaSelfHostedConfigParams | null` Body param: Updated environment configuration - `BetaCloudConfigParams` Request params for `cloud` environment configuration. Fields default to null; on update, omitted fields preserve the existing value. - `type: "cloud"` Environment type - `"cloud"` - `networking?: BetaUnrestrictedNetwork | BetaLimitedNetworkParams | null` Network configuration policy. Omit on update to preserve the existing value. - `BetaUnrestrictedNetwork` Unrestricted network access. - `type: "unrestricted"` Network policy type - `"unrestricted"` - `BetaLimitedNetworkParams` Limited network request params. Fields default to null; on update, omitted fields preserve the existing value. - `type: "limited"` Network policy type - `"limited"` - `allow_mcp_servers?: boolean | null` Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. Defaults to `false`. - `allow_package_managers?: boolean | null` Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. Defaults to `false`. - `allowed_hosts?: Array | null` Specifies domains the container can reach. - `packages?: BetaPackagesParams | null` Specify packages (and optionally their versions) available in this environment. When versioning, use the version semantics relevant for the package manager, e.g. for `pip` use `package==1.0.0`. You are responsible for validating the package and version exist. Unversioned installs the latest. - `apt?: Array | null` Ubuntu/Debian packages to install - `cargo?: Array | null` Rust packages to install - `gem?: Array | null` Ruby packages to install - `go?: Array | null` Go packages to install - `npm?: Array | null` Node.js packages to install - `pip?: Array | null` Python packages to install - `type?: "packages"` Package configuration type - `"packages"` - `BetaSelfHostedConfigParams` Request params for `self_hosted` environment configuration. - `type: "self_hosted"` Environment type - `"self_hosted"` - `description?: string | null` Body param: Updated description of the environment - `metadata?: Record` Body param: User-provided metadata key-value pairs. Set a value to null or empty string to delete the key. - `name?: string | null` Body param: Updated name for the environment - `scope?: "organization" | "account" | null` Body param: The visibility scope for this environment. 'organization' makes the environment visible to all accounts. 'account' restricts visibility to the owning account only. - `"organization"` - `"account"` - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaEnvironment` Unified Environment resource for both cloud and self-hosted environments. - `id: string` Environment identifier (e.g., 'env_...') - `archived_at: string | null` RFC 3339 timestamp when environment was archived, or null if not archived - `config: BetaCloudConfig | BetaSelfHostedConfig` Environment configuration (either Anthropic Cloud or self-hosted) - `BetaCloudConfig` `cloud` environment configuration. - `networking: BetaUnrestrictedNetwork | BetaLimitedNetwork` Network configuration policy. - `BetaUnrestrictedNetwork` Unrestricted network access. - `type: "unrestricted"` Network policy type - `"unrestricted"` - `BetaLimitedNetwork` Limited network access. - `allow_mcp_servers: boolean` Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. - `allow_package_managers: boolean` Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. - `allowed_hosts: Array` Specifies domains the container can reach. - `type: "limited"` Network policy type - `"limited"` - `packages: BetaPackages` Package manager configuration. - `apt: Array` Ubuntu/Debian packages to install - `cargo: Array` Rust packages to install - `gem: Array` Ruby packages to install - `go: Array` Go packages to install - `npm: Array` Node.js packages to install - `pip: Array` Python packages to install - `type?: "packages"` Package configuration type - `"packages"` - `type: "cloud"` Environment type - `"cloud"` - `BetaSelfHostedConfig` Configuration for self-hosted environments. - `type: "self_hosted"` Environment type - `"self_hosted"` - `created_at: string` RFC 3339 timestamp when environment was created - `description: string` User-provided description for the environment - `metadata: Record` User-provided metadata key-value pairs - `name: string` Human-readable name for the environment - `type: "environment"` The type of object (always 'environment') - `"environment"` - `updated_at: string` RFC 3339 timestamp when environment was last updated - `scope?: "organization" | "account"` The visibility scope for this environment. 'organization' means visible to all accounts. 'account' means visible only to the owning account. - `"organization"` - `"account"` ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const betaEnvironment = await client.beta.environments.update('env_011CZkZ9X2dpNyB7HsEFoRfW'); console.log(betaEnvironment.id); ``` #### Response ```json { "id": "env_011CZkZ9X2dpNyB7HsEFoRfW", "archived_at": null, "config": { "networking": { "allow_mcp_servers": false, "allow_package_managers": true, "allowed_hosts": [ "api.example.com" ], "type": "limited" }, "packages": { "apt": [ "string" ], "cargo": [ "string" ], "gem": [ "string" ], "go": [ "string" ], "npm": [ "string" ], "pip": [ "pandas", "numpy" ], "type": "packages" }, "type": "cloud" }, "created_at": "2026-03-15T10:00:00Z", "description": "Python environment with data-analysis packages.", "metadata": {}, "name": "python-data-analysis", "type": "environment", "updated_at": "2026-03-15T10:00:00Z", "scope": "organization" } ``` ## Delete Environment `client.beta.environments.delete(stringenvironmentID, EnvironmentDeleteParamsparams?, RequestOptionsoptions?): BetaEnvironmentDeleteResponse` **delete** `/v1/environments/{environment_id}` Delete an environment by ID. Returns a confirmation of the deletion. ### Parameters - `environmentID: string` - `params: EnvironmentDeleteParams` - `betas?: Array` Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaEnvironmentDeleteResponse` Response after deleting an environment. - `id: string` Environment identifier - `type: "environment_deleted"` The type of response - `"environment_deleted"` ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const betaEnvironmentDeleteResponse = await client.beta.environments.delete( 'env_011CZkZ9X2dpNyB7HsEFoRfW', ); console.log(betaEnvironmentDeleteResponse.id); ``` #### Response ```json { "id": "env_011CZkZ9X2dpNyB7HsEFoRfW", "type": "environment_deleted" } ``` ## Archive Environment `client.beta.environments.archive(stringenvironmentID, EnvironmentArchiveParamsparams?, RequestOptionsoptions?): BetaEnvironment` **post** `/v1/environments/{environment_id}/archive` Archive an environment by ID. Archived environments cannot be used to create new sessions. ### Parameters - `environmentID: string` - `params: EnvironmentArchiveParams` - `betas?: Array` Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaEnvironment` Unified Environment resource for both cloud and self-hosted environments. - `id: string` Environment identifier (e.g., 'env_...') - `archived_at: string | null` RFC 3339 timestamp when environment was archived, or null if not archived - `config: BetaCloudConfig | BetaSelfHostedConfig` Environment configuration (either Anthropic Cloud or self-hosted) - `BetaCloudConfig` `cloud` environment configuration. - `networking: BetaUnrestrictedNetwork | BetaLimitedNetwork` Network configuration policy. - `BetaUnrestrictedNetwork` Unrestricted network access. - `type: "unrestricted"` Network policy type - `"unrestricted"` - `BetaLimitedNetwork` Limited network access. - `allow_mcp_servers: boolean` Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. - `allow_package_managers: boolean` Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. - `allowed_hosts: Array` Specifies domains the container can reach. - `type: "limited"` Network policy type - `"limited"` - `packages: BetaPackages` Package manager configuration. - `apt: Array` Ubuntu/Debian packages to install - `cargo: Array` Rust packages to install - `gem: Array` Ruby packages to install - `go: Array` Go packages to install - `npm: Array` Node.js packages to install - `pip: Array` Python packages to install - `type?: "packages"` Package configuration type - `"packages"` - `type: "cloud"` Environment type - `"cloud"` - `BetaSelfHostedConfig` Configuration for self-hosted environments. - `type: "self_hosted"` Environment type - `"self_hosted"` - `created_at: string` RFC 3339 timestamp when environment was created - `description: string` User-provided description for the environment - `metadata: Record` User-provided metadata key-value pairs - `name: string` Human-readable name for the environment - `type: "environment"` The type of object (always 'environment') - `"environment"` - `updated_at: string` RFC 3339 timestamp when environment was last updated - `scope?: "organization" | "account"` The visibility scope for this environment. 'organization' means visible to all accounts. 'account' means visible only to the owning account. - `"organization"` - `"account"` ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const betaEnvironment = await client.beta.environments.archive('env_011CZkZ9X2dpNyB7HsEFoRfW'); console.log(betaEnvironment.id); ``` #### Response ```json { "id": "env_011CZkZ9X2dpNyB7HsEFoRfW", "archived_at": null, "config": { "networking": { "allow_mcp_servers": false, "allow_package_managers": true, "allowed_hosts": [ "api.example.com" ], "type": "limited" }, "packages": { "apt": [ "string" ], "cargo": [ "string" ], "gem": [ "string" ], "go": [ "string" ], "npm": [ "string" ], "pip": [ "pandas", "numpy" ], "type": "packages" }, "type": "cloud" }, "created_at": "2026-03-15T10:00:00Z", "description": "Python environment with data-analysis packages.", "metadata": {}, "name": "python-data-analysis", "type": "environment", "updated_at": "2026-03-15T10:00:00Z", "scope": "organization" } ``` ## Domain Types ### Beta Cloud Config - `BetaCloudConfig` `cloud` environment configuration. - `networking: BetaUnrestrictedNetwork | BetaLimitedNetwork` Network configuration policy. - `BetaUnrestrictedNetwork` Unrestricted network access. - `type: "unrestricted"` Network policy type - `"unrestricted"` - `BetaLimitedNetwork` Limited network access. - `allow_mcp_servers: boolean` Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. - `allow_package_managers: boolean` Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. - `allowed_hosts: Array` Specifies domains the container can reach. - `type: "limited"` Network policy type - `"limited"` - `packages: BetaPackages` Package manager configuration. - `apt: Array` Ubuntu/Debian packages to install - `cargo: Array` Rust packages to install - `gem: Array` Ruby packages to install - `go: Array` Go packages to install - `npm: Array` Node.js packages to install - `pip: Array` Python packages to install - `type?: "packages"` Package configuration type - `"packages"` - `type: "cloud"` Environment type - `"cloud"` ### Beta Cloud Config Params - `BetaCloudConfigParams` Request params for `cloud` environment configuration. Fields default to null; on update, omitted fields preserve the existing value. - `type: "cloud"` Environment type - `"cloud"` - `networking?: BetaUnrestrictedNetwork | BetaLimitedNetworkParams | null` Network configuration policy. Omit on update to preserve the existing value. - `BetaUnrestrictedNetwork` Unrestricted network access. - `type: "unrestricted"` Network policy type - `"unrestricted"` - `BetaLimitedNetworkParams` Limited network request params. Fields default to null; on update, omitted fields preserve the existing value. - `type: "limited"` Network policy type - `"limited"` - `allow_mcp_servers?: boolean | null` Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. Defaults to `false`. - `allow_package_managers?: boolean | null` Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. Defaults to `false`. - `allowed_hosts?: Array | null` Specifies domains the container can reach. - `packages?: BetaPackagesParams | null` Specify packages (and optionally their versions) available in this environment. When versioning, use the version semantics relevant for the package manager, e.g. for `pip` use `package==1.0.0`. You are responsible for validating the package and version exist. Unversioned installs the latest. - `apt?: Array | null` Ubuntu/Debian packages to install - `cargo?: Array | null` Rust packages to install - `gem?: Array | null` Ruby packages to install - `go?: Array | null` Go packages to install - `npm?: Array | null` Node.js packages to install - `pip?: Array | null` Python packages to install - `type?: "packages"` Package configuration type - `"packages"` ### Beta Environment - `BetaEnvironment` Unified Environment resource for both cloud and self-hosted environments. - `id: string` Environment identifier (e.g., 'env_...') - `archived_at: string | null` RFC 3339 timestamp when environment was archived, or null if not archived - `config: BetaCloudConfig | BetaSelfHostedConfig` Environment configuration (either Anthropic Cloud or self-hosted) - `BetaCloudConfig` `cloud` environment configuration. - `networking: BetaUnrestrictedNetwork | BetaLimitedNetwork` Network configuration policy. - `BetaUnrestrictedNetwork` Unrestricted network access. - `type: "unrestricted"` Network policy type - `"unrestricted"` - `BetaLimitedNetwork` Limited network access. - `allow_mcp_servers: boolean` Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. - `allow_package_managers: boolean` Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. - `allowed_hosts: Array` Specifies domains the container can reach. - `type: "limited"` Network policy type - `"limited"` - `packages: BetaPackages` Package manager configuration. - `apt: Array` Ubuntu/Debian packages to install - `cargo: Array` Rust packages to install - `gem: Array` Ruby packages to install - `go: Array` Go packages to install - `npm: Array` Node.js packages to install - `pip: Array` Python packages to install - `type?: "packages"` Package configuration type - `"packages"` - `type: "cloud"` Environment type - `"cloud"` - `BetaSelfHostedConfig` Configuration for self-hosted environments. - `type: "self_hosted"` Environment type - `"self_hosted"` - `created_at: string` RFC 3339 timestamp when environment was created - `description: string` User-provided description for the environment - `metadata: Record` User-provided metadata key-value pairs - `name: string` Human-readable name for the environment - `type: "environment"` The type of object (always 'environment') - `"environment"` - `updated_at: string` RFC 3339 timestamp when environment was last updated - `scope?: "organization" | "account"` The visibility scope for this environment. 'organization' means visible to all accounts. 'account' means visible only to the owning account. - `"organization"` - `"account"` ### Beta Environment Delete Response - `BetaEnvironmentDeleteResponse` Response after deleting an environment. - `id: string` Environment identifier - `type: "environment_deleted"` The type of response - `"environment_deleted"` ### Beta Limited Network - `BetaLimitedNetwork` Limited network access. - `allow_mcp_servers: boolean` Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. - `allow_package_managers: boolean` Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. - `allowed_hosts: Array` Specifies domains the container can reach. - `type: "limited"` Network policy type - `"limited"` ### Beta Limited Network Params - `BetaLimitedNetworkParams` Limited network request params. Fields default to null; on update, omitted fields preserve the existing value. - `type: "limited"` Network policy type - `"limited"` - `allow_mcp_servers?: boolean | null` Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. Defaults to `false`. - `allow_package_managers?: boolean | null` Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the `allowed_hosts` array. Defaults to `false`. - `allowed_hosts?: Array | null` Specifies domains the container can reach. ### Beta Packages - `BetaPackages` Packages (and their versions) available in this environment. - `apt: Array` Ubuntu/Debian packages to install - `cargo: Array` Rust packages to install - `gem: Array` Ruby packages to install - `go: Array` Go packages to install - `npm: Array` Node.js packages to install - `pip: Array` Python packages to install - `type?: "packages"` Package configuration type - `"packages"` ### Beta Packages Params - `BetaPackagesParams` Specify packages (and optionally their versions) available in this environment. When versioning, use the version semantics relevant for the package manager, e.g. for `pip` use `package==1.0.0`. You are responsible for validating the package and version exist. Unversioned installs the latest. - `apt?: Array | null` Ubuntu/Debian packages to install - `cargo?: Array | null` Rust packages to install - `gem?: Array | null` Ruby packages to install - `go?: Array | null` Go packages to install - `npm?: Array | null` Node.js packages to install - `pip?: Array | null` Python packages to install - `type?: "packages"` Package configuration type - `"packages"` ### Beta Self Hosted Config - `BetaSelfHostedConfig` Configuration for self-hosted environments. - `type: "self_hosted"` Environment type - `"self_hosted"` ### Beta Self Hosted Config Params - `BetaSelfHostedConfigParams` Request params for `self_hosted` environment configuration. - `type: "self_hosted"` Environment type - `"self_hosted"` ### Beta Unrestricted Network - `BetaUnrestrictedNetwork` Unrestricted network access. - `type: "unrestricted"` Network policy type - `"unrestricted"` # Work ## Get Work Item `client.beta.environments.work.retrieve(stringworkID, WorkRetrieveParamsparams, RequestOptionsoptions?): BetaSelfHostedWork` **get** `/v1/environments/{environment_id}/work/{work_id}` Note: these endpoints are called automatically by the pre-built environment worker provided in the SDKs and CLI, for orchestrating sessions with self-hosted sandbox environments. They are included here as a reference; you do not need to invoke them directly. Retrieve detailed information about a specific work item. ### Parameters - `workID: string` - `params: WorkRetrieveParams` - `environment_id: string` Path param - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaSelfHostedWork` Work resource representing a unit of work in a self-hosted environment. Work items are queued when sessions are created or when long-dormant sessions receive new messages. The environment worker polls for work to execute in a self-hosted sandbox. - `id: string` Work identifier (e.g., 'work_...') - `acknowledged_at: string | null` RFC 3339 timestamp when the work item was acknowledged and assigned to a self-hosted sandbox - `created_at: string` RFC 3339 timestamp when work was created - `data: BetaSessionWorkData` The actual work to be performed - `id: string` Session identifier (e.g., 'session_...') - `type: "session"` Type of work data - `"session"` - `environment_id: string` Environment identifier this work belongs to (e.g., `env_...`) - `latest_heartbeat_at: string | null` RFC 3339 timestamp of the most recent heartbeat - `metadata: Record` User-provided metadata key-value pairs associated with this work item - `started_at: string | null` RFC 3339 timestamp when work execution started - `state: "queued" | "starting" | "active" | 2 more` Current state of the work item - `"queued"` - `"starting"` - `"active"` - `"stopping"` - `"stopped"` - `stop_requested_at: string | null` RFC 3339 timestamp when stop was requested - `stopped_at: string | null` RFC 3339 timestamp when work execution stopped - `type: "work"` The type of object (always 'work') - `"work"` ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const betaSelfHostedWork = await client.beta.environments.work.retrieve('work_id', { environment_id: 'env_011CZkZ9X2dpNyB7HsEFoRfW', }); console.log(betaSelfHostedWork.id); ``` #### Response ```json { "id": "id", "acknowledged_at": "acknowledged_at", "created_at": "created_at", "data": { "id": "id", "type": "session" }, "environment_id": "environment_id", "latest_heartbeat_at": "latest_heartbeat_at", "metadata": { "foo": "string" }, "started_at": "started_at", "state": "queued", "stop_requested_at": "stop_requested_at", "stopped_at": "stopped_at", "type": "work" } ``` ## Poll for Work `client.beta.environments.work.poll(stringenvironmentID, WorkPollParamsparams?, RequestOptionsoptions?): BetaSelfHostedWork | null` **get** `/v1/environments/{environment_id}/work/poll` Note: these endpoints are called automatically by the pre-built environment worker provided in the SDKs and CLI, for orchestrating sessions with self-hosted sandbox environments. They are included here as a reference; you do not need to invoke them directly. Long poll for work items in the queue. ### Parameters - `environmentID: string` - `params: WorkPollParams` - `block_ms?: number | null` Query param: How long to wait for work to arrive before returning. Must be 1-999 in milliseconds. Defaults to non-blocking (returns immediately if no work is available). - `reclaim_older_than_ms?: number | null` Query param: Reclaim unacknowledged work items older than this many milliseconds. If omitted, uses the default (5000ms). - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` - `"Anthropic-Worker-ID"?: string` Header param: Unique identifier for the specific worker polling, used to track aggregated environment-level work metrics in Console ### Returns - `BetaSelfHostedWork | null` - `id: string` Work identifier (e.g., 'work_...') - `acknowledged_at: string | null` RFC 3339 timestamp when the work item was acknowledged and assigned to a self-hosted sandbox - `created_at: string` RFC 3339 timestamp when work was created - `data: BetaSessionWorkData` The actual work to be performed - `id: string` Session identifier (e.g., 'session_...') - `type: "session"` Type of work data - `"session"` - `environment_id: string` Environment identifier this work belongs to (e.g., `env_...`) - `latest_heartbeat_at: string | null` RFC 3339 timestamp of the most recent heartbeat - `metadata: Record` User-provided metadata key-value pairs associated with this work item - `started_at: string | null` RFC 3339 timestamp when work execution started - `state: "queued" | "starting" | "active" | 2 more` Current state of the work item - `"queued"` - `"starting"` - `"active"` - `"stopping"` - `"stopped"` - `stop_requested_at: string | null` RFC 3339 timestamp when stop was requested - `stopped_at: string | null` RFC 3339 timestamp when work execution stopped - `type: "work"` The type of object (always 'work') - `"work"` ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const betaSelfHostedWork = await client.beta.environments.work.poll('env_011CZkZ9X2dpNyB7HsEFoRfW'); console.log(betaSelfHostedWork.id); ``` #### Response ```json { "id": "id", "acknowledged_at": "acknowledged_at", "created_at": "created_at", "data": { "id": "id", "type": "session" }, "environment_id": "environment_id", "latest_heartbeat_at": "latest_heartbeat_at", "metadata": { "foo": "string" }, "started_at": "started_at", "state": "queued", "stop_requested_at": "stop_requested_at", "stopped_at": "stopped_at", "type": "work" } ``` ## Acknowledge Work `client.beta.environments.work.ack(stringworkID, WorkAckParamsparams, RequestOptionsoptions?): BetaSelfHostedWork` **post** `/v1/environments/{environment_id}/work/{work_id}/ack` Note: these endpoints are called automatically by the pre-built environment worker provided in the SDKs and CLI, for orchestrating sessions with self-hosted sandbox environments. They are included here as a reference; you do not need to invoke them directly. Acknowledge receipt of a work item, transitioning it from 'queued' to 'starting' and removing it from the queue. ### Parameters - `workID: string` - `params: WorkAckParams` - `environment_id: string` Path param - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaSelfHostedWork` Work resource representing a unit of work in a self-hosted environment. Work items are queued when sessions are created or when long-dormant sessions receive new messages. The environment worker polls for work to execute in a self-hosted sandbox. - `id: string` Work identifier (e.g., 'work_...') - `acknowledged_at: string | null` RFC 3339 timestamp when the work item was acknowledged and assigned to a self-hosted sandbox - `created_at: string` RFC 3339 timestamp when work was created - `data: BetaSessionWorkData` The actual work to be performed - `id: string` Session identifier (e.g., 'session_...') - `type: "session"` Type of work data - `"session"` - `environment_id: string` Environment identifier this work belongs to (e.g., `env_...`) - `latest_heartbeat_at: string | null` RFC 3339 timestamp of the most recent heartbeat - `metadata: Record` User-provided metadata key-value pairs associated with this work item - `started_at: string | null` RFC 3339 timestamp when work execution started - `state: "queued" | "starting" | "active" | 2 more` Current state of the work item - `"queued"` - `"starting"` - `"active"` - `"stopping"` - `"stopped"` - `stop_requested_at: string | null` RFC 3339 timestamp when stop was requested - `stopped_at: string | null` RFC 3339 timestamp when work execution stopped - `type: "work"` The type of object (always 'work') - `"work"` ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const betaSelfHostedWork = await client.beta.environments.work.ack('work_id', { environment_id: 'env_011CZkZ9X2dpNyB7HsEFoRfW', }); console.log(betaSelfHostedWork.id); ``` #### Response ```json { "id": "id", "acknowledged_at": "acknowledged_at", "created_at": "created_at", "data": { "id": "id", "type": "session" }, "environment_id": "environment_id", "latest_heartbeat_at": "latest_heartbeat_at", "metadata": { "foo": "string" }, "started_at": "started_at", "state": "queued", "stop_requested_at": "stop_requested_at", "stopped_at": "stopped_at", "type": "work" } ``` ## Record Heartbeat `client.beta.environments.work.heartbeat(stringworkID, WorkHeartbeatParamsparams, RequestOptionsoptions?): BetaSelfHostedWorkHeartbeatResponse` **post** `/v1/environments/{environment_id}/work/{work_id}/heartbeat` Note: these endpoints are called automatically by the pre-built environment worker provided in the SDKs and CLI, for orchestrating sessions with self-hosted sandbox environments. They are included here as a reference; you do not need to invoke them directly. Record a heartbeat for a work item to maintain the lease. ### Parameters - `workID: string` - `params: WorkHeartbeatParams` - `environment_id: string` Path param - `desired_ttl_seconds?: number | null` Query param: Desired TTL in seconds - `expected_last_heartbeat?: string | null` Query param: Expected last_heartbeat for conditional update (optimistic concurrency). Use literal 'NO_HEARTBEAT' to claim an unclaimed lease (first heartbeat). For subsequent heartbeats, echo the server's previous last_heartbeat value exactly. Returns 412 Precondition Failed if the actual value doesn't match. - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaSelfHostedWorkHeartbeatResponse` Response after recording a heartbeat for a work item. - `last_heartbeat: string` RFC 3339 timestamp of the actual heartbeat from DB - `lease_extended: boolean` Whether the heartbeat succeeded in extending the lease - `state: "queued" | "starting" | "active" | 2 more` Current state of the work item (active/stopping/stopped) - `"queued"` - `"starting"` - `"active"` - `"stopping"` - `"stopped"` - `ttl_seconds: number` Effective TTL applied to the lease - `type: "work_heartbeat"` The type of response - `"work_heartbeat"` ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const betaSelfHostedWorkHeartbeatResponse = await client.beta.environments.work.heartbeat( 'work_id', { environment_id: 'env_011CZkZ9X2dpNyB7HsEFoRfW' }, ); console.log(betaSelfHostedWorkHeartbeatResponse.last_heartbeat); ``` #### Response ```json { "last_heartbeat": "last_heartbeat", "lease_extended": true, "state": "queued", "ttl_seconds": 0, "type": "work_heartbeat" } ``` ## Stop Work `client.beta.environments.work.stop(stringworkID, WorkStopParamsparams, RequestOptionsoptions?): BetaSelfHostedWork` **post** `/v1/environments/{environment_id}/work/{work_id}/stop` Note: these endpoints are called automatically by the pre-built environment worker provided in the SDKs and CLI, for orchestrating sessions with self-hosted sandbox environments. They are included here as a reference; you do not need to invoke them directly. Stop a work item, initiating graceful or forced shutdown. ### Parameters - `workID: string` - `params: WorkStopParams` - `environment_id: string` Path param - `force?: boolean` Body param: If true, immediately stop work without graceful shutdown - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaSelfHostedWork` Work resource representing a unit of work in a self-hosted environment. Work items are queued when sessions are created or when long-dormant sessions receive new messages. The environment worker polls for work to execute in a self-hosted sandbox. - `id: string` Work identifier (e.g., 'work_...') - `acknowledged_at: string | null` RFC 3339 timestamp when the work item was acknowledged and assigned to a self-hosted sandbox - `created_at: string` RFC 3339 timestamp when work was created - `data: BetaSessionWorkData` The actual work to be performed - `id: string` Session identifier (e.g., 'session_...') - `type: "session"` Type of work data - `"session"` - `environment_id: string` Environment identifier this work belongs to (e.g., `env_...`) - `latest_heartbeat_at: string | null` RFC 3339 timestamp of the most recent heartbeat - `metadata: Record` User-provided metadata key-value pairs associated with this work item - `started_at: string | null` RFC 3339 timestamp when work execution started - `state: "queued" | "starting" | "active" | 2 more` Current state of the work item - `"queued"` - `"starting"` - `"active"` - `"stopping"` - `"stopped"` - `stop_requested_at: string | null` RFC 3339 timestamp when stop was requested - `stopped_at: string | null` RFC 3339 timestamp when work execution stopped - `type: "work"` The type of object (always 'work') - `"work"` ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const betaSelfHostedWork = await client.beta.environments.work.stop('work_id', { environment_id: 'env_011CZkZ9X2dpNyB7HsEFoRfW', }); console.log(betaSelfHostedWork.id); ``` #### Response ```json { "id": "id", "acknowledged_at": "acknowledged_at", "created_at": "created_at", "data": { "id": "id", "type": "session" }, "environment_id": "environment_id", "latest_heartbeat_at": "latest_heartbeat_at", "metadata": { "foo": "string" }, "started_at": "started_at", "state": "queued", "stop_requested_at": "stop_requested_at", "stopped_at": "stopped_at", "type": "work" } ``` ## List Work Items `client.beta.environments.work.list(stringenvironmentID, WorkListParamsparams?, RequestOptionsoptions?): PageCursor` **get** `/v1/environments/{environment_id}/work` Note: these endpoints are called automatically by the pre-built environment worker provided in the SDKs and CLI, for orchestrating sessions with self-hosted sandbox environments. They are included here as a reference; you do not need to invoke them directly. List work items in an environment. ### Parameters - `environmentID: string` - `params: WorkListParams` - `limit?: number` Query param: Maximum number of work items to return - `page?: string | null` Query param: Opaque cursor from previous response for pagination - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaSelfHostedWork` Work resource representing a unit of work in a self-hosted environment. Work items are queued when sessions are created or when long-dormant sessions receive new messages. The environment worker polls for work to execute in a self-hosted sandbox. - `id: string` Work identifier (e.g., 'work_...') - `acknowledged_at: string | null` RFC 3339 timestamp when the work item was acknowledged and assigned to a self-hosted sandbox - `created_at: string` RFC 3339 timestamp when work was created - `data: BetaSessionWorkData` The actual work to be performed - `id: string` Session identifier (e.g., 'session_...') - `type: "session"` Type of work data - `"session"` - `environment_id: string` Environment identifier this work belongs to (e.g., `env_...`) - `latest_heartbeat_at: string | null` RFC 3339 timestamp of the most recent heartbeat - `metadata: Record` User-provided metadata key-value pairs associated with this work item - `started_at: string | null` RFC 3339 timestamp when work execution started - `state: "queued" | "starting" | "active" | 2 more` Current state of the work item - `"queued"` - `"starting"` - `"active"` - `"stopping"` - `"stopped"` - `stop_requested_at: string | null` RFC 3339 timestamp when stop was requested - `stopped_at: string | null` RFC 3339 timestamp when work execution stopped - `type: "work"` The type of object (always 'work') - `"work"` ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); // Automatically fetches more pages as needed. for await (const betaSelfHostedWork of client.beta.environments.work.list( 'env_011CZkZ9X2dpNyB7HsEFoRfW', )) { console.log(betaSelfHostedWork.id); } ``` #### Response ```json { "data": [ { "id": "id", "acknowledged_at": "acknowledged_at", "created_at": "created_at", "data": { "id": "id", "type": "session" }, "environment_id": "environment_id", "latest_heartbeat_at": "latest_heartbeat_at", "metadata": { "foo": "string" }, "started_at": "started_at", "state": "queued", "stop_requested_at": "stop_requested_at", "stopped_at": "stopped_at", "type": "work" } ], "next_page": "next_page" } ``` ## Update Work Item `client.beta.environments.work.update(stringworkID, WorkUpdateParamsparams, RequestOptionsoptions?): BetaSelfHostedWork` **post** `/v1/environments/{environment_id}/work/{work_id}` Note: these endpoints are called automatically by the pre-built environment worker provided in the SDKs and CLI, for orchestrating sessions with self-hosted sandbox environments. They are included here as a reference; you do not need to invoke them directly. Update work item metadata with merge semantics. ### Parameters - `workID: string` - `params: WorkUpdateParams` - `environment_id: string` Path param - `metadata: Record` Body param: Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve existing metadata. - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaSelfHostedWork` Work resource representing a unit of work in a self-hosted environment. Work items are queued when sessions are created or when long-dormant sessions receive new messages. The environment worker polls for work to execute in a self-hosted sandbox. - `id: string` Work identifier (e.g., 'work_...') - `acknowledged_at: string | null` RFC 3339 timestamp when the work item was acknowledged and assigned to a self-hosted sandbox - `created_at: string` RFC 3339 timestamp when work was created - `data: BetaSessionWorkData` The actual work to be performed - `id: string` Session identifier (e.g., 'session_...') - `type: "session"` Type of work data - `"session"` - `environment_id: string` Environment identifier this work belongs to (e.g., `env_...`) - `latest_heartbeat_at: string | null` RFC 3339 timestamp of the most recent heartbeat - `metadata: Record` User-provided metadata key-value pairs associated with this work item - `started_at: string | null` RFC 3339 timestamp when work execution started - `state: "queued" | "starting" | "active" | 2 more` Current state of the work item - `"queued"` - `"starting"` - `"active"` - `"stopping"` - `"stopped"` - `stop_requested_at: string | null` RFC 3339 timestamp when stop was requested - `stopped_at: string | null` RFC 3339 timestamp when work execution stopped - `type: "work"` The type of object (always 'work') - `"work"` ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const betaSelfHostedWork = await client.beta.environments.work.update('work_id', { environment_id: 'env_011CZkZ9X2dpNyB7HsEFoRfW', metadata: { foo: 'string' }, }); console.log(betaSelfHostedWork.id); ``` #### Response ```json { "id": "id", "acknowledged_at": "acknowledged_at", "created_at": "created_at", "data": { "id": "id", "type": "session" }, "environment_id": "environment_id", "latest_heartbeat_at": "latest_heartbeat_at", "metadata": { "foo": "string" }, "started_at": "started_at", "state": "queued", "stop_requested_at": "stop_requested_at", "stopped_at": "stopped_at", "type": "work" } ``` ## Get Queue Statistics `client.beta.environments.work.stats(stringenvironmentID, WorkStatsParamsparams?, RequestOptionsoptions?): BetaSelfHostedWorkQueueStats` **get** `/v1/environments/{environment_id}/work/stats` Get statistics about the work queue for an environment. ### Parameters - `environmentID: string` - `params: WorkStatsParams` - `betas?: Array` Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaSelfHostedWorkQueueStats` Statistics about the work queue for an environment. Uses Redis Stream consumer group metrics for O(1) queries. - `depth: number` Number of work items waiting to be picked up (lag from consumer group) - `oldest_queued_at: string | null` RFC 3339 timestamp of oldest item in the work stream (includes both queued and pending items), null if stream empty - `pending: number` Number of work items being processed (polled but not acknowledged) - `type: "work_queue_stats"` The type of object - `"work_queue_stats"` - `workers_polling: number | null` Number of workers that have polled for work in the last 30 seconds. Requires worker_id to be sent with poll requests. ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const betaSelfHostedWorkQueueStats = await client.beta.environments.work.stats( 'env_011CZkZ9X2dpNyB7HsEFoRfW', ); console.log(betaSelfHostedWorkQueueStats.depth); ``` #### Response ```json { "depth": 0, "oldest_queued_at": "oldest_queued_at", "pending": 0, "type": "work_queue_stats", "workers_polling": 0 } ``` ## Domain Types ### Beta Self Hosted Work - `BetaSelfHostedWork` Work resource representing a unit of work in a self-hosted environment. Work items are queued when sessions are created or when long-dormant sessions receive new messages. The environment worker polls for work to execute in a self-hosted sandbox. - `id: string` Work identifier (e.g., 'work_...') - `acknowledged_at: string | null` RFC 3339 timestamp when the work item was acknowledged and assigned to a self-hosted sandbox - `created_at: string` RFC 3339 timestamp when work was created - `data: BetaSessionWorkData` The actual work to be performed - `id: string` Session identifier (e.g., 'session_...') - `type: "session"` Type of work data - `"session"` - `environment_id: string` Environment identifier this work belongs to (e.g., `env_...`) - `latest_heartbeat_at: string | null` RFC 3339 timestamp of the most recent heartbeat - `metadata: Record` User-provided metadata key-value pairs associated with this work item - `started_at: string | null` RFC 3339 timestamp when work execution started - `state: "queued" | "starting" | "active" | 2 more` Current state of the work item - `"queued"` - `"starting"` - `"active"` - `"stopping"` - `"stopped"` - `stop_requested_at: string | null` RFC 3339 timestamp when stop was requested - `stopped_at: string | null` RFC 3339 timestamp when work execution stopped - `type: "work"` The type of object (always 'work') - `"work"` ### Beta Self Hosted Work Heartbeat Response - `BetaSelfHostedWorkHeartbeatResponse` Response after recording a heartbeat for a work item. - `last_heartbeat: string` RFC 3339 timestamp of the actual heartbeat from DB - `lease_extended: boolean` Whether the heartbeat succeeded in extending the lease - `state: "queued" | "starting" | "active" | 2 more` Current state of the work item (active/stopping/stopped) - `"queued"` - `"starting"` - `"active"` - `"stopping"` - `"stopped"` - `ttl_seconds: number` Effective TTL applied to the lease - `type: "work_heartbeat"` The type of response - `"work_heartbeat"` ### Beta Self Hosted Work List Response - `BetaSelfHostedWorkListResponse` Response when listing work items with cursor-based pagination. - `data: Array` List of work items - `id: string` Work identifier (e.g., 'work_...') - `acknowledged_at: string | null` RFC 3339 timestamp when the work item was acknowledged and assigned to a self-hosted sandbox - `created_at: string` RFC 3339 timestamp when work was created - `data: BetaSessionWorkData` The actual work to be performed - `id: string` Session identifier (e.g., 'session_...') - `type: "session"` Type of work data - `"session"` - `environment_id: string` Environment identifier this work belongs to (e.g., `env_...`) - `latest_heartbeat_at: string | null` RFC 3339 timestamp of the most recent heartbeat - `metadata: Record` User-provided metadata key-value pairs associated with this work item - `started_at: string | null` RFC 3339 timestamp when work execution started - `state: "queued" | "starting" | "active" | 2 more` Current state of the work item - `"queued"` - `"starting"` - `"active"` - `"stopping"` - `"stopped"` - `stop_requested_at: string | null` RFC 3339 timestamp when stop was requested - `stopped_at: string | null` RFC 3339 timestamp when work execution stopped - `type: "work"` The type of object (always 'work') - `"work"` - `next_page: string | null` Opaque cursor for fetching the next page of results ### Beta Self Hosted Work Queue Stats - `BetaSelfHostedWorkQueueStats` Statistics about the work queue for an environment. Uses Redis Stream consumer group metrics for O(1) queries. - `depth: number` Number of work items waiting to be picked up (lag from consumer group) - `oldest_queued_at: string | null` RFC 3339 timestamp of oldest item in the work stream (includes both queued and pending items), null if stream empty - `pending: number` Number of work items being processed (polled but not acknowledged) - `type: "work_queue_stats"` The type of object - `"work_queue_stats"` - `workers_polling: number | null` Number of workers that have polled for work in the last 30 seconds. Requires worker_id to be sent with poll requests. ### Beta Self Hosted Work Stop Request - `BetaSelfHostedWorkStopRequest` Request to stop a work item. - `force?: boolean` If true, immediately stop work without graceful shutdown ### Beta Self Hosted Work Update Request - `BetaSelfHostedWorkUpdateRequest` Request to update work item metadata. - `metadata: Record` Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve existing metadata. ### Beta Session Work Data - `BetaSessionWorkData` Work data for session work items. This resource type is used when work represents a session that needs to be executed in a self-hosted environment. - `id: string` Session identifier (e.g., 'session_...') - `type: "session"` Type of work data - `"session"` # Sessions ## Create Session `client.beta.sessions.create(SessionCreateParamsparams, RequestOptionsoptions?): BetaManagedAgentsSession` **post** `/v1/sessions` Create Session ### Parameters - `params: SessionCreateParams` - `agent: string | BetaManagedAgentsAgentParams` Body param: Agent identifier. Accepts the `agent` ID string, which pins the latest version for the session, or an `agent` object with both id and version specified. - `string` - `BetaManagedAgentsAgentParams` Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version - `id: string` The `agent` ID. - `type: "agent"` - `"agent"` - `version?: number` The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified. - `environment_id: string` Body param: ID of the `environment` defining the container configuration for this session. - `metadata?: Record` Body param: Arbitrary key-value metadata attached to the session. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars. - `resources?: Array` Body param: Resources (e.g. repositories, files) to mount into the session's container. - `BetaManagedAgentsGitHubRepositoryResourceParams` Mount a GitHub repository into the session's container. - `authorization_token: string` GitHub authorization token used to clone the repository. - `type: "github_repository"` - `"github_repository"` - `url: string` Github URL of the repository - `checkout?: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout | null` Branch or commit to check out. Defaults to the repository's default branch. - `BetaManagedAgentsBranchCheckout` - `name: string` Branch name to check out. - `type: "branch"` - `"branch"` - `BetaManagedAgentsCommitCheckout` - `sha: string` Full commit SHA to check out. - `type: "commit"` - `"commit"` - `mount_path?: string | null` Mount path in the container. Defaults to `/workspace/`. - `BetaManagedAgentsFileResourceParams` Mount a file uploaded via the Files API into the session. - `file_id: string` ID of a previously uploaded file. - `type: "file"` - `"file"` - `mount_path?: string | null` Mount path in the container. Defaults to `/mnt/session/uploads/`. - `BetaManagedAgentsMemoryStoreResourceParam` Parameters for attaching a memory store to an agent session. - `memory_store_id: string` The memory store ID (memstore_...). Must belong to the caller's organization and workspace. - `type: "memory_store"` - `"memory_store"` - `access?: "read_write" | "read_only" | null` Access mode for an attached memory store. - `"read_write"` - `"read_only"` - `instructions?: string | null` Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars. - `title?: string | null` Body param: Human-readable session title. - `vault_ids?: Array` Body param: Vault IDs for stored credentials the agent can use during the session. - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaManagedAgentsSession` A Managed Agents `session`. - `id: string` - `agent: BetaManagedAgentsSessionAgent` Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. - `id: string` - `description: string | null` - `mcp_servers: Array` - `name: string` - `type: "url"` - `"url"` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `id: BetaManagedAgentsModel` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-opus-4-8" | "claude-opus-4-7" | "claude-opus-4-6" | 7 more` - `"claude-opus-4-8"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-7"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-6"` Most intelligent model for building agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` Fastest model with near-frontier intelligence - `"claude-haiku-4-5-20251001"` Fastest model with near-frontier intelligence - `"claude-opus-4-5"` Premium model combining maximum intelligence with practical performance - `"claude-opus-4-5-20251101"` Premium model combining maximum intelligence with practical performance - `"claude-sonnet-4-5"` High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` High-performance model for agents and coding - `(string & {})` - `speed?: "standard" | "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `multiagent: BetaManagedAgentsSessionMultiagentCoordinator | null` Resolved coordinator topology with full agent definitions for each roster member. - `agents: Array` Full `agent` definitions the coordinator may spawn as session threads. - `id: string` - `description: string | null` - `mcp_servers: Array` - `name: string` - `type: "url"` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `name: string` - `skills: Array` - `BetaManagedAgentsAnthropicSkill` A resolved Anthropic-managed skill. - `skill_id: string` - `type: "anthropic"` - `"anthropic"` - `version: string` - `BetaManagedAgentsCustomSkill` A resolved user-created custom skill. - `skill_id: string` - `type: "custom"` - `"custom"` - `version: string` - `system: string | null` - `tools: Array` - `BetaManagedAgentsAgentToolset20260401` - `configs: Array` - `enabled: boolean` - `name: "bash" | "edit" | "read" | 5 more` Built-in agent tool identifier. - `"bash"` - `"edit"` - `"read"` - `"write"` - `"glob"` - `"grep"` - `"web_fetch"` - `"web_search"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `"always_allow"` - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "always_ask"` - `"always_ask"` - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` Resolved default configuration for agent tools. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "agent_toolset_20260401"` - `"agent_toolset_20260401"` - `BetaManagedAgentsMCPToolset` - `configs: Array` - `enabled: boolean` - `name: string` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` Resolved default configuration for all tools from an MCP server. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `mcp_server_name: string` - `type: "mcp_toolset"` - `"mcp_toolset"` - `BetaManagedAgentsCustomTool` A custom tool as returned in API responses. - `description: string` - `input_schema: BetaManagedAgentsCustomToolInputSchema` JSON Schema for custom tool input parameters. - `properties?: Record | null` JSON Schema properties defining the tool's input parameters. - `required?: Array` List of required property names. - `type?: "object"` Must be 'object' for tool input schemas. - `"object"` - `name: string` - `type: "custom"` - `"custom"` - `type: "agent"` - `"agent"` - `version: number` - `type: "coordinator"` - `"coordinator"` - `name: string` - `skills: Array` - `BetaManagedAgentsAnthropicSkill` A resolved Anthropic-managed skill. - `BetaManagedAgentsCustomSkill` A resolved user-created custom skill. - `system: string | null` - `tools: Array` - `BetaManagedAgentsAgentToolset20260401` - `BetaManagedAgentsMCPToolset` - `BetaManagedAgentsCustomTool` A custom tool as returned in API responses. - `type: "agent"` - `"agent"` - `version: number` - `archived_at: string | null` A timestamp in RFC 3339 format - `created_at: string` A timestamp in RFC 3339 format - `environment_id: string` - `metadata: Record` - `outcome_evaluations: Array` Per-outcome evaluation state. One entry per define_outcome event sent to the session. - `completed_at: string | null` A timestamp in RFC 3339 format - `description: string` What the agent should produce. - `explanation: string | null` Grader's verdict text from the most recent evaluation. For satisfied, explains why criteria are met; for needs_revision (intermediate), what's missing; for failed, why unrecoverable. - `iteration: number` 0-indexed revision cycle the outcome is currently on. - `outcome_id: string` Server-generated outc_ ID for this outcome. - `result: string` Current evaluation state. `pending` before the agent begins work; `running` while producing or revising; `evaluating` while the grader scores; `satisfied`/`max_iterations_reached`/`failed`/`interrupted` are terminal. - `type: "outcome_evaluation"` - `"outcome_evaluation"` - `resources: Array` - `BetaManagedAgentsGitHubRepositoryResource` - `id: string` - `created_at: string` A timestamp in RFC 3339 format - `mount_path: string` - `type: "github_repository"` - `"github_repository"` - `updated_at: string` A timestamp in RFC 3339 format - `url: string` - `checkout?: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout | null` - `BetaManagedAgentsBranchCheckout` - `name: string` Branch name to check out. - `type: "branch"` - `"branch"` - `BetaManagedAgentsCommitCheckout` - `sha: string` Full commit SHA to check out. - `type: "commit"` - `"commit"` - `BetaManagedAgentsFileResource` - `id: string` - `created_at: string` A timestamp in RFC 3339 format - `file_id: string` - `mount_path: string` - `type: "file"` - `"file"` - `updated_at: string` A timestamp in RFC 3339 format - `BetaManagedAgentsMemoryStoreResource` A memory store attached to an agent session. - `memory_store_id: string` The memory store ID (memstore_...). Must belong to the caller's organization and workspace. - `type: "memory_store"` - `"memory_store"` - `access?: "read_write" | "read_only" | null` Access mode for an attached memory store. - `"read_write"` - `"read_only"` - `description?: string` Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description. - `instructions?: string | null` Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars. - `mount_path?: string | null` Filesystem path where the store is mounted in the session container, e.g. /mnt/memory/user-preferences. Derived from the store's name. Output-only. - `name?: string | null` Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource. - `stats: BetaManagedAgentsSessionStats` Timing statistics for a session. - `active_seconds?: number` Cumulative time in seconds the session spent in running status. Excludes idle time. - `duration_seconds?: number` Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. - `status: "rescheduling" | "running" | "idle" | "terminated"` SessionStatus enum - `"rescheduling"` - `"running"` - `"idle"` - `"terminated"` - `title: string | null` - `type: "session"` - `"session"` - `updated_at: string` A timestamp in RFC 3339 format - `usage: BetaManagedAgentsSessionUsage` Cumulative token usage for a session across all turns. - `cache_creation?: BetaManagedAgentsCacheCreationUsage` Prompt-cache creation token usage broken down by cache lifetime. - `ephemeral_1h_input_tokens?: number` Tokens used to create 1-hour ephemeral cache entries. - `ephemeral_5m_input_tokens?: number` Tokens used to create 5-minute ephemeral cache entries. - `cache_read_input_tokens?: number` Total tokens read from prompt cache. - `input_tokens?: number` Total input tokens consumed across all turns. - `output_tokens?: number` Total output tokens generated across all turns. - `vault_ids: Array` Vault IDs attached to the session at creation. Empty when no vaults were supplied. ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const betaManagedAgentsSession = await client.beta.sessions.create({ agent: 'agent_011CZkYpogX7uDKUyvBTophP', environment_id: 'env_011CZkZ9X2dpNyB7HsEFoRfW', }); console.log(betaManagedAgentsSession.id); ``` #### Response ```json { "id": "sesn_011CZkZAtmR3yMPDzynEDxu7", "agent": { "id": "agent_011CZkYpogX7uDKUyvBTophP", "description": "A general-purpose starter agent.", "mcp_servers": [ { "name": "example-mcp", "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse" } ], "model": { "id": "claude-sonnet-4-6", "speed": "standard" }, "multiagent": { "agents": [ { "id": "agent_011CZkYqphY8vELVzwCUpqiQ", "description": "A focused research subagent.", "mcp_servers": [ { "name": "example-mcp", "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse" } ], "model": { "id": "claude-sonnet-4-6", "speed": "standard" }, "name": "Researcher", "skills": [ { "skill_id": "xlsx", "type": "anthropic", "version": "1" } ], "system": "You are a research subagent that gathers and summarises sources for the coordinating agent.", "tools": [ { "configs": [ { "enabled": true, "name": "bash", "permission_policy": { "type": "always_allow" } } ], "default_config": { "enabled": true, "permission_policy": { "type": "always_ask" } }, "type": "agent_toolset_20260401" } ], "type": "agent", "version": 1 } ], "type": "coordinator" }, "name": "My First Agent", "skills": [ { "skill_id": "xlsx", "type": "anthropic", "version": "1" }, { "skill_id": "skill_011CZkZFNu9hAbo3jZPRgTlx", "type": "custom", "version": "2" } ], "system": "You are a general-purpose agent that can research, write code, run commands, and use connected tools to complete the user's task end to end.", "tools": [ { "configs": [ { "enabled": true, "name": "bash", "permission_policy": { "type": "always_allow" } } ], "default_config": { "enabled": true, "permission_policy": { "type": "always_ask" } }, "type": "agent_toolset_20260401" } ], "type": "agent", "version": 1 }, "archived_at": null, "created_at": "2026-03-15T10:00:00Z", "environment_id": "env_011CZkZ9X2dpNyB7HsEFoRfW", "metadata": {}, "outcome_evaluations": [ { "completed_at": "2026-03-15T10:02:31Z", "description": "Produce a 2-page summary as summary.md", "explanation": "All five sections present with inline citations.", "iteration": 0, "outcome_id": "outc_011CZkZRSw2kEfs6ncTVljxP", "result": "satisfied", "type": "outcome_evaluation" } ], "resources": [ { "id": "sesrsc_011CZkZBJq5dWxk9fVLNcPht", "created_at": "2026-03-15T10:00:00Z", "file_id": "file_011CNha8iCJcU1wXNR6q4V8w", "mount_path": "/uploads/receipt.pdf", "type": "file", "updated_at": "2026-03-15T10:00:00Z" }, { "id": "sesrsc_011CZkZCKr6eXyl0gWMOdQiu", "created_at": "2026-03-15T10:00:00Z", "mount_path": "/workspace/example-repo", "type": "github_repository", "updated_at": "2026-03-15T10:00:00Z", "url": "https://github.com/example-org/example-repo", "checkout": { "name": "main", "type": "branch" } } ], "stats": { "active_seconds": 0, "duration_seconds": 0 }, "status": "idle", "title": "Order #1234 inquiry", "type": "session", "updated_at": "2026-03-15T10:00:00Z", "usage": { "cache_creation": { "ephemeral_1h_input_tokens": 0, "ephemeral_5m_input_tokens": 0 }, "cache_read_input_tokens": 0, "input_tokens": 0, "output_tokens": 0 }, "vault_ids": [ "vlt_011CZkZDLs7fYzm1hXNPeRjv" ] } ``` ## List Sessions `client.beta.sessions.list(SessionListParamsparams?, RequestOptionsoptions?): PageCursor` **get** `/v1/sessions` List Sessions ### Parameters - `params: SessionListParams` - `agent_id?: string` Query param: Filter sessions created with this agent ID. - `agent_version?: number` Query param: Filter by agent version. Only applies when agent_id is also set. - `"created_at[gt]"?: string` Query param: Return sessions created after this time (exclusive). - `"created_at[gte]"?: string` Query param: Return sessions created at or after this time (inclusive). - `"created_at[lt]"?: string` Query param: Return sessions created before this time (exclusive). - `"created_at[lte]"?: string` Query param: Return sessions created at or before this time (inclusive). - `include_archived?: boolean` Query param: When true, includes archived sessions. Default: false (exclude archived). - `limit?: number` Query param: Maximum number of results to return. - `memory_store_id?: string` Query param: Filter sessions whose resources contain a memory_store with this memory store ID. - `order?: "asc" | "desc"` Query param: Sort direction for results, ordered by created_at. Defaults to desc (newest first). - `"asc"` - `"desc"` - `page?: string` Query param: Opaque pagination cursor from a previous response's next_page. - `statuses?: Array<"rescheduling" | "running" | "idle" | "terminated">` Query param: Filter by session status. Repeat the parameter to match any of multiple statuses. - `"rescheduling"` - `"running"` - `"idle"` - `"terminated"` - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaManagedAgentsSession` A Managed Agents `session`. - `id: string` - `agent: BetaManagedAgentsSessionAgent` Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. - `id: string` - `description: string | null` - `mcp_servers: Array` - `name: string` - `type: "url"` - `"url"` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `id: BetaManagedAgentsModel` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-opus-4-8" | "claude-opus-4-7" | "claude-opus-4-6" | 7 more` - `"claude-opus-4-8"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-7"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-6"` Most intelligent model for building agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` Fastest model with near-frontier intelligence - `"claude-haiku-4-5-20251001"` Fastest model with near-frontier intelligence - `"claude-opus-4-5"` Premium model combining maximum intelligence with practical performance - `"claude-opus-4-5-20251101"` Premium model combining maximum intelligence with practical performance - `"claude-sonnet-4-5"` High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` High-performance model for agents and coding - `(string & {})` - `speed?: "standard" | "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `multiagent: BetaManagedAgentsSessionMultiagentCoordinator | null` Resolved coordinator topology with full agent definitions for each roster member. - `agents: Array` Full `agent` definitions the coordinator may spawn as session threads. - `id: string` - `description: string | null` - `mcp_servers: Array` - `name: string` - `type: "url"` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `name: string` - `skills: Array` - `BetaManagedAgentsAnthropicSkill` A resolved Anthropic-managed skill. - `skill_id: string` - `type: "anthropic"` - `"anthropic"` - `version: string` - `BetaManagedAgentsCustomSkill` A resolved user-created custom skill. - `skill_id: string` - `type: "custom"` - `"custom"` - `version: string` - `system: string | null` - `tools: Array` - `BetaManagedAgentsAgentToolset20260401` - `configs: Array` - `enabled: boolean` - `name: "bash" | "edit" | "read" | 5 more` Built-in agent tool identifier. - `"bash"` - `"edit"` - `"read"` - `"write"` - `"glob"` - `"grep"` - `"web_fetch"` - `"web_search"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `"always_allow"` - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "always_ask"` - `"always_ask"` - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` Resolved default configuration for agent tools. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "agent_toolset_20260401"` - `"agent_toolset_20260401"` - `BetaManagedAgentsMCPToolset` - `configs: Array` - `enabled: boolean` - `name: string` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` Resolved default configuration for all tools from an MCP server. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `mcp_server_name: string` - `type: "mcp_toolset"` - `"mcp_toolset"` - `BetaManagedAgentsCustomTool` A custom tool as returned in API responses. - `description: string` - `input_schema: BetaManagedAgentsCustomToolInputSchema` JSON Schema for custom tool input parameters. - `properties?: Record | null` JSON Schema properties defining the tool's input parameters. - `required?: Array` List of required property names. - `type?: "object"` Must be 'object' for tool input schemas. - `"object"` - `name: string` - `type: "custom"` - `"custom"` - `type: "agent"` - `"agent"` - `version: number` - `type: "coordinator"` - `"coordinator"` - `name: string` - `skills: Array` - `BetaManagedAgentsAnthropicSkill` A resolved Anthropic-managed skill. - `BetaManagedAgentsCustomSkill` A resolved user-created custom skill. - `system: string | null` - `tools: Array` - `BetaManagedAgentsAgentToolset20260401` - `BetaManagedAgentsMCPToolset` - `BetaManagedAgentsCustomTool` A custom tool as returned in API responses. - `type: "agent"` - `"agent"` - `version: number` - `archived_at: string | null` A timestamp in RFC 3339 format - `created_at: string` A timestamp in RFC 3339 format - `environment_id: string` - `metadata: Record` - `outcome_evaluations: Array` Per-outcome evaluation state. One entry per define_outcome event sent to the session. - `completed_at: string | null` A timestamp in RFC 3339 format - `description: string` What the agent should produce. - `explanation: string | null` Grader's verdict text from the most recent evaluation. For satisfied, explains why criteria are met; for needs_revision (intermediate), what's missing; for failed, why unrecoverable. - `iteration: number` 0-indexed revision cycle the outcome is currently on. - `outcome_id: string` Server-generated outc_ ID for this outcome. - `result: string` Current evaluation state. `pending` before the agent begins work; `running` while producing or revising; `evaluating` while the grader scores; `satisfied`/`max_iterations_reached`/`failed`/`interrupted` are terminal. - `type: "outcome_evaluation"` - `"outcome_evaluation"` - `resources: Array` - `BetaManagedAgentsGitHubRepositoryResource` - `id: string` - `created_at: string` A timestamp in RFC 3339 format - `mount_path: string` - `type: "github_repository"` - `"github_repository"` - `updated_at: string` A timestamp in RFC 3339 format - `url: string` - `checkout?: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout | null` - `BetaManagedAgentsBranchCheckout` - `name: string` Branch name to check out. - `type: "branch"` - `"branch"` - `BetaManagedAgentsCommitCheckout` - `sha: string` Full commit SHA to check out. - `type: "commit"` - `"commit"` - `BetaManagedAgentsFileResource` - `id: string` - `created_at: string` A timestamp in RFC 3339 format - `file_id: string` - `mount_path: string` - `type: "file"` - `"file"` - `updated_at: string` A timestamp in RFC 3339 format - `BetaManagedAgentsMemoryStoreResource` A memory store attached to an agent session. - `memory_store_id: string` The memory store ID (memstore_...). Must belong to the caller's organization and workspace. - `type: "memory_store"` - `"memory_store"` - `access?: "read_write" | "read_only" | null` Access mode for an attached memory store. - `"read_write"` - `"read_only"` - `description?: string` Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description. - `instructions?: string | null` Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars. - `mount_path?: string | null` Filesystem path where the store is mounted in the session container, e.g. /mnt/memory/user-preferences. Derived from the store's name. Output-only. - `name?: string | null` Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource. - `stats: BetaManagedAgentsSessionStats` Timing statistics for a session. - `active_seconds?: number` Cumulative time in seconds the session spent in running status. Excludes idle time. - `duration_seconds?: number` Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. - `status: "rescheduling" | "running" | "idle" | "terminated"` SessionStatus enum - `"rescheduling"` - `"running"` - `"idle"` - `"terminated"` - `title: string | null` - `type: "session"` - `"session"` - `updated_at: string` A timestamp in RFC 3339 format - `usage: BetaManagedAgentsSessionUsage` Cumulative token usage for a session across all turns. - `cache_creation?: BetaManagedAgentsCacheCreationUsage` Prompt-cache creation token usage broken down by cache lifetime. - `ephemeral_1h_input_tokens?: number` Tokens used to create 1-hour ephemeral cache entries. - `ephemeral_5m_input_tokens?: number` Tokens used to create 5-minute ephemeral cache entries. - `cache_read_input_tokens?: number` Total tokens read from prompt cache. - `input_tokens?: number` Total input tokens consumed across all turns. - `output_tokens?: number` Total output tokens generated across all turns. - `vault_ids: Array` Vault IDs attached to the session at creation. Empty when no vaults were supplied. ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); // Automatically fetches more pages as needed. for await (const betaManagedAgentsSession of client.beta.sessions.list()) { console.log(betaManagedAgentsSession.id); } ``` #### Response ```json { "data": [ { "id": "sesn_011CZkZAtmR3yMPDzynEDxu7", "agent": { "id": "agent_011CZkYpogX7uDKUyvBTophP", "description": "A general-purpose starter agent.", "mcp_servers": [ { "name": "example-mcp", "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse" } ], "model": { "id": "claude-sonnet-4-6", "speed": "standard" }, "multiagent": { "agents": [ { "id": "agent_011CZkYqphY8vELVzwCUpqiQ", "description": "A focused research subagent.", "mcp_servers": [ { "name": "example-mcp", "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse" } ], "model": { "id": "claude-sonnet-4-6", "speed": "standard" }, "name": "Researcher", "skills": [ { "skill_id": "xlsx", "type": "anthropic", "version": "1" } ], "system": "You are a research subagent that gathers and summarises sources for the coordinating agent.", "tools": [ { "configs": [ { "enabled": true, "name": "bash", "permission_policy": { "type": "always_allow" } } ], "default_config": { "enabled": true, "permission_policy": { "type": "always_ask" } }, "type": "agent_toolset_20260401" } ], "type": "agent", "version": 1 } ], "type": "coordinator" }, "name": "My First Agent", "skills": [ { "skill_id": "xlsx", "type": "anthropic", "version": "1" }, { "skill_id": "skill_011CZkZFNu9hAbo3jZPRgTlx", "type": "custom", "version": "2" } ], "system": "You are a general-purpose agent that can research, write code, run commands, and use connected tools to complete the user's task end to end.", "tools": [ { "configs": [ { "enabled": true, "name": "bash", "permission_policy": { "type": "always_allow" } } ], "default_config": { "enabled": true, "permission_policy": { "type": "always_ask" } }, "type": "agent_toolset_20260401" } ], "type": "agent", "version": 1 }, "archived_at": null, "created_at": "2026-03-15T10:00:00Z", "environment_id": "env_011CZkZ9X2dpNyB7HsEFoRfW", "metadata": {}, "outcome_evaluations": [ { "completed_at": "2026-03-15T10:02:31Z", "description": "Produce a 2-page summary as summary.md", "explanation": "All five sections present with inline citations.", "iteration": 0, "outcome_id": "outc_011CZkZRSw2kEfs6ncTVljxP", "result": "satisfied", "type": "outcome_evaluation" } ], "resources": [ { "id": "sesrsc_011CZkZBJq5dWxk9fVLNcPht", "created_at": "2026-03-15T10:00:00Z", "file_id": "file_011CNha8iCJcU1wXNR6q4V8w", "mount_path": "/uploads/receipt.pdf", "type": "file", "updated_at": "2026-03-15T10:00:00Z" }, { "id": "sesrsc_011CZkZCKr6eXyl0gWMOdQiu", "created_at": "2026-03-15T10:00:00Z", "mount_path": "/workspace/example-repo", "type": "github_repository", "updated_at": "2026-03-15T10:00:00Z", "url": "https://github.com/example-org/example-repo", "checkout": { "name": "main", "type": "branch" } } ], "stats": { "active_seconds": 0, "duration_seconds": 0 }, "status": "idle", "title": "Order #1234 inquiry", "type": "session", "updated_at": "2026-03-15T10:00:00Z", "usage": { "cache_creation": { "ephemeral_1h_input_tokens": 0, "ephemeral_5m_input_tokens": 0 }, "cache_read_input_tokens": 0, "input_tokens": 0, "output_tokens": 0 }, "vault_ids": [ "vlt_011CZkZDLs7fYzm1hXNPeRjv" ] } ], "next_page": "page_MjAyNS0wNS0xNFQwMDowMDowMFo=" } ``` ## Get Session `client.beta.sessions.retrieve(stringsessionID, SessionRetrieveParamsparams?, RequestOptionsoptions?): BetaManagedAgentsSession` **get** `/v1/sessions/{session_id}` Get Session ### Parameters - `sessionID: string` - `params: SessionRetrieveParams` - `betas?: Array` Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaManagedAgentsSession` A Managed Agents `session`. - `id: string` - `agent: BetaManagedAgentsSessionAgent` Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. - `id: string` - `description: string | null` - `mcp_servers: Array` - `name: string` - `type: "url"` - `"url"` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `id: BetaManagedAgentsModel` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-opus-4-8" | "claude-opus-4-7" | "claude-opus-4-6" | 7 more` - `"claude-opus-4-8"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-7"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-6"` Most intelligent model for building agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` Fastest model with near-frontier intelligence - `"claude-haiku-4-5-20251001"` Fastest model with near-frontier intelligence - `"claude-opus-4-5"` Premium model combining maximum intelligence with practical performance - `"claude-opus-4-5-20251101"` Premium model combining maximum intelligence with practical performance - `"claude-sonnet-4-5"` High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` High-performance model for agents and coding - `(string & {})` - `speed?: "standard" | "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `multiagent: BetaManagedAgentsSessionMultiagentCoordinator | null` Resolved coordinator topology with full agent definitions for each roster member. - `agents: Array` Full `agent` definitions the coordinator may spawn as session threads. - `id: string` - `description: string | null` - `mcp_servers: Array` - `name: string` - `type: "url"` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `name: string` - `skills: Array` - `BetaManagedAgentsAnthropicSkill` A resolved Anthropic-managed skill. - `skill_id: string` - `type: "anthropic"` - `"anthropic"` - `version: string` - `BetaManagedAgentsCustomSkill` A resolved user-created custom skill. - `skill_id: string` - `type: "custom"` - `"custom"` - `version: string` - `system: string | null` - `tools: Array` - `BetaManagedAgentsAgentToolset20260401` - `configs: Array` - `enabled: boolean` - `name: "bash" | "edit" | "read" | 5 more` Built-in agent tool identifier. - `"bash"` - `"edit"` - `"read"` - `"write"` - `"glob"` - `"grep"` - `"web_fetch"` - `"web_search"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `"always_allow"` - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "always_ask"` - `"always_ask"` - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` Resolved default configuration for agent tools. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "agent_toolset_20260401"` - `"agent_toolset_20260401"` - `BetaManagedAgentsMCPToolset` - `configs: Array` - `enabled: boolean` - `name: string` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` Resolved default configuration for all tools from an MCP server. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `mcp_server_name: string` - `type: "mcp_toolset"` - `"mcp_toolset"` - `BetaManagedAgentsCustomTool` A custom tool as returned in API responses. - `description: string` - `input_schema: BetaManagedAgentsCustomToolInputSchema` JSON Schema for custom tool input parameters. - `properties?: Record | null` JSON Schema properties defining the tool's input parameters. - `required?: Array` List of required property names. - `type?: "object"` Must be 'object' for tool input schemas. - `"object"` - `name: string` - `type: "custom"` - `"custom"` - `type: "agent"` - `"agent"` - `version: number` - `type: "coordinator"` - `"coordinator"` - `name: string` - `skills: Array` - `BetaManagedAgentsAnthropicSkill` A resolved Anthropic-managed skill. - `BetaManagedAgentsCustomSkill` A resolved user-created custom skill. - `system: string | null` - `tools: Array` - `BetaManagedAgentsAgentToolset20260401` - `BetaManagedAgentsMCPToolset` - `BetaManagedAgentsCustomTool` A custom tool as returned in API responses. - `type: "agent"` - `"agent"` - `version: number` - `archived_at: string | null` A timestamp in RFC 3339 format - `created_at: string` A timestamp in RFC 3339 format - `environment_id: string` - `metadata: Record` - `outcome_evaluations: Array` Per-outcome evaluation state. One entry per define_outcome event sent to the session. - `completed_at: string | null` A timestamp in RFC 3339 format - `description: string` What the agent should produce. - `explanation: string | null` Grader's verdict text from the most recent evaluation. For satisfied, explains why criteria are met; for needs_revision (intermediate), what's missing; for failed, why unrecoverable. - `iteration: number` 0-indexed revision cycle the outcome is currently on. - `outcome_id: string` Server-generated outc_ ID for this outcome. - `result: string` Current evaluation state. `pending` before the agent begins work; `running` while producing or revising; `evaluating` while the grader scores; `satisfied`/`max_iterations_reached`/`failed`/`interrupted` are terminal. - `type: "outcome_evaluation"` - `"outcome_evaluation"` - `resources: Array` - `BetaManagedAgentsGitHubRepositoryResource` - `id: string` - `created_at: string` A timestamp in RFC 3339 format - `mount_path: string` - `type: "github_repository"` - `"github_repository"` - `updated_at: string` A timestamp in RFC 3339 format - `url: string` - `checkout?: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout | null` - `BetaManagedAgentsBranchCheckout` - `name: string` Branch name to check out. - `type: "branch"` - `"branch"` - `BetaManagedAgentsCommitCheckout` - `sha: string` Full commit SHA to check out. - `type: "commit"` - `"commit"` - `BetaManagedAgentsFileResource` - `id: string` - `created_at: string` A timestamp in RFC 3339 format - `file_id: string` - `mount_path: string` - `type: "file"` - `"file"` - `updated_at: string` A timestamp in RFC 3339 format - `BetaManagedAgentsMemoryStoreResource` A memory store attached to an agent session. - `memory_store_id: string` The memory store ID (memstore_...). Must belong to the caller's organization and workspace. - `type: "memory_store"` - `"memory_store"` - `access?: "read_write" | "read_only" | null` Access mode for an attached memory store. - `"read_write"` - `"read_only"` - `description?: string` Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description. - `instructions?: string | null` Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars. - `mount_path?: string | null` Filesystem path where the store is mounted in the session container, e.g. /mnt/memory/user-preferences. Derived from the store's name. Output-only. - `name?: string | null` Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource. - `stats: BetaManagedAgentsSessionStats` Timing statistics for a session. - `active_seconds?: number` Cumulative time in seconds the session spent in running status. Excludes idle time. - `duration_seconds?: number` Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. - `status: "rescheduling" | "running" | "idle" | "terminated"` SessionStatus enum - `"rescheduling"` - `"running"` - `"idle"` - `"terminated"` - `title: string | null` - `type: "session"` - `"session"` - `updated_at: string` A timestamp in RFC 3339 format - `usage: BetaManagedAgentsSessionUsage` Cumulative token usage for a session across all turns. - `cache_creation?: BetaManagedAgentsCacheCreationUsage` Prompt-cache creation token usage broken down by cache lifetime. - `ephemeral_1h_input_tokens?: number` Tokens used to create 1-hour ephemeral cache entries. - `ephemeral_5m_input_tokens?: number` Tokens used to create 5-minute ephemeral cache entries. - `cache_read_input_tokens?: number` Total tokens read from prompt cache. - `input_tokens?: number` Total input tokens consumed across all turns. - `output_tokens?: number` Total output tokens generated across all turns. - `vault_ids: Array` Vault IDs attached to the session at creation. Empty when no vaults were supplied. ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const betaManagedAgentsSession = await client.beta.sessions.retrieve( 'sesn_011CZkZAtmR3yMPDzynEDxu7', ); console.log(betaManagedAgentsSession.id); ``` #### Response ```json { "id": "sesn_011CZkZAtmR3yMPDzynEDxu7", "agent": { "id": "agent_011CZkYpogX7uDKUyvBTophP", "description": "A general-purpose starter agent.", "mcp_servers": [ { "name": "example-mcp", "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse" } ], "model": { "id": "claude-sonnet-4-6", "speed": "standard" }, "multiagent": { "agents": [ { "id": "agent_011CZkYqphY8vELVzwCUpqiQ", "description": "A focused research subagent.", "mcp_servers": [ { "name": "example-mcp", "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse" } ], "model": { "id": "claude-sonnet-4-6", "speed": "standard" }, "name": "Researcher", "skills": [ { "skill_id": "xlsx", "type": "anthropic", "version": "1" } ], "system": "You are a research subagent that gathers and summarises sources for the coordinating agent.", "tools": [ { "configs": [ { "enabled": true, "name": "bash", "permission_policy": { "type": "always_allow" } } ], "default_config": { "enabled": true, "permission_policy": { "type": "always_ask" } }, "type": "agent_toolset_20260401" } ], "type": "agent", "version": 1 } ], "type": "coordinator" }, "name": "My First Agent", "skills": [ { "skill_id": "xlsx", "type": "anthropic", "version": "1" }, { "skill_id": "skill_011CZkZFNu9hAbo3jZPRgTlx", "type": "custom", "version": "2" } ], "system": "You are a general-purpose agent that can research, write code, run commands, and use connected tools to complete the user's task end to end.", "tools": [ { "configs": [ { "enabled": true, "name": "bash", "permission_policy": { "type": "always_allow" } } ], "default_config": { "enabled": true, "permission_policy": { "type": "always_ask" } }, "type": "agent_toolset_20260401" } ], "type": "agent", "version": 1 }, "archived_at": null, "created_at": "2026-03-15T10:00:00Z", "environment_id": "env_011CZkZ9X2dpNyB7HsEFoRfW", "metadata": {}, "outcome_evaluations": [ { "completed_at": "2026-03-15T10:02:31Z", "description": "Produce a 2-page summary as summary.md", "explanation": "All five sections present with inline citations.", "iteration": 0, "outcome_id": "outc_011CZkZRSw2kEfs6ncTVljxP", "result": "satisfied", "type": "outcome_evaluation" } ], "resources": [ { "id": "sesrsc_011CZkZBJq5dWxk9fVLNcPht", "created_at": "2026-03-15T10:00:00Z", "file_id": "file_011CNha8iCJcU1wXNR6q4V8w", "mount_path": "/uploads/receipt.pdf", "type": "file", "updated_at": "2026-03-15T10:00:00Z" }, { "id": "sesrsc_011CZkZCKr6eXyl0gWMOdQiu", "created_at": "2026-03-15T10:00:00Z", "mount_path": "/workspace/example-repo", "type": "github_repository", "updated_at": "2026-03-15T10:00:00Z", "url": "https://github.com/example-org/example-repo", "checkout": { "name": "main", "type": "branch" } } ], "stats": { "active_seconds": 0, "duration_seconds": 0 }, "status": "idle", "title": "Order #1234 inquiry", "type": "session", "updated_at": "2026-03-15T10:00:00Z", "usage": { "cache_creation": { "ephemeral_1h_input_tokens": 0, "ephemeral_5m_input_tokens": 0 }, "cache_read_input_tokens": 0, "input_tokens": 0, "output_tokens": 0 }, "vault_ids": [ "vlt_011CZkZDLs7fYzm1hXNPeRjv" ] } ``` ## Update Session `client.beta.sessions.update(stringsessionID, SessionUpdateParamsparams, RequestOptionsoptions?): BetaManagedAgentsSession` **post** `/v1/sessions/{session_id}` Update Session ### Parameters - `sessionID: string` - `params: SessionUpdateParams` - `agent?: BetaManagedAgentsSessionAgentUpdate` Body param: Mid-session agent configuration update. Only `tools` and `mcp_servers` are updatable. Full replacement: the provided array becomes the new value. To preserve existing entries, GET the session, modify the array, and POST it back. - `mcp_servers?: Array` Replacement MCP server list. Full replacement: the provided array becomes the new value. Send an empty array to clear; omit to preserve. - `name: string` Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters. - `type: "url"` - `"url"` - `url: string` Endpoint URL for the MCP server. - `tools?: Array` Replacement tool list. Full replacement: the provided array becomes the new value. Send an empty array to clear; omit to preserve. - `BetaManagedAgentsAgentToolset20260401Params` Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent. - `type: "agent_toolset_20260401"` - `"agent_toolset_20260401"` - `configs?: Array` Per-tool configuration overrides. - `name: "bash" | "edit" | "read" | 5 more` Built-in agent tool identifier. - `"bash"` - `"edit"` - `"read"` - `"write"` - `"glob"` - `"grep"` - `"web_fetch"` - `"web_search"` - `enabled?: boolean | null` Whether this tool is enabled and available to Claude. Overrides the default_config setting. - `permission_policy?: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy | null` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `"always_allow"` - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "always_ask"` - `"always_ask"` - `default_config?: BetaManagedAgentsAgentToolsetDefaultConfigParams | null` Default configuration for all tools in a toolset. - `enabled?: boolean | null` Whether tools are enabled and available to Claude by default. Defaults to true if not specified. - `permission_policy?: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy | null` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `BetaManagedAgentsMCPToolsetParams` Configuration for tools from an MCP server defined in `mcp_servers`. - `mcp_server_name: string` Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters. - `type: "mcp_toolset"` - `"mcp_toolset"` - `configs?: Array` Per-tool configuration overrides. - `name: string` Name of the MCP tool to configure. 1-128 characters. - `enabled?: boolean | null` Whether this tool is enabled. Overrides the `default_config` setting. - `permission_policy?: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy | null` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `default_config?: BetaManagedAgentsMCPToolsetDefaultConfigParams | null` Default configuration for all tools from an MCP server. - `enabled?: boolean | null` Whether tools are enabled by default. Defaults to true if not specified. - `permission_policy?: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy | null` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `BetaManagedAgentsCustomToolParams` A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an `agent.custom_tool_use` event is emitted and the session goes idle, waiting for the client to provide the result via a `user.custom_tool_result` event. - `description: string` Description of what the tool does, shown to the agent to help it decide when to use the tool. 1-1024 characters. - `input_schema: BetaManagedAgentsCustomToolInputSchema` JSON Schema for custom tool input parameters. - `properties?: Record | null` JSON Schema properties defining the tool's input parameters. - `required?: Array` List of required property names. - `type?: "object"` Must be 'object' for tool input schemas. - `"object"` - `name: string` Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens. - `type: "custom"` - `"custom"` - `metadata?: Record | null` Body param: Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve. - `title?: string | null` Body param: Human-readable session title. - `vault_ids?: Array` Body param: Vault IDs (`vlt_*`) to attach to the session. Not yet supported; requests setting this field are rejected. Reserved for future use. - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaManagedAgentsSession` A Managed Agents `session`. - `id: string` - `agent: BetaManagedAgentsSessionAgent` Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. - `id: string` - `description: string | null` - `mcp_servers: Array` - `name: string` - `type: "url"` - `"url"` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `id: BetaManagedAgentsModel` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-opus-4-8" | "claude-opus-4-7" | "claude-opus-4-6" | 7 more` - `"claude-opus-4-8"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-7"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-6"` Most intelligent model for building agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` Fastest model with near-frontier intelligence - `"claude-haiku-4-5-20251001"` Fastest model with near-frontier intelligence - `"claude-opus-4-5"` Premium model combining maximum intelligence with practical performance - `"claude-opus-4-5-20251101"` Premium model combining maximum intelligence with practical performance - `"claude-sonnet-4-5"` High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` High-performance model for agents and coding - `(string & {})` - `speed?: "standard" | "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `multiagent: BetaManagedAgentsSessionMultiagentCoordinator | null` Resolved coordinator topology with full agent definitions for each roster member. - `agents: Array` Full `agent` definitions the coordinator may spawn as session threads. - `id: string` - `description: string | null` - `mcp_servers: Array` - `name: string` - `type: "url"` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `name: string` - `skills: Array` - `BetaManagedAgentsAnthropicSkill` A resolved Anthropic-managed skill. - `skill_id: string` - `type: "anthropic"` - `"anthropic"` - `version: string` - `BetaManagedAgentsCustomSkill` A resolved user-created custom skill. - `skill_id: string` - `type: "custom"` - `"custom"` - `version: string` - `system: string | null` - `tools: Array` - `BetaManagedAgentsAgentToolset20260401` - `configs: Array` - `enabled: boolean` - `name: "bash" | "edit" | "read" | 5 more` Built-in agent tool identifier. - `"bash"` - `"edit"` - `"read"` - `"write"` - `"glob"` - `"grep"` - `"web_fetch"` - `"web_search"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `"always_allow"` - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "always_ask"` - `"always_ask"` - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` Resolved default configuration for agent tools. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "agent_toolset_20260401"` - `"agent_toolset_20260401"` - `BetaManagedAgentsMCPToolset` - `configs: Array` - `enabled: boolean` - `name: string` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` Resolved default configuration for all tools from an MCP server. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `mcp_server_name: string` - `type: "mcp_toolset"` - `"mcp_toolset"` - `BetaManagedAgentsCustomTool` A custom tool as returned in API responses. - `description: string` - `input_schema: BetaManagedAgentsCustomToolInputSchema` JSON Schema for custom tool input parameters. - `properties?: Record | null` JSON Schema properties defining the tool's input parameters. - `required?: Array` List of required property names. - `type?: "object"` Must be 'object' for tool input schemas. - `"object"` - `name: string` - `type: "custom"` - `"custom"` - `type: "agent"` - `"agent"` - `version: number` - `type: "coordinator"` - `"coordinator"` - `name: string` - `skills: Array` - `BetaManagedAgentsAnthropicSkill` A resolved Anthropic-managed skill. - `BetaManagedAgentsCustomSkill` A resolved user-created custom skill. - `system: string | null` - `tools: Array` - `BetaManagedAgentsAgentToolset20260401` - `BetaManagedAgentsMCPToolset` - `BetaManagedAgentsCustomTool` A custom tool as returned in API responses. - `type: "agent"` - `"agent"` - `version: number` - `archived_at: string | null` A timestamp in RFC 3339 format - `created_at: string` A timestamp in RFC 3339 format - `environment_id: string` - `metadata: Record` - `outcome_evaluations: Array` Per-outcome evaluation state. One entry per define_outcome event sent to the session. - `completed_at: string | null` A timestamp in RFC 3339 format - `description: string` What the agent should produce. - `explanation: string | null` Grader's verdict text from the most recent evaluation. For satisfied, explains why criteria are met; for needs_revision (intermediate), what's missing; for failed, why unrecoverable. - `iteration: number` 0-indexed revision cycle the outcome is currently on. - `outcome_id: string` Server-generated outc_ ID for this outcome. - `result: string` Current evaluation state. `pending` before the agent begins work; `running` while producing or revising; `evaluating` while the grader scores; `satisfied`/`max_iterations_reached`/`failed`/`interrupted` are terminal. - `type: "outcome_evaluation"` - `"outcome_evaluation"` - `resources: Array` - `BetaManagedAgentsGitHubRepositoryResource` - `id: string` - `created_at: string` A timestamp in RFC 3339 format - `mount_path: string` - `type: "github_repository"` - `"github_repository"` - `updated_at: string` A timestamp in RFC 3339 format - `url: string` - `checkout?: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout | null` - `BetaManagedAgentsBranchCheckout` - `name: string` Branch name to check out. - `type: "branch"` - `"branch"` - `BetaManagedAgentsCommitCheckout` - `sha: string` Full commit SHA to check out. - `type: "commit"` - `"commit"` - `BetaManagedAgentsFileResource` - `id: string` - `created_at: string` A timestamp in RFC 3339 format - `file_id: string` - `mount_path: string` - `type: "file"` - `"file"` - `updated_at: string` A timestamp in RFC 3339 format - `BetaManagedAgentsMemoryStoreResource` A memory store attached to an agent session. - `memory_store_id: string` The memory store ID (memstore_...). Must belong to the caller's organization and workspace. - `type: "memory_store"` - `"memory_store"` - `access?: "read_write" | "read_only" | null` Access mode for an attached memory store. - `"read_write"` - `"read_only"` - `description?: string` Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description. - `instructions?: string | null` Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars. - `mount_path?: string | null` Filesystem path where the store is mounted in the session container, e.g. /mnt/memory/user-preferences. Derived from the store's name. Output-only. - `name?: string | null` Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource. - `stats: BetaManagedAgentsSessionStats` Timing statistics for a session. - `active_seconds?: number` Cumulative time in seconds the session spent in running status. Excludes idle time. - `duration_seconds?: number` Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. - `status: "rescheduling" | "running" | "idle" | "terminated"` SessionStatus enum - `"rescheduling"` - `"running"` - `"idle"` - `"terminated"` - `title: string | null` - `type: "session"` - `"session"` - `updated_at: string` A timestamp in RFC 3339 format - `usage: BetaManagedAgentsSessionUsage` Cumulative token usage for a session across all turns. - `cache_creation?: BetaManagedAgentsCacheCreationUsage` Prompt-cache creation token usage broken down by cache lifetime. - `ephemeral_1h_input_tokens?: number` Tokens used to create 1-hour ephemeral cache entries. - `ephemeral_5m_input_tokens?: number` Tokens used to create 5-minute ephemeral cache entries. - `cache_read_input_tokens?: number` Total tokens read from prompt cache. - `input_tokens?: number` Total input tokens consumed across all turns. - `output_tokens?: number` Total output tokens generated across all turns. - `vault_ids: Array` Vault IDs attached to the session at creation. Empty when no vaults were supplied. ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const betaManagedAgentsSession = await client.beta.sessions.update('sesn_011CZkZAtmR3yMPDzynEDxu7'); console.log(betaManagedAgentsSession.id); ``` #### Response ```json { "id": "sesn_011CZkZAtmR3yMPDzynEDxu7", "agent": { "id": "agent_011CZkYpogX7uDKUyvBTophP", "description": "A general-purpose starter agent.", "mcp_servers": [ { "name": "example-mcp", "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse" } ], "model": { "id": "claude-sonnet-4-6", "speed": "standard" }, "multiagent": { "agents": [ { "id": "agent_011CZkYqphY8vELVzwCUpqiQ", "description": "A focused research subagent.", "mcp_servers": [ { "name": "example-mcp", "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse" } ], "model": { "id": "claude-sonnet-4-6", "speed": "standard" }, "name": "Researcher", "skills": [ { "skill_id": "xlsx", "type": "anthropic", "version": "1" } ], "system": "You are a research subagent that gathers and summarises sources for the coordinating agent.", "tools": [ { "configs": [ { "enabled": true, "name": "bash", "permission_policy": { "type": "always_allow" } } ], "default_config": { "enabled": true, "permission_policy": { "type": "always_ask" } }, "type": "agent_toolset_20260401" } ], "type": "agent", "version": 1 } ], "type": "coordinator" }, "name": "My First Agent", "skills": [ { "skill_id": "xlsx", "type": "anthropic", "version": "1" }, { "skill_id": "skill_011CZkZFNu9hAbo3jZPRgTlx", "type": "custom", "version": "2" } ], "system": "You are a general-purpose agent that can research, write code, run commands, and use connected tools to complete the user's task end to end.", "tools": [ { "configs": [ { "enabled": true, "name": "bash", "permission_policy": { "type": "always_allow" } } ], "default_config": { "enabled": true, "permission_policy": { "type": "always_ask" } }, "type": "agent_toolset_20260401" } ], "type": "agent", "version": 1 }, "archived_at": null, "created_at": "2026-03-15T10:00:00Z", "environment_id": "env_011CZkZ9X2dpNyB7HsEFoRfW", "metadata": {}, "outcome_evaluations": [ { "completed_at": "2026-03-15T10:02:31Z", "description": "Produce a 2-page summary as summary.md", "explanation": "All five sections present with inline citations.", "iteration": 0, "outcome_id": "outc_011CZkZRSw2kEfs6ncTVljxP", "result": "satisfied", "type": "outcome_evaluation" } ], "resources": [ { "id": "sesrsc_011CZkZBJq5dWxk9fVLNcPht", "created_at": "2026-03-15T10:00:00Z", "file_id": "file_011CNha8iCJcU1wXNR6q4V8w", "mount_path": "/uploads/receipt.pdf", "type": "file", "updated_at": "2026-03-15T10:00:00Z" }, { "id": "sesrsc_011CZkZCKr6eXyl0gWMOdQiu", "created_at": "2026-03-15T10:00:00Z", "mount_path": "/workspace/example-repo", "type": "github_repository", "updated_at": "2026-03-15T10:00:00Z", "url": "https://github.com/example-org/example-repo", "checkout": { "name": "main", "type": "branch" } } ], "stats": { "active_seconds": 0, "duration_seconds": 0 }, "status": "idle", "title": "Order #1234 inquiry", "type": "session", "updated_at": "2026-03-15T10:00:00Z", "usage": { "cache_creation": { "ephemeral_1h_input_tokens": 0, "ephemeral_5m_input_tokens": 0 }, "cache_read_input_tokens": 0, "input_tokens": 0, "output_tokens": 0 }, "vault_ids": [ "vlt_011CZkZDLs7fYzm1hXNPeRjv" ] } ``` ## Delete Session `client.beta.sessions.delete(stringsessionID, SessionDeleteParamsparams?, RequestOptionsoptions?): BetaManagedAgentsDeletedSession` **delete** `/v1/sessions/{session_id}` Delete Session ### Parameters - `sessionID: string` - `params: SessionDeleteParams` - `betas?: Array` Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaManagedAgentsDeletedSession` Confirmation that a `session` has been permanently deleted. - `id: string` - `type: "session_deleted"` - `"session_deleted"` ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const betaManagedAgentsDeletedSession = await client.beta.sessions.delete( 'sesn_011CZkZAtmR3yMPDzynEDxu7', ); console.log(betaManagedAgentsDeletedSession.id); ``` #### Response ```json { "id": "sesn_011CZkZAtmR3yMPDzynEDxu7", "type": "session_deleted" } ``` ## Archive Session `client.beta.sessions.archive(stringsessionID, SessionArchiveParamsparams?, RequestOptionsoptions?): BetaManagedAgentsSession` **post** `/v1/sessions/{session_id}/archive` Archive Session ### Parameters - `sessionID: string` - `params: SessionArchiveParams` - `betas?: Array` Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaManagedAgentsSession` A Managed Agents `session`. - `id: string` - `agent: BetaManagedAgentsSessionAgent` Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. - `id: string` - `description: string | null` - `mcp_servers: Array` - `name: string` - `type: "url"` - `"url"` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `id: BetaManagedAgentsModel` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-opus-4-8" | "claude-opus-4-7" | "claude-opus-4-6" | 7 more` - `"claude-opus-4-8"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-7"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-6"` Most intelligent model for building agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` Fastest model with near-frontier intelligence - `"claude-haiku-4-5-20251001"` Fastest model with near-frontier intelligence - `"claude-opus-4-5"` Premium model combining maximum intelligence with practical performance - `"claude-opus-4-5-20251101"` Premium model combining maximum intelligence with practical performance - `"claude-sonnet-4-5"` High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` High-performance model for agents and coding - `(string & {})` - `speed?: "standard" | "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `multiagent: BetaManagedAgentsSessionMultiagentCoordinator | null` Resolved coordinator topology with full agent definitions for each roster member. - `agents: Array` Full `agent` definitions the coordinator may spawn as session threads. - `id: string` - `description: string | null` - `mcp_servers: Array` - `name: string` - `type: "url"` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `name: string` - `skills: Array` - `BetaManagedAgentsAnthropicSkill` A resolved Anthropic-managed skill. - `skill_id: string` - `type: "anthropic"` - `"anthropic"` - `version: string` - `BetaManagedAgentsCustomSkill` A resolved user-created custom skill. - `skill_id: string` - `type: "custom"` - `"custom"` - `version: string` - `system: string | null` - `tools: Array` - `BetaManagedAgentsAgentToolset20260401` - `configs: Array` - `enabled: boolean` - `name: "bash" | "edit" | "read" | 5 more` Built-in agent tool identifier. - `"bash"` - `"edit"` - `"read"` - `"write"` - `"glob"` - `"grep"` - `"web_fetch"` - `"web_search"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `"always_allow"` - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "always_ask"` - `"always_ask"` - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` Resolved default configuration for agent tools. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "agent_toolset_20260401"` - `"agent_toolset_20260401"` - `BetaManagedAgentsMCPToolset` - `configs: Array` - `enabled: boolean` - `name: string` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` Resolved default configuration for all tools from an MCP server. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `mcp_server_name: string` - `type: "mcp_toolset"` - `"mcp_toolset"` - `BetaManagedAgentsCustomTool` A custom tool as returned in API responses. - `description: string` - `input_schema: BetaManagedAgentsCustomToolInputSchema` JSON Schema for custom tool input parameters. - `properties?: Record | null` JSON Schema properties defining the tool's input parameters. - `required?: Array` List of required property names. - `type?: "object"` Must be 'object' for tool input schemas. - `"object"` - `name: string` - `type: "custom"` - `"custom"` - `type: "agent"` - `"agent"` - `version: number` - `type: "coordinator"` - `"coordinator"` - `name: string` - `skills: Array` - `BetaManagedAgentsAnthropicSkill` A resolved Anthropic-managed skill. - `BetaManagedAgentsCustomSkill` A resolved user-created custom skill. - `system: string | null` - `tools: Array` - `BetaManagedAgentsAgentToolset20260401` - `BetaManagedAgentsMCPToolset` - `BetaManagedAgentsCustomTool` A custom tool as returned in API responses. - `type: "agent"` - `"agent"` - `version: number` - `archived_at: string | null` A timestamp in RFC 3339 format - `created_at: string` A timestamp in RFC 3339 format - `environment_id: string` - `metadata: Record` - `outcome_evaluations: Array` Per-outcome evaluation state. One entry per define_outcome event sent to the session. - `completed_at: string | null` A timestamp in RFC 3339 format - `description: string` What the agent should produce. - `explanation: string | null` Grader's verdict text from the most recent evaluation. For satisfied, explains why criteria are met; for needs_revision (intermediate), what's missing; for failed, why unrecoverable. - `iteration: number` 0-indexed revision cycle the outcome is currently on. - `outcome_id: string` Server-generated outc_ ID for this outcome. - `result: string` Current evaluation state. `pending` before the agent begins work; `running` while producing or revising; `evaluating` while the grader scores; `satisfied`/`max_iterations_reached`/`failed`/`interrupted` are terminal. - `type: "outcome_evaluation"` - `"outcome_evaluation"` - `resources: Array` - `BetaManagedAgentsGitHubRepositoryResource` - `id: string` - `created_at: string` A timestamp in RFC 3339 format - `mount_path: string` - `type: "github_repository"` - `"github_repository"` - `updated_at: string` A timestamp in RFC 3339 format - `url: string` - `checkout?: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout | null` - `BetaManagedAgentsBranchCheckout` - `name: string` Branch name to check out. - `type: "branch"` - `"branch"` - `BetaManagedAgentsCommitCheckout` - `sha: string` Full commit SHA to check out. - `type: "commit"` - `"commit"` - `BetaManagedAgentsFileResource` - `id: string` - `created_at: string` A timestamp in RFC 3339 format - `file_id: string` - `mount_path: string` - `type: "file"` - `"file"` - `updated_at: string` A timestamp in RFC 3339 format - `BetaManagedAgentsMemoryStoreResource` A memory store attached to an agent session. - `memory_store_id: string` The memory store ID (memstore_...). Must belong to the caller's organization and workspace. - `type: "memory_store"` - `"memory_store"` - `access?: "read_write" | "read_only" | null` Access mode for an attached memory store. - `"read_write"` - `"read_only"` - `description?: string` Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description. - `instructions?: string | null` Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars. - `mount_path?: string | null` Filesystem path where the store is mounted in the session container, e.g. /mnt/memory/user-preferences. Derived from the store's name. Output-only. - `name?: string | null` Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource. - `stats: BetaManagedAgentsSessionStats` Timing statistics for a session. - `active_seconds?: number` Cumulative time in seconds the session spent in running status. Excludes idle time. - `duration_seconds?: number` Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. - `status: "rescheduling" | "running" | "idle" | "terminated"` SessionStatus enum - `"rescheduling"` - `"running"` - `"idle"` - `"terminated"` - `title: string | null` - `type: "session"` - `"session"` - `updated_at: string` A timestamp in RFC 3339 format - `usage: BetaManagedAgentsSessionUsage` Cumulative token usage for a session across all turns. - `cache_creation?: BetaManagedAgentsCacheCreationUsage` Prompt-cache creation token usage broken down by cache lifetime. - `ephemeral_1h_input_tokens?: number` Tokens used to create 1-hour ephemeral cache entries. - `ephemeral_5m_input_tokens?: number` Tokens used to create 5-minute ephemeral cache entries. - `cache_read_input_tokens?: number` Total tokens read from prompt cache. - `input_tokens?: number` Total input tokens consumed across all turns. - `output_tokens?: number` Total output tokens generated across all turns. - `vault_ids: Array` Vault IDs attached to the session at creation. Empty when no vaults were supplied. ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const betaManagedAgentsSession = await client.beta.sessions.archive( 'sesn_011CZkZAtmR3yMPDzynEDxu7', ); console.log(betaManagedAgentsSession.id); ``` #### Response ```json { "id": "sesn_011CZkZAtmR3yMPDzynEDxu7", "agent": { "id": "agent_011CZkYpogX7uDKUyvBTophP", "description": "A general-purpose starter agent.", "mcp_servers": [ { "name": "example-mcp", "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse" } ], "model": { "id": "claude-sonnet-4-6", "speed": "standard" }, "multiagent": { "agents": [ { "id": "agent_011CZkYqphY8vELVzwCUpqiQ", "description": "A focused research subagent.", "mcp_servers": [ { "name": "example-mcp", "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse" } ], "model": { "id": "claude-sonnet-4-6", "speed": "standard" }, "name": "Researcher", "skills": [ { "skill_id": "xlsx", "type": "anthropic", "version": "1" } ], "system": "You are a research subagent that gathers and summarises sources for the coordinating agent.", "tools": [ { "configs": [ { "enabled": true, "name": "bash", "permission_policy": { "type": "always_allow" } } ], "default_config": { "enabled": true, "permission_policy": { "type": "always_ask" } }, "type": "agent_toolset_20260401" } ], "type": "agent", "version": 1 } ], "type": "coordinator" }, "name": "My First Agent", "skills": [ { "skill_id": "xlsx", "type": "anthropic", "version": "1" }, { "skill_id": "skill_011CZkZFNu9hAbo3jZPRgTlx", "type": "custom", "version": "2" } ], "system": "You are a general-purpose agent that can research, write code, run commands, and use connected tools to complete the user's task end to end.", "tools": [ { "configs": [ { "enabled": true, "name": "bash", "permission_policy": { "type": "always_allow" } } ], "default_config": { "enabled": true, "permission_policy": { "type": "always_ask" } }, "type": "agent_toolset_20260401" } ], "type": "agent", "version": 1 }, "archived_at": null, "created_at": "2026-03-15T10:00:00Z", "environment_id": "env_011CZkZ9X2dpNyB7HsEFoRfW", "metadata": {}, "outcome_evaluations": [ { "completed_at": "2026-03-15T10:02:31Z", "description": "Produce a 2-page summary as summary.md", "explanation": "All five sections present with inline citations.", "iteration": 0, "outcome_id": "outc_011CZkZRSw2kEfs6ncTVljxP", "result": "satisfied", "type": "outcome_evaluation" } ], "resources": [ { "id": "sesrsc_011CZkZBJq5dWxk9fVLNcPht", "created_at": "2026-03-15T10:00:00Z", "file_id": "file_011CNha8iCJcU1wXNR6q4V8w", "mount_path": "/uploads/receipt.pdf", "type": "file", "updated_at": "2026-03-15T10:00:00Z" }, { "id": "sesrsc_011CZkZCKr6eXyl0gWMOdQiu", "created_at": "2026-03-15T10:00:00Z", "mount_path": "/workspace/example-repo", "type": "github_repository", "updated_at": "2026-03-15T10:00:00Z", "url": "https://github.com/example-org/example-repo", "checkout": { "name": "main", "type": "branch" } } ], "stats": { "active_seconds": 0, "duration_seconds": 0 }, "status": "idle", "title": "Order #1234 inquiry", "type": "session", "updated_at": "2026-03-15T10:00:00Z", "usage": { "cache_creation": { "ephemeral_1h_input_tokens": 0, "ephemeral_5m_input_tokens": 0 }, "cache_read_input_tokens": 0, "input_tokens": 0, "output_tokens": 0 }, "vault_ids": [ "vlt_011CZkZDLs7fYzm1hXNPeRjv" ] } ``` ## Domain Types ### Beta Managed Agents Agent Params - `BetaManagedAgentsAgentParams` Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version - `id: string` The `agent` ID. - `type: "agent"` - `"agent"` - `version?: number` The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified. ### Beta Managed Agents Branch Checkout - `BetaManagedAgentsBranchCheckout` - `name: string` Branch name to check out. - `type: "branch"` - `"branch"` ### Beta Managed Agents Cache Creation Usage - `BetaManagedAgentsCacheCreationUsage` Prompt-cache creation token usage broken down by cache lifetime. - `ephemeral_1h_input_tokens?: number` Tokens used to create 1-hour ephemeral cache entries. - `ephemeral_5m_input_tokens?: number` Tokens used to create 5-minute ephemeral cache entries. ### Beta Managed Agents Commit Checkout - `BetaManagedAgentsCommitCheckout` - `sha: string` Full commit SHA to check out. - `type: "commit"` - `"commit"` ### Beta Managed Agents Deleted Session - `BetaManagedAgentsDeletedSession` Confirmation that a `session` has been permanently deleted. - `id: string` - `type: "session_deleted"` - `"session_deleted"` ### Beta Managed Agents File Resource Params - `BetaManagedAgentsFileResourceParams` Mount a file uploaded via the Files API into the session. - `file_id: string` ID of a previously uploaded file. - `type: "file"` - `"file"` - `mount_path?: string | null` Mount path in the container. Defaults to `/mnt/session/uploads/`. ### Beta Managed Agents GitHub Repository Resource Params - `BetaManagedAgentsGitHubRepositoryResourceParams` Mount a GitHub repository into the session's container. - `authorization_token: string` GitHub authorization token used to clone the repository. - `type: "github_repository"` - `"github_repository"` - `url: string` Github URL of the repository - `checkout?: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout | null` Branch or commit to check out. Defaults to the repository's default branch. - `BetaManagedAgentsBranchCheckout` - `name: string` Branch name to check out. - `type: "branch"` - `"branch"` - `BetaManagedAgentsCommitCheckout` - `sha: string` Full commit SHA to check out. - `type: "commit"` - `"commit"` - `mount_path?: string | null` Mount path in the container. Defaults to `/workspace/`. ### Beta Managed Agents Memory Store Resource Param - `BetaManagedAgentsMemoryStoreResourceParam` Parameters for attaching a memory store to an agent session. - `memory_store_id: string` The memory store ID (memstore_...). Must belong to the caller's organization and workspace. - `type: "memory_store"` - `"memory_store"` - `access?: "read_write" | "read_only" | null` Access mode for an attached memory store. - `"read_write"` - `"read_only"` - `instructions?: string | null` Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars. ### Beta Managed Agents Multiagent - `BetaManagedAgentsMultiagent` Resolved coordinator topology with a concrete agent roster. - `agents: Array` Agents the coordinator may spawn as session threads, each resolved to a specific version. - `id: string` - `type: "agent"` - `"agent"` - `version: number` - `type: "coordinator"` - `"coordinator"` ### Beta Managed Agents Multiagent Params - `BetaManagedAgentsMultiagentParams` A coordinator topology: the session's primary thread orchestrates work by spawning session threads, each running an agent drawn from the `agents` roster. - `agents: Array` Agents the coordinator may spawn as session threads. 1–20 entries. Each entry is an agent ID string, a versioned `{"type":"agent","id","version"}` reference, or `{"type":"self"}` to allow recursive self-invocation. Entries must reference distinct agents (after resolving `self` and string forms); at most one `self`. Referenced agents must exist, must not be archived, and must not themselves have `multiagent` set (depth limit 1). - `string` - `BetaManagedAgentsAgentParams` Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version - `id: string` The `agent` ID. - `type: "agent"` - `"agent"` - `version?: number` The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified. - `BetaManagedAgentsMultiagentSelfParams` Sentinel roster entry meaning "the agent that owns this configuration". Resolved server-side to a concrete agent reference. - `type: "self"` - `"self"` - `type: "coordinator"` - `"coordinator"` ### Beta Managed Agents Multiagent Roster Entry Params - `BetaManagedAgentsMultiagentRosterEntryParams = string | BetaManagedAgentsAgentParams | BetaManagedAgentsMultiagentSelfParams` An entry in a multiagent roster: an agent ID string, a versioned agent reference, or `self`. - `string` - `BetaManagedAgentsAgentParams` Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version - `id: string` The `agent` ID. - `type: "agent"` - `"agent"` - `version?: number` The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified. - `BetaManagedAgentsMultiagentSelfParams` Sentinel roster entry meaning "the agent that owns this configuration". Resolved server-side to a concrete agent reference. - `type: "self"` - `"self"` ### Beta Managed Agents Outcome Evaluation Resource - `BetaManagedAgentsOutcomeEvaluationResource` Evaluation state for a single outcome defined via a define_outcome event. - `completed_at: string | null` A timestamp in RFC 3339 format - `description: string` What the agent should produce. - `explanation: string | null` Grader's verdict text from the most recent evaluation. For satisfied, explains why criteria are met; for needs_revision (intermediate), what's missing; for failed, why unrecoverable. - `iteration: number` 0-indexed revision cycle the outcome is currently on. - `outcome_id: string` Server-generated outc_ ID for this outcome. - `result: string` Current evaluation state. `pending` before the agent begins work; `running` while producing or revising; `evaluating` while the grader scores; `satisfied`/`max_iterations_reached`/`failed`/`interrupted` are terminal. - `type: "outcome_evaluation"` - `"outcome_evaluation"` ### Beta Managed Agents Session - `BetaManagedAgentsSession` A Managed Agents `session`. - `id: string` - `agent: BetaManagedAgentsSessionAgent` Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. - `id: string` - `description: string | null` - `mcp_servers: Array` - `name: string` - `type: "url"` - `"url"` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `id: BetaManagedAgentsModel` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-opus-4-8" | "claude-opus-4-7" | "claude-opus-4-6" | 7 more` - `"claude-opus-4-8"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-7"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-6"` Most intelligent model for building agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` Fastest model with near-frontier intelligence - `"claude-haiku-4-5-20251001"` Fastest model with near-frontier intelligence - `"claude-opus-4-5"` Premium model combining maximum intelligence with practical performance - `"claude-opus-4-5-20251101"` Premium model combining maximum intelligence with practical performance - `"claude-sonnet-4-5"` High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` High-performance model for agents and coding - `(string & {})` - `speed?: "standard" | "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `multiagent: BetaManagedAgentsSessionMultiagentCoordinator | null` Resolved coordinator topology with full agent definitions for each roster member. - `agents: Array` Full `agent` definitions the coordinator may spawn as session threads. - `id: string` - `description: string | null` - `mcp_servers: Array` - `name: string` - `type: "url"` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `name: string` - `skills: Array` - `BetaManagedAgentsAnthropicSkill` A resolved Anthropic-managed skill. - `skill_id: string` - `type: "anthropic"` - `"anthropic"` - `version: string` - `BetaManagedAgentsCustomSkill` A resolved user-created custom skill. - `skill_id: string` - `type: "custom"` - `"custom"` - `version: string` - `system: string | null` - `tools: Array` - `BetaManagedAgentsAgentToolset20260401` - `configs: Array` - `enabled: boolean` - `name: "bash" | "edit" | "read" | 5 more` Built-in agent tool identifier. - `"bash"` - `"edit"` - `"read"` - `"write"` - `"glob"` - `"grep"` - `"web_fetch"` - `"web_search"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `"always_allow"` - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "always_ask"` - `"always_ask"` - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` Resolved default configuration for agent tools. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "agent_toolset_20260401"` - `"agent_toolset_20260401"` - `BetaManagedAgentsMCPToolset` - `configs: Array` - `enabled: boolean` - `name: string` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` Resolved default configuration for all tools from an MCP server. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `mcp_server_name: string` - `type: "mcp_toolset"` - `"mcp_toolset"` - `BetaManagedAgentsCustomTool` A custom tool as returned in API responses. - `description: string` - `input_schema: BetaManagedAgentsCustomToolInputSchema` JSON Schema for custom tool input parameters. - `properties?: Record | null` JSON Schema properties defining the tool's input parameters. - `required?: Array` List of required property names. - `type?: "object"` Must be 'object' for tool input schemas. - `"object"` - `name: string` - `type: "custom"` - `"custom"` - `type: "agent"` - `"agent"` - `version: number` - `type: "coordinator"` - `"coordinator"` - `name: string` - `skills: Array` - `BetaManagedAgentsAnthropicSkill` A resolved Anthropic-managed skill. - `BetaManagedAgentsCustomSkill` A resolved user-created custom skill. - `system: string | null` - `tools: Array` - `BetaManagedAgentsAgentToolset20260401` - `BetaManagedAgentsMCPToolset` - `BetaManagedAgentsCustomTool` A custom tool as returned in API responses. - `type: "agent"` - `"agent"` - `version: number` - `archived_at: string | null` A timestamp in RFC 3339 format - `created_at: string` A timestamp in RFC 3339 format - `environment_id: string` - `metadata: Record` - `outcome_evaluations: Array` Per-outcome evaluation state. One entry per define_outcome event sent to the session. - `completed_at: string | null` A timestamp in RFC 3339 format - `description: string` What the agent should produce. - `explanation: string | null` Grader's verdict text from the most recent evaluation. For satisfied, explains why criteria are met; for needs_revision (intermediate), what's missing; for failed, why unrecoverable. - `iteration: number` 0-indexed revision cycle the outcome is currently on. - `outcome_id: string` Server-generated outc_ ID for this outcome. - `result: string` Current evaluation state. `pending` before the agent begins work; `running` while producing or revising; `evaluating` while the grader scores; `satisfied`/`max_iterations_reached`/`failed`/`interrupted` are terminal. - `type: "outcome_evaluation"` - `"outcome_evaluation"` - `resources: Array` - `BetaManagedAgentsGitHubRepositoryResource` - `id: string` - `created_at: string` A timestamp in RFC 3339 format - `mount_path: string` - `type: "github_repository"` - `"github_repository"` - `updated_at: string` A timestamp in RFC 3339 format - `url: string` - `checkout?: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout | null` - `BetaManagedAgentsBranchCheckout` - `name: string` Branch name to check out. - `type: "branch"` - `"branch"` - `BetaManagedAgentsCommitCheckout` - `sha: string` Full commit SHA to check out. - `type: "commit"` - `"commit"` - `BetaManagedAgentsFileResource` - `id: string` - `created_at: string` A timestamp in RFC 3339 format - `file_id: string` - `mount_path: string` - `type: "file"` - `"file"` - `updated_at: string` A timestamp in RFC 3339 format - `BetaManagedAgentsMemoryStoreResource` A memory store attached to an agent session. - `memory_store_id: string` The memory store ID (memstore_...). Must belong to the caller's organization and workspace. - `type: "memory_store"` - `"memory_store"` - `access?: "read_write" | "read_only" | null` Access mode for an attached memory store. - `"read_write"` - `"read_only"` - `description?: string` Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description. - `instructions?: string | null` Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars. - `mount_path?: string | null` Filesystem path where the store is mounted in the session container, e.g. /mnt/memory/user-preferences. Derived from the store's name. Output-only. - `name?: string | null` Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource. - `stats: BetaManagedAgentsSessionStats` Timing statistics for a session. - `active_seconds?: number` Cumulative time in seconds the session spent in running status. Excludes idle time. - `duration_seconds?: number` Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. - `status: "rescheduling" | "running" | "idle" | "terminated"` SessionStatus enum - `"rescheduling"` - `"running"` - `"idle"` - `"terminated"` - `title: string | null` - `type: "session"` - `"session"` - `updated_at: string` A timestamp in RFC 3339 format - `usage: BetaManagedAgentsSessionUsage` Cumulative token usage for a session across all turns. - `cache_creation?: BetaManagedAgentsCacheCreationUsage` Prompt-cache creation token usage broken down by cache lifetime. - `ephemeral_1h_input_tokens?: number` Tokens used to create 1-hour ephemeral cache entries. - `ephemeral_5m_input_tokens?: number` Tokens used to create 5-minute ephemeral cache entries. - `cache_read_input_tokens?: number` Total tokens read from prompt cache. - `input_tokens?: number` Total input tokens consumed across all turns. - `output_tokens?: number` Total output tokens generated across all turns. - `vault_ids: Array` Vault IDs attached to the session at creation. Empty when no vaults were supplied. ### Beta Managed Agents Session Agent - `BetaManagedAgentsSessionAgent` Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. - `id: string` - `description: string | null` - `mcp_servers: Array` - `name: string` - `type: "url"` - `"url"` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `id: BetaManagedAgentsModel` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-opus-4-8" | "claude-opus-4-7" | "claude-opus-4-6" | 7 more` - `"claude-opus-4-8"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-7"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-6"` Most intelligent model for building agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` Fastest model with near-frontier intelligence - `"claude-haiku-4-5-20251001"` Fastest model with near-frontier intelligence - `"claude-opus-4-5"` Premium model combining maximum intelligence with practical performance - `"claude-opus-4-5-20251101"` Premium model combining maximum intelligence with practical performance - `"claude-sonnet-4-5"` High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` High-performance model for agents and coding - `(string & {})` - `speed?: "standard" | "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `multiagent: BetaManagedAgentsSessionMultiagentCoordinator | null` Resolved coordinator topology with full agent definitions for each roster member. - `agents: Array` Full `agent` definitions the coordinator may spawn as session threads. - `id: string` - `description: string | null` - `mcp_servers: Array` - `name: string` - `type: "url"` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `name: string` - `skills: Array` - `BetaManagedAgentsAnthropicSkill` A resolved Anthropic-managed skill. - `skill_id: string` - `type: "anthropic"` - `"anthropic"` - `version: string` - `BetaManagedAgentsCustomSkill` A resolved user-created custom skill. - `skill_id: string` - `type: "custom"` - `"custom"` - `version: string` - `system: string | null` - `tools: Array` - `BetaManagedAgentsAgentToolset20260401` - `configs: Array` - `enabled: boolean` - `name: "bash" | "edit" | "read" | 5 more` Built-in agent tool identifier. - `"bash"` - `"edit"` - `"read"` - `"write"` - `"glob"` - `"grep"` - `"web_fetch"` - `"web_search"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `"always_allow"` - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "always_ask"` - `"always_ask"` - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` Resolved default configuration for agent tools. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "agent_toolset_20260401"` - `"agent_toolset_20260401"` - `BetaManagedAgentsMCPToolset` - `configs: Array` - `enabled: boolean` - `name: string` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` Resolved default configuration for all tools from an MCP server. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `mcp_server_name: string` - `type: "mcp_toolset"` - `"mcp_toolset"` - `BetaManagedAgentsCustomTool` A custom tool as returned in API responses. - `description: string` - `input_schema: BetaManagedAgentsCustomToolInputSchema` JSON Schema for custom tool input parameters. - `properties?: Record | null` JSON Schema properties defining the tool's input parameters. - `required?: Array` List of required property names. - `type?: "object"` Must be 'object' for tool input schemas. - `"object"` - `name: string` - `type: "custom"` - `"custom"` - `type: "agent"` - `"agent"` - `version: number` - `type: "coordinator"` - `"coordinator"` - `name: string` - `skills: Array` - `BetaManagedAgentsAnthropicSkill` A resolved Anthropic-managed skill. - `BetaManagedAgentsCustomSkill` A resolved user-created custom skill. - `system: string | null` - `tools: Array` - `BetaManagedAgentsAgentToolset20260401` - `BetaManagedAgentsMCPToolset` - `BetaManagedAgentsCustomTool` A custom tool as returned in API responses. - `type: "agent"` - `"agent"` - `version: number` ### Beta Managed Agents Session Agent Update - `BetaManagedAgentsSessionAgentUpdate` Mid-session agent configuration update. Only `tools` and `mcp_servers` are updatable. Full replacement: the provided array becomes the new value. To preserve existing entries, GET the session, modify the array, and POST it back. - `mcp_servers?: Array` Replacement MCP server list. Full replacement: the provided array becomes the new value. Send an empty array to clear; omit to preserve. - `name: string` Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters. - `type: "url"` - `"url"` - `url: string` Endpoint URL for the MCP server. - `tools?: Array` Replacement tool list. Full replacement: the provided array becomes the new value. Send an empty array to clear; omit to preserve. - `BetaManagedAgentsAgentToolset20260401Params` Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent. - `type: "agent_toolset_20260401"` - `"agent_toolset_20260401"` - `configs?: Array` Per-tool configuration overrides. - `name: "bash" | "edit" | "read" | 5 more` Built-in agent tool identifier. - `"bash"` - `"edit"` - `"read"` - `"write"` - `"glob"` - `"grep"` - `"web_fetch"` - `"web_search"` - `enabled?: boolean | null` Whether this tool is enabled and available to Claude. Overrides the default_config setting. - `permission_policy?: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy | null` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `"always_allow"` - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "always_ask"` - `"always_ask"` - `default_config?: BetaManagedAgentsAgentToolsetDefaultConfigParams | null` Default configuration for all tools in a toolset. - `enabled?: boolean | null` Whether tools are enabled and available to Claude by default. Defaults to true if not specified. - `permission_policy?: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy | null` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `BetaManagedAgentsMCPToolsetParams` Configuration for tools from an MCP server defined in `mcp_servers`. - `mcp_server_name: string` Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters. - `type: "mcp_toolset"` - `"mcp_toolset"` - `configs?: Array` Per-tool configuration overrides. - `name: string` Name of the MCP tool to configure. 1-128 characters. - `enabled?: boolean | null` Whether this tool is enabled. Overrides the `default_config` setting. - `permission_policy?: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy | null` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `default_config?: BetaManagedAgentsMCPToolsetDefaultConfigParams | null` Default configuration for all tools from an MCP server. - `enabled?: boolean | null` Whether tools are enabled by default. Defaults to true if not specified. - `permission_policy?: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy | null` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `BetaManagedAgentsCustomToolParams` A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an `agent.custom_tool_use` event is emitted and the session goes idle, waiting for the client to provide the result via a `user.custom_tool_result` event. - `description: string` Description of what the tool does, shown to the agent to help it decide when to use the tool. 1-1024 characters. - `input_schema: BetaManagedAgentsCustomToolInputSchema` JSON Schema for custom tool input parameters. - `properties?: Record | null` JSON Schema properties defining the tool's input parameters. - `required?: Array` List of required property names. - `type?: "object"` Must be 'object' for tool input schemas. - `"object"` - `name: string` Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens. - `type: "custom"` - `"custom"` ### Beta Managed Agents Session Multiagent Coordinator - `BetaManagedAgentsSessionMultiagentCoordinator` Resolved coordinator topology with full agent definitions for each roster member. - `agents: Array` Full `agent` definitions the coordinator may spawn as session threads. - `id: string` - `description: string | null` - `mcp_servers: Array` - `name: string` - `type: "url"` - `"url"` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `id: BetaManagedAgentsModel` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-opus-4-8" | "claude-opus-4-7" | "claude-opus-4-6" | 7 more` - `"claude-opus-4-8"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-7"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-6"` Most intelligent model for building agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` Fastest model with near-frontier intelligence - `"claude-haiku-4-5-20251001"` Fastest model with near-frontier intelligence - `"claude-opus-4-5"` Premium model combining maximum intelligence with practical performance - `"claude-opus-4-5-20251101"` Premium model combining maximum intelligence with practical performance - `"claude-sonnet-4-5"` High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` High-performance model for agents and coding - `(string & {})` - `speed?: "standard" | "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `name: string` - `skills: Array` - `BetaManagedAgentsAnthropicSkill` A resolved Anthropic-managed skill. - `skill_id: string` - `type: "anthropic"` - `"anthropic"` - `version: string` - `BetaManagedAgentsCustomSkill` A resolved user-created custom skill. - `skill_id: string` - `type: "custom"` - `"custom"` - `version: string` - `system: string | null` - `tools: Array` - `BetaManagedAgentsAgentToolset20260401` - `configs: Array` - `enabled: boolean` - `name: "bash" | "edit" | "read" | 5 more` Built-in agent tool identifier. - `"bash"` - `"edit"` - `"read"` - `"write"` - `"glob"` - `"grep"` - `"web_fetch"` - `"web_search"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `"always_allow"` - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "always_ask"` - `"always_ask"` - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` Resolved default configuration for agent tools. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "agent_toolset_20260401"` - `"agent_toolset_20260401"` - `BetaManagedAgentsMCPToolset` - `configs: Array` - `enabled: boolean` - `name: string` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` Resolved default configuration for all tools from an MCP server. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `mcp_server_name: string` - `type: "mcp_toolset"` - `"mcp_toolset"` - `BetaManagedAgentsCustomTool` A custom tool as returned in API responses. - `description: string` - `input_schema: BetaManagedAgentsCustomToolInputSchema` JSON Schema for custom tool input parameters. - `properties?: Record | null` JSON Schema properties defining the tool's input parameters. - `required?: Array` List of required property names. - `type?: "object"` Must be 'object' for tool input schemas. - `"object"` - `name: string` - `type: "custom"` - `"custom"` - `type: "agent"` - `"agent"` - `version: number` - `type: "coordinator"` - `"coordinator"` ### Beta Managed Agents Session Stats - `BetaManagedAgentsSessionStats` Timing statistics for a session. - `active_seconds?: number` Cumulative time in seconds the session spent in running status. Excludes idle time. - `duration_seconds?: number` Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. ### Beta Managed Agents Session Updated Event - `BetaManagedAgentsSessionUpdatedEvent` Emitted when an UpdateSession request changed at least one field. Carries only the fields that changed; absent fields were not part of the update. The new configuration applies from the next turn. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `type: "session.updated"` - `"session.updated"` - `agent?: BetaManagedAgentsSessionAgent | null` Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. - `id: string` - `description: string | null` - `mcp_servers: Array` - `name: string` - `type: "url"` - `"url"` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `id: BetaManagedAgentsModel` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-opus-4-8" | "claude-opus-4-7" | "claude-opus-4-6" | 7 more` - `"claude-opus-4-8"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-7"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-6"` Most intelligent model for building agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` Fastest model with near-frontier intelligence - `"claude-haiku-4-5-20251001"` Fastest model with near-frontier intelligence - `"claude-opus-4-5"` Premium model combining maximum intelligence with practical performance - `"claude-opus-4-5-20251101"` Premium model combining maximum intelligence with practical performance - `"claude-sonnet-4-5"` High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` High-performance model for agents and coding - `(string & {})` - `speed?: "standard" | "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `multiagent: BetaManagedAgentsSessionMultiagentCoordinator | null` Resolved coordinator topology with full agent definitions for each roster member. - `agents: Array` Full `agent` definitions the coordinator may spawn as session threads. - `id: string` - `description: string | null` - `mcp_servers: Array` - `name: string` - `type: "url"` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `name: string` - `skills: Array` - `BetaManagedAgentsAnthropicSkill` A resolved Anthropic-managed skill. - `skill_id: string` - `type: "anthropic"` - `"anthropic"` - `version: string` - `BetaManagedAgentsCustomSkill` A resolved user-created custom skill. - `skill_id: string` - `type: "custom"` - `"custom"` - `version: string` - `system: string | null` - `tools: Array` - `BetaManagedAgentsAgentToolset20260401` - `configs: Array` - `enabled: boolean` - `name: "bash" | "edit" | "read" | 5 more` Built-in agent tool identifier. - `"bash"` - `"edit"` - `"read"` - `"write"` - `"glob"` - `"grep"` - `"web_fetch"` - `"web_search"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `"always_allow"` - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "always_ask"` - `"always_ask"` - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` Resolved default configuration for agent tools. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "agent_toolset_20260401"` - `"agent_toolset_20260401"` - `BetaManagedAgentsMCPToolset` - `configs: Array` - `enabled: boolean` - `name: string` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` Resolved default configuration for all tools from an MCP server. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `mcp_server_name: string` - `type: "mcp_toolset"` - `"mcp_toolset"` - `BetaManagedAgentsCustomTool` A custom tool as returned in API responses. - `description: string` - `input_schema: BetaManagedAgentsCustomToolInputSchema` JSON Schema for custom tool input parameters. - `properties?: Record | null` JSON Schema properties defining the tool's input parameters. - `required?: Array` List of required property names. - `type?: "object"` Must be 'object' for tool input schemas. - `"object"` - `name: string` - `type: "custom"` - `"custom"` - `type: "agent"` - `"agent"` - `version: number` - `type: "coordinator"` - `"coordinator"` - `name: string` - `skills: Array` - `BetaManagedAgentsAnthropicSkill` A resolved Anthropic-managed skill. - `BetaManagedAgentsCustomSkill` A resolved user-created custom skill. - `system: string | null` - `tools: Array` - `BetaManagedAgentsAgentToolset20260401` - `BetaManagedAgentsMCPToolset` - `BetaManagedAgentsCustomTool` A custom tool as returned in API responses. - `type: "agent"` - `"agent"` - `version: number` - `metadata?: Record` The session's full metadata bag after the update. Present when the update set non-empty metadata; absent when metadata was unchanged or cleared to empty. - `title?: string | null` The session's new title. Present only when the update changed it. ### Beta Managed Agents Session Usage - `BetaManagedAgentsSessionUsage` Cumulative token usage for a session across all turns. - `cache_creation?: BetaManagedAgentsCacheCreationUsage` Prompt-cache creation token usage broken down by cache lifetime. - `ephemeral_1h_input_tokens?: number` Tokens used to create 1-hour ephemeral cache entries. - `ephemeral_5m_input_tokens?: number` Tokens used to create 5-minute ephemeral cache entries. - `cache_read_input_tokens?: number` Total tokens read from prompt cache. - `input_tokens?: number` Total input tokens consumed across all turns. - `output_tokens?: number` Total output tokens generated across all turns. ### Beta Managed Agents User Tool Result Event - `BetaManagedAgentsUserToolResultEvent` Event sent by the client providing the result of an agent-toolset tool execution. Only valid on `self_hosted` environments, where sandbox-routed tools are executed by the client rather than the server. - `id: string` Unique identifier for this event. - `tool_use_id: string` The id of the `agent.tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `type: "user.tool_result"` - `"user.tool_result"` - `content?: Array` The result content returned by the tool. - `BetaManagedAgentsTextBlock` Regular text content. - `text: string` The text content. - `type: "text"` - `"text"` - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` Union type for image source variants. - `BetaManagedAgentsBase64ImageSource` Base64-encoded image data. - `data: string` Base64-encoded image data. - `media_type: string` MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). - `type: "base64"` - `"base64"` - `BetaManagedAgentsURLImageSource` Image referenced by URL. - `type: "url"` - `"url"` - `url: string` URL of the image to fetch. - `BetaManagedAgentsFileImageSource` Image referenced by file ID. - `file_id: string` ID of a previously uploaded file. - `type: "file"` - `"file"` - `type: "image"` - `"image"` - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` Union type for document source variants. - `BetaManagedAgentsBase64DocumentSource` Base64-encoded document data. - `data: string` Base64-encoded document data. - `media_type: string` MIME type of the document (e.g., "application/pdf"). - `type: "base64"` - `"base64"` - `BetaManagedAgentsPlainTextDocumentSource` Plain text document content. - `data: string` The plain text content. - `media_type: "text/plain"` MIME type of the text content. Must be "text/plain". - `"text/plain"` - `type: "text"` - `"text"` - `BetaManagedAgentsURLDocumentSource` Document referenced by URL. - `type: "url"` - `"url"` - `url: string` URL of the document to fetch. - `BetaManagedAgentsFileDocumentSource` Document referenced by file ID. - `file_id: string` ID of a previously uploaded file. - `type: "file"` - `"file"` - `type: "document"` - `"document"` - `context?: string | null` Additional context about the document for the model. - `title?: string | null` The title of the document. - `BetaManagedAgentsSearchResultBlock` A block containing a web search result. - `citations: BetaManagedAgentsSearchResultCitations` Citation settings for a search result. - `enabled: boolean` Whether citations are enabled for this search result. - `content: Array` Array of text content blocks from the search result. - `text: string` The text content. - `type: "text"` - `"text"` - `source: string` The URL source of the search result. - `title: string` The title of the search result. - `type: "search_result"` - `"search_result"` - `is_error?: boolean | null` Whether the tool execution resulted in an error. - `processed_at?: string | null` A timestamp in RFC 3339 format - `session_thread_id?: string | null` Routes this result to a subagent thread. Copy from the `agent.tool_use` event's `session_thread_id`. # Events ## List Events `client.beta.sessions.events.list(stringsessionID, EventListParamsparams?, RequestOptionsoptions?): PageCursor` **get** `/v1/sessions/{session_id}/events` List Events ### Parameters - `sessionID: string` - `params: EventListParams` - `"created_at[gt]"?: string` Query param: Return events created after this time (exclusive). - `"created_at[gte]"?: string` Query param: Return events created at or after this time (inclusive). - `"created_at[lt]"?: string` Query param: Return events created before this time (exclusive). - `"created_at[lte]"?: string` Query param: Return events created at or before this time (inclusive). - `limit?: number` Query param: Query parameter for limit - `order?: "asc" | "desc"` Query param: Sort direction for results, ordered by created_at. Defaults to asc (chronological). - `"asc"` - `"desc"` - `page?: string` Query param: Opaque pagination cursor from a previous response's next_page. - `types?: Array` Query param: Filter by event type. Values match the `type` field on returned events (for example, `user.message` or `agent.tool_use`). Omit to return all event types. - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaManagedAgentsSessionEvent = BetaManagedAgentsUserMessageEvent | BetaManagedAgentsUserInterruptEvent | BetaManagedAgentsUserToolConfirmationEvent | 30 more` Union type for all event types in a session. - `BetaManagedAgentsUserMessageEvent` A user message event in the session conversation. - `id: string` Unique identifier for this event. - `content: Array` Array of content blocks comprising the user message. - `BetaManagedAgentsTextBlock` Regular text content. - `text: string` The text content. - `type: "text"` - `"text"` - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` Union type for image source variants. - `BetaManagedAgentsBase64ImageSource` Base64-encoded image data. - `data: string` Base64-encoded image data. - `media_type: string` MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). - `type: "base64"` - `"base64"` - `BetaManagedAgentsURLImageSource` Image referenced by URL. - `type: "url"` - `"url"` - `url: string` URL of the image to fetch. - `BetaManagedAgentsFileImageSource` Image referenced by file ID. - `file_id: string` ID of a previously uploaded file. - `type: "file"` - `"file"` - `type: "image"` - `"image"` - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` Union type for document source variants. - `BetaManagedAgentsBase64DocumentSource` Base64-encoded document data. - `data: string` Base64-encoded document data. - `media_type: string` MIME type of the document (e.g., "application/pdf"). - `type: "base64"` - `"base64"` - `BetaManagedAgentsPlainTextDocumentSource` Plain text document content. - `data: string` The plain text content. - `media_type: "text/plain"` MIME type of the text content. Must be "text/plain". - `"text/plain"` - `type: "text"` - `"text"` - `BetaManagedAgentsURLDocumentSource` Document referenced by URL. - `type: "url"` - `"url"` - `url: string` URL of the document to fetch. - `BetaManagedAgentsFileDocumentSource` Document referenced by file ID. - `file_id: string` ID of a previously uploaded file. - `type: "file"` - `"file"` - `type: "document"` - `"document"` - `context?: string | null` Additional context about the document for the model. - `title?: string | null` The title of the document. - `type: "user.message"` - `"user.message"` - `processed_at?: string | null` A timestamp in RFC 3339 format - `BetaManagedAgentsUserInterruptEvent` An interrupt event that pauses agent execution and returns control to the user. - `id: string` Unique identifier for this event. - `type: "user.interrupt"` - `"user.interrupt"` - `processed_at?: string | null` A timestamp in RFC 3339 format - `session_thread_id?: string | null` If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread. - `BetaManagedAgentsUserToolConfirmationEvent` A tool confirmation event that approves or denies a pending tool execution. - `id: string` Unique identifier for this event. - `result: "allow" | "deny"` UserToolConfirmationResult enum - `"allow"` - `"deny"` - `tool_use_id: string` The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `type: "user.tool_confirmation"` - `"user.tool_confirmation"` - `deny_message?: string | null` Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. - `processed_at?: string | null` A timestamp in RFC 3339 format - `session_thread_id?: string | null` When set, the confirmation routes to this subagent's thread rather than the primary. Echo this from the `session_thread_id` on the `agent.tool_use` or `agent.mcp_tool_use` event that prompted the approval. - `BetaManagedAgentsUserCustomToolResultEvent` Event sent by the client providing the result of a custom tool execution. - `id: string` Unique identifier for this event. - `custom_tool_use_id: string` The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `type: "user.custom_tool_result"` - `"user.custom_tool_result"` - `content?: Array` The result content returned by the tool. - `BetaManagedAgentsTextBlock` Regular text content. - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `BetaManagedAgentsSearchResultBlock` A block containing a web search result. - `citations: BetaManagedAgentsSearchResultCitations` Citation settings for a search result. - `enabled: boolean` Whether citations are enabled for this search result. - `content: Array` Array of text content blocks from the search result. - `text: string` The text content. - `type: "text"` - `"text"` - `source: string` The URL source of the search result. - `title: string` The title of the search result. - `type: "search_result"` - `"search_result"` - `is_error?: boolean | null` Whether the tool execution resulted in an error. - `processed_at?: string | null` A timestamp in RFC 3339 format - `session_thread_id?: string | null` Routes this result to a subagent thread. Copy from the `agent.custom_tool_use` event's `session_thread_id`. - `BetaManagedAgentsAgentCustomToolUseEvent` Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. - `id: string` Unique identifier for this event. - `input: Record` Input parameters for the tool call. - `name: string` Name of the custom tool being called. - `processed_at: string` A timestamp in RFC 3339 format - `type: "agent.custom_tool_use"` - `"agent.custom_tool_use"` - `session_thread_id?: string | null` When set, this event was cross-posted from a subagent's thread to surface its custom tool use on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.custom_tool_result` event to route the result back. - `BetaManagedAgentsAgentMessageEvent` An agent response event in the session conversation. - `id: string` Unique identifier for this event. - `content: Array` Array of text blocks comprising the agent response. - `text: string` The text content. - `type: "text"` - `processed_at: string` A timestamp in RFC 3339 format - `type: "agent.message"` - `"agent.message"` - `BetaManagedAgentsAgentThinkingEvent` Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `type: "agent.thinking"` - `"agent.thinking"` - `BetaManagedAgentsAgentMCPToolUseEvent` Event emitted when the agent invokes a tool provided by an MCP server. - `id: string` Unique identifier for this event. - `input: Record` Input parameters for the tool call. - `mcp_server_name: string` Name of the MCP server providing the tool. - `name: string` Name of the MCP tool being used. - `processed_at: string` A timestamp in RFC 3339 format - `type: "agent.mcp_tool_use"` - `"agent.mcp_tool_use"` - `evaluated_permission?: "allow" | "ask" | "deny"` AgentEvaluatedPermission enum - `"allow"` - `"ask"` - `"deny"` - `session_thread_id?: string | null` When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.tool_confirmation` event to route the approval back. - `BetaManagedAgentsAgentMCPToolResultEvent` Event representing the result of an MCP tool execution. - `id: string` Unique identifier for this event. - `mcp_tool_use_id: string` The id of the `agent.mcp_tool_use` event this result corresponds to. - `processed_at: string` A timestamp in RFC 3339 format - `type: "agent.mcp_tool_result"` - `"agent.mcp_tool_result"` - `content?: Array` The result content returned by the tool. - `BetaManagedAgentsTextBlock` Regular text content. - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `BetaManagedAgentsSearchResultBlock` A block containing a web search result. - `is_error?: boolean | null` Whether the tool execution resulted in an error. - `BetaManagedAgentsAgentToolUseEvent` Event emitted when the agent invokes a built-in agent tool. - `id: string` Unique identifier for this event. - `input: Record` Input parameters for the tool call. - `name: string` Name of the agent tool being used. - `processed_at: string` A timestamp in RFC 3339 format - `type: "agent.tool_use"` - `"agent.tool_use"` - `evaluated_permission?: "allow" | "ask" | "deny"` AgentEvaluatedPermission enum - `"allow"` - `"ask"` - `"deny"` - `session_thread_id?: string | null` When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.tool_confirmation` event to route the approval back. - `BetaManagedAgentsAgentToolResultEvent` Event representing the result of an agent tool execution. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `tool_use_id: string` The id of the `agent.tool_use` event this result corresponds to. - `type: "agent.tool_result"` - `"agent.tool_result"` - `content?: Array` The result content returned by the tool. - `BetaManagedAgentsTextBlock` Regular text content. - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `BetaManagedAgentsSearchResultBlock` A block containing a web search result. - `is_error?: boolean | null` Whether the tool execution resulted in an error. - `BetaManagedAgentsAgentThreadMessageReceivedEvent` Delivery event written to the target thread's input stream when an agent-to-agent message arrives. - `id: string` Unique identifier for this event. - `content: Array` Message content blocks. - `BetaManagedAgentsTextBlock` Regular text content. - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `from_session_thread_id: string` Public `sthr_` ID of the thread that sent the message. - `processed_at: string` A timestamp in RFC 3339 format - `type: "agent.thread_message_received"` - `"agent.thread_message_received"` - `from_agent_name?: string | null` Name of the callable agent this message came from. Absent when received from the primary agent. - `BetaManagedAgentsAgentThreadMessageSentEvent` Observability event emitted to the sender's output stream when an agent-to-agent message is sent. - `id: string` Unique identifier for this event. - `content: Array` Message content blocks. - `BetaManagedAgentsTextBlock` Regular text content. - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `processed_at: string` A timestamp in RFC 3339 format - `to_session_thread_id: string` Public `sthr_` ID of the thread the message was sent to. - `type: "agent.thread_message_sent"` - `"agent.thread_message_sent"` - `to_agent_name?: string | null` Name of the callable agent this message was sent to. Absent when sent to the primary agent. - `BetaManagedAgentsAgentThreadContextCompactedEvent` Indicates that context compaction (summarization) occurred during the session. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `type: "agent.thread_context_compacted"` - `"agent.thread_context_compacted"` - `BetaManagedAgentsSessionErrorEvent` An error event indicating a problem occurred during session execution. - `id: string` Unique identifier for this event. - `error: BetaManagedAgentsUnknownError | BetaManagedAgentsModelOverloadedError | BetaManagedAgentsModelRateLimitedError | 4 more` An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. - `BetaManagedAgentsUnknownError` An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` What the client should do next in response to this error. - `BetaManagedAgentsRetryStatusRetrying` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `type: "retrying"` - `"retrying"` - `BetaManagedAgentsRetryStatusExhausted` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `type: "exhausted"` - `"exhausted"` - `BetaManagedAgentsRetryStatusTerminal` The session encountered a terminal error and will transition to `terminated` state. - `type: "terminal"` - `"terminal"` - `type: "unknown_error"` - `"unknown_error"` - `BetaManagedAgentsModelOverloadedError` The model is currently overloaded. Emitted after automatic retries are exhausted. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` What the client should do next in response to this error. - `BetaManagedAgentsRetryStatusRetrying` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal` The session encountered a terminal error and will transition to `terminated` state. - `type: "model_overloaded_error"` - `"model_overloaded_error"` - `BetaManagedAgentsModelRateLimitedError` The model request was rate-limited. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` What the client should do next in response to this error. - `BetaManagedAgentsRetryStatusRetrying` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal` The session encountered a terminal error and will transition to `terminated` state. - `type: "model_rate_limited_error"` - `"model_rate_limited_error"` - `BetaManagedAgentsModelRequestFailedError` A model request failed for a reason other than overload or rate-limiting. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` What the client should do next in response to this error. - `BetaManagedAgentsRetryStatusRetrying` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal` The session encountered a terminal error and will transition to `terminated` state. - `type: "model_request_failed_error"` - `"model_request_failed_error"` - `BetaManagedAgentsMCPConnectionFailedError` Failed to connect to an MCP server. - `mcp_server_name: string` Name of the MCP server that failed to connect. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` What the client should do next in response to this error. - `BetaManagedAgentsRetryStatusRetrying` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal` The session encountered a terminal error and will transition to `terminated` state. - `type: "mcp_connection_failed_error"` - `"mcp_connection_failed_error"` - `BetaManagedAgentsMCPAuthenticationFailedError` Authentication to an MCP server failed. - `mcp_server_name: string` Name of the MCP server that failed authentication. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` What the client should do next in response to this error. - `BetaManagedAgentsRetryStatusRetrying` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal` The session encountered a terminal error and will transition to `terminated` state. - `type: "mcp_authentication_failed_error"` - `"mcp_authentication_failed_error"` - `BetaManagedAgentsBillingError` The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` What the client should do next in response to this error. - `BetaManagedAgentsRetryStatusRetrying` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal` The session encountered a terminal error and will transition to `terminated` state. - `type: "billing_error"` - `"billing_error"` - `processed_at: string` A timestamp in RFC 3339 format - `type: "session.error"` - `"session.error"` - `BetaManagedAgentsSessionStatusRescheduledEvent` Indicates the session is recovering from an error state and is rescheduled for execution. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `type: "session.status_rescheduled"` - `"session.status_rescheduled"` - `BetaManagedAgentsSessionStatusRunningEvent` Indicates the session is actively running and the agent is working. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `type: "session.status_running"` - `"session.status_running"` - `BetaManagedAgentsSessionStatusIdleEvent` Indicates the agent has paused and is awaiting user input. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `stop_reason: BetaManagedAgentsSessionEndTurn | BetaManagedAgentsSessionRequiresAction | BetaManagedAgentsSessionRetriesExhausted` The agent completed its turn naturally and is ready for the next user message. - `BetaManagedAgentsSessionEndTurn` The agent completed its turn naturally and is ready for the next user message. - `type: "end_turn"` - `"end_turn"` - `BetaManagedAgentsSessionRequiresAction` The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. - `event_ids: Array` The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. - `type: "requires_action"` - `"requires_action"` - `BetaManagedAgentsSessionRetriesExhausted` The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). - `type: "retries_exhausted"` - `"retries_exhausted"` - `type: "session.status_idle"` - `"session.status_idle"` - `BetaManagedAgentsSessionStatusTerminatedEvent` Indicates the session has terminated, either due to an error or completion. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `type: "session.status_terminated"` - `"session.status_terminated"` - `BetaManagedAgentsSessionThreadCreatedEvent` Emitted when a subagent is spawned as a new thread. Written to the parent thread's output stream so clients observing the session see child creation. - `id: string` Unique identifier for this event. - `agent_name: string` Name of the callable agent the thread runs. - `processed_at: string` A timestamp in RFC 3339 format - `session_thread_id: string` Public `sthr_` ID of the newly created thread. - `type: "session.thread_created"` - `"session.thread_created"` - `BetaManagedAgentsSpanOutcomeEvaluationStartEvent` Emitted when an outcome evaluation cycle begins. - `id: string` Unique identifier for this event. - `iteration: number` 0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc. - `outcome_id: string` The `outc_` ID of the outcome being evaluated. - `processed_at: string` A timestamp in RFC 3339 format - `type: "span.outcome_evaluation_start"` - `"span.outcome_evaluation_start"` - `BetaManagedAgentsSpanOutcomeEvaluationEndEvent` Emitted when an outcome evaluation cycle completes. Carries the verdict and aggregate token usage. A verdict of `needs_revision` means another evaluation cycle follows; `satisfied`, `max_iterations_reached`, `failed`, or `interrupted` are terminal — no further evaluation cycles follow. - `id: string` Unique identifier for this event. - `explanation: string` Human-readable explanation of the verdict. For `needs_revision`, describes which criteria failed and why. - `iteration: number` 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`. - `outcome_evaluation_start_id: string` The id of the corresponding `span.outcome_evaluation_start` event. - `outcome_id: string` The `outc_` ID of the outcome being evaluated. - `processed_at: string` A timestamp in RFC 3339 format - `result: string` Evaluation verdict. 'satisfied': criteria met, session goes idle. 'needs_revision': criteria not met, another revision cycle follows. 'max_iterations_reached': evaluation budget exhausted with criteria still unmet — one final acknowledgment turn follows before the session goes idle, but no further evaluation runs. 'failed': grader determined the rubric does not apply to the deliverables. 'interrupted': user sent an interrupt while evaluation was in progress. - `type: "span.outcome_evaluation_end"` - `"span.outcome_evaluation_end"` - `usage: BetaManagedAgentsSpanModelUsage` Token usage for a single model request. - `cache_creation_input_tokens: number` Tokens used to create prompt cache in this request. - `cache_read_input_tokens: number` Tokens read from prompt cache in this request. - `input_tokens: number` Input tokens consumed by this request. - `output_tokens: number` Output tokens generated by this request. - `speed?: "standard" | "fast" | null` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `BetaManagedAgentsSpanModelRequestStartEvent` Emitted when a model request is initiated by the agent. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `type: "span.model_request_start"` - `"span.model_request_start"` - `BetaManagedAgentsSpanModelRequestEndEvent` Emitted when a model request completes. - `id: string` Unique identifier for this event. - `is_error: boolean | null` Whether the model request resulted in an error. - `model_request_start_id: string` The id of the corresponding `span.model_request_start` event. - `model_usage: BetaManagedAgentsSpanModelUsage` Token usage for a single model request. - `processed_at: string` A timestamp in RFC 3339 format - `type: "span.model_request_end"` - `"span.model_request_end"` - `BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent` Periodic heartbeat emitted while an outcome evaluation cycle is in progress. Distinguishes 'evaluation is actively running' from 'evaluation is stuck' between the corresponding `span.outcome_evaluation_start` and `span.outcome_evaluation_end` events. - `id: string` Unique identifier for this event. - `iteration: number` 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`. - `outcome_id: string` The `outc_` ID of the outcome being evaluated. - `processed_at: string` A timestamp in RFC 3339 format - `type: "span.outcome_evaluation_ongoing"` - `"span.outcome_evaluation_ongoing"` - `BetaManagedAgentsUserDefineOutcomeEvent` Echo of a `user.define_outcome` input event. Carries the server-generated `outcome_id` that subsequent `span.outcome_evaluation_*` events reference. - `id: string` Unique identifier for this event. - `description: string` What the agent should produce. Copied from the input event. - `max_iterations: number | null` Evaluate-then-revise cycles before giving up. Default 3, max 20. - `outcome_id: string` Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list. - `processed_at: string` A timestamp in RFC 3339 format - `rubric: BetaManagedAgentsFileRubric | BetaManagedAgentsTextRubric` Rubric for grading the quality of an outcome. - `BetaManagedAgentsFileRubric` Rubric referenced by a file uploaded via the Files API. - `file_id: string` ID of the rubric file. - `type: "file"` - `"file"` - `BetaManagedAgentsTextRubric` Rubric content provided inline as text. - `content: string` Rubric content. Plain text or markdown — the grader treats it as freeform text. - `type: "text"` - `"text"` - `type: "user.define_outcome"` - `"user.define_outcome"` - `BetaManagedAgentsSessionDeletedEvent` Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `type: "session.deleted"` - `"session.deleted"` - `BetaManagedAgentsSessionThreadStatusRunningEvent` A session thread has begun executing. Emitted on the thread's own stream and cross-posted to the primary stream for child threads. - `id: string` Unique identifier for this event. - `agent_name: string` Name of the agent the thread runs. - `processed_at: string` A timestamp in RFC 3339 format - `session_thread_id: string` Public sthr_ ID of the thread that started running. - `type: "session.thread_status_running"` - `"session.thread_status_running"` - `BetaManagedAgentsSessionThreadStatusIdleEvent` A session thread has yielded and is awaiting input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads. - `id: string` Unique identifier for this event. - `agent_name: string` Name of the agent the thread runs. - `processed_at: string` A timestamp in RFC 3339 format - `session_thread_id: string` Public sthr_ ID of the thread that went idle. - `stop_reason: BetaManagedAgentsSessionEndTurn | BetaManagedAgentsSessionRequiresAction | BetaManagedAgentsSessionRetriesExhausted` The agent completed its turn naturally and is ready for the next user message. - `BetaManagedAgentsSessionEndTurn` The agent completed its turn naturally and is ready for the next user message. - `BetaManagedAgentsSessionRequiresAction` The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. - `BetaManagedAgentsSessionRetriesExhausted` The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). - `type: "session.thread_status_idle"` - `"session.thread_status_idle"` - `BetaManagedAgentsSessionThreadStatusTerminatedEvent` A session thread has terminated and will accept no further input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads. - `id: string` Unique identifier for this event. - `agent_name: string` Name of the agent the thread runs. - `processed_at: string` A timestamp in RFC 3339 format - `session_thread_id: string` Public sthr_ ID of the thread that terminated. - `type: "session.thread_status_terminated"` - `"session.thread_status_terminated"` - `BetaManagedAgentsUserToolResultEvent` Event sent by the client providing the result of an agent-toolset tool execution. Only valid on `self_hosted` environments, where sandbox-routed tools are executed by the client rather than the server. - `id: string` Unique identifier for this event. - `tool_use_id: string` The id of the `agent.tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `type: "user.tool_result"` - `"user.tool_result"` - `content?: Array` The result content returned by the tool. - `BetaManagedAgentsTextBlock` Regular text content. - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `BetaManagedAgentsSearchResultBlock` A block containing a web search result. - `is_error?: boolean | null` Whether the tool execution resulted in an error. - `processed_at?: string | null` A timestamp in RFC 3339 format - `session_thread_id?: string | null` Routes this result to a subagent thread. Copy from the `agent.tool_use` event's `session_thread_id`. - `BetaManagedAgentsSessionThreadStatusRescheduledEvent` A session thread hit a transient error and is retrying automatically. Emitted on the thread's own stream and cross-posted to the primary stream for child threads. - `id: string` Unique identifier for this event. - `agent_name: string` Name of the agent the thread runs. - `processed_at: string` A timestamp in RFC 3339 format - `session_thread_id: string` Public sthr_ ID of the thread that is retrying. - `type: "session.thread_status_rescheduled"` - `"session.thread_status_rescheduled"` - `BetaManagedAgentsSessionUpdatedEvent` Emitted when an UpdateSession request changed at least one field. Carries only the fields that changed; absent fields were not part of the update. The new configuration applies from the next turn. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `type: "session.updated"` - `"session.updated"` - `agent?: BetaManagedAgentsSessionAgent | null` Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. - `id: string` - `description: string | null` - `mcp_servers: Array` - `name: string` - `type: "url"` - `"url"` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `id: BetaManagedAgentsModel` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-opus-4-8" | "claude-opus-4-7" | "claude-opus-4-6" | 7 more` - `"claude-opus-4-8"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-7"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-6"` Most intelligent model for building agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` Fastest model with near-frontier intelligence - `"claude-haiku-4-5-20251001"` Fastest model with near-frontier intelligence - `"claude-opus-4-5"` Premium model combining maximum intelligence with practical performance - `"claude-opus-4-5-20251101"` Premium model combining maximum intelligence with practical performance - `"claude-sonnet-4-5"` High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` High-performance model for agents and coding - `(string & {})` - `speed?: "standard" | "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `multiagent: BetaManagedAgentsSessionMultiagentCoordinator | null` Resolved coordinator topology with full agent definitions for each roster member. - `agents: Array` Full `agent` definitions the coordinator may spawn as session threads. - `id: string` - `description: string | null` - `mcp_servers: Array` - `name: string` - `type: "url"` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `name: string` - `skills: Array` - `BetaManagedAgentsAnthropicSkill` A resolved Anthropic-managed skill. - `skill_id: string` - `type: "anthropic"` - `"anthropic"` - `version: string` - `BetaManagedAgentsCustomSkill` A resolved user-created custom skill. - `skill_id: string` - `type: "custom"` - `"custom"` - `version: string` - `system: string | null` - `tools: Array` - `BetaManagedAgentsAgentToolset20260401` - `configs: Array` - `enabled: boolean` - `name: "bash" | "edit" | "read" | 5 more` Built-in agent tool identifier. - `"bash"` - `"edit"` - `"read"` - `"write"` - `"glob"` - `"grep"` - `"web_fetch"` - `"web_search"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `"always_allow"` - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "always_ask"` - `"always_ask"` - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` Resolved default configuration for agent tools. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "agent_toolset_20260401"` - `"agent_toolset_20260401"` - `BetaManagedAgentsMCPToolset` - `configs: Array` - `enabled: boolean` - `name: string` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` Resolved default configuration for all tools from an MCP server. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `mcp_server_name: string` - `type: "mcp_toolset"` - `"mcp_toolset"` - `BetaManagedAgentsCustomTool` A custom tool as returned in API responses. - `description: string` - `input_schema: BetaManagedAgentsCustomToolInputSchema` JSON Schema for custom tool input parameters. - `properties?: Record | null` JSON Schema properties defining the tool's input parameters. - `required?: Array` List of required property names. - `type?: "object"` Must be 'object' for tool input schemas. - `"object"` - `name: string` - `type: "custom"` - `"custom"` - `type: "agent"` - `"agent"` - `version: number` - `type: "coordinator"` - `"coordinator"` - `name: string` - `skills: Array` - `BetaManagedAgentsAnthropicSkill` A resolved Anthropic-managed skill. - `BetaManagedAgentsCustomSkill` A resolved user-created custom skill. - `system: string | null` - `tools: Array` - `BetaManagedAgentsAgentToolset20260401` - `BetaManagedAgentsMCPToolset` - `BetaManagedAgentsCustomTool` A custom tool as returned in API responses. - `type: "agent"` - `"agent"` - `version: number` - `metadata?: Record` The session's full metadata bag after the update. Present when the update set non-empty metadata; absent when metadata was unchanged or cleared to empty. - `title?: string | null` The session's new title. Present only when the update changed it. ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); // Automatically fetches more pages as needed. for await (const betaManagedAgentsSessionEvent of client.beta.sessions.events.list( 'sesn_011CZkZAtmR3yMPDzynEDxu7', )) { console.log(betaManagedAgentsSessionEvent); } ``` #### Response ```json { "data": [ { "id": "sevt_011CZkZGOp0iBcp4kaQSihUmy", "content": [ { "text": "Where is my order #1234?", "type": "text" } ], "type": "user.message", "processed_at": "2026-03-15T10:00:00Z" }, { "id": "sevt_011CZkZHPq1jCdq5lbRTjiVnz", "content": [ { "text": "Let me look up order #1234 for you.", "type": "text" } ], "processed_at": "2026-03-15T10:00:00Z", "type": "agent.message" } ], "next_page": "page_MjAyNS0wNS0xNFQwMDowMDowMFo=" } ``` ## Send Events `client.beta.sessions.events.send(stringsessionID, EventSendParamsparams, RequestOptionsoptions?): BetaManagedAgentsSendSessionEvents` **post** `/v1/sessions/{session_id}/events` Send Events ### Parameters - `sessionID: string` - `params: EventSendParams` - `events: Array` Body param: Events to send to the `session`. - `BetaManagedAgentsUserMessageEventParams` Parameters for sending a user message to the session. - `content: Array` Array of content blocks for the user message. - `BetaManagedAgentsTextBlock` Regular text content. - `text: string` The text content. - `type: "text"` - `"text"` - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` Union type for image source variants. - `BetaManagedAgentsBase64ImageSource` Base64-encoded image data. - `data: string` Base64-encoded image data. - `media_type: string` MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). - `type: "base64"` - `"base64"` - `BetaManagedAgentsURLImageSource` Image referenced by URL. - `type: "url"` - `"url"` - `url: string` URL of the image to fetch. - `BetaManagedAgentsFileImageSource` Image referenced by file ID. - `file_id: string` ID of a previously uploaded file. - `type: "file"` - `"file"` - `type: "image"` - `"image"` - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` Union type for document source variants. - `BetaManagedAgentsBase64DocumentSource` Base64-encoded document data. - `data: string` Base64-encoded document data. - `media_type: string` MIME type of the document (e.g., "application/pdf"). - `type: "base64"` - `"base64"` - `BetaManagedAgentsPlainTextDocumentSource` Plain text document content. - `data: string` The plain text content. - `media_type: "text/plain"` MIME type of the text content. Must be "text/plain". - `"text/plain"` - `type: "text"` - `"text"` - `BetaManagedAgentsURLDocumentSource` Document referenced by URL. - `type: "url"` - `"url"` - `url: string` URL of the document to fetch. - `BetaManagedAgentsFileDocumentSource` Document referenced by file ID. - `file_id: string` ID of a previously uploaded file. - `type: "file"` - `"file"` - `type: "document"` - `"document"` - `context?: string | null` Additional context about the document for the model. - `title?: string | null` The title of the document. - `type: "user.message"` - `"user.message"` - `BetaManagedAgentsUserInterruptEventParams` Parameters for sending an interrupt to pause the agent. - `type: "user.interrupt"` - `"user.interrupt"` - `session_thread_id?: string | null` If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread. - `BetaManagedAgentsUserToolConfirmationEventParams` Parameters for confirming or denying a tool execution request. - `result: "allow" | "deny"` UserToolConfirmationResult enum - `"allow"` - `"deny"` - `tool_use_id: string` The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `type: "user.tool_confirmation"` - `"user.tool_confirmation"` - `deny_message?: string | null` Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. - `BetaManagedAgentsUserCustomToolResultEventParams` Parameters for providing the result of a custom tool execution. - `custom_tool_use_id: string` The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `type: "user.custom_tool_result"` - `"user.custom_tool_result"` - `content?: Array` The result content returned by the tool. - `BetaManagedAgentsTextBlock` Regular text content. - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `BetaManagedAgentsSearchResultBlock` A block containing a web search result. - `citations: BetaManagedAgentsSearchResultCitations` Citation settings for a search result. - `enabled: boolean` Whether citations are enabled for this search result. - `content: Array` Array of text content blocks from the search result. - `text: string` The text content. - `type: "text"` - `"text"` - `source: string` The URL source of the search result. - `title: string` The title of the search result. - `type: "search_result"` - `"search_result"` - `is_error?: boolean | null` Whether the tool execution resulted in an error. - `BetaManagedAgentsUserDefineOutcomeEventParams` Parameters for defining an outcome the agent should work toward. The agent begins work on receipt. - `description: string` What the agent should produce. This is the task specification. - `rubric: BetaManagedAgentsFileRubricParams | BetaManagedAgentsTextRubricParams` Rubric for grading the quality of an outcome. - `BetaManagedAgentsFileRubricParams` Rubric referenced by a file uploaded via the Files API. - `file_id: string` ID of the rubric file. - `type: "file"` - `"file"` - `BetaManagedAgentsTextRubricParams` Rubric content provided inline as text. - `content: string` Rubric content. Plain text or markdown — the grader treats it as freeform text. Maximum 262144 characters. - `type: "text"` - `"text"` - `type: "user.define_outcome"` - `"user.define_outcome"` - `max_iterations?: number | null` Eval→revision cycles before giving up. Default 3, max 20. - `BetaManagedAgentsUserToolResultEventParams` Parameters for providing the result of an agent-toolset tool execution. Only valid on `self_hosted` environments, where sandbox-routed tools are executed by the client rather than the server. - `tool_use_id: string` The id of the `agent.tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `type: "user.tool_result"` - `"user.tool_result"` - `content?: Array` The result content returned by the tool. - `BetaManagedAgentsTextBlock` Regular text content. - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `BetaManagedAgentsSearchResultBlock` A block containing a web search result. - `is_error?: boolean | null` Whether the tool execution resulted in an error. - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaManagedAgentsSendSessionEvents` Events that were successfully sent to the session. - `data?: Array` Sent events - `BetaManagedAgentsUserMessageEvent` A user message event in the session conversation. - `id: string` Unique identifier for this event. - `content: Array` Array of content blocks comprising the user message. - `BetaManagedAgentsTextBlock` Regular text content. - `text: string` The text content. - `type: "text"` - `"text"` - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` Union type for image source variants. - `BetaManagedAgentsBase64ImageSource` Base64-encoded image data. - `data: string` Base64-encoded image data. - `media_type: string` MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). - `type: "base64"` - `"base64"` - `BetaManagedAgentsURLImageSource` Image referenced by URL. - `type: "url"` - `"url"` - `url: string` URL of the image to fetch. - `BetaManagedAgentsFileImageSource` Image referenced by file ID. - `file_id: string` ID of a previously uploaded file. - `type: "file"` - `"file"` - `type: "image"` - `"image"` - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` Union type for document source variants. - `BetaManagedAgentsBase64DocumentSource` Base64-encoded document data. - `data: string` Base64-encoded document data. - `media_type: string` MIME type of the document (e.g., "application/pdf"). - `type: "base64"` - `"base64"` - `BetaManagedAgentsPlainTextDocumentSource` Plain text document content. - `data: string` The plain text content. - `media_type: "text/plain"` MIME type of the text content. Must be "text/plain". - `"text/plain"` - `type: "text"` - `"text"` - `BetaManagedAgentsURLDocumentSource` Document referenced by URL. - `type: "url"` - `"url"` - `url: string` URL of the document to fetch. - `BetaManagedAgentsFileDocumentSource` Document referenced by file ID. - `file_id: string` ID of a previously uploaded file. - `type: "file"` - `"file"` - `type: "document"` - `"document"` - `context?: string | null` Additional context about the document for the model. - `title?: string | null` The title of the document. - `type: "user.message"` - `"user.message"` - `processed_at?: string | null` A timestamp in RFC 3339 format - `BetaManagedAgentsUserInterruptEvent` An interrupt event that pauses agent execution and returns control to the user. - `id: string` Unique identifier for this event. - `type: "user.interrupt"` - `"user.interrupt"` - `processed_at?: string | null` A timestamp in RFC 3339 format - `session_thread_id?: string | null` If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread. - `BetaManagedAgentsUserToolConfirmationEvent` A tool confirmation event that approves or denies a pending tool execution. - `id: string` Unique identifier for this event. - `result: "allow" | "deny"` UserToolConfirmationResult enum - `"allow"` - `"deny"` - `tool_use_id: string` The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `type: "user.tool_confirmation"` - `"user.tool_confirmation"` - `deny_message?: string | null` Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. - `processed_at?: string | null` A timestamp in RFC 3339 format - `session_thread_id?: string | null` When set, the confirmation routes to this subagent's thread rather than the primary. Echo this from the `session_thread_id` on the `agent.tool_use` or `agent.mcp_tool_use` event that prompted the approval. - `BetaManagedAgentsUserCustomToolResultEvent` Event sent by the client providing the result of a custom tool execution. - `id: string` Unique identifier for this event. - `custom_tool_use_id: string` The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `type: "user.custom_tool_result"` - `"user.custom_tool_result"` - `content?: Array` The result content returned by the tool. - `BetaManagedAgentsTextBlock` Regular text content. - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `BetaManagedAgentsSearchResultBlock` A block containing a web search result. - `citations: BetaManagedAgentsSearchResultCitations` Citation settings for a search result. - `enabled: boolean` Whether citations are enabled for this search result. - `content: Array` Array of text content blocks from the search result. - `text: string` The text content. - `type: "text"` - `"text"` - `source: string` The URL source of the search result. - `title: string` The title of the search result. - `type: "search_result"` - `"search_result"` - `is_error?: boolean | null` Whether the tool execution resulted in an error. - `processed_at?: string | null` A timestamp in RFC 3339 format - `session_thread_id?: string | null` Routes this result to a subagent thread. Copy from the `agent.custom_tool_use` event's `session_thread_id`. - `BetaManagedAgentsUserDefineOutcomeEvent` Echo of a `user.define_outcome` input event. Carries the server-generated `outcome_id` that subsequent `span.outcome_evaluation_*` events reference. - `id: string` Unique identifier for this event. - `description: string` What the agent should produce. Copied from the input event. - `max_iterations: number | null` Evaluate-then-revise cycles before giving up. Default 3, max 20. - `outcome_id: string` Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list. - `processed_at: string` A timestamp in RFC 3339 format - `rubric: BetaManagedAgentsFileRubric | BetaManagedAgentsTextRubric` Rubric for grading the quality of an outcome. - `BetaManagedAgentsFileRubric` Rubric referenced by a file uploaded via the Files API. - `file_id: string` ID of the rubric file. - `type: "file"` - `"file"` - `BetaManagedAgentsTextRubric` Rubric content provided inline as text. - `content: string` Rubric content. Plain text or markdown — the grader treats it as freeform text. - `type: "text"` - `"text"` - `type: "user.define_outcome"` - `"user.define_outcome"` - `BetaManagedAgentsUserToolResultEvent` Event sent by the client providing the result of an agent-toolset tool execution. Only valid on `self_hosted` environments, where sandbox-routed tools are executed by the client rather than the server. - `id: string` Unique identifier for this event. - `tool_use_id: string` The id of the `agent.tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `type: "user.tool_result"` - `"user.tool_result"` - `content?: Array` The result content returned by the tool. - `BetaManagedAgentsTextBlock` Regular text content. - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `BetaManagedAgentsSearchResultBlock` A block containing a web search result. - `is_error?: boolean | null` Whether the tool execution resulted in an error. - `processed_at?: string | null` A timestamp in RFC 3339 format - `session_thread_id?: string | null` Routes this result to a subagent thread. Copy from the `agent.tool_use` event's `session_thread_id`. ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const betaManagedAgentsSendSessionEvents = await client.beta.sessions.events.send( 'sesn_011CZkZAtmR3yMPDzynEDxu7', { events: [ { content: [{ text: 'Where is my order #1234?', type: 'text' }], type: 'user.message' }, ], }, ); console.log(betaManagedAgentsSendSessionEvents.data); ``` #### Response ```json { "data": [ { "id": "sevt_011CZkZGOp0iBcp4kaQSihUmy", "content": [ { "text": "Where is my order #1234?", "type": "text" } ], "type": "user.message", "processed_at": "2026-03-15T10:00:00Z" } ] } ``` ## Stream Events `client.beta.sessions.events.stream(stringsessionID, EventStreamParamsparams?, RequestOptionsoptions?): BetaManagedAgentsStreamSessionEvents | Stream` **get** `/v1/sessions/{session_id}/events/stream` Stream Events ### Parameters - `sessionID: string` - `params: EventStreamParams` - `betas?: Array` Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaManagedAgentsStreamSessionEvents = BetaManagedAgentsUserMessageEvent | BetaManagedAgentsUserInterruptEvent | BetaManagedAgentsUserToolConfirmationEvent | 30 more` Server-sent event in the session stream. - `BetaManagedAgentsUserMessageEvent` A user message event in the session conversation. - `id: string` Unique identifier for this event. - `content: Array` Array of content blocks comprising the user message. - `BetaManagedAgentsTextBlock` Regular text content. - `text: string` The text content. - `type: "text"` - `"text"` - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` Union type for image source variants. - `BetaManagedAgentsBase64ImageSource` Base64-encoded image data. - `data: string` Base64-encoded image data. - `media_type: string` MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). - `type: "base64"` - `"base64"` - `BetaManagedAgentsURLImageSource` Image referenced by URL. - `type: "url"` - `"url"` - `url: string` URL of the image to fetch. - `BetaManagedAgentsFileImageSource` Image referenced by file ID. - `file_id: string` ID of a previously uploaded file. - `type: "file"` - `"file"` - `type: "image"` - `"image"` - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` Union type for document source variants. - `BetaManagedAgentsBase64DocumentSource` Base64-encoded document data. - `data: string` Base64-encoded document data. - `media_type: string` MIME type of the document (e.g., "application/pdf"). - `type: "base64"` - `"base64"` - `BetaManagedAgentsPlainTextDocumentSource` Plain text document content. - `data: string` The plain text content. - `media_type: "text/plain"` MIME type of the text content. Must be "text/plain". - `"text/plain"` - `type: "text"` - `"text"` - `BetaManagedAgentsURLDocumentSource` Document referenced by URL. - `type: "url"` - `"url"` - `url: string` URL of the document to fetch. - `BetaManagedAgentsFileDocumentSource` Document referenced by file ID. - `file_id: string` ID of a previously uploaded file. - `type: "file"` - `"file"` - `type: "document"` - `"document"` - `context?: string | null` Additional context about the document for the model. - `title?: string | null` The title of the document. - `type: "user.message"` - `"user.message"` - `processed_at?: string | null` A timestamp in RFC 3339 format - `BetaManagedAgentsUserInterruptEvent` An interrupt event that pauses agent execution and returns control to the user. - `id: string` Unique identifier for this event. - `type: "user.interrupt"` - `"user.interrupt"` - `processed_at?: string | null` A timestamp in RFC 3339 format - `session_thread_id?: string | null` If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread. - `BetaManagedAgentsUserToolConfirmationEvent` A tool confirmation event that approves or denies a pending tool execution. - `id: string` Unique identifier for this event. - `result: "allow" | "deny"` UserToolConfirmationResult enum - `"allow"` - `"deny"` - `tool_use_id: string` The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `type: "user.tool_confirmation"` - `"user.tool_confirmation"` - `deny_message?: string | null` Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. - `processed_at?: string | null` A timestamp in RFC 3339 format - `session_thread_id?: string | null` When set, the confirmation routes to this subagent's thread rather than the primary. Echo this from the `session_thread_id` on the `agent.tool_use` or `agent.mcp_tool_use` event that prompted the approval. - `BetaManagedAgentsUserCustomToolResultEvent` Event sent by the client providing the result of a custom tool execution. - `id: string` Unique identifier for this event. - `custom_tool_use_id: string` The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `type: "user.custom_tool_result"` - `"user.custom_tool_result"` - `content?: Array` The result content returned by the tool. - `BetaManagedAgentsTextBlock` Regular text content. - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `BetaManagedAgentsSearchResultBlock` A block containing a web search result. - `citations: BetaManagedAgentsSearchResultCitations` Citation settings for a search result. - `enabled: boolean` Whether citations are enabled for this search result. - `content: Array` Array of text content blocks from the search result. - `text: string` The text content. - `type: "text"` - `"text"` - `source: string` The URL source of the search result. - `title: string` The title of the search result. - `type: "search_result"` - `"search_result"` - `is_error?: boolean | null` Whether the tool execution resulted in an error. - `processed_at?: string | null` A timestamp in RFC 3339 format - `session_thread_id?: string | null` Routes this result to a subagent thread. Copy from the `agent.custom_tool_use` event's `session_thread_id`. - `BetaManagedAgentsAgentCustomToolUseEvent` Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. - `id: string` Unique identifier for this event. - `input: Record` Input parameters for the tool call. - `name: string` Name of the custom tool being called. - `processed_at: string` A timestamp in RFC 3339 format - `type: "agent.custom_tool_use"` - `"agent.custom_tool_use"` - `session_thread_id?: string | null` When set, this event was cross-posted from a subagent's thread to surface its custom tool use on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.custom_tool_result` event to route the result back. - `BetaManagedAgentsAgentMessageEvent` An agent response event in the session conversation. - `id: string` Unique identifier for this event. - `content: Array` Array of text blocks comprising the agent response. - `text: string` The text content. - `type: "text"` - `processed_at: string` A timestamp in RFC 3339 format - `type: "agent.message"` - `"agent.message"` - `BetaManagedAgentsAgentThinkingEvent` Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `type: "agent.thinking"` - `"agent.thinking"` - `BetaManagedAgentsAgentMCPToolUseEvent` Event emitted when the agent invokes a tool provided by an MCP server. - `id: string` Unique identifier for this event. - `input: Record` Input parameters for the tool call. - `mcp_server_name: string` Name of the MCP server providing the tool. - `name: string` Name of the MCP tool being used. - `processed_at: string` A timestamp in RFC 3339 format - `type: "agent.mcp_tool_use"` - `"agent.mcp_tool_use"` - `evaluated_permission?: "allow" | "ask" | "deny"` AgentEvaluatedPermission enum - `"allow"` - `"ask"` - `"deny"` - `session_thread_id?: string | null` When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.tool_confirmation` event to route the approval back. - `BetaManagedAgentsAgentMCPToolResultEvent` Event representing the result of an MCP tool execution. - `id: string` Unique identifier for this event. - `mcp_tool_use_id: string` The id of the `agent.mcp_tool_use` event this result corresponds to. - `processed_at: string` A timestamp in RFC 3339 format - `type: "agent.mcp_tool_result"` - `"agent.mcp_tool_result"` - `content?: Array` The result content returned by the tool. - `BetaManagedAgentsTextBlock` Regular text content. - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `BetaManagedAgentsSearchResultBlock` A block containing a web search result. - `is_error?: boolean | null` Whether the tool execution resulted in an error. - `BetaManagedAgentsAgentToolUseEvent` Event emitted when the agent invokes a built-in agent tool. - `id: string` Unique identifier for this event. - `input: Record` Input parameters for the tool call. - `name: string` Name of the agent tool being used. - `processed_at: string` A timestamp in RFC 3339 format - `type: "agent.tool_use"` - `"agent.tool_use"` - `evaluated_permission?: "allow" | "ask" | "deny"` AgentEvaluatedPermission enum - `"allow"` - `"ask"` - `"deny"` - `session_thread_id?: string | null` When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.tool_confirmation` event to route the approval back. - `BetaManagedAgentsAgentToolResultEvent` Event representing the result of an agent tool execution. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `tool_use_id: string` The id of the `agent.tool_use` event this result corresponds to. - `type: "agent.tool_result"` - `"agent.tool_result"` - `content?: Array` The result content returned by the tool. - `BetaManagedAgentsTextBlock` Regular text content. - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `BetaManagedAgentsSearchResultBlock` A block containing a web search result. - `is_error?: boolean | null` Whether the tool execution resulted in an error. - `BetaManagedAgentsAgentThreadMessageReceivedEvent` Delivery event written to the target thread's input stream when an agent-to-agent message arrives. - `id: string` Unique identifier for this event. - `content: Array` Message content blocks. - `BetaManagedAgentsTextBlock` Regular text content. - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `from_session_thread_id: string` Public `sthr_` ID of the thread that sent the message. - `processed_at: string` A timestamp in RFC 3339 format - `type: "agent.thread_message_received"` - `"agent.thread_message_received"` - `from_agent_name?: string | null` Name of the callable agent this message came from. Absent when received from the primary agent. - `BetaManagedAgentsAgentThreadMessageSentEvent` Observability event emitted to the sender's output stream when an agent-to-agent message is sent. - `id: string` Unique identifier for this event. - `content: Array` Message content blocks. - `BetaManagedAgentsTextBlock` Regular text content. - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `processed_at: string` A timestamp in RFC 3339 format - `to_session_thread_id: string` Public `sthr_` ID of the thread the message was sent to. - `type: "agent.thread_message_sent"` - `"agent.thread_message_sent"` - `to_agent_name?: string | null` Name of the callable agent this message was sent to. Absent when sent to the primary agent. - `BetaManagedAgentsAgentThreadContextCompactedEvent` Indicates that context compaction (summarization) occurred during the session. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `type: "agent.thread_context_compacted"` - `"agent.thread_context_compacted"` - `BetaManagedAgentsSessionErrorEvent` An error event indicating a problem occurred during session execution. - `id: string` Unique identifier for this event. - `error: BetaManagedAgentsUnknownError | BetaManagedAgentsModelOverloadedError | BetaManagedAgentsModelRateLimitedError | 4 more` An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. - `BetaManagedAgentsUnknownError` An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` What the client should do next in response to this error. - `BetaManagedAgentsRetryStatusRetrying` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `type: "retrying"` - `"retrying"` - `BetaManagedAgentsRetryStatusExhausted` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `type: "exhausted"` - `"exhausted"` - `BetaManagedAgentsRetryStatusTerminal` The session encountered a terminal error and will transition to `terminated` state. - `type: "terminal"` - `"terminal"` - `type: "unknown_error"` - `"unknown_error"` - `BetaManagedAgentsModelOverloadedError` The model is currently overloaded. Emitted after automatic retries are exhausted. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` What the client should do next in response to this error. - `BetaManagedAgentsRetryStatusRetrying` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal` The session encountered a terminal error and will transition to `terminated` state. - `type: "model_overloaded_error"` - `"model_overloaded_error"` - `BetaManagedAgentsModelRateLimitedError` The model request was rate-limited. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` What the client should do next in response to this error. - `BetaManagedAgentsRetryStatusRetrying` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal` The session encountered a terminal error and will transition to `terminated` state. - `type: "model_rate_limited_error"` - `"model_rate_limited_error"` - `BetaManagedAgentsModelRequestFailedError` A model request failed for a reason other than overload or rate-limiting. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` What the client should do next in response to this error. - `BetaManagedAgentsRetryStatusRetrying` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal` The session encountered a terminal error and will transition to `terminated` state. - `type: "model_request_failed_error"` - `"model_request_failed_error"` - `BetaManagedAgentsMCPConnectionFailedError` Failed to connect to an MCP server. - `mcp_server_name: string` Name of the MCP server that failed to connect. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` What the client should do next in response to this error. - `BetaManagedAgentsRetryStatusRetrying` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal` The session encountered a terminal error and will transition to `terminated` state. - `type: "mcp_connection_failed_error"` - `"mcp_connection_failed_error"` - `BetaManagedAgentsMCPAuthenticationFailedError` Authentication to an MCP server failed. - `mcp_server_name: string` Name of the MCP server that failed authentication. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` What the client should do next in response to this error. - `BetaManagedAgentsRetryStatusRetrying` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal` The session encountered a terminal error and will transition to `terminated` state. - `type: "mcp_authentication_failed_error"` - `"mcp_authentication_failed_error"` - `BetaManagedAgentsBillingError` The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` What the client should do next in response to this error. - `BetaManagedAgentsRetryStatusRetrying` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal` The session encountered a terminal error and will transition to `terminated` state. - `type: "billing_error"` - `"billing_error"` - `processed_at: string` A timestamp in RFC 3339 format - `type: "session.error"` - `"session.error"` - `BetaManagedAgentsSessionStatusRescheduledEvent` Indicates the session is recovering from an error state and is rescheduled for execution. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `type: "session.status_rescheduled"` - `"session.status_rescheduled"` - `BetaManagedAgentsSessionStatusRunningEvent` Indicates the session is actively running and the agent is working. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `type: "session.status_running"` - `"session.status_running"` - `BetaManagedAgentsSessionStatusIdleEvent` Indicates the agent has paused and is awaiting user input. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `stop_reason: BetaManagedAgentsSessionEndTurn | BetaManagedAgentsSessionRequiresAction | BetaManagedAgentsSessionRetriesExhausted` The agent completed its turn naturally and is ready for the next user message. - `BetaManagedAgentsSessionEndTurn` The agent completed its turn naturally and is ready for the next user message. - `type: "end_turn"` - `"end_turn"` - `BetaManagedAgentsSessionRequiresAction` The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. - `event_ids: Array` The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. - `type: "requires_action"` - `"requires_action"` - `BetaManagedAgentsSessionRetriesExhausted` The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). - `type: "retries_exhausted"` - `"retries_exhausted"` - `type: "session.status_idle"` - `"session.status_idle"` - `BetaManagedAgentsSessionStatusTerminatedEvent` Indicates the session has terminated, either due to an error or completion. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `type: "session.status_terminated"` - `"session.status_terminated"` - `BetaManagedAgentsSessionThreadCreatedEvent` Emitted when a subagent is spawned as a new thread. Written to the parent thread's output stream so clients observing the session see child creation. - `id: string` Unique identifier for this event. - `agent_name: string` Name of the callable agent the thread runs. - `processed_at: string` A timestamp in RFC 3339 format - `session_thread_id: string` Public `sthr_` ID of the newly created thread. - `type: "session.thread_created"` - `"session.thread_created"` - `BetaManagedAgentsSpanOutcomeEvaluationStartEvent` Emitted when an outcome evaluation cycle begins. - `id: string` Unique identifier for this event. - `iteration: number` 0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc. - `outcome_id: string` The `outc_` ID of the outcome being evaluated. - `processed_at: string` A timestamp in RFC 3339 format - `type: "span.outcome_evaluation_start"` - `"span.outcome_evaluation_start"` - `BetaManagedAgentsSpanOutcomeEvaluationEndEvent` Emitted when an outcome evaluation cycle completes. Carries the verdict and aggregate token usage. A verdict of `needs_revision` means another evaluation cycle follows; `satisfied`, `max_iterations_reached`, `failed`, or `interrupted` are terminal — no further evaluation cycles follow. - `id: string` Unique identifier for this event. - `explanation: string` Human-readable explanation of the verdict. For `needs_revision`, describes which criteria failed and why. - `iteration: number` 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`. - `outcome_evaluation_start_id: string` The id of the corresponding `span.outcome_evaluation_start` event. - `outcome_id: string` The `outc_` ID of the outcome being evaluated. - `processed_at: string` A timestamp in RFC 3339 format - `result: string` Evaluation verdict. 'satisfied': criteria met, session goes idle. 'needs_revision': criteria not met, another revision cycle follows. 'max_iterations_reached': evaluation budget exhausted with criteria still unmet — one final acknowledgment turn follows before the session goes idle, but no further evaluation runs. 'failed': grader determined the rubric does not apply to the deliverables. 'interrupted': user sent an interrupt while evaluation was in progress. - `type: "span.outcome_evaluation_end"` - `"span.outcome_evaluation_end"` - `usage: BetaManagedAgentsSpanModelUsage` Token usage for a single model request. - `cache_creation_input_tokens: number` Tokens used to create prompt cache in this request. - `cache_read_input_tokens: number` Tokens read from prompt cache in this request. - `input_tokens: number` Input tokens consumed by this request. - `output_tokens: number` Output tokens generated by this request. - `speed?: "standard" | "fast" | null` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `BetaManagedAgentsSpanModelRequestStartEvent` Emitted when a model request is initiated by the agent. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `type: "span.model_request_start"` - `"span.model_request_start"` - `BetaManagedAgentsSpanModelRequestEndEvent` Emitted when a model request completes. - `id: string` Unique identifier for this event. - `is_error: boolean | null` Whether the model request resulted in an error. - `model_request_start_id: string` The id of the corresponding `span.model_request_start` event. - `model_usage: BetaManagedAgentsSpanModelUsage` Token usage for a single model request. - `processed_at: string` A timestamp in RFC 3339 format - `type: "span.model_request_end"` - `"span.model_request_end"` - `BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent` Periodic heartbeat emitted while an outcome evaluation cycle is in progress. Distinguishes 'evaluation is actively running' from 'evaluation is stuck' between the corresponding `span.outcome_evaluation_start` and `span.outcome_evaluation_end` events. - `id: string` Unique identifier for this event. - `iteration: number` 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`. - `outcome_id: string` The `outc_` ID of the outcome being evaluated. - `processed_at: string` A timestamp in RFC 3339 format - `type: "span.outcome_evaluation_ongoing"` - `"span.outcome_evaluation_ongoing"` - `BetaManagedAgentsUserDefineOutcomeEvent` Echo of a `user.define_outcome` input event. Carries the server-generated `outcome_id` that subsequent `span.outcome_evaluation_*` events reference. - `id: string` Unique identifier for this event. - `description: string` What the agent should produce. Copied from the input event. - `max_iterations: number | null` Evaluate-then-revise cycles before giving up. Default 3, max 20. - `outcome_id: string` Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list. - `processed_at: string` A timestamp in RFC 3339 format - `rubric: BetaManagedAgentsFileRubric | BetaManagedAgentsTextRubric` Rubric for grading the quality of an outcome. - `BetaManagedAgentsFileRubric` Rubric referenced by a file uploaded via the Files API. - `file_id: string` ID of the rubric file. - `type: "file"` - `"file"` - `BetaManagedAgentsTextRubric` Rubric content provided inline as text. - `content: string` Rubric content. Plain text or markdown — the grader treats it as freeform text. - `type: "text"` - `"text"` - `type: "user.define_outcome"` - `"user.define_outcome"` - `BetaManagedAgentsSessionDeletedEvent` Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `type: "session.deleted"` - `"session.deleted"` - `BetaManagedAgentsSessionThreadStatusRunningEvent` A session thread has begun executing. Emitted on the thread's own stream and cross-posted to the primary stream for child threads. - `id: string` Unique identifier for this event. - `agent_name: string` Name of the agent the thread runs. - `processed_at: string` A timestamp in RFC 3339 format - `session_thread_id: string` Public sthr_ ID of the thread that started running. - `type: "session.thread_status_running"` - `"session.thread_status_running"` - `BetaManagedAgentsSessionThreadStatusIdleEvent` A session thread has yielded and is awaiting input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads. - `id: string` Unique identifier for this event. - `agent_name: string` Name of the agent the thread runs. - `processed_at: string` A timestamp in RFC 3339 format - `session_thread_id: string` Public sthr_ ID of the thread that went idle. - `stop_reason: BetaManagedAgentsSessionEndTurn | BetaManagedAgentsSessionRequiresAction | BetaManagedAgentsSessionRetriesExhausted` The agent completed its turn naturally and is ready for the next user message. - `BetaManagedAgentsSessionEndTurn` The agent completed its turn naturally and is ready for the next user message. - `BetaManagedAgentsSessionRequiresAction` The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. - `BetaManagedAgentsSessionRetriesExhausted` The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). - `type: "session.thread_status_idle"` - `"session.thread_status_idle"` - `BetaManagedAgentsSessionThreadStatusTerminatedEvent` A session thread has terminated and will accept no further input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads. - `id: string` Unique identifier for this event. - `agent_name: string` Name of the agent the thread runs. - `processed_at: string` A timestamp in RFC 3339 format - `session_thread_id: string` Public sthr_ ID of the thread that terminated. - `type: "session.thread_status_terminated"` - `"session.thread_status_terminated"` - `BetaManagedAgentsUserToolResultEvent` Event sent by the client providing the result of an agent-toolset tool execution. Only valid on `self_hosted` environments, where sandbox-routed tools are executed by the client rather than the server. - `id: string` Unique identifier for this event. - `tool_use_id: string` The id of the `agent.tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `type: "user.tool_result"` - `"user.tool_result"` - `content?: Array` The result content returned by the tool. - `BetaManagedAgentsTextBlock` Regular text content. - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `BetaManagedAgentsSearchResultBlock` A block containing a web search result. - `is_error?: boolean | null` Whether the tool execution resulted in an error. - `processed_at?: string | null` A timestamp in RFC 3339 format - `session_thread_id?: string | null` Routes this result to a subagent thread. Copy from the `agent.tool_use` event's `session_thread_id`. - `BetaManagedAgentsSessionThreadStatusRescheduledEvent` A session thread hit a transient error and is retrying automatically. Emitted on the thread's own stream and cross-posted to the primary stream for child threads. - `id: string` Unique identifier for this event. - `agent_name: string` Name of the agent the thread runs. - `processed_at: string` A timestamp in RFC 3339 format - `session_thread_id: string` Public sthr_ ID of the thread that is retrying. - `type: "session.thread_status_rescheduled"` - `"session.thread_status_rescheduled"` - `BetaManagedAgentsSessionUpdatedEvent` Emitted when an UpdateSession request changed at least one field. Carries only the fields that changed; absent fields were not part of the update. The new configuration applies from the next turn. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `type: "session.updated"` - `"session.updated"` - `agent?: BetaManagedAgentsSessionAgent | null` Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. - `id: string` - `description: string | null` - `mcp_servers: Array` - `name: string` - `type: "url"` - `"url"` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `id: BetaManagedAgentsModel` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-opus-4-8" | "claude-opus-4-7" | "claude-opus-4-6" | 7 more` - `"claude-opus-4-8"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-7"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-6"` Most intelligent model for building agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` Fastest model with near-frontier intelligence - `"claude-haiku-4-5-20251001"` Fastest model with near-frontier intelligence - `"claude-opus-4-5"` Premium model combining maximum intelligence with practical performance - `"claude-opus-4-5-20251101"` Premium model combining maximum intelligence with practical performance - `"claude-sonnet-4-5"` High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` High-performance model for agents and coding - `(string & {})` - `speed?: "standard" | "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `multiagent: BetaManagedAgentsSessionMultiagentCoordinator | null` Resolved coordinator topology with full agent definitions for each roster member. - `agents: Array` Full `agent` definitions the coordinator may spawn as session threads. - `id: string` - `description: string | null` - `mcp_servers: Array` - `name: string` - `type: "url"` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `name: string` - `skills: Array` - `BetaManagedAgentsAnthropicSkill` A resolved Anthropic-managed skill. - `skill_id: string` - `type: "anthropic"` - `"anthropic"` - `version: string` - `BetaManagedAgentsCustomSkill` A resolved user-created custom skill. - `skill_id: string` - `type: "custom"` - `"custom"` - `version: string` - `system: string | null` - `tools: Array` - `BetaManagedAgentsAgentToolset20260401` - `configs: Array` - `enabled: boolean` - `name: "bash" | "edit" | "read" | 5 more` Built-in agent tool identifier. - `"bash"` - `"edit"` - `"read"` - `"write"` - `"glob"` - `"grep"` - `"web_fetch"` - `"web_search"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `"always_allow"` - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "always_ask"` - `"always_ask"` - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` Resolved default configuration for agent tools. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "agent_toolset_20260401"` - `"agent_toolset_20260401"` - `BetaManagedAgentsMCPToolset` - `configs: Array` - `enabled: boolean` - `name: string` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` Resolved default configuration for all tools from an MCP server. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `mcp_server_name: string` - `type: "mcp_toolset"` - `"mcp_toolset"` - `BetaManagedAgentsCustomTool` A custom tool as returned in API responses. - `description: string` - `input_schema: BetaManagedAgentsCustomToolInputSchema` JSON Schema for custom tool input parameters. - `properties?: Record | null` JSON Schema properties defining the tool's input parameters. - `required?: Array` List of required property names. - `type?: "object"` Must be 'object' for tool input schemas. - `"object"` - `name: string` - `type: "custom"` - `"custom"` - `type: "agent"` - `"agent"` - `version: number` - `type: "coordinator"` - `"coordinator"` - `name: string` - `skills: Array` - `BetaManagedAgentsAnthropicSkill` A resolved Anthropic-managed skill. - `BetaManagedAgentsCustomSkill` A resolved user-created custom skill. - `system: string | null` - `tools: Array` - `BetaManagedAgentsAgentToolset20260401` - `BetaManagedAgentsMCPToolset` - `BetaManagedAgentsCustomTool` A custom tool as returned in API responses. - `type: "agent"` - `"agent"` - `version: number` - `metadata?: Record` The session's full metadata bag after the update. Present when the update set non-empty metadata; absent when metadata was unchanged or cleared to empty. - `title?: string | null` The session's new title. Present only when the update changed it. ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const betaManagedAgentsStreamSessionEvents = await client.beta.sessions.events.stream( 'sesn_011CZkZAtmR3yMPDzynEDxu7', ); console.log(betaManagedAgentsStreamSessionEvents); ``` #### Response ```json { "id": "sevt_011CZkZGOp0iBcp4kaQSihUmy", "content": [ { "text": "Where is my order #1234?", "type": "text" } ], "type": "user.message", "processed_at": "2026-03-15T10:00:00Z" } ``` ## Domain Types ### Beta Managed Agents Agent Custom Tool Use Event - `BetaManagedAgentsAgentCustomToolUseEvent` Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. - `id: string` Unique identifier for this event. - `input: Record` Input parameters for the tool call. - `name: string` Name of the custom tool being called. - `processed_at: string` A timestamp in RFC 3339 format - `type: "agent.custom_tool_use"` - `"agent.custom_tool_use"` - `session_thread_id?: string | null` When set, this event was cross-posted from a subagent's thread to surface its custom tool use on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.custom_tool_result` event to route the result back. ### Beta Managed Agents Agent MCP Tool Result Event - `BetaManagedAgentsAgentMCPToolResultEvent` Event representing the result of an MCP tool execution. - `id: string` Unique identifier for this event. - `mcp_tool_use_id: string` The id of the `agent.mcp_tool_use` event this result corresponds to. - `processed_at: string` A timestamp in RFC 3339 format - `type: "agent.mcp_tool_result"` - `"agent.mcp_tool_result"` - `content?: Array` The result content returned by the tool. - `BetaManagedAgentsTextBlock` Regular text content. - `text: string` The text content. - `type: "text"` - `"text"` - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` Union type for image source variants. - `BetaManagedAgentsBase64ImageSource` Base64-encoded image data. - `data: string` Base64-encoded image data. - `media_type: string` MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). - `type: "base64"` - `"base64"` - `BetaManagedAgentsURLImageSource` Image referenced by URL. - `type: "url"` - `"url"` - `url: string` URL of the image to fetch. - `BetaManagedAgentsFileImageSource` Image referenced by file ID. - `file_id: string` ID of a previously uploaded file. - `type: "file"` - `"file"` - `type: "image"` - `"image"` - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` Union type for document source variants. - `BetaManagedAgentsBase64DocumentSource` Base64-encoded document data. - `data: string` Base64-encoded document data. - `media_type: string` MIME type of the document (e.g., "application/pdf"). - `type: "base64"` - `"base64"` - `BetaManagedAgentsPlainTextDocumentSource` Plain text document content. - `data: string` The plain text content. - `media_type: "text/plain"` MIME type of the text content. Must be "text/plain". - `"text/plain"` - `type: "text"` - `"text"` - `BetaManagedAgentsURLDocumentSource` Document referenced by URL. - `type: "url"` - `"url"` - `url: string` URL of the document to fetch. - `BetaManagedAgentsFileDocumentSource` Document referenced by file ID. - `file_id: string` ID of a previously uploaded file. - `type: "file"` - `"file"` - `type: "document"` - `"document"` - `context?: string | null` Additional context about the document for the model. - `title?: string | null` The title of the document. - `BetaManagedAgentsSearchResultBlock` A block containing a web search result. - `citations: BetaManagedAgentsSearchResultCitations` Citation settings for a search result. - `enabled: boolean` Whether citations are enabled for this search result. - `content: Array` Array of text content blocks from the search result. - `text: string` The text content. - `type: "text"` - `"text"` - `source: string` The URL source of the search result. - `title: string` The title of the search result. - `type: "search_result"` - `"search_result"` - `is_error?: boolean | null` Whether the tool execution resulted in an error. ### Beta Managed Agents Agent MCP Tool Use Event - `BetaManagedAgentsAgentMCPToolUseEvent` Event emitted when the agent invokes a tool provided by an MCP server. - `id: string` Unique identifier for this event. - `input: Record` Input parameters for the tool call. - `mcp_server_name: string` Name of the MCP server providing the tool. - `name: string` Name of the MCP tool being used. - `processed_at: string` A timestamp in RFC 3339 format - `type: "agent.mcp_tool_use"` - `"agent.mcp_tool_use"` - `evaluated_permission?: "allow" | "ask" | "deny"` AgentEvaluatedPermission enum - `"allow"` - `"ask"` - `"deny"` - `session_thread_id?: string | null` When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.tool_confirmation` event to route the approval back. ### Beta Managed Agents Agent Message Event - `BetaManagedAgentsAgentMessageEvent` An agent response event in the session conversation. - `id: string` Unique identifier for this event. - `content: Array` Array of text blocks comprising the agent response. - `text: string` The text content. - `type: "text"` - `"text"` - `processed_at: string` A timestamp in RFC 3339 format - `type: "agent.message"` - `"agent.message"` ### Beta Managed Agents Agent Thinking Event - `BetaManagedAgentsAgentThinkingEvent` Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `type: "agent.thinking"` - `"agent.thinking"` ### Beta Managed Agents Agent Thread Context Compacted Event - `BetaManagedAgentsAgentThreadContextCompactedEvent` Indicates that context compaction (summarization) occurred during the session. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `type: "agent.thread_context_compacted"` - `"agent.thread_context_compacted"` ### Beta Managed Agents Agent Thread Message Received Event - `BetaManagedAgentsAgentThreadMessageReceivedEvent` Delivery event written to the target thread's input stream when an agent-to-agent message arrives. - `id: string` Unique identifier for this event. - `content: Array` Message content blocks. - `BetaManagedAgentsTextBlock` Regular text content. - `text: string` The text content. - `type: "text"` - `"text"` - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` Union type for image source variants. - `BetaManagedAgentsBase64ImageSource` Base64-encoded image data. - `data: string` Base64-encoded image data. - `media_type: string` MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). - `type: "base64"` - `"base64"` - `BetaManagedAgentsURLImageSource` Image referenced by URL. - `type: "url"` - `"url"` - `url: string` URL of the image to fetch. - `BetaManagedAgentsFileImageSource` Image referenced by file ID. - `file_id: string` ID of a previously uploaded file. - `type: "file"` - `"file"` - `type: "image"` - `"image"` - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` Union type for document source variants. - `BetaManagedAgentsBase64DocumentSource` Base64-encoded document data. - `data: string` Base64-encoded document data. - `media_type: string` MIME type of the document (e.g., "application/pdf"). - `type: "base64"` - `"base64"` - `BetaManagedAgentsPlainTextDocumentSource` Plain text document content. - `data: string` The plain text content. - `media_type: "text/plain"` MIME type of the text content. Must be "text/plain". - `"text/plain"` - `type: "text"` - `"text"` - `BetaManagedAgentsURLDocumentSource` Document referenced by URL. - `type: "url"` - `"url"` - `url: string` URL of the document to fetch. - `BetaManagedAgentsFileDocumentSource` Document referenced by file ID. - `file_id: string` ID of a previously uploaded file. - `type: "file"` - `"file"` - `type: "document"` - `"document"` - `context?: string | null` Additional context about the document for the model. - `title?: string | null` The title of the document. - `from_session_thread_id: string` Public `sthr_` ID of the thread that sent the message. - `processed_at: string` A timestamp in RFC 3339 format - `type: "agent.thread_message_received"` - `"agent.thread_message_received"` - `from_agent_name?: string | null` Name of the callable agent this message came from. Absent when received from the primary agent. ### Beta Managed Agents Agent Thread Message Sent Event - `BetaManagedAgentsAgentThreadMessageSentEvent` Observability event emitted to the sender's output stream when an agent-to-agent message is sent. - `id: string` Unique identifier for this event. - `content: Array` Message content blocks. - `BetaManagedAgentsTextBlock` Regular text content. - `text: string` The text content. - `type: "text"` - `"text"` - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` Union type for image source variants. - `BetaManagedAgentsBase64ImageSource` Base64-encoded image data. - `data: string` Base64-encoded image data. - `media_type: string` MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). - `type: "base64"` - `"base64"` - `BetaManagedAgentsURLImageSource` Image referenced by URL. - `type: "url"` - `"url"` - `url: string` URL of the image to fetch. - `BetaManagedAgentsFileImageSource` Image referenced by file ID. - `file_id: string` ID of a previously uploaded file. - `type: "file"` - `"file"` - `type: "image"` - `"image"` - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` Union type for document source variants. - `BetaManagedAgentsBase64DocumentSource` Base64-encoded document data. - `data: string` Base64-encoded document data. - `media_type: string` MIME type of the document (e.g., "application/pdf"). - `type: "base64"` - `"base64"` - `BetaManagedAgentsPlainTextDocumentSource` Plain text document content. - `data: string` The plain text content. - `media_type: "text/plain"` MIME type of the text content. Must be "text/plain". - `"text/plain"` - `type: "text"` - `"text"` - `BetaManagedAgentsURLDocumentSource` Document referenced by URL. - `type: "url"` - `"url"` - `url: string` URL of the document to fetch. - `BetaManagedAgentsFileDocumentSource` Document referenced by file ID. - `file_id: string` ID of a previously uploaded file. - `type: "file"` - `"file"` - `type: "document"` - `"document"` - `context?: string | null` Additional context about the document for the model. - `title?: string | null` The title of the document. - `processed_at: string` A timestamp in RFC 3339 format - `to_session_thread_id: string` Public `sthr_` ID of the thread the message was sent to. - `type: "agent.thread_message_sent"` - `"agent.thread_message_sent"` - `to_agent_name?: string | null` Name of the callable agent this message was sent to. Absent when sent to the primary agent. ### Beta Managed Agents Agent Tool Result Event - `BetaManagedAgentsAgentToolResultEvent` Event representing the result of an agent tool execution. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `tool_use_id: string` The id of the `agent.tool_use` event this result corresponds to. - `type: "agent.tool_result"` - `"agent.tool_result"` - `content?: Array` The result content returned by the tool. - `BetaManagedAgentsTextBlock` Regular text content. - `text: string` The text content. - `type: "text"` - `"text"` - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` Union type for image source variants. - `BetaManagedAgentsBase64ImageSource` Base64-encoded image data. - `data: string` Base64-encoded image data. - `media_type: string` MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). - `type: "base64"` - `"base64"` - `BetaManagedAgentsURLImageSource` Image referenced by URL. - `type: "url"` - `"url"` - `url: string` URL of the image to fetch. - `BetaManagedAgentsFileImageSource` Image referenced by file ID. - `file_id: string` ID of a previously uploaded file. - `type: "file"` - `"file"` - `type: "image"` - `"image"` - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` Union type for document source variants. - `BetaManagedAgentsBase64DocumentSource` Base64-encoded document data. - `data: string` Base64-encoded document data. - `media_type: string` MIME type of the document (e.g., "application/pdf"). - `type: "base64"` - `"base64"` - `BetaManagedAgentsPlainTextDocumentSource` Plain text document content. - `data: string` The plain text content. - `media_type: "text/plain"` MIME type of the text content. Must be "text/plain". - `"text/plain"` - `type: "text"` - `"text"` - `BetaManagedAgentsURLDocumentSource` Document referenced by URL. - `type: "url"` - `"url"` - `url: string` URL of the document to fetch. - `BetaManagedAgentsFileDocumentSource` Document referenced by file ID. - `file_id: string` ID of a previously uploaded file. - `type: "file"` - `"file"` - `type: "document"` - `"document"` - `context?: string | null` Additional context about the document for the model. - `title?: string | null` The title of the document. - `BetaManagedAgentsSearchResultBlock` A block containing a web search result. - `citations: BetaManagedAgentsSearchResultCitations` Citation settings for a search result. - `enabled: boolean` Whether citations are enabled for this search result. - `content: Array` Array of text content blocks from the search result. - `text: string` The text content. - `type: "text"` - `"text"` - `source: string` The URL source of the search result. - `title: string` The title of the search result. - `type: "search_result"` - `"search_result"` - `is_error?: boolean | null` Whether the tool execution resulted in an error. ### Beta Managed Agents Agent Tool Use Event - `BetaManagedAgentsAgentToolUseEvent` Event emitted when the agent invokes a built-in agent tool. - `id: string` Unique identifier for this event. - `input: Record` Input parameters for the tool call. - `name: string` Name of the agent tool being used. - `processed_at: string` A timestamp in RFC 3339 format - `type: "agent.tool_use"` - `"agent.tool_use"` - `evaluated_permission?: "allow" | "ask" | "deny"` AgentEvaluatedPermission enum - `"allow"` - `"ask"` - `"deny"` - `session_thread_id?: string | null` When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.tool_confirmation` event to route the approval back. ### Beta Managed Agents Base64 Document Source - `BetaManagedAgentsBase64DocumentSource` Base64-encoded document data. - `data: string` Base64-encoded document data. - `media_type: string` MIME type of the document (e.g., "application/pdf"). - `type: "base64"` - `"base64"` ### Beta Managed Agents Base64 Image Source - `BetaManagedAgentsBase64ImageSource` Base64-encoded image data. - `data: string` Base64-encoded image data. - `media_type: string` MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). - `type: "base64"` - `"base64"` ### Beta Managed Agents Billing Error - `BetaManagedAgentsBillingError` The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` What the client should do next in response to this error. - `BetaManagedAgentsRetryStatusRetrying` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `type: "retrying"` - `"retrying"` - `BetaManagedAgentsRetryStatusExhausted` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `type: "exhausted"` - `"exhausted"` - `BetaManagedAgentsRetryStatusTerminal` The session encountered a terminal error and will transition to `terminated` state. - `type: "terminal"` - `"terminal"` - `type: "billing_error"` - `"billing_error"` ### Beta Managed Agents Document Block - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` Union type for document source variants. - `BetaManagedAgentsBase64DocumentSource` Base64-encoded document data. - `data: string` Base64-encoded document data. - `media_type: string` MIME type of the document (e.g., "application/pdf"). - `type: "base64"` - `"base64"` - `BetaManagedAgentsPlainTextDocumentSource` Plain text document content. - `data: string` The plain text content. - `media_type: "text/plain"` MIME type of the text content. Must be "text/plain". - `"text/plain"` - `type: "text"` - `"text"` - `BetaManagedAgentsURLDocumentSource` Document referenced by URL. - `type: "url"` - `"url"` - `url: string` URL of the document to fetch. - `BetaManagedAgentsFileDocumentSource` Document referenced by file ID. - `file_id: string` ID of a previously uploaded file. - `type: "file"` - `"file"` - `type: "document"` - `"document"` - `context?: string | null` Additional context about the document for the model. - `title?: string | null` The title of the document. ### Beta Managed Agents Event Params - `BetaManagedAgentsEventParams = BetaManagedAgentsUserMessageEventParams | BetaManagedAgentsUserInterruptEventParams | BetaManagedAgentsUserToolConfirmationEventParams | 3 more` Union type for event parameters that can be sent to a session. - `BetaManagedAgentsUserMessageEventParams` Parameters for sending a user message to the session. - `content: Array` Array of content blocks for the user message. - `BetaManagedAgentsTextBlock` Regular text content. - `text: string` The text content. - `type: "text"` - `"text"` - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` Union type for image source variants. - `BetaManagedAgentsBase64ImageSource` Base64-encoded image data. - `data: string` Base64-encoded image data. - `media_type: string` MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). - `type: "base64"` - `"base64"` - `BetaManagedAgentsURLImageSource` Image referenced by URL. - `type: "url"` - `"url"` - `url: string` URL of the image to fetch. - `BetaManagedAgentsFileImageSource` Image referenced by file ID. - `file_id: string` ID of a previously uploaded file. - `type: "file"` - `"file"` - `type: "image"` - `"image"` - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` Union type for document source variants. - `BetaManagedAgentsBase64DocumentSource` Base64-encoded document data. - `data: string` Base64-encoded document data. - `media_type: string` MIME type of the document (e.g., "application/pdf"). - `type: "base64"` - `"base64"` - `BetaManagedAgentsPlainTextDocumentSource` Plain text document content. - `data: string` The plain text content. - `media_type: "text/plain"` MIME type of the text content. Must be "text/plain". - `"text/plain"` - `type: "text"` - `"text"` - `BetaManagedAgentsURLDocumentSource` Document referenced by URL. - `type: "url"` - `"url"` - `url: string` URL of the document to fetch. - `BetaManagedAgentsFileDocumentSource` Document referenced by file ID. - `file_id: string` ID of a previously uploaded file. - `type: "file"` - `"file"` - `type: "document"` - `"document"` - `context?: string | null` Additional context about the document for the model. - `title?: string | null` The title of the document. - `type: "user.message"` - `"user.message"` - `BetaManagedAgentsUserInterruptEventParams` Parameters for sending an interrupt to pause the agent. - `type: "user.interrupt"` - `"user.interrupt"` - `session_thread_id?: string | null` If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread. - `BetaManagedAgentsUserToolConfirmationEventParams` Parameters for confirming or denying a tool execution request. - `result: "allow" | "deny"` UserToolConfirmationResult enum - `"allow"` - `"deny"` - `tool_use_id: string` The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `type: "user.tool_confirmation"` - `"user.tool_confirmation"` - `deny_message?: string | null` Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. - `BetaManagedAgentsUserCustomToolResultEventParams` Parameters for providing the result of a custom tool execution. - `custom_tool_use_id: string` The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `type: "user.custom_tool_result"` - `"user.custom_tool_result"` - `content?: Array` The result content returned by the tool. - `BetaManagedAgentsTextBlock` Regular text content. - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `BetaManagedAgentsSearchResultBlock` A block containing a web search result. - `citations: BetaManagedAgentsSearchResultCitations` Citation settings for a search result. - `enabled: boolean` Whether citations are enabled for this search result. - `content: Array` Array of text content blocks from the search result. - `text: string` The text content. - `type: "text"` - `"text"` - `source: string` The URL source of the search result. - `title: string` The title of the search result. - `type: "search_result"` - `"search_result"` - `is_error?: boolean | null` Whether the tool execution resulted in an error. - `BetaManagedAgentsUserDefineOutcomeEventParams` Parameters for defining an outcome the agent should work toward. The agent begins work on receipt. - `description: string` What the agent should produce. This is the task specification. - `rubric: BetaManagedAgentsFileRubricParams | BetaManagedAgentsTextRubricParams` Rubric for grading the quality of an outcome. - `BetaManagedAgentsFileRubricParams` Rubric referenced by a file uploaded via the Files API. - `file_id: string` ID of the rubric file. - `type: "file"` - `"file"` - `BetaManagedAgentsTextRubricParams` Rubric content provided inline as text. - `content: string` Rubric content. Plain text or markdown — the grader treats it as freeform text. Maximum 262144 characters. - `type: "text"` - `"text"` - `type: "user.define_outcome"` - `"user.define_outcome"` - `max_iterations?: number | null` Eval→revision cycles before giving up. Default 3, max 20. - `BetaManagedAgentsUserToolResultEventParams` Parameters for providing the result of an agent-toolset tool execution. Only valid on `self_hosted` environments, where sandbox-routed tools are executed by the client rather than the server. - `tool_use_id: string` The id of the `agent.tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `type: "user.tool_result"` - `"user.tool_result"` - `content?: Array` The result content returned by the tool. - `BetaManagedAgentsTextBlock` Regular text content. - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `BetaManagedAgentsSearchResultBlock` A block containing a web search result. - `is_error?: boolean | null` Whether the tool execution resulted in an error. ### Beta Managed Agents File Document Source - `BetaManagedAgentsFileDocumentSource` Document referenced by file ID. - `file_id: string` ID of a previously uploaded file. - `type: "file"` - `"file"` ### Beta Managed Agents File Image Source - `BetaManagedAgentsFileImageSource` Image referenced by file ID. - `file_id: string` ID of a previously uploaded file. - `type: "file"` - `"file"` ### Beta Managed Agents File Rubric - `BetaManagedAgentsFileRubric` Rubric referenced by a file uploaded via the Files API. - `file_id: string` ID of the rubric file. - `type: "file"` - `"file"` ### Beta Managed Agents File Rubric Params - `BetaManagedAgentsFileRubricParams` Rubric referenced by a file uploaded via the Files API. - `file_id: string` ID of the rubric file. - `type: "file"` - `"file"` ### Beta Managed Agents Image Block - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` Union type for image source variants. - `BetaManagedAgentsBase64ImageSource` Base64-encoded image data. - `data: string` Base64-encoded image data. - `media_type: string` MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). - `type: "base64"` - `"base64"` - `BetaManagedAgentsURLImageSource` Image referenced by URL. - `type: "url"` - `"url"` - `url: string` URL of the image to fetch. - `BetaManagedAgentsFileImageSource` Image referenced by file ID. - `file_id: string` ID of a previously uploaded file. - `type: "file"` - `"file"` - `type: "image"` - `"image"` ### Beta Managed Agents MCP Authentication Failed Error - `BetaManagedAgentsMCPAuthenticationFailedError` Authentication to an MCP server failed. - `mcp_server_name: string` Name of the MCP server that failed authentication. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` What the client should do next in response to this error. - `BetaManagedAgentsRetryStatusRetrying` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `type: "retrying"` - `"retrying"` - `BetaManagedAgentsRetryStatusExhausted` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `type: "exhausted"` - `"exhausted"` - `BetaManagedAgentsRetryStatusTerminal` The session encountered a terminal error and will transition to `terminated` state. - `type: "terminal"` - `"terminal"` - `type: "mcp_authentication_failed_error"` - `"mcp_authentication_failed_error"` ### Beta Managed Agents MCP Connection Failed Error - `BetaManagedAgentsMCPConnectionFailedError` Failed to connect to an MCP server. - `mcp_server_name: string` Name of the MCP server that failed to connect. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` What the client should do next in response to this error. - `BetaManagedAgentsRetryStatusRetrying` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `type: "retrying"` - `"retrying"` - `BetaManagedAgentsRetryStatusExhausted` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `type: "exhausted"` - `"exhausted"` - `BetaManagedAgentsRetryStatusTerminal` The session encountered a terminal error and will transition to `terminated` state. - `type: "terminal"` - `"terminal"` - `type: "mcp_connection_failed_error"` - `"mcp_connection_failed_error"` ### Beta Managed Agents Model Overloaded Error - `BetaManagedAgentsModelOverloadedError` The model is currently overloaded. Emitted after automatic retries are exhausted. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` What the client should do next in response to this error. - `BetaManagedAgentsRetryStatusRetrying` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `type: "retrying"` - `"retrying"` - `BetaManagedAgentsRetryStatusExhausted` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `type: "exhausted"` - `"exhausted"` - `BetaManagedAgentsRetryStatusTerminal` The session encountered a terminal error and will transition to `terminated` state. - `type: "terminal"` - `"terminal"` - `type: "model_overloaded_error"` - `"model_overloaded_error"` ### Beta Managed Agents Model Rate Limited Error - `BetaManagedAgentsModelRateLimitedError` The model request was rate-limited. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` What the client should do next in response to this error. - `BetaManagedAgentsRetryStatusRetrying` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `type: "retrying"` - `"retrying"` - `BetaManagedAgentsRetryStatusExhausted` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `type: "exhausted"` - `"exhausted"` - `BetaManagedAgentsRetryStatusTerminal` The session encountered a terminal error and will transition to `terminated` state. - `type: "terminal"` - `"terminal"` - `type: "model_rate_limited_error"` - `"model_rate_limited_error"` ### Beta Managed Agents Model Request Failed Error - `BetaManagedAgentsModelRequestFailedError` A model request failed for a reason other than overload or rate-limiting. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` What the client should do next in response to this error. - `BetaManagedAgentsRetryStatusRetrying` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `type: "retrying"` - `"retrying"` - `BetaManagedAgentsRetryStatusExhausted` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `type: "exhausted"` - `"exhausted"` - `BetaManagedAgentsRetryStatusTerminal` The session encountered a terminal error and will transition to `terminated` state. - `type: "terminal"` - `"terminal"` - `type: "model_request_failed_error"` - `"model_request_failed_error"` ### Beta Managed Agents Plain Text Document Source - `BetaManagedAgentsPlainTextDocumentSource` Plain text document content. - `data: string` The plain text content. - `media_type: "text/plain"` MIME type of the text content. Must be "text/plain". - `"text/plain"` - `type: "text"` - `"text"` ### Beta Managed Agents Retry Status Exhausted - `BetaManagedAgentsRetryStatusExhausted` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `type: "exhausted"` - `"exhausted"` ### Beta Managed Agents Retry Status Retrying - `BetaManagedAgentsRetryStatusRetrying` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `type: "retrying"` - `"retrying"` ### Beta Managed Agents Retry Status Terminal - `BetaManagedAgentsRetryStatusTerminal` The session encountered a terminal error and will transition to `terminated` state. - `type: "terminal"` - `"terminal"` ### Beta Managed Agents Search Result Block - `BetaManagedAgentsSearchResultBlock` A block containing a web search result. - `citations: BetaManagedAgentsSearchResultCitations` Citation settings for a search result. - `enabled: boolean` Whether citations are enabled for this search result. - `content: Array` Array of text content blocks from the search result. - `text: string` The text content. - `type: "text"` - `"text"` - `source: string` The URL source of the search result. - `title: string` The title of the search result. - `type: "search_result"` - `"search_result"` ### Beta Managed Agents Search Result Citations - `BetaManagedAgentsSearchResultCitations` Citation settings for a search result. - `enabled: boolean` Whether citations are enabled for this search result. ### Beta Managed Agents Search Result Content - `BetaManagedAgentsSearchResultContent` Text content within a search result. - `text: string` The text content. - `type: "text"` - `"text"` ### Beta Managed Agents Send Session Events - `BetaManagedAgentsSendSessionEvents` Events that were successfully sent to the session. - `data?: Array` Sent events - `BetaManagedAgentsUserMessageEvent` A user message event in the session conversation. - `id: string` Unique identifier for this event. - `content: Array` Array of content blocks comprising the user message. - `BetaManagedAgentsTextBlock` Regular text content. - `text: string` The text content. - `type: "text"` - `"text"` - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` Union type for image source variants. - `BetaManagedAgentsBase64ImageSource` Base64-encoded image data. - `data: string` Base64-encoded image data. - `media_type: string` MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). - `type: "base64"` - `"base64"` - `BetaManagedAgentsURLImageSource` Image referenced by URL. - `type: "url"` - `"url"` - `url: string` URL of the image to fetch. - `BetaManagedAgentsFileImageSource` Image referenced by file ID. - `file_id: string` ID of a previously uploaded file. - `type: "file"` - `"file"` - `type: "image"` - `"image"` - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` Union type for document source variants. - `BetaManagedAgentsBase64DocumentSource` Base64-encoded document data. - `data: string` Base64-encoded document data. - `media_type: string` MIME type of the document (e.g., "application/pdf"). - `type: "base64"` - `"base64"` - `BetaManagedAgentsPlainTextDocumentSource` Plain text document content. - `data: string` The plain text content. - `media_type: "text/plain"` MIME type of the text content. Must be "text/plain". - `"text/plain"` - `type: "text"` - `"text"` - `BetaManagedAgentsURLDocumentSource` Document referenced by URL. - `type: "url"` - `"url"` - `url: string` URL of the document to fetch. - `BetaManagedAgentsFileDocumentSource` Document referenced by file ID. - `file_id: string` ID of a previously uploaded file. - `type: "file"` - `"file"` - `type: "document"` - `"document"` - `context?: string | null` Additional context about the document for the model. - `title?: string | null` The title of the document. - `type: "user.message"` - `"user.message"` - `processed_at?: string | null` A timestamp in RFC 3339 format - `BetaManagedAgentsUserInterruptEvent` An interrupt event that pauses agent execution and returns control to the user. - `id: string` Unique identifier for this event. - `type: "user.interrupt"` - `"user.interrupt"` - `processed_at?: string | null` A timestamp in RFC 3339 format - `session_thread_id?: string | null` If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread. - `BetaManagedAgentsUserToolConfirmationEvent` A tool confirmation event that approves or denies a pending tool execution. - `id: string` Unique identifier for this event. - `result: "allow" | "deny"` UserToolConfirmationResult enum - `"allow"` - `"deny"` - `tool_use_id: string` The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `type: "user.tool_confirmation"` - `"user.tool_confirmation"` - `deny_message?: string | null` Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. - `processed_at?: string | null` A timestamp in RFC 3339 format - `session_thread_id?: string | null` When set, the confirmation routes to this subagent's thread rather than the primary. Echo this from the `session_thread_id` on the `agent.tool_use` or `agent.mcp_tool_use` event that prompted the approval. - `BetaManagedAgentsUserCustomToolResultEvent` Event sent by the client providing the result of a custom tool execution. - `id: string` Unique identifier for this event. - `custom_tool_use_id: string` The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `type: "user.custom_tool_result"` - `"user.custom_tool_result"` - `content?: Array` The result content returned by the tool. - `BetaManagedAgentsTextBlock` Regular text content. - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `BetaManagedAgentsSearchResultBlock` A block containing a web search result. - `citations: BetaManagedAgentsSearchResultCitations` Citation settings for a search result. - `enabled: boolean` Whether citations are enabled for this search result. - `content: Array` Array of text content blocks from the search result. - `text: string` The text content. - `type: "text"` - `"text"` - `source: string` The URL source of the search result. - `title: string` The title of the search result. - `type: "search_result"` - `"search_result"` - `is_error?: boolean | null` Whether the tool execution resulted in an error. - `processed_at?: string | null` A timestamp in RFC 3339 format - `session_thread_id?: string | null` Routes this result to a subagent thread. Copy from the `agent.custom_tool_use` event's `session_thread_id`. - `BetaManagedAgentsUserDefineOutcomeEvent` Echo of a `user.define_outcome` input event. Carries the server-generated `outcome_id` that subsequent `span.outcome_evaluation_*` events reference. - `id: string` Unique identifier for this event. - `description: string` What the agent should produce. Copied from the input event. - `max_iterations: number | null` Evaluate-then-revise cycles before giving up. Default 3, max 20. - `outcome_id: string` Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list. - `processed_at: string` A timestamp in RFC 3339 format - `rubric: BetaManagedAgentsFileRubric | BetaManagedAgentsTextRubric` Rubric for grading the quality of an outcome. - `BetaManagedAgentsFileRubric` Rubric referenced by a file uploaded via the Files API. - `file_id: string` ID of the rubric file. - `type: "file"` - `"file"` - `BetaManagedAgentsTextRubric` Rubric content provided inline as text. - `content: string` Rubric content. Plain text or markdown — the grader treats it as freeform text. - `type: "text"` - `"text"` - `type: "user.define_outcome"` - `"user.define_outcome"` - `BetaManagedAgentsUserToolResultEvent` Event sent by the client providing the result of an agent-toolset tool execution. Only valid on `self_hosted` environments, where sandbox-routed tools are executed by the client rather than the server. - `id: string` Unique identifier for this event. - `tool_use_id: string` The id of the `agent.tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `type: "user.tool_result"` - `"user.tool_result"` - `content?: Array` The result content returned by the tool. - `BetaManagedAgentsTextBlock` Regular text content. - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `BetaManagedAgentsSearchResultBlock` A block containing a web search result. - `is_error?: boolean | null` Whether the tool execution resulted in an error. - `processed_at?: string | null` A timestamp in RFC 3339 format - `session_thread_id?: string | null` Routes this result to a subagent thread. Copy from the `agent.tool_use` event's `session_thread_id`. ### Beta Managed Agents Session Deleted Event - `BetaManagedAgentsSessionDeletedEvent` Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `type: "session.deleted"` - `"session.deleted"` ### Beta Managed Agents Session End Turn - `BetaManagedAgentsSessionEndTurn` The agent completed its turn naturally and is ready for the next user message. - `type: "end_turn"` - `"end_turn"` ### Beta Managed Agents Session Error Event - `BetaManagedAgentsSessionErrorEvent` An error event indicating a problem occurred during session execution. - `id: string` Unique identifier for this event. - `error: BetaManagedAgentsUnknownError | BetaManagedAgentsModelOverloadedError | BetaManagedAgentsModelRateLimitedError | 4 more` An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. - `BetaManagedAgentsUnknownError` An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` What the client should do next in response to this error. - `BetaManagedAgentsRetryStatusRetrying` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `type: "retrying"` - `"retrying"` - `BetaManagedAgentsRetryStatusExhausted` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `type: "exhausted"` - `"exhausted"` - `BetaManagedAgentsRetryStatusTerminal` The session encountered a terminal error and will transition to `terminated` state. - `type: "terminal"` - `"terminal"` - `type: "unknown_error"` - `"unknown_error"` - `BetaManagedAgentsModelOverloadedError` The model is currently overloaded. Emitted after automatic retries are exhausted. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` What the client should do next in response to this error. - `BetaManagedAgentsRetryStatusRetrying` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal` The session encountered a terminal error and will transition to `terminated` state. - `type: "model_overloaded_error"` - `"model_overloaded_error"` - `BetaManagedAgentsModelRateLimitedError` The model request was rate-limited. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` What the client should do next in response to this error. - `BetaManagedAgentsRetryStatusRetrying` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal` The session encountered a terminal error and will transition to `terminated` state. - `type: "model_rate_limited_error"` - `"model_rate_limited_error"` - `BetaManagedAgentsModelRequestFailedError` A model request failed for a reason other than overload or rate-limiting. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` What the client should do next in response to this error. - `BetaManagedAgentsRetryStatusRetrying` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal` The session encountered a terminal error and will transition to `terminated` state. - `type: "model_request_failed_error"` - `"model_request_failed_error"` - `BetaManagedAgentsMCPConnectionFailedError` Failed to connect to an MCP server. - `mcp_server_name: string` Name of the MCP server that failed to connect. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` What the client should do next in response to this error. - `BetaManagedAgentsRetryStatusRetrying` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal` The session encountered a terminal error and will transition to `terminated` state. - `type: "mcp_connection_failed_error"` - `"mcp_connection_failed_error"` - `BetaManagedAgentsMCPAuthenticationFailedError` Authentication to an MCP server failed. - `mcp_server_name: string` Name of the MCP server that failed authentication. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` What the client should do next in response to this error. - `BetaManagedAgentsRetryStatusRetrying` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal` The session encountered a terminal error and will transition to `terminated` state. - `type: "mcp_authentication_failed_error"` - `"mcp_authentication_failed_error"` - `BetaManagedAgentsBillingError` The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` What the client should do next in response to this error. - `BetaManagedAgentsRetryStatusRetrying` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal` The session encountered a terminal error and will transition to `terminated` state. - `type: "billing_error"` - `"billing_error"` - `processed_at: string` A timestamp in RFC 3339 format - `type: "session.error"` - `"session.error"` ### Beta Managed Agents Session Event - `BetaManagedAgentsSessionEvent = BetaManagedAgentsUserMessageEvent | BetaManagedAgentsUserInterruptEvent | BetaManagedAgentsUserToolConfirmationEvent | 30 more` Union type for all event types in a session. - `BetaManagedAgentsUserMessageEvent` A user message event in the session conversation. - `id: string` Unique identifier for this event. - `content: Array` Array of content blocks comprising the user message. - `BetaManagedAgentsTextBlock` Regular text content. - `text: string` The text content. - `type: "text"` - `"text"` - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` Union type for image source variants. - `BetaManagedAgentsBase64ImageSource` Base64-encoded image data. - `data: string` Base64-encoded image data. - `media_type: string` MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). - `type: "base64"` - `"base64"` - `BetaManagedAgentsURLImageSource` Image referenced by URL. - `type: "url"` - `"url"` - `url: string` URL of the image to fetch. - `BetaManagedAgentsFileImageSource` Image referenced by file ID. - `file_id: string` ID of a previously uploaded file. - `type: "file"` - `"file"` - `type: "image"` - `"image"` - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` Union type for document source variants. - `BetaManagedAgentsBase64DocumentSource` Base64-encoded document data. - `data: string` Base64-encoded document data. - `media_type: string` MIME type of the document (e.g., "application/pdf"). - `type: "base64"` - `"base64"` - `BetaManagedAgentsPlainTextDocumentSource` Plain text document content. - `data: string` The plain text content. - `media_type: "text/plain"` MIME type of the text content. Must be "text/plain". - `"text/plain"` - `type: "text"` - `"text"` - `BetaManagedAgentsURLDocumentSource` Document referenced by URL. - `type: "url"` - `"url"` - `url: string` URL of the document to fetch. - `BetaManagedAgentsFileDocumentSource` Document referenced by file ID. - `file_id: string` ID of a previously uploaded file. - `type: "file"` - `"file"` - `type: "document"` - `"document"` - `context?: string | null` Additional context about the document for the model. - `title?: string | null` The title of the document. - `type: "user.message"` - `"user.message"` - `processed_at?: string | null` A timestamp in RFC 3339 format - `BetaManagedAgentsUserInterruptEvent` An interrupt event that pauses agent execution and returns control to the user. - `id: string` Unique identifier for this event. - `type: "user.interrupt"` - `"user.interrupt"` - `processed_at?: string | null` A timestamp in RFC 3339 format - `session_thread_id?: string | null` If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread. - `BetaManagedAgentsUserToolConfirmationEvent` A tool confirmation event that approves or denies a pending tool execution. - `id: string` Unique identifier for this event. - `result: "allow" | "deny"` UserToolConfirmationResult enum - `"allow"` - `"deny"` - `tool_use_id: string` The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `type: "user.tool_confirmation"` - `"user.tool_confirmation"` - `deny_message?: string | null` Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. - `processed_at?: string | null` A timestamp in RFC 3339 format - `session_thread_id?: string | null` When set, the confirmation routes to this subagent's thread rather than the primary. Echo this from the `session_thread_id` on the `agent.tool_use` or `agent.mcp_tool_use` event that prompted the approval. - `BetaManagedAgentsUserCustomToolResultEvent` Event sent by the client providing the result of a custom tool execution. - `id: string` Unique identifier for this event. - `custom_tool_use_id: string` The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `type: "user.custom_tool_result"` - `"user.custom_tool_result"` - `content?: Array` The result content returned by the tool. - `BetaManagedAgentsTextBlock` Regular text content. - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `BetaManagedAgentsSearchResultBlock` A block containing a web search result. - `citations: BetaManagedAgentsSearchResultCitations` Citation settings for a search result. - `enabled: boolean` Whether citations are enabled for this search result. - `content: Array` Array of text content blocks from the search result. - `text: string` The text content. - `type: "text"` - `"text"` - `source: string` The URL source of the search result. - `title: string` The title of the search result. - `type: "search_result"` - `"search_result"` - `is_error?: boolean | null` Whether the tool execution resulted in an error. - `processed_at?: string | null` A timestamp in RFC 3339 format - `session_thread_id?: string | null` Routes this result to a subagent thread. Copy from the `agent.custom_tool_use` event's `session_thread_id`. - `BetaManagedAgentsAgentCustomToolUseEvent` Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. - `id: string` Unique identifier for this event. - `input: Record` Input parameters for the tool call. - `name: string` Name of the custom tool being called. - `processed_at: string` A timestamp in RFC 3339 format - `type: "agent.custom_tool_use"` - `"agent.custom_tool_use"` - `session_thread_id?: string | null` When set, this event was cross-posted from a subagent's thread to surface its custom tool use on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.custom_tool_result` event to route the result back. - `BetaManagedAgentsAgentMessageEvent` An agent response event in the session conversation. - `id: string` Unique identifier for this event. - `content: Array` Array of text blocks comprising the agent response. - `text: string` The text content. - `type: "text"` - `processed_at: string` A timestamp in RFC 3339 format - `type: "agent.message"` - `"agent.message"` - `BetaManagedAgentsAgentThinkingEvent` Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `type: "agent.thinking"` - `"agent.thinking"` - `BetaManagedAgentsAgentMCPToolUseEvent` Event emitted when the agent invokes a tool provided by an MCP server. - `id: string` Unique identifier for this event. - `input: Record` Input parameters for the tool call. - `mcp_server_name: string` Name of the MCP server providing the tool. - `name: string` Name of the MCP tool being used. - `processed_at: string` A timestamp in RFC 3339 format - `type: "agent.mcp_tool_use"` - `"agent.mcp_tool_use"` - `evaluated_permission?: "allow" | "ask" | "deny"` AgentEvaluatedPermission enum - `"allow"` - `"ask"` - `"deny"` - `session_thread_id?: string | null` When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.tool_confirmation` event to route the approval back. - `BetaManagedAgentsAgentMCPToolResultEvent` Event representing the result of an MCP tool execution. - `id: string` Unique identifier for this event. - `mcp_tool_use_id: string` The id of the `agent.mcp_tool_use` event this result corresponds to. - `processed_at: string` A timestamp in RFC 3339 format - `type: "agent.mcp_tool_result"` - `"agent.mcp_tool_result"` - `content?: Array` The result content returned by the tool. - `BetaManagedAgentsTextBlock` Regular text content. - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `BetaManagedAgentsSearchResultBlock` A block containing a web search result. - `is_error?: boolean | null` Whether the tool execution resulted in an error. - `BetaManagedAgentsAgentToolUseEvent` Event emitted when the agent invokes a built-in agent tool. - `id: string` Unique identifier for this event. - `input: Record` Input parameters for the tool call. - `name: string` Name of the agent tool being used. - `processed_at: string` A timestamp in RFC 3339 format - `type: "agent.tool_use"` - `"agent.tool_use"` - `evaluated_permission?: "allow" | "ask" | "deny"` AgentEvaluatedPermission enum - `"allow"` - `"ask"` - `"deny"` - `session_thread_id?: string | null` When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.tool_confirmation` event to route the approval back. - `BetaManagedAgentsAgentToolResultEvent` Event representing the result of an agent tool execution. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `tool_use_id: string` The id of the `agent.tool_use` event this result corresponds to. - `type: "agent.tool_result"` - `"agent.tool_result"` - `content?: Array` The result content returned by the tool. - `BetaManagedAgentsTextBlock` Regular text content. - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `BetaManagedAgentsSearchResultBlock` A block containing a web search result. - `is_error?: boolean | null` Whether the tool execution resulted in an error. - `BetaManagedAgentsAgentThreadMessageReceivedEvent` Delivery event written to the target thread's input stream when an agent-to-agent message arrives. - `id: string` Unique identifier for this event. - `content: Array` Message content blocks. - `BetaManagedAgentsTextBlock` Regular text content. - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `from_session_thread_id: string` Public `sthr_` ID of the thread that sent the message. - `processed_at: string` A timestamp in RFC 3339 format - `type: "agent.thread_message_received"` - `"agent.thread_message_received"` - `from_agent_name?: string | null` Name of the callable agent this message came from. Absent when received from the primary agent. - `BetaManagedAgentsAgentThreadMessageSentEvent` Observability event emitted to the sender's output stream when an agent-to-agent message is sent. - `id: string` Unique identifier for this event. - `content: Array` Message content blocks. - `BetaManagedAgentsTextBlock` Regular text content. - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `processed_at: string` A timestamp in RFC 3339 format - `to_session_thread_id: string` Public `sthr_` ID of the thread the message was sent to. - `type: "agent.thread_message_sent"` - `"agent.thread_message_sent"` - `to_agent_name?: string | null` Name of the callable agent this message was sent to. Absent when sent to the primary agent. - `BetaManagedAgentsAgentThreadContextCompactedEvent` Indicates that context compaction (summarization) occurred during the session. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `type: "agent.thread_context_compacted"` - `"agent.thread_context_compacted"` - `BetaManagedAgentsSessionErrorEvent` An error event indicating a problem occurred during session execution. - `id: string` Unique identifier for this event. - `error: BetaManagedAgentsUnknownError | BetaManagedAgentsModelOverloadedError | BetaManagedAgentsModelRateLimitedError | 4 more` An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. - `BetaManagedAgentsUnknownError` An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` What the client should do next in response to this error. - `BetaManagedAgentsRetryStatusRetrying` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `type: "retrying"` - `"retrying"` - `BetaManagedAgentsRetryStatusExhausted` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `type: "exhausted"` - `"exhausted"` - `BetaManagedAgentsRetryStatusTerminal` The session encountered a terminal error and will transition to `terminated` state. - `type: "terminal"` - `"terminal"` - `type: "unknown_error"` - `"unknown_error"` - `BetaManagedAgentsModelOverloadedError` The model is currently overloaded. Emitted after automatic retries are exhausted. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` What the client should do next in response to this error. - `BetaManagedAgentsRetryStatusRetrying` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal` The session encountered a terminal error and will transition to `terminated` state. - `type: "model_overloaded_error"` - `"model_overloaded_error"` - `BetaManagedAgentsModelRateLimitedError` The model request was rate-limited. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` What the client should do next in response to this error. - `BetaManagedAgentsRetryStatusRetrying` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal` The session encountered a terminal error and will transition to `terminated` state. - `type: "model_rate_limited_error"` - `"model_rate_limited_error"` - `BetaManagedAgentsModelRequestFailedError` A model request failed for a reason other than overload or rate-limiting. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` What the client should do next in response to this error. - `BetaManagedAgentsRetryStatusRetrying` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal` The session encountered a terminal error and will transition to `terminated` state. - `type: "model_request_failed_error"` - `"model_request_failed_error"` - `BetaManagedAgentsMCPConnectionFailedError` Failed to connect to an MCP server. - `mcp_server_name: string` Name of the MCP server that failed to connect. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` What the client should do next in response to this error. - `BetaManagedAgentsRetryStatusRetrying` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal` The session encountered a terminal error and will transition to `terminated` state. - `type: "mcp_connection_failed_error"` - `"mcp_connection_failed_error"` - `BetaManagedAgentsMCPAuthenticationFailedError` Authentication to an MCP server failed. - `mcp_server_name: string` Name of the MCP server that failed authentication. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` What the client should do next in response to this error. - `BetaManagedAgentsRetryStatusRetrying` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal` The session encountered a terminal error and will transition to `terminated` state. - `type: "mcp_authentication_failed_error"` - `"mcp_authentication_failed_error"` - `BetaManagedAgentsBillingError` The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` What the client should do next in response to this error. - `BetaManagedAgentsRetryStatusRetrying` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal` The session encountered a terminal error and will transition to `terminated` state. - `type: "billing_error"` - `"billing_error"` - `processed_at: string` A timestamp in RFC 3339 format - `type: "session.error"` - `"session.error"` - `BetaManagedAgentsSessionStatusRescheduledEvent` Indicates the session is recovering from an error state and is rescheduled for execution. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `type: "session.status_rescheduled"` - `"session.status_rescheduled"` - `BetaManagedAgentsSessionStatusRunningEvent` Indicates the session is actively running and the agent is working. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `type: "session.status_running"` - `"session.status_running"` - `BetaManagedAgentsSessionStatusIdleEvent` Indicates the agent has paused and is awaiting user input. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `stop_reason: BetaManagedAgentsSessionEndTurn | BetaManagedAgentsSessionRequiresAction | BetaManagedAgentsSessionRetriesExhausted` The agent completed its turn naturally and is ready for the next user message. - `BetaManagedAgentsSessionEndTurn` The agent completed its turn naturally and is ready for the next user message. - `type: "end_turn"` - `"end_turn"` - `BetaManagedAgentsSessionRequiresAction` The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. - `event_ids: Array` The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. - `type: "requires_action"` - `"requires_action"` - `BetaManagedAgentsSessionRetriesExhausted` The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). - `type: "retries_exhausted"` - `"retries_exhausted"` - `type: "session.status_idle"` - `"session.status_idle"` - `BetaManagedAgentsSessionStatusTerminatedEvent` Indicates the session has terminated, either due to an error or completion. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `type: "session.status_terminated"` - `"session.status_terminated"` - `BetaManagedAgentsSessionThreadCreatedEvent` Emitted when a subagent is spawned as a new thread. Written to the parent thread's output stream so clients observing the session see child creation. - `id: string` Unique identifier for this event. - `agent_name: string` Name of the callable agent the thread runs. - `processed_at: string` A timestamp in RFC 3339 format - `session_thread_id: string` Public `sthr_` ID of the newly created thread. - `type: "session.thread_created"` - `"session.thread_created"` - `BetaManagedAgentsSpanOutcomeEvaluationStartEvent` Emitted when an outcome evaluation cycle begins. - `id: string` Unique identifier for this event. - `iteration: number` 0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc. - `outcome_id: string` The `outc_` ID of the outcome being evaluated. - `processed_at: string` A timestamp in RFC 3339 format - `type: "span.outcome_evaluation_start"` - `"span.outcome_evaluation_start"` - `BetaManagedAgentsSpanOutcomeEvaluationEndEvent` Emitted when an outcome evaluation cycle completes. Carries the verdict and aggregate token usage. A verdict of `needs_revision` means another evaluation cycle follows; `satisfied`, `max_iterations_reached`, `failed`, or `interrupted` are terminal — no further evaluation cycles follow. - `id: string` Unique identifier for this event. - `explanation: string` Human-readable explanation of the verdict. For `needs_revision`, describes which criteria failed and why. - `iteration: number` 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`. - `outcome_evaluation_start_id: string` The id of the corresponding `span.outcome_evaluation_start` event. - `outcome_id: string` The `outc_` ID of the outcome being evaluated. - `processed_at: string` A timestamp in RFC 3339 format - `result: string` Evaluation verdict. 'satisfied': criteria met, session goes idle. 'needs_revision': criteria not met, another revision cycle follows. 'max_iterations_reached': evaluation budget exhausted with criteria still unmet — one final acknowledgment turn follows before the session goes idle, but no further evaluation runs. 'failed': grader determined the rubric does not apply to the deliverables. 'interrupted': user sent an interrupt while evaluation was in progress. - `type: "span.outcome_evaluation_end"` - `"span.outcome_evaluation_end"` - `usage: BetaManagedAgentsSpanModelUsage` Token usage for a single model request. - `cache_creation_input_tokens: number` Tokens used to create prompt cache in this request. - `cache_read_input_tokens: number` Tokens read from prompt cache in this request. - `input_tokens: number` Input tokens consumed by this request. - `output_tokens: number` Output tokens generated by this request. - `speed?: "standard" | "fast" | null` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `BetaManagedAgentsSpanModelRequestStartEvent` Emitted when a model request is initiated by the agent. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `type: "span.model_request_start"` - `"span.model_request_start"` - `BetaManagedAgentsSpanModelRequestEndEvent` Emitted when a model request completes. - `id: string` Unique identifier for this event. - `is_error: boolean | null` Whether the model request resulted in an error. - `model_request_start_id: string` The id of the corresponding `span.model_request_start` event. - `model_usage: BetaManagedAgentsSpanModelUsage` Token usage for a single model request. - `processed_at: string` A timestamp in RFC 3339 format - `type: "span.model_request_end"` - `"span.model_request_end"` - `BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent` Periodic heartbeat emitted while an outcome evaluation cycle is in progress. Distinguishes 'evaluation is actively running' from 'evaluation is stuck' between the corresponding `span.outcome_evaluation_start` and `span.outcome_evaluation_end` events. - `id: string` Unique identifier for this event. - `iteration: number` 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`. - `outcome_id: string` The `outc_` ID of the outcome being evaluated. - `processed_at: string` A timestamp in RFC 3339 format - `type: "span.outcome_evaluation_ongoing"` - `"span.outcome_evaluation_ongoing"` - `BetaManagedAgentsUserDefineOutcomeEvent` Echo of a `user.define_outcome` input event. Carries the server-generated `outcome_id` that subsequent `span.outcome_evaluation_*` events reference. - `id: string` Unique identifier for this event. - `description: string` What the agent should produce. Copied from the input event. - `max_iterations: number | null` Evaluate-then-revise cycles before giving up. Default 3, max 20. - `outcome_id: string` Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list. - `processed_at: string` A timestamp in RFC 3339 format - `rubric: BetaManagedAgentsFileRubric | BetaManagedAgentsTextRubric` Rubric for grading the quality of an outcome. - `BetaManagedAgentsFileRubric` Rubric referenced by a file uploaded via the Files API. - `file_id: string` ID of the rubric file. - `type: "file"` - `"file"` - `BetaManagedAgentsTextRubric` Rubric content provided inline as text. - `content: string` Rubric content. Plain text or markdown — the grader treats it as freeform text. - `type: "text"` - `"text"` - `type: "user.define_outcome"` - `"user.define_outcome"` - `BetaManagedAgentsSessionDeletedEvent` Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `type: "session.deleted"` - `"session.deleted"` - `BetaManagedAgentsSessionThreadStatusRunningEvent` A session thread has begun executing. Emitted on the thread's own stream and cross-posted to the primary stream for child threads. - `id: string` Unique identifier for this event. - `agent_name: string` Name of the agent the thread runs. - `processed_at: string` A timestamp in RFC 3339 format - `session_thread_id: string` Public sthr_ ID of the thread that started running. - `type: "session.thread_status_running"` - `"session.thread_status_running"` - `BetaManagedAgentsSessionThreadStatusIdleEvent` A session thread has yielded and is awaiting input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads. - `id: string` Unique identifier for this event. - `agent_name: string` Name of the agent the thread runs. - `processed_at: string` A timestamp in RFC 3339 format - `session_thread_id: string` Public sthr_ ID of the thread that went idle. - `stop_reason: BetaManagedAgentsSessionEndTurn | BetaManagedAgentsSessionRequiresAction | BetaManagedAgentsSessionRetriesExhausted` The agent completed its turn naturally and is ready for the next user message. - `BetaManagedAgentsSessionEndTurn` The agent completed its turn naturally and is ready for the next user message. - `BetaManagedAgentsSessionRequiresAction` The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. - `BetaManagedAgentsSessionRetriesExhausted` The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). - `type: "session.thread_status_idle"` - `"session.thread_status_idle"` - `BetaManagedAgentsSessionThreadStatusTerminatedEvent` A session thread has terminated and will accept no further input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads. - `id: string` Unique identifier for this event. - `agent_name: string` Name of the agent the thread runs. - `processed_at: string` A timestamp in RFC 3339 format - `session_thread_id: string` Public sthr_ ID of the thread that terminated. - `type: "session.thread_status_terminated"` - `"session.thread_status_terminated"` - `BetaManagedAgentsUserToolResultEvent` Event sent by the client providing the result of an agent-toolset tool execution. Only valid on `self_hosted` environments, where sandbox-routed tools are executed by the client rather than the server. - `id: string` Unique identifier for this event. - `tool_use_id: string` The id of the `agent.tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `type: "user.tool_result"` - `"user.tool_result"` - `content?: Array` The result content returned by the tool. - `BetaManagedAgentsTextBlock` Regular text content. - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `BetaManagedAgentsSearchResultBlock` A block containing a web search result. - `is_error?: boolean | null` Whether the tool execution resulted in an error. - `processed_at?: string | null` A timestamp in RFC 3339 format - `session_thread_id?: string | null` Routes this result to a subagent thread. Copy from the `agent.tool_use` event's `session_thread_id`. - `BetaManagedAgentsSessionThreadStatusRescheduledEvent` A session thread hit a transient error and is retrying automatically. Emitted on the thread's own stream and cross-posted to the primary stream for child threads. - `id: string` Unique identifier for this event. - `agent_name: string` Name of the agent the thread runs. - `processed_at: string` A timestamp in RFC 3339 format - `session_thread_id: string` Public sthr_ ID of the thread that is retrying. - `type: "session.thread_status_rescheduled"` - `"session.thread_status_rescheduled"` - `BetaManagedAgentsSessionUpdatedEvent` Emitted when an UpdateSession request changed at least one field. Carries only the fields that changed; absent fields were not part of the update. The new configuration applies from the next turn. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `type: "session.updated"` - `"session.updated"` - `agent?: BetaManagedAgentsSessionAgent | null` Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. - `id: string` - `description: string | null` - `mcp_servers: Array` - `name: string` - `type: "url"` - `"url"` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `id: BetaManagedAgentsModel` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-opus-4-8" | "claude-opus-4-7" | "claude-opus-4-6" | 7 more` - `"claude-opus-4-8"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-7"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-6"` Most intelligent model for building agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` Fastest model with near-frontier intelligence - `"claude-haiku-4-5-20251001"` Fastest model with near-frontier intelligence - `"claude-opus-4-5"` Premium model combining maximum intelligence with practical performance - `"claude-opus-4-5-20251101"` Premium model combining maximum intelligence with practical performance - `"claude-sonnet-4-5"` High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` High-performance model for agents and coding - `(string & {})` - `speed?: "standard" | "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `multiagent: BetaManagedAgentsSessionMultiagentCoordinator | null` Resolved coordinator topology with full agent definitions for each roster member. - `agents: Array` Full `agent` definitions the coordinator may spawn as session threads. - `id: string` - `description: string | null` - `mcp_servers: Array` - `name: string` - `type: "url"` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `name: string` - `skills: Array` - `BetaManagedAgentsAnthropicSkill` A resolved Anthropic-managed skill. - `skill_id: string` - `type: "anthropic"` - `"anthropic"` - `version: string` - `BetaManagedAgentsCustomSkill` A resolved user-created custom skill. - `skill_id: string` - `type: "custom"` - `"custom"` - `version: string` - `system: string | null` - `tools: Array` - `BetaManagedAgentsAgentToolset20260401` - `configs: Array` - `enabled: boolean` - `name: "bash" | "edit" | "read" | 5 more` Built-in agent tool identifier. - `"bash"` - `"edit"` - `"read"` - `"write"` - `"glob"` - `"grep"` - `"web_fetch"` - `"web_search"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `"always_allow"` - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "always_ask"` - `"always_ask"` - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` Resolved default configuration for agent tools. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "agent_toolset_20260401"` - `"agent_toolset_20260401"` - `BetaManagedAgentsMCPToolset` - `configs: Array` - `enabled: boolean` - `name: string` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` Resolved default configuration for all tools from an MCP server. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `mcp_server_name: string` - `type: "mcp_toolset"` - `"mcp_toolset"` - `BetaManagedAgentsCustomTool` A custom tool as returned in API responses. - `description: string` - `input_schema: BetaManagedAgentsCustomToolInputSchema` JSON Schema for custom tool input parameters. - `properties?: Record | null` JSON Schema properties defining the tool's input parameters. - `required?: Array` List of required property names. - `type?: "object"` Must be 'object' for tool input schemas. - `"object"` - `name: string` - `type: "custom"` - `"custom"` - `type: "agent"` - `"agent"` - `version: number` - `type: "coordinator"` - `"coordinator"` - `name: string` - `skills: Array` - `BetaManagedAgentsAnthropicSkill` A resolved Anthropic-managed skill. - `BetaManagedAgentsCustomSkill` A resolved user-created custom skill. - `system: string | null` - `tools: Array` - `BetaManagedAgentsAgentToolset20260401` - `BetaManagedAgentsMCPToolset` - `BetaManagedAgentsCustomTool` A custom tool as returned in API responses. - `type: "agent"` - `"agent"` - `version: number` - `metadata?: Record` The session's full metadata bag after the update. Present when the update set non-empty metadata; absent when metadata was unchanged or cleared to empty. - `title?: string | null` The session's new title. Present only when the update changed it. ### Beta Managed Agents Session Requires Action - `BetaManagedAgentsSessionRequiresAction` The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. - `event_ids: Array` The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. - `type: "requires_action"` - `"requires_action"` ### Beta Managed Agents Session Retries Exhausted - `BetaManagedAgentsSessionRetriesExhausted` The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). - `type: "retries_exhausted"` - `"retries_exhausted"` ### Beta Managed Agents Session Status Idle Event - `BetaManagedAgentsSessionStatusIdleEvent` Indicates the agent has paused and is awaiting user input. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `stop_reason: BetaManagedAgentsSessionEndTurn | BetaManagedAgentsSessionRequiresAction | BetaManagedAgentsSessionRetriesExhausted` The agent completed its turn naturally and is ready for the next user message. - `BetaManagedAgentsSessionEndTurn` The agent completed its turn naturally and is ready for the next user message. - `type: "end_turn"` - `"end_turn"` - `BetaManagedAgentsSessionRequiresAction` The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. - `event_ids: Array` The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. - `type: "requires_action"` - `"requires_action"` - `BetaManagedAgentsSessionRetriesExhausted` The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). - `type: "retries_exhausted"` - `"retries_exhausted"` - `type: "session.status_idle"` - `"session.status_idle"` ### Beta Managed Agents Session Status Rescheduled Event - `BetaManagedAgentsSessionStatusRescheduledEvent` Indicates the session is recovering from an error state and is rescheduled for execution. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `type: "session.status_rescheduled"` - `"session.status_rescheduled"` ### Beta Managed Agents Session Status Running Event - `BetaManagedAgentsSessionStatusRunningEvent` Indicates the session is actively running and the agent is working. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `type: "session.status_running"` - `"session.status_running"` ### Beta Managed Agents Session Status Terminated Event - `BetaManagedAgentsSessionStatusTerminatedEvent` Indicates the session has terminated, either due to an error or completion. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `type: "session.status_terminated"` - `"session.status_terminated"` ### Beta Managed Agents Session Thread Created Event - `BetaManagedAgentsSessionThreadCreatedEvent` Emitted when a subagent is spawned as a new thread. Written to the parent thread's output stream so clients observing the session see child creation. - `id: string` Unique identifier for this event. - `agent_name: string` Name of the callable agent the thread runs. - `processed_at: string` A timestamp in RFC 3339 format - `session_thread_id: string` Public `sthr_` ID of the newly created thread. - `type: "session.thread_created"` - `"session.thread_created"` ### Beta Managed Agents Session Thread Status Idle Event - `BetaManagedAgentsSessionThreadStatusIdleEvent` A session thread has yielded and is awaiting input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads. - `id: string` Unique identifier for this event. - `agent_name: string` Name of the agent the thread runs. - `processed_at: string` A timestamp in RFC 3339 format - `session_thread_id: string` Public sthr_ ID of the thread that went idle. - `stop_reason: BetaManagedAgentsSessionEndTurn | BetaManagedAgentsSessionRequiresAction | BetaManagedAgentsSessionRetriesExhausted` The agent completed its turn naturally and is ready for the next user message. - `BetaManagedAgentsSessionEndTurn` The agent completed its turn naturally and is ready for the next user message. - `type: "end_turn"` - `"end_turn"` - `BetaManagedAgentsSessionRequiresAction` The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. - `event_ids: Array` The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. - `type: "requires_action"` - `"requires_action"` - `BetaManagedAgentsSessionRetriesExhausted` The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). - `type: "retries_exhausted"` - `"retries_exhausted"` - `type: "session.thread_status_idle"` - `"session.thread_status_idle"` ### Beta Managed Agents Session Thread Status Rescheduled Event - `BetaManagedAgentsSessionThreadStatusRescheduledEvent` A session thread hit a transient error and is retrying automatically. Emitted on the thread's own stream and cross-posted to the primary stream for child threads. - `id: string` Unique identifier for this event. - `agent_name: string` Name of the agent the thread runs. - `processed_at: string` A timestamp in RFC 3339 format - `session_thread_id: string` Public sthr_ ID of the thread that is retrying. - `type: "session.thread_status_rescheduled"` - `"session.thread_status_rescheduled"` ### Beta Managed Agents Session Thread Status Running Event - `BetaManagedAgentsSessionThreadStatusRunningEvent` A session thread has begun executing. Emitted on the thread's own stream and cross-posted to the primary stream for child threads. - `id: string` Unique identifier for this event. - `agent_name: string` Name of the agent the thread runs. - `processed_at: string` A timestamp in RFC 3339 format - `session_thread_id: string` Public sthr_ ID of the thread that started running. - `type: "session.thread_status_running"` - `"session.thread_status_running"` ### Beta Managed Agents Session Thread Status Terminated Event - `BetaManagedAgentsSessionThreadStatusTerminatedEvent` A session thread has terminated and will accept no further input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads. - `id: string` Unique identifier for this event. - `agent_name: string` Name of the agent the thread runs. - `processed_at: string` A timestamp in RFC 3339 format - `session_thread_id: string` Public sthr_ ID of the thread that terminated. - `type: "session.thread_status_terminated"` - `"session.thread_status_terminated"` ### Beta Managed Agents Span Model Request End Event - `BetaManagedAgentsSpanModelRequestEndEvent` Emitted when a model request completes. - `id: string` Unique identifier for this event. - `is_error: boolean | null` Whether the model request resulted in an error. - `model_request_start_id: string` The id of the corresponding `span.model_request_start` event. - `model_usage: BetaManagedAgentsSpanModelUsage` Token usage for a single model request. - `cache_creation_input_tokens: number` Tokens used to create prompt cache in this request. - `cache_read_input_tokens: number` Tokens read from prompt cache in this request. - `input_tokens: number` Input tokens consumed by this request. - `output_tokens: number` Output tokens generated by this request. - `speed?: "standard" | "fast" | null` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `processed_at: string` A timestamp in RFC 3339 format - `type: "span.model_request_end"` - `"span.model_request_end"` ### Beta Managed Agents Span Model Request Start Event - `BetaManagedAgentsSpanModelRequestStartEvent` Emitted when a model request is initiated by the agent. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `type: "span.model_request_start"` - `"span.model_request_start"` ### Beta Managed Agents Span Model Usage - `BetaManagedAgentsSpanModelUsage` Token usage for a single model request. - `cache_creation_input_tokens: number` Tokens used to create prompt cache in this request. - `cache_read_input_tokens: number` Tokens read from prompt cache in this request. - `input_tokens: number` Input tokens consumed by this request. - `output_tokens: number` Output tokens generated by this request. - `speed?: "standard" | "fast" | null` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` ### Beta Managed Agents Span Outcome Evaluation End Event - `BetaManagedAgentsSpanOutcomeEvaluationEndEvent` Emitted when an outcome evaluation cycle completes. Carries the verdict and aggregate token usage. A verdict of `needs_revision` means another evaluation cycle follows; `satisfied`, `max_iterations_reached`, `failed`, or `interrupted` are terminal — no further evaluation cycles follow. - `id: string` Unique identifier for this event. - `explanation: string` Human-readable explanation of the verdict. For `needs_revision`, describes which criteria failed and why. - `iteration: number` 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`. - `outcome_evaluation_start_id: string` The id of the corresponding `span.outcome_evaluation_start` event. - `outcome_id: string` The `outc_` ID of the outcome being evaluated. - `processed_at: string` A timestamp in RFC 3339 format - `result: string` Evaluation verdict. 'satisfied': criteria met, session goes idle. 'needs_revision': criteria not met, another revision cycle follows. 'max_iterations_reached': evaluation budget exhausted with criteria still unmet — one final acknowledgment turn follows before the session goes idle, but no further evaluation runs. 'failed': grader determined the rubric does not apply to the deliverables. 'interrupted': user sent an interrupt while evaluation was in progress. - `type: "span.outcome_evaluation_end"` - `"span.outcome_evaluation_end"` - `usage: BetaManagedAgentsSpanModelUsage` Token usage for a single model request. - `cache_creation_input_tokens: number` Tokens used to create prompt cache in this request. - `cache_read_input_tokens: number` Tokens read from prompt cache in this request. - `input_tokens: number` Input tokens consumed by this request. - `output_tokens: number` Output tokens generated by this request. - `speed?: "standard" | "fast" | null` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` ### Beta Managed Agents Span Outcome Evaluation Ongoing Event - `BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent` Periodic heartbeat emitted while an outcome evaluation cycle is in progress. Distinguishes 'evaluation is actively running' from 'evaluation is stuck' between the corresponding `span.outcome_evaluation_start` and `span.outcome_evaluation_end` events. - `id: string` Unique identifier for this event. - `iteration: number` 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`. - `outcome_id: string` The `outc_` ID of the outcome being evaluated. - `processed_at: string` A timestamp in RFC 3339 format - `type: "span.outcome_evaluation_ongoing"` - `"span.outcome_evaluation_ongoing"` ### Beta Managed Agents Span Outcome Evaluation Start Event - `BetaManagedAgentsSpanOutcomeEvaluationStartEvent` Emitted when an outcome evaluation cycle begins. - `id: string` Unique identifier for this event. - `iteration: number` 0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc. - `outcome_id: string` The `outc_` ID of the outcome being evaluated. - `processed_at: string` A timestamp in RFC 3339 format - `type: "span.outcome_evaluation_start"` - `"span.outcome_evaluation_start"` ### Beta Managed Agents Stream Session Events - `BetaManagedAgentsStreamSessionEvents = BetaManagedAgentsUserMessageEvent | BetaManagedAgentsUserInterruptEvent | BetaManagedAgentsUserToolConfirmationEvent | 30 more` Server-sent event in the session stream. - `BetaManagedAgentsUserMessageEvent` A user message event in the session conversation. - `id: string` Unique identifier for this event. - `content: Array` Array of content blocks comprising the user message. - `BetaManagedAgentsTextBlock` Regular text content. - `text: string` The text content. - `type: "text"` - `"text"` - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` Union type for image source variants. - `BetaManagedAgentsBase64ImageSource` Base64-encoded image data. - `data: string` Base64-encoded image data. - `media_type: string` MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). - `type: "base64"` - `"base64"` - `BetaManagedAgentsURLImageSource` Image referenced by URL. - `type: "url"` - `"url"` - `url: string` URL of the image to fetch. - `BetaManagedAgentsFileImageSource` Image referenced by file ID. - `file_id: string` ID of a previously uploaded file. - `type: "file"` - `"file"` - `type: "image"` - `"image"` - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` Union type for document source variants. - `BetaManagedAgentsBase64DocumentSource` Base64-encoded document data. - `data: string` Base64-encoded document data. - `media_type: string` MIME type of the document (e.g., "application/pdf"). - `type: "base64"` - `"base64"` - `BetaManagedAgentsPlainTextDocumentSource` Plain text document content. - `data: string` The plain text content. - `media_type: "text/plain"` MIME type of the text content. Must be "text/plain". - `"text/plain"` - `type: "text"` - `"text"` - `BetaManagedAgentsURLDocumentSource` Document referenced by URL. - `type: "url"` - `"url"` - `url: string` URL of the document to fetch. - `BetaManagedAgentsFileDocumentSource` Document referenced by file ID. - `file_id: string` ID of a previously uploaded file. - `type: "file"` - `"file"` - `type: "document"` - `"document"` - `context?: string | null` Additional context about the document for the model. - `title?: string | null` The title of the document. - `type: "user.message"` - `"user.message"` - `processed_at?: string | null` A timestamp in RFC 3339 format - `BetaManagedAgentsUserInterruptEvent` An interrupt event that pauses agent execution and returns control to the user. - `id: string` Unique identifier for this event. - `type: "user.interrupt"` - `"user.interrupt"` - `processed_at?: string | null` A timestamp in RFC 3339 format - `session_thread_id?: string | null` If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread. - `BetaManagedAgentsUserToolConfirmationEvent` A tool confirmation event that approves or denies a pending tool execution. - `id: string` Unique identifier for this event. - `result: "allow" | "deny"` UserToolConfirmationResult enum - `"allow"` - `"deny"` - `tool_use_id: string` The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `type: "user.tool_confirmation"` - `"user.tool_confirmation"` - `deny_message?: string | null` Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. - `processed_at?: string | null` A timestamp in RFC 3339 format - `session_thread_id?: string | null` When set, the confirmation routes to this subagent's thread rather than the primary. Echo this from the `session_thread_id` on the `agent.tool_use` or `agent.mcp_tool_use` event that prompted the approval. - `BetaManagedAgentsUserCustomToolResultEvent` Event sent by the client providing the result of a custom tool execution. - `id: string` Unique identifier for this event. - `custom_tool_use_id: string` The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `type: "user.custom_tool_result"` - `"user.custom_tool_result"` - `content?: Array` The result content returned by the tool. - `BetaManagedAgentsTextBlock` Regular text content. - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `BetaManagedAgentsSearchResultBlock` A block containing a web search result. - `citations: BetaManagedAgentsSearchResultCitations` Citation settings for a search result. - `enabled: boolean` Whether citations are enabled for this search result. - `content: Array` Array of text content blocks from the search result. - `text: string` The text content. - `type: "text"` - `"text"` - `source: string` The URL source of the search result. - `title: string` The title of the search result. - `type: "search_result"` - `"search_result"` - `is_error?: boolean | null` Whether the tool execution resulted in an error. - `processed_at?: string | null` A timestamp in RFC 3339 format - `session_thread_id?: string | null` Routes this result to a subagent thread. Copy from the `agent.custom_tool_use` event's `session_thread_id`. - `BetaManagedAgentsAgentCustomToolUseEvent` Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. - `id: string` Unique identifier for this event. - `input: Record` Input parameters for the tool call. - `name: string` Name of the custom tool being called. - `processed_at: string` A timestamp in RFC 3339 format - `type: "agent.custom_tool_use"` - `"agent.custom_tool_use"` - `session_thread_id?: string | null` When set, this event was cross-posted from a subagent's thread to surface its custom tool use on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.custom_tool_result` event to route the result back. - `BetaManagedAgentsAgentMessageEvent` An agent response event in the session conversation. - `id: string` Unique identifier for this event. - `content: Array` Array of text blocks comprising the agent response. - `text: string` The text content. - `type: "text"` - `processed_at: string` A timestamp in RFC 3339 format - `type: "agent.message"` - `"agent.message"` - `BetaManagedAgentsAgentThinkingEvent` Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `type: "agent.thinking"` - `"agent.thinking"` - `BetaManagedAgentsAgentMCPToolUseEvent` Event emitted when the agent invokes a tool provided by an MCP server. - `id: string` Unique identifier for this event. - `input: Record` Input parameters for the tool call. - `mcp_server_name: string` Name of the MCP server providing the tool. - `name: string` Name of the MCP tool being used. - `processed_at: string` A timestamp in RFC 3339 format - `type: "agent.mcp_tool_use"` - `"agent.mcp_tool_use"` - `evaluated_permission?: "allow" | "ask" | "deny"` AgentEvaluatedPermission enum - `"allow"` - `"ask"` - `"deny"` - `session_thread_id?: string | null` When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.tool_confirmation` event to route the approval back. - `BetaManagedAgentsAgentMCPToolResultEvent` Event representing the result of an MCP tool execution. - `id: string` Unique identifier for this event. - `mcp_tool_use_id: string` The id of the `agent.mcp_tool_use` event this result corresponds to. - `processed_at: string` A timestamp in RFC 3339 format - `type: "agent.mcp_tool_result"` - `"agent.mcp_tool_result"` - `content?: Array` The result content returned by the tool. - `BetaManagedAgentsTextBlock` Regular text content. - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `BetaManagedAgentsSearchResultBlock` A block containing a web search result. - `is_error?: boolean | null` Whether the tool execution resulted in an error. - `BetaManagedAgentsAgentToolUseEvent` Event emitted when the agent invokes a built-in agent tool. - `id: string` Unique identifier for this event. - `input: Record` Input parameters for the tool call. - `name: string` Name of the agent tool being used. - `processed_at: string` A timestamp in RFC 3339 format - `type: "agent.tool_use"` - `"agent.tool_use"` - `evaluated_permission?: "allow" | "ask" | "deny"` AgentEvaluatedPermission enum - `"allow"` - `"ask"` - `"deny"` - `session_thread_id?: string | null` When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.tool_confirmation` event to route the approval back. - `BetaManagedAgentsAgentToolResultEvent` Event representing the result of an agent tool execution. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `tool_use_id: string` The id of the `agent.tool_use` event this result corresponds to. - `type: "agent.tool_result"` - `"agent.tool_result"` - `content?: Array` The result content returned by the tool. - `BetaManagedAgentsTextBlock` Regular text content. - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `BetaManagedAgentsSearchResultBlock` A block containing a web search result. - `is_error?: boolean | null` Whether the tool execution resulted in an error. - `BetaManagedAgentsAgentThreadMessageReceivedEvent` Delivery event written to the target thread's input stream when an agent-to-agent message arrives. - `id: string` Unique identifier for this event. - `content: Array` Message content blocks. - `BetaManagedAgentsTextBlock` Regular text content. - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `from_session_thread_id: string` Public `sthr_` ID of the thread that sent the message. - `processed_at: string` A timestamp in RFC 3339 format - `type: "agent.thread_message_received"` - `"agent.thread_message_received"` - `from_agent_name?: string | null` Name of the callable agent this message came from. Absent when received from the primary agent. - `BetaManagedAgentsAgentThreadMessageSentEvent` Observability event emitted to the sender's output stream when an agent-to-agent message is sent. - `id: string` Unique identifier for this event. - `content: Array` Message content blocks. - `BetaManagedAgentsTextBlock` Regular text content. - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `processed_at: string` A timestamp in RFC 3339 format - `to_session_thread_id: string` Public `sthr_` ID of the thread the message was sent to. - `type: "agent.thread_message_sent"` - `"agent.thread_message_sent"` - `to_agent_name?: string | null` Name of the callable agent this message was sent to. Absent when sent to the primary agent. - `BetaManagedAgentsAgentThreadContextCompactedEvent` Indicates that context compaction (summarization) occurred during the session. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `type: "agent.thread_context_compacted"` - `"agent.thread_context_compacted"` - `BetaManagedAgentsSessionErrorEvent` An error event indicating a problem occurred during session execution. - `id: string` Unique identifier for this event. - `error: BetaManagedAgentsUnknownError | BetaManagedAgentsModelOverloadedError | BetaManagedAgentsModelRateLimitedError | 4 more` An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. - `BetaManagedAgentsUnknownError` An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` What the client should do next in response to this error. - `BetaManagedAgentsRetryStatusRetrying` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `type: "retrying"` - `"retrying"` - `BetaManagedAgentsRetryStatusExhausted` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `type: "exhausted"` - `"exhausted"` - `BetaManagedAgentsRetryStatusTerminal` The session encountered a terminal error and will transition to `terminated` state. - `type: "terminal"` - `"terminal"` - `type: "unknown_error"` - `"unknown_error"` - `BetaManagedAgentsModelOverloadedError` The model is currently overloaded. Emitted after automatic retries are exhausted. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` What the client should do next in response to this error. - `BetaManagedAgentsRetryStatusRetrying` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal` The session encountered a terminal error and will transition to `terminated` state. - `type: "model_overloaded_error"` - `"model_overloaded_error"` - `BetaManagedAgentsModelRateLimitedError` The model request was rate-limited. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` What the client should do next in response to this error. - `BetaManagedAgentsRetryStatusRetrying` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal` The session encountered a terminal error and will transition to `terminated` state. - `type: "model_rate_limited_error"` - `"model_rate_limited_error"` - `BetaManagedAgentsModelRequestFailedError` A model request failed for a reason other than overload or rate-limiting. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` What the client should do next in response to this error. - `BetaManagedAgentsRetryStatusRetrying` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal` The session encountered a terminal error and will transition to `terminated` state. - `type: "model_request_failed_error"` - `"model_request_failed_error"` - `BetaManagedAgentsMCPConnectionFailedError` Failed to connect to an MCP server. - `mcp_server_name: string` Name of the MCP server that failed to connect. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` What the client should do next in response to this error. - `BetaManagedAgentsRetryStatusRetrying` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal` The session encountered a terminal error and will transition to `terminated` state. - `type: "mcp_connection_failed_error"` - `"mcp_connection_failed_error"` - `BetaManagedAgentsMCPAuthenticationFailedError` Authentication to an MCP server failed. - `mcp_server_name: string` Name of the MCP server that failed authentication. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` What the client should do next in response to this error. - `BetaManagedAgentsRetryStatusRetrying` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal` The session encountered a terminal error and will transition to `terminated` state. - `type: "mcp_authentication_failed_error"` - `"mcp_authentication_failed_error"` - `BetaManagedAgentsBillingError` The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` What the client should do next in response to this error. - `BetaManagedAgentsRetryStatusRetrying` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal` The session encountered a terminal error and will transition to `terminated` state. - `type: "billing_error"` - `"billing_error"` - `processed_at: string` A timestamp in RFC 3339 format - `type: "session.error"` - `"session.error"` - `BetaManagedAgentsSessionStatusRescheduledEvent` Indicates the session is recovering from an error state and is rescheduled for execution. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `type: "session.status_rescheduled"` - `"session.status_rescheduled"` - `BetaManagedAgentsSessionStatusRunningEvent` Indicates the session is actively running and the agent is working. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `type: "session.status_running"` - `"session.status_running"` - `BetaManagedAgentsSessionStatusIdleEvent` Indicates the agent has paused and is awaiting user input. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `stop_reason: BetaManagedAgentsSessionEndTurn | BetaManagedAgentsSessionRequiresAction | BetaManagedAgentsSessionRetriesExhausted` The agent completed its turn naturally and is ready for the next user message. - `BetaManagedAgentsSessionEndTurn` The agent completed its turn naturally and is ready for the next user message. - `type: "end_turn"` - `"end_turn"` - `BetaManagedAgentsSessionRequiresAction` The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. - `event_ids: Array` The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. - `type: "requires_action"` - `"requires_action"` - `BetaManagedAgentsSessionRetriesExhausted` The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). - `type: "retries_exhausted"` - `"retries_exhausted"` - `type: "session.status_idle"` - `"session.status_idle"` - `BetaManagedAgentsSessionStatusTerminatedEvent` Indicates the session has terminated, either due to an error or completion. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `type: "session.status_terminated"` - `"session.status_terminated"` - `BetaManagedAgentsSessionThreadCreatedEvent` Emitted when a subagent is spawned as a new thread. Written to the parent thread's output stream so clients observing the session see child creation. - `id: string` Unique identifier for this event. - `agent_name: string` Name of the callable agent the thread runs. - `processed_at: string` A timestamp in RFC 3339 format - `session_thread_id: string` Public `sthr_` ID of the newly created thread. - `type: "session.thread_created"` - `"session.thread_created"` - `BetaManagedAgentsSpanOutcomeEvaluationStartEvent` Emitted when an outcome evaluation cycle begins. - `id: string` Unique identifier for this event. - `iteration: number` 0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc. - `outcome_id: string` The `outc_` ID of the outcome being evaluated. - `processed_at: string` A timestamp in RFC 3339 format - `type: "span.outcome_evaluation_start"` - `"span.outcome_evaluation_start"` - `BetaManagedAgentsSpanOutcomeEvaluationEndEvent` Emitted when an outcome evaluation cycle completes. Carries the verdict and aggregate token usage. A verdict of `needs_revision` means another evaluation cycle follows; `satisfied`, `max_iterations_reached`, `failed`, or `interrupted` are terminal — no further evaluation cycles follow. - `id: string` Unique identifier for this event. - `explanation: string` Human-readable explanation of the verdict. For `needs_revision`, describes which criteria failed and why. - `iteration: number` 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`. - `outcome_evaluation_start_id: string` The id of the corresponding `span.outcome_evaluation_start` event. - `outcome_id: string` The `outc_` ID of the outcome being evaluated. - `processed_at: string` A timestamp in RFC 3339 format - `result: string` Evaluation verdict. 'satisfied': criteria met, session goes idle. 'needs_revision': criteria not met, another revision cycle follows. 'max_iterations_reached': evaluation budget exhausted with criteria still unmet — one final acknowledgment turn follows before the session goes idle, but no further evaluation runs. 'failed': grader determined the rubric does not apply to the deliverables. 'interrupted': user sent an interrupt while evaluation was in progress. - `type: "span.outcome_evaluation_end"` - `"span.outcome_evaluation_end"` - `usage: BetaManagedAgentsSpanModelUsage` Token usage for a single model request. - `cache_creation_input_tokens: number` Tokens used to create prompt cache in this request. - `cache_read_input_tokens: number` Tokens read from prompt cache in this request. - `input_tokens: number` Input tokens consumed by this request. - `output_tokens: number` Output tokens generated by this request. - `speed?: "standard" | "fast" | null` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `BetaManagedAgentsSpanModelRequestStartEvent` Emitted when a model request is initiated by the agent. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `type: "span.model_request_start"` - `"span.model_request_start"` - `BetaManagedAgentsSpanModelRequestEndEvent` Emitted when a model request completes. - `id: string` Unique identifier for this event. - `is_error: boolean | null` Whether the model request resulted in an error. - `model_request_start_id: string` The id of the corresponding `span.model_request_start` event. - `model_usage: BetaManagedAgentsSpanModelUsage` Token usage for a single model request. - `processed_at: string` A timestamp in RFC 3339 format - `type: "span.model_request_end"` - `"span.model_request_end"` - `BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent` Periodic heartbeat emitted while an outcome evaluation cycle is in progress. Distinguishes 'evaluation is actively running' from 'evaluation is stuck' between the corresponding `span.outcome_evaluation_start` and `span.outcome_evaluation_end` events. - `id: string` Unique identifier for this event. - `iteration: number` 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`. - `outcome_id: string` The `outc_` ID of the outcome being evaluated. - `processed_at: string` A timestamp in RFC 3339 format - `type: "span.outcome_evaluation_ongoing"` - `"span.outcome_evaluation_ongoing"` - `BetaManagedAgentsUserDefineOutcomeEvent` Echo of a `user.define_outcome` input event. Carries the server-generated `outcome_id` that subsequent `span.outcome_evaluation_*` events reference. - `id: string` Unique identifier for this event. - `description: string` What the agent should produce. Copied from the input event. - `max_iterations: number | null` Evaluate-then-revise cycles before giving up. Default 3, max 20. - `outcome_id: string` Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list. - `processed_at: string` A timestamp in RFC 3339 format - `rubric: BetaManagedAgentsFileRubric | BetaManagedAgentsTextRubric` Rubric for grading the quality of an outcome. - `BetaManagedAgentsFileRubric` Rubric referenced by a file uploaded via the Files API. - `file_id: string` ID of the rubric file. - `type: "file"` - `"file"` - `BetaManagedAgentsTextRubric` Rubric content provided inline as text. - `content: string` Rubric content. Plain text or markdown — the grader treats it as freeform text. - `type: "text"` - `"text"` - `type: "user.define_outcome"` - `"user.define_outcome"` - `BetaManagedAgentsSessionDeletedEvent` Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `type: "session.deleted"` - `"session.deleted"` - `BetaManagedAgentsSessionThreadStatusRunningEvent` A session thread has begun executing. Emitted on the thread's own stream and cross-posted to the primary stream for child threads. - `id: string` Unique identifier for this event. - `agent_name: string` Name of the agent the thread runs. - `processed_at: string` A timestamp in RFC 3339 format - `session_thread_id: string` Public sthr_ ID of the thread that started running. - `type: "session.thread_status_running"` - `"session.thread_status_running"` - `BetaManagedAgentsSessionThreadStatusIdleEvent` A session thread has yielded and is awaiting input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads. - `id: string` Unique identifier for this event. - `agent_name: string` Name of the agent the thread runs. - `processed_at: string` A timestamp in RFC 3339 format - `session_thread_id: string` Public sthr_ ID of the thread that went idle. - `stop_reason: BetaManagedAgentsSessionEndTurn | BetaManagedAgentsSessionRequiresAction | BetaManagedAgentsSessionRetriesExhausted` The agent completed its turn naturally and is ready for the next user message. - `BetaManagedAgentsSessionEndTurn` The agent completed its turn naturally and is ready for the next user message. - `BetaManagedAgentsSessionRequiresAction` The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. - `BetaManagedAgentsSessionRetriesExhausted` The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). - `type: "session.thread_status_idle"` - `"session.thread_status_idle"` - `BetaManagedAgentsSessionThreadStatusTerminatedEvent` A session thread has terminated and will accept no further input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads. - `id: string` Unique identifier for this event. - `agent_name: string` Name of the agent the thread runs. - `processed_at: string` A timestamp in RFC 3339 format - `session_thread_id: string` Public sthr_ ID of the thread that terminated. - `type: "session.thread_status_terminated"` - `"session.thread_status_terminated"` - `BetaManagedAgentsUserToolResultEvent` Event sent by the client providing the result of an agent-toolset tool execution. Only valid on `self_hosted` environments, where sandbox-routed tools are executed by the client rather than the server. - `id: string` Unique identifier for this event. - `tool_use_id: string` The id of the `agent.tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `type: "user.tool_result"` - `"user.tool_result"` - `content?: Array` The result content returned by the tool. - `BetaManagedAgentsTextBlock` Regular text content. - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `BetaManagedAgentsSearchResultBlock` A block containing a web search result. - `is_error?: boolean | null` Whether the tool execution resulted in an error. - `processed_at?: string | null` A timestamp in RFC 3339 format - `session_thread_id?: string | null` Routes this result to a subagent thread. Copy from the `agent.tool_use` event's `session_thread_id`. - `BetaManagedAgentsSessionThreadStatusRescheduledEvent` A session thread hit a transient error and is retrying automatically. Emitted on the thread's own stream and cross-posted to the primary stream for child threads. - `id: string` Unique identifier for this event. - `agent_name: string` Name of the agent the thread runs. - `processed_at: string` A timestamp in RFC 3339 format - `session_thread_id: string` Public sthr_ ID of the thread that is retrying. - `type: "session.thread_status_rescheduled"` - `"session.thread_status_rescheduled"` - `BetaManagedAgentsSessionUpdatedEvent` Emitted when an UpdateSession request changed at least one field. Carries only the fields that changed; absent fields were not part of the update. The new configuration applies from the next turn. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `type: "session.updated"` - `"session.updated"` - `agent?: BetaManagedAgentsSessionAgent | null` Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. - `id: string` - `description: string | null` - `mcp_servers: Array` - `name: string` - `type: "url"` - `"url"` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `id: BetaManagedAgentsModel` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-opus-4-8" | "claude-opus-4-7" | "claude-opus-4-6" | 7 more` - `"claude-opus-4-8"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-7"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-6"` Most intelligent model for building agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` Fastest model with near-frontier intelligence - `"claude-haiku-4-5-20251001"` Fastest model with near-frontier intelligence - `"claude-opus-4-5"` Premium model combining maximum intelligence with practical performance - `"claude-opus-4-5-20251101"` Premium model combining maximum intelligence with practical performance - `"claude-sonnet-4-5"` High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` High-performance model for agents and coding - `(string & {})` - `speed?: "standard" | "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `multiagent: BetaManagedAgentsSessionMultiagentCoordinator | null` Resolved coordinator topology with full agent definitions for each roster member. - `agents: Array` Full `agent` definitions the coordinator may spawn as session threads. - `id: string` - `description: string | null` - `mcp_servers: Array` - `name: string` - `type: "url"` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `name: string` - `skills: Array` - `BetaManagedAgentsAnthropicSkill` A resolved Anthropic-managed skill. - `skill_id: string` - `type: "anthropic"` - `"anthropic"` - `version: string` - `BetaManagedAgentsCustomSkill` A resolved user-created custom skill. - `skill_id: string` - `type: "custom"` - `"custom"` - `version: string` - `system: string | null` - `tools: Array` - `BetaManagedAgentsAgentToolset20260401` - `configs: Array` - `enabled: boolean` - `name: "bash" | "edit" | "read" | 5 more` Built-in agent tool identifier. - `"bash"` - `"edit"` - `"read"` - `"write"` - `"glob"` - `"grep"` - `"web_fetch"` - `"web_search"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `"always_allow"` - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "always_ask"` - `"always_ask"` - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` Resolved default configuration for agent tools. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "agent_toolset_20260401"` - `"agent_toolset_20260401"` - `BetaManagedAgentsMCPToolset` - `configs: Array` - `enabled: boolean` - `name: string` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` Resolved default configuration for all tools from an MCP server. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `mcp_server_name: string` - `type: "mcp_toolset"` - `"mcp_toolset"` - `BetaManagedAgentsCustomTool` A custom tool as returned in API responses. - `description: string` - `input_schema: BetaManagedAgentsCustomToolInputSchema` JSON Schema for custom tool input parameters. - `properties?: Record | null` JSON Schema properties defining the tool's input parameters. - `required?: Array` List of required property names. - `type?: "object"` Must be 'object' for tool input schemas. - `"object"` - `name: string` - `type: "custom"` - `"custom"` - `type: "agent"` - `"agent"` - `version: number` - `type: "coordinator"` - `"coordinator"` - `name: string` - `skills: Array` - `BetaManagedAgentsAnthropicSkill` A resolved Anthropic-managed skill. - `BetaManagedAgentsCustomSkill` A resolved user-created custom skill. - `system: string | null` - `tools: Array` - `BetaManagedAgentsAgentToolset20260401` - `BetaManagedAgentsMCPToolset` - `BetaManagedAgentsCustomTool` A custom tool as returned in API responses. - `type: "agent"` - `"agent"` - `version: number` - `metadata?: Record` The session's full metadata bag after the update. Present when the update set non-empty metadata; absent when metadata was unchanged or cleared to empty. - `title?: string | null` The session's new title. Present only when the update changed it. ### Beta Managed Agents Text Block - `BetaManagedAgentsTextBlock` Regular text content. - `text: string` The text content. - `type: "text"` - `"text"` ### Beta Managed Agents Text Rubric - `BetaManagedAgentsTextRubric` Rubric content provided inline as text. - `content: string` Rubric content. Plain text or markdown — the grader treats it as freeform text. - `type: "text"` - `"text"` ### Beta Managed Agents Text Rubric Params - `BetaManagedAgentsTextRubricParams` Rubric content provided inline as text. - `content: string` Rubric content. Plain text or markdown — the grader treats it as freeform text. Maximum 262144 characters. - `type: "text"` - `"text"` ### Beta Managed Agents Unknown Error - `BetaManagedAgentsUnknownError` An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` What the client should do next in response to this error. - `BetaManagedAgentsRetryStatusRetrying` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `type: "retrying"` - `"retrying"` - `BetaManagedAgentsRetryStatusExhausted` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `type: "exhausted"` - `"exhausted"` - `BetaManagedAgentsRetryStatusTerminal` The session encountered a terminal error and will transition to `terminated` state. - `type: "terminal"` - `"terminal"` - `type: "unknown_error"` - `"unknown_error"` ### Beta Managed Agents URL Document Source - `BetaManagedAgentsURLDocumentSource` Document referenced by URL. - `type: "url"` - `"url"` - `url: string` URL of the document to fetch. ### Beta Managed Agents URL Image Source - `BetaManagedAgentsURLImageSource` Image referenced by URL. - `type: "url"` - `"url"` - `url: string` URL of the image to fetch. ### Beta Managed Agents User Custom Tool Result Event - `BetaManagedAgentsUserCustomToolResultEvent` Event sent by the client providing the result of a custom tool execution. - `id: string` Unique identifier for this event. - `custom_tool_use_id: string` The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `type: "user.custom_tool_result"` - `"user.custom_tool_result"` - `content?: Array` The result content returned by the tool. - `BetaManagedAgentsTextBlock` Regular text content. - `text: string` The text content. - `type: "text"` - `"text"` - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` Union type for image source variants. - `BetaManagedAgentsBase64ImageSource` Base64-encoded image data. - `data: string` Base64-encoded image data. - `media_type: string` MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). - `type: "base64"` - `"base64"` - `BetaManagedAgentsURLImageSource` Image referenced by URL. - `type: "url"` - `"url"` - `url: string` URL of the image to fetch. - `BetaManagedAgentsFileImageSource` Image referenced by file ID. - `file_id: string` ID of a previously uploaded file. - `type: "file"` - `"file"` - `type: "image"` - `"image"` - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` Union type for document source variants. - `BetaManagedAgentsBase64DocumentSource` Base64-encoded document data. - `data: string` Base64-encoded document data. - `media_type: string` MIME type of the document (e.g., "application/pdf"). - `type: "base64"` - `"base64"` - `BetaManagedAgentsPlainTextDocumentSource` Plain text document content. - `data: string` The plain text content. - `media_type: "text/plain"` MIME type of the text content. Must be "text/plain". - `"text/plain"` - `type: "text"` - `"text"` - `BetaManagedAgentsURLDocumentSource` Document referenced by URL. - `type: "url"` - `"url"` - `url: string` URL of the document to fetch. - `BetaManagedAgentsFileDocumentSource` Document referenced by file ID. - `file_id: string` ID of a previously uploaded file. - `type: "file"` - `"file"` - `type: "document"` - `"document"` - `context?: string | null` Additional context about the document for the model. - `title?: string | null` The title of the document. - `BetaManagedAgentsSearchResultBlock` A block containing a web search result. - `citations: BetaManagedAgentsSearchResultCitations` Citation settings for a search result. - `enabled: boolean` Whether citations are enabled for this search result. - `content: Array` Array of text content blocks from the search result. - `text: string` The text content. - `type: "text"` - `"text"` - `source: string` The URL source of the search result. - `title: string` The title of the search result. - `type: "search_result"` - `"search_result"` - `is_error?: boolean | null` Whether the tool execution resulted in an error. - `processed_at?: string | null` A timestamp in RFC 3339 format - `session_thread_id?: string | null` Routes this result to a subagent thread. Copy from the `agent.custom_tool_use` event's `session_thread_id`. ### Beta Managed Agents User Custom Tool Result Event Params - `BetaManagedAgentsUserCustomToolResultEventParams` Parameters for providing the result of a custom tool execution. - `custom_tool_use_id: string` The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `type: "user.custom_tool_result"` - `"user.custom_tool_result"` - `content?: Array` The result content returned by the tool. - `BetaManagedAgentsTextBlock` Regular text content. - `text: string` The text content. - `type: "text"` - `"text"` - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` Union type for image source variants. - `BetaManagedAgentsBase64ImageSource` Base64-encoded image data. - `data: string` Base64-encoded image data. - `media_type: string` MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). - `type: "base64"` - `"base64"` - `BetaManagedAgentsURLImageSource` Image referenced by URL. - `type: "url"` - `"url"` - `url: string` URL of the image to fetch. - `BetaManagedAgentsFileImageSource` Image referenced by file ID. - `file_id: string` ID of a previously uploaded file. - `type: "file"` - `"file"` - `type: "image"` - `"image"` - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` Union type for document source variants. - `BetaManagedAgentsBase64DocumentSource` Base64-encoded document data. - `data: string` Base64-encoded document data. - `media_type: string` MIME type of the document (e.g., "application/pdf"). - `type: "base64"` - `"base64"` - `BetaManagedAgentsPlainTextDocumentSource` Plain text document content. - `data: string` The plain text content. - `media_type: "text/plain"` MIME type of the text content. Must be "text/plain". - `"text/plain"` - `type: "text"` - `"text"` - `BetaManagedAgentsURLDocumentSource` Document referenced by URL. - `type: "url"` - `"url"` - `url: string` URL of the document to fetch. - `BetaManagedAgentsFileDocumentSource` Document referenced by file ID. - `file_id: string` ID of a previously uploaded file. - `type: "file"` - `"file"` - `type: "document"` - `"document"` - `context?: string | null` Additional context about the document for the model. - `title?: string | null` The title of the document. - `BetaManagedAgentsSearchResultBlock` A block containing a web search result. - `citations: BetaManagedAgentsSearchResultCitations` Citation settings for a search result. - `enabled: boolean` Whether citations are enabled for this search result. - `content: Array` Array of text content blocks from the search result. - `text: string` The text content. - `type: "text"` - `"text"` - `source: string` The URL source of the search result. - `title: string` The title of the search result. - `type: "search_result"` - `"search_result"` - `is_error?: boolean | null` Whether the tool execution resulted in an error. ### Beta Managed Agents User Define Outcome Event - `BetaManagedAgentsUserDefineOutcomeEvent` Echo of a `user.define_outcome` input event. Carries the server-generated `outcome_id` that subsequent `span.outcome_evaluation_*` events reference. - `id: string` Unique identifier for this event. - `description: string` What the agent should produce. Copied from the input event. - `max_iterations: number | null` Evaluate-then-revise cycles before giving up. Default 3, max 20. - `outcome_id: string` Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list. - `processed_at: string` A timestamp in RFC 3339 format - `rubric: BetaManagedAgentsFileRubric | BetaManagedAgentsTextRubric` Rubric for grading the quality of an outcome. - `BetaManagedAgentsFileRubric` Rubric referenced by a file uploaded via the Files API. - `file_id: string` ID of the rubric file. - `type: "file"` - `"file"` - `BetaManagedAgentsTextRubric` Rubric content provided inline as text. - `content: string` Rubric content. Plain text or markdown — the grader treats it as freeform text. - `type: "text"` - `"text"` - `type: "user.define_outcome"` - `"user.define_outcome"` ### Beta Managed Agents User Define Outcome Event Params - `BetaManagedAgentsUserDefineOutcomeEventParams` Parameters for defining an outcome the agent should work toward. The agent begins work on receipt. - `description: string` What the agent should produce. This is the task specification. - `rubric: BetaManagedAgentsFileRubricParams | BetaManagedAgentsTextRubricParams` Rubric for grading the quality of an outcome. - `BetaManagedAgentsFileRubricParams` Rubric referenced by a file uploaded via the Files API. - `file_id: string` ID of the rubric file. - `type: "file"` - `"file"` - `BetaManagedAgentsTextRubricParams` Rubric content provided inline as text. - `content: string` Rubric content. Plain text or markdown — the grader treats it as freeform text. Maximum 262144 characters. - `type: "text"` - `"text"` - `type: "user.define_outcome"` - `"user.define_outcome"` - `max_iterations?: number | null` Eval→revision cycles before giving up. Default 3, max 20. ### Beta Managed Agents User Interrupt Event - `BetaManagedAgentsUserInterruptEvent` An interrupt event that pauses agent execution and returns control to the user. - `id: string` Unique identifier for this event. - `type: "user.interrupt"` - `"user.interrupt"` - `processed_at?: string | null` A timestamp in RFC 3339 format - `session_thread_id?: string | null` If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread. ### Beta Managed Agents User Interrupt Event Params - `BetaManagedAgentsUserInterruptEventParams` Parameters for sending an interrupt to pause the agent. - `type: "user.interrupt"` - `"user.interrupt"` - `session_thread_id?: string | null` If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread. ### Beta Managed Agents User Message Event - `BetaManagedAgentsUserMessageEvent` A user message event in the session conversation. - `id: string` Unique identifier for this event. - `content: Array` Array of content blocks comprising the user message. - `BetaManagedAgentsTextBlock` Regular text content. - `text: string` The text content. - `type: "text"` - `"text"` - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` Union type for image source variants. - `BetaManagedAgentsBase64ImageSource` Base64-encoded image data. - `data: string` Base64-encoded image data. - `media_type: string` MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). - `type: "base64"` - `"base64"` - `BetaManagedAgentsURLImageSource` Image referenced by URL. - `type: "url"` - `"url"` - `url: string` URL of the image to fetch. - `BetaManagedAgentsFileImageSource` Image referenced by file ID. - `file_id: string` ID of a previously uploaded file. - `type: "file"` - `"file"` - `type: "image"` - `"image"` - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` Union type for document source variants. - `BetaManagedAgentsBase64DocumentSource` Base64-encoded document data. - `data: string` Base64-encoded document data. - `media_type: string` MIME type of the document (e.g., "application/pdf"). - `type: "base64"` - `"base64"` - `BetaManagedAgentsPlainTextDocumentSource` Plain text document content. - `data: string` The plain text content. - `media_type: "text/plain"` MIME type of the text content. Must be "text/plain". - `"text/plain"` - `type: "text"` - `"text"` - `BetaManagedAgentsURLDocumentSource` Document referenced by URL. - `type: "url"` - `"url"` - `url: string` URL of the document to fetch. - `BetaManagedAgentsFileDocumentSource` Document referenced by file ID. - `file_id: string` ID of a previously uploaded file. - `type: "file"` - `"file"` - `type: "document"` - `"document"` - `context?: string | null` Additional context about the document for the model. - `title?: string | null` The title of the document. - `type: "user.message"` - `"user.message"` - `processed_at?: string | null` A timestamp in RFC 3339 format ### Beta Managed Agents User Message Event Params - `BetaManagedAgentsUserMessageEventParams` Parameters for sending a user message to the session. - `content: Array` Array of content blocks for the user message. - `BetaManagedAgentsTextBlock` Regular text content. - `text: string` The text content. - `type: "text"` - `"text"` - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` Union type for image source variants. - `BetaManagedAgentsBase64ImageSource` Base64-encoded image data. - `data: string` Base64-encoded image data. - `media_type: string` MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). - `type: "base64"` - `"base64"` - `BetaManagedAgentsURLImageSource` Image referenced by URL. - `type: "url"` - `"url"` - `url: string` URL of the image to fetch. - `BetaManagedAgentsFileImageSource` Image referenced by file ID. - `file_id: string` ID of a previously uploaded file. - `type: "file"` - `"file"` - `type: "image"` - `"image"` - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` Union type for document source variants. - `BetaManagedAgentsBase64DocumentSource` Base64-encoded document data. - `data: string` Base64-encoded document data. - `media_type: string` MIME type of the document (e.g., "application/pdf"). - `type: "base64"` - `"base64"` - `BetaManagedAgentsPlainTextDocumentSource` Plain text document content. - `data: string` The plain text content. - `media_type: "text/plain"` MIME type of the text content. Must be "text/plain". - `"text/plain"` - `type: "text"` - `"text"` - `BetaManagedAgentsURLDocumentSource` Document referenced by URL. - `type: "url"` - `"url"` - `url: string` URL of the document to fetch. - `BetaManagedAgentsFileDocumentSource` Document referenced by file ID. - `file_id: string` ID of a previously uploaded file. - `type: "file"` - `"file"` - `type: "document"` - `"document"` - `context?: string | null` Additional context about the document for the model. - `title?: string | null` The title of the document. - `type: "user.message"` - `"user.message"` ### Beta Managed Agents User Tool Confirmation Event - `BetaManagedAgentsUserToolConfirmationEvent` A tool confirmation event that approves or denies a pending tool execution. - `id: string` Unique identifier for this event. - `result: "allow" | "deny"` UserToolConfirmationResult enum - `"allow"` - `"deny"` - `tool_use_id: string` The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `type: "user.tool_confirmation"` - `"user.tool_confirmation"` - `deny_message?: string | null` Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. - `processed_at?: string | null` A timestamp in RFC 3339 format - `session_thread_id?: string | null` When set, the confirmation routes to this subagent's thread rather than the primary. Echo this from the `session_thread_id` on the `agent.tool_use` or `agent.mcp_tool_use` event that prompted the approval. ### Beta Managed Agents User Tool Confirmation Event Params - `BetaManagedAgentsUserToolConfirmationEventParams` Parameters for confirming or denying a tool execution request. - `result: "allow" | "deny"` UserToolConfirmationResult enum - `"allow"` - `"deny"` - `tool_use_id: string` The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `type: "user.tool_confirmation"` - `"user.tool_confirmation"` - `deny_message?: string | null` Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. ### Beta Managed Agents User Tool Result Event Params - `BetaManagedAgentsUserToolResultEventParams` Parameters for providing the result of an agent-toolset tool execution. Only valid on `self_hosted` environments, where sandbox-routed tools are executed by the client rather than the server. - `tool_use_id: string` The id of the `agent.tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `type: "user.tool_result"` - `"user.tool_result"` - `content?: Array` The result content returned by the tool. - `BetaManagedAgentsTextBlock` Regular text content. - `text: string` The text content. - `type: "text"` - `"text"` - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` Union type for image source variants. - `BetaManagedAgentsBase64ImageSource` Base64-encoded image data. - `data: string` Base64-encoded image data. - `media_type: string` MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). - `type: "base64"` - `"base64"` - `BetaManagedAgentsURLImageSource` Image referenced by URL. - `type: "url"` - `"url"` - `url: string` URL of the image to fetch. - `BetaManagedAgentsFileImageSource` Image referenced by file ID. - `file_id: string` ID of a previously uploaded file. - `type: "file"` - `"file"` - `type: "image"` - `"image"` - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` Union type for document source variants. - `BetaManagedAgentsBase64DocumentSource` Base64-encoded document data. - `data: string` Base64-encoded document data. - `media_type: string` MIME type of the document (e.g., "application/pdf"). - `type: "base64"` - `"base64"` - `BetaManagedAgentsPlainTextDocumentSource` Plain text document content. - `data: string` The plain text content. - `media_type: "text/plain"` MIME type of the text content. Must be "text/plain". - `"text/plain"` - `type: "text"` - `"text"` - `BetaManagedAgentsURLDocumentSource` Document referenced by URL. - `type: "url"` - `"url"` - `url: string` URL of the document to fetch. - `BetaManagedAgentsFileDocumentSource` Document referenced by file ID. - `file_id: string` ID of a previously uploaded file. - `type: "file"` - `"file"` - `type: "document"` - `"document"` - `context?: string | null` Additional context about the document for the model. - `title?: string | null` The title of the document. - `BetaManagedAgentsSearchResultBlock` A block containing a web search result. - `citations: BetaManagedAgentsSearchResultCitations` Citation settings for a search result. - `enabled: boolean` Whether citations are enabled for this search result. - `content: Array` Array of text content blocks from the search result. - `text: string` The text content. - `type: "text"` - `"text"` - `source: string` The URL source of the search result. - `title: string` The title of the search result. - `type: "search_result"` - `"search_result"` - `is_error?: boolean | null` Whether the tool execution resulted in an error. # Resources ## Add Session Resource `client.beta.sessions.resources.add(stringsessionID, ResourceAddParamsparams, RequestOptionsoptions?): BetaManagedAgentsFileResource` **post** `/v1/sessions/{session_id}/resources` Add Session Resource ### Parameters - `sessionID: string` - `params: ResourceAddParams` - `file_id: string` Body param: ID of a previously uploaded file. - `type: "file"` Body param - `"file"` - `mount_path?: string | null` Body param: Mount path in the container. Defaults to `/mnt/session/uploads/`. - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaManagedAgentsFileResource` - `id: string` - `created_at: string` A timestamp in RFC 3339 format - `file_id: string` - `mount_path: string` - `type: "file"` - `"file"` - `updated_at: string` A timestamp in RFC 3339 format ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const betaManagedAgentsFileResource = await client.beta.sessions.resources.add( 'sesn_011CZkZAtmR3yMPDzynEDxu7', { file_id: 'file_011CNha8iCJcU1wXNR6q4V8w', type: 'file' }, ); console.log(betaManagedAgentsFileResource.id); ``` #### Response ```json { "id": "sesrsc_011CZkZBJq5dWxk9fVLNcPht", "created_at": "2026-03-15T10:00:00Z", "file_id": "file_011CNha8iCJcU1wXNR6q4V8w", "mount_path": "/uploads/receipt.pdf", "type": "file", "updated_at": "2026-03-15T10:00:00Z" } ``` ## List Session Resources `client.beta.sessions.resources.list(stringsessionID, ResourceListParamsparams?, RequestOptionsoptions?): PageCursor` **get** `/v1/sessions/{session_id}/resources` List Session Resources ### Parameters - `sessionID: string` - `params: ResourceListParams` - `limit?: number` Query param: Maximum number of resources to return per page (max 1000). If omitted, returns all resources. - `page?: string` Query param: Opaque cursor from a previous response's next_page field. - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaManagedAgentsSessionResource = BetaManagedAgentsGitHubRepositoryResource | BetaManagedAgentsFileResource | BetaManagedAgentsMemoryStoreResource` A memory store attached to an agent session. - `BetaManagedAgentsGitHubRepositoryResource` - `id: string` - `created_at: string` A timestamp in RFC 3339 format - `mount_path: string` - `type: "github_repository"` - `"github_repository"` - `updated_at: string` A timestamp in RFC 3339 format - `url: string` - `checkout?: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout | null` - `BetaManagedAgentsBranchCheckout` - `name: string` Branch name to check out. - `type: "branch"` - `"branch"` - `BetaManagedAgentsCommitCheckout` - `sha: string` Full commit SHA to check out. - `type: "commit"` - `"commit"` - `BetaManagedAgentsFileResource` - `id: string` - `created_at: string` A timestamp in RFC 3339 format - `file_id: string` - `mount_path: string` - `type: "file"` - `"file"` - `updated_at: string` A timestamp in RFC 3339 format - `BetaManagedAgentsMemoryStoreResource` A memory store attached to an agent session. - `memory_store_id: string` The memory store ID (memstore_...). Must belong to the caller's organization and workspace. - `type: "memory_store"` - `"memory_store"` - `access?: "read_write" | "read_only" | null` Access mode for an attached memory store. - `"read_write"` - `"read_only"` - `description?: string` Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description. - `instructions?: string | null` Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars. - `mount_path?: string | null` Filesystem path where the store is mounted in the session container, e.g. /mnt/memory/user-preferences. Derived from the store's name. Output-only. - `name?: string | null` Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource. ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); // Automatically fetches more pages as needed. for await (const betaManagedAgentsSessionResource of client.beta.sessions.resources.list( 'sesn_011CZkZAtmR3yMPDzynEDxu7', )) { console.log(betaManagedAgentsSessionResource); } ``` #### Response ```json { "data": [ { "id": "sesrsc_011CZkZBJq5dWxk9fVLNcPht", "created_at": "2026-03-15T10:00:00Z", "file_id": "file_011CNha8iCJcU1wXNR6q4V8w", "mount_path": "/uploads/receipt.pdf", "type": "file", "updated_at": "2026-03-15T10:00:00Z" }, { "id": "sesrsc_011CZkZCKr6eXyl0gWMOdQiu", "created_at": "2026-03-15T10:00:00Z", "mount_path": "/workspace/example-repo", "type": "github_repository", "updated_at": "2026-03-15T10:00:00Z", "url": "https://github.com/example-org/example-repo", "checkout": { "name": "main", "type": "branch" } } ], "next_page": "page_MjAyNS0wNS0xNFQwMDowMDowMFo=" } ``` ## Get Session Resource `client.beta.sessions.resources.retrieve(stringresourceID, ResourceRetrieveParamsparams, RequestOptionsoptions?): ResourceRetrieveResponse` **get** `/v1/sessions/{session_id}/resources/{resource_id}` Get Session Resource ### Parameters - `resourceID: string` - `params: ResourceRetrieveParams` - `session_id: string` Path param: Path parameter session_id - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `ResourceRetrieveResponse = BetaManagedAgentsGitHubRepositoryResource | BetaManagedAgentsFileResource | BetaManagedAgentsMemoryStoreResource` The requested session resource. - `BetaManagedAgentsGitHubRepositoryResource` - `id: string` - `created_at: string` A timestamp in RFC 3339 format - `mount_path: string` - `type: "github_repository"` - `"github_repository"` - `updated_at: string` A timestamp in RFC 3339 format - `url: string` - `checkout?: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout | null` - `BetaManagedAgentsBranchCheckout` - `name: string` Branch name to check out. - `type: "branch"` - `"branch"` - `BetaManagedAgentsCommitCheckout` - `sha: string` Full commit SHA to check out. - `type: "commit"` - `"commit"` - `BetaManagedAgentsFileResource` - `id: string` - `created_at: string` A timestamp in RFC 3339 format - `file_id: string` - `mount_path: string` - `type: "file"` - `"file"` - `updated_at: string` A timestamp in RFC 3339 format - `BetaManagedAgentsMemoryStoreResource` A memory store attached to an agent session. - `memory_store_id: string` The memory store ID (memstore_...). Must belong to the caller's organization and workspace. - `type: "memory_store"` - `"memory_store"` - `access?: "read_write" | "read_only" | null` Access mode for an attached memory store. - `"read_write"` - `"read_only"` - `description?: string` Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description. - `instructions?: string | null` Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars. - `mount_path?: string | null` Filesystem path where the store is mounted in the session container, e.g. /mnt/memory/user-preferences. Derived from the store's name. Output-only. - `name?: string | null` Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource. ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const resource = await client.beta.sessions.resources.retrieve('sesrsc_011CZkZBJq5dWxk9fVLNcPht', { session_id: 'sesn_011CZkZAtmR3yMPDzynEDxu7', }); console.log(resource); ``` #### Response ```json { "id": "sesrsc_011CZkZCKr6eXyl0gWMOdQiu", "created_at": "2026-03-15T10:00:00Z", "mount_path": "/workspace/example-repo", "type": "github_repository", "updated_at": "2026-03-15T10:00:00Z", "url": "https://github.com/example-org/example-repo", "checkout": { "name": "main", "type": "branch" } } ``` ## Update Session Resource `client.beta.sessions.resources.update(stringresourceID, ResourceUpdateParamsparams, RequestOptionsoptions?): ResourceUpdateResponse` **post** `/v1/sessions/{session_id}/resources/{resource_id}` Update Session Resource ### Parameters - `resourceID: string` - `params: ResourceUpdateParams` - `session_id: string` Path param: Path parameter session_id - `authorization_token: string` Body param: New authorization token for the resource. Currently only `github_repository` resources support token rotation. - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `ResourceUpdateResponse = BetaManagedAgentsGitHubRepositoryResource | BetaManagedAgentsFileResource | BetaManagedAgentsMemoryStoreResource` The updated session resource. - `BetaManagedAgentsGitHubRepositoryResource` - `id: string` - `created_at: string` A timestamp in RFC 3339 format - `mount_path: string` - `type: "github_repository"` - `"github_repository"` - `updated_at: string` A timestamp in RFC 3339 format - `url: string` - `checkout?: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout | null` - `BetaManagedAgentsBranchCheckout` - `name: string` Branch name to check out. - `type: "branch"` - `"branch"` - `BetaManagedAgentsCommitCheckout` - `sha: string` Full commit SHA to check out. - `type: "commit"` - `"commit"` - `BetaManagedAgentsFileResource` - `id: string` - `created_at: string` A timestamp in RFC 3339 format - `file_id: string` - `mount_path: string` - `type: "file"` - `"file"` - `updated_at: string` A timestamp in RFC 3339 format - `BetaManagedAgentsMemoryStoreResource` A memory store attached to an agent session. - `memory_store_id: string` The memory store ID (memstore_...). Must belong to the caller's organization and workspace. - `type: "memory_store"` - `"memory_store"` - `access?: "read_write" | "read_only" | null` Access mode for an attached memory store. - `"read_write"` - `"read_only"` - `description?: string` Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description. - `instructions?: string | null` Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars. - `mount_path?: string | null` Filesystem path where the store is mounted in the session container, e.g. /mnt/memory/user-preferences. Derived from the store's name. Output-only. - `name?: string | null` Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource. ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const resource = await client.beta.sessions.resources.update('sesrsc_011CZkZBJq5dWxk9fVLNcPht', { session_id: 'sesn_011CZkZAtmR3yMPDzynEDxu7', authorization_token: 'ghp_exampletoken', }); console.log(resource); ``` #### Response ```json { "id": "sesrsc_011CZkZCKr6eXyl0gWMOdQiu", "created_at": "2026-03-15T10:00:00Z", "mount_path": "/workspace/example-repo", "type": "github_repository", "updated_at": "2026-03-15T10:00:00Z", "url": "https://github.com/example-org/example-repo", "checkout": { "name": "main", "type": "branch" } } ``` ## Delete Session Resource `client.beta.sessions.resources.delete(stringresourceID, ResourceDeleteParamsparams, RequestOptionsoptions?): BetaManagedAgentsDeleteSessionResource` **delete** `/v1/sessions/{session_id}/resources/{resource_id}` Delete Session Resource ### Parameters - `resourceID: string` - `params: ResourceDeleteParams` - `session_id: string` Path param: Path parameter session_id - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaManagedAgentsDeleteSessionResource` Confirmation of resource deletion. - `id: string` - `type: "session_resource_deleted"` - `"session_resource_deleted"` ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const betaManagedAgentsDeleteSessionResource = await client.beta.sessions.resources.delete( 'sesrsc_011CZkZBJq5dWxk9fVLNcPht', { session_id: 'sesn_011CZkZAtmR3yMPDzynEDxu7' }, ); console.log(betaManagedAgentsDeleteSessionResource.id); ``` #### Response ```json { "id": "sesrsc_011CZkZBJq5dWxk9fVLNcPht", "type": "session_resource_deleted" } ``` ## Domain Types ### Beta Managed Agents Delete Session Resource - `BetaManagedAgentsDeleteSessionResource` Confirmation of resource deletion. - `id: string` - `type: "session_resource_deleted"` - `"session_resource_deleted"` ### Beta Managed Agents File Resource - `BetaManagedAgentsFileResource` - `id: string` - `created_at: string` A timestamp in RFC 3339 format - `file_id: string` - `mount_path: string` - `type: "file"` - `"file"` - `updated_at: string` A timestamp in RFC 3339 format ### Beta Managed Agents GitHub Repository Resource - `BetaManagedAgentsGitHubRepositoryResource` - `id: string` - `created_at: string` A timestamp in RFC 3339 format - `mount_path: string` - `type: "github_repository"` - `"github_repository"` - `updated_at: string` A timestamp in RFC 3339 format - `url: string` - `checkout?: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout | null` - `BetaManagedAgentsBranchCheckout` - `name: string` Branch name to check out. - `type: "branch"` - `"branch"` - `BetaManagedAgentsCommitCheckout` - `sha: string` Full commit SHA to check out. - `type: "commit"` - `"commit"` ### Beta Managed Agents Memory Store Resource - `BetaManagedAgentsMemoryStoreResource` A memory store attached to an agent session. - `memory_store_id: string` The memory store ID (memstore_...). Must belong to the caller's organization and workspace. - `type: "memory_store"` - `"memory_store"` - `access?: "read_write" | "read_only" | null` Access mode for an attached memory store. - `"read_write"` - `"read_only"` - `description?: string` Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description. - `instructions?: string | null` Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars. - `mount_path?: string | null` Filesystem path where the store is mounted in the session container, e.g. /mnt/memory/user-preferences. Derived from the store's name. Output-only. - `name?: string | null` Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource. ### Beta Managed Agents Session Resource - `BetaManagedAgentsSessionResource = BetaManagedAgentsGitHubRepositoryResource | BetaManagedAgentsFileResource | BetaManagedAgentsMemoryStoreResource` A memory store attached to an agent session. - `BetaManagedAgentsGitHubRepositoryResource` - `id: string` - `created_at: string` A timestamp in RFC 3339 format - `mount_path: string` - `type: "github_repository"` - `"github_repository"` - `updated_at: string` A timestamp in RFC 3339 format - `url: string` - `checkout?: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout | null` - `BetaManagedAgentsBranchCheckout` - `name: string` Branch name to check out. - `type: "branch"` - `"branch"` - `BetaManagedAgentsCommitCheckout` - `sha: string` Full commit SHA to check out. - `type: "commit"` - `"commit"` - `BetaManagedAgentsFileResource` - `id: string` - `created_at: string` A timestamp in RFC 3339 format - `file_id: string` - `mount_path: string` - `type: "file"` - `"file"` - `updated_at: string` A timestamp in RFC 3339 format - `BetaManagedAgentsMemoryStoreResource` A memory store attached to an agent session. - `memory_store_id: string` The memory store ID (memstore_...). Must belong to the caller's organization and workspace. - `type: "memory_store"` - `"memory_store"` - `access?: "read_write" | "read_only" | null` Access mode for an attached memory store. - `"read_write"` - `"read_only"` - `description?: string` Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description. - `instructions?: string | null` Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars. - `mount_path?: string | null` Filesystem path where the store is mounted in the session container, e.g. /mnt/memory/user-preferences. Derived from the store's name. Output-only. - `name?: string | null` Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource. ### Resource Retrieve Response - `ResourceRetrieveResponse = BetaManagedAgentsGitHubRepositoryResource | BetaManagedAgentsFileResource | BetaManagedAgentsMemoryStoreResource` The requested session resource. - `BetaManagedAgentsGitHubRepositoryResource` - `id: string` - `created_at: string` A timestamp in RFC 3339 format - `mount_path: string` - `type: "github_repository"` - `"github_repository"` - `updated_at: string` A timestamp in RFC 3339 format - `url: string` - `checkout?: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout | null` - `BetaManagedAgentsBranchCheckout` - `name: string` Branch name to check out. - `type: "branch"` - `"branch"` - `BetaManagedAgentsCommitCheckout` - `sha: string` Full commit SHA to check out. - `type: "commit"` - `"commit"` - `BetaManagedAgentsFileResource` - `id: string` - `created_at: string` A timestamp in RFC 3339 format - `file_id: string` - `mount_path: string` - `type: "file"` - `"file"` - `updated_at: string` A timestamp in RFC 3339 format - `BetaManagedAgentsMemoryStoreResource` A memory store attached to an agent session. - `memory_store_id: string` The memory store ID (memstore_...). Must belong to the caller's organization and workspace. - `type: "memory_store"` - `"memory_store"` - `access?: "read_write" | "read_only" | null` Access mode for an attached memory store. - `"read_write"` - `"read_only"` - `description?: string` Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description. - `instructions?: string | null` Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars. - `mount_path?: string | null` Filesystem path where the store is mounted in the session container, e.g. /mnt/memory/user-preferences. Derived from the store's name. Output-only. - `name?: string | null` Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource. ### Resource Update Response - `ResourceUpdateResponse = BetaManagedAgentsGitHubRepositoryResource | BetaManagedAgentsFileResource | BetaManagedAgentsMemoryStoreResource` The updated session resource. - `BetaManagedAgentsGitHubRepositoryResource` - `id: string` - `created_at: string` A timestamp in RFC 3339 format - `mount_path: string` - `type: "github_repository"` - `"github_repository"` - `updated_at: string` A timestamp in RFC 3339 format - `url: string` - `checkout?: BetaManagedAgentsBranchCheckout | BetaManagedAgentsCommitCheckout | null` - `BetaManagedAgentsBranchCheckout` - `name: string` Branch name to check out. - `type: "branch"` - `"branch"` - `BetaManagedAgentsCommitCheckout` - `sha: string` Full commit SHA to check out. - `type: "commit"` - `"commit"` - `BetaManagedAgentsFileResource` - `id: string` - `created_at: string` A timestamp in RFC 3339 format - `file_id: string` - `mount_path: string` - `type: "file"` - `"file"` - `updated_at: string` A timestamp in RFC 3339 format - `BetaManagedAgentsMemoryStoreResource` A memory store attached to an agent session. - `memory_store_id: string` The memory store ID (memstore_...). Must belong to the caller's organization and workspace. - `type: "memory_store"` - `"memory_store"` - `access?: "read_write" | "read_only" | null` Access mode for an attached memory store. - `"read_write"` - `"read_only"` - `description?: string` Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description. - `instructions?: string | null` Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars. - `mount_path?: string | null` Filesystem path where the store is mounted in the session container, e.g. /mnt/memory/user-preferences. Derived from the store's name. Output-only. - `name?: string | null` Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource. # Threads ## List Session Threads `client.beta.sessions.threads.list(stringsessionID, ThreadListParamsparams?, RequestOptionsoptions?): PageCursor` **get** `/v1/sessions/{session_id}/threads` List Session Threads ### Parameters - `sessionID: string` - `params: ThreadListParams` - `limit?: number` Query param: Maximum results per page. Defaults to 1000. - `page?: string` Query param: Opaque pagination cursor from a previous response's next_page. Forward-only. - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaManagedAgentsSessionThread` An execution thread within a `session`. Each session has one primary thread plus zero or more child threads spawned by the coordinator. - `id: string` Unique identifier for this thread. - `agent: BetaManagedAgentsSessionThreadAgent` Resolved `agent` definition for a single `session_thread`. Snapshot of the agent at thread creation time. The multiagent roster is not repeated here; read it from `Session.agent`. - `id: string` - `description: string | null` - `mcp_servers: Array` - `name: string` - `type: "url"` - `"url"` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `id: BetaManagedAgentsModel` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-opus-4-8" | "claude-opus-4-7" | "claude-opus-4-6" | 7 more` - `"claude-opus-4-8"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-7"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-6"` Most intelligent model for building agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` Fastest model with near-frontier intelligence - `"claude-haiku-4-5-20251001"` Fastest model with near-frontier intelligence - `"claude-opus-4-5"` Premium model combining maximum intelligence with practical performance - `"claude-opus-4-5-20251101"` Premium model combining maximum intelligence with practical performance - `"claude-sonnet-4-5"` High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` High-performance model for agents and coding - `(string & {})` - `speed?: "standard" | "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `name: string` - `skills: Array` - `BetaManagedAgentsAnthropicSkill` A resolved Anthropic-managed skill. - `skill_id: string` - `type: "anthropic"` - `"anthropic"` - `version: string` - `BetaManagedAgentsCustomSkill` A resolved user-created custom skill. - `skill_id: string` - `type: "custom"` - `"custom"` - `version: string` - `system: string | null` - `tools: Array` - `BetaManagedAgentsAgentToolset20260401` - `configs: Array` - `enabled: boolean` - `name: "bash" | "edit" | "read" | 5 more` Built-in agent tool identifier. - `"bash"` - `"edit"` - `"read"` - `"write"` - `"glob"` - `"grep"` - `"web_fetch"` - `"web_search"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `"always_allow"` - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "always_ask"` - `"always_ask"` - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` Resolved default configuration for agent tools. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "agent_toolset_20260401"` - `"agent_toolset_20260401"` - `BetaManagedAgentsMCPToolset` - `configs: Array` - `enabled: boolean` - `name: string` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` Resolved default configuration for all tools from an MCP server. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `mcp_server_name: string` - `type: "mcp_toolset"` - `"mcp_toolset"` - `BetaManagedAgentsCustomTool` A custom tool as returned in API responses. - `description: string` - `input_schema: BetaManagedAgentsCustomToolInputSchema` JSON Schema for custom tool input parameters. - `properties?: Record | null` JSON Schema properties defining the tool's input parameters. - `required?: Array` List of required property names. - `type?: "object"` Must be 'object' for tool input schemas. - `"object"` - `name: string` - `type: "custom"` - `"custom"` - `type: "agent"` - `"agent"` - `version: number` - `archived_at: string | null` A timestamp in RFC 3339 format - `created_at: string` A timestamp in RFC 3339 format - `parent_thread_id: string | null` Parent thread that spawned this thread. Null for the primary thread. - `session_id: string` The session this thread belongs to. - `stats: BetaManagedAgentsSessionThreadStats | null` Timing statistics for a session thread. - `active_seconds?: number` Cumulative time in seconds the thread spent actively running. Excludes idle time. - `duration_seconds?: number` Elapsed time since thread creation in seconds. For archived threads, frozen at the final update. - `startup_seconds?: number` Time in seconds for the thread to begin running. Zero for child threads, which start immediately. - `status: BetaManagedAgentsSessionThreadStatus` SessionThreadStatus enum - `"running"` - `"idle"` - `"rescheduling"` - `"terminated"` - `type: "session_thread"` - `"session_thread"` - `updated_at: string` A timestamp in RFC 3339 format - `usage: BetaManagedAgentsSessionThreadUsage | null` Cumulative token usage for a session thread across all turns. - `cache_creation?: BetaManagedAgentsCacheCreationUsage` Prompt-cache creation token usage broken down by cache lifetime. - `ephemeral_1h_input_tokens?: number` Tokens used to create 1-hour ephemeral cache entries. - `ephemeral_5m_input_tokens?: number` Tokens used to create 5-minute ephemeral cache entries. - `cache_read_input_tokens?: number` Total tokens read from prompt cache. - `input_tokens?: number` Total input tokens consumed across all turns. - `output_tokens?: number` Total output tokens generated across all turns. ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); // Automatically fetches more pages as needed. for await (const betaManagedAgentsSessionThread of client.beta.sessions.threads.list( 'sesn_011CZkZAtmR3yMPDzynEDxu7', )) { console.log(betaManagedAgentsSessionThread.id); } ``` #### Response ```json { "data": [ { "id": "sthr_011CZkZVWa6oIjw0rgXZpnBt", "agent": { "id": "agent_011CZkYqphY8vELVzwCUpqiQ", "description": "A focused research subagent.", "mcp_servers": [ { "name": "example-mcp", "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse" } ], "model": { "id": "claude-sonnet-4-6", "speed": "standard" }, "name": "Researcher", "skills": [ { "skill_id": "xlsx", "type": "anthropic", "version": "1" } ], "system": "You are a research subagent that gathers and summarises sources for the coordinating agent.", "tools": [ { "configs": [ { "enabled": true, "name": "bash", "permission_policy": { "type": "always_allow" } } ], "default_config": { "enabled": true, "permission_policy": { "type": "always_ask" } }, "type": "agent_toolset_20260401" } ], "type": "agent", "version": 1 }, "archived_at": null, "created_at": "2026-03-15T10:00:00Z", "parent_thread_id": null, "session_id": "sesn_011CZkZAtmR3yMPDzynEDxu7", "stats": { "active_seconds": 0, "duration_seconds": 0, "startup_seconds": 0 }, "status": "idle", "type": "session_thread", "updated_at": "2026-03-15T10:00:00Z", "usage": { "cache_creation": { "ephemeral_1h_input_tokens": 0, "ephemeral_5m_input_tokens": 0 }, "cache_read_input_tokens": 0, "input_tokens": 0, "output_tokens": 0 } } ], "next_page": "page_MjAyNS0wNS0xNFQwMDowMDowMFo=" } ``` ## Get Session Thread `client.beta.sessions.threads.retrieve(stringthreadID, ThreadRetrieveParamsparams, RequestOptionsoptions?): BetaManagedAgentsSessionThread` **get** `/v1/sessions/{session_id}/threads/{thread_id}` Get Session Thread ### Parameters - `threadID: string` - `params: ThreadRetrieveParams` - `session_id: string` Path param: Path parameter session_id - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaManagedAgentsSessionThread` An execution thread within a `session`. Each session has one primary thread plus zero or more child threads spawned by the coordinator. - `id: string` Unique identifier for this thread. - `agent: BetaManagedAgentsSessionThreadAgent` Resolved `agent` definition for a single `session_thread`. Snapshot of the agent at thread creation time. The multiagent roster is not repeated here; read it from `Session.agent`. - `id: string` - `description: string | null` - `mcp_servers: Array` - `name: string` - `type: "url"` - `"url"` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `id: BetaManagedAgentsModel` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-opus-4-8" | "claude-opus-4-7" | "claude-opus-4-6" | 7 more` - `"claude-opus-4-8"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-7"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-6"` Most intelligent model for building agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` Fastest model with near-frontier intelligence - `"claude-haiku-4-5-20251001"` Fastest model with near-frontier intelligence - `"claude-opus-4-5"` Premium model combining maximum intelligence with practical performance - `"claude-opus-4-5-20251101"` Premium model combining maximum intelligence with practical performance - `"claude-sonnet-4-5"` High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` High-performance model for agents and coding - `(string & {})` - `speed?: "standard" | "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `name: string` - `skills: Array` - `BetaManagedAgentsAnthropicSkill` A resolved Anthropic-managed skill. - `skill_id: string` - `type: "anthropic"` - `"anthropic"` - `version: string` - `BetaManagedAgentsCustomSkill` A resolved user-created custom skill. - `skill_id: string` - `type: "custom"` - `"custom"` - `version: string` - `system: string | null` - `tools: Array` - `BetaManagedAgentsAgentToolset20260401` - `configs: Array` - `enabled: boolean` - `name: "bash" | "edit" | "read" | 5 more` Built-in agent tool identifier. - `"bash"` - `"edit"` - `"read"` - `"write"` - `"glob"` - `"grep"` - `"web_fetch"` - `"web_search"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `"always_allow"` - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "always_ask"` - `"always_ask"` - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` Resolved default configuration for agent tools. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "agent_toolset_20260401"` - `"agent_toolset_20260401"` - `BetaManagedAgentsMCPToolset` - `configs: Array` - `enabled: boolean` - `name: string` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` Resolved default configuration for all tools from an MCP server. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `mcp_server_name: string` - `type: "mcp_toolset"` - `"mcp_toolset"` - `BetaManagedAgentsCustomTool` A custom tool as returned in API responses. - `description: string` - `input_schema: BetaManagedAgentsCustomToolInputSchema` JSON Schema for custom tool input parameters. - `properties?: Record | null` JSON Schema properties defining the tool's input parameters. - `required?: Array` List of required property names. - `type?: "object"` Must be 'object' for tool input schemas. - `"object"` - `name: string` - `type: "custom"` - `"custom"` - `type: "agent"` - `"agent"` - `version: number` - `archived_at: string | null` A timestamp in RFC 3339 format - `created_at: string` A timestamp in RFC 3339 format - `parent_thread_id: string | null` Parent thread that spawned this thread. Null for the primary thread. - `session_id: string` The session this thread belongs to. - `stats: BetaManagedAgentsSessionThreadStats | null` Timing statistics for a session thread. - `active_seconds?: number` Cumulative time in seconds the thread spent actively running. Excludes idle time. - `duration_seconds?: number` Elapsed time since thread creation in seconds. For archived threads, frozen at the final update. - `startup_seconds?: number` Time in seconds for the thread to begin running. Zero for child threads, which start immediately. - `status: BetaManagedAgentsSessionThreadStatus` SessionThreadStatus enum - `"running"` - `"idle"` - `"rescheduling"` - `"terminated"` - `type: "session_thread"` - `"session_thread"` - `updated_at: string` A timestamp in RFC 3339 format - `usage: BetaManagedAgentsSessionThreadUsage | null` Cumulative token usage for a session thread across all turns. - `cache_creation?: BetaManagedAgentsCacheCreationUsage` Prompt-cache creation token usage broken down by cache lifetime. - `ephemeral_1h_input_tokens?: number` Tokens used to create 1-hour ephemeral cache entries. - `ephemeral_5m_input_tokens?: number` Tokens used to create 5-minute ephemeral cache entries. - `cache_read_input_tokens?: number` Total tokens read from prompt cache. - `input_tokens?: number` Total input tokens consumed across all turns. - `output_tokens?: number` Total output tokens generated across all turns. ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const betaManagedAgentsSessionThread = await client.beta.sessions.threads.retrieve( 'sthr_011CZkZVWa6oIjw0rgXZpnBt', { session_id: 'sesn_011CZkZAtmR3yMPDzynEDxu7' }, ); console.log(betaManagedAgentsSessionThread.id); ``` #### Response ```json { "id": "sthr_011CZkZVWa6oIjw0rgXZpnBt", "agent": { "id": "agent_011CZkYqphY8vELVzwCUpqiQ", "description": "A focused research subagent.", "mcp_servers": [ { "name": "example-mcp", "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse" } ], "model": { "id": "claude-sonnet-4-6", "speed": "standard" }, "name": "Researcher", "skills": [ { "skill_id": "xlsx", "type": "anthropic", "version": "1" } ], "system": "You are a research subagent that gathers and summarises sources for the coordinating agent.", "tools": [ { "configs": [ { "enabled": true, "name": "bash", "permission_policy": { "type": "always_allow" } } ], "default_config": { "enabled": true, "permission_policy": { "type": "always_ask" } }, "type": "agent_toolset_20260401" } ], "type": "agent", "version": 1 }, "archived_at": null, "created_at": "2026-03-15T10:00:00Z", "parent_thread_id": null, "session_id": "sesn_011CZkZAtmR3yMPDzynEDxu7", "stats": { "active_seconds": 0, "duration_seconds": 0, "startup_seconds": 0 }, "status": "idle", "type": "session_thread", "updated_at": "2026-03-15T10:00:00Z", "usage": { "cache_creation": { "ephemeral_1h_input_tokens": 0, "ephemeral_5m_input_tokens": 0 }, "cache_read_input_tokens": 0, "input_tokens": 0, "output_tokens": 0 } } ``` ## Archive Session Thread `client.beta.sessions.threads.archive(stringthreadID, ThreadArchiveParamsparams, RequestOptionsoptions?): BetaManagedAgentsSessionThread` **post** `/v1/sessions/{session_id}/threads/{thread_id}/archive` Archive Session Thread ### Parameters - `threadID: string` - `params: ThreadArchiveParams` - `session_id: string` Path param: Path parameter session_id - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaManagedAgentsSessionThread` An execution thread within a `session`. Each session has one primary thread plus zero or more child threads spawned by the coordinator. - `id: string` Unique identifier for this thread. - `agent: BetaManagedAgentsSessionThreadAgent` Resolved `agent` definition for a single `session_thread`. Snapshot of the agent at thread creation time. The multiagent roster is not repeated here; read it from `Session.agent`. - `id: string` - `description: string | null` - `mcp_servers: Array` - `name: string` - `type: "url"` - `"url"` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `id: BetaManagedAgentsModel` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-opus-4-8" | "claude-opus-4-7" | "claude-opus-4-6" | 7 more` - `"claude-opus-4-8"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-7"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-6"` Most intelligent model for building agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` Fastest model with near-frontier intelligence - `"claude-haiku-4-5-20251001"` Fastest model with near-frontier intelligence - `"claude-opus-4-5"` Premium model combining maximum intelligence with practical performance - `"claude-opus-4-5-20251101"` Premium model combining maximum intelligence with practical performance - `"claude-sonnet-4-5"` High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` High-performance model for agents and coding - `(string & {})` - `speed?: "standard" | "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `name: string` - `skills: Array` - `BetaManagedAgentsAnthropicSkill` A resolved Anthropic-managed skill. - `skill_id: string` - `type: "anthropic"` - `"anthropic"` - `version: string` - `BetaManagedAgentsCustomSkill` A resolved user-created custom skill. - `skill_id: string` - `type: "custom"` - `"custom"` - `version: string` - `system: string | null` - `tools: Array` - `BetaManagedAgentsAgentToolset20260401` - `configs: Array` - `enabled: boolean` - `name: "bash" | "edit" | "read" | 5 more` Built-in agent tool identifier. - `"bash"` - `"edit"` - `"read"` - `"write"` - `"glob"` - `"grep"` - `"web_fetch"` - `"web_search"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `"always_allow"` - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "always_ask"` - `"always_ask"` - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` Resolved default configuration for agent tools. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "agent_toolset_20260401"` - `"agent_toolset_20260401"` - `BetaManagedAgentsMCPToolset` - `configs: Array` - `enabled: boolean` - `name: string` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` Resolved default configuration for all tools from an MCP server. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `mcp_server_name: string` - `type: "mcp_toolset"` - `"mcp_toolset"` - `BetaManagedAgentsCustomTool` A custom tool as returned in API responses. - `description: string` - `input_schema: BetaManagedAgentsCustomToolInputSchema` JSON Schema for custom tool input parameters. - `properties?: Record | null` JSON Schema properties defining the tool's input parameters. - `required?: Array` List of required property names. - `type?: "object"` Must be 'object' for tool input schemas. - `"object"` - `name: string` - `type: "custom"` - `"custom"` - `type: "agent"` - `"agent"` - `version: number` - `archived_at: string | null` A timestamp in RFC 3339 format - `created_at: string` A timestamp in RFC 3339 format - `parent_thread_id: string | null` Parent thread that spawned this thread. Null for the primary thread. - `session_id: string` The session this thread belongs to. - `stats: BetaManagedAgentsSessionThreadStats | null` Timing statistics for a session thread. - `active_seconds?: number` Cumulative time in seconds the thread spent actively running. Excludes idle time. - `duration_seconds?: number` Elapsed time since thread creation in seconds. For archived threads, frozen at the final update. - `startup_seconds?: number` Time in seconds for the thread to begin running. Zero for child threads, which start immediately. - `status: BetaManagedAgentsSessionThreadStatus` SessionThreadStatus enum - `"running"` - `"idle"` - `"rescheduling"` - `"terminated"` - `type: "session_thread"` - `"session_thread"` - `updated_at: string` A timestamp in RFC 3339 format - `usage: BetaManagedAgentsSessionThreadUsage | null` Cumulative token usage for a session thread across all turns. - `cache_creation?: BetaManagedAgentsCacheCreationUsage` Prompt-cache creation token usage broken down by cache lifetime. - `ephemeral_1h_input_tokens?: number` Tokens used to create 1-hour ephemeral cache entries. - `ephemeral_5m_input_tokens?: number` Tokens used to create 5-minute ephemeral cache entries. - `cache_read_input_tokens?: number` Total tokens read from prompt cache. - `input_tokens?: number` Total input tokens consumed across all turns. - `output_tokens?: number` Total output tokens generated across all turns. ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const betaManagedAgentsSessionThread = await client.beta.sessions.threads.archive( 'sthr_011CZkZVWa6oIjw0rgXZpnBt', { session_id: 'sesn_011CZkZAtmR3yMPDzynEDxu7' }, ); console.log(betaManagedAgentsSessionThread.id); ``` #### Response ```json { "id": "sthr_011CZkZVWa6oIjw0rgXZpnBt", "agent": { "id": "agent_011CZkYqphY8vELVzwCUpqiQ", "description": "A focused research subagent.", "mcp_servers": [ { "name": "example-mcp", "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse" } ], "model": { "id": "claude-sonnet-4-6", "speed": "standard" }, "name": "Researcher", "skills": [ { "skill_id": "xlsx", "type": "anthropic", "version": "1" } ], "system": "You are a research subagent that gathers and summarises sources for the coordinating agent.", "tools": [ { "configs": [ { "enabled": true, "name": "bash", "permission_policy": { "type": "always_allow" } } ], "default_config": { "enabled": true, "permission_policy": { "type": "always_ask" } }, "type": "agent_toolset_20260401" } ], "type": "agent", "version": 1 }, "archived_at": null, "created_at": "2026-03-15T10:00:00Z", "parent_thread_id": null, "session_id": "sesn_011CZkZAtmR3yMPDzynEDxu7", "stats": { "active_seconds": 0, "duration_seconds": 0, "startup_seconds": 0 }, "status": "idle", "type": "session_thread", "updated_at": "2026-03-15T10:00:00Z", "usage": { "cache_creation": { "ephemeral_1h_input_tokens": 0, "ephemeral_5m_input_tokens": 0 }, "cache_read_input_tokens": 0, "input_tokens": 0, "output_tokens": 0 } } ``` ## Domain Types ### Beta Managed Agents Session Thread - `BetaManagedAgentsSessionThread` An execution thread within a `session`. Each session has one primary thread plus zero or more child threads spawned by the coordinator. - `id: string` Unique identifier for this thread. - `agent: BetaManagedAgentsSessionThreadAgent` Resolved `agent` definition for a single `session_thread`. Snapshot of the agent at thread creation time. The multiagent roster is not repeated here; read it from `Session.agent`. - `id: string` - `description: string | null` - `mcp_servers: Array` - `name: string` - `type: "url"` - `"url"` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `id: BetaManagedAgentsModel` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-opus-4-8" | "claude-opus-4-7" | "claude-opus-4-6" | 7 more` - `"claude-opus-4-8"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-7"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-6"` Most intelligent model for building agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` Fastest model with near-frontier intelligence - `"claude-haiku-4-5-20251001"` Fastest model with near-frontier intelligence - `"claude-opus-4-5"` Premium model combining maximum intelligence with practical performance - `"claude-opus-4-5-20251101"` Premium model combining maximum intelligence with practical performance - `"claude-sonnet-4-5"` High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` High-performance model for agents and coding - `(string & {})` - `speed?: "standard" | "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `name: string` - `skills: Array` - `BetaManagedAgentsAnthropicSkill` A resolved Anthropic-managed skill. - `skill_id: string` - `type: "anthropic"` - `"anthropic"` - `version: string` - `BetaManagedAgentsCustomSkill` A resolved user-created custom skill. - `skill_id: string` - `type: "custom"` - `"custom"` - `version: string` - `system: string | null` - `tools: Array` - `BetaManagedAgentsAgentToolset20260401` - `configs: Array` - `enabled: boolean` - `name: "bash" | "edit" | "read" | 5 more` Built-in agent tool identifier. - `"bash"` - `"edit"` - `"read"` - `"write"` - `"glob"` - `"grep"` - `"web_fetch"` - `"web_search"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `"always_allow"` - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "always_ask"` - `"always_ask"` - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` Resolved default configuration for agent tools. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "agent_toolset_20260401"` - `"agent_toolset_20260401"` - `BetaManagedAgentsMCPToolset` - `configs: Array` - `enabled: boolean` - `name: string` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` Resolved default configuration for all tools from an MCP server. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `mcp_server_name: string` - `type: "mcp_toolset"` - `"mcp_toolset"` - `BetaManagedAgentsCustomTool` A custom tool as returned in API responses. - `description: string` - `input_schema: BetaManagedAgentsCustomToolInputSchema` JSON Schema for custom tool input parameters. - `properties?: Record | null` JSON Schema properties defining the tool's input parameters. - `required?: Array` List of required property names. - `type?: "object"` Must be 'object' for tool input schemas. - `"object"` - `name: string` - `type: "custom"` - `"custom"` - `type: "agent"` - `"agent"` - `version: number` - `archived_at: string | null` A timestamp in RFC 3339 format - `created_at: string` A timestamp in RFC 3339 format - `parent_thread_id: string | null` Parent thread that spawned this thread. Null for the primary thread. - `session_id: string` The session this thread belongs to. - `stats: BetaManagedAgentsSessionThreadStats | null` Timing statistics for a session thread. - `active_seconds?: number` Cumulative time in seconds the thread spent actively running. Excludes idle time. - `duration_seconds?: number` Elapsed time since thread creation in seconds. For archived threads, frozen at the final update. - `startup_seconds?: number` Time in seconds for the thread to begin running. Zero for child threads, which start immediately. - `status: BetaManagedAgentsSessionThreadStatus` SessionThreadStatus enum - `"running"` - `"idle"` - `"rescheduling"` - `"terminated"` - `type: "session_thread"` - `"session_thread"` - `updated_at: string` A timestamp in RFC 3339 format - `usage: BetaManagedAgentsSessionThreadUsage | null` Cumulative token usage for a session thread across all turns. - `cache_creation?: BetaManagedAgentsCacheCreationUsage` Prompt-cache creation token usage broken down by cache lifetime. - `ephemeral_1h_input_tokens?: number` Tokens used to create 1-hour ephemeral cache entries. - `ephemeral_5m_input_tokens?: number` Tokens used to create 5-minute ephemeral cache entries. - `cache_read_input_tokens?: number` Total tokens read from prompt cache. - `input_tokens?: number` Total input tokens consumed across all turns. - `output_tokens?: number` Total output tokens generated across all turns. ### Beta Managed Agents Session Thread Stats - `BetaManagedAgentsSessionThreadStats` Timing statistics for a session thread. - `active_seconds?: number` Cumulative time in seconds the thread spent actively running. Excludes idle time. - `duration_seconds?: number` Elapsed time since thread creation in seconds. For archived threads, frozen at the final update. - `startup_seconds?: number` Time in seconds for the thread to begin running. Zero for child threads, which start immediately. ### Beta Managed Agents Session Thread Status - `BetaManagedAgentsSessionThreadStatus = "running" | "idle" | "rescheduling" | "terminated"` SessionThreadStatus enum - `"running"` - `"idle"` - `"rescheduling"` - `"terminated"` ### Beta Managed Agents Session Thread Usage - `BetaManagedAgentsSessionThreadUsage` Cumulative token usage for a session thread across all turns. - `cache_creation?: BetaManagedAgentsCacheCreationUsage` Prompt-cache creation token usage broken down by cache lifetime. - `ephemeral_1h_input_tokens?: number` Tokens used to create 1-hour ephemeral cache entries. - `ephemeral_5m_input_tokens?: number` Tokens used to create 5-minute ephemeral cache entries. - `cache_read_input_tokens?: number` Total tokens read from prompt cache. - `input_tokens?: number` Total input tokens consumed across all turns. - `output_tokens?: number` Total output tokens generated across all turns. ### Beta Managed Agents Stream Session Thread Events - `BetaManagedAgentsStreamSessionThreadEvents = BetaManagedAgentsUserMessageEvent | BetaManagedAgentsUserInterruptEvent | BetaManagedAgentsUserToolConfirmationEvent | 30 more` Server-sent event in a single thread's stream. - `BetaManagedAgentsUserMessageEvent` A user message event in the session conversation. - `id: string` Unique identifier for this event. - `content: Array` Array of content blocks comprising the user message. - `BetaManagedAgentsTextBlock` Regular text content. - `text: string` The text content. - `type: "text"` - `"text"` - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` Union type for image source variants. - `BetaManagedAgentsBase64ImageSource` Base64-encoded image data. - `data: string` Base64-encoded image data. - `media_type: string` MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). - `type: "base64"` - `"base64"` - `BetaManagedAgentsURLImageSource` Image referenced by URL. - `type: "url"` - `"url"` - `url: string` URL of the image to fetch. - `BetaManagedAgentsFileImageSource` Image referenced by file ID. - `file_id: string` ID of a previously uploaded file. - `type: "file"` - `"file"` - `type: "image"` - `"image"` - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` Union type for document source variants. - `BetaManagedAgentsBase64DocumentSource` Base64-encoded document data. - `data: string` Base64-encoded document data. - `media_type: string` MIME type of the document (e.g., "application/pdf"). - `type: "base64"` - `"base64"` - `BetaManagedAgentsPlainTextDocumentSource` Plain text document content. - `data: string` The plain text content. - `media_type: "text/plain"` MIME type of the text content. Must be "text/plain". - `"text/plain"` - `type: "text"` - `"text"` - `BetaManagedAgentsURLDocumentSource` Document referenced by URL. - `type: "url"` - `"url"` - `url: string` URL of the document to fetch. - `BetaManagedAgentsFileDocumentSource` Document referenced by file ID. - `file_id: string` ID of a previously uploaded file. - `type: "file"` - `"file"` - `type: "document"` - `"document"` - `context?: string | null` Additional context about the document for the model. - `title?: string | null` The title of the document. - `type: "user.message"` - `"user.message"` - `processed_at?: string | null` A timestamp in RFC 3339 format - `BetaManagedAgentsUserInterruptEvent` An interrupt event that pauses agent execution and returns control to the user. - `id: string` Unique identifier for this event. - `type: "user.interrupt"` - `"user.interrupt"` - `processed_at?: string | null` A timestamp in RFC 3339 format - `session_thread_id?: string | null` If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread. - `BetaManagedAgentsUserToolConfirmationEvent` A tool confirmation event that approves or denies a pending tool execution. - `id: string` Unique identifier for this event. - `result: "allow" | "deny"` UserToolConfirmationResult enum - `"allow"` - `"deny"` - `tool_use_id: string` The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `type: "user.tool_confirmation"` - `"user.tool_confirmation"` - `deny_message?: string | null` Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. - `processed_at?: string | null` A timestamp in RFC 3339 format - `session_thread_id?: string | null` When set, the confirmation routes to this subagent's thread rather than the primary. Echo this from the `session_thread_id` on the `agent.tool_use` or `agent.mcp_tool_use` event that prompted the approval. - `BetaManagedAgentsUserCustomToolResultEvent` Event sent by the client providing the result of a custom tool execution. - `id: string` Unique identifier for this event. - `custom_tool_use_id: string` The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `type: "user.custom_tool_result"` - `"user.custom_tool_result"` - `content?: Array` The result content returned by the tool. - `BetaManagedAgentsTextBlock` Regular text content. - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `BetaManagedAgentsSearchResultBlock` A block containing a web search result. - `citations: BetaManagedAgentsSearchResultCitations` Citation settings for a search result. - `enabled: boolean` Whether citations are enabled for this search result. - `content: Array` Array of text content blocks from the search result. - `text: string` The text content. - `type: "text"` - `"text"` - `source: string` The URL source of the search result. - `title: string` The title of the search result. - `type: "search_result"` - `"search_result"` - `is_error?: boolean | null` Whether the tool execution resulted in an error. - `processed_at?: string | null` A timestamp in RFC 3339 format - `session_thread_id?: string | null` Routes this result to a subagent thread. Copy from the `agent.custom_tool_use` event's `session_thread_id`. - `BetaManagedAgentsAgentCustomToolUseEvent` Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. - `id: string` Unique identifier for this event. - `input: Record` Input parameters for the tool call. - `name: string` Name of the custom tool being called. - `processed_at: string` A timestamp in RFC 3339 format - `type: "agent.custom_tool_use"` - `"agent.custom_tool_use"` - `session_thread_id?: string | null` When set, this event was cross-posted from a subagent's thread to surface its custom tool use on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.custom_tool_result` event to route the result back. - `BetaManagedAgentsAgentMessageEvent` An agent response event in the session conversation. - `id: string` Unique identifier for this event. - `content: Array` Array of text blocks comprising the agent response. - `text: string` The text content. - `type: "text"` - `processed_at: string` A timestamp in RFC 3339 format - `type: "agent.message"` - `"agent.message"` - `BetaManagedAgentsAgentThinkingEvent` Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `type: "agent.thinking"` - `"agent.thinking"` - `BetaManagedAgentsAgentMCPToolUseEvent` Event emitted when the agent invokes a tool provided by an MCP server. - `id: string` Unique identifier for this event. - `input: Record` Input parameters for the tool call. - `mcp_server_name: string` Name of the MCP server providing the tool. - `name: string` Name of the MCP tool being used. - `processed_at: string` A timestamp in RFC 3339 format - `type: "agent.mcp_tool_use"` - `"agent.mcp_tool_use"` - `evaluated_permission?: "allow" | "ask" | "deny"` AgentEvaluatedPermission enum - `"allow"` - `"ask"` - `"deny"` - `session_thread_id?: string | null` When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.tool_confirmation` event to route the approval back. - `BetaManagedAgentsAgentMCPToolResultEvent` Event representing the result of an MCP tool execution. - `id: string` Unique identifier for this event. - `mcp_tool_use_id: string` The id of the `agent.mcp_tool_use` event this result corresponds to. - `processed_at: string` A timestamp in RFC 3339 format - `type: "agent.mcp_tool_result"` - `"agent.mcp_tool_result"` - `content?: Array` The result content returned by the tool. - `BetaManagedAgentsTextBlock` Regular text content. - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `BetaManagedAgentsSearchResultBlock` A block containing a web search result. - `is_error?: boolean | null` Whether the tool execution resulted in an error. - `BetaManagedAgentsAgentToolUseEvent` Event emitted when the agent invokes a built-in agent tool. - `id: string` Unique identifier for this event. - `input: Record` Input parameters for the tool call. - `name: string` Name of the agent tool being used. - `processed_at: string` A timestamp in RFC 3339 format - `type: "agent.tool_use"` - `"agent.tool_use"` - `evaluated_permission?: "allow" | "ask" | "deny"` AgentEvaluatedPermission enum - `"allow"` - `"ask"` - `"deny"` - `session_thread_id?: string | null` When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.tool_confirmation` event to route the approval back. - `BetaManagedAgentsAgentToolResultEvent` Event representing the result of an agent tool execution. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `tool_use_id: string` The id of the `agent.tool_use` event this result corresponds to. - `type: "agent.tool_result"` - `"agent.tool_result"` - `content?: Array` The result content returned by the tool. - `BetaManagedAgentsTextBlock` Regular text content. - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `BetaManagedAgentsSearchResultBlock` A block containing a web search result. - `is_error?: boolean | null` Whether the tool execution resulted in an error. - `BetaManagedAgentsAgentThreadMessageReceivedEvent` Delivery event written to the target thread's input stream when an agent-to-agent message arrives. - `id: string` Unique identifier for this event. - `content: Array` Message content blocks. - `BetaManagedAgentsTextBlock` Regular text content. - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `from_session_thread_id: string` Public `sthr_` ID of the thread that sent the message. - `processed_at: string` A timestamp in RFC 3339 format - `type: "agent.thread_message_received"` - `"agent.thread_message_received"` - `from_agent_name?: string | null` Name of the callable agent this message came from. Absent when received from the primary agent. - `BetaManagedAgentsAgentThreadMessageSentEvent` Observability event emitted to the sender's output stream when an agent-to-agent message is sent. - `id: string` Unique identifier for this event. - `content: Array` Message content blocks. - `BetaManagedAgentsTextBlock` Regular text content. - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `processed_at: string` A timestamp in RFC 3339 format - `to_session_thread_id: string` Public `sthr_` ID of the thread the message was sent to. - `type: "agent.thread_message_sent"` - `"agent.thread_message_sent"` - `to_agent_name?: string | null` Name of the callable agent this message was sent to. Absent when sent to the primary agent. - `BetaManagedAgentsAgentThreadContextCompactedEvent` Indicates that context compaction (summarization) occurred during the session. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `type: "agent.thread_context_compacted"` - `"agent.thread_context_compacted"` - `BetaManagedAgentsSessionErrorEvent` An error event indicating a problem occurred during session execution. - `id: string` Unique identifier for this event. - `error: BetaManagedAgentsUnknownError | BetaManagedAgentsModelOverloadedError | BetaManagedAgentsModelRateLimitedError | 4 more` An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. - `BetaManagedAgentsUnknownError` An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` What the client should do next in response to this error. - `BetaManagedAgentsRetryStatusRetrying` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `type: "retrying"` - `"retrying"` - `BetaManagedAgentsRetryStatusExhausted` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `type: "exhausted"` - `"exhausted"` - `BetaManagedAgentsRetryStatusTerminal` The session encountered a terminal error and will transition to `terminated` state. - `type: "terminal"` - `"terminal"` - `type: "unknown_error"` - `"unknown_error"` - `BetaManagedAgentsModelOverloadedError` The model is currently overloaded. Emitted after automatic retries are exhausted. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` What the client should do next in response to this error. - `BetaManagedAgentsRetryStatusRetrying` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal` The session encountered a terminal error and will transition to `terminated` state. - `type: "model_overloaded_error"` - `"model_overloaded_error"` - `BetaManagedAgentsModelRateLimitedError` The model request was rate-limited. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` What the client should do next in response to this error. - `BetaManagedAgentsRetryStatusRetrying` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal` The session encountered a terminal error and will transition to `terminated` state. - `type: "model_rate_limited_error"` - `"model_rate_limited_error"` - `BetaManagedAgentsModelRequestFailedError` A model request failed for a reason other than overload or rate-limiting. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` What the client should do next in response to this error. - `BetaManagedAgentsRetryStatusRetrying` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal` The session encountered a terminal error and will transition to `terminated` state. - `type: "model_request_failed_error"` - `"model_request_failed_error"` - `BetaManagedAgentsMCPConnectionFailedError` Failed to connect to an MCP server. - `mcp_server_name: string` Name of the MCP server that failed to connect. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` What the client should do next in response to this error. - `BetaManagedAgentsRetryStatusRetrying` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal` The session encountered a terminal error and will transition to `terminated` state. - `type: "mcp_connection_failed_error"` - `"mcp_connection_failed_error"` - `BetaManagedAgentsMCPAuthenticationFailedError` Authentication to an MCP server failed. - `mcp_server_name: string` Name of the MCP server that failed authentication. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` What the client should do next in response to this error. - `BetaManagedAgentsRetryStatusRetrying` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal` The session encountered a terminal error and will transition to `terminated` state. - `type: "mcp_authentication_failed_error"` - `"mcp_authentication_failed_error"` - `BetaManagedAgentsBillingError` The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` What the client should do next in response to this error. - `BetaManagedAgentsRetryStatusRetrying` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal` The session encountered a terminal error and will transition to `terminated` state. - `type: "billing_error"` - `"billing_error"` - `processed_at: string` A timestamp in RFC 3339 format - `type: "session.error"` - `"session.error"` - `BetaManagedAgentsSessionStatusRescheduledEvent` Indicates the session is recovering from an error state and is rescheduled for execution. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `type: "session.status_rescheduled"` - `"session.status_rescheduled"` - `BetaManagedAgentsSessionStatusRunningEvent` Indicates the session is actively running and the agent is working. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `type: "session.status_running"` - `"session.status_running"` - `BetaManagedAgentsSessionStatusIdleEvent` Indicates the agent has paused and is awaiting user input. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `stop_reason: BetaManagedAgentsSessionEndTurn | BetaManagedAgentsSessionRequiresAction | BetaManagedAgentsSessionRetriesExhausted` The agent completed its turn naturally and is ready for the next user message. - `BetaManagedAgentsSessionEndTurn` The agent completed its turn naturally and is ready for the next user message. - `type: "end_turn"` - `"end_turn"` - `BetaManagedAgentsSessionRequiresAction` The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. - `event_ids: Array` The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. - `type: "requires_action"` - `"requires_action"` - `BetaManagedAgentsSessionRetriesExhausted` The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). - `type: "retries_exhausted"` - `"retries_exhausted"` - `type: "session.status_idle"` - `"session.status_idle"` - `BetaManagedAgentsSessionStatusTerminatedEvent` Indicates the session has terminated, either due to an error or completion. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `type: "session.status_terminated"` - `"session.status_terminated"` - `BetaManagedAgentsSessionThreadCreatedEvent` Emitted when a subagent is spawned as a new thread. Written to the parent thread's output stream so clients observing the session see child creation. - `id: string` Unique identifier for this event. - `agent_name: string` Name of the callable agent the thread runs. - `processed_at: string` A timestamp in RFC 3339 format - `session_thread_id: string` Public `sthr_` ID of the newly created thread. - `type: "session.thread_created"` - `"session.thread_created"` - `BetaManagedAgentsSpanOutcomeEvaluationStartEvent` Emitted when an outcome evaluation cycle begins. - `id: string` Unique identifier for this event. - `iteration: number` 0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc. - `outcome_id: string` The `outc_` ID of the outcome being evaluated. - `processed_at: string` A timestamp in RFC 3339 format - `type: "span.outcome_evaluation_start"` - `"span.outcome_evaluation_start"` - `BetaManagedAgentsSpanOutcomeEvaluationEndEvent` Emitted when an outcome evaluation cycle completes. Carries the verdict and aggregate token usage. A verdict of `needs_revision` means another evaluation cycle follows; `satisfied`, `max_iterations_reached`, `failed`, or `interrupted` are terminal — no further evaluation cycles follow. - `id: string` Unique identifier for this event. - `explanation: string` Human-readable explanation of the verdict. For `needs_revision`, describes which criteria failed and why. - `iteration: number` 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`. - `outcome_evaluation_start_id: string` The id of the corresponding `span.outcome_evaluation_start` event. - `outcome_id: string` The `outc_` ID of the outcome being evaluated. - `processed_at: string` A timestamp in RFC 3339 format - `result: string` Evaluation verdict. 'satisfied': criteria met, session goes idle. 'needs_revision': criteria not met, another revision cycle follows. 'max_iterations_reached': evaluation budget exhausted with criteria still unmet — one final acknowledgment turn follows before the session goes idle, but no further evaluation runs. 'failed': grader determined the rubric does not apply to the deliverables. 'interrupted': user sent an interrupt while evaluation was in progress. - `type: "span.outcome_evaluation_end"` - `"span.outcome_evaluation_end"` - `usage: BetaManagedAgentsSpanModelUsage` Token usage for a single model request. - `cache_creation_input_tokens: number` Tokens used to create prompt cache in this request. - `cache_read_input_tokens: number` Tokens read from prompt cache in this request. - `input_tokens: number` Input tokens consumed by this request. - `output_tokens: number` Output tokens generated by this request. - `speed?: "standard" | "fast" | null` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `BetaManagedAgentsSpanModelRequestStartEvent` Emitted when a model request is initiated by the agent. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `type: "span.model_request_start"` - `"span.model_request_start"` - `BetaManagedAgentsSpanModelRequestEndEvent` Emitted when a model request completes. - `id: string` Unique identifier for this event. - `is_error: boolean | null` Whether the model request resulted in an error. - `model_request_start_id: string` The id of the corresponding `span.model_request_start` event. - `model_usage: BetaManagedAgentsSpanModelUsage` Token usage for a single model request. - `processed_at: string` A timestamp in RFC 3339 format - `type: "span.model_request_end"` - `"span.model_request_end"` - `BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent` Periodic heartbeat emitted while an outcome evaluation cycle is in progress. Distinguishes 'evaluation is actively running' from 'evaluation is stuck' between the corresponding `span.outcome_evaluation_start` and `span.outcome_evaluation_end` events. - `id: string` Unique identifier for this event. - `iteration: number` 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`. - `outcome_id: string` The `outc_` ID of the outcome being evaluated. - `processed_at: string` A timestamp in RFC 3339 format - `type: "span.outcome_evaluation_ongoing"` - `"span.outcome_evaluation_ongoing"` - `BetaManagedAgentsUserDefineOutcomeEvent` Echo of a `user.define_outcome` input event. Carries the server-generated `outcome_id` that subsequent `span.outcome_evaluation_*` events reference. - `id: string` Unique identifier for this event. - `description: string` What the agent should produce. Copied from the input event. - `max_iterations: number | null` Evaluate-then-revise cycles before giving up. Default 3, max 20. - `outcome_id: string` Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list. - `processed_at: string` A timestamp in RFC 3339 format - `rubric: BetaManagedAgentsFileRubric | BetaManagedAgentsTextRubric` Rubric for grading the quality of an outcome. - `BetaManagedAgentsFileRubric` Rubric referenced by a file uploaded via the Files API. - `file_id: string` ID of the rubric file. - `type: "file"` - `"file"` - `BetaManagedAgentsTextRubric` Rubric content provided inline as text. - `content: string` Rubric content. Plain text or markdown — the grader treats it as freeform text. - `type: "text"` - `"text"` - `type: "user.define_outcome"` - `"user.define_outcome"` - `BetaManagedAgentsSessionDeletedEvent` Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `type: "session.deleted"` - `"session.deleted"` - `BetaManagedAgentsSessionThreadStatusRunningEvent` A session thread has begun executing. Emitted on the thread's own stream and cross-posted to the primary stream for child threads. - `id: string` Unique identifier for this event. - `agent_name: string` Name of the agent the thread runs. - `processed_at: string` A timestamp in RFC 3339 format - `session_thread_id: string` Public sthr_ ID of the thread that started running. - `type: "session.thread_status_running"` - `"session.thread_status_running"` - `BetaManagedAgentsSessionThreadStatusIdleEvent` A session thread has yielded and is awaiting input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads. - `id: string` Unique identifier for this event. - `agent_name: string` Name of the agent the thread runs. - `processed_at: string` A timestamp in RFC 3339 format - `session_thread_id: string` Public sthr_ ID of the thread that went idle. - `stop_reason: BetaManagedAgentsSessionEndTurn | BetaManagedAgentsSessionRequiresAction | BetaManagedAgentsSessionRetriesExhausted` The agent completed its turn naturally and is ready for the next user message. - `BetaManagedAgentsSessionEndTurn` The agent completed its turn naturally and is ready for the next user message. - `BetaManagedAgentsSessionRequiresAction` The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. - `BetaManagedAgentsSessionRetriesExhausted` The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). - `type: "session.thread_status_idle"` - `"session.thread_status_idle"` - `BetaManagedAgentsSessionThreadStatusTerminatedEvent` A session thread has terminated and will accept no further input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads. - `id: string` Unique identifier for this event. - `agent_name: string` Name of the agent the thread runs. - `processed_at: string` A timestamp in RFC 3339 format - `session_thread_id: string` Public sthr_ ID of the thread that terminated. - `type: "session.thread_status_terminated"` - `"session.thread_status_terminated"` - `BetaManagedAgentsUserToolResultEvent` Event sent by the client providing the result of an agent-toolset tool execution. Only valid on `self_hosted` environments, where sandbox-routed tools are executed by the client rather than the server. - `id: string` Unique identifier for this event. - `tool_use_id: string` The id of the `agent.tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `type: "user.tool_result"` - `"user.tool_result"` - `content?: Array` The result content returned by the tool. - `BetaManagedAgentsTextBlock` Regular text content. - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `BetaManagedAgentsSearchResultBlock` A block containing a web search result. - `is_error?: boolean | null` Whether the tool execution resulted in an error. - `processed_at?: string | null` A timestamp in RFC 3339 format - `session_thread_id?: string | null` Routes this result to a subagent thread. Copy from the `agent.tool_use` event's `session_thread_id`. - `BetaManagedAgentsSessionThreadStatusRescheduledEvent` A session thread hit a transient error and is retrying automatically. Emitted on the thread's own stream and cross-posted to the primary stream for child threads. - `id: string` Unique identifier for this event. - `agent_name: string` Name of the agent the thread runs. - `processed_at: string` A timestamp in RFC 3339 format - `session_thread_id: string` Public sthr_ ID of the thread that is retrying. - `type: "session.thread_status_rescheduled"` - `"session.thread_status_rescheduled"` - `BetaManagedAgentsSessionUpdatedEvent` Emitted when an UpdateSession request changed at least one field. Carries only the fields that changed; absent fields were not part of the update. The new configuration applies from the next turn. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `type: "session.updated"` - `"session.updated"` - `agent?: BetaManagedAgentsSessionAgent | null` Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. - `id: string` - `description: string | null` - `mcp_servers: Array` - `name: string` - `type: "url"` - `"url"` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `id: BetaManagedAgentsModel` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-opus-4-8" | "claude-opus-4-7" | "claude-opus-4-6" | 7 more` - `"claude-opus-4-8"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-7"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-6"` Most intelligent model for building agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` Fastest model with near-frontier intelligence - `"claude-haiku-4-5-20251001"` Fastest model with near-frontier intelligence - `"claude-opus-4-5"` Premium model combining maximum intelligence with practical performance - `"claude-opus-4-5-20251101"` Premium model combining maximum intelligence with practical performance - `"claude-sonnet-4-5"` High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` High-performance model for agents and coding - `(string & {})` - `speed?: "standard" | "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `multiagent: BetaManagedAgentsSessionMultiagentCoordinator | null` Resolved coordinator topology with full agent definitions for each roster member. - `agents: Array` Full `agent` definitions the coordinator may spawn as session threads. - `id: string` - `description: string | null` - `mcp_servers: Array` - `name: string` - `type: "url"` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `name: string` - `skills: Array` - `BetaManagedAgentsAnthropicSkill` A resolved Anthropic-managed skill. - `skill_id: string` - `type: "anthropic"` - `"anthropic"` - `version: string` - `BetaManagedAgentsCustomSkill` A resolved user-created custom skill. - `skill_id: string` - `type: "custom"` - `"custom"` - `version: string` - `system: string | null` - `tools: Array` - `BetaManagedAgentsAgentToolset20260401` - `configs: Array` - `enabled: boolean` - `name: "bash" | "edit" | "read" | 5 more` Built-in agent tool identifier. - `"bash"` - `"edit"` - `"read"` - `"write"` - `"glob"` - `"grep"` - `"web_fetch"` - `"web_search"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `"always_allow"` - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "always_ask"` - `"always_ask"` - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` Resolved default configuration for agent tools. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "agent_toolset_20260401"` - `"agent_toolset_20260401"` - `BetaManagedAgentsMCPToolset` - `configs: Array` - `enabled: boolean` - `name: string` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` Resolved default configuration for all tools from an MCP server. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `mcp_server_name: string` - `type: "mcp_toolset"` - `"mcp_toolset"` - `BetaManagedAgentsCustomTool` A custom tool as returned in API responses. - `description: string` - `input_schema: BetaManagedAgentsCustomToolInputSchema` JSON Schema for custom tool input parameters. - `properties?: Record | null` JSON Schema properties defining the tool's input parameters. - `required?: Array` List of required property names. - `type?: "object"` Must be 'object' for tool input schemas. - `"object"` - `name: string` - `type: "custom"` - `"custom"` - `type: "agent"` - `"agent"` - `version: number` - `type: "coordinator"` - `"coordinator"` - `name: string` - `skills: Array` - `BetaManagedAgentsAnthropicSkill` A resolved Anthropic-managed skill. - `BetaManagedAgentsCustomSkill` A resolved user-created custom skill. - `system: string | null` - `tools: Array` - `BetaManagedAgentsAgentToolset20260401` - `BetaManagedAgentsMCPToolset` - `BetaManagedAgentsCustomTool` A custom tool as returned in API responses. - `type: "agent"` - `"agent"` - `version: number` - `metadata?: Record` The session's full metadata bag after the update. Present when the update set non-empty metadata; absent when metadata was unchanged or cleared to empty. - `title?: string | null` The session's new title. Present only when the update changed it. # Events ## List Session Thread Events `client.beta.sessions.threads.events.list(stringthreadID, EventListParamsparams, RequestOptionsoptions?): PageCursor` **get** `/v1/sessions/{session_id}/threads/{thread_id}/events` List Session Thread Events ### Parameters - `threadID: string` - `params: EventListParams` - `session_id: string` Path param: Path parameter session_id - `limit?: number` Query param: Query parameter for limit - `page?: string` Query param: Query parameter for page - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaManagedAgentsSessionEvent = BetaManagedAgentsUserMessageEvent | BetaManagedAgentsUserInterruptEvent | BetaManagedAgentsUserToolConfirmationEvent | 30 more` Union type for all event types in a session. - `BetaManagedAgentsUserMessageEvent` A user message event in the session conversation. - `id: string` Unique identifier for this event. - `content: Array` Array of content blocks comprising the user message. - `BetaManagedAgentsTextBlock` Regular text content. - `text: string` The text content. - `type: "text"` - `"text"` - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` Union type for image source variants. - `BetaManagedAgentsBase64ImageSource` Base64-encoded image data. - `data: string` Base64-encoded image data. - `media_type: string` MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). - `type: "base64"` - `"base64"` - `BetaManagedAgentsURLImageSource` Image referenced by URL. - `type: "url"` - `"url"` - `url: string` URL of the image to fetch. - `BetaManagedAgentsFileImageSource` Image referenced by file ID. - `file_id: string` ID of a previously uploaded file. - `type: "file"` - `"file"` - `type: "image"` - `"image"` - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` Union type for document source variants. - `BetaManagedAgentsBase64DocumentSource` Base64-encoded document data. - `data: string` Base64-encoded document data. - `media_type: string` MIME type of the document (e.g., "application/pdf"). - `type: "base64"` - `"base64"` - `BetaManagedAgentsPlainTextDocumentSource` Plain text document content. - `data: string` The plain text content. - `media_type: "text/plain"` MIME type of the text content. Must be "text/plain". - `"text/plain"` - `type: "text"` - `"text"` - `BetaManagedAgentsURLDocumentSource` Document referenced by URL. - `type: "url"` - `"url"` - `url: string` URL of the document to fetch. - `BetaManagedAgentsFileDocumentSource` Document referenced by file ID. - `file_id: string` ID of a previously uploaded file. - `type: "file"` - `"file"` - `type: "document"` - `"document"` - `context?: string | null` Additional context about the document for the model. - `title?: string | null` The title of the document. - `type: "user.message"` - `"user.message"` - `processed_at?: string | null` A timestamp in RFC 3339 format - `BetaManagedAgentsUserInterruptEvent` An interrupt event that pauses agent execution and returns control to the user. - `id: string` Unique identifier for this event. - `type: "user.interrupt"` - `"user.interrupt"` - `processed_at?: string | null` A timestamp in RFC 3339 format - `session_thread_id?: string | null` If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread. - `BetaManagedAgentsUserToolConfirmationEvent` A tool confirmation event that approves or denies a pending tool execution. - `id: string` Unique identifier for this event. - `result: "allow" | "deny"` UserToolConfirmationResult enum - `"allow"` - `"deny"` - `tool_use_id: string` The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `type: "user.tool_confirmation"` - `"user.tool_confirmation"` - `deny_message?: string | null` Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. - `processed_at?: string | null` A timestamp in RFC 3339 format - `session_thread_id?: string | null` When set, the confirmation routes to this subagent's thread rather than the primary. Echo this from the `session_thread_id` on the `agent.tool_use` or `agent.mcp_tool_use` event that prompted the approval. - `BetaManagedAgentsUserCustomToolResultEvent` Event sent by the client providing the result of a custom tool execution. - `id: string` Unique identifier for this event. - `custom_tool_use_id: string` The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `type: "user.custom_tool_result"` - `"user.custom_tool_result"` - `content?: Array` The result content returned by the tool. - `BetaManagedAgentsTextBlock` Regular text content. - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `BetaManagedAgentsSearchResultBlock` A block containing a web search result. - `citations: BetaManagedAgentsSearchResultCitations` Citation settings for a search result. - `enabled: boolean` Whether citations are enabled for this search result. - `content: Array` Array of text content blocks from the search result. - `text: string` The text content. - `type: "text"` - `"text"` - `source: string` The URL source of the search result. - `title: string` The title of the search result. - `type: "search_result"` - `"search_result"` - `is_error?: boolean | null` Whether the tool execution resulted in an error. - `processed_at?: string | null` A timestamp in RFC 3339 format - `session_thread_id?: string | null` Routes this result to a subagent thread. Copy from the `agent.custom_tool_use` event's `session_thread_id`. - `BetaManagedAgentsAgentCustomToolUseEvent` Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. - `id: string` Unique identifier for this event. - `input: Record` Input parameters for the tool call. - `name: string` Name of the custom tool being called. - `processed_at: string` A timestamp in RFC 3339 format - `type: "agent.custom_tool_use"` - `"agent.custom_tool_use"` - `session_thread_id?: string | null` When set, this event was cross-posted from a subagent's thread to surface its custom tool use on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.custom_tool_result` event to route the result back. - `BetaManagedAgentsAgentMessageEvent` An agent response event in the session conversation. - `id: string` Unique identifier for this event. - `content: Array` Array of text blocks comprising the agent response. - `text: string` The text content. - `type: "text"` - `processed_at: string` A timestamp in RFC 3339 format - `type: "agent.message"` - `"agent.message"` - `BetaManagedAgentsAgentThinkingEvent` Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `type: "agent.thinking"` - `"agent.thinking"` - `BetaManagedAgentsAgentMCPToolUseEvent` Event emitted when the agent invokes a tool provided by an MCP server. - `id: string` Unique identifier for this event. - `input: Record` Input parameters for the tool call. - `mcp_server_name: string` Name of the MCP server providing the tool. - `name: string` Name of the MCP tool being used. - `processed_at: string` A timestamp in RFC 3339 format - `type: "agent.mcp_tool_use"` - `"agent.mcp_tool_use"` - `evaluated_permission?: "allow" | "ask" | "deny"` AgentEvaluatedPermission enum - `"allow"` - `"ask"` - `"deny"` - `session_thread_id?: string | null` When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.tool_confirmation` event to route the approval back. - `BetaManagedAgentsAgentMCPToolResultEvent` Event representing the result of an MCP tool execution. - `id: string` Unique identifier for this event. - `mcp_tool_use_id: string` The id of the `agent.mcp_tool_use` event this result corresponds to. - `processed_at: string` A timestamp in RFC 3339 format - `type: "agent.mcp_tool_result"` - `"agent.mcp_tool_result"` - `content?: Array` The result content returned by the tool. - `BetaManagedAgentsTextBlock` Regular text content. - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `BetaManagedAgentsSearchResultBlock` A block containing a web search result. - `is_error?: boolean | null` Whether the tool execution resulted in an error. - `BetaManagedAgentsAgentToolUseEvent` Event emitted when the agent invokes a built-in agent tool. - `id: string` Unique identifier for this event. - `input: Record` Input parameters for the tool call. - `name: string` Name of the agent tool being used. - `processed_at: string` A timestamp in RFC 3339 format - `type: "agent.tool_use"` - `"agent.tool_use"` - `evaluated_permission?: "allow" | "ask" | "deny"` AgentEvaluatedPermission enum - `"allow"` - `"ask"` - `"deny"` - `session_thread_id?: string | null` When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.tool_confirmation` event to route the approval back. - `BetaManagedAgentsAgentToolResultEvent` Event representing the result of an agent tool execution. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `tool_use_id: string` The id of the `agent.tool_use` event this result corresponds to. - `type: "agent.tool_result"` - `"agent.tool_result"` - `content?: Array` The result content returned by the tool. - `BetaManagedAgentsTextBlock` Regular text content. - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `BetaManagedAgentsSearchResultBlock` A block containing a web search result. - `is_error?: boolean | null` Whether the tool execution resulted in an error. - `BetaManagedAgentsAgentThreadMessageReceivedEvent` Delivery event written to the target thread's input stream when an agent-to-agent message arrives. - `id: string` Unique identifier for this event. - `content: Array` Message content blocks. - `BetaManagedAgentsTextBlock` Regular text content. - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `from_session_thread_id: string` Public `sthr_` ID of the thread that sent the message. - `processed_at: string` A timestamp in RFC 3339 format - `type: "agent.thread_message_received"` - `"agent.thread_message_received"` - `from_agent_name?: string | null` Name of the callable agent this message came from. Absent when received from the primary agent. - `BetaManagedAgentsAgentThreadMessageSentEvent` Observability event emitted to the sender's output stream when an agent-to-agent message is sent. - `id: string` Unique identifier for this event. - `content: Array` Message content blocks. - `BetaManagedAgentsTextBlock` Regular text content. - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `processed_at: string` A timestamp in RFC 3339 format - `to_session_thread_id: string` Public `sthr_` ID of the thread the message was sent to. - `type: "agent.thread_message_sent"` - `"agent.thread_message_sent"` - `to_agent_name?: string | null` Name of the callable agent this message was sent to. Absent when sent to the primary agent. - `BetaManagedAgentsAgentThreadContextCompactedEvent` Indicates that context compaction (summarization) occurred during the session. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `type: "agent.thread_context_compacted"` - `"agent.thread_context_compacted"` - `BetaManagedAgentsSessionErrorEvent` An error event indicating a problem occurred during session execution. - `id: string` Unique identifier for this event. - `error: BetaManagedAgentsUnknownError | BetaManagedAgentsModelOverloadedError | BetaManagedAgentsModelRateLimitedError | 4 more` An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. - `BetaManagedAgentsUnknownError` An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` What the client should do next in response to this error. - `BetaManagedAgentsRetryStatusRetrying` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `type: "retrying"` - `"retrying"` - `BetaManagedAgentsRetryStatusExhausted` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `type: "exhausted"` - `"exhausted"` - `BetaManagedAgentsRetryStatusTerminal` The session encountered a terminal error and will transition to `terminated` state. - `type: "terminal"` - `"terminal"` - `type: "unknown_error"` - `"unknown_error"` - `BetaManagedAgentsModelOverloadedError` The model is currently overloaded. Emitted after automatic retries are exhausted. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` What the client should do next in response to this error. - `BetaManagedAgentsRetryStatusRetrying` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal` The session encountered a terminal error and will transition to `terminated` state. - `type: "model_overloaded_error"` - `"model_overloaded_error"` - `BetaManagedAgentsModelRateLimitedError` The model request was rate-limited. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` What the client should do next in response to this error. - `BetaManagedAgentsRetryStatusRetrying` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal` The session encountered a terminal error and will transition to `terminated` state. - `type: "model_rate_limited_error"` - `"model_rate_limited_error"` - `BetaManagedAgentsModelRequestFailedError` A model request failed for a reason other than overload or rate-limiting. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` What the client should do next in response to this error. - `BetaManagedAgentsRetryStatusRetrying` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal` The session encountered a terminal error and will transition to `terminated` state. - `type: "model_request_failed_error"` - `"model_request_failed_error"` - `BetaManagedAgentsMCPConnectionFailedError` Failed to connect to an MCP server. - `mcp_server_name: string` Name of the MCP server that failed to connect. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` What the client should do next in response to this error. - `BetaManagedAgentsRetryStatusRetrying` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal` The session encountered a terminal error and will transition to `terminated` state. - `type: "mcp_connection_failed_error"` - `"mcp_connection_failed_error"` - `BetaManagedAgentsMCPAuthenticationFailedError` Authentication to an MCP server failed. - `mcp_server_name: string` Name of the MCP server that failed authentication. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` What the client should do next in response to this error. - `BetaManagedAgentsRetryStatusRetrying` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal` The session encountered a terminal error and will transition to `terminated` state. - `type: "mcp_authentication_failed_error"` - `"mcp_authentication_failed_error"` - `BetaManagedAgentsBillingError` The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` What the client should do next in response to this error. - `BetaManagedAgentsRetryStatusRetrying` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal` The session encountered a terminal error and will transition to `terminated` state. - `type: "billing_error"` - `"billing_error"` - `processed_at: string` A timestamp in RFC 3339 format - `type: "session.error"` - `"session.error"` - `BetaManagedAgentsSessionStatusRescheduledEvent` Indicates the session is recovering from an error state and is rescheduled for execution. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `type: "session.status_rescheduled"` - `"session.status_rescheduled"` - `BetaManagedAgentsSessionStatusRunningEvent` Indicates the session is actively running and the agent is working. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `type: "session.status_running"` - `"session.status_running"` - `BetaManagedAgentsSessionStatusIdleEvent` Indicates the agent has paused and is awaiting user input. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `stop_reason: BetaManagedAgentsSessionEndTurn | BetaManagedAgentsSessionRequiresAction | BetaManagedAgentsSessionRetriesExhausted` The agent completed its turn naturally and is ready for the next user message. - `BetaManagedAgentsSessionEndTurn` The agent completed its turn naturally and is ready for the next user message. - `type: "end_turn"` - `"end_turn"` - `BetaManagedAgentsSessionRequiresAction` The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. - `event_ids: Array` The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. - `type: "requires_action"` - `"requires_action"` - `BetaManagedAgentsSessionRetriesExhausted` The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). - `type: "retries_exhausted"` - `"retries_exhausted"` - `type: "session.status_idle"` - `"session.status_idle"` - `BetaManagedAgentsSessionStatusTerminatedEvent` Indicates the session has terminated, either due to an error or completion. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `type: "session.status_terminated"` - `"session.status_terminated"` - `BetaManagedAgentsSessionThreadCreatedEvent` Emitted when a subagent is spawned as a new thread. Written to the parent thread's output stream so clients observing the session see child creation. - `id: string` Unique identifier for this event. - `agent_name: string` Name of the callable agent the thread runs. - `processed_at: string` A timestamp in RFC 3339 format - `session_thread_id: string` Public `sthr_` ID of the newly created thread. - `type: "session.thread_created"` - `"session.thread_created"` - `BetaManagedAgentsSpanOutcomeEvaluationStartEvent` Emitted when an outcome evaluation cycle begins. - `id: string` Unique identifier for this event. - `iteration: number` 0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc. - `outcome_id: string` The `outc_` ID of the outcome being evaluated. - `processed_at: string` A timestamp in RFC 3339 format - `type: "span.outcome_evaluation_start"` - `"span.outcome_evaluation_start"` - `BetaManagedAgentsSpanOutcomeEvaluationEndEvent` Emitted when an outcome evaluation cycle completes. Carries the verdict and aggregate token usage. A verdict of `needs_revision` means another evaluation cycle follows; `satisfied`, `max_iterations_reached`, `failed`, or `interrupted` are terminal — no further evaluation cycles follow. - `id: string` Unique identifier for this event. - `explanation: string` Human-readable explanation of the verdict. For `needs_revision`, describes which criteria failed and why. - `iteration: number` 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`. - `outcome_evaluation_start_id: string` The id of the corresponding `span.outcome_evaluation_start` event. - `outcome_id: string` The `outc_` ID of the outcome being evaluated. - `processed_at: string` A timestamp in RFC 3339 format - `result: string` Evaluation verdict. 'satisfied': criteria met, session goes idle. 'needs_revision': criteria not met, another revision cycle follows. 'max_iterations_reached': evaluation budget exhausted with criteria still unmet — one final acknowledgment turn follows before the session goes idle, but no further evaluation runs. 'failed': grader determined the rubric does not apply to the deliverables. 'interrupted': user sent an interrupt while evaluation was in progress. - `type: "span.outcome_evaluation_end"` - `"span.outcome_evaluation_end"` - `usage: BetaManagedAgentsSpanModelUsage` Token usage for a single model request. - `cache_creation_input_tokens: number` Tokens used to create prompt cache in this request. - `cache_read_input_tokens: number` Tokens read from prompt cache in this request. - `input_tokens: number` Input tokens consumed by this request. - `output_tokens: number` Output tokens generated by this request. - `speed?: "standard" | "fast" | null` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `BetaManagedAgentsSpanModelRequestStartEvent` Emitted when a model request is initiated by the agent. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `type: "span.model_request_start"` - `"span.model_request_start"` - `BetaManagedAgentsSpanModelRequestEndEvent` Emitted when a model request completes. - `id: string` Unique identifier for this event. - `is_error: boolean | null` Whether the model request resulted in an error. - `model_request_start_id: string` The id of the corresponding `span.model_request_start` event. - `model_usage: BetaManagedAgentsSpanModelUsage` Token usage for a single model request. - `processed_at: string` A timestamp in RFC 3339 format - `type: "span.model_request_end"` - `"span.model_request_end"` - `BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent` Periodic heartbeat emitted while an outcome evaluation cycle is in progress. Distinguishes 'evaluation is actively running' from 'evaluation is stuck' between the corresponding `span.outcome_evaluation_start` and `span.outcome_evaluation_end` events. - `id: string` Unique identifier for this event. - `iteration: number` 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`. - `outcome_id: string` The `outc_` ID of the outcome being evaluated. - `processed_at: string` A timestamp in RFC 3339 format - `type: "span.outcome_evaluation_ongoing"` - `"span.outcome_evaluation_ongoing"` - `BetaManagedAgentsUserDefineOutcomeEvent` Echo of a `user.define_outcome` input event. Carries the server-generated `outcome_id` that subsequent `span.outcome_evaluation_*` events reference. - `id: string` Unique identifier for this event. - `description: string` What the agent should produce. Copied from the input event. - `max_iterations: number | null` Evaluate-then-revise cycles before giving up. Default 3, max 20. - `outcome_id: string` Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list. - `processed_at: string` A timestamp in RFC 3339 format - `rubric: BetaManagedAgentsFileRubric | BetaManagedAgentsTextRubric` Rubric for grading the quality of an outcome. - `BetaManagedAgentsFileRubric` Rubric referenced by a file uploaded via the Files API. - `file_id: string` ID of the rubric file. - `type: "file"` - `"file"` - `BetaManagedAgentsTextRubric` Rubric content provided inline as text. - `content: string` Rubric content. Plain text or markdown — the grader treats it as freeform text. - `type: "text"` - `"text"` - `type: "user.define_outcome"` - `"user.define_outcome"` - `BetaManagedAgentsSessionDeletedEvent` Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `type: "session.deleted"` - `"session.deleted"` - `BetaManagedAgentsSessionThreadStatusRunningEvent` A session thread has begun executing. Emitted on the thread's own stream and cross-posted to the primary stream for child threads. - `id: string` Unique identifier for this event. - `agent_name: string` Name of the agent the thread runs. - `processed_at: string` A timestamp in RFC 3339 format - `session_thread_id: string` Public sthr_ ID of the thread that started running. - `type: "session.thread_status_running"` - `"session.thread_status_running"` - `BetaManagedAgentsSessionThreadStatusIdleEvent` A session thread has yielded and is awaiting input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads. - `id: string` Unique identifier for this event. - `agent_name: string` Name of the agent the thread runs. - `processed_at: string` A timestamp in RFC 3339 format - `session_thread_id: string` Public sthr_ ID of the thread that went idle. - `stop_reason: BetaManagedAgentsSessionEndTurn | BetaManagedAgentsSessionRequiresAction | BetaManagedAgentsSessionRetriesExhausted` The agent completed its turn naturally and is ready for the next user message. - `BetaManagedAgentsSessionEndTurn` The agent completed its turn naturally and is ready for the next user message. - `BetaManagedAgentsSessionRequiresAction` The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. - `BetaManagedAgentsSessionRetriesExhausted` The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). - `type: "session.thread_status_idle"` - `"session.thread_status_idle"` - `BetaManagedAgentsSessionThreadStatusTerminatedEvent` A session thread has terminated and will accept no further input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads. - `id: string` Unique identifier for this event. - `agent_name: string` Name of the agent the thread runs. - `processed_at: string` A timestamp in RFC 3339 format - `session_thread_id: string` Public sthr_ ID of the thread that terminated. - `type: "session.thread_status_terminated"` - `"session.thread_status_terminated"` - `BetaManagedAgentsUserToolResultEvent` Event sent by the client providing the result of an agent-toolset tool execution. Only valid on `self_hosted` environments, where sandbox-routed tools are executed by the client rather than the server. - `id: string` Unique identifier for this event. - `tool_use_id: string` The id of the `agent.tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `type: "user.tool_result"` - `"user.tool_result"` - `content?: Array` The result content returned by the tool. - `BetaManagedAgentsTextBlock` Regular text content. - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `BetaManagedAgentsSearchResultBlock` A block containing a web search result. - `is_error?: boolean | null` Whether the tool execution resulted in an error. - `processed_at?: string | null` A timestamp in RFC 3339 format - `session_thread_id?: string | null` Routes this result to a subagent thread. Copy from the `agent.tool_use` event's `session_thread_id`. - `BetaManagedAgentsSessionThreadStatusRescheduledEvent` A session thread hit a transient error and is retrying automatically. Emitted on the thread's own stream and cross-posted to the primary stream for child threads. - `id: string` Unique identifier for this event. - `agent_name: string` Name of the agent the thread runs. - `processed_at: string` A timestamp in RFC 3339 format - `session_thread_id: string` Public sthr_ ID of the thread that is retrying. - `type: "session.thread_status_rescheduled"` - `"session.thread_status_rescheduled"` - `BetaManagedAgentsSessionUpdatedEvent` Emitted when an UpdateSession request changed at least one field. Carries only the fields that changed; absent fields were not part of the update. The new configuration applies from the next turn. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `type: "session.updated"` - `"session.updated"` - `agent?: BetaManagedAgentsSessionAgent | null` Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. - `id: string` - `description: string | null` - `mcp_servers: Array` - `name: string` - `type: "url"` - `"url"` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `id: BetaManagedAgentsModel` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-opus-4-8" | "claude-opus-4-7" | "claude-opus-4-6" | 7 more` - `"claude-opus-4-8"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-7"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-6"` Most intelligent model for building agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` Fastest model with near-frontier intelligence - `"claude-haiku-4-5-20251001"` Fastest model with near-frontier intelligence - `"claude-opus-4-5"` Premium model combining maximum intelligence with practical performance - `"claude-opus-4-5-20251101"` Premium model combining maximum intelligence with practical performance - `"claude-sonnet-4-5"` High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` High-performance model for agents and coding - `(string & {})` - `speed?: "standard" | "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `multiagent: BetaManagedAgentsSessionMultiagentCoordinator | null` Resolved coordinator topology with full agent definitions for each roster member. - `agents: Array` Full `agent` definitions the coordinator may spawn as session threads. - `id: string` - `description: string | null` - `mcp_servers: Array` - `name: string` - `type: "url"` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `name: string` - `skills: Array` - `BetaManagedAgentsAnthropicSkill` A resolved Anthropic-managed skill. - `skill_id: string` - `type: "anthropic"` - `"anthropic"` - `version: string` - `BetaManagedAgentsCustomSkill` A resolved user-created custom skill. - `skill_id: string` - `type: "custom"` - `"custom"` - `version: string` - `system: string | null` - `tools: Array` - `BetaManagedAgentsAgentToolset20260401` - `configs: Array` - `enabled: boolean` - `name: "bash" | "edit" | "read" | 5 more` Built-in agent tool identifier. - `"bash"` - `"edit"` - `"read"` - `"write"` - `"glob"` - `"grep"` - `"web_fetch"` - `"web_search"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `"always_allow"` - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "always_ask"` - `"always_ask"` - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` Resolved default configuration for agent tools. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "agent_toolset_20260401"` - `"agent_toolset_20260401"` - `BetaManagedAgentsMCPToolset` - `configs: Array` - `enabled: boolean` - `name: string` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` Resolved default configuration for all tools from an MCP server. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `mcp_server_name: string` - `type: "mcp_toolset"` - `"mcp_toolset"` - `BetaManagedAgentsCustomTool` A custom tool as returned in API responses. - `description: string` - `input_schema: BetaManagedAgentsCustomToolInputSchema` JSON Schema for custom tool input parameters. - `properties?: Record | null` JSON Schema properties defining the tool's input parameters. - `required?: Array` List of required property names. - `type?: "object"` Must be 'object' for tool input schemas. - `"object"` - `name: string` - `type: "custom"` - `"custom"` - `type: "agent"` - `"agent"` - `version: number` - `type: "coordinator"` - `"coordinator"` - `name: string` - `skills: Array` - `BetaManagedAgentsAnthropicSkill` A resolved Anthropic-managed skill. - `BetaManagedAgentsCustomSkill` A resolved user-created custom skill. - `system: string | null` - `tools: Array` - `BetaManagedAgentsAgentToolset20260401` - `BetaManagedAgentsMCPToolset` - `BetaManagedAgentsCustomTool` A custom tool as returned in API responses. - `type: "agent"` - `"agent"` - `version: number` - `metadata?: Record` The session's full metadata bag after the update. Present when the update set non-empty metadata; absent when metadata was unchanged or cleared to empty. - `title?: string | null` The session's new title. Present only when the update changed it. ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); // Automatically fetches more pages as needed. for await (const betaManagedAgentsSessionEvent of client.beta.sessions.threads.events.list( 'sthr_011CZkZVWa6oIjw0rgXZpnBt', { session_id: 'sesn_011CZkZAtmR3yMPDzynEDxu7' }, )) { console.log(betaManagedAgentsSessionEvent); } ``` #### Response ```json { "data": [ { "id": "sevt_011CZkZGOp0iBcp4kaQSihUmy", "content": [ { "text": "Where is my order #1234?", "type": "text" } ], "type": "user.message", "processed_at": "2026-03-15T10:00:00Z" } ], "next_page": "next_page" } ``` ## Stream Session Thread Events `client.beta.sessions.threads.events.stream(stringthreadID, EventStreamParamsparams, RequestOptionsoptions?): BetaManagedAgentsStreamSessionThreadEvents | Stream` **get** `/v1/sessions/{session_id}/threads/{thread_id}/stream` Stream Session Thread Events ### Parameters - `threadID: string` - `params: EventStreamParams` - `session_id: string` Path param: Path parameter session_id - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaManagedAgentsStreamSessionThreadEvents = BetaManagedAgentsUserMessageEvent | BetaManagedAgentsUserInterruptEvent | BetaManagedAgentsUserToolConfirmationEvent | 30 more` Server-sent event in a single thread's stream. - `BetaManagedAgentsUserMessageEvent` A user message event in the session conversation. - `id: string` Unique identifier for this event. - `content: Array` Array of content blocks comprising the user message. - `BetaManagedAgentsTextBlock` Regular text content. - `text: string` The text content. - `type: "text"` - `"text"` - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `source: BetaManagedAgentsBase64ImageSource | BetaManagedAgentsURLImageSource | BetaManagedAgentsFileImageSource` Union type for image source variants. - `BetaManagedAgentsBase64ImageSource` Base64-encoded image data. - `data: string` Base64-encoded image data. - `media_type: string` MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). - `type: "base64"` - `"base64"` - `BetaManagedAgentsURLImageSource` Image referenced by URL. - `type: "url"` - `"url"` - `url: string` URL of the image to fetch. - `BetaManagedAgentsFileImageSource` Image referenced by file ID. - `file_id: string` ID of a previously uploaded file. - `type: "file"` - `"file"` - `type: "image"` - `"image"` - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `source: BetaManagedAgentsBase64DocumentSource | BetaManagedAgentsPlainTextDocumentSource | BetaManagedAgentsURLDocumentSource | BetaManagedAgentsFileDocumentSource` Union type for document source variants. - `BetaManagedAgentsBase64DocumentSource` Base64-encoded document data. - `data: string` Base64-encoded document data. - `media_type: string` MIME type of the document (e.g., "application/pdf"). - `type: "base64"` - `"base64"` - `BetaManagedAgentsPlainTextDocumentSource` Plain text document content. - `data: string` The plain text content. - `media_type: "text/plain"` MIME type of the text content. Must be "text/plain". - `"text/plain"` - `type: "text"` - `"text"` - `BetaManagedAgentsURLDocumentSource` Document referenced by URL. - `type: "url"` - `"url"` - `url: string` URL of the document to fetch. - `BetaManagedAgentsFileDocumentSource` Document referenced by file ID. - `file_id: string` ID of a previously uploaded file. - `type: "file"` - `"file"` - `type: "document"` - `"document"` - `context?: string | null` Additional context about the document for the model. - `title?: string | null` The title of the document. - `type: "user.message"` - `"user.message"` - `processed_at?: string | null` A timestamp in RFC 3339 format - `BetaManagedAgentsUserInterruptEvent` An interrupt event that pauses agent execution and returns control to the user. - `id: string` Unique identifier for this event. - `type: "user.interrupt"` - `"user.interrupt"` - `processed_at?: string | null` A timestamp in RFC 3339 format - `session_thread_id?: string | null` If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread. - `BetaManagedAgentsUserToolConfirmationEvent` A tool confirmation event that approves or denies a pending tool execution. - `id: string` Unique identifier for this event. - `result: "allow" | "deny"` UserToolConfirmationResult enum - `"allow"` - `"deny"` - `tool_use_id: string` The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `type: "user.tool_confirmation"` - `"user.tool_confirmation"` - `deny_message?: string | null` Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. - `processed_at?: string | null` A timestamp in RFC 3339 format - `session_thread_id?: string | null` When set, the confirmation routes to this subagent's thread rather than the primary. Echo this from the `session_thread_id` on the `agent.tool_use` or `agent.mcp_tool_use` event that prompted the approval. - `BetaManagedAgentsUserCustomToolResultEvent` Event sent by the client providing the result of a custom tool execution. - `id: string` Unique identifier for this event. - `custom_tool_use_id: string` The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `type: "user.custom_tool_result"` - `"user.custom_tool_result"` - `content?: Array` The result content returned by the tool. - `BetaManagedAgentsTextBlock` Regular text content. - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `BetaManagedAgentsSearchResultBlock` A block containing a web search result. - `citations: BetaManagedAgentsSearchResultCitations` Citation settings for a search result. - `enabled: boolean` Whether citations are enabled for this search result. - `content: Array` Array of text content blocks from the search result. - `text: string` The text content. - `type: "text"` - `"text"` - `source: string` The URL source of the search result. - `title: string` The title of the search result. - `type: "search_result"` - `"search_result"` - `is_error?: boolean | null` Whether the tool execution resulted in an error. - `processed_at?: string | null` A timestamp in RFC 3339 format - `session_thread_id?: string | null` Routes this result to a subagent thread. Copy from the `agent.custom_tool_use` event's `session_thread_id`. - `BetaManagedAgentsAgentCustomToolUseEvent` Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result. - `id: string` Unique identifier for this event. - `input: Record` Input parameters for the tool call. - `name: string` Name of the custom tool being called. - `processed_at: string` A timestamp in RFC 3339 format - `type: "agent.custom_tool_use"` - `"agent.custom_tool_use"` - `session_thread_id?: string | null` When set, this event was cross-posted from a subagent's thread to surface its custom tool use on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.custom_tool_result` event to route the result back. - `BetaManagedAgentsAgentMessageEvent` An agent response event in the session conversation. - `id: string` Unique identifier for this event. - `content: Array` Array of text blocks comprising the agent response. - `text: string` The text content. - `type: "text"` - `processed_at: string` A timestamp in RFC 3339 format - `type: "agent.message"` - `"agent.message"` - `BetaManagedAgentsAgentThinkingEvent` Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `type: "agent.thinking"` - `"agent.thinking"` - `BetaManagedAgentsAgentMCPToolUseEvent` Event emitted when the agent invokes a tool provided by an MCP server. - `id: string` Unique identifier for this event. - `input: Record` Input parameters for the tool call. - `mcp_server_name: string` Name of the MCP server providing the tool. - `name: string` Name of the MCP tool being used. - `processed_at: string` A timestamp in RFC 3339 format - `type: "agent.mcp_tool_use"` - `"agent.mcp_tool_use"` - `evaluated_permission?: "allow" | "ask" | "deny"` AgentEvaluatedPermission enum - `"allow"` - `"ask"` - `"deny"` - `session_thread_id?: string | null` When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.tool_confirmation` event to route the approval back. - `BetaManagedAgentsAgentMCPToolResultEvent` Event representing the result of an MCP tool execution. - `id: string` Unique identifier for this event. - `mcp_tool_use_id: string` The id of the `agent.mcp_tool_use` event this result corresponds to. - `processed_at: string` A timestamp in RFC 3339 format - `type: "agent.mcp_tool_result"` - `"agent.mcp_tool_result"` - `content?: Array` The result content returned by the tool. - `BetaManagedAgentsTextBlock` Regular text content. - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `BetaManagedAgentsSearchResultBlock` A block containing a web search result. - `is_error?: boolean | null` Whether the tool execution resulted in an error. - `BetaManagedAgentsAgentToolUseEvent` Event emitted when the agent invokes a built-in agent tool. - `id: string` Unique identifier for this event. - `input: Record` Input parameters for the tool call. - `name: string` Name of the agent tool being used. - `processed_at: string` A timestamp in RFC 3339 format - `type: "agent.tool_use"` - `"agent.tool_use"` - `evaluated_permission?: "allow" | "ask" | "deny"` AgentEvaluatedPermission enum - `"allow"` - `"ask"` - `"deny"` - `session_thread_id?: string | null` When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.tool_confirmation` event to route the approval back. - `BetaManagedAgentsAgentToolResultEvent` Event representing the result of an agent tool execution. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `tool_use_id: string` The id of the `agent.tool_use` event this result corresponds to. - `type: "agent.tool_result"` - `"agent.tool_result"` - `content?: Array` The result content returned by the tool. - `BetaManagedAgentsTextBlock` Regular text content. - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `BetaManagedAgentsSearchResultBlock` A block containing a web search result. - `is_error?: boolean | null` Whether the tool execution resulted in an error. - `BetaManagedAgentsAgentThreadMessageReceivedEvent` Delivery event written to the target thread's input stream when an agent-to-agent message arrives. - `id: string` Unique identifier for this event. - `content: Array` Message content blocks. - `BetaManagedAgentsTextBlock` Regular text content. - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `from_session_thread_id: string` Public `sthr_` ID of the thread that sent the message. - `processed_at: string` A timestamp in RFC 3339 format - `type: "agent.thread_message_received"` - `"agent.thread_message_received"` - `from_agent_name?: string | null` Name of the callable agent this message came from. Absent when received from the primary agent. - `BetaManagedAgentsAgentThreadMessageSentEvent` Observability event emitted to the sender's output stream when an agent-to-agent message is sent. - `id: string` Unique identifier for this event. - `content: Array` Message content blocks. - `BetaManagedAgentsTextBlock` Regular text content. - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `processed_at: string` A timestamp in RFC 3339 format - `to_session_thread_id: string` Public `sthr_` ID of the thread the message was sent to. - `type: "agent.thread_message_sent"` - `"agent.thread_message_sent"` - `to_agent_name?: string | null` Name of the callable agent this message was sent to. Absent when sent to the primary agent. - `BetaManagedAgentsAgentThreadContextCompactedEvent` Indicates that context compaction (summarization) occurred during the session. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `type: "agent.thread_context_compacted"` - `"agent.thread_context_compacted"` - `BetaManagedAgentsSessionErrorEvent` An error event indicating a problem occurred during session execution. - `id: string` Unique identifier for this event. - `error: BetaManagedAgentsUnknownError | BetaManagedAgentsModelOverloadedError | BetaManagedAgentsModelRateLimitedError | 4 more` An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. - `BetaManagedAgentsUnknownError` An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` What the client should do next in response to this error. - `BetaManagedAgentsRetryStatusRetrying` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `type: "retrying"` - `"retrying"` - `BetaManagedAgentsRetryStatusExhausted` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `type: "exhausted"` - `"exhausted"` - `BetaManagedAgentsRetryStatusTerminal` The session encountered a terminal error and will transition to `terminated` state. - `type: "terminal"` - `"terminal"` - `type: "unknown_error"` - `"unknown_error"` - `BetaManagedAgentsModelOverloadedError` The model is currently overloaded. Emitted after automatic retries are exhausted. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` What the client should do next in response to this error. - `BetaManagedAgentsRetryStatusRetrying` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal` The session encountered a terminal error and will transition to `terminated` state. - `type: "model_overloaded_error"` - `"model_overloaded_error"` - `BetaManagedAgentsModelRateLimitedError` The model request was rate-limited. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` What the client should do next in response to this error. - `BetaManagedAgentsRetryStatusRetrying` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal` The session encountered a terminal error and will transition to `terminated` state. - `type: "model_rate_limited_error"` - `"model_rate_limited_error"` - `BetaManagedAgentsModelRequestFailedError` A model request failed for a reason other than overload or rate-limiting. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` What the client should do next in response to this error. - `BetaManagedAgentsRetryStatusRetrying` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal` The session encountered a terminal error and will transition to `terminated` state. - `type: "model_request_failed_error"` - `"model_request_failed_error"` - `BetaManagedAgentsMCPConnectionFailedError` Failed to connect to an MCP server. - `mcp_server_name: string` Name of the MCP server that failed to connect. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` What the client should do next in response to this error. - `BetaManagedAgentsRetryStatusRetrying` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal` The session encountered a terminal error and will transition to `terminated` state. - `type: "mcp_connection_failed_error"` - `"mcp_connection_failed_error"` - `BetaManagedAgentsMCPAuthenticationFailedError` Authentication to an MCP server failed. - `mcp_server_name: string` Name of the MCP server that failed authentication. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` What the client should do next in response to this error. - `BetaManagedAgentsRetryStatusRetrying` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal` The session encountered a terminal error and will transition to `terminated` state. - `type: "mcp_authentication_failed_error"` - `"mcp_authentication_failed_error"` - `BetaManagedAgentsBillingError` The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state. - `message: string` Human-readable error description. - `retry_status: BetaManagedAgentsRetryStatusRetrying | BetaManagedAgentsRetryStatusExhausted | BetaManagedAgentsRetryStatusTerminal` What the client should do next in response to this error. - `BetaManagedAgentsRetryStatusRetrying` The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out. - `BetaManagedAgentsRetryStatusExhausted` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - `BetaManagedAgentsRetryStatusTerminal` The session encountered a terminal error and will transition to `terminated` state. - `type: "billing_error"` - `"billing_error"` - `processed_at: string` A timestamp in RFC 3339 format - `type: "session.error"` - `"session.error"` - `BetaManagedAgentsSessionStatusRescheduledEvent` Indicates the session is recovering from an error state and is rescheduled for execution. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `type: "session.status_rescheduled"` - `"session.status_rescheduled"` - `BetaManagedAgentsSessionStatusRunningEvent` Indicates the session is actively running and the agent is working. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `type: "session.status_running"` - `"session.status_running"` - `BetaManagedAgentsSessionStatusIdleEvent` Indicates the agent has paused and is awaiting user input. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `stop_reason: BetaManagedAgentsSessionEndTurn | BetaManagedAgentsSessionRequiresAction | BetaManagedAgentsSessionRetriesExhausted` The agent completed its turn naturally and is ready for the next user message. - `BetaManagedAgentsSessionEndTurn` The agent completed its turn naturally and is ready for the next user message. - `type: "end_turn"` - `"end_turn"` - `BetaManagedAgentsSessionRequiresAction` The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. - `event_ids: Array` The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder. - `type: "requires_action"` - `"requires_action"` - `BetaManagedAgentsSessionRetriesExhausted` The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). - `type: "retries_exhausted"` - `"retries_exhausted"` - `type: "session.status_idle"` - `"session.status_idle"` - `BetaManagedAgentsSessionStatusTerminatedEvent` Indicates the session has terminated, either due to an error or completion. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `type: "session.status_terminated"` - `"session.status_terminated"` - `BetaManagedAgentsSessionThreadCreatedEvent` Emitted when a subagent is spawned as a new thread. Written to the parent thread's output stream so clients observing the session see child creation. - `id: string` Unique identifier for this event. - `agent_name: string` Name of the callable agent the thread runs. - `processed_at: string` A timestamp in RFC 3339 format - `session_thread_id: string` Public `sthr_` ID of the newly created thread. - `type: "session.thread_created"` - `"session.thread_created"` - `BetaManagedAgentsSpanOutcomeEvaluationStartEvent` Emitted when an outcome evaluation cycle begins. - `id: string` Unique identifier for this event. - `iteration: number` 0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc. - `outcome_id: string` The `outc_` ID of the outcome being evaluated. - `processed_at: string` A timestamp in RFC 3339 format - `type: "span.outcome_evaluation_start"` - `"span.outcome_evaluation_start"` - `BetaManagedAgentsSpanOutcomeEvaluationEndEvent` Emitted when an outcome evaluation cycle completes. Carries the verdict and aggregate token usage. A verdict of `needs_revision` means another evaluation cycle follows; `satisfied`, `max_iterations_reached`, `failed`, or `interrupted` are terminal — no further evaluation cycles follow. - `id: string` Unique identifier for this event. - `explanation: string` Human-readable explanation of the verdict. For `needs_revision`, describes which criteria failed and why. - `iteration: number` 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`. - `outcome_evaluation_start_id: string` The id of the corresponding `span.outcome_evaluation_start` event. - `outcome_id: string` The `outc_` ID of the outcome being evaluated. - `processed_at: string` A timestamp in RFC 3339 format - `result: string` Evaluation verdict. 'satisfied': criteria met, session goes idle. 'needs_revision': criteria not met, another revision cycle follows. 'max_iterations_reached': evaluation budget exhausted with criteria still unmet — one final acknowledgment turn follows before the session goes idle, but no further evaluation runs. 'failed': grader determined the rubric does not apply to the deliverables. 'interrupted': user sent an interrupt while evaluation was in progress. - `type: "span.outcome_evaluation_end"` - `"span.outcome_evaluation_end"` - `usage: BetaManagedAgentsSpanModelUsage` Token usage for a single model request. - `cache_creation_input_tokens: number` Tokens used to create prompt cache in this request. - `cache_read_input_tokens: number` Tokens read from prompt cache in this request. - `input_tokens: number` Input tokens consumed by this request. - `output_tokens: number` Output tokens generated by this request. - `speed?: "standard" | "fast" | null` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `BetaManagedAgentsSpanModelRequestStartEvent` Emitted when a model request is initiated by the agent. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `type: "span.model_request_start"` - `"span.model_request_start"` - `BetaManagedAgentsSpanModelRequestEndEvent` Emitted when a model request completes. - `id: string` Unique identifier for this event. - `is_error: boolean | null` Whether the model request resulted in an error. - `model_request_start_id: string` The id of the corresponding `span.model_request_start` event. - `model_usage: BetaManagedAgentsSpanModelUsage` Token usage for a single model request. - `processed_at: string` A timestamp in RFC 3339 format - `type: "span.model_request_end"` - `"span.model_request_end"` - `BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent` Periodic heartbeat emitted while an outcome evaluation cycle is in progress. Distinguishes 'evaluation is actively running' from 'evaluation is stuck' between the corresponding `span.outcome_evaluation_start` and `span.outcome_evaluation_end` events. - `id: string` Unique identifier for this event. - `iteration: number` 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`. - `outcome_id: string` The `outc_` ID of the outcome being evaluated. - `processed_at: string` A timestamp in RFC 3339 format - `type: "span.outcome_evaluation_ongoing"` - `"span.outcome_evaluation_ongoing"` - `BetaManagedAgentsUserDefineOutcomeEvent` Echo of a `user.define_outcome` input event. Carries the server-generated `outcome_id` that subsequent `span.outcome_evaluation_*` events reference. - `id: string` Unique identifier for this event. - `description: string` What the agent should produce. Copied from the input event. - `max_iterations: number | null` Evaluate-then-revise cycles before giving up. Default 3, max 20. - `outcome_id: string` Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list. - `processed_at: string` A timestamp in RFC 3339 format - `rubric: BetaManagedAgentsFileRubric | BetaManagedAgentsTextRubric` Rubric for grading the quality of an outcome. - `BetaManagedAgentsFileRubric` Rubric referenced by a file uploaded via the Files API. - `file_id: string` ID of the rubric file. - `type: "file"` - `"file"` - `BetaManagedAgentsTextRubric` Rubric content provided inline as text. - `content: string` Rubric content. Plain text or markdown — the grader treats it as freeform text. - `type: "text"` - `"text"` - `type: "user.define_outcome"` - `"user.define_outcome"` - `BetaManagedAgentsSessionDeletedEvent` Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `type: "session.deleted"` - `"session.deleted"` - `BetaManagedAgentsSessionThreadStatusRunningEvent` A session thread has begun executing. Emitted on the thread's own stream and cross-posted to the primary stream for child threads. - `id: string` Unique identifier for this event. - `agent_name: string` Name of the agent the thread runs. - `processed_at: string` A timestamp in RFC 3339 format - `session_thread_id: string` Public sthr_ ID of the thread that started running. - `type: "session.thread_status_running"` - `"session.thread_status_running"` - `BetaManagedAgentsSessionThreadStatusIdleEvent` A session thread has yielded and is awaiting input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads. - `id: string` Unique identifier for this event. - `agent_name: string` Name of the agent the thread runs. - `processed_at: string` A timestamp in RFC 3339 format - `session_thread_id: string` Public sthr_ ID of the thread that went idle. - `stop_reason: BetaManagedAgentsSessionEndTurn | BetaManagedAgentsSessionRequiresAction | BetaManagedAgentsSessionRetriesExhausted` The agent completed its turn naturally and is ready for the next user message. - `BetaManagedAgentsSessionEndTurn` The agent completed its turn naturally and is ready for the next user message. - `BetaManagedAgentsSessionRequiresAction` The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running. - `BetaManagedAgentsSessionRetriesExhausted` The turn ended because the retry budget was exhausted (`max_iterations` hit or an error escalated to `retry_status: 'exhausted'`). - `type: "session.thread_status_idle"` - `"session.thread_status_idle"` - `BetaManagedAgentsSessionThreadStatusTerminatedEvent` A session thread has terminated and will accept no further input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads. - `id: string` Unique identifier for this event. - `agent_name: string` Name of the agent the thread runs. - `processed_at: string` A timestamp in RFC 3339 format - `session_thread_id: string` Public sthr_ ID of the thread that terminated. - `type: "session.thread_status_terminated"` - `"session.thread_status_terminated"` - `BetaManagedAgentsUserToolResultEvent` Event sent by the client providing the result of an agent-toolset tool execution. Only valid on `self_hosted` environments, where sandbox-routed tools are executed by the client rather than the server. - `id: string` Unique identifier for this event. - `tool_use_id: string` The id of the `agent.tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field. - `type: "user.tool_result"` - `"user.tool_result"` - `content?: Array` The result content returned by the tool. - `BetaManagedAgentsTextBlock` Regular text content. - `BetaManagedAgentsImageBlock` Image content specified directly as base64 data or as a reference via a URL. - `BetaManagedAgentsDocumentBlock` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - `BetaManagedAgentsSearchResultBlock` A block containing a web search result. - `is_error?: boolean | null` Whether the tool execution resulted in an error. - `processed_at?: string | null` A timestamp in RFC 3339 format - `session_thread_id?: string | null` Routes this result to a subagent thread. Copy from the `agent.tool_use` event's `session_thread_id`. - `BetaManagedAgentsSessionThreadStatusRescheduledEvent` A session thread hit a transient error and is retrying automatically. Emitted on the thread's own stream and cross-posted to the primary stream for child threads. - `id: string` Unique identifier for this event. - `agent_name: string` Name of the agent the thread runs. - `processed_at: string` A timestamp in RFC 3339 format - `session_thread_id: string` Public sthr_ ID of the thread that is retrying. - `type: "session.thread_status_rescheduled"` - `"session.thread_status_rescheduled"` - `BetaManagedAgentsSessionUpdatedEvent` Emitted when an UpdateSession request changed at least one field. Carries only the fields that changed; absent fields were not part of the update. The new configuration applies from the next turn. - `id: string` Unique identifier for this event. - `processed_at: string` A timestamp in RFC 3339 format - `type: "session.updated"` - `"session.updated"` - `agent?: BetaManagedAgentsSessionAgent | null` Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. - `id: string` - `description: string | null` - `mcp_servers: Array` - `name: string` - `type: "url"` - `"url"` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `id: BetaManagedAgentsModel` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-opus-4-8" | "claude-opus-4-7" | "claude-opus-4-6" | 7 more` - `"claude-opus-4-8"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-7"` Frontier intelligence for long-running agents and coding - `"claude-opus-4-6"` Most intelligent model for building agents and coding - `"claude-sonnet-4-6"` Best combination of speed and intelligence - `"claude-haiku-4-5"` Fastest model with near-frontier intelligence - `"claude-haiku-4-5-20251001"` Fastest model with near-frontier intelligence - `"claude-opus-4-5"` Premium model combining maximum intelligence with practical performance - `"claude-opus-4-5-20251101"` Premium model combining maximum intelligence with practical performance - `"claude-sonnet-4-5"` High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` High-performance model for agents and coding - `(string & {})` - `speed?: "standard" | "fast"` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `multiagent: BetaManagedAgentsSessionMultiagentCoordinator | null` Resolved coordinator topology with full agent definitions for each roster member. - `agents: Array` Full `agent` definitions the coordinator may spawn as session threads. - `id: string` - `description: string | null` - `mcp_servers: Array` - `name: string` - `type: "url"` - `url: string` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `name: string` - `skills: Array` - `BetaManagedAgentsAnthropicSkill` A resolved Anthropic-managed skill. - `skill_id: string` - `type: "anthropic"` - `"anthropic"` - `version: string` - `BetaManagedAgentsCustomSkill` A resolved user-created custom skill. - `skill_id: string` - `type: "custom"` - `"custom"` - `version: string` - `system: string | null` - `tools: Array` - `BetaManagedAgentsAgentToolset20260401` - `configs: Array` - `enabled: boolean` - `name: "bash" | "edit" | "read" | 5 more` Built-in agent tool identifier. - `"bash"` - `"edit"` - `"read"` - `"write"` - `"glob"` - `"grep"` - `"web_fetch"` - `"web_search"` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - `"always_allow"` - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "always_ask"` - `"always_ask"` - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` Resolved default configuration for agent tools. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `type: "agent_toolset_20260401"` - `"agent_toolset_20260401"` - `BetaManagedAgentsMCPToolset` - `configs: Array` - `enabled: boolean` - `name: string` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` Resolved default configuration for all tools from an MCP server. - `enabled: boolean` - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy | BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - `BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `mcp_server_name: string` - `type: "mcp_toolset"` - `"mcp_toolset"` - `BetaManagedAgentsCustomTool` A custom tool as returned in API responses. - `description: string` - `input_schema: BetaManagedAgentsCustomToolInputSchema` JSON Schema for custom tool input parameters. - `properties?: Record | null` JSON Schema properties defining the tool's input parameters. - `required?: Array` List of required property names. - `type?: "object"` Must be 'object' for tool input schemas. - `"object"` - `name: string` - `type: "custom"` - `"custom"` - `type: "agent"` - `"agent"` - `version: number` - `type: "coordinator"` - `"coordinator"` - `name: string` - `skills: Array` - `BetaManagedAgentsAnthropicSkill` A resolved Anthropic-managed skill. - `BetaManagedAgentsCustomSkill` A resolved user-created custom skill. - `system: string | null` - `tools: Array` - `BetaManagedAgentsAgentToolset20260401` - `BetaManagedAgentsMCPToolset` - `BetaManagedAgentsCustomTool` A custom tool as returned in API responses. - `type: "agent"` - `"agent"` - `version: number` - `metadata?: Record` The session's full metadata bag after the update. Present when the update set non-empty metadata; absent when metadata was unchanged or cleared to empty. - `title?: string | null` The session's new title. Present only when the update changed it. ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const betaManagedAgentsStreamSessionThreadEvents = await client.beta.sessions.threads.events.stream( 'sthr_011CZkZVWa6oIjw0rgXZpnBt', { session_id: 'sesn_011CZkZAtmR3yMPDzynEDxu7' }, ); console.log(betaManagedAgentsStreamSessionThreadEvents); ``` #### Response ```json { "id": "sevt_011CZkZGOp0iBcp4kaQSihUmy", "content": [ { "text": "Where is my order #1234?", "type": "text" } ], "type": "user.message", "processed_at": "2026-03-15T10:00:00Z" } ``` # Vaults ## Create Vault `client.beta.vaults.create(VaultCreateParamsparams, RequestOptionsoptions?): BetaManagedAgentsVault` **post** `/v1/vaults` Create Vault ### Parameters - `params: VaultCreateParams` - `display_name: string` Body param: Human-readable name for the vault. 1-255 characters. - `metadata?: Record` Body param: Arbitrary key-value metadata to attach to the vault. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars. - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaManagedAgentsVault` A vault that stores credentials for use by agents during sessions. - `id: string` Unique identifier for the vault. - `archived_at: string | null` A timestamp in RFC 3339 format - `created_at: string` A timestamp in RFC 3339 format - `display_name: string` Human-readable name for the vault. - `metadata: Record` Arbitrary key-value metadata attached to the vault. - `type: "vault"` - `"vault"` - `updated_at: string` A timestamp in RFC 3339 format ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const betaManagedAgentsVault = await client.beta.vaults.create({ display_name: 'Example vault' }); console.log(betaManagedAgentsVault.id); ``` #### Response ```json { "id": "vlt_011CZkZDLs7fYzm1hXNPeRjv", "archived_at": null, "created_at": "2026-03-15T10:00:00Z", "display_name": "Example vault", "metadata": { "environment": "production" }, "type": "vault", "updated_at": "2026-03-15T10:00:00Z" } ``` ## List Vaults `client.beta.vaults.list(VaultListParamsparams?, RequestOptionsoptions?): PageCursor` **get** `/v1/vaults` List Vaults ### Parameters - `params: VaultListParams` - `include_archived?: boolean` Query param: Whether to include archived vaults in the results. - `limit?: number` Query param: Maximum number of vaults to return per page. Defaults to 20, maximum 100. - `page?: string` Query param: Opaque pagination token from a previous `list_vaults` response. - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaManagedAgentsVault` A vault that stores credentials for use by agents during sessions. - `id: string` Unique identifier for the vault. - `archived_at: string | null` A timestamp in RFC 3339 format - `created_at: string` A timestamp in RFC 3339 format - `display_name: string` Human-readable name for the vault. - `metadata: Record` Arbitrary key-value metadata attached to the vault. - `type: "vault"` - `"vault"` - `updated_at: string` A timestamp in RFC 3339 format ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); // Automatically fetches more pages as needed. for await (const betaManagedAgentsVault of client.beta.vaults.list()) { console.log(betaManagedAgentsVault.id); } ``` #### Response ```json { "data": [ { "id": "vlt_011CZkZDLs7fYzm1hXNPeRjv", "archived_at": null, "created_at": "2026-03-15T10:00:00Z", "display_name": "Example vault", "metadata": { "environment": "production" }, "type": "vault", "updated_at": "2026-03-15T10:00:00Z" } ], "next_page": "page_MjAyNS0wNS0xNFQwMDowMDowMFo=" } ``` ## Get Vault `client.beta.vaults.retrieve(stringvaultID, VaultRetrieveParamsparams?, RequestOptionsoptions?): BetaManagedAgentsVault` **get** `/v1/vaults/{vault_id}` Get Vault ### Parameters - `vaultID: string` - `params: VaultRetrieveParams` - `betas?: Array` Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaManagedAgentsVault` A vault that stores credentials for use by agents during sessions. - `id: string` Unique identifier for the vault. - `archived_at: string | null` A timestamp in RFC 3339 format - `created_at: string` A timestamp in RFC 3339 format - `display_name: string` Human-readable name for the vault. - `metadata: Record` Arbitrary key-value metadata attached to the vault. - `type: "vault"` - `"vault"` - `updated_at: string` A timestamp in RFC 3339 format ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const betaManagedAgentsVault = await client.beta.vaults.retrieve('vlt_011CZkZDLs7fYzm1hXNPeRjv'); console.log(betaManagedAgentsVault.id); ``` #### Response ```json { "id": "vlt_011CZkZDLs7fYzm1hXNPeRjv", "archived_at": null, "created_at": "2026-03-15T10:00:00Z", "display_name": "Example vault", "metadata": { "environment": "production" }, "type": "vault", "updated_at": "2026-03-15T10:00:00Z" } ``` ## Update Vault `client.beta.vaults.update(stringvaultID, VaultUpdateParamsparams, RequestOptionsoptions?): BetaManagedAgentsVault` **post** `/v1/vaults/{vault_id}` Update Vault ### Parameters - `vaultID: string` - `params: VaultUpdateParams` - `display_name?: string | null` Body param: Updated human-readable name for the vault. 1-255 characters. - `metadata?: Record | null` Body param: Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omitted keys are preserved. - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaManagedAgentsVault` A vault that stores credentials for use by agents during sessions. - `id: string` Unique identifier for the vault. - `archived_at: string | null` A timestamp in RFC 3339 format - `created_at: string` A timestamp in RFC 3339 format - `display_name: string` Human-readable name for the vault. - `metadata: Record` Arbitrary key-value metadata attached to the vault. - `type: "vault"` - `"vault"` - `updated_at: string` A timestamp in RFC 3339 format ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const betaManagedAgentsVault = await client.beta.vaults.update('vlt_011CZkZDLs7fYzm1hXNPeRjv'); console.log(betaManagedAgentsVault.id); ``` #### Response ```json { "id": "vlt_011CZkZDLs7fYzm1hXNPeRjv", "archived_at": null, "created_at": "2026-03-15T10:00:00Z", "display_name": "Example vault", "metadata": { "environment": "production" }, "type": "vault", "updated_at": "2026-03-15T10:00:00Z" } ``` ## Delete Vault `client.beta.vaults.delete(stringvaultID, VaultDeleteParamsparams?, RequestOptionsoptions?): BetaManagedAgentsDeletedVault` **delete** `/v1/vaults/{vault_id}` Delete Vault ### Parameters - `vaultID: string` - `params: VaultDeleteParams` - `betas?: Array` Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaManagedAgentsDeletedVault` Confirmation of a deleted vault. - `id: string` Unique identifier of the deleted vault. - `type: "vault_deleted"` - `"vault_deleted"` ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const betaManagedAgentsDeletedVault = await client.beta.vaults.delete( 'vlt_011CZkZDLs7fYzm1hXNPeRjv', ); console.log(betaManagedAgentsDeletedVault.id); ``` #### Response ```json { "id": "vlt_011CZkZDLs7fYzm1hXNPeRjv", "type": "vault_deleted" } ``` ## Archive Vault `client.beta.vaults.archive(stringvaultID, VaultArchiveParamsparams?, RequestOptionsoptions?): BetaManagedAgentsVault` **post** `/v1/vaults/{vault_id}/archive` Archive Vault ### Parameters - `vaultID: string` - `params: VaultArchiveParams` - `betas?: Array` Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaManagedAgentsVault` A vault that stores credentials for use by agents during sessions. - `id: string` Unique identifier for the vault. - `archived_at: string | null` A timestamp in RFC 3339 format - `created_at: string` A timestamp in RFC 3339 format - `display_name: string` Human-readable name for the vault. - `metadata: Record` Arbitrary key-value metadata attached to the vault. - `type: "vault"` - `"vault"` - `updated_at: string` A timestamp in RFC 3339 format ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const betaManagedAgentsVault = await client.beta.vaults.archive('vlt_011CZkZDLs7fYzm1hXNPeRjv'); console.log(betaManagedAgentsVault.id); ``` #### Response ```json { "id": "vlt_011CZkZDLs7fYzm1hXNPeRjv", "archived_at": null, "created_at": "2026-03-15T10:00:00Z", "display_name": "Example vault", "metadata": { "environment": "production" }, "type": "vault", "updated_at": "2026-03-15T10:00:00Z" } ``` ## Domain Types ### Beta Managed Agents Deleted Vault - `BetaManagedAgentsDeletedVault` Confirmation of a deleted vault. - `id: string` Unique identifier of the deleted vault. - `type: "vault_deleted"` - `"vault_deleted"` ### Beta Managed Agents Vault - `BetaManagedAgentsVault` A vault that stores credentials for use by agents during sessions. - `id: string` Unique identifier for the vault. - `archived_at: string | null` A timestamp in RFC 3339 format - `created_at: string` A timestamp in RFC 3339 format - `display_name: string` Human-readable name for the vault. - `metadata: Record` Arbitrary key-value metadata attached to the vault. - `type: "vault"` - `"vault"` - `updated_at: string` A timestamp in RFC 3339 format # Credentials ## Create Credential `client.beta.vaults.credentials.create(stringvaultID, CredentialCreateParamsparams, RequestOptionsoptions?): BetaManagedAgentsCredential` **post** `/v1/vaults/{vault_id}/credentials` Create Credential ### Parameters - `vaultID: string` - `params: CredentialCreateParams` - `auth: BetaManagedAgentsMCPOAuthCreateParams | BetaManagedAgentsStaticBearerCreateParams` Body param: Authentication details for creating a credential. - `BetaManagedAgentsMCPOAuthCreateParams` Parameters for creating an MCP OAuth credential. - `access_token: string` OAuth access token. - `mcp_server_url: string` URL of the MCP server this credential authenticates against. - `type: "mcp_oauth"` - `"mcp_oauth"` - `expires_at?: string | null` A timestamp in RFC 3339 format - `refresh?: BetaManagedAgentsMCPOAuthRefreshParams | null` OAuth refresh token parameters for creating a credential with refresh support. - `client_id: string` OAuth client ID. - `refresh_token: string` OAuth refresh token. - `token_endpoint: string` Token endpoint URL used to refresh the access token. - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneParam | BetaManagedAgentsTokenEndpointAuthBasicParam | BetaManagedAgentsTokenEndpointAuthPostParam` Token endpoint requires no client authentication. - `BetaManagedAgentsTokenEndpointAuthNoneParam` Token endpoint requires no client authentication. - `type: "none"` - `"none"` - `BetaManagedAgentsTokenEndpointAuthBasicParam` Token endpoint uses HTTP Basic authentication with client credentials. - `client_secret: string` OAuth client secret. - `type: "client_secret_basic"` - `"client_secret_basic"` - `BetaManagedAgentsTokenEndpointAuthPostParam` Token endpoint uses POST body authentication with client credentials. - `client_secret: string` OAuth client secret. - `type: "client_secret_post"` - `"client_secret_post"` - `resource?: string | null` OAuth resource indicator. - `scope?: string | null` OAuth scope for the refresh request. - `BetaManagedAgentsStaticBearerCreateParams` Parameters for creating a static bearer token credential. - `token: string` Static bearer token value. - `mcp_server_url: string` URL of the MCP server this credential authenticates against. - `type: "static_bearer"` - `"static_bearer"` - `display_name?: string | null` Body param: Human-readable name for the credential. Up to 255 characters. - `metadata?: Record` Body param: Arbitrary key-value metadata to attach to the credential. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars. - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaManagedAgentsCredential` A credential stored in a vault. Sensitive fields are never returned in responses. - `id: string` Unique identifier for the credential. - `archived_at: string | null` A timestamp in RFC 3339 format - `auth: BetaManagedAgentsMCPOAuthAuthResponse | BetaManagedAgentsStaticBearerAuthResponse` Authentication details for a credential. - `BetaManagedAgentsMCPOAuthAuthResponse` OAuth credential details for an MCP server. - `mcp_server_url: string` URL of the MCP server this credential authenticates against. - `type: "mcp_oauth"` - `"mcp_oauth"` - `expires_at?: string | null` A timestamp in RFC 3339 format - `refresh?: BetaManagedAgentsMCPOAuthRefreshResponse | null` OAuth refresh token configuration returned in credential responses. - `client_id: string` OAuth client ID. - `token_endpoint: string` Token endpoint URL used to refresh the access token. - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse | BetaManagedAgentsTokenEndpointAuthBasicResponse | BetaManagedAgentsTokenEndpointAuthPostResponse` Token endpoint requires no client authentication. - `BetaManagedAgentsTokenEndpointAuthNoneResponse` Token endpoint requires no client authentication. - `type: "none"` - `"none"` - `BetaManagedAgentsTokenEndpointAuthBasicResponse` Token endpoint uses HTTP Basic authentication with client credentials. - `type: "client_secret_basic"` - `"client_secret_basic"` - `BetaManagedAgentsTokenEndpointAuthPostResponse` Token endpoint uses POST body authentication with client credentials. - `type: "client_secret_post"` - `"client_secret_post"` - `resource?: string | null` OAuth resource indicator. - `scope?: string | null` OAuth scope for the refresh request. - `BetaManagedAgentsStaticBearerAuthResponse` Static bearer token credential details for an MCP server. - `mcp_server_url: string` URL of the MCP server this credential authenticates against. - `type: "static_bearer"` - `"static_bearer"` - `created_at: string` A timestamp in RFC 3339 format - `metadata: Record` Arbitrary key-value metadata attached to the credential. - `type: "vault_credential"` - `"vault_credential"` - `updated_at: string` A timestamp in RFC 3339 format - `vault_id: string` Identifier of the vault this credential belongs to. - `display_name?: string | null` Human-readable name for the credential. ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const betaManagedAgentsCredential = await client.beta.vaults.credentials.create( 'vlt_011CZkZDLs7fYzm1hXNPeRjv', { auth: { token: 'bearer_exampletoken', mcp_server_url: 'https://example-server.modelcontextprotocol.io/sse', type: 'static_bearer', }, }, ); console.log(betaManagedAgentsCredential.id); ``` #### Response ```json { "id": "vcrd_011CZkZEMt8gZan2iYOQfSkw", "archived_at": null, "auth": { "mcp_server_url": "https://example-server.modelcontextprotocol.io/sse", "type": "static_bearer" }, "created_at": "2026-03-15T10:00:00Z", "metadata": { "environment": "production" }, "type": "vault_credential", "updated_at": "2026-03-15T10:00:00Z", "vault_id": "vlt_011CZkZDLs7fYzm1hXNPeRjv", "display_name": "Example credential" } ``` ## List Credentials `client.beta.vaults.credentials.list(stringvaultID, CredentialListParamsparams?, RequestOptionsoptions?): PageCursor` **get** `/v1/vaults/{vault_id}/credentials` List Credentials ### Parameters - `vaultID: string` - `params: CredentialListParams` - `include_archived?: boolean` Query param: Whether to include archived credentials in the results. - `limit?: number` Query param: Maximum number of credentials to return per page. Defaults to 20, maximum 100. - `page?: string` Query param: Opaque pagination token from a previous `list_credentials` response. - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaManagedAgentsCredential` A credential stored in a vault. Sensitive fields are never returned in responses. - `id: string` Unique identifier for the credential. - `archived_at: string | null` A timestamp in RFC 3339 format - `auth: BetaManagedAgentsMCPOAuthAuthResponse | BetaManagedAgentsStaticBearerAuthResponse` Authentication details for a credential. - `BetaManagedAgentsMCPOAuthAuthResponse` OAuth credential details for an MCP server. - `mcp_server_url: string` URL of the MCP server this credential authenticates against. - `type: "mcp_oauth"` - `"mcp_oauth"` - `expires_at?: string | null` A timestamp in RFC 3339 format - `refresh?: BetaManagedAgentsMCPOAuthRefreshResponse | null` OAuth refresh token configuration returned in credential responses. - `client_id: string` OAuth client ID. - `token_endpoint: string` Token endpoint URL used to refresh the access token. - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse | BetaManagedAgentsTokenEndpointAuthBasicResponse | BetaManagedAgentsTokenEndpointAuthPostResponse` Token endpoint requires no client authentication. - `BetaManagedAgentsTokenEndpointAuthNoneResponse` Token endpoint requires no client authentication. - `type: "none"` - `"none"` - `BetaManagedAgentsTokenEndpointAuthBasicResponse` Token endpoint uses HTTP Basic authentication with client credentials. - `type: "client_secret_basic"` - `"client_secret_basic"` - `BetaManagedAgentsTokenEndpointAuthPostResponse` Token endpoint uses POST body authentication with client credentials. - `type: "client_secret_post"` - `"client_secret_post"` - `resource?: string | null` OAuth resource indicator. - `scope?: string | null` OAuth scope for the refresh request. - `BetaManagedAgentsStaticBearerAuthResponse` Static bearer token credential details for an MCP server. - `mcp_server_url: string` URL of the MCP server this credential authenticates against. - `type: "static_bearer"` - `"static_bearer"` - `created_at: string` A timestamp in RFC 3339 format - `metadata: Record` Arbitrary key-value metadata attached to the credential. - `type: "vault_credential"` - `"vault_credential"` - `updated_at: string` A timestamp in RFC 3339 format - `vault_id: string` Identifier of the vault this credential belongs to. - `display_name?: string | null` Human-readable name for the credential. ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); // Automatically fetches more pages as needed. for await (const betaManagedAgentsCredential of client.beta.vaults.credentials.list( 'vlt_011CZkZDLs7fYzm1hXNPeRjv', )) { console.log(betaManagedAgentsCredential.id); } ``` #### Response ```json { "data": [ { "id": "vcrd_011CZkZEMt8gZan2iYOQfSkw", "archived_at": null, "auth": { "mcp_server_url": "https://example-server.modelcontextprotocol.io/sse", "type": "static_bearer" }, "created_at": "2026-03-15T10:00:00Z", "metadata": { "environment": "production" }, "type": "vault_credential", "updated_at": "2026-03-15T10:00:00Z", "vault_id": "vlt_011CZkZDLs7fYzm1hXNPeRjv", "display_name": "Example credential" } ], "next_page": "page_MjAyNS0wNS0xNFQwMDowMDowMFo=" } ``` ## Get Credential `client.beta.vaults.credentials.retrieve(stringcredentialID, CredentialRetrieveParamsparams, RequestOptionsoptions?): BetaManagedAgentsCredential` **get** `/v1/vaults/{vault_id}/credentials/{credential_id}` Get Credential ### Parameters - `credentialID: string` - `params: CredentialRetrieveParams` - `vault_id: string` Path param: Path parameter vault_id - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaManagedAgentsCredential` A credential stored in a vault. Sensitive fields are never returned in responses. - `id: string` Unique identifier for the credential. - `archived_at: string | null` A timestamp in RFC 3339 format - `auth: BetaManagedAgentsMCPOAuthAuthResponse | BetaManagedAgentsStaticBearerAuthResponse` Authentication details for a credential. - `BetaManagedAgentsMCPOAuthAuthResponse` OAuth credential details for an MCP server. - `mcp_server_url: string` URL of the MCP server this credential authenticates against. - `type: "mcp_oauth"` - `"mcp_oauth"` - `expires_at?: string | null` A timestamp in RFC 3339 format - `refresh?: BetaManagedAgentsMCPOAuthRefreshResponse | null` OAuth refresh token configuration returned in credential responses. - `client_id: string` OAuth client ID. - `token_endpoint: string` Token endpoint URL used to refresh the access token. - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse | BetaManagedAgentsTokenEndpointAuthBasicResponse | BetaManagedAgentsTokenEndpointAuthPostResponse` Token endpoint requires no client authentication. - `BetaManagedAgentsTokenEndpointAuthNoneResponse` Token endpoint requires no client authentication. - `type: "none"` - `"none"` - `BetaManagedAgentsTokenEndpointAuthBasicResponse` Token endpoint uses HTTP Basic authentication with client credentials. - `type: "client_secret_basic"` - `"client_secret_basic"` - `BetaManagedAgentsTokenEndpointAuthPostResponse` Token endpoint uses POST body authentication with client credentials. - `type: "client_secret_post"` - `"client_secret_post"` - `resource?: string | null` OAuth resource indicator. - `scope?: string | null` OAuth scope for the refresh request. - `BetaManagedAgentsStaticBearerAuthResponse` Static bearer token credential details for an MCP server. - `mcp_server_url: string` URL of the MCP server this credential authenticates against. - `type: "static_bearer"` - `"static_bearer"` - `created_at: string` A timestamp in RFC 3339 format - `metadata: Record` Arbitrary key-value metadata attached to the credential. - `type: "vault_credential"` - `"vault_credential"` - `updated_at: string` A timestamp in RFC 3339 format - `vault_id: string` Identifier of the vault this credential belongs to. - `display_name?: string | null` Human-readable name for the credential. ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const betaManagedAgentsCredential = await client.beta.vaults.credentials.retrieve( 'vcrd_011CZkZEMt8gZan2iYOQfSkw', { vault_id: 'vlt_011CZkZDLs7fYzm1hXNPeRjv' }, ); console.log(betaManagedAgentsCredential.id); ``` #### Response ```json { "id": "vcrd_011CZkZEMt8gZan2iYOQfSkw", "archived_at": null, "auth": { "mcp_server_url": "https://example-server.modelcontextprotocol.io/sse", "type": "static_bearer" }, "created_at": "2026-03-15T10:00:00Z", "metadata": { "environment": "production" }, "type": "vault_credential", "updated_at": "2026-03-15T10:00:00Z", "vault_id": "vlt_011CZkZDLs7fYzm1hXNPeRjv", "display_name": "Example credential" } ``` ## Update Credential `client.beta.vaults.credentials.update(stringcredentialID, CredentialUpdateParamsparams, RequestOptionsoptions?): BetaManagedAgentsCredential` **post** `/v1/vaults/{vault_id}/credentials/{credential_id}` Update Credential ### Parameters - `credentialID: string` - `params: CredentialUpdateParams` - `vault_id: string` Path param: Path parameter vault_id - `auth?: BetaManagedAgentsMCPOAuthUpdateParams | BetaManagedAgentsStaticBearerUpdateParams` Body param: Updated authentication details for a credential. - `BetaManagedAgentsMCPOAuthUpdateParams` Parameters for updating an MCP OAuth credential. The `mcp_server_url` is immutable. - `type: "mcp_oauth"` - `"mcp_oauth"` - `access_token?: string | null` Updated OAuth access token. - `expires_at?: string | null` A timestamp in RFC 3339 format - `refresh?: BetaManagedAgentsMCPOAuthRefreshUpdateParams | null` Parameters for updating OAuth refresh token configuration. - `refresh_token?: string | null` Updated OAuth refresh token. - `scope?: string | null` Updated OAuth scope for the refresh request. - `token_endpoint_auth?: BetaManagedAgentsTokenEndpointAuthBasicUpdateParam | BetaManagedAgentsTokenEndpointAuthPostUpdateParam` Updated HTTP Basic authentication parameters for the token endpoint. - `BetaManagedAgentsTokenEndpointAuthBasicUpdateParam` Updated HTTP Basic authentication parameters for the token endpoint. - `type: "client_secret_basic"` - `"client_secret_basic"` - `client_secret?: string | null` Updated OAuth client secret. - `BetaManagedAgentsTokenEndpointAuthPostUpdateParam` Updated POST body authentication parameters for the token endpoint. - `type: "client_secret_post"` - `"client_secret_post"` - `client_secret?: string | null` Updated OAuth client secret. - `BetaManagedAgentsStaticBearerUpdateParams` Parameters for updating a static bearer token credential. The `mcp_server_url` is immutable. - `type: "static_bearer"` - `"static_bearer"` - `token?: string | null` Updated static bearer token value. - `display_name?: string | null` Body param: Updated human-readable name for the credential. 1-255 characters. - `metadata?: Record | null` Body param: Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omitted keys are preserved. - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaManagedAgentsCredential` A credential stored in a vault. Sensitive fields are never returned in responses. - `id: string` Unique identifier for the credential. - `archived_at: string | null` A timestamp in RFC 3339 format - `auth: BetaManagedAgentsMCPOAuthAuthResponse | BetaManagedAgentsStaticBearerAuthResponse` Authentication details for a credential. - `BetaManagedAgentsMCPOAuthAuthResponse` OAuth credential details for an MCP server. - `mcp_server_url: string` URL of the MCP server this credential authenticates against. - `type: "mcp_oauth"` - `"mcp_oauth"` - `expires_at?: string | null` A timestamp in RFC 3339 format - `refresh?: BetaManagedAgentsMCPOAuthRefreshResponse | null` OAuth refresh token configuration returned in credential responses. - `client_id: string` OAuth client ID. - `token_endpoint: string` Token endpoint URL used to refresh the access token. - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse | BetaManagedAgentsTokenEndpointAuthBasicResponse | BetaManagedAgentsTokenEndpointAuthPostResponse` Token endpoint requires no client authentication. - `BetaManagedAgentsTokenEndpointAuthNoneResponse` Token endpoint requires no client authentication. - `type: "none"` - `"none"` - `BetaManagedAgentsTokenEndpointAuthBasicResponse` Token endpoint uses HTTP Basic authentication with client credentials. - `type: "client_secret_basic"` - `"client_secret_basic"` - `BetaManagedAgentsTokenEndpointAuthPostResponse` Token endpoint uses POST body authentication with client credentials. - `type: "client_secret_post"` - `"client_secret_post"` - `resource?: string | null` OAuth resource indicator. - `scope?: string | null` OAuth scope for the refresh request. - `BetaManagedAgentsStaticBearerAuthResponse` Static bearer token credential details for an MCP server. - `mcp_server_url: string` URL of the MCP server this credential authenticates against. - `type: "static_bearer"` - `"static_bearer"` - `created_at: string` A timestamp in RFC 3339 format - `metadata: Record` Arbitrary key-value metadata attached to the credential. - `type: "vault_credential"` - `"vault_credential"` - `updated_at: string` A timestamp in RFC 3339 format - `vault_id: string` Identifier of the vault this credential belongs to. - `display_name?: string | null` Human-readable name for the credential. ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const betaManagedAgentsCredential = await client.beta.vaults.credentials.update( 'vcrd_011CZkZEMt8gZan2iYOQfSkw', { vault_id: 'vlt_011CZkZDLs7fYzm1hXNPeRjv' }, ); console.log(betaManagedAgentsCredential.id); ``` #### Response ```json { "id": "vcrd_011CZkZEMt8gZan2iYOQfSkw", "archived_at": null, "auth": { "mcp_server_url": "https://example-server.modelcontextprotocol.io/sse", "type": "static_bearer" }, "created_at": "2026-03-15T10:00:00Z", "metadata": { "environment": "production" }, "type": "vault_credential", "updated_at": "2026-03-15T10:00:00Z", "vault_id": "vlt_011CZkZDLs7fYzm1hXNPeRjv", "display_name": "Example credential" } ``` ## Delete Credential `client.beta.vaults.credentials.delete(stringcredentialID, CredentialDeleteParamsparams, RequestOptionsoptions?): BetaManagedAgentsDeletedCredential` **delete** `/v1/vaults/{vault_id}/credentials/{credential_id}` Delete Credential ### Parameters - `credentialID: string` - `params: CredentialDeleteParams` - `vault_id: string` Path param: Path parameter vault_id - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaManagedAgentsDeletedCredential` Confirmation of a deleted credential. - `id: string` Unique identifier of the deleted credential. - `type: "vault_credential_deleted"` - `"vault_credential_deleted"` ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const betaManagedAgentsDeletedCredential = await client.beta.vaults.credentials.delete( 'vcrd_011CZkZEMt8gZan2iYOQfSkw', { vault_id: 'vlt_011CZkZDLs7fYzm1hXNPeRjv' }, ); console.log(betaManagedAgentsDeletedCredential.id); ``` #### Response ```json { "id": "vcrd_011CZkZEMt8gZan2iYOQfSkw", "type": "vault_credential_deleted" } ``` ## Archive Credential `client.beta.vaults.credentials.archive(stringcredentialID, CredentialArchiveParamsparams, RequestOptionsoptions?): BetaManagedAgentsCredential` **post** `/v1/vaults/{vault_id}/credentials/{credential_id}/archive` Archive Credential ### Parameters - `credentialID: string` - `params: CredentialArchiveParams` - `vault_id: string` Path param: Path parameter vault_id - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaManagedAgentsCredential` A credential stored in a vault. Sensitive fields are never returned in responses. - `id: string` Unique identifier for the credential. - `archived_at: string | null` A timestamp in RFC 3339 format - `auth: BetaManagedAgentsMCPOAuthAuthResponse | BetaManagedAgentsStaticBearerAuthResponse` Authentication details for a credential. - `BetaManagedAgentsMCPOAuthAuthResponse` OAuth credential details for an MCP server. - `mcp_server_url: string` URL of the MCP server this credential authenticates against. - `type: "mcp_oauth"` - `"mcp_oauth"` - `expires_at?: string | null` A timestamp in RFC 3339 format - `refresh?: BetaManagedAgentsMCPOAuthRefreshResponse | null` OAuth refresh token configuration returned in credential responses. - `client_id: string` OAuth client ID. - `token_endpoint: string` Token endpoint URL used to refresh the access token. - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse | BetaManagedAgentsTokenEndpointAuthBasicResponse | BetaManagedAgentsTokenEndpointAuthPostResponse` Token endpoint requires no client authentication. - `BetaManagedAgentsTokenEndpointAuthNoneResponse` Token endpoint requires no client authentication. - `type: "none"` - `"none"` - `BetaManagedAgentsTokenEndpointAuthBasicResponse` Token endpoint uses HTTP Basic authentication with client credentials. - `type: "client_secret_basic"` - `"client_secret_basic"` - `BetaManagedAgentsTokenEndpointAuthPostResponse` Token endpoint uses POST body authentication with client credentials. - `type: "client_secret_post"` - `"client_secret_post"` - `resource?: string | null` OAuth resource indicator. - `scope?: string | null` OAuth scope for the refresh request. - `BetaManagedAgentsStaticBearerAuthResponse` Static bearer token credential details for an MCP server. - `mcp_server_url: string` URL of the MCP server this credential authenticates against. - `type: "static_bearer"` - `"static_bearer"` - `created_at: string` A timestamp in RFC 3339 format - `metadata: Record` Arbitrary key-value metadata attached to the credential. - `type: "vault_credential"` - `"vault_credential"` - `updated_at: string` A timestamp in RFC 3339 format - `vault_id: string` Identifier of the vault this credential belongs to. - `display_name?: string | null` Human-readable name for the credential. ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const betaManagedAgentsCredential = await client.beta.vaults.credentials.archive( 'vcrd_011CZkZEMt8gZan2iYOQfSkw', { vault_id: 'vlt_011CZkZDLs7fYzm1hXNPeRjv' }, ); console.log(betaManagedAgentsCredential.id); ``` #### Response ```json { "id": "vcrd_011CZkZEMt8gZan2iYOQfSkw", "archived_at": null, "auth": { "mcp_server_url": "https://example-server.modelcontextprotocol.io/sse", "type": "static_bearer" }, "created_at": "2026-03-15T10:00:00Z", "metadata": { "environment": "production" }, "type": "vault_credential", "updated_at": "2026-03-15T10:00:00Z", "vault_id": "vlt_011CZkZDLs7fYzm1hXNPeRjv", "display_name": "Example credential" } ``` ## Validate Credential `client.beta.vaults.credentials.mcpOAuthValidate(stringcredentialID, CredentialMCPOAuthValidateParamsparams, RequestOptionsoptions?): BetaManagedAgentsCredentialValidation` **post** `/v1/vaults/{vault_id}/credentials/{credential_id}/mcp_oauth_validate` Validate Credential ### Parameters - `credentialID: string` - `params: CredentialMCPOAuthValidateParams` - `vault_id: string` Path param: Path parameter vault_id - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaManagedAgentsCredentialValidation` Result of live-probing a credential against its configured MCP server. - `credential_id: string` Unique identifier of the credential that was validated. - `has_refresh_token: boolean` Whether the credential has a refresh token configured. - `mcp_probe: BetaManagedAgentsMCPProbe | null` The failing step of an MCP validation probe. - `http_response: BetaManagedAgentsRefreshHTTPResponse | null` An HTTP response captured during a credential validation probe. - `body: string` Response body. May be truncated and has sensitive values scrubbed. - `body_truncated: boolean` Whether `body` was truncated. - `content_type: string` Value of the `Content-Type` response header. - `status_code: number` HTTP status code. - `method: string` The MCP method that failed (for example `initialize` or `tools/list`). - `refresh: BetaManagedAgentsRefreshObject | null` Outcome of a refresh-token exchange attempted during credential validation. - `http_response: BetaManagedAgentsRefreshHTTPResponse | null` An HTTP response captured during a credential validation probe. - `status: "succeeded" | "failed" | "connect_error" | "no_refresh_token"` Outcome of a refresh-token exchange attempted during credential validation. - `"succeeded"` - `"failed"` - `"connect_error"` - `"no_refresh_token"` - `status: BetaManagedAgentsCredentialValidationStatus` Overall verdict of a credential validation probe. - `"valid"` - `"invalid"` - `"unknown"` - `type: "vault_credential_validation"` - `"vault_credential_validation"` - `validated_at: string` A timestamp in RFC 3339 format - `vault_id: string` Identifier of the vault containing the credential. ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const betaManagedAgentsCredentialValidation = await client.beta.vaults.credentials.mcpOAuthValidate( 'vcrd_011CZkZEMt8gZan2iYOQfSkw', { vault_id: 'vlt_011CZkZDLs7fYzm1hXNPeRjv' }, ); console.log(betaManagedAgentsCredentialValidation.credential_id); ``` #### Response ```json { "credential_id": "vcrd_011CZkZEMt8gZan2iYOQfSkw", "has_refresh_token": true, "mcp_probe": { "http_response": { "body": "body", "body_truncated": true, "content_type": "content_type", "status_code": 0 }, "method": "method" }, "refresh": { "http_response": { "body": "body", "body_truncated": true, "content_type": "content_type", "status_code": 0 }, "status": "succeeded" }, "status": "valid", "type": "vault_credential_validation", "validated_at": "2026-03-15T10:00:00Z", "vault_id": "vlt_011CZkZDLs7fYzm1hXNPeRjv" } ``` ## Domain Types ### Beta Managed Agents Credential - `BetaManagedAgentsCredential` A credential stored in a vault. Sensitive fields are never returned in responses. - `id: string` Unique identifier for the credential. - `archived_at: string | null` A timestamp in RFC 3339 format - `auth: BetaManagedAgentsMCPOAuthAuthResponse | BetaManagedAgentsStaticBearerAuthResponse` Authentication details for a credential. - `BetaManagedAgentsMCPOAuthAuthResponse` OAuth credential details for an MCP server. - `mcp_server_url: string` URL of the MCP server this credential authenticates against. - `type: "mcp_oauth"` - `"mcp_oauth"` - `expires_at?: string | null` A timestamp in RFC 3339 format - `refresh?: BetaManagedAgentsMCPOAuthRefreshResponse | null` OAuth refresh token configuration returned in credential responses. - `client_id: string` OAuth client ID. - `token_endpoint: string` Token endpoint URL used to refresh the access token. - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse | BetaManagedAgentsTokenEndpointAuthBasicResponse | BetaManagedAgentsTokenEndpointAuthPostResponse` Token endpoint requires no client authentication. - `BetaManagedAgentsTokenEndpointAuthNoneResponse` Token endpoint requires no client authentication. - `type: "none"` - `"none"` - `BetaManagedAgentsTokenEndpointAuthBasicResponse` Token endpoint uses HTTP Basic authentication with client credentials. - `type: "client_secret_basic"` - `"client_secret_basic"` - `BetaManagedAgentsTokenEndpointAuthPostResponse` Token endpoint uses POST body authentication with client credentials. - `type: "client_secret_post"` - `"client_secret_post"` - `resource?: string | null` OAuth resource indicator. - `scope?: string | null` OAuth scope for the refresh request. - `BetaManagedAgentsStaticBearerAuthResponse` Static bearer token credential details for an MCP server. - `mcp_server_url: string` URL of the MCP server this credential authenticates against. - `type: "static_bearer"` - `"static_bearer"` - `created_at: string` A timestamp in RFC 3339 format - `metadata: Record` Arbitrary key-value metadata attached to the credential. - `type: "vault_credential"` - `"vault_credential"` - `updated_at: string` A timestamp in RFC 3339 format - `vault_id: string` Identifier of the vault this credential belongs to. - `display_name?: string | null` Human-readable name for the credential. ### Beta Managed Agents Credential Validation - `BetaManagedAgentsCredentialValidation` Result of live-probing a credential against its configured MCP server. - `credential_id: string` Unique identifier of the credential that was validated. - `has_refresh_token: boolean` Whether the credential has a refresh token configured. - `mcp_probe: BetaManagedAgentsMCPProbe | null` The failing step of an MCP validation probe. - `http_response: BetaManagedAgentsRefreshHTTPResponse | null` An HTTP response captured during a credential validation probe. - `body: string` Response body. May be truncated and has sensitive values scrubbed. - `body_truncated: boolean` Whether `body` was truncated. - `content_type: string` Value of the `Content-Type` response header. - `status_code: number` HTTP status code. - `method: string` The MCP method that failed (for example `initialize` or `tools/list`). - `refresh: BetaManagedAgentsRefreshObject | null` Outcome of a refresh-token exchange attempted during credential validation. - `http_response: BetaManagedAgentsRefreshHTTPResponse | null` An HTTP response captured during a credential validation probe. - `status: "succeeded" | "failed" | "connect_error" | "no_refresh_token"` Outcome of a refresh-token exchange attempted during credential validation. - `"succeeded"` - `"failed"` - `"connect_error"` - `"no_refresh_token"` - `status: BetaManagedAgentsCredentialValidationStatus` Overall verdict of a credential validation probe. - `"valid"` - `"invalid"` - `"unknown"` - `type: "vault_credential_validation"` - `"vault_credential_validation"` - `validated_at: string` A timestamp in RFC 3339 format - `vault_id: string` Identifier of the vault containing the credential. ### Beta Managed Agents Credential Validation Status - `BetaManagedAgentsCredentialValidationStatus = "valid" | "invalid" | "unknown"` Overall verdict of a credential validation probe. - `"valid"` - `"invalid"` - `"unknown"` ### Beta Managed Agents Deleted Credential - `BetaManagedAgentsDeletedCredential` Confirmation of a deleted credential. - `id: string` Unique identifier of the deleted credential. - `type: "vault_credential_deleted"` - `"vault_credential_deleted"` ### Beta Managed Agents MCP OAuth Auth Response - `BetaManagedAgentsMCPOAuthAuthResponse` OAuth credential details for an MCP server. - `mcp_server_url: string` URL of the MCP server this credential authenticates against. - `type: "mcp_oauth"` - `"mcp_oauth"` - `expires_at?: string | null` A timestamp in RFC 3339 format - `refresh?: BetaManagedAgentsMCPOAuthRefreshResponse | null` OAuth refresh token configuration returned in credential responses. - `client_id: string` OAuth client ID. - `token_endpoint: string` Token endpoint URL used to refresh the access token. - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse | BetaManagedAgentsTokenEndpointAuthBasicResponse | BetaManagedAgentsTokenEndpointAuthPostResponse` Token endpoint requires no client authentication. - `BetaManagedAgentsTokenEndpointAuthNoneResponse` Token endpoint requires no client authentication. - `type: "none"` - `"none"` - `BetaManagedAgentsTokenEndpointAuthBasicResponse` Token endpoint uses HTTP Basic authentication with client credentials. - `type: "client_secret_basic"` - `"client_secret_basic"` - `BetaManagedAgentsTokenEndpointAuthPostResponse` Token endpoint uses POST body authentication with client credentials. - `type: "client_secret_post"` - `"client_secret_post"` - `resource?: string | null` OAuth resource indicator. - `scope?: string | null` OAuth scope for the refresh request. ### Beta Managed Agents MCP OAuth Create Params - `BetaManagedAgentsMCPOAuthCreateParams` Parameters for creating an MCP OAuth credential. - `access_token: string` OAuth access token. - `mcp_server_url: string` URL of the MCP server this credential authenticates against. - `type: "mcp_oauth"` - `"mcp_oauth"` - `expires_at?: string | null` A timestamp in RFC 3339 format - `refresh?: BetaManagedAgentsMCPOAuthRefreshParams | null` OAuth refresh token parameters for creating a credential with refresh support. - `client_id: string` OAuth client ID. - `refresh_token: string` OAuth refresh token. - `token_endpoint: string` Token endpoint URL used to refresh the access token. - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneParam | BetaManagedAgentsTokenEndpointAuthBasicParam | BetaManagedAgentsTokenEndpointAuthPostParam` Token endpoint requires no client authentication. - `BetaManagedAgentsTokenEndpointAuthNoneParam` Token endpoint requires no client authentication. - `type: "none"` - `"none"` - `BetaManagedAgentsTokenEndpointAuthBasicParam` Token endpoint uses HTTP Basic authentication with client credentials. - `client_secret: string` OAuth client secret. - `type: "client_secret_basic"` - `"client_secret_basic"` - `BetaManagedAgentsTokenEndpointAuthPostParam` Token endpoint uses POST body authentication with client credentials. - `client_secret: string` OAuth client secret. - `type: "client_secret_post"` - `"client_secret_post"` - `resource?: string | null` OAuth resource indicator. - `scope?: string | null` OAuth scope for the refresh request. ### Beta Managed Agents MCP OAuth Refresh Params - `BetaManagedAgentsMCPOAuthRefreshParams` OAuth refresh token parameters for creating a credential with refresh support. - `client_id: string` OAuth client ID. - `refresh_token: string` OAuth refresh token. - `token_endpoint: string` Token endpoint URL used to refresh the access token. - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneParam | BetaManagedAgentsTokenEndpointAuthBasicParam | BetaManagedAgentsTokenEndpointAuthPostParam` Token endpoint requires no client authentication. - `BetaManagedAgentsTokenEndpointAuthNoneParam` Token endpoint requires no client authentication. - `type: "none"` - `"none"` - `BetaManagedAgentsTokenEndpointAuthBasicParam` Token endpoint uses HTTP Basic authentication with client credentials. - `client_secret: string` OAuth client secret. - `type: "client_secret_basic"` - `"client_secret_basic"` - `BetaManagedAgentsTokenEndpointAuthPostParam` Token endpoint uses POST body authentication with client credentials. - `client_secret: string` OAuth client secret. - `type: "client_secret_post"` - `"client_secret_post"` - `resource?: string | null` OAuth resource indicator. - `scope?: string | null` OAuth scope for the refresh request. ### Beta Managed Agents MCP OAuth Refresh Response - `BetaManagedAgentsMCPOAuthRefreshResponse` OAuth refresh token configuration returned in credential responses. - `client_id: string` OAuth client ID. - `token_endpoint: string` Token endpoint URL used to refresh the access token. - `token_endpoint_auth: BetaManagedAgentsTokenEndpointAuthNoneResponse | BetaManagedAgentsTokenEndpointAuthBasicResponse | BetaManagedAgentsTokenEndpointAuthPostResponse` Token endpoint requires no client authentication. - `BetaManagedAgentsTokenEndpointAuthNoneResponse` Token endpoint requires no client authentication. - `type: "none"` - `"none"` - `BetaManagedAgentsTokenEndpointAuthBasicResponse` Token endpoint uses HTTP Basic authentication with client credentials. - `type: "client_secret_basic"` - `"client_secret_basic"` - `BetaManagedAgentsTokenEndpointAuthPostResponse` Token endpoint uses POST body authentication with client credentials. - `type: "client_secret_post"` - `"client_secret_post"` - `resource?: string | null` OAuth resource indicator. - `scope?: string | null` OAuth scope for the refresh request. ### Beta Managed Agents MCP OAuth Refresh Update Params - `BetaManagedAgentsMCPOAuthRefreshUpdateParams` Parameters for updating OAuth refresh token configuration. - `refresh_token?: string | null` Updated OAuth refresh token. - `scope?: string | null` Updated OAuth scope for the refresh request. - `token_endpoint_auth?: BetaManagedAgentsTokenEndpointAuthBasicUpdateParam | BetaManagedAgentsTokenEndpointAuthPostUpdateParam` Updated HTTP Basic authentication parameters for the token endpoint. - `BetaManagedAgentsTokenEndpointAuthBasicUpdateParam` Updated HTTP Basic authentication parameters for the token endpoint. - `type: "client_secret_basic"` - `"client_secret_basic"` - `client_secret?: string | null` Updated OAuth client secret. - `BetaManagedAgentsTokenEndpointAuthPostUpdateParam` Updated POST body authentication parameters for the token endpoint. - `type: "client_secret_post"` - `"client_secret_post"` - `client_secret?: string | null` Updated OAuth client secret. ### Beta Managed Agents MCP OAuth Update Params - `BetaManagedAgentsMCPOAuthUpdateParams` Parameters for updating an MCP OAuth credential. The `mcp_server_url` is immutable. - `type: "mcp_oauth"` - `"mcp_oauth"` - `access_token?: string | null` Updated OAuth access token. - `expires_at?: string | null` A timestamp in RFC 3339 format - `refresh?: BetaManagedAgentsMCPOAuthRefreshUpdateParams | null` Parameters for updating OAuth refresh token configuration. - `refresh_token?: string | null` Updated OAuth refresh token. - `scope?: string | null` Updated OAuth scope for the refresh request. - `token_endpoint_auth?: BetaManagedAgentsTokenEndpointAuthBasicUpdateParam | BetaManagedAgentsTokenEndpointAuthPostUpdateParam` Updated HTTP Basic authentication parameters for the token endpoint. - `BetaManagedAgentsTokenEndpointAuthBasicUpdateParam` Updated HTTP Basic authentication parameters for the token endpoint. - `type: "client_secret_basic"` - `"client_secret_basic"` - `client_secret?: string | null` Updated OAuth client secret. - `BetaManagedAgentsTokenEndpointAuthPostUpdateParam` Updated POST body authentication parameters for the token endpoint. - `type: "client_secret_post"` - `"client_secret_post"` - `client_secret?: string | null` Updated OAuth client secret. ### Beta Managed Agents MCP Probe - `BetaManagedAgentsMCPProbe` The failing step of an MCP validation probe. - `http_response: BetaManagedAgentsRefreshHTTPResponse | null` An HTTP response captured during a credential validation probe. - `body: string` Response body. May be truncated and has sensitive values scrubbed. - `body_truncated: boolean` Whether `body` was truncated. - `content_type: string` Value of the `Content-Type` response header. - `status_code: number` HTTP status code. - `method: string` The MCP method that failed (for example `initialize` or `tools/list`). ### Beta Managed Agents Refresh HTTP Response - `BetaManagedAgentsRefreshHTTPResponse` An HTTP response captured during a credential validation probe. - `body: string` Response body. May be truncated and has sensitive values scrubbed. - `body_truncated: boolean` Whether `body` was truncated. - `content_type: string` Value of the `Content-Type` response header. - `status_code: number` HTTP status code. ### Beta Managed Agents Refresh Object - `BetaManagedAgentsRefreshObject` Outcome of a refresh-token exchange attempted during credential validation. - `http_response: BetaManagedAgentsRefreshHTTPResponse | null` An HTTP response captured during a credential validation probe. - `body: string` Response body. May be truncated and has sensitive values scrubbed. - `body_truncated: boolean` Whether `body` was truncated. - `content_type: string` Value of the `Content-Type` response header. - `status_code: number` HTTP status code. - `status: "succeeded" | "failed" | "connect_error" | "no_refresh_token"` Outcome of a refresh-token exchange attempted during credential validation. - `"succeeded"` - `"failed"` - `"connect_error"` - `"no_refresh_token"` ### Beta Managed Agents Static Bearer Auth Response - `BetaManagedAgentsStaticBearerAuthResponse` Static bearer token credential details for an MCP server. - `mcp_server_url: string` URL of the MCP server this credential authenticates against. - `type: "static_bearer"` - `"static_bearer"` ### Beta Managed Agents Static Bearer Create Params - `BetaManagedAgentsStaticBearerCreateParams` Parameters for creating a static bearer token credential. - `token: string` Static bearer token value. - `mcp_server_url: string` URL of the MCP server this credential authenticates against. - `type: "static_bearer"` - `"static_bearer"` ### Beta Managed Agents Static Bearer Update Params - `BetaManagedAgentsStaticBearerUpdateParams` Parameters for updating a static bearer token credential. The `mcp_server_url` is immutable. - `type: "static_bearer"` - `"static_bearer"` - `token?: string | null` Updated static bearer token value. ### Beta Managed Agents Token Endpoint Auth Basic Param - `BetaManagedAgentsTokenEndpointAuthBasicParam` Token endpoint uses HTTP Basic authentication with client credentials. - `client_secret: string` OAuth client secret. - `type: "client_secret_basic"` - `"client_secret_basic"` ### Beta Managed Agents Token Endpoint Auth Basic Response - `BetaManagedAgentsTokenEndpointAuthBasicResponse` Token endpoint uses HTTP Basic authentication with client credentials. - `type: "client_secret_basic"` - `"client_secret_basic"` ### Beta Managed Agents Token Endpoint Auth Basic Update Param - `BetaManagedAgentsTokenEndpointAuthBasicUpdateParam` Updated HTTP Basic authentication parameters for the token endpoint. - `type: "client_secret_basic"` - `"client_secret_basic"` - `client_secret?: string | null` Updated OAuth client secret. ### Beta Managed Agents Token Endpoint Auth None Param - `BetaManagedAgentsTokenEndpointAuthNoneParam` Token endpoint requires no client authentication. - `type: "none"` - `"none"` ### Beta Managed Agents Token Endpoint Auth None Response - `BetaManagedAgentsTokenEndpointAuthNoneResponse` Token endpoint requires no client authentication. - `type: "none"` - `"none"` ### Beta Managed Agents Token Endpoint Auth Post Param - `BetaManagedAgentsTokenEndpointAuthPostParam` Token endpoint uses POST body authentication with client credentials. - `client_secret: string` OAuth client secret. - `type: "client_secret_post"` - `"client_secret_post"` ### Beta Managed Agents Token Endpoint Auth Post Response - `BetaManagedAgentsTokenEndpointAuthPostResponse` Token endpoint uses POST body authentication with client credentials. - `type: "client_secret_post"` - `"client_secret_post"` ### Beta Managed Agents Token Endpoint Auth Post Update Param - `BetaManagedAgentsTokenEndpointAuthPostUpdateParam` Updated POST body authentication parameters for the token endpoint. - `type: "client_secret_post"` - `"client_secret_post"` - `client_secret?: string | null` Updated OAuth client secret. # Memory Stores ## Create a memory store `client.beta.memoryStores.create(MemoryStoreCreateParamsparams, RequestOptionsoptions?): BetaManagedAgentsMemoryStore` **post** `/v1/memory_stores` Create a memory store ### Parameters - `params: MemoryStoreCreateParams` - `name: string` Body param: Human-readable name for the store. Required; 1–255 characters; no control characters. The mount-path slug under `/mnt/memory/` is derived from this name (lowercased, non-alphanumeric runs collapsed to a hyphen). Names need not be unique within a workspace. - `description?: string` Body param: Free-text description of what the store contains, up to 1024 characters. Included in the agent's system prompt when the store is attached, so word it to be useful to the agent. - `metadata?: Record` Body param: Arbitrary key-value tags for your own bookkeeping (such as the end user a store belongs to). Up to 16 pairs; keys 1–64 characters; values up to 512 characters. Not visible to the agent. - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaManagedAgentsMemoryStore` A `memory_store`: a named container for agent memories, scoped to a workspace. Attach a store to a session via `resources[]` to mount it as a directory the agent can read and write. - `id: string` Unique identifier for the memory store (a `memstore_...` tagged ID). Use this when attaching the store to a session, or in the `{memory_store_id}` path parameter of subsequent calls. - `created_at: string` A timestamp in RFC 3339 format - `name: string` Human-readable name for the store. 1–255 characters. The store's mount-path slug under `/mnt/memory/` is derived from this name. - `type: "memory_store"` - `"memory_store"` - `updated_at: string` A timestamp in RFC 3339 format - `archived_at?: string | null` A timestamp in RFC 3339 format - `description?: string` Free-text description of what the store contains, up to 1024 characters. Included in the agent's system prompt when the store is attached, so word it to be useful to the agent. Empty string when unset. - `metadata?: Record` Arbitrary key-value tags for your own bookkeeping (such as the end user a store belongs to). Up to 16 pairs; keys 1–64 characters; values up to 512 characters. Returned on retrieve/list but not filterable. ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const betaManagedAgentsMemoryStore = await client.beta.memoryStores.create({ name: 'x' }); console.log(betaManagedAgentsMemoryStore.id); ``` #### Response ```json { "id": "id", "created_at": "2019-12-27T18:11:19.117Z", "name": "name", "type": "memory_store", "updated_at": "2019-12-27T18:11:19.117Z", "archived_at": "2019-12-27T18:11:19.117Z", "description": "description", "metadata": { "foo": "string" } } ``` ## List memory stores `client.beta.memoryStores.list(MemoryStoreListParamsparams?, RequestOptionsoptions?): PageCursor` **get** `/v1/memory_stores` List memory stores ### Parameters - `params: MemoryStoreListParams` - `"created_at[gte]"?: string` Query param: Return only stores whose `created_at` is at or after this time (inclusive). Sent on the wire as `created_at[gte]`. - `"created_at[lte]"?: string` Query param: Return only stores whose `created_at` is at or before this time (inclusive). Sent on the wire as `created_at[lte]`. - `include_archived?: boolean` Query param: When `true`, archived stores are included in the results. Defaults to `false` (archived stores are excluded). - `limit?: number` Query param: Maximum number of stores to return per page. Must be between 1 and 100. Defaults to 20 when omitted. - `page?: string` Query param: Opaque pagination cursor (a `page_...` value). Pass the `next_page` value from a previous response to fetch the next page; omit for the first page. - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaManagedAgentsMemoryStore` A `memory_store`: a named container for agent memories, scoped to a workspace. Attach a store to a session via `resources[]` to mount it as a directory the agent can read and write. - `id: string` Unique identifier for the memory store (a `memstore_...` tagged ID). Use this when attaching the store to a session, or in the `{memory_store_id}` path parameter of subsequent calls. - `created_at: string` A timestamp in RFC 3339 format - `name: string` Human-readable name for the store. 1–255 characters. The store's mount-path slug under `/mnt/memory/` is derived from this name. - `type: "memory_store"` - `"memory_store"` - `updated_at: string` A timestamp in RFC 3339 format - `archived_at?: string | null` A timestamp in RFC 3339 format - `description?: string` Free-text description of what the store contains, up to 1024 characters. Included in the agent's system prompt when the store is attached, so word it to be useful to the agent. Empty string when unset. - `metadata?: Record` Arbitrary key-value tags for your own bookkeeping (such as the end user a store belongs to). Up to 16 pairs; keys 1–64 characters; values up to 512 characters. Returned on retrieve/list but not filterable. ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); // Automatically fetches more pages as needed. for await (const betaManagedAgentsMemoryStore of client.beta.memoryStores.list()) { console.log(betaManagedAgentsMemoryStore.id); } ``` #### Response ```json { "data": [ { "id": "id", "created_at": "2019-12-27T18:11:19.117Z", "name": "name", "type": "memory_store", "updated_at": "2019-12-27T18:11:19.117Z", "archived_at": "2019-12-27T18:11:19.117Z", "description": "description", "metadata": { "foo": "string" } } ], "next_page": "next_page" } ``` ## Retrieve a memory store `client.beta.memoryStores.retrieve(stringmemoryStoreID, MemoryStoreRetrieveParamsparams?, RequestOptionsoptions?): BetaManagedAgentsMemoryStore` **get** `/v1/memory_stores/{memory_store_id}` Retrieve a memory store ### Parameters - `memoryStoreID: string` - `params: MemoryStoreRetrieveParams` - `betas?: Array` Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaManagedAgentsMemoryStore` A `memory_store`: a named container for agent memories, scoped to a workspace. Attach a store to a session via `resources[]` to mount it as a directory the agent can read and write. - `id: string` Unique identifier for the memory store (a `memstore_...` tagged ID). Use this when attaching the store to a session, or in the `{memory_store_id}` path parameter of subsequent calls. - `created_at: string` A timestamp in RFC 3339 format - `name: string` Human-readable name for the store. 1–255 characters. The store's mount-path slug under `/mnt/memory/` is derived from this name. - `type: "memory_store"` - `"memory_store"` - `updated_at: string` A timestamp in RFC 3339 format - `archived_at?: string | null` A timestamp in RFC 3339 format - `description?: string` Free-text description of what the store contains, up to 1024 characters. Included in the agent's system prompt when the store is attached, so word it to be useful to the agent. Empty string when unset. - `metadata?: Record` Arbitrary key-value tags for your own bookkeeping (such as the end user a store belongs to). Up to 16 pairs; keys 1–64 characters; values up to 512 characters. Returned on retrieve/list but not filterable. ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const betaManagedAgentsMemoryStore = await client.beta.memoryStores.retrieve('memory_store_id'); console.log(betaManagedAgentsMemoryStore.id); ``` #### Response ```json { "id": "id", "created_at": "2019-12-27T18:11:19.117Z", "name": "name", "type": "memory_store", "updated_at": "2019-12-27T18:11:19.117Z", "archived_at": "2019-12-27T18:11:19.117Z", "description": "description", "metadata": { "foo": "string" } } ``` ## Update a memory store `client.beta.memoryStores.update(stringmemoryStoreID, MemoryStoreUpdateParamsparams, RequestOptionsoptions?): BetaManagedAgentsMemoryStore` **post** `/v1/memory_stores/{memory_store_id}` Update a memory store ### Parameters - `memoryStoreID: string` - `params: MemoryStoreUpdateParams` - `description?: string | null` Body param: New description for the store, up to 1024 characters. Pass an empty string to clear it. - `metadata?: Record | null` Body param: Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve. The stored bag is limited to 16 keys (up to 64 chars each) with values up to 512 chars. - `name?: string | null` Body param: New human-readable name for the store. 1–255 characters; no control characters. Renaming changes the slug used for the store's `mount_path` in sessions created after the update. - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaManagedAgentsMemoryStore` A `memory_store`: a named container for agent memories, scoped to a workspace. Attach a store to a session via `resources[]` to mount it as a directory the agent can read and write. - `id: string` Unique identifier for the memory store (a `memstore_...` tagged ID). Use this when attaching the store to a session, or in the `{memory_store_id}` path parameter of subsequent calls. - `created_at: string` A timestamp in RFC 3339 format - `name: string` Human-readable name for the store. 1–255 characters. The store's mount-path slug under `/mnt/memory/` is derived from this name. - `type: "memory_store"` - `"memory_store"` - `updated_at: string` A timestamp in RFC 3339 format - `archived_at?: string | null` A timestamp in RFC 3339 format - `description?: string` Free-text description of what the store contains, up to 1024 characters. Included in the agent's system prompt when the store is attached, so word it to be useful to the agent. Empty string when unset. - `metadata?: Record` Arbitrary key-value tags for your own bookkeeping (such as the end user a store belongs to). Up to 16 pairs; keys 1–64 characters; values up to 512 characters. Returned on retrieve/list but not filterable. ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const betaManagedAgentsMemoryStore = await client.beta.memoryStores.update('memory_store_id'); console.log(betaManagedAgentsMemoryStore.id); ``` #### Response ```json { "id": "id", "created_at": "2019-12-27T18:11:19.117Z", "name": "name", "type": "memory_store", "updated_at": "2019-12-27T18:11:19.117Z", "archived_at": "2019-12-27T18:11:19.117Z", "description": "description", "metadata": { "foo": "string" } } ``` ## Delete a memory store `client.beta.memoryStores.delete(stringmemoryStoreID, MemoryStoreDeleteParamsparams?, RequestOptionsoptions?): BetaManagedAgentsDeletedMemoryStore` **delete** `/v1/memory_stores/{memory_store_id}` Delete a memory store ### Parameters - `memoryStoreID: string` - `params: MemoryStoreDeleteParams` - `betas?: Array` Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaManagedAgentsDeletedMemoryStore` Confirmation that a `memory_store` was deleted. - `id: string` ID of the deleted memory store (a `memstore_...` identifier). The store and all its memories and versions are no longer retrievable. - `type: "memory_store_deleted"` - `"memory_store_deleted"` ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const betaManagedAgentsDeletedMemoryStore = await client.beta.memoryStores.delete( 'memory_store_id', ); console.log(betaManagedAgentsDeletedMemoryStore.id); ``` #### Response ```json { "id": "id", "type": "memory_store_deleted" } ``` ## Archive a memory store `client.beta.memoryStores.archive(stringmemoryStoreID, MemoryStoreArchiveParamsparams?, RequestOptionsoptions?): BetaManagedAgentsMemoryStore` **post** `/v1/memory_stores/{memory_store_id}/archive` Archive a memory store ### Parameters - `memoryStoreID: string` - `params: MemoryStoreArchiveParams` - `betas?: Array` Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaManagedAgentsMemoryStore` A `memory_store`: a named container for agent memories, scoped to a workspace. Attach a store to a session via `resources[]` to mount it as a directory the agent can read and write. - `id: string` Unique identifier for the memory store (a `memstore_...` tagged ID). Use this when attaching the store to a session, or in the `{memory_store_id}` path parameter of subsequent calls. - `created_at: string` A timestamp in RFC 3339 format - `name: string` Human-readable name for the store. 1–255 characters. The store's mount-path slug under `/mnt/memory/` is derived from this name. - `type: "memory_store"` - `"memory_store"` - `updated_at: string` A timestamp in RFC 3339 format - `archived_at?: string | null` A timestamp in RFC 3339 format - `description?: string` Free-text description of what the store contains, up to 1024 characters. Included in the agent's system prompt when the store is attached, so word it to be useful to the agent. Empty string when unset. - `metadata?: Record` Arbitrary key-value tags for your own bookkeeping (such as the end user a store belongs to). Up to 16 pairs; keys 1–64 characters; values up to 512 characters. Returned on retrieve/list but not filterable. ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const betaManagedAgentsMemoryStore = await client.beta.memoryStores.archive('memory_store_id'); console.log(betaManagedAgentsMemoryStore.id); ``` #### Response ```json { "id": "id", "created_at": "2019-12-27T18:11:19.117Z", "name": "name", "type": "memory_store", "updated_at": "2019-12-27T18:11:19.117Z", "archived_at": "2019-12-27T18:11:19.117Z", "description": "description", "metadata": { "foo": "string" } } ``` ## Domain Types ### Beta Managed Agents Deleted Memory Store - `BetaManagedAgentsDeletedMemoryStore` Confirmation that a `memory_store` was deleted. - `id: string` ID of the deleted memory store (a `memstore_...` identifier). The store and all its memories and versions are no longer retrievable. - `type: "memory_store_deleted"` - `"memory_store_deleted"` ### Beta Managed Agents Memory Store - `BetaManagedAgentsMemoryStore` A `memory_store`: a named container for agent memories, scoped to a workspace. Attach a store to a session via `resources[]` to mount it as a directory the agent can read and write. - `id: string` Unique identifier for the memory store (a `memstore_...` tagged ID). Use this when attaching the store to a session, or in the `{memory_store_id}` path parameter of subsequent calls. - `created_at: string` A timestamp in RFC 3339 format - `name: string` Human-readable name for the store. 1–255 characters. The store's mount-path slug under `/mnt/memory/` is derived from this name. - `type: "memory_store"` - `"memory_store"` - `updated_at: string` A timestamp in RFC 3339 format - `archived_at?: string | null` A timestamp in RFC 3339 format - `description?: string` Free-text description of what the store contains, up to 1024 characters. Included in the agent's system prompt when the store is attached, so word it to be useful to the agent. Empty string when unset. - `metadata?: Record` Arbitrary key-value tags for your own bookkeeping (such as the end user a store belongs to). Up to 16 pairs; keys 1–64 characters; values up to 512 characters. Returned on retrieve/list but not filterable. # Memories ## Create a memory `client.beta.memoryStores.memories.create(stringmemoryStoreID, MemoryCreateParamsparams, RequestOptionsoptions?): BetaManagedAgentsMemory` **post** `/v1/memory_stores/{memory_store_id}/memories` Create a memory ### Parameters - `memoryStoreID: string` - `params: MemoryCreateParams` - `content: string | null` Body param: UTF-8 text content for the new memory. Maximum 100 kB (102,400 bytes). Required; pass `""` explicitly to create an empty memory. - `path: string` Body param: Hierarchical path for the new memory, e.g. `/projects/foo/notes.md`. Must start with `/`, contain at least one non-empty segment, and be at most 1,024 bytes. Must not contain empty segments, `.` or `..` segments, control or format characters, and must be NFC-normalized. Paths are case-sensitive. - `view?: BetaManagedAgentsMemoryView` Query param: Query parameter for view - `"basic"` - `"full"` - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaManagedAgentsMemory` A `memory` object: a single text document at a hierarchical path inside a memory store. The `content` field is populated when `view=full` and `null` when `view=basic`; the `content_size_bytes` and `content_sha256` fields are always populated so sync clients can diff without fetching content. Memories are addressed by their `mem_...` ID; the path is the create key and can be changed via update. - `id: string` Unique identifier for this memory (a `mem_...` value). Stable across renames; use this ID, not the path, to read, update, or delete the memory. - `content_sha256: string` Lowercase hex SHA-256 digest of the UTF-8 `content` bytes (64 characters). The server applies no normalization, so clients can compute the same hash locally for staleness checks and as the value for a `content_sha256` precondition on update. Always populated, regardless of `view`. - `content_size_bytes: number` Size of `content` in bytes (the UTF-8 plaintext length). Always populated, regardless of `view`. - `created_at: string` A timestamp in RFC 3339 format - `memory_store_id: string` ID of the memory store this memory belongs to (a `memstore_...` value). - `memory_version_id: string` ID of the `memory_version` representing this memory's current content (a `memver_...` value). This is the authoritative head pointer; `memory_version` objects do not carry an `is_latest` flag, so compare against this field instead. Enumerate the full history via [List memory versions](/docs/en/api/beta/memory_stores/memory_versions/list). - `path: string` Hierarchical path of the memory within the store, e.g. `/projects/foo/notes.md`. Always starts with `/`. Paths are case-sensitive and unique within a store. Maximum 1,024 bytes. - `type: "memory"` - `"memory"` - `updated_at: string` A timestamp in RFC 3339 format - `content?: string | null` The memory's UTF-8 text content. Populated when `view=full`; `null` when `view=basic`. Maximum 100 kB (102,400 bytes). ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const betaManagedAgentsMemory = await client.beta.memoryStores.memories.create('memory_store_id', { content: 'content', path: 'xx', }); console.log(betaManagedAgentsMemory.id); ``` #### Response ```json { "id": "id", "content_sha256": "content_sha256", "content_size_bytes": 0, "created_at": "2019-12-27T18:11:19.117Z", "memory_store_id": "memory_store_id", "memory_version_id": "memory_version_id", "path": "path", "type": "memory", "updated_at": "2019-12-27T18:11:19.117Z", "content": "content" } ``` ## List memories `client.beta.memoryStores.memories.list(stringmemoryStoreID, MemoryListParamsparams?, RequestOptionsoptions?): PageCursor` **get** `/v1/memory_stores/{memory_store_id}/memories` List memories ### Parameters - `memoryStoreID: string` - `params: MemoryListParams` - `depth?: number` Query param: Query parameter for depth - `limit?: number` Query param: Query parameter for limit - `order?: "asc" | "desc"` Query param: Query parameter for order - `"asc"` - `"desc"` - `order_by?: string` Query param: Query parameter for order_by - `page?: string` Query param: Query parameter for page - `path_prefix?: string` Query param: Optional path prefix filter (raw string-prefix match; include a trailing slash for directory-scoped lists). This value appears in request URLs. Do not include secrets or personally identifiable information. - `view?: BetaManagedAgentsMemoryView` Query param: Query parameter for view - `"basic"` - `"full"` - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaManagedAgentsMemoryListItem = BetaManagedAgentsMemory | BetaManagedAgentsMemoryPrefix` One item in a [List memories](/docs/en/api/beta/memory_stores/memories/list) response: either a `memory` object or, when `depth` is set, a `memory_prefix` rollup marker. - `BetaManagedAgentsMemory` A `memory` object: a single text document at a hierarchical path inside a memory store. The `content` field is populated when `view=full` and `null` when `view=basic`; the `content_size_bytes` and `content_sha256` fields are always populated so sync clients can diff without fetching content. Memories are addressed by their `mem_...` ID; the path is the create key and can be changed via update. - `id: string` Unique identifier for this memory (a `mem_...` value). Stable across renames; use this ID, not the path, to read, update, or delete the memory. - `content_sha256: string` Lowercase hex SHA-256 digest of the UTF-8 `content` bytes (64 characters). The server applies no normalization, so clients can compute the same hash locally for staleness checks and as the value for a `content_sha256` precondition on update. Always populated, regardless of `view`. - `content_size_bytes: number` Size of `content` in bytes (the UTF-8 plaintext length). Always populated, regardless of `view`. - `created_at: string` A timestamp in RFC 3339 format - `memory_store_id: string` ID of the memory store this memory belongs to (a `memstore_...` value). - `memory_version_id: string` ID of the `memory_version` representing this memory's current content (a `memver_...` value). This is the authoritative head pointer; `memory_version` objects do not carry an `is_latest` flag, so compare against this field instead. Enumerate the full history via [List memory versions](/docs/en/api/beta/memory_stores/memory_versions/list). - `path: string` Hierarchical path of the memory within the store, e.g. `/projects/foo/notes.md`. Always starts with `/`. Paths are case-sensitive and unique within a store. Maximum 1,024 bytes. - `type: "memory"` - `"memory"` - `updated_at: string` A timestamp in RFC 3339 format - `content?: string | null` The memory's UTF-8 text content. Populated when `view=full`; `null` when `view=basic`. Maximum 100 kB (102,400 bytes). - `BetaManagedAgentsMemoryPrefix` A rolled-up directory marker returned by [List memories](/docs/en/api/beta/memory_stores/memories/list) when `depth` is set. Indicates that one or more memories exist deeper than the requested depth under this prefix. This is a list-time rollup, not a stored resource; it has no ID and no lifecycle. Each prefix counts toward the page `limit` and interleaves with `memory` items in path order. - `path: string` The rolled-up path prefix, including a trailing `/` (e.g. `/projects/foo/`). Pass this value as `path_prefix` on a subsequent list call to drill into the directory. - `type: "memory_prefix"` - `"memory_prefix"` ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); // Automatically fetches more pages as needed. for await (const betaManagedAgentsMemoryListItem of client.beta.memoryStores.memories.list( 'memory_store_id', )) { console.log(betaManagedAgentsMemoryListItem); } ``` #### Response ```json { "data": [ { "id": "id", "content_sha256": "content_sha256", "content_size_bytes": 0, "created_at": "2019-12-27T18:11:19.117Z", "memory_store_id": "memory_store_id", "memory_version_id": "memory_version_id", "path": "path", "type": "memory", "updated_at": "2019-12-27T18:11:19.117Z", "content": "content" } ], "next_page": "next_page" } ``` ## Retrieve a memory `client.beta.memoryStores.memories.retrieve(stringmemoryID, MemoryRetrieveParamsparams, RequestOptionsoptions?): BetaManagedAgentsMemory` **get** `/v1/memory_stores/{memory_store_id}/memories/{memory_id}` Retrieve a memory ### Parameters - `memoryID: string` - `params: MemoryRetrieveParams` - `memory_store_id: string` Path param: Path parameter memory_store_id - `view?: BetaManagedAgentsMemoryView` Query param: Query parameter for view - `"basic"` - `"full"` - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaManagedAgentsMemory` A `memory` object: a single text document at a hierarchical path inside a memory store. The `content` field is populated when `view=full` and `null` when `view=basic`; the `content_size_bytes` and `content_sha256` fields are always populated so sync clients can diff without fetching content. Memories are addressed by their `mem_...` ID; the path is the create key and can be changed via update. - `id: string` Unique identifier for this memory (a `mem_...` value). Stable across renames; use this ID, not the path, to read, update, or delete the memory. - `content_sha256: string` Lowercase hex SHA-256 digest of the UTF-8 `content` bytes (64 characters). The server applies no normalization, so clients can compute the same hash locally for staleness checks and as the value for a `content_sha256` precondition on update. Always populated, regardless of `view`. - `content_size_bytes: number` Size of `content` in bytes (the UTF-8 plaintext length). Always populated, regardless of `view`. - `created_at: string` A timestamp in RFC 3339 format - `memory_store_id: string` ID of the memory store this memory belongs to (a `memstore_...` value). - `memory_version_id: string` ID of the `memory_version` representing this memory's current content (a `memver_...` value). This is the authoritative head pointer; `memory_version` objects do not carry an `is_latest` flag, so compare against this field instead. Enumerate the full history via [List memory versions](/docs/en/api/beta/memory_stores/memory_versions/list). - `path: string` Hierarchical path of the memory within the store, e.g. `/projects/foo/notes.md`. Always starts with `/`. Paths are case-sensitive and unique within a store. Maximum 1,024 bytes. - `type: "memory"` - `"memory"` - `updated_at: string` A timestamp in RFC 3339 format - `content?: string | null` The memory's UTF-8 text content. Populated when `view=full`; `null` when `view=basic`. Maximum 100 kB (102,400 bytes). ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const betaManagedAgentsMemory = await client.beta.memoryStores.memories.retrieve('memory_id', { memory_store_id: 'memory_store_id', }); console.log(betaManagedAgentsMemory.id); ``` #### Response ```json { "id": "id", "content_sha256": "content_sha256", "content_size_bytes": 0, "created_at": "2019-12-27T18:11:19.117Z", "memory_store_id": "memory_store_id", "memory_version_id": "memory_version_id", "path": "path", "type": "memory", "updated_at": "2019-12-27T18:11:19.117Z", "content": "content" } ``` ## Update a memory `client.beta.memoryStores.memories.update(stringmemoryID, MemoryUpdateParamsparams, RequestOptionsoptions?): BetaManagedAgentsMemory` **post** `/v1/memory_stores/{memory_store_id}/memories/{memory_id}` Update a memory ### Parameters - `memoryID: string` - `params: MemoryUpdateParams` - `memory_store_id: string` Path param: Path parameter memory_store_id - `view?: BetaManagedAgentsMemoryView` Query param: Query parameter for view - `"basic"` - `"full"` - `content?: string | null` Body param: New UTF-8 text content for the memory. Maximum 100 kB (102,400 bytes). Omit to leave the content unchanged (e.g., for a rename-only update). - `path?: string | null` Body param: New path for the memory (a rename). Must start with `/`, contain at least one non-empty segment, and be at most 1,024 bytes. Must not contain empty segments, `.` or `..` segments, control or format characters, and must be NFC-normalized. Paths are case-sensitive. The memory's `id` is preserved across renames. Omit to leave the path unchanged. - `precondition?: BetaManagedAgentsPrecondition` Body param: Optimistic-concurrency precondition: the update applies only if the memory's stored `content_sha256` equals the supplied value. On mismatch, the request returns `memory_precondition_failed_error` (HTTP 409); re-read the memory and retry against the fresh state. If the precondition fails but the stored state already exactly matches the requested `content` and `path`, the server returns 200 instead of 409. - `type: "content_sha256"` - `"content_sha256"` - `content_sha256?: string` Expected `content_sha256` of the stored memory (64 lowercase hexadecimal characters). Typically the `content_sha256` returned by a prior read or list call. Because the server applies no content normalization, clients can also compute this locally as the SHA-256 of the UTF-8 content bytes. - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaManagedAgentsMemory` A `memory` object: a single text document at a hierarchical path inside a memory store. The `content` field is populated when `view=full` and `null` when `view=basic`; the `content_size_bytes` and `content_sha256` fields are always populated so sync clients can diff without fetching content. Memories are addressed by their `mem_...` ID; the path is the create key and can be changed via update. - `id: string` Unique identifier for this memory (a `mem_...` value). Stable across renames; use this ID, not the path, to read, update, or delete the memory. - `content_sha256: string` Lowercase hex SHA-256 digest of the UTF-8 `content` bytes (64 characters). The server applies no normalization, so clients can compute the same hash locally for staleness checks and as the value for a `content_sha256` precondition on update. Always populated, regardless of `view`. - `content_size_bytes: number` Size of `content` in bytes (the UTF-8 plaintext length). Always populated, regardless of `view`. - `created_at: string` A timestamp in RFC 3339 format - `memory_store_id: string` ID of the memory store this memory belongs to (a `memstore_...` value). - `memory_version_id: string` ID of the `memory_version` representing this memory's current content (a `memver_...` value). This is the authoritative head pointer; `memory_version` objects do not carry an `is_latest` flag, so compare against this field instead. Enumerate the full history via [List memory versions](/docs/en/api/beta/memory_stores/memory_versions/list). - `path: string` Hierarchical path of the memory within the store, e.g. `/projects/foo/notes.md`. Always starts with `/`. Paths are case-sensitive and unique within a store. Maximum 1,024 bytes. - `type: "memory"` - `"memory"` - `updated_at: string` A timestamp in RFC 3339 format - `content?: string | null` The memory's UTF-8 text content. Populated when `view=full`; `null` when `view=basic`. Maximum 100 kB (102,400 bytes). ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const betaManagedAgentsMemory = await client.beta.memoryStores.memories.update('memory_id', { memory_store_id: 'memory_store_id', }); console.log(betaManagedAgentsMemory.id); ``` #### Response ```json { "id": "id", "content_sha256": "content_sha256", "content_size_bytes": 0, "created_at": "2019-12-27T18:11:19.117Z", "memory_store_id": "memory_store_id", "memory_version_id": "memory_version_id", "path": "path", "type": "memory", "updated_at": "2019-12-27T18:11:19.117Z", "content": "content" } ``` ## Delete a memory `client.beta.memoryStores.memories.delete(stringmemoryID, MemoryDeleteParamsparams, RequestOptionsoptions?): BetaManagedAgentsDeletedMemory` **delete** `/v1/memory_stores/{memory_store_id}/memories/{memory_id}` Delete a memory ### Parameters - `memoryID: string` - `params: MemoryDeleteParams` - `memory_store_id: string` Path param: Path parameter memory_store_id - `expected_content_sha256?: string` Query param: Query parameter for expected_content_sha256 - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaManagedAgentsDeletedMemory` Tombstone returned by [Delete a memory](/docs/en/api/beta/memory_stores/memories/delete). The memory's version history persists and remains listable via [List memory versions](/docs/en/api/beta/memory_stores/memory_versions/list) until the store itself is deleted. - `id: string` ID of the deleted memory (a `mem_...` value). - `type: "memory_deleted"` - `"memory_deleted"` ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const betaManagedAgentsDeletedMemory = await client.beta.memoryStores.memories.delete('memory_id', { memory_store_id: 'memory_store_id', }); console.log(betaManagedAgentsDeletedMemory.id); ``` #### Response ```json { "id": "id", "type": "memory_deleted" } ``` ## Domain Types ### Beta Managed Agents Conflict Error - `BetaManagedAgentsConflictError` - `type: "conflict_error"` - `"conflict_error"` - `message?: string` ### Beta Managed Agents Content Sha256 Precondition - `BetaManagedAgentsContentSha256Precondition` Optimistic-concurrency precondition: the update applies only if the memory's stored `content_sha256` equals the supplied value. On mismatch, the request returns `memory_precondition_failed_error` (HTTP 409); re-read the memory and retry against the fresh state. If the precondition fails but the stored state already exactly matches the requested `content` and `path`, the server returns 200 instead of 409. - `type: "content_sha256"` - `"content_sha256"` - `content_sha256?: string` Expected `content_sha256` of the stored memory (64 lowercase hexadecimal characters). Typically the `content_sha256` returned by a prior read or list call. Because the server applies no content normalization, clients can also compute this locally as the SHA-256 of the UTF-8 content bytes. ### Beta Managed Agents Deleted Memory - `BetaManagedAgentsDeletedMemory` Tombstone returned by [Delete a memory](/docs/en/api/beta/memory_stores/memories/delete). The memory's version history persists and remains listable via [List memory versions](/docs/en/api/beta/memory_stores/memory_versions/list) until the store itself is deleted. - `id: string` ID of the deleted memory (a `mem_...` value). - `type: "memory_deleted"` - `"memory_deleted"` ### Beta Managed Agents Error - `BetaManagedAgentsError = BetaInvalidRequestError | BetaAuthenticationError | BetaBillingError | 9 more` - `BetaInvalidRequestError` - `message: string` - `type: "invalid_request_error"` - `"invalid_request_error"` - `BetaAuthenticationError` - `message: string` - `type: "authentication_error"` - `"authentication_error"` - `BetaBillingError` - `message: string` - `type: "billing_error"` - `"billing_error"` - `BetaPermissionError` - `message: string` - `type: "permission_error"` - `"permission_error"` - `BetaNotFoundError` - `message: string` - `type: "not_found_error"` - `"not_found_error"` - `BetaRateLimitError` - `message: string` - `type: "rate_limit_error"` - `"rate_limit_error"` - `BetaGatewayTimeoutError` - `message: string` - `type: "timeout_error"` - `"timeout_error"` - `BetaAPIError` - `message: string` - `type: "api_error"` - `"api_error"` - `BetaOverloadedError` - `message: string` - `type: "overloaded_error"` - `"overloaded_error"` - `BetaManagedAgentsMemoryPreconditionFailedError` - `type: "memory_precondition_failed_error"` - `"memory_precondition_failed_error"` - `message?: string` - `BetaManagedAgentsMemoryPathConflictError` - `type: "memory_path_conflict_error"` - `"memory_path_conflict_error"` - `conflicting_memory_id?: string` - `conflicting_path?: string` - `message?: string` - `BetaManagedAgentsConflictError` - `type: "conflict_error"` - `"conflict_error"` - `message?: string` ### Beta Managed Agents Memory - `BetaManagedAgentsMemory` A `memory` object: a single text document at a hierarchical path inside a memory store. The `content` field is populated when `view=full` and `null` when `view=basic`; the `content_size_bytes` and `content_sha256` fields are always populated so sync clients can diff without fetching content. Memories are addressed by their `mem_...` ID; the path is the create key and can be changed via update. - `id: string` Unique identifier for this memory (a `mem_...` value). Stable across renames; use this ID, not the path, to read, update, or delete the memory. - `content_sha256: string` Lowercase hex SHA-256 digest of the UTF-8 `content` bytes (64 characters). The server applies no normalization, so clients can compute the same hash locally for staleness checks and as the value for a `content_sha256` precondition on update. Always populated, regardless of `view`. - `content_size_bytes: number` Size of `content` in bytes (the UTF-8 plaintext length). Always populated, regardless of `view`. - `created_at: string` A timestamp in RFC 3339 format - `memory_store_id: string` ID of the memory store this memory belongs to (a `memstore_...` value). - `memory_version_id: string` ID of the `memory_version` representing this memory's current content (a `memver_...` value). This is the authoritative head pointer; `memory_version` objects do not carry an `is_latest` flag, so compare against this field instead. Enumerate the full history via [List memory versions](/docs/en/api/beta/memory_stores/memory_versions/list). - `path: string` Hierarchical path of the memory within the store, e.g. `/projects/foo/notes.md`. Always starts with `/`. Paths are case-sensitive and unique within a store. Maximum 1,024 bytes. - `type: "memory"` - `"memory"` - `updated_at: string` A timestamp in RFC 3339 format - `content?: string | null` The memory's UTF-8 text content. Populated when `view=full`; `null` when `view=basic`. Maximum 100 kB (102,400 bytes). ### Beta Managed Agents Memory List Item - `BetaManagedAgentsMemoryListItem = BetaManagedAgentsMemory | BetaManagedAgentsMemoryPrefix` One item in a [List memories](/docs/en/api/beta/memory_stores/memories/list) response: either a `memory` object or, when `depth` is set, a `memory_prefix` rollup marker. - `BetaManagedAgentsMemory` A `memory` object: a single text document at a hierarchical path inside a memory store. The `content` field is populated when `view=full` and `null` when `view=basic`; the `content_size_bytes` and `content_sha256` fields are always populated so sync clients can diff without fetching content. Memories are addressed by their `mem_...` ID; the path is the create key and can be changed via update. - `id: string` Unique identifier for this memory (a `mem_...` value). Stable across renames; use this ID, not the path, to read, update, or delete the memory. - `content_sha256: string` Lowercase hex SHA-256 digest of the UTF-8 `content` bytes (64 characters). The server applies no normalization, so clients can compute the same hash locally for staleness checks and as the value for a `content_sha256` precondition on update. Always populated, regardless of `view`. - `content_size_bytes: number` Size of `content` in bytes (the UTF-8 plaintext length). Always populated, regardless of `view`. - `created_at: string` A timestamp in RFC 3339 format - `memory_store_id: string` ID of the memory store this memory belongs to (a `memstore_...` value). - `memory_version_id: string` ID of the `memory_version` representing this memory's current content (a `memver_...` value). This is the authoritative head pointer; `memory_version` objects do not carry an `is_latest` flag, so compare against this field instead. Enumerate the full history via [List memory versions](/docs/en/api/beta/memory_stores/memory_versions/list). - `path: string` Hierarchical path of the memory within the store, e.g. `/projects/foo/notes.md`. Always starts with `/`. Paths are case-sensitive and unique within a store. Maximum 1,024 bytes. - `type: "memory"` - `"memory"` - `updated_at: string` A timestamp in RFC 3339 format - `content?: string | null` The memory's UTF-8 text content. Populated when `view=full`; `null` when `view=basic`. Maximum 100 kB (102,400 bytes). - `BetaManagedAgentsMemoryPrefix` A rolled-up directory marker returned by [List memories](/docs/en/api/beta/memory_stores/memories/list) when `depth` is set. Indicates that one or more memories exist deeper than the requested depth under this prefix. This is a list-time rollup, not a stored resource; it has no ID and no lifecycle. Each prefix counts toward the page `limit` and interleaves with `memory` items in path order. - `path: string` The rolled-up path prefix, including a trailing `/` (e.g. `/projects/foo/`). Pass this value as `path_prefix` on a subsequent list call to drill into the directory. - `type: "memory_prefix"` - `"memory_prefix"` ### Beta Managed Agents Memory Path Conflict Error - `BetaManagedAgentsMemoryPathConflictError` - `type: "memory_path_conflict_error"` - `"memory_path_conflict_error"` - `conflicting_memory_id?: string` - `conflicting_path?: string` - `message?: string` ### Beta Managed Agents Memory Precondition Failed Error - `BetaManagedAgentsMemoryPreconditionFailedError` - `type: "memory_precondition_failed_error"` - `"memory_precondition_failed_error"` - `message?: string` ### Beta Managed Agents Memory Prefix - `BetaManagedAgentsMemoryPrefix` A rolled-up directory marker returned by [List memories](/docs/en/api/beta/memory_stores/memories/list) when `depth` is set. Indicates that one or more memories exist deeper than the requested depth under this prefix. This is a list-time rollup, not a stored resource; it has no ID and no lifecycle. Each prefix counts toward the page `limit` and interleaves with `memory` items in path order. - `path: string` The rolled-up path prefix, including a trailing `/` (e.g. `/projects/foo/`). Pass this value as `path_prefix` on a subsequent list call to drill into the directory. - `type: "memory_prefix"` - `"memory_prefix"` ### Beta Managed Agents Memory View - `BetaManagedAgentsMemoryView = "basic" | "full"` Selects which projection of a `memory` or `memory_version` the server returns. `basic` returns the object with `content` set to `null`; `full` populates `content`. When omitted, the default is endpoint-specific: retrieve operations default to `full`; list, create, and update operations default to `basic`. Listing with `view=full` caps `limit` at 20. - `"basic"` - `"full"` ### Beta Managed Agents Precondition - `BetaManagedAgentsPrecondition` Optimistic-concurrency precondition: the update applies only if the memory's stored `content_sha256` equals the supplied value. On mismatch, the request returns `memory_precondition_failed_error` (HTTP 409); re-read the memory and retry against the fresh state. If the precondition fails but the stored state already exactly matches the requested `content` and `path`, the server returns 200 instead of 409. - `type: "content_sha256"` - `"content_sha256"` - `content_sha256?: string` Expected `content_sha256` of the stored memory (64 lowercase hexadecimal characters). Typically the `content_sha256` returned by a prior read or list call. Because the server applies no content normalization, clients can also compute this locally as the SHA-256 of the UTF-8 content bytes. # Memory Versions ## List memory versions `client.beta.memoryStores.memoryVersions.list(stringmemoryStoreID, MemoryVersionListParamsparams?, RequestOptionsoptions?): PageCursor` **get** `/v1/memory_stores/{memory_store_id}/memory_versions` List memory versions ### Parameters - `memoryStoreID: string` - `params: MemoryVersionListParams` - `api_key_id?: string` Query param: Query parameter for api_key_id - `"created_at[gte]"?: string` Query param: Return versions created at or after this time (inclusive). - `"created_at[lte]"?: string` Query param: Return versions created at or before this time (inclusive). - `limit?: number` Query param: Query parameter for limit - `memory_id?: string` Query param: Query parameter for memory_id - `operation?: BetaManagedAgentsMemoryVersionOperation` Query param: Query parameter for operation - `"created"` - `"modified"` - `"deleted"` - `page?: string` Query param: Query parameter for page - `session_id?: string` Query param: Query parameter for session_id - `view?: BetaManagedAgentsMemoryView` Query param: Query parameter for view - `"basic"` - `"full"` - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaManagedAgentsMemoryVersion` A `memory_version` object: one immutable, attributed row in a memory's append-only history. Every non-no-op mutation to a memory produces a new version. Versions belong to the store (not the individual memory) and persist after the memory is deleted. Retrieving a redacted version returns 200 with `content`, `path`, `content_size_bytes`, and `content_sha256` set to `null`; branch on `redacted_at`, not HTTP status. - `id: string` Unique identifier for this version (a `memver_...` value). - `created_at: string` A timestamp in RFC 3339 format - `memory_id: string` ID of the memory this version snapshots (a `mem_...` value). Remains valid after the memory is deleted; pass it as `memory_id` to [List memory versions](/docs/en/api/beta/memory_stores/memory_versions/list) to retrieve the full lineage including the `deleted` row. - `memory_store_id: string` ID of the memory store this version belongs to (a `memstore_...` value). - `operation: BetaManagedAgentsMemoryVersionOperation` The kind of mutation a `memory_version` records. Every non-no-op mutation to a memory appends exactly one version row with one of these values. - `"created"` - `"modified"` - `"deleted"` - `type: "memory_version"` - `"memory_version"` - `content?: string | null` The memory's UTF-8 text content as of this version. `null` when `view=basic`, when `operation` is `deleted`, or when `redacted_at` is set. - `content_sha256?: string | null` Lowercase hex SHA-256 digest of `content` as of this version (64 characters). `null` when `redacted_at` is set or `operation` is `deleted`. Populated regardless of `view` otherwise. - `content_size_bytes?: number | null` Size of `content` in bytes as of this version. `null` when `redacted_at` is set or `operation` is `deleted`. Populated regardless of `view` otherwise. - `created_by?: BetaManagedAgentsActor` Identifies who performed a write or redact operation. Captured at write time on the `memory_version` row. The API key that created a session is not recorded on agent writes; attribution answers who made the write, not who is ultimately responsible. Look up session provenance separately via the [Sessions API](/docs/en/api/sessions-retrieve). - `BetaManagedAgentsSessionActor` Attribution for a write made by an agent during a session, through the mounted filesystem at `/mnt/memory/`. - `session_id: string` ID of the session that performed the write (a `sesn_...` value). Look up the session via [Retrieve a session](/docs/en/api/sessions-retrieve) for further provenance. - `type: "session_actor"` - `"session_actor"` - `BetaManagedAgentsAPIActor` Attribution for a write made directly via the public API (outside of any session). - `api_key_id: string` ID of the API key that performed the write. This identifies the key, not the secret. - `type: "api_actor"` - `"api_actor"` - `BetaManagedAgentsUserActor` Attribution for a write made by a human user through the Anthropic Console. - `type: "user_actor"` - `"user_actor"` - `user_id: string` ID of the user who performed the write (a `user_...` value). - `path?: string | null` The memory's path at the time of this write. `null` if and only if `redacted_at` is set. - `redacted_at?: string | null` A timestamp in RFC 3339 format - `redacted_by?: BetaManagedAgentsActor` Identifies who performed a write or redact operation. Captured at write time on the `memory_version` row. The API key that created a session is not recorded on agent writes; attribution answers who made the write, not who is ultimately responsible. Look up session provenance separately via the [Sessions API](/docs/en/api/sessions-retrieve). ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); // Automatically fetches more pages as needed. for await (const betaManagedAgentsMemoryVersion of client.beta.memoryStores.memoryVersions.list( 'memory_store_id', )) { console.log(betaManagedAgentsMemoryVersion.id); } ``` #### Response ```json { "data": [ { "id": "id", "created_at": "2019-12-27T18:11:19.117Z", "memory_id": "memory_id", "memory_store_id": "memory_store_id", "operation": "created", "type": "memory_version", "content": "content", "content_sha256": "content_sha256", "content_size_bytes": 0, "created_by": { "session_id": "x", "type": "session_actor" }, "path": "path", "redacted_at": "2019-12-27T18:11:19.117Z", "redacted_by": { "session_id": "x", "type": "session_actor" } } ], "next_page": "next_page" } ``` ## Retrieve a memory version `client.beta.memoryStores.memoryVersions.retrieve(stringmemoryVersionID, MemoryVersionRetrieveParamsparams, RequestOptionsoptions?): BetaManagedAgentsMemoryVersion` **get** `/v1/memory_stores/{memory_store_id}/memory_versions/{memory_version_id}` Retrieve a memory version ### Parameters - `memoryVersionID: string` - `params: MemoryVersionRetrieveParams` - `memory_store_id: string` Path param: Path parameter memory_store_id - `view?: BetaManagedAgentsMemoryView` Query param: Query parameter for view - `"basic"` - `"full"` - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaManagedAgentsMemoryVersion` A `memory_version` object: one immutable, attributed row in a memory's append-only history. Every non-no-op mutation to a memory produces a new version. Versions belong to the store (not the individual memory) and persist after the memory is deleted. Retrieving a redacted version returns 200 with `content`, `path`, `content_size_bytes`, and `content_sha256` set to `null`; branch on `redacted_at`, not HTTP status. - `id: string` Unique identifier for this version (a `memver_...` value). - `created_at: string` A timestamp in RFC 3339 format - `memory_id: string` ID of the memory this version snapshots (a `mem_...` value). Remains valid after the memory is deleted; pass it as `memory_id` to [List memory versions](/docs/en/api/beta/memory_stores/memory_versions/list) to retrieve the full lineage including the `deleted` row. - `memory_store_id: string` ID of the memory store this version belongs to (a `memstore_...` value). - `operation: BetaManagedAgentsMemoryVersionOperation` The kind of mutation a `memory_version` records. Every non-no-op mutation to a memory appends exactly one version row with one of these values. - `"created"` - `"modified"` - `"deleted"` - `type: "memory_version"` - `"memory_version"` - `content?: string | null` The memory's UTF-8 text content as of this version. `null` when `view=basic`, when `operation` is `deleted`, or when `redacted_at` is set. - `content_sha256?: string | null` Lowercase hex SHA-256 digest of `content` as of this version (64 characters). `null` when `redacted_at` is set or `operation` is `deleted`. Populated regardless of `view` otherwise. - `content_size_bytes?: number | null` Size of `content` in bytes as of this version. `null` when `redacted_at` is set or `operation` is `deleted`. Populated regardless of `view` otherwise. - `created_by?: BetaManagedAgentsActor` Identifies who performed a write or redact operation. Captured at write time on the `memory_version` row. The API key that created a session is not recorded on agent writes; attribution answers who made the write, not who is ultimately responsible. Look up session provenance separately via the [Sessions API](/docs/en/api/sessions-retrieve). - `BetaManagedAgentsSessionActor` Attribution for a write made by an agent during a session, through the mounted filesystem at `/mnt/memory/`. - `session_id: string` ID of the session that performed the write (a `sesn_...` value). Look up the session via [Retrieve a session](/docs/en/api/sessions-retrieve) for further provenance. - `type: "session_actor"` - `"session_actor"` - `BetaManagedAgentsAPIActor` Attribution for a write made directly via the public API (outside of any session). - `api_key_id: string` ID of the API key that performed the write. This identifies the key, not the secret. - `type: "api_actor"` - `"api_actor"` - `BetaManagedAgentsUserActor` Attribution for a write made by a human user through the Anthropic Console. - `type: "user_actor"` - `"user_actor"` - `user_id: string` ID of the user who performed the write (a `user_...` value). - `path?: string | null` The memory's path at the time of this write. `null` if and only if `redacted_at` is set. - `redacted_at?: string | null` A timestamp in RFC 3339 format - `redacted_by?: BetaManagedAgentsActor` Identifies who performed a write or redact operation. Captured at write time on the `memory_version` row. The API key that created a session is not recorded on agent writes; attribution answers who made the write, not who is ultimately responsible. Look up session provenance separately via the [Sessions API](/docs/en/api/sessions-retrieve). ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const betaManagedAgentsMemoryVersion = await client.beta.memoryStores.memoryVersions.retrieve( 'memory_version_id', { memory_store_id: 'memory_store_id' }, ); console.log(betaManagedAgentsMemoryVersion.id); ``` #### Response ```json { "id": "id", "created_at": "2019-12-27T18:11:19.117Z", "memory_id": "memory_id", "memory_store_id": "memory_store_id", "operation": "created", "type": "memory_version", "content": "content", "content_sha256": "content_sha256", "content_size_bytes": 0, "created_by": { "session_id": "x", "type": "session_actor" }, "path": "path", "redacted_at": "2019-12-27T18:11:19.117Z", "redacted_by": { "session_id": "x", "type": "session_actor" } } ``` ## Redact a memory version `client.beta.memoryStores.memoryVersions.redact(stringmemoryVersionID, MemoryVersionRedactParamsparams, RequestOptionsoptions?): BetaManagedAgentsMemoryVersion` **post** `/v1/memory_stores/{memory_store_id}/memory_versions/{memory_version_id}/redact` Redact a memory version ### Parameters - `memoryVersionID: string` - `params: MemoryVersionRedactParams` - `memory_store_id: string` Path param: Path parameter memory_store_id - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaManagedAgentsMemoryVersion` A `memory_version` object: one immutable, attributed row in a memory's append-only history. Every non-no-op mutation to a memory produces a new version. Versions belong to the store (not the individual memory) and persist after the memory is deleted. Retrieving a redacted version returns 200 with `content`, `path`, `content_size_bytes`, and `content_sha256` set to `null`; branch on `redacted_at`, not HTTP status. - `id: string` Unique identifier for this version (a `memver_...` value). - `created_at: string` A timestamp in RFC 3339 format - `memory_id: string` ID of the memory this version snapshots (a `mem_...` value). Remains valid after the memory is deleted; pass it as `memory_id` to [List memory versions](/docs/en/api/beta/memory_stores/memory_versions/list) to retrieve the full lineage including the `deleted` row. - `memory_store_id: string` ID of the memory store this version belongs to (a `memstore_...` value). - `operation: BetaManagedAgentsMemoryVersionOperation` The kind of mutation a `memory_version` records. Every non-no-op mutation to a memory appends exactly one version row with one of these values. - `"created"` - `"modified"` - `"deleted"` - `type: "memory_version"` - `"memory_version"` - `content?: string | null` The memory's UTF-8 text content as of this version. `null` when `view=basic`, when `operation` is `deleted`, or when `redacted_at` is set. - `content_sha256?: string | null` Lowercase hex SHA-256 digest of `content` as of this version (64 characters). `null` when `redacted_at` is set or `operation` is `deleted`. Populated regardless of `view` otherwise. - `content_size_bytes?: number | null` Size of `content` in bytes as of this version. `null` when `redacted_at` is set or `operation` is `deleted`. Populated regardless of `view` otherwise. - `created_by?: BetaManagedAgentsActor` Identifies who performed a write or redact operation. Captured at write time on the `memory_version` row. The API key that created a session is not recorded on agent writes; attribution answers who made the write, not who is ultimately responsible. Look up session provenance separately via the [Sessions API](/docs/en/api/sessions-retrieve). - `BetaManagedAgentsSessionActor` Attribution for a write made by an agent during a session, through the mounted filesystem at `/mnt/memory/`. - `session_id: string` ID of the session that performed the write (a `sesn_...` value). Look up the session via [Retrieve a session](/docs/en/api/sessions-retrieve) for further provenance. - `type: "session_actor"` - `"session_actor"` - `BetaManagedAgentsAPIActor` Attribution for a write made directly via the public API (outside of any session). - `api_key_id: string` ID of the API key that performed the write. This identifies the key, not the secret. - `type: "api_actor"` - `"api_actor"` - `BetaManagedAgentsUserActor` Attribution for a write made by a human user through the Anthropic Console. - `type: "user_actor"` - `"user_actor"` - `user_id: string` ID of the user who performed the write (a `user_...` value). - `path?: string | null` The memory's path at the time of this write. `null` if and only if `redacted_at` is set. - `redacted_at?: string | null` A timestamp in RFC 3339 format - `redacted_by?: BetaManagedAgentsActor` Identifies who performed a write or redact operation. Captured at write time on the `memory_version` row. The API key that created a session is not recorded on agent writes; attribution answers who made the write, not who is ultimately responsible. Look up session provenance separately via the [Sessions API](/docs/en/api/sessions-retrieve). ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const betaManagedAgentsMemoryVersion = await client.beta.memoryStores.memoryVersions.redact( 'memory_version_id', { memory_store_id: 'memory_store_id' }, ); console.log(betaManagedAgentsMemoryVersion.id); ``` #### Response ```json { "id": "id", "created_at": "2019-12-27T18:11:19.117Z", "memory_id": "memory_id", "memory_store_id": "memory_store_id", "operation": "created", "type": "memory_version", "content": "content", "content_sha256": "content_sha256", "content_size_bytes": 0, "created_by": { "session_id": "x", "type": "session_actor" }, "path": "path", "redacted_at": "2019-12-27T18:11:19.117Z", "redacted_by": { "session_id": "x", "type": "session_actor" } } ``` ## Domain Types ### Beta Managed Agents Actor - `BetaManagedAgentsActor = BetaManagedAgentsSessionActor | BetaManagedAgentsAPIActor | BetaManagedAgentsUserActor` Identifies who performed a write or redact operation. Captured at write time on the `memory_version` row. The API key that created a session is not recorded on agent writes; attribution answers who made the write, not who is ultimately responsible. Look up session provenance separately via the [Sessions API](/docs/en/api/sessions-retrieve). - `BetaManagedAgentsSessionActor` Attribution for a write made by an agent during a session, through the mounted filesystem at `/mnt/memory/`. - `session_id: string` ID of the session that performed the write (a `sesn_...` value). Look up the session via [Retrieve a session](/docs/en/api/sessions-retrieve) for further provenance. - `type: "session_actor"` - `"session_actor"` - `BetaManagedAgentsAPIActor` Attribution for a write made directly via the public API (outside of any session). - `api_key_id: string` ID of the API key that performed the write. This identifies the key, not the secret. - `type: "api_actor"` - `"api_actor"` - `BetaManagedAgentsUserActor` Attribution for a write made by a human user through the Anthropic Console. - `type: "user_actor"` - `"user_actor"` - `user_id: string` ID of the user who performed the write (a `user_...` value). ### Beta Managed Agents API Actor - `BetaManagedAgentsAPIActor` Attribution for a write made directly via the public API (outside of any session). - `api_key_id: string` ID of the API key that performed the write. This identifies the key, not the secret. - `type: "api_actor"` - `"api_actor"` ### Beta Managed Agents Memory Version - `BetaManagedAgentsMemoryVersion` A `memory_version` object: one immutable, attributed row in a memory's append-only history. Every non-no-op mutation to a memory produces a new version. Versions belong to the store (not the individual memory) and persist after the memory is deleted. Retrieving a redacted version returns 200 with `content`, `path`, `content_size_bytes`, and `content_sha256` set to `null`; branch on `redacted_at`, not HTTP status. - `id: string` Unique identifier for this version (a `memver_...` value). - `created_at: string` A timestamp in RFC 3339 format - `memory_id: string` ID of the memory this version snapshots (a `mem_...` value). Remains valid after the memory is deleted; pass it as `memory_id` to [List memory versions](/docs/en/api/beta/memory_stores/memory_versions/list) to retrieve the full lineage including the `deleted` row. - `memory_store_id: string` ID of the memory store this version belongs to (a `memstore_...` value). - `operation: BetaManagedAgentsMemoryVersionOperation` The kind of mutation a `memory_version` records. Every non-no-op mutation to a memory appends exactly one version row with one of these values. - `"created"` - `"modified"` - `"deleted"` - `type: "memory_version"` - `"memory_version"` - `content?: string | null` The memory's UTF-8 text content as of this version. `null` when `view=basic`, when `operation` is `deleted`, or when `redacted_at` is set. - `content_sha256?: string | null` Lowercase hex SHA-256 digest of `content` as of this version (64 characters). `null` when `redacted_at` is set or `operation` is `deleted`. Populated regardless of `view` otherwise. - `content_size_bytes?: number | null` Size of `content` in bytes as of this version. `null` when `redacted_at` is set or `operation` is `deleted`. Populated regardless of `view` otherwise. - `created_by?: BetaManagedAgentsActor` Identifies who performed a write or redact operation. Captured at write time on the `memory_version` row. The API key that created a session is not recorded on agent writes; attribution answers who made the write, not who is ultimately responsible. Look up session provenance separately via the [Sessions API](/docs/en/api/sessions-retrieve). - `BetaManagedAgentsSessionActor` Attribution for a write made by an agent during a session, through the mounted filesystem at `/mnt/memory/`. - `session_id: string` ID of the session that performed the write (a `sesn_...` value). Look up the session via [Retrieve a session](/docs/en/api/sessions-retrieve) for further provenance. - `type: "session_actor"` - `"session_actor"` - `BetaManagedAgentsAPIActor` Attribution for a write made directly via the public API (outside of any session). - `api_key_id: string` ID of the API key that performed the write. This identifies the key, not the secret. - `type: "api_actor"` - `"api_actor"` - `BetaManagedAgentsUserActor` Attribution for a write made by a human user through the Anthropic Console. - `type: "user_actor"` - `"user_actor"` - `user_id: string` ID of the user who performed the write (a `user_...` value). - `path?: string | null` The memory's path at the time of this write. `null` if and only if `redacted_at` is set. - `redacted_at?: string | null` A timestamp in RFC 3339 format - `redacted_by?: BetaManagedAgentsActor` Identifies who performed a write or redact operation. Captured at write time on the `memory_version` row. The API key that created a session is not recorded on agent writes; attribution answers who made the write, not who is ultimately responsible. Look up session provenance separately via the [Sessions API](/docs/en/api/sessions-retrieve). ### Beta Managed Agents Memory Version Operation - `BetaManagedAgentsMemoryVersionOperation = "created" | "modified" | "deleted"` The kind of mutation a `memory_version` records. Every non-no-op mutation to a memory appends exactly one version row with one of these values. - `"created"` - `"modified"` - `"deleted"` ### Beta Managed Agents Session Actor - `BetaManagedAgentsSessionActor` Attribution for a write made by an agent during a session, through the mounted filesystem at `/mnt/memory/`. - `session_id: string` ID of the session that performed the write (a `sesn_...` value). Look up the session via [Retrieve a session](/docs/en/api/sessions-retrieve) for further provenance. - `type: "session_actor"` - `"session_actor"` ### Beta Managed Agents User Actor - `BetaManagedAgentsUserActor` Attribution for a write made by a human user through the Anthropic Console. - `type: "user_actor"` - `"user_actor"` - `user_id: string` ID of the user who performed the write (a `user_...` value). # Files ## Upload File `client.beta.files.upload(FileUploadParamsparams, RequestOptionsoptions?): FileMetadata` **post** `/v1/files` Upload File ### Parameters - `params: FileUploadParams` - `file: Uploadable` Body param: The file to upload - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `FileMetadata` - `id: string` Unique object identifier. The format and length of IDs may change over time. - `created_at: string` RFC 3339 datetime string representing when the file was created. - `filename: string` Original filename of the uploaded file. - `mime_type: string` MIME type of the file. - `size_bytes: number` Size of the file in bytes. - `type: "file"` Object type. For files, this is always `"file"`. - `"file"` - `downloadable?: boolean` Whether the file can be downloaded. - `scope?: BetaFileScope | null` The scope of this file, indicating the context in which it was created (e.g., a session). - `id: string` The ID of the scoping resource (e.g., the session ID). - `type: "session"` The type of scope (e.g., `"session"`). - `"session"` ### Example ```typescript import fs from 'fs'; import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const fileMetadata = await client.beta.files.upload({ file: fs.createReadStream('path/to/file') }); console.log(fileMetadata.id); ``` #### Response ```json { "id": "file_011CNha8iCJcU1wXNR6q4V8w", "created_at": "2025-04-15T18:37:24.100435Z", "filename": "document.pdf", "mime_type": "application/pdf", "size_bytes": 102400, "type": "file", "downloadable": false, "scope": { "id": "id", "type": "session" } } ``` ## List Files `client.beta.files.list(FileListParamsparams?, RequestOptionsoptions?): Page` **get** `/v1/files` List Files ### Parameters - `params: FileListParams` - `after_id?: string` Query param: ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object. - `before_id?: string` Query param: ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object. - `limit?: number` Query param: Number of items to return per page. Defaults to `20`. Ranges from `1` to `1000`. - `scope_id?: string` Query param: Filter by scope ID. Only returns files associated with the specified scope (e.g., a session ID). - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `FileMetadata` - `id: string` Unique object identifier. The format and length of IDs may change over time. - `created_at: string` RFC 3339 datetime string representing when the file was created. - `filename: string` Original filename of the uploaded file. - `mime_type: string` MIME type of the file. - `size_bytes: number` Size of the file in bytes. - `type: "file"` Object type. For files, this is always `"file"`. - `"file"` - `downloadable?: boolean` Whether the file can be downloaded. - `scope?: BetaFileScope | null` The scope of this file, indicating the context in which it was created (e.g., a session). - `id: string` The ID of the scoping resource (e.g., the session ID). - `type: "session"` The type of scope (e.g., `"session"`). - `"session"` ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); // Automatically fetches more pages as needed. for await (const fileMetadata of client.beta.files.list()) { console.log(fileMetadata.id); } ``` #### Response ```json { "data": [ { "id": "file_011CNha8iCJcU1wXNR6q4V8w", "created_at": "2025-04-15T18:37:24.100435Z", "filename": "document.pdf", "mime_type": "application/pdf", "size_bytes": 102400, "type": "file", "downloadable": false, "scope": { "id": "id", "type": "session" } } ], "first_id": "file_011CNha8iCJcU1wXNR6q4V8w", "has_more": true, "last_id": "file_013Zva2CMHLNnXjNJJKqJ2EF" } ``` ## Download File `client.beta.files.download(stringfileID, FileDownloadParamsparams?, RequestOptionsoptions?): Response` **get** `/v1/files/{file_id}/content` Download File ### Parameters - `fileID: string` ID of the File. - `params: FileDownloadParams` - `betas?: Array` Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `unnamed_schema_2 = Response` ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const response = await client.beta.files.download('file_id'); console.log(response); const content = await response.blob(); console.log(content); ``` ## Get File Metadata `client.beta.files.retrieveMetadata(stringfileID, FileRetrieveMetadataParamsparams?, RequestOptionsoptions?): FileMetadata` **get** `/v1/files/{file_id}` Get File Metadata ### Parameters - `fileID: string` ID of the File. - `params: FileRetrieveMetadataParams` - `betas?: Array` Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `FileMetadata` - `id: string` Unique object identifier. The format and length of IDs may change over time. - `created_at: string` RFC 3339 datetime string representing when the file was created. - `filename: string` Original filename of the uploaded file. - `mime_type: string` MIME type of the file. - `size_bytes: number` Size of the file in bytes. - `type: "file"` Object type. For files, this is always `"file"`. - `"file"` - `downloadable?: boolean` Whether the file can be downloaded. - `scope?: BetaFileScope | null` The scope of this file, indicating the context in which it was created (e.g., a session). - `id: string` The ID of the scoping resource (e.g., the session ID). - `type: "session"` The type of scope (e.g., `"session"`). - `"session"` ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const fileMetadata = await client.beta.files.retrieveMetadata('file_id'); console.log(fileMetadata.id); ``` #### Response ```json { "id": "file_011CNha8iCJcU1wXNR6q4V8w", "created_at": "2025-04-15T18:37:24.100435Z", "filename": "document.pdf", "mime_type": "application/pdf", "size_bytes": 102400, "type": "file", "downloadable": false, "scope": { "id": "id", "type": "session" } } ``` ## Delete File `client.beta.files.delete(stringfileID, FileDeleteParamsparams?, RequestOptionsoptions?): DeletedFile` **delete** `/v1/files/{file_id}` Delete File ### Parameters - `fileID: string` ID of the File. - `params: FileDeleteParams` - `betas?: Array` Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `DeletedFile` - `id: string` ID of the deleted file. - `type?: "file_deleted"` Deleted object type. For file deletion, this is always `"file_deleted"`. - `"file_deleted"` ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const deletedFile = await client.beta.files.delete('file_id'); console.log(deletedFile.id); ``` #### Response ```json { "id": "file_011CNha8iCJcU1wXNR6q4V8w", "type": "file_deleted" } ``` ## Domain Types ### Beta File Scope - `BetaFileScope` - `id: string` The ID of the scoping resource (e.g., the session ID). - `type: "session"` The type of scope (e.g., `"session"`). - `"session"` ### Deleted File - `DeletedFile` - `id: string` ID of the deleted file. - `type?: "file_deleted"` Deleted object type. For file deletion, this is always `"file_deleted"`. - `"file_deleted"` ### File Metadata - `FileMetadata` - `id: string` Unique object identifier. The format and length of IDs may change over time. - `created_at: string` RFC 3339 datetime string representing when the file was created. - `filename: string` Original filename of the uploaded file. - `mime_type: string` MIME type of the file. - `size_bytes: number` Size of the file in bytes. - `type: "file"` Object type. For files, this is always `"file"`. - `"file"` - `downloadable?: boolean` Whether the file can be downloaded. - `scope?: BetaFileScope | null` The scope of this file, indicating the context in which it was created (e.g., a session). - `id: string` The ID of the scoping resource (e.g., the session ID). - `type: "session"` The type of scope (e.g., `"session"`). - `"session"` # Skills ## Create Skill `client.beta.skills.create(SkillCreateParamsparams?, RequestOptionsoptions?): SkillCreateResponse` **post** `/v1/skills` Create Skill ### Parameters - `params: SkillCreateParams` - `display_title?: string | null` Body param: Display title for the skill. This is a human-readable label that is not included in the prompt sent to the model. - `files?: Array | null` Body param: Files to upload for the skill. All files must be in the same top-level directory and must include a SKILL.md file at the root of that directory. - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `SkillCreateResponse` - `id: string` Unique identifier for the skill. The format and length of IDs may change over time. - `created_at: string` ISO 8601 timestamp of when the skill was created. - `display_title: string | null` Display title for the skill. This is a human-readable label that is not included in the prompt sent to the model. - `latest_version: string | null` The latest version identifier for the skill. This represents the most recent version of the skill that has been created. - `source: string` Source of the skill. This may be one of the following values: * `"custom"`: the skill was created by a user * `"anthropic"`: the skill was created by Anthropic - `type: string` Object type. For Skills, this is always `"skill"`. - `updated_at: string` ISO 8601 timestamp of when the skill was last updated. ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const skill = await client.beta.skills.create(); console.log(skill.id); ``` #### Response ```json { "id": "skill_01JAbcdefghijklmnopqrstuvw", "created_at": "2024-10-30T23:58:27.427722Z", "display_title": "My Custom Skill", "latest_version": "1759178010641129", "source": "custom", "type": "type", "updated_at": "2024-10-30T23:58:27.427722Z" } ``` ## List Skills `client.beta.skills.list(SkillListParamsparams?, RequestOptionsoptions?): PageCursor` **get** `/v1/skills` List Skills ### Parameters - `params: SkillListParams` - `limit?: number` Query param: Number of results to return per page. Maximum value is 100. Defaults to 20. - `page?: string | null` Query param: Pagination token for fetching a specific page of results. Pass the value from a previous response's `next_page` field to get the next page of results. - `source?: string | null` Query param: Filter skills by source. If provided, only skills from the specified source will be returned: * `"custom"`: only return user-created skills * `"anthropic"`: only return Anthropic-created skills - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `SkillListResponse` - `id: string` Unique identifier for the skill. The format and length of IDs may change over time. - `created_at: string` ISO 8601 timestamp of when the skill was created. - `display_title: string | null` Display title for the skill. This is a human-readable label that is not included in the prompt sent to the model. - `latest_version: string | null` The latest version identifier for the skill. This represents the most recent version of the skill that has been created. - `source: string` Source of the skill. This may be one of the following values: * `"custom"`: the skill was created by a user * `"anthropic"`: the skill was created by Anthropic - `type: string` Object type. For Skills, this is always `"skill"`. - `updated_at: string` ISO 8601 timestamp of when the skill was last updated. ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); // Automatically fetches more pages as needed. for await (const skillListResponse of client.beta.skills.list()) { console.log(skillListResponse.id); } ``` #### Response ```json { "data": [ { "id": "skill_01JAbcdefghijklmnopqrstuvw", "created_at": "2024-10-30T23:58:27.427722Z", "display_title": "My Custom Skill", "latest_version": "1759178010641129", "source": "custom", "type": "type", "updated_at": "2024-10-30T23:58:27.427722Z" } ], "has_more": true, "next_page": "page_MjAyNS0wNS0xNFQwMDowMDowMFo=" } ``` ## Get Skill `client.beta.skills.retrieve(stringskillID, SkillRetrieveParamsparams?, RequestOptionsoptions?): SkillRetrieveResponse` **get** `/v1/skills/{skill_id}` Get Skill ### Parameters - `skillID: string` Unique identifier for the skill. The format and length of IDs may change over time. - `params: SkillRetrieveParams` - `betas?: Array` Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `SkillRetrieveResponse` - `id: string` Unique identifier for the skill. The format and length of IDs may change over time. - `created_at: string` ISO 8601 timestamp of when the skill was created. - `display_title: string | null` Display title for the skill. This is a human-readable label that is not included in the prompt sent to the model. - `latest_version: string | null` The latest version identifier for the skill. This represents the most recent version of the skill that has been created. - `source: string` Source of the skill. This may be one of the following values: * `"custom"`: the skill was created by a user * `"anthropic"`: the skill was created by Anthropic - `type: string` Object type. For Skills, this is always `"skill"`. - `updated_at: string` ISO 8601 timestamp of when the skill was last updated. ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const skill = await client.beta.skills.retrieve('skill_id'); console.log(skill.id); ``` #### Response ```json { "id": "skill_01JAbcdefghijklmnopqrstuvw", "created_at": "2024-10-30T23:58:27.427722Z", "display_title": "My Custom Skill", "latest_version": "1759178010641129", "source": "custom", "type": "type", "updated_at": "2024-10-30T23:58:27.427722Z" } ``` ## Delete Skill `client.beta.skills.delete(stringskillID, SkillDeleteParamsparams?, RequestOptionsoptions?): SkillDeleteResponse` **delete** `/v1/skills/{skill_id}` Delete Skill ### Parameters - `skillID: string` Unique identifier for the skill. The format and length of IDs may change over time. - `params: SkillDeleteParams` - `betas?: Array` Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `SkillDeleteResponse` - `id: string` Unique identifier for the skill. The format and length of IDs may change over time. - `type: string` Deleted object type. For Skills, this is always `"skill_deleted"`. ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const skill = await client.beta.skills.delete('skill_id'); console.log(skill.id); ``` #### Response ```json { "id": "skill_01JAbcdefghijklmnopqrstuvw", "type": "type" } ``` ## Domain Types ### Skill Create Response - `SkillCreateResponse` - `id: string` Unique identifier for the skill. The format and length of IDs may change over time. - `created_at: string` ISO 8601 timestamp of when the skill was created. - `display_title: string | null` Display title for the skill. This is a human-readable label that is not included in the prompt sent to the model. - `latest_version: string | null` The latest version identifier for the skill. This represents the most recent version of the skill that has been created. - `source: string` Source of the skill. This may be one of the following values: * `"custom"`: the skill was created by a user * `"anthropic"`: the skill was created by Anthropic - `type: string` Object type. For Skills, this is always `"skill"`. - `updated_at: string` ISO 8601 timestamp of when the skill was last updated. ### Skill List Response - `SkillListResponse` - `id: string` Unique identifier for the skill. The format and length of IDs may change over time. - `created_at: string` ISO 8601 timestamp of when the skill was created. - `display_title: string | null` Display title for the skill. This is a human-readable label that is not included in the prompt sent to the model. - `latest_version: string | null` The latest version identifier for the skill. This represents the most recent version of the skill that has been created. - `source: string` Source of the skill. This may be one of the following values: * `"custom"`: the skill was created by a user * `"anthropic"`: the skill was created by Anthropic - `type: string` Object type. For Skills, this is always `"skill"`. - `updated_at: string` ISO 8601 timestamp of when the skill was last updated. ### Skill Retrieve Response - `SkillRetrieveResponse` - `id: string` Unique identifier for the skill. The format and length of IDs may change over time. - `created_at: string` ISO 8601 timestamp of when the skill was created. - `display_title: string | null` Display title for the skill. This is a human-readable label that is not included in the prompt sent to the model. - `latest_version: string | null` The latest version identifier for the skill. This represents the most recent version of the skill that has been created. - `source: string` Source of the skill. This may be one of the following values: * `"custom"`: the skill was created by a user * `"anthropic"`: the skill was created by Anthropic - `type: string` Object type. For Skills, this is always `"skill"`. - `updated_at: string` ISO 8601 timestamp of when the skill was last updated. ### Skill Delete Response - `SkillDeleteResponse` - `id: string` Unique identifier for the skill. The format and length of IDs may change over time. - `type: string` Deleted object type. For Skills, this is always `"skill_deleted"`. # Versions ## Create Skill Version `client.beta.skills.versions.create(stringskillID, VersionCreateParamsparams?, RequestOptionsoptions?): VersionCreateResponse` **post** `/v1/skills/{skill_id}/versions` Create Skill Version ### Parameters - `skillID: string` Unique identifier for the skill. The format and length of IDs may change over time. - `params: VersionCreateParams` - `files?: Array | null` Body param: Files to upload for the skill. All files must be in the same top-level directory and must include a SKILL.md file at the root of that directory. - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `VersionCreateResponse` - `id: string` Unique identifier for the skill version. The format and length of IDs may change over time. - `created_at: string` ISO 8601 timestamp of when the skill version was created. - `description: string` Description of the skill version. This is extracted from the SKILL.md file in the skill upload. - `directory: string` Directory name of the skill version. This is the top-level directory name that was extracted from the uploaded files. - `name: string` Human-readable name of the skill version. This is extracted from the SKILL.md file in the skill upload. - `skill_id: string` Identifier for the skill that this version belongs to. - `type: string` Object type. For Skill Versions, this is always `"skill_version"`. - `version: string` Version identifier for the skill. Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129"). ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const version = await client.beta.skills.versions.create('skill_id'); console.log(version.id); ``` #### Response ```json { "id": "skillver_01JAbcdefghijklmnopqrstuvw", "created_at": "2024-10-30T23:58:27.427722Z", "description": "A custom skill for doing something useful", "directory": "my-skill", "name": "my-skill", "skill_id": "skill_01JAbcdefghijklmnopqrstuvw", "type": "type", "version": "1759178010641129" } ``` ## List Skill Versions `client.beta.skills.versions.list(stringskillID, VersionListParamsparams?, RequestOptionsoptions?): PageCursor` **get** `/v1/skills/{skill_id}/versions` List Skill Versions ### Parameters - `skillID: string` Unique identifier for the skill. The format and length of IDs may change over time. - `params: VersionListParams` - `limit?: number | null` Query param: Number of items to return per page. Defaults to `20`. Ranges from `1` to `1000`. - `page?: string | null` Query param: Optionally set to the `next_page` token from the previous response. - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `VersionListResponse` - `id: string` Unique identifier for the skill version. The format and length of IDs may change over time. - `created_at: string` ISO 8601 timestamp of when the skill version was created. - `description: string` Description of the skill version. This is extracted from the SKILL.md file in the skill upload. - `directory: string` Directory name of the skill version. This is the top-level directory name that was extracted from the uploaded files. - `name: string` Human-readable name of the skill version. This is extracted from the SKILL.md file in the skill upload. - `skill_id: string` Identifier for the skill that this version belongs to. - `type: string` Object type. For Skill Versions, this is always `"skill_version"`. - `version: string` Version identifier for the skill. Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129"). ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); // Automatically fetches more pages as needed. for await (const versionListResponse of client.beta.skills.versions.list('skill_id')) { console.log(versionListResponse.id); } ``` #### Response ```json { "data": [ { "id": "skillver_01JAbcdefghijklmnopqrstuvw", "created_at": "2024-10-30T23:58:27.427722Z", "description": "A custom skill for doing something useful", "directory": "my-skill", "name": "my-skill", "skill_id": "skill_01JAbcdefghijklmnopqrstuvw", "type": "type", "version": "1759178010641129" } ], "has_more": true, "next_page": "page_MjAyNS0wNS0xNFQwMDowMDowMFo=" } ``` ## Download Skill Version Content `client.beta.skills.versions.download(stringversion, VersionDownloadParamsparams, RequestOptionsoptions?): Response` **get** `/v1/skills/{skill_id}/versions/{version}/content` Download a skill version's content as a zip archive. ### Parameters - `version: string` Version identifier for the skill. Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129"). - `params: VersionDownloadParams` - `skill_id: string` Path param: Unique identifier for the skill. The format and length of IDs may change over time. - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `unnamed_schema_3 = Response` ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const response = await client.beta.skills.versions.download('version', { skill_id: 'skill_id' }); console.log(response); const content = await response.blob(); console.log(content); ``` ## Get Skill Version `client.beta.skills.versions.retrieve(stringversion, VersionRetrieveParamsparams, RequestOptionsoptions?): VersionRetrieveResponse` **get** `/v1/skills/{skill_id}/versions/{version}` Get Skill Version ### Parameters - `version: string` Version identifier for the skill. Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129"). - `params: VersionRetrieveParams` - `skill_id: string` Path param: Unique identifier for the skill. The format and length of IDs may change over time. - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `VersionRetrieveResponse` - `id: string` Unique identifier for the skill version. The format and length of IDs may change over time. - `created_at: string` ISO 8601 timestamp of when the skill version was created. - `description: string` Description of the skill version. This is extracted from the SKILL.md file in the skill upload. - `directory: string` Directory name of the skill version. This is the top-level directory name that was extracted from the uploaded files. - `name: string` Human-readable name of the skill version. This is extracted from the SKILL.md file in the skill upload. - `skill_id: string` Identifier for the skill that this version belongs to. - `type: string` Object type. For Skill Versions, this is always `"skill_version"`. - `version: string` Version identifier for the skill. Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129"). ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const version = await client.beta.skills.versions.retrieve('version', { skill_id: 'skill_id' }); console.log(version.id); ``` #### Response ```json { "id": "skillver_01JAbcdefghijklmnopqrstuvw", "created_at": "2024-10-30T23:58:27.427722Z", "description": "A custom skill for doing something useful", "directory": "my-skill", "name": "my-skill", "skill_id": "skill_01JAbcdefghijklmnopqrstuvw", "type": "type", "version": "1759178010641129" } ``` ## Delete Skill Version `client.beta.skills.versions.delete(stringversion, VersionDeleteParamsparams, RequestOptionsoptions?): VersionDeleteResponse` **delete** `/v1/skills/{skill_id}/versions/{version}` Delete Skill Version ### Parameters - `version: string` Version identifier for the skill. Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129"). - `params: VersionDeleteParams` - `skill_id: string` Path param: Unique identifier for the skill. The format and length of IDs may change over time. - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `VersionDeleteResponse` - `id: string` Version identifier for the skill. Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129"). - `type: string` Deleted object type. For Skill Versions, this is always `"skill_version_deleted"`. ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const version = await client.beta.skills.versions.delete('version', { skill_id: 'skill_id' }); console.log(version.id); ``` #### Response ```json { "id": "1759178010641129", "type": "type" } ``` ## Domain Types ### Version Create Response - `VersionCreateResponse` - `id: string` Unique identifier for the skill version. The format and length of IDs may change over time. - `created_at: string` ISO 8601 timestamp of when the skill version was created. - `description: string` Description of the skill version. This is extracted from the SKILL.md file in the skill upload. - `directory: string` Directory name of the skill version. This is the top-level directory name that was extracted from the uploaded files. - `name: string` Human-readable name of the skill version. This is extracted from the SKILL.md file in the skill upload. - `skill_id: string` Identifier for the skill that this version belongs to. - `type: string` Object type. For Skill Versions, this is always `"skill_version"`. - `version: string` Version identifier for the skill. Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129"). ### Version List Response - `VersionListResponse` - `id: string` Unique identifier for the skill version. The format and length of IDs may change over time. - `created_at: string` ISO 8601 timestamp of when the skill version was created. - `description: string` Description of the skill version. This is extracted from the SKILL.md file in the skill upload. - `directory: string` Directory name of the skill version. This is the top-level directory name that was extracted from the uploaded files. - `name: string` Human-readable name of the skill version. This is extracted from the SKILL.md file in the skill upload. - `skill_id: string` Identifier for the skill that this version belongs to. - `type: string` Object type. For Skill Versions, this is always `"skill_version"`. - `version: string` Version identifier for the skill. Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129"). ### Version Retrieve Response - `VersionRetrieveResponse` - `id: string` Unique identifier for the skill version. The format and length of IDs may change over time. - `created_at: string` ISO 8601 timestamp of when the skill version was created. - `description: string` Description of the skill version. This is extracted from the SKILL.md file in the skill upload. - `directory: string` Directory name of the skill version. This is the top-level directory name that was extracted from the uploaded files. - `name: string` Human-readable name of the skill version. This is extracted from the SKILL.md file in the skill upload. - `skill_id: string` Identifier for the skill that this version belongs to. - `type: string` Object type. For Skill Versions, this is always `"skill_version"`. - `version: string` Version identifier for the skill. Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129"). ### Version Delete Response - `VersionDeleteResponse` - `id: string` Version identifier for the skill. Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129"). - `type: string` Deleted object type. For Skill Versions, this is always `"skill_version_deleted"`. # User Profiles ## Create User Profile `client.beta.userProfiles.create(UserProfileCreateParamsparams, RequestOptionsoptions?): BetaUserProfile` **post** `/v1/user_profiles` Create User Profile ### Parameters - `params: UserProfileCreateParams` - `external_id?: string | null` Body param: Platform's own identifier for this user. Not enforced unique. Maximum 255 characters. - `metadata?: Record` Body param: Free-form key-value data to attach to this user profile. Maximum 16 keys, with keys up to 64 characters and values up to 512 characters. Values must be non-empty strings. - `name?: string | null` Body param: Display name of the entity this profile represents. Required when relationship is `resold` (the resold-to company's name); optional otherwise. Maximum 255 characters. - `relationship?: "external" | "resold" | "internal"` Body param: How the entity behind a user profile relates to the platform that owns the API key. `external`: an individual end-user of the platform. `resold`: a company the platform resells Claude access to. `internal`: the platform's own usage. - `"external"` - `"resold"` - `"internal"` - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaUserProfile` - `id: string` Unique identifier for this user profile, prefixed `uprof_`. - `created_at: string` A timestamp in RFC 3339 format - `metadata: Record` Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars. - `relationship: "external" | "resold" | "internal"` How the entity behind a user profile relates to the platform that owns the API key. `external`: an individual end-user of the platform. `resold`: a company the platform resells Claude access to. `internal`: the platform's own usage. - `"external"` - `"resold"` - `"internal"` - `trust_grants: Record` Trust grants for this profile, keyed by grant name. Key omitted when no grant is active or in flight. - `status: "active" | "pending" | "rejected"` Status of the trust grant. - `"active"` - `"pending"` - `"rejected"` - `type: "user_profile"` Object type. Always `user_profile`. - `"user_profile"` - `updated_at: string` A timestamp in RFC 3339 format - `external_id?: string | null` Platform's own identifier for this user. Not enforced unique. - `name?: string | null` Display name of the entity this profile represents. For `resold` this is the resold-to company's name. ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const betaUserProfile = await client.beta.userProfiles.create(); console.log(betaUserProfile.id); ``` #### Response ```json { "id": "uprof_011CZkZCu8hGbp5mYRQgUmz9", "created_at": "2026-03-15T10:00:00Z", "metadata": {}, "relationship": "external", "trust_grants": { "cyber": { "status": "active" } }, "type": "user_profile", "updated_at": "2026-03-15T10:00:00Z", "external_id": "user_12345", "name": "Example User" } ``` ## List User Profiles `client.beta.userProfiles.list(UserProfileListParamsparams?, RequestOptionsoptions?): PageCursor` **get** `/v1/user_profiles` List User Profiles ### Parameters - `params: UserProfileListParams` - `limit?: number` Query param: Query parameter for limit - `order?: "asc" | "desc"` Query param: Query parameter for order - `"asc"` - `"desc"` - `page?: string` Query param: Query parameter for page - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaUserProfile` - `id: string` Unique identifier for this user profile, prefixed `uprof_`. - `created_at: string` A timestamp in RFC 3339 format - `metadata: Record` Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars. - `relationship: "external" | "resold" | "internal"` How the entity behind a user profile relates to the platform that owns the API key. `external`: an individual end-user of the platform. `resold`: a company the platform resells Claude access to. `internal`: the platform's own usage. - `"external"` - `"resold"` - `"internal"` - `trust_grants: Record` Trust grants for this profile, keyed by grant name. Key omitted when no grant is active or in flight. - `status: "active" | "pending" | "rejected"` Status of the trust grant. - `"active"` - `"pending"` - `"rejected"` - `type: "user_profile"` Object type. Always `user_profile`. - `"user_profile"` - `updated_at: string` A timestamp in RFC 3339 format - `external_id?: string | null` Platform's own identifier for this user. Not enforced unique. - `name?: string | null` Display name of the entity this profile represents. For `resold` this is the resold-to company's name. ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); // Automatically fetches more pages as needed. for await (const betaUserProfile of client.beta.userProfiles.list()) { console.log(betaUserProfile.id); } ``` #### Response ```json { "data": [ { "id": "uprof_011CZkZCu8hGbp5mYRQgUmz9", "created_at": "2026-03-15T10:00:00Z", "metadata": {}, "relationship": "external", "trust_grants": { "cyber": { "status": "active" } }, "type": "user_profile", "updated_at": "2026-03-15T10:00:00Z", "external_id": "user_12345", "name": "Example User" } ], "next_page": "page_MjAyNS0wNS0xNFQwMDowMDowMFo=" } ``` ## Get User Profile `client.beta.userProfiles.retrieve(stringuserProfileID, UserProfileRetrieveParamsparams?, RequestOptionsoptions?): BetaUserProfile` **get** `/v1/user_profiles/{user_profile_id}` Get User Profile ### Parameters - `userProfileID: string` - `params: UserProfileRetrieveParams` - `betas?: Array` Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaUserProfile` - `id: string` Unique identifier for this user profile, prefixed `uprof_`. - `created_at: string` A timestamp in RFC 3339 format - `metadata: Record` Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars. - `relationship: "external" | "resold" | "internal"` How the entity behind a user profile relates to the platform that owns the API key. `external`: an individual end-user of the platform. `resold`: a company the platform resells Claude access to. `internal`: the platform's own usage. - `"external"` - `"resold"` - `"internal"` - `trust_grants: Record` Trust grants for this profile, keyed by grant name. Key omitted when no grant is active or in flight. - `status: "active" | "pending" | "rejected"` Status of the trust grant. - `"active"` - `"pending"` - `"rejected"` - `type: "user_profile"` Object type. Always `user_profile`. - `"user_profile"` - `updated_at: string` A timestamp in RFC 3339 format - `external_id?: string | null` Platform's own identifier for this user. Not enforced unique. - `name?: string | null` Display name of the entity this profile represents. For `resold` this is the resold-to company's name. ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const betaUserProfile = await client.beta.userProfiles.retrieve('uprof_011CZkZCu8hGbp5mYRQgUmz9'); console.log(betaUserProfile.id); ``` #### Response ```json { "id": "uprof_011CZkZCu8hGbp5mYRQgUmz9", "created_at": "2026-03-15T10:00:00Z", "metadata": {}, "relationship": "external", "trust_grants": { "cyber": { "status": "active" } }, "type": "user_profile", "updated_at": "2026-03-15T10:00:00Z", "external_id": "user_12345", "name": "Example User" } ``` ## Update User Profile `client.beta.userProfiles.update(stringuserProfileID, UserProfileUpdateParamsparams, RequestOptionsoptions?): BetaUserProfile` **post** `/v1/user_profiles/{user_profile_id}` Update User Profile ### Parameters - `userProfileID: string` - `params: UserProfileUpdateParams` - `external_id?: string | null` Body param: If present, replaces the stored external_id. Omit to leave unchanged. Maximum 255 characters. - `metadata?: Record` Body param: Key-value pairs to merge into the stored metadata. Keys provided overwrite existing values. To remove a key, set its value to an empty string. Keys not provided are left unchanged. Maximum 16 keys, with keys up to 64 characters and values up to 512 characters. - `name?: string | null` Body param: If present, replaces the stored name. Omit to leave unchanged. Maximum 255 characters. - `relationship?: "external" | "resold" | "internal" | null` Body param: How the entity behind a user profile relates to the platform that owns the API key. `external`: an individual end-user of the platform. `resold`: a company the platform resells Claude access to. `internal`: the platform's own usage. - `"external"` - `"resold"` - `"internal"` - `betas?: Array` Header param: Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaUserProfile` - `id: string` Unique identifier for this user profile, prefixed `uprof_`. - `created_at: string` A timestamp in RFC 3339 format - `metadata: Record` Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars. - `relationship: "external" | "resold" | "internal"` How the entity behind a user profile relates to the platform that owns the API key. `external`: an individual end-user of the platform. `resold`: a company the platform resells Claude access to. `internal`: the platform's own usage. - `"external"` - `"resold"` - `"internal"` - `trust_grants: Record` Trust grants for this profile, keyed by grant name. Key omitted when no grant is active or in flight. - `status: "active" | "pending" | "rejected"` Status of the trust grant. - `"active"` - `"pending"` - `"rejected"` - `type: "user_profile"` Object type. Always `user_profile`. - `"user_profile"` - `updated_at: string` A timestamp in RFC 3339 format - `external_id?: string | null` Platform's own identifier for this user. Not enforced unique. - `name?: string | null` Display name of the entity this profile represents. For `resold` this is the resold-to company's name. ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const betaUserProfile = await client.beta.userProfiles.update('uprof_011CZkZCu8hGbp5mYRQgUmz9'); console.log(betaUserProfile.id); ``` #### Response ```json { "id": "uprof_011CZkZCu8hGbp5mYRQgUmz9", "created_at": "2026-03-15T10:00:00Z", "metadata": {}, "relationship": "external", "trust_grants": { "cyber": { "status": "active" } }, "type": "user_profile", "updated_at": "2026-03-15T10:00:00Z", "external_id": "user_12345", "name": "Example User" } ``` ## Create Enrollment URL `client.beta.userProfiles.createEnrollmentURL(stringuserProfileID, UserProfileCreateEnrollmentURLParamsparams?, RequestOptionsoptions?): BetaUserProfileEnrollmentURL` **post** `/v1/user_profiles/{user_profile_id}/enrollment_url` Create Enrollment URL ### Parameters - `userProfileID: string` - `params: UserProfileCreateEnrollmentURLParams` - `betas?: Array` Optional header to specify the beta version(s) you want to use. - `(string & {})` - `"message-batches-2024-09-24" | "prompt-caching-2024-07-31" | "computer-use-2024-10-22" | 23 more` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"thinking-token-count-2026-05-13"` ### Returns - `BetaUserProfileEnrollmentURL` - `expires_at: string` A timestamp in RFC 3339 format - `type: "enrollment_url"` Object type. Always `enrollment_url`. - `"enrollment_url"` - `url: string` Enrollment URL to send to the end user. Valid until `expires_at`. ### Example ```typescript import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env['ANTHROPIC_API_KEY'], // This is the default and can be omitted }); const betaUserProfileEnrollmentURL = await client.beta.userProfiles.createEnrollmentURL( 'uprof_011CZkZCu8hGbp5mYRQgUmz9', ); console.log(betaUserProfileEnrollmentURL.expires_at); ``` #### Response ```json { "expires_at": "2026-03-15T10:15:00Z", "type": "enrollment_url", "url": "https://platform.claude.com/user-profiles/enrollment/M3J0bGJxZ2ppMnptbnB1" } ``` ## Domain Types ### Beta User Profile - `BetaUserProfile` - `id: string` Unique identifier for this user profile, prefixed `uprof_`. - `created_at: string` A timestamp in RFC 3339 format - `metadata: Record` Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars. - `relationship: "external" | "resold" | "internal"` How the entity behind a user profile relates to the platform that owns the API key. `external`: an individual end-user of the platform. `resold`: a company the platform resells Claude access to. `internal`: the platform's own usage. - `"external"` - `"resold"` - `"internal"` - `trust_grants: Record` Trust grants for this profile, keyed by grant name. Key omitted when no grant is active or in flight. - `status: "active" | "pending" | "rejected"` Status of the trust grant. - `"active"` - `"pending"` - `"rejected"` - `type: "user_profile"` Object type. Always `user_profile`. - `"user_profile"` - `updated_at: string` A timestamp in RFC 3339 format - `external_id?: string | null` Platform's own identifier for this user. Not enforced unique. - `name?: string | null` Display name of the entity this profile represents. For `resold` this is the resold-to company's name. ### Beta User Profile Enrollment URL - `BetaUserProfileEnrollmentURL` - `expires_at: string` A timestamp in RFC 3339 format - `type: "enrollment_url"` Object type. Always `enrollment_url`. - `"enrollment_url"` - `url: string` Enrollment URL to send to the end user. Valid until `expires_at`. ### Beta User Profile Trust Grant - `BetaUserProfileTrustGrant` - `status: "active" | "pending" | "rejected"` Status of the trust grant. - `"active"` - `"pending"` - `"rejected"` # Webhooks ## Domain Types ### Beta Webhook Event - `BetaWebhookEvent` - `id: string` Unique event identifier for idempotency. - `created_at: string` RFC 3339 timestamp when the event occurred. - `data: BetaWebhookEventData` - `BetaWebhookSessionCreatedEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "session.created"` - `"session.created"` - `workspace_id: string` - `BetaWebhookSessionPendingEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "session.pending"` - `"session.pending"` - `workspace_id: string` - `BetaWebhookSessionRunningEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "session.running"` - `"session.running"` - `workspace_id: string` - `BetaWebhookSessionIdledEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "session.idled"` - `"session.idled"` - `workspace_id: string` - `BetaWebhookSessionRequiresActionEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "session.requires_action"` - `"session.requires_action"` - `workspace_id: string` - `BetaWebhookSessionArchivedEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "session.archived"` - `"session.archived"` - `workspace_id: string` - `BetaWebhookSessionDeletedEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "session.deleted"` - `"session.deleted"` - `workspace_id: string` - `BetaWebhookSessionStatusRescheduledEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "session.status_rescheduled"` - `"session.status_rescheduled"` - `workspace_id: string` - `BetaWebhookSessionStatusRunStartedEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "session.status_run_started"` - `"session.status_run_started"` - `workspace_id: string` - `BetaWebhookSessionStatusIdledEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "session.status_idled"` - `"session.status_idled"` - `workspace_id: string` - `BetaWebhookSessionStatusTerminatedEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "session.status_terminated"` - `"session.status_terminated"` - `workspace_id: string` - `BetaWebhookSessionThreadCreatedEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "session.thread_created"` - `"session.thread_created"` - `workspace_id: string` - `BetaWebhookSessionThreadIdledEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "session.thread_idled"` - `"session.thread_idled"` - `workspace_id: string` - `BetaWebhookSessionThreadTerminatedEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "session.thread_terminated"` - `"session.thread_terminated"` - `workspace_id: string` - `BetaWebhookSessionOutcomeEvaluationEndedEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "session.outcome_evaluation_ended"` - `"session.outcome_evaluation_ended"` - `workspace_id: string` - `BetaWebhookVaultCreatedEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "vault.created"` - `"vault.created"` - `workspace_id: string` - `BetaWebhookVaultArchivedEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "vault.archived"` - `"vault.archived"` - `workspace_id: string` - `BetaWebhookVaultDeletedEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "vault.deleted"` - `"vault.deleted"` - `workspace_id: string` - `BetaWebhookVaultCredentialCreatedEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "vault_credential.created"` - `"vault_credential.created"` - `vault_id: string` ID of the vault that owns this credential. - `workspace_id: string` - `BetaWebhookVaultCredentialArchivedEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "vault_credential.archived"` - `"vault_credential.archived"` - `vault_id: string` ID of the vault that owns this credential. - `workspace_id: string` - `BetaWebhookVaultCredentialDeletedEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "vault_credential.deleted"` - `"vault_credential.deleted"` - `vault_id: string` ID of the vault that owns this credential. - `workspace_id: string` - `BetaWebhookVaultCredentialRefreshFailedEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "vault_credential.refresh_failed"` - `"vault_credential.refresh_failed"` - `vault_id: string` ID of the vault that owns this credential. - `workspace_id: string` - `type: "event"` Object type. Always `event` for webhook payloads. - `"event"` ### Beta Webhook Event Data - `BetaWebhookEventData = BetaWebhookSessionCreatedEventData | BetaWebhookSessionPendingEventData | BetaWebhookSessionRunningEventData | 19 more` - `BetaWebhookSessionCreatedEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "session.created"` - `"session.created"` - `workspace_id: string` - `BetaWebhookSessionPendingEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "session.pending"` - `"session.pending"` - `workspace_id: string` - `BetaWebhookSessionRunningEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "session.running"` - `"session.running"` - `workspace_id: string` - `BetaWebhookSessionIdledEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "session.idled"` - `"session.idled"` - `workspace_id: string` - `BetaWebhookSessionRequiresActionEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "session.requires_action"` - `"session.requires_action"` - `workspace_id: string` - `BetaWebhookSessionArchivedEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "session.archived"` - `"session.archived"` - `workspace_id: string` - `BetaWebhookSessionDeletedEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "session.deleted"` - `"session.deleted"` - `workspace_id: string` - `BetaWebhookSessionStatusRescheduledEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "session.status_rescheduled"` - `"session.status_rescheduled"` - `workspace_id: string` - `BetaWebhookSessionStatusRunStartedEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "session.status_run_started"` - `"session.status_run_started"` - `workspace_id: string` - `BetaWebhookSessionStatusIdledEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "session.status_idled"` - `"session.status_idled"` - `workspace_id: string` - `BetaWebhookSessionStatusTerminatedEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "session.status_terminated"` - `"session.status_terminated"` - `workspace_id: string` - `BetaWebhookSessionThreadCreatedEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "session.thread_created"` - `"session.thread_created"` - `workspace_id: string` - `BetaWebhookSessionThreadIdledEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "session.thread_idled"` - `"session.thread_idled"` - `workspace_id: string` - `BetaWebhookSessionThreadTerminatedEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "session.thread_terminated"` - `"session.thread_terminated"` - `workspace_id: string` - `BetaWebhookSessionOutcomeEvaluationEndedEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "session.outcome_evaluation_ended"` - `"session.outcome_evaluation_ended"` - `workspace_id: string` - `BetaWebhookVaultCreatedEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "vault.created"` - `"vault.created"` - `workspace_id: string` - `BetaWebhookVaultArchivedEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "vault.archived"` - `"vault.archived"` - `workspace_id: string` - `BetaWebhookVaultDeletedEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "vault.deleted"` - `"vault.deleted"` - `workspace_id: string` - `BetaWebhookVaultCredentialCreatedEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "vault_credential.created"` - `"vault_credential.created"` - `vault_id: string` ID of the vault that owns this credential. - `workspace_id: string` - `BetaWebhookVaultCredentialArchivedEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "vault_credential.archived"` - `"vault_credential.archived"` - `vault_id: string` ID of the vault that owns this credential. - `workspace_id: string` - `BetaWebhookVaultCredentialDeletedEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "vault_credential.deleted"` - `"vault_credential.deleted"` - `vault_id: string` ID of the vault that owns this credential. - `workspace_id: string` - `BetaWebhookVaultCredentialRefreshFailedEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "vault_credential.refresh_failed"` - `"vault_credential.refresh_failed"` - `vault_id: string` ID of the vault that owns this credential. - `workspace_id: string` ### Beta Webhook Session Archived Event Data - `BetaWebhookSessionArchivedEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "session.archived"` - `"session.archived"` - `workspace_id: string` ### Beta Webhook Session Created Event Data - `BetaWebhookSessionCreatedEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "session.created"` - `"session.created"` - `workspace_id: string` ### Beta Webhook Session Deleted Event Data - `BetaWebhookSessionDeletedEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "session.deleted"` - `"session.deleted"` - `workspace_id: string` ### Beta Webhook Session Idled Event Data - `BetaWebhookSessionIdledEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "session.idled"` - `"session.idled"` - `workspace_id: string` ### Beta Webhook Session Outcome Evaluation Ended Event Data - `BetaWebhookSessionOutcomeEvaluationEndedEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "session.outcome_evaluation_ended"` - `"session.outcome_evaluation_ended"` - `workspace_id: string` ### Beta Webhook Session Pending Event Data - `BetaWebhookSessionPendingEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "session.pending"` - `"session.pending"` - `workspace_id: string` ### Beta Webhook Session Requires Action Event Data - `BetaWebhookSessionRequiresActionEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "session.requires_action"` - `"session.requires_action"` - `workspace_id: string` ### Beta Webhook Session Running Event Data - `BetaWebhookSessionRunningEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "session.running"` - `"session.running"` - `workspace_id: string` ### Beta Webhook Session Status Idled Event Data - `BetaWebhookSessionStatusIdledEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "session.status_idled"` - `"session.status_idled"` - `workspace_id: string` ### Beta Webhook Session Status Rescheduled Event Data - `BetaWebhookSessionStatusRescheduledEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "session.status_rescheduled"` - `"session.status_rescheduled"` - `workspace_id: string` ### Beta Webhook Session Status Run Started Event Data - `BetaWebhookSessionStatusRunStartedEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "session.status_run_started"` - `"session.status_run_started"` - `workspace_id: string` ### Beta Webhook Session Status Terminated Event Data - `BetaWebhookSessionStatusTerminatedEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "session.status_terminated"` - `"session.status_terminated"` - `workspace_id: string` ### Beta Webhook Session Thread Created Event Data - `BetaWebhookSessionThreadCreatedEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "session.thread_created"` - `"session.thread_created"` - `workspace_id: string` ### Beta Webhook Session Thread Idled Event Data - `BetaWebhookSessionThreadIdledEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "session.thread_idled"` - `"session.thread_idled"` - `workspace_id: string` ### Beta Webhook Session Thread Terminated Event Data - `BetaWebhookSessionThreadTerminatedEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "session.thread_terminated"` - `"session.thread_terminated"` - `workspace_id: string` ### Beta Webhook Vault Archived Event Data - `BetaWebhookVaultArchivedEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "vault.archived"` - `"vault.archived"` - `workspace_id: string` ### Beta Webhook Vault Created Event Data - `BetaWebhookVaultCreatedEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "vault.created"` - `"vault.created"` - `workspace_id: string` ### Beta Webhook Vault Credential Archived Event Data - `BetaWebhookVaultCredentialArchivedEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "vault_credential.archived"` - `"vault_credential.archived"` - `vault_id: string` ID of the vault that owns this credential. - `workspace_id: string` ### Beta Webhook Vault Credential Created Event Data - `BetaWebhookVaultCredentialCreatedEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "vault_credential.created"` - `"vault_credential.created"` - `vault_id: string` ID of the vault that owns this credential. - `workspace_id: string` ### Beta Webhook Vault Credential Deleted Event Data - `BetaWebhookVaultCredentialDeletedEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "vault_credential.deleted"` - `"vault_credential.deleted"` - `vault_id: string` ID of the vault that owns this credential. - `workspace_id: string` ### Beta Webhook Vault Credential Refresh Failed Event Data - `BetaWebhookVaultCredentialRefreshFailedEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "vault_credential.refresh_failed"` - `"vault_credential.refresh_failed"` - `vault_id: string` ID of the vault that owns this credential. - `workspace_id: string` ### Beta Webhook Vault Deleted Event Data - `BetaWebhookVaultDeletedEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "vault.deleted"` - `"vault.deleted"` - `workspace_id: string` ### Unwrap Webhook Event - `UnwrapWebhookEvent` - `id: string` Unique event identifier for idempotency. - `created_at: string` RFC 3339 timestamp when the event occurred. - `data: BetaWebhookEventData` - `BetaWebhookSessionCreatedEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "session.created"` - `"session.created"` - `workspace_id: string` - `BetaWebhookSessionPendingEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "session.pending"` - `"session.pending"` - `workspace_id: string` - `BetaWebhookSessionRunningEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "session.running"` - `"session.running"` - `workspace_id: string` - `BetaWebhookSessionIdledEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "session.idled"` - `"session.idled"` - `workspace_id: string` - `BetaWebhookSessionRequiresActionEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "session.requires_action"` - `"session.requires_action"` - `workspace_id: string` - `BetaWebhookSessionArchivedEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "session.archived"` - `"session.archived"` - `workspace_id: string` - `BetaWebhookSessionDeletedEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "session.deleted"` - `"session.deleted"` - `workspace_id: string` - `BetaWebhookSessionStatusRescheduledEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "session.status_rescheduled"` - `"session.status_rescheduled"` - `workspace_id: string` - `BetaWebhookSessionStatusRunStartedEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "session.status_run_started"` - `"session.status_run_started"` - `workspace_id: string` - `BetaWebhookSessionStatusIdledEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "session.status_idled"` - `"session.status_idled"` - `workspace_id: string` - `BetaWebhookSessionStatusTerminatedEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "session.status_terminated"` - `"session.status_terminated"` - `workspace_id: string` - `BetaWebhookSessionThreadCreatedEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "session.thread_created"` - `"session.thread_created"` - `workspace_id: string` - `BetaWebhookSessionThreadIdledEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "session.thread_idled"` - `"session.thread_idled"` - `workspace_id: string` - `BetaWebhookSessionThreadTerminatedEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "session.thread_terminated"` - `"session.thread_terminated"` - `workspace_id: string` - `BetaWebhookSessionOutcomeEvaluationEndedEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "session.outcome_evaluation_ended"` - `"session.outcome_evaluation_ended"` - `workspace_id: string` - `BetaWebhookVaultCreatedEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "vault.created"` - `"vault.created"` - `workspace_id: string` - `BetaWebhookVaultArchivedEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "vault.archived"` - `"vault.archived"` - `workspace_id: string` - `BetaWebhookVaultDeletedEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "vault.deleted"` - `"vault.deleted"` - `workspace_id: string` - `BetaWebhookVaultCredentialCreatedEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "vault_credential.created"` - `"vault_credential.created"` - `vault_id: string` ID of the vault that owns this credential. - `workspace_id: string` - `BetaWebhookVaultCredentialArchivedEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "vault_credential.archived"` - `"vault_credential.archived"` - `vault_id: string` ID of the vault that owns this credential. - `workspace_id: string` - `BetaWebhookVaultCredentialDeletedEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "vault_credential.deleted"` - `"vault_credential.deleted"` - `vault_id: string` ID of the vault that owns this credential. - `workspace_id: string` - `BetaWebhookVaultCredentialRefreshFailedEventData` - `id: string` ID of the resource that triggered the event. - `organization_id: string` - `type: "vault_credential.refresh_failed"` - `"vault_credential.refresh_failed"` - `vault_id: string` ID of the vault that owns this credential. - `workspace_id: string` - `type: "event"` Object type. Always `event` for webhook payloads. - `"event"`