中文 ← MyDocs

Beta

Domain Types

Anthropic Beta

  • AnthropicBeta = string or "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 more

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Beta API Error

  • BetaAPIError object { message, type }

    • message: string

    • type: "api_error"

      • "api_error"

Beta Authentication Error

  • BetaAuthenticationError object { message, type }

    • message: string

    • type: "authentication_error"

      • "authentication_error"

Beta Billing Error

  • BetaBillingError object { message, type }

    • message: string

    • type: "billing_error"

      • "billing_error"

Beta Error

  • BetaError = BetaInvalidRequestError or BetaAuthenticationError or BetaBillingError or 6 more

    • BetaInvalidRequestError object { message, type }

      • message: string

      • type: "invalid_request_error"

        • "invalid_request_error"

    • BetaAuthenticationError object { message, type }

      • message: string

      • type: "authentication_error"

        • "authentication_error"

    • BetaBillingError object { message, type }

      • message: string

      • type: "billing_error"

        • "billing_error"

    • BetaPermissionError object { message, type }

      • message: string

      • type: "permission_error"

        • "permission_error"

    • BetaNotFoundError object { message, type }

      • message: string

      • type: "not_found_error"

        • "not_found_error"

    • BetaRateLimitError object { message, type }

      • message: string

      • type: "rate_limit_error"

        • "rate_limit_error"

    • BetaGatewayTimeoutError object { message, type }

      • message: string

      • type: "timeout_error"

        • "timeout_error"

    • BetaAPIError object { message, type }

      • message: string

      • type: "api_error"

        • "api_error"

    • BetaOverloadedError object { message, type }

      • message: string

      • type: "overloaded_error"

        • "overloaded_error"

Beta Error Response

  • BetaErrorResponse object { error, request_id, type }

    • error: BetaError

      • BetaInvalidRequestError object { message, type }

        • message: string

        • type: "invalid_request_error"

          • "invalid_request_error"

      • BetaAuthenticationError object { message, type }

        • message: string

        • type: "authentication_error"

          • "authentication_error"

      • BetaBillingError object { message, type }

        • message: string

        • type: "billing_error"

          • "billing_error"

      • BetaPermissionError object { message, type }

        • message: string

        • type: "permission_error"

          • "permission_error"

      • BetaNotFoundError object { message, type }

        • message: string

        • type: "not_found_error"

          • "not_found_error"

      • BetaRateLimitError object { message, type }

        • message: string

        • type: "rate_limit_error"

          • "rate_limit_error"

      • BetaGatewayTimeoutError object { message, type }

        • message: string

        • type: "timeout_error"

          • "timeout_error"

      • BetaAPIError object { message, type }

        • message: string

        • type: "api_error"

          • "api_error"

      • BetaOverloadedError object { message, type }

        • message: string

        • type: "overloaded_error"

          • "overloaded_error"

    • request_id: string

    • type: "error"

      • "error"

Beta Gateway Timeout Error

  • BetaGatewayTimeoutError object { message, type }

    • message: string

    • type: "timeout_error"

      • "timeout_error"

Beta Invalid Request Error

  • BetaInvalidRequestError object { message, type }

    • message: string

    • type: "invalid_request_error"

      • "invalid_request_error"

Beta Not Found Error

  • BetaNotFoundError object { message, type }

    • message: string

    • type: "not_found_error"

      • "not_found_error"

Beta Overloaded Error

  • BetaOverloadedError object { message, type }

    • message: string

    • type: "overloaded_error"

      • "overloaded_error"

Beta Permission Error

  • BetaPermissionError object { message, type }

    • message: string

    • type: "permission_error"

      • "permission_error"

Beta Rate Limit Error

  • BetaRateLimitError object { message, type }

    • message: string

    • type: "rate_limit_error"

      • "rate_limit_error"

Models

List Models

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.

Query Parameters

  • after_id: optional string

    ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object.

  • before_id: optional string

    ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object.

  • limit: optional number

    Number of items to return per page.

    Defaults to 20. Ranges from 1 to 1000.

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Returns

  • data: array of BetaModelInfo

    • id: string

      Unique model identifier.

    • 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

          Indicates whether a capability is supported.

        • clear_tool_uses_20250919: BetaCapabilitySupport

          Indicates whether a capability is supported.

        • compact_20260112: BetaCapabilitySupport

          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

          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

      Maximum input context window size in tokens for this model.

    • max_tokens: number

      Maximum value for the max_tokens parameter when using this model.

    • type: "model"

      Object type.

      For Models, this is always "model".

      • "model"

  • first_id: string

    First ID in the data list. Can be used as the before_id for the previous page.

  • has_more: boolean

    Indicates if there are more results in the requested page direction.

  • last_id: string

    Last ID in the data list. Can be used as the after_id for the next page.

Example

curl https://api.anthropic.com/v1/models \
    -H 'anthropic-version: 2023-06-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

Response

{
  "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

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.

Path Parameters

  • model_id: string

    Model identifier or alias.

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Returns

  • BetaModelInfo object { id, capabilities, created_at, 4 more }

    • id: string

      Unique model identifier.

    • 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

          Indicates whether a capability is supported.

        • clear_tool_uses_20250919: BetaCapabilitySupport

          Indicates whether a capability is supported.

        • compact_20260112: BetaCapabilitySupport

          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

          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

      Maximum input context window size in tokens for this model.

    • max_tokens: number

      Maximum value for the max_tokens parameter when using this model.

    • type: "model"

      Object type.

      For Models, this is always "model".

      • "model"

Example

curl https://api.anthropic.com/v1/models/$MODEL_ID \
    -H 'anthropic-version: 2023-06-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

Response

{
  "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 object { supported }

    Indicates whether a capability is supported.

    • supported: boolean

      Whether this capability is supported by the model.

Beta Context Management Capability

  • BetaContextManagementCapability object { clear_thinking_20251015, clear_tool_uses_20250919, compact_20260112, supported }

    Context management capability details.

    • clear_thinking_20251015: BetaCapabilitySupport

      Indicates whether a capability is supported.

      • supported: boolean

        Whether this capability is supported by the model.

    • clear_tool_uses_20250919: BetaCapabilitySupport

      Indicates whether a capability is supported.

    • compact_20260112: BetaCapabilitySupport

      Indicates whether a capability is supported.

    • supported: boolean

      Whether this capability is supported by the model.

Beta Effort Capability

  • BetaEffortCapability object { high, low, max, 3 more }

    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

      Indicates whether a capability is supported.

Beta Model Capabilities

  • BetaModelCapabilities object { batch, citations, code_execution, 6 more }

    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

        Indicates whether a capability is supported.

      • clear_tool_uses_20250919: BetaCapabilitySupport

        Indicates whether a capability is supported.

      • compact_20260112: BetaCapabilitySupport

        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

        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 object { id, capabilities, created_at, 4 more }

    • id: string

      Unique model identifier.

    • 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

          Indicates whether a capability is supported.

        • clear_tool_uses_20250919: BetaCapabilitySupport

          Indicates whether a capability is supported.

        • compact_20260112: BetaCapabilitySupport

          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

          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

      Maximum input context window size in tokens for this model.

    • max_tokens: number

      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 object { supported, types }

    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 object { adaptive, enabled }

    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

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

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Body 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 without generating a response.

    Different models have different maximum values for this parameter. See models for details.

  • messages: array of BetaMessageParam

    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:

    [{"role": "user", "content": "Hello, Claude"}]

    Example with multiple conversational turns:

    [
  {"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:

    [
  {"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:

    {"role": "user", "content": "Hello, Claude"}

    {"role": "user", "content": [{"type": "text", "text": "Hello, Claude"}]}

    See input examples.

    Note that if you want to include a system prompt, 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 or array of BetaContentBlockParam

      • string

      • array of BetaContentBlockParam

        • BetaTextBlockParam object { text, type, cache_control, citations }

          • text: string

          • type: "text"

            • "text"

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

            • type: "ephemeral"

              • "ephemeral"

            • ttl: optional "5m" or "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: optional array of BetaTextCitationParam

            • BetaCitationCharLocationParam object { cited_text, document_index, document_title, 3 more }

              • cited_text: string

              • document_index: number

              • document_title: string

              • end_char_index: number

              • start_char_index: number

              • type: "char_location"

                • "char_location"

            • BetaCitationPageLocationParam object { cited_text, document_index, document_title, 3 more }

              • cited_text: string

              • document_index: number

              • document_title: string

              • end_page_number: number

              • start_page_number: number

              • type: "page_location"

                • "page_location"

            • BetaCitationContentBlockLocationParam object { cited_text, document_index, document_title, 3 more }

              • 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

              • 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 object { cited_text, encrypted_index, title, 2 more }

              • cited_text: string

              • encrypted_index: string

              • title: string

              • type: "web_search_result_location"

                • "web_search_result_location"

              • url: string

            • BetaCitationSearchResultLocationParam object { cited_text, end_block_index, search_result_index, 4 more }

              • 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

              • type: "search_result_location"

                • "search_result_location"

        • BetaImageBlockParam object { source, type, cache_control }

          • source: BetaBase64ImageSource or BetaURLImageSource or BetaFileImageSource

            • BetaBase64ImageSource object { data, media_type, type }

              • data: string

              • media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"

                • "image/jpeg"

                • "image/png"

                • "image/gif"

                • "image/webp"

              • type: "base64"

                • "base64"

            • BetaURLImageSource object { type, url }

              • type: "url"

                • "url"

              • url: string

            • BetaFileImageSource object { file_id, type }

              • file_id: string

              • type: "file"

                • "file"

          • type: "image"

            • "image"

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

        • BetaRequestDocumentBlock object { source, type, cache_control, 3 more }

          • source: BetaBase64PDFSource or BetaPlainTextSource or BetaContentBlockSource or 2 more

            • BetaBase64PDFSource object { data, media_type, type }

              • data: string

              • media_type: "application/pdf"

                • "application/pdf"

              • type: "base64"

                • "base64"

            • BetaPlainTextSource object { data, media_type, type }

              • data: string

              • media_type: "text/plain"

                • "text/plain"

              • type: "text"

                • "text"

            • BetaContentBlockSource object { content, type }

              • content: string or array of BetaContentBlockSourceContent

                • string

                • BetaContentBlockSourceContent = array of BetaContentBlockSourceContent

                  • BetaTextBlockParam object { text, type, cache_control, citations }

                  • BetaImageBlockParam object { source, type, cache_control }

              • type: "content"

                • "content"

            • BetaURLPDFSource object { type, url }

              • type: "url"

                • "url"

              • url: string

            • BetaFileDocumentSource object { file_id, type }

              • file_id: string

              • type: "file"

                • "file"

          • type: "document"

            • "document"

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

          • citations: optional BetaCitationsConfigParam

            • enabled: optional boolean

          • context: optional string

          • title: optional string

        • BetaSearchResultBlockParam object { content, source, title, 3 more }

          • content: array of BetaTextBlockParam

            • text: string

            • type: "text"

            • cache_control: optional BetaCacheControlEphemeral

              Create a cache control breakpoint at this content block.

            • citations: optional array of BetaTextCitationParam

          • source: string

          • title: string

          • type: "search_result"

            • "search_result"

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

          • citations: optional BetaCitationsConfigParam

        • BetaThinkingBlockParam object { signature, thinking, type }

          • signature: string

          • thinking: string

          • type: "thinking"

            • "thinking"

        • BetaRedactedThinkingBlockParam object { data, type }

          • data: string

          • type: "redacted_thinking"

            • "redacted_thinking"

        • BetaToolUseBlockParam object { id, input, name, 3 more }

          • id: string

          • input: map[unknown]

          • name: string

          • type: "tool_use"

            • "tool_use"

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

          • caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

            Tool invocation directly from the model.

            • BetaDirectCaller object { type }

              Tool invocation directly from the model.

              • type: "direct"

                • "direct"

            • BetaServerToolCaller object { tool_id, type }

              Tool invocation generated by a server-side tool.

              • tool_id: string

              • type: "code_execution_20250825"

                • "code_execution_20250825"

            • BetaServerToolCaller20260120 object { tool_id, type }

              • tool_id: string

              • type: "code_execution_20260120"

                • "code_execution_20260120"

        • BetaToolResultBlockParam object { tool_use_id, type, cache_control, 2 more }

          • tool_use_id: string

          • type: "tool_result"

            • "tool_result"

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

          • content: optional string or array of BetaTextBlockParam or BetaImageBlockParam or BetaSearchResultBlockParam or 2 more

            • string

            • array of BetaTextBlockParam or BetaImageBlockParam or BetaSearchResultBlockParam or 2 more

              • BetaTextBlockParam object { text, type, cache_control, citations }

              • BetaImageBlockParam object { source, type, cache_control }

              • BetaSearchResultBlockParam object { content, source, title, 3 more }

              • BetaRequestDocumentBlock object { source, type, cache_control, 3 more }

              • BetaToolReferenceBlockParam object { tool_name, type, cache_control }

                Tool reference block that can be included in tool_result content.

                • tool_name: string

                • type: "tool_reference"

                  • "tool_reference"

                • cache_control: optional BetaCacheControlEphemeral

                  Create a cache control breakpoint at this content block.

          • is_error: optional boolean

        • BetaServerToolUseBlockParam object { id, input, name, 3 more }

          • id: string

          • input: map[unknown]

          • name: "advisor" or "web_search" or "web_fetch" or 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: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

          • caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

            Tool invocation directly from the model.

            • BetaDirectCaller object { type }

              Tool invocation directly from the model.

            • BetaServerToolCaller object { tool_id, type }

              Tool invocation generated by a server-side tool.

            • BetaServerToolCaller20260120 object { tool_id, type }

        • BetaWebSearchToolResultBlockParam object { content, tool_use_id, type, 2 more }

          • content: BetaWebSearchToolResultBlockParamContent

            • ResultBlock = array of BetaWebSearchResultBlockParam

              • encrypted_content: string

              • title: string

              • type: "web_search_result"

                • "web_search_result"

              • url: string

              • page_age: optional string

            • BetaWebSearchToolRequestError object { error_code, type }

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

            Create a cache control breakpoint at this content block.

          • caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

            Tool invocation directly from the model.

            • BetaDirectCaller object { type }

              Tool invocation directly from the model.

            • BetaServerToolCaller object { tool_id, type }

              Tool invocation generated by a server-side tool.

            • BetaServerToolCaller20260120 object { tool_id, type }

        • BetaWebFetchToolResultBlockParam object { content, tool_use_id, type, 2 more }

          • content: BetaWebFetchToolResultErrorBlockParam or BetaWebFetchBlockParam

            • BetaWebFetchToolResultErrorBlockParam object { error_code, type }

              • error_code: BetaWebFetchToolResultErrorCode

                • "invalid_tool_input"

                • "url_too_long"

                • "url_not_allowed"

                • "url_not_accessible"

                • "unsupported_content_type"

                • "too_many_requests"

                • "max_uses_exceeded"

                • "unavailable"

              • type: "web_fetch_tool_result_error"

                • "web_fetch_tool_result_error"

            • BetaWebFetchBlockParam object { content, type, url, retrieved_at }

              • content: BetaRequestDocumentBlock

              • type: "web_fetch_result"

                • "web_fetch_result"

              • url: string

                Fetched content URL

              • retrieved_at: optional string

                ISO 8601 timestamp when the content was retrieved

          • tool_use_id: string

          • type: "web_fetch_tool_result"

            • "web_fetch_tool_result"

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

          • caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

            Tool invocation directly from the model.

            • BetaDirectCaller object { type }

              Tool invocation directly from the model.

            • BetaServerToolCaller object { tool_id, type }

              Tool invocation generated by a server-side tool.

            • BetaServerToolCaller20260120 object { tool_id, type }

        • BetaAdvisorToolResultBlockParam object { content, tool_use_id, type, cache_control }

          • content: BetaAdvisorToolResultErrorParam or BetaAdvisorResultBlockParam or BetaAdvisorRedactedResultBlockParam

            • BetaAdvisorToolResultErrorParam object { error_code, type }

              • error_code: "max_uses_exceeded" or "prompt_too_long" or "too_many_requests" or 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 object { text, type }

              • text: string

              • type: "advisor_result"

                • "advisor_result"

            • BetaAdvisorRedactedResultBlockParam object { encrypted_content, type }

              • encrypted_content: string

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

              • type: "advisor_redacted_result"

                • "advisor_redacted_result"

          • tool_use_id: string

          • type: "advisor_tool_result"

            • "advisor_tool_result"

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

        • BetaCodeExecutionToolResultBlockParam object { content, tool_use_id, type, cache_control }

          • content: BetaCodeExecutionToolResultBlockParamContent

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

            • BetaCodeExecutionToolResultErrorParam object { error_code, type }

              • 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 object { content, return_code, stderr, 2 more }

              • content: array of BetaCodeExecutionOutputBlockParam

                • 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 object { content, encrypted_stdout, return_code, 2 more }

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

              • content: array of BetaCodeExecutionOutputBlockParam

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

            Create a cache control breakpoint at this content block.

        • BetaBashCodeExecutionToolResultBlockParam object { content, tool_use_id, type, cache_control }

          • content: BetaBashCodeExecutionToolResultErrorParam or BetaBashCodeExecutionResultBlockParam

            • BetaBashCodeExecutionToolResultErrorParam object { error_code, type }

              • error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 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 object { content, return_code, stderr, 2 more }

              • content: array of BetaBashCodeExecutionOutputBlockParam

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

            Create a cache control breakpoint at this content block.

        • BetaTextEditorCodeExecutionToolResultBlockParam object { content, tool_use_id, type, cache_control }

          • content: BetaTextEditorCodeExecutionToolResultErrorParam or BetaTextEditorCodeExecutionViewResultBlockParam or BetaTextEditorCodeExecutionCreateResultBlockParam or BetaTextEditorCodeExecutionStrReplaceResultBlockParam

            • BetaTextEditorCodeExecutionToolResultErrorParam object { error_code, type, error_message }

              • error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 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: optional string

            • BetaTextEditorCodeExecutionViewResultBlockParam object { content, file_type, type, 3 more }

              • content: string

              • file_type: "text" or "image" or "pdf"

                • "text"

                • "image"

                • "pdf"

              • type: "text_editor_code_execution_view_result"

                • "text_editor_code_execution_view_result"

              • num_lines: optional number

              • start_line: optional number

              • total_lines: optional number

            • BetaTextEditorCodeExecutionCreateResultBlockParam object { is_file_update, type }

              • is_file_update: boolean

              • type: "text_editor_code_execution_create_result"

                • "text_editor_code_execution_create_result"

            • BetaTextEditorCodeExecutionStrReplaceResultBlockParam object { type, lines, new_lines, 3 more }

              • type: "text_editor_code_execution_str_replace_result"

                • "text_editor_code_execution_str_replace_result"

              • lines: optional array of string

              • new_lines: optional number

              • new_start: optional number

              • old_lines: optional number

              • old_start: optional number

          • tool_use_id: string

          • type: "text_editor_code_execution_tool_result"

            • "text_editor_code_execution_tool_result"

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

        • BetaToolSearchToolResultBlockParam object { content, tool_use_id, type, cache_control }

          • content: BetaToolSearchToolResultErrorParam or BetaToolSearchToolSearchResultBlockParam

            • BetaToolSearchToolResultErrorParam object { error_code, type }

              • error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "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 object { tool_references, type }

              • tool_references: array of BetaToolReferenceBlockParam

                • tool_name: string

                • type: "tool_reference"

                • cache_control: optional BetaCacheControlEphemeral

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

            Create a cache control breakpoint at this content block.

        • BetaMCPToolUseBlockParam object { id, input, name, 3 more }

          • id: string

          • input: map[unknown]

          • name: string

          • server_name: string

            The name of the MCP server

          • type: "mcp_tool_use"

            • "mcp_tool_use"

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

        • BetaRequestMCPToolResultBlockParam object { tool_use_id, type, cache_control, 2 more }

          • tool_use_id: string

          • type: "mcp_tool_result"

            • "mcp_tool_result"

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

          • content: optional string or array of BetaTextBlockParam

            • string

            • BetaMCPToolResultBlockParamContent = array of BetaTextBlockParam

              • text: string

              • type: "text"

              • cache_control: optional BetaCacheControlEphemeral

                Create a cache control breakpoint at this content block.

              • citations: optional array of BetaTextCitationParam

          • is_error: optional boolean

        • BetaContainerUploadBlockParam object { file_id, type, cache_control }

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

          • file_id: string

          • type: "container_upload"

            • "container_upload"

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

        • BetaCompactionBlockParam object { content, type, cache_control, encrypted_content }

          A compaction block containing summary of previous context.

          Users should round-trip these blocks from responses to subsequent requests to maintain context across compaction boundaries.

          When content is None, the block represents a failed compaction. The server treats these as no-ops. Empty string content is not allowed.

          • content: string

            Summary of previously compacted content, or null if compaction failed

          • type: "compaction"

            • "compaction"

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

          • encrypted_content: optional string

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

    • role: "user" or "assistant"

      • "user"

      • "assistant"

  • model: Model

    The model that will complete your prompt.

    See models for additional details and options.

    • "claude-opus-4-7" or "claude-mythos-preview" or "claude-opus-4-6" or 14 more

      The model that will complete your prompt.

      See models for additional details and options.

      • "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: optional BetaCacheControlEphemeral

    Top-level cache control automatically applies a cache_control marker to the last cacheable block in the request.

  • container: optional BetaContainerParams or string

    Container identifier for reuse across requests.

    • BetaContainerParams object { id, skills }

      Container parameters with skills to be loaded.

      • id: optional string

        Container id

      • skills: optional array of BetaSkillParams

        List of skills to load in the container

        • skill_id: string

          Skill ID

        • type: "anthropic" or "custom"

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

          • "anthropic"

          • "custom"

        • version: optional string

          Skill version or 'latest' for most recent version

    • string

  • context_management: optional BetaContextManagementConfig

    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: optional array of BetaClearToolUses20250919Edit or BetaClearThinking20251015Edit or BetaCompact20260112Edit

      List of context management edits to apply

      • BetaClearToolUses20250919Edit object { type, clear_at_least, clear_tool_inputs, 3 more }

        • type: "clear_tool_uses_20250919"

          • "clear_tool_uses_20250919"

        • clear_at_least: optional BetaInputTokensClearAtLeast

          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: optional boolean or array of string

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

          • boolean

          • array of string

        • exclude_tools: optional array of string

          Tool names whose uses are preserved from clearing

        • keep: optional BetaToolUsesKeep

          Number of tool uses to retain in the conversation

          • type: "tool_uses"

            • "tool_uses"

          • value: number

        • trigger: optional BetaInputTokensTrigger or BetaToolUsesTrigger

          Condition that triggers the context management strategy

          • BetaInputTokensTrigger object { type, value }

            • type: "input_tokens"

              • "input_tokens"

            • value: number

          • BetaToolUsesTrigger object { type, value }

            • type: "tool_uses"

              • "tool_uses"

            • value: number

      • BetaClearThinking20251015Edit object { type, keep }

        • type: "clear_thinking_20251015"

          • "clear_thinking_20251015"

        • keep: optional BetaThinkingTurns or BetaAllThinkingTurns or "all"

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

          • BetaThinkingTurns object { type, value }

            • type: "thinking_turns"

              • "thinking_turns"

            • value: number

          • BetaAllThinkingTurns object { type }

            • type: "all"

              • "all"

          • "all"

            • "all"

      • BetaCompact20260112Edit object { type, instructions, pause_after_compaction, trigger }

        Automatically compact older context when reaching the configured trigger threshold.

        • type: "compact_20260112"

          • "compact_20260112"

        • instructions: optional string

          Additional instructions for summarization.

        • pause_after_compaction: optional boolean

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

        • trigger: optional BetaInputTokensTrigger

          When to trigger compaction. Defaults to 150000 input tokens.

  • diagnostics: optional BetaDiagnosticsParam

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

    • previous_message_id: optional string

      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: optional string

    Specifies the geographic region for inference processing. If not specified, the workspace's default_inference_geo is used.

  • mcp_servers: optional array of BetaRequestMCPServerURLDefinition

    MCP servers to be utilized in this request

    • name: string

    • type: "url"

      • "url"

    • url: string

    • authorization_token: optional string

    • tool_configuration: optional BetaRequestMCPServerToolConfiguration

      • allowed_tools: optional array of string

      • enabled: optional boolean

  • metadata: optional BetaMetadata

    An object describing metadata about the request.

    • user_id: optional string

      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: optional BetaOutputConfig

    Configuration options for the model's output, such as the output format.

    • effort: optional "low" or "medium" or "high" or 2 more

      All possible effort levels.

      • "low"

      • "medium"

      • "high"

      • "xhigh"

      • "max"

    • format: optional BetaJSONOutputFormat

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

      • schema: map[unknown]

        The JSON schema of the format

      • type: "json_schema"

        • "json_schema"

    • task_budget: optional 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: optional number

        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: optional BetaJSONOutputFormat

    Deprecated: Use output_config.format instead. See structured outputs

    A schema to specify Claude's output format in responses. This parameter will be removed in a future release.

  • service_tier: optional "auto" or "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 for details.

    • "auto"

    • "standard_only"

  • speed: optional "standard" or "fast"

    The inference speed mode for this request. "fast" enables high output-tokens-per-second inference.

    • "standard"

    • "fast"

  • stop_sequences: optional array of string

    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: optional boolean

    Whether to incrementally stream the response using server-sent events.

    See streaming for details.

  • system: optional string or array of BetaTextBlockParam

    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.

    • string

    • array of BetaTextBlockParam

      • text: string

      • type: "text"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • citations: optional array of BetaTextCitationParam

  • temperature: optional 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: optional 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 for details.

    • BetaThinkingConfigEnabled object { budget_tokens, type, display }

      • 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 for details.

      • type: "enabled"

        • "enabled"

      • display: optional "summarized" or "omitted"

        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 object { type }

      • type: "disabled"

        • "disabled"

    • BetaThinkingConfigAdaptive object { type, display }

      • type: "adaptive"

        • "adaptive"

      • display: optional "summarized" or "omitted"

        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: optional 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 object { type, disable_parallel_tool_use }

      The model will automatically decide whether to use tools.

      • type: "auto"

        • "auto"

      • disable_parallel_tool_use: optional boolean

        Whether to disable parallel tool use.

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

    • BetaToolChoiceAny object { type, disable_parallel_tool_use }

      The model will use any available tools.

      • type: "any"

        • "any"

      • disable_parallel_tool_use: optional boolean

        Whether to disable parallel tool use.

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

    • BetaToolChoiceTool object { name, type, disable_parallel_tool_use }

      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: optional boolean

        Whether to disable parallel tool use.

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

    • BetaToolChoiceNone object { type }

      The model will not be allowed to use tools.

      • type: "none"

        • "none"

  • tools: optional array of BetaToolUnion

    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, see their individual documentation as each has its own behavior (e.g., the 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 for the tool input shape that the model will produce in tool_use output content blocks.

    For example, if you defined tools as:

    [
  {
    "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:

    [
  {
    "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:

    [
  {
    "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 for more details.

    • BetaTool object { input_schema, name, allowed_callers, 7 more }

      • input_schema: object { type, properties, required }

        JSON schema for this tool's input.

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

        • type: "object"

          • "object"

        • properties: optional map[unknown]

        • required: optional array of string

      • name: string

        Name of the tool.

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

      • allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

        • "direct"

        • "code_execution_20250825"

        • "code_execution_20260120"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • defer_loading: optional boolean

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

      • description: optional 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: optional boolean

        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: optional array of map[unknown]

      • strict: optional boolean

        When true, guarantees schema validation on tool names and inputs

      • type: optional "custom"

        • "custom"

    • BetaToolBash20241022 object { name, type, allowed_callers, 4 more }

      • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

        • "direct"

        • "code_execution_20250825"

        • "code_execution_20260120"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • defer_loading: optional boolean

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

      • input_examples: optional array of map[unknown]

      • strict: optional boolean

        When true, guarantees schema validation on tool names and inputs

    • BetaToolBash20250124 object { name, type, allowed_callers, 4 more }

      • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

        • "direct"

        • "code_execution_20250825"

        • "code_execution_20260120"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • defer_loading: optional boolean

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

      • input_examples: optional array of map[unknown]

      • strict: optional boolean

        When true, guarantees schema validation on tool names and inputs

    • BetaCodeExecutionTool20250522 object { name, type, allowed_callers, 3 more }

      • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

        • "direct"

        • "code_execution_20250825"

        • "code_execution_20260120"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • defer_loading: optional boolean

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

      • strict: optional boolean

        When true, guarantees schema validation on tool names and inputs

    • BetaCodeExecutionTool20250825 object { name, type, allowed_callers, 3 more }

      • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

        • "direct"

        • "code_execution_20250825"

        • "code_execution_20260120"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • defer_loading: optional boolean

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

      • strict: optional boolean

        When true, guarantees schema validation on tool names and inputs

    • BetaCodeExecutionTool20260120 object { name, type, allowed_callers, 3 more }

      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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

        • "direct"

        • "code_execution_20250825"

        • "code_execution_20260120"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • defer_loading: optional boolean

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

      • strict: optional boolean

        When true, guarantees schema validation on tool names and inputs

    • BetaToolComputerUse20241022 object { display_height_px, display_width_px, name, 7 more }

      • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

        • "direct"

        • "code_execution_20250825"

        • "code_execution_20260120"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • defer_loading: optional boolean

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

      • display_number: optional number

        The X11 display number (e.g. 0, 1) for the display.

      • input_examples: optional array of map[unknown]

      • strict: optional boolean

        When true, guarantees schema validation on tool names and inputs

    • BetaMemoryTool20250818 object { name, type, allowed_callers, 4 more }

      • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

        • "direct"

        • "code_execution_20250825"

        • "code_execution_20260120"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • defer_loading: optional boolean

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

      • input_examples: optional array of map[unknown]

      • strict: optional boolean

        When true, guarantees schema validation on tool names and inputs

    • BetaToolComputerUse20250124 object { display_height_px, display_width_px, name, 7 more }

      • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

        • "direct"

        • "code_execution_20250825"

        • "code_execution_20260120"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • defer_loading: optional boolean

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

      • display_number: optional number

        The X11 display number (e.g. 0, 1) for the display.

      • input_examples: optional array of map[unknown]

      • strict: optional boolean

        When true, guarantees schema validation on tool names and inputs

    • BetaToolTextEditor20241022 object { name, type, allowed_callers, 4 more }

      • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

        • "direct"

        • "code_execution_20250825"

        • "code_execution_20260120"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • defer_loading: optional boolean

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

      • input_examples: optional array of map[unknown]

      • strict: optional boolean

        When true, guarantees schema validation on tool names and inputs

    • BetaToolComputerUse20251124 object { display_height_px, display_width_px, name, 8 more }

      • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

        • "direct"

        • "code_execution_20250825"

        • "code_execution_20260120"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • defer_loading: optional boolean

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

      • display_number: optional number

        The X11 display number (e.g. 0, 1) for the display.

      • enable_zoom: optional boolean

        Whether to enable an action to take a zoomed-in screenshot of the screen.

      • input_examples: optional array of map[unknown]

      • strict: optional boolean

        When true, guarantees schema validation on tool names and inputs

    • BetaToolTextEditor20250124 object { name, type, allowed_callers, 4 more }

      • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

        • "direct"

        • "code_execution_20250825"

        • "code_execution_20260120"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • defer_loading: optional boolean

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

      • input_examples: optional array of map[unknown]

      • strict: optional boolean

        When true, guarantees schema validation on tool names and inputs

    • BetaToolTextEditor20250429 object { name, type, allowed_callers, 4 more }

      • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

        • "direct"

        • "code_execution_20250825"

        • "code_execution_20260120"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • defer_loading: optional boolean

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

      • input_examples: optional array of map[unknown]

      • strict: optional boolean

        When true, guarantees schema validation on tool names and inputs

    • BetaToolTextEditor20250728 object { name, type, allowed_callers, 5 more }

      • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

        • "direct"

        • "code_execution_20250825"

        • "code_execution_20260120"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • defer_loading: optional boolean

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

      • input_examples: optional array of map[unknown]

      • max_characters: optional number

        Maximum number of characters to display when viewing a file. If not specified, defaults to displaying the full file.

      • strict: optional boolean

        When true, guarantees schema validation on tool names and inputs

    • BetaWebSearchTool20250305 object { name, type, allowed_callers, 7 more }

      • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

        • "direct"

        • "code_execution_20250825"

        • "code_execution_20260120"

      • allowed_domains: optional array of string

        If provided, only these domains will be included in results. Cannot be used alongside blocked_domains.

      • blocked_domains: optional array of string

        If provided, these domains will never appear in results. Cannot be used alongside allowed_domains.

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • defer_loading: optional boolean

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

      • max_uses: optional number

        Maximum number of times the tool can be used in the API request.

      • strict: optional boolean

        When true, guarantees schema validation on tool names and inputs

      • user_location: optional BetaUserLocation

        Parameters for the user's location. Used to provide more relevant search results.

        • type: "approximate"

          • "approximate"

        • city: optional string

          The city of the user.

        • country: optional string

          The two letter ISO country code of the user.

        • region: optional string

          The region of the user.

        • timezone: optional string

          The IANA timezone of the user.

    • BetaWebFetchTool20250910 object { name, type, allowed_callers, 8 more }

      • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

        • "direct"

        • "code_execution_20250825"

        • "code_execution_20260120"

      • allowed_domains: optional array of string

        List of domains to allow fetching from

      • blocked_domains: optional array of string

        List of domains to block fetching from

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • citations: optional BetaCitationsConfigParam

        Citations configuration for fetched documents. Citations are disabled by default.

      • defer_loading: optional 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: optional number

        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: optional number

        Maximum number of times the tool can be used in the API request.

      • strict: optional boolean

        When true, guarantees schema validation on tool names and inputs

    • BetaWebSearchTool20260209 object { name, type, allowed_callers, 7 more }

      • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

        • "direct"

        • "code_execution_20250825"

        • "code_execution_20260120"

      • allowed_domains: optional array of string

        If provided, only these domains will be included in results. Cannot be used alongside blocked_domains.

      • blocked_domains: optional array of string

        If provided, these domains will never appear in results. Cannot be used alongside allowed_domains.

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • defer_loading: optional boolean

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

      • max_uses: optional number

        Maximum number of times the tool can be used in the API request.

      • strict: optional boolean

        When true, guarantees schema validation on tool names and inputs

      • user_location: optional BetaUserLocation

        Parameters for the user's location. Used to provide more relevant search results.

    • BetaWebFetchTool20260209 object { name, type, allowed_callers, 8 more }

      • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

        • "direct"

        • "code_execution_20250825"

        • "code_execution_20260120"

      • allowed_domains: optional array of string

        List of domains to allow fetching from

      • blocked_domains: optional array of string

        List of domains to block fetching from

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • citations: optional BetaCitationsConfigParam

        Citations configuration for fetched documents. Citations are disabled by default.

      • defer_loading: optional 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: optional number

        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: optional number

        Maximum number of times the tool can be used in the API request.

      • strict: optional boolean

        When true, guarantees schema validation on tool names and inputs

    • BetaWebFetchTool20260309 object { name, type, allowed_callers, 9 more }

      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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

        • "direct"

        • "code_execution_20250825"

        • "code_execution_20260120"

      • allowed_domains: optional array of string

        List of domains to allow fetching from

      • blocked_domains: optional array of string

        List of domains to block fetching from

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • citations: optional BetaCitationsConfigParam

        Citations configuration for fetched documents. Citations are disabled by default.

      • defer_loading: optional 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: optional number

        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: optional number

        Maximum number of times the tool can be used in the API request.

      • strict: optional boolean

        When true, guarantees schema validation on tool names and inputs

      • use_cache: optional 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 object { model, name, type, 6 more }

      • model: Model

        The model that will complete your prompt.

        See models 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

        • "direct"

        • "code_execution_20250825"

        • "code_execution_20260120"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • caching: optional BetaCacheControlEphemeral

        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: optional boolean

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

      • max_uses: optional number

        Maximum number of times the tool can be used in the API request.

      • strict: optional boolean

        When true, guarantees schema validation on tool names and inputs

    • BetaToolSearchToolBm25_20251119 object { name, type, allowed_callers, 3 more }

      • 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" or "tool_search_tool_bm25"

        • "tool_search_tool_bm25_20251119"

        • "tool_search_tool_bm25"

      • allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

        • "direct"

        • "code_execution_20250825"

        • "code_execution_20260120"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • defer_loading: optional boolean

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

      • strict: optional boolean

        When true, guarantees schema validation on tool names and inputs

    • BetaToolSearchToolRegex20251119 object { name, type, allowed_callers, 3 more }

      • 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" or "tool_search_tool_regex"

        • "tool_search_tool_regex_20251119"

        • "tool_search_tool_regex"

      • allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

        • "direct"

        • "code_execution_20250825"

        • "code_execution_20260120"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • defer_loading: optional boolean

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

      • strict: optional boolean

        When true, guarantees schema validation on tool names and inputs

    • BetaMCPToolset object { mcp_server_name, type, cache_control, 2 more }

      Configuration for a group of tools from an MCP server.

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

      • mcp_server_name: string

        Name of the MCP server to configure tools for

      • type: "mcp_toolset"

        • "mcp_toolset"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • configs: optional map[BetaMCPToolConfig]

        Configuration overrides for specific tools, keyed by tool name

        • defer_loading: optional boolean

        • enabled: optional boolean

      • default_config: optional BetaMCPToolDefaultConfig

        Default configuration applied to all tools from this server

        • defer_loading: optional boolean

        • enabled: optional boolean

  • top_k: optional 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.

    Recommended for advanced use cases only.

  • top_p: optional 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: optional string

    The user profile ID to attribute this request to. Use when acting on behalf of a party other than your organization.

Returns

  • BetaMessage object { id, container, content, 9 more }

    • id: string

      Unique object identifier.

      The format and length of IDs may change over time.

    • 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 of BetaSkill

        Skills loaded in the container

        • skill_id: string

          Skill ID

        • type: "anthropic" or "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 of BetaContentBlock

      Content generated by the model.

      This is an array of content blocks, each of which has a type that determines its shape.

      Example:

      [{"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:

      [
  {"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:

      [{"type": "text", "text": "B)"}]

      • BetaTextBlock object { citations, text, type }

        • citations: array of BetaTextCitation

          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 object { cited_text, document_index, document_title, 4 more }

            • cited_text: string

            • document_index: number

            • document_title: string

            • end_char_index: number

            • file_id: string

            • start_char_index: number

            • type: "char_location"

              • "char_location"

          • BetaCitationPageLocation object { cited_text, document_index, document_title, 4 more }

            • cited_text: string

            • document_index: number

            • document_title: string

            • end_page_number: number

            • file_id: string

            • start_page_number: number

            • type: "page_location"

              • "page_location"

          • BetaCitationContentBlockLocation object { cited_text, document_index, document_title, 4 more }

            • 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

            • 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

            • 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 object { cited_text, encrypted_index, title, 2 more }

            • cited_text: string

            • encrypted_index: string

            • title: string

            • type: "web_search_result_location"

              • "web_search_result_location"

            • url: string

          • BetaCitationSearchResultLocation object { cited_text, end_block_index, search_result_index, 4 more }

            • 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

            • type: "search_result_location"

              • "search_result_location"

        • text: string

        • type: "text"

          • "text"

      • BetaThinkingBlock object { signature, thinking, type }

        • signature: string

        • thinking: string

        • type: "thinking"

          • "thinking"

      • BetaRedactedThinkingBlock object { data, type }

        • data: string

        • type: "redacted_thinking"

          • "redacted_thinking"

      • BetaToolUseBlock object { id, input, name, 2 more }

        • id: string

        • input: map[unknown]

        • name: string

        • type: "tool_use"

          • "tool_use"

        • caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

          Tool invocation directly from the model.

          • BetaDirectCaller object { type }

            Tool invocation directly from the model.

            • type: "direct"

              • "direct"

          • BetaServerToolCaller object { tool_id, type }

            Tool invocation generated by a server-side tool.

            • tool_id: string

            • type: "code_execution_20250825"

              • "code_execution_20250825"

          • BetaServerToolCaller20260120 object { tool_id, type }

            • tool_id: string

            • type: "code_execution_20260120"

              • "code_execution_20260120"

      • BetaServerToolUseBlock object { id, input, name, 2 more }

        • id: string

        • input: map[unknown]

        • name: "advisor" or "web_search" or "web_fetch" or 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: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

          Tool invocation directly from the model.

          • BetaDirectCaller object { type }

            Tool invocation directly from the model.

          • BetaServerToolCaller object { tool_id, type }

            Tool invocation generated by a server-side tool.

          • BetaServerToolCaller20260120 object { tool_id, type }

      • BetaWebSearchToolResultBlock object { content, tool_use_id, type, caller }

        • content: BetaWebSearchToolResultBlockContent

          • BetaWebSearchToolResultError object { error_code, type }

            • 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 of BetaWebSearchResultBlock

            • encrypted_content: string

            • page_age: string

            • 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: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

          Tool invocation directly from the model.

          • BetaDirectCaller object { type }

            Tool invocation directly from the model.

          • BetaServerToolCaller object { tool_id, type }

            Tool invocation generated by a server-side tool.

          • BetaServerToolCaller20260120 object { tool_id, type }

      • BetaWebFetchToolResultBlock object { content, tool_use_id, type, caller }

        • content: BetaWebFetchToolResultErrorBlock or BetaWebFetchBlock

          • BetaWebFetchToolResultErrorBlock object { error_code, type }

            • error_code: BetaWebFetchToolResultErrorCode

              • "invalid_tool_input"

              • "url_too_long"

              • "url_not_allowed"

              • "url_not_accessible"

              • "unsupported_content_type"

              • "too_many_requests"

              • "max_uses_exceeded"

              • "unavailable"

            • type: "web_fetch_tool_result_error"

              • "web_fetch_tool_result_error"

          • BetaWebFetchBlock object { content, retrieved_at, type, url }

            • content: BetaDocumentBlock

              • citations: BetaCitationConfig

                Citation configuration for the document

                • enabled: boolean

              • source: BetaBase64PDFSource or BetaPlainTextSource

                • BetaBase64PDFSource object { data, media_type, type }

                  • data: string

                  • media_type: "application/pdf"

                    • "application/pdf"

                  • type: "base64"

                    • "base64"

                • BetaPlainTextSource object { data, media_type, type }

                  • data: string

                  • media_type: "text/plain"

                    • "text/plain"

                  • type: "text"

                    • "text"

              • title: string

                The title of the document

              • type: "document"

                • "document"

            • retrieved_at: string

              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: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

          Tool invocation directly from the model.

          • BetaDirectCaller object { type }

            Tool invocation directly from the model.

          • BetaServerToolCaller object { tool_id, type }

            Tool invocation generated by a server-side tool.

          • BetaServerToolCaller20260120 object { tool_id, type }

      • BetaAdvisorToolResultBlock object { content, tool_use_id, type }

        • content: BetaAdvisorToolResultError or BetaAdvisorResultBlock or BetaAdvisorRedactedResultBlock

          • BetaAdvisorToolResultError object { error_code, type }

            • error_code: "max_uses_exceeded" or "prompt_too_long" or "too_many_requests" or 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 object { text, type }

            • text: string

            • type: "advisor_result"

              • "advisor_result"

          • BetaAdvisorRedactedResultBlock object { encrypted_content, type }

            • encrypted_content: string

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

            • type: "advisor_redacted_result"

              • "advisor_redacted_result"

        • tool_use_id: string

        • type: "advisor_tool_result"

          • "advisor_tool_result"

      • BetaCodeExecutionToolResultBlock object { content, tool_use_id, type }

        • content: BetaCodeExecutionToolResultBlockContent

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

          • BetaCodeExecutionToolResultError object { error_code, type }

            • 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 object { content, return_code, stderr, 2 more }

            • content: array of BetaCodeExecutionOutputBlock

              • 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 object { content, encrypted_stdout, return_code, 2 more }

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

            • content: array of BetaCodeExecutionOutputBlock

              • 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 object { content, tool_use_id, type }

        • content: BetaBashCodeExecutionToolResultError or BetaBashCodeExecutionResultBlock

          • BetaBashCodeExecutionToolResultError object { error_code, type }

            • error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 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 object { content, return_code, stderr, 2 more }

            • content: array of BetaBashCodeExecutionOutputBlock

              • 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 object { content, tool_use_id, type }

        • content: BetaTextEditorCodeExecutionToolResultError or BetaTextEditorCodeExecutionViewResultBlock or BetaTextEditorCodeExecutionCreateResultBlock or BetaTextEditorCodeExecutionStrReplaceResultBlock

          • BetaTextEditorCodeExecutionToolResultError object { error_code, error_message, type }

            • error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more

              • "invalid_tool_input"

              • "unavailable"

              • "too_many_requests"

              • "execution_time_exceeded"

              • "file_not_found"

            • error_message: string

            • type: "text_editor_code_execution_tool_result_error"

              • "text_editor_code_execution_tool_result_error"

          • BetaTextEditorCodeExecutionViewResultBlock object { content, file_type, num_lines, 3 more }

            • content: string

            • file_type: "text" or "image" or "pdf"

              • "text"

              • "image"

              • "pdf"

            • num_lines: number

            • start_line: number

            • total_lines: number

            • type: "text_editor_code_execution_view_result"

              • "text_editor_code_execution_view_result"

          • BetaTextEditorCodeExecutionCreateResultBlock object { is_file_update, type }

            • is_file_update: boolean

            • type: "text_editor_code_execution_create_result"

              • "text_editor_code_execution_create_result"

          • BetaTextEditorCodeExecutionStrReplaceResultBlock object { lines, new_lines, new_start, 3 more }

            • lines: array of string

            • new_lines: number

            • new_start: number

            • old_lines: number

            • old_start: number

            • 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 object { content, tool_use_id, type }

        • content: BetaToolSearchToolResultError or BetaToolSearchToolSearchResultBlock

          • BetaToolSearchToolResultError object { error_code, error_message, type }

            • error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"

              • "invalid_tool_input"

              • "unavailable"

              • "too_many_requests"

              • "execution_time_exceeded"

            • error_message: string

            • type: "tool_search_tool_result_error"

              • "tool_search_tool_result_error"

          • BetaToolSearchToolSearchResultBlock object { tool_references, type }

            • tool_references: array of BetaToolReferenceBlock

              • 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 object { id, input, name, 2 more }

        • id: string

        • input: map[unknown]

        • 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 object { content, is_error, tool_use_id, type }

        • content: string or array of BetaTextBlock

          • string

          • BetaMCPToolResultBlockContent = array of BetaTextBlock

            • citations: array of BetaTextCitation

              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 object { file_id, type }

        Response model for a file uploaded to the container.

        • file_id: string

        • type: "container_upload"

          • "container_upload"

      • BetaCompactionBlock object { content, encrypted_content, type }

        A compaction block returned when autocompact is triggered.

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

        • content: string

          Summary of compacted content, or null if compaction failed

        • encrypted_content: string

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

        • type: "compaction"

          • "compaction"

    • context_management: BetaContextManagementResponse

      Context management response.

      Information about context management strategies applied during the request.

      • applied_edits: array of BetaClearToolUses20250919EditResponse or BetaClearThinking20251015EditResponse

        List of context management edits that were applied.

        • BetaClearToolUses20250919EditResponse object { cleared_input_tokens, cleared_tool_uses, type }

          • cleared_input_tokens: number

            Number of input tokens cleared by this edit.

          • cleared_tool_uses: number

            Number of tool uses that were cleared.

          • type: "clear_tool_uses_20250919"

            The type of context management edit applied.

            • "clear_tool_uses_20250919"

        • BetaClearThinking20251015EditResponse object { cleared_input_tokens, cleared_thinking_turns, type }

          • cleared_input_tokens: number

            Number of input tokens cleared by this edit.

          • cleared_thinking_turns: number

            Number of thinking turns that were cleared.

          • type: "clear_thinking_20251015"

            The type of context management edit applied.

            • "clear_thinking_20251015"

    • diagnostics: BetaDiagnostics

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

      • cache_miss_reason: BetaCacheMissModelChanged or BetaCacheMissSystemChanged or BetaCacheMissToolsChanged or 3 more

        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 object { cache_missed_input_tokens, type }

          • 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 object { cache_missed_input_tokens, type }

          • 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 object { cache_missed_input_tokens, type }

          • 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 object { cache_missed_input_tokens, type }

          • 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 object { type }

          • type: "previous_message_not_found"

            • "previous_message_not_found"

        • BetaCacheMissUnavailable object { type }

          • type: "unavailable"

            • "unavailable"

    • model: Model

      The model that will complete your prompt.

      See models for additional details and options.

      • "claude-opus-4-7" or "claude-mythos-preview" or "claude-opus-4-6" or 14 more

        The model that will complete your prompt.

        See models for additional details and options.

        • "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

      Structured information about a refusal.

      • category: "cyber" or "bio"

        The policy category that triggered the refusal.

        null when the refusal doesn't map to a named category.

        • "cyber"

        • "bio"

      • explanation: string

        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

      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

      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

        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.

      • inference_geo: string

        The geographic region where inference was performed for this request.

      • input_tokens: number

        The number of input tokens which were used.

      • iterations: BetaIterationsUsage

        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 object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }

          Token usage for a sampling iteration.

          • cache_creation: BetaCacheCreation

            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 object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }

          Token usage for a compaction iteration.

          • cache_creation: BetaCacheCreation

            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 object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 4 more }

          Token usage for an advisor sub-inference iteration.

          • cache_creation: BetaCacheCreation

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

      • server_tool_use: BetaServerToolUsage

        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" or "priority" or "batch"

        If the request used the priority, standard, or batch tier.

        • "standard"

        • "priority"

        • "batch"

      • speed: "standard" or "fast"

        The inference speed mode used for this request.

        • "standard"

        • "fast"

Example

curl https://api.anthropic.com/v1/messages \
    -H 'Content-Type: application/json' \
    -H 'anthropic-version: 2023-06-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY" \
    --max-time 600 \
    -d "{
          \"max_tokens\": 1024,
          \"messages\": [
            {
              \"content\": \"Hello, world\",
              \"role\": \"user\"
            }
          ],
          \"model\": \"claude-opus-4-6\",
          \"system\": [
            {
              \"text\": \"Today's date is 2024-06-01.\",
              \"type\": \"text\"
            }
          ],
          \"temperature\": 1,
          \"thinking\": {
            \"type\": \"adaptive\"
          },
          \"tools\": [
            {
              \"input_schema\": {
                \"type\": \"object\",
                \"properties\": {
                  \"location\": \"bar\",
                  \"unit\": \"bar\"
                },
                \"required\": [
                  \"location\"
                ]
              },
              \"name\": \"name\"
            }
          ],
          \"top_k\": 5,
          \"top_p\": 0.7
        }"

Response

{
  "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,
    "server_tool_use": {
      "web_fetch_requests": 2,
      "web_search_requests": 0
    },
    "service_tier": "standard",
    "speed": "standard"
  }
}

Count tokens in a Message

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

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Body Parameters

  • messages: array of BetaMessageParam

    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:

    [{"role": "user", "content": "Hello, Claude"}]

    Example with multiple conversational turns:

    [
  {"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:

    [
  {"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:

    {"role": "user", "content": "Hello, Claude"}

    {"role": "user", "content": [{"type": "text", "text": "Hello, Claude"}]}

    See input examples.

    Note that if you want to include a system prompt, 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 or array of BetaContentBlockParam

      • string

      • array of BetaContentBlockParam

        • BetaTextBlockParam object { text, type, cache_control, citations }

          • text: string

          • type: "text"

            • "text"

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

            • type: "ephemeral"

              • "ephemeral"

            • ttl: optional "5m" or "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: optional array of BetaTextCitationParam

            • BetaCitationCharLocationParam object { cited_text, document_index, document_title, 3 more }

              • cited_text: string

              • document_index: number

              • document_title: string

              • end_char_index: number

              • start_char_index: number

              • type: "char_location"

                • "char_location"

            • BetaCitationPageLocationParam object { cited_text, document_index, document_title, 3 more }

              • cited_text: string

              • document_index: number

              • document_title: string

              • end_page_number: number

              • start_page_number: number

              • type: "page_location"

                • "page_location"

            • BetaCitationContentBlockLocationParam object { cited_text, document_index, document_title, 3 more }

              • 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

              • 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 object { cited_text, encrypted_index, title, 2 more }

              • cited_text: string

              • encrypted_index: string

              • title: string

              • type: "web_search_result_location"

                • "web_search_result_location"

              • url: string

            • BetaCitationSearchResultLocationParam object { cited_text, end_block_index, search_result_index, 4 more }

              • 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

              • type: "search_result_location"

                • "search_result_location"

        • BetaImageBlockParam object { source, type, cache_control }

          • source: BetaBase64ImageSource or BetaURLImageSource or BetaFileImageSource

            • BetaBase64ImageSource object { data, media_type, type }

              • data: string

              • media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"

                • "image/jpeg"

                • "image/png"

                • "image/gif"

                • "image/webp"

              • type: "base64"

                • "base64"

            • BetaURLImageSource object { type, url }

              • type: "url"

                • "url"

              • url: string

            • BetaFileImageSource object { file_id, type }

              • file_id: string

              • type: "file"

                • "file"

          • type: "image"

            • "image"

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

        • BetaRequestDocumentBlock object { source, type, cache_control, 3 more }

          • source: BetaBase64PDFSource or BetaPlainTextSource or BetaContentBlockSource or 2 more

            • BetaBase64PDFSource object { data, media_type, type }

              • data: string

              • media_type: "application/pdf"

                • "application/pdf"

              • type: "base64"

                • "base64"

            • BetaPlainTextSource object { data, media_type, type }

              • data: string

              • media_type: "text/plain"

                • "text/plain"

              • type: "text"

                • "text"

            • BetaContentBlockSource object { content, type }

              • content: string or array of BetaContentBlockSourceContent

                • string

                • BetaContentBlockSourceContent = array of BetaContentBlockSourceContent

                  • BetaTextBlockParam object { text, type, cache_control, citations }

                  • BetaImageBlockParam object { source, type, cache_control }

              • type: "content"

                • "content"

            • BetaURLPDFSource object { type, url }

              • type: "url"

                • "url"

              • url: string

            • BetaFileDocumentSource object { file_id, type }

              • file_id: string

              • type: "file"

                • "file"

          • type: "document"

            • "document"

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

          • citations: optional BetaCitationsConfigParam

            • enabled: optional boolean

          • context: optional string

          • title: optional string

        • BetaSearchResultBlockParam object { content, source, title, 3 more }

          • content: array of BetaTextBlockParam

            • text: string

            • type: "text"

            • cache_control: optional BetaCacheControlEphemeral

              Create a cache control breakpoint at this content block.

            • citations: optional array of BetaTextCitationParam

          • source: string

          • title: string

          • type: "search_result"

            • "search_result"

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

          • citations: optional BetaCitationsConfigParam

        • BetaThinkingBlockParam object { signature, thinking, type }

          • signature: string

          • thinking: string

          • type: "thinking"

            • "thinking"

        • BetaRedactedThinkingBlockParam object { data, type }

          • data: string

          • type: "redacted_thinking"

            • "redacted_thinking"

        • BetaToolUseBlockParam object { id, input, name, 3 more }

          • id: string

          • input: map[unknown]

          • name: string

          • type: "tool_use"

            • "tool_use"

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

          • caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

            Tool invocation directly from the model.

            • BetaDirectCaller object { type }

              Tool invocation directly from the model.

              • type: "direct"

                • "direct"

            • BetaServerToolCaller object { tool_id, type }

              Tool invocation generated by a server-side tool.

              • tool_id: string

              • type: "code_execution_20250825"

                • "code_execution_20250825"

            • BetaServerToolCaller20260120 object { tool_id, type }

              • tool_id: string

              • type: "code_execution_20260120"

                • "code_execution_20260120"

        • BetaToolResultBlockParam object { tool_use_id, type, cache_control, 2 more }

          • tool_use_id: string

          • type: "tool_result"

            • "tool_result"

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

          • content: optional string or array of BetaTextBlockParam or BetaImageBlockParam or BetaSearchResultBlockParam or 2 more

            • string

            • array of BetaTextBlockParam or BetaImageBlockParam or BetaSearchResultBlockParam or 2 more

              • BetaTextBlockParam object { text, type, cache_control, citations }

              • BetaImageBlockParam object { source, type, cache_control }

              • BetaSearchResultBlockParam object { content, source, title, 3 more }

              • BetaRequestDocumentBlock object { source, type, cache_control, 3 more }

              • BetaToolReferenceBlockParam object { tool_name, type, cache_control }

                Tool reference block that can be included in tool_result content.

                • tool_name: string

                • type: "tool_reference"

                  • "tool_reference"

                • cache_control: optional BetaCacheControlEphemeral

                  Create a cache control breakpoint at this content block.

          • is_error: optional boolean

        • BetaServerToolUseBlockParam object { id, input, name, 3 more }

          • id: string

          • input: map[unknown]

          • name: "advisor" or "web_search" or "web_fetch" or 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: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

          • caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

            Tool invocation directly from the model.

            • BetaDirectCaller object { type }

              Tool invocation directly from the model.

            • BetaServerToolCaller object { tool_id, type }

              Tool invocation generated by a server-side tool.

            • BetaServerToolCaller20260120 object { tool_id, type }

        • BetaWebSearchToolResultBlockParam object { content, tool_use_id, type, 2 more }

          • content: BetaWebSearchToolResultBlockParamContent

            • ResultBlock = array of BetaWebSearchResultBlockParam

              • encrypted_content: string

              • title: string

              • type: "web_search_result"

                • "web_search_result"

              • url: string

              • page_age: optional string

            • BetaWebSearchToolRequestError object { error_code, type }

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

            Create a cache control breakpoint at this content block.

          • caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

            Tool invocation directly from the model.

            • BetaDirectCaller object { type }

              Tool invocation directly from the model.

            • BetaServerToolCaller object { tool_id, type }

              Tool invocation generated by a server-side tool.

            • BetaServerToolCaller20260120 object { tool_id, type }

        • BetaWebFetchToolResultBlockParam object { content, tool_use_id, type, 2 more }

          • content: BetaWebFetchToolResultErrorBlockParam or BetaWebFetchBlockParam

            • BetaWebFetchToolResultErrorBlockParam object { error_code, type }

              • error_code: BetaWebFetchToolResultErrorCode

                • "invalid_tool_input"

                • "url_too_long"

                • "url_not_allowed"

                • "url_not_accessible"

                • "unsupported_content_type"

                • "too_many_requests"

                • "max_uses_exceeded"

                • "unavailable"

              • type: "web_fetch_tool_result_error"

                • "web_fetch_tool_result_error"

            • BetaWebFetchBlockParam object { content, type, url, retrieved_at }

              • content: BetaRequestDocumentBlock

              • type: "web_fetch_result"

                • "web_fetch_result"

              • url: string

                Fetched content URL

              • retrieved_at: optional string

                ISO 8601 timestamp when the content was retrieved

          • tool_use_id: string

          • type: "web_fetch_tool_result"

            • "web_fetch_tool_result"

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

          • caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

            Tool invocation directly from the model.

            • BetaDirectCaller object { type }

              Tool invocation directly from the model.

            • BetaServerToolCaller object { tool_id, type }

              Tool invocation generated by a server-side tool.

            • BetaServerToolCaller20260120 object { tool_id, type }

        • BetaAdvisorToolResultBlockParam object { content, tool_use_id, type, cache_control }

          • content: BetaAdvisorToolResultErrorParam or BetaAdvisorResultBlockParam or BetaAdvisorRedactedResultBlockParam

            • BetaAdvisorToolResultErrorParam object { error_code, type }

              • error_code: "max_uses_exceeded" or "prompt_too_long" or "too_many_requests" or 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 object { text, type }

              • text: string

              • type: "advisor_result"

                • "advisor_result"

            • BetaAdvisorRedactedResultBlockParam object { encrypted_content, type }

              • encrypted_content: string

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

              • type: "advisor_redacted_result"

                • "advisor_redacted_result"

          • tool_use_id: string

          • type: "advisor_tool_result"

            • "advisor_tool_result"

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

        • BetaCodeExecutionToolResultBlockParam object { content, tool_use_id, type, cache_control }

          • content: BetaCodeExecutionToolResultBlockParamContent

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

            • BetaCodeExecutionToolResultErrorParam object { error_code, type }

              • 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 object { content, return_code, stderr, 2 more }

              • content: array of BetaCodeExecutionOutputBlockParam

                • 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 object { content, encrypted_stdout, return_code, 2 more }

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

              • content: array of BetaCodeExecutionOutputBlockParam

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

            Create a cache control breakpoint at this content block.

        • BetaBashCodeExecutionToolResultBlockParam object { content, tool_use_id, type, cache_control }

          • content: BetaBashCodeExecutionToolResultErrorParam or BetaBashCodeExecutionResultBlockParam

            • BetaBashCodeExecutionToolResultErrorParam object { error_code, type }

              • error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 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 object { content, return_code, stderr, 2 more }

              • content: array of BetaBashCodeExecutionOutputBlockParam

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

            Create a cache control breakpoint at this content block.

        • BetaTextEditorCodeExecutionToolResultBlockParam object { content, tool_use_id, type, cache_control }

          • content: BetaTextEditorCodeExecutionToolResultErrorParam or BetaTextEditorCodeExecutionViewResultBlockParam or BetaTextEditorCodeExecutionCreateResultBlockParam or BetaTextEditorCodeExecutionStrReplaceResultBlockParam

            • BetaTextEditorCodeExecutionToolResultErrorParam object { error_code, type, error_message }

              • error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 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: optional string

            • BetaTextEditorCodeExecutionViewResultBlockParam object { content, file_type, type, 3 more }

              • content: string

              • file_type: "text" or "image" or "pdf"

                • "text"

                • "image"

                • "pdf"

              • type: "text_editor_code_execution_view_result"

                • "text_editor_code_execution_view_result"

              • num_lines: optional number

              • start_line: optional number

              • total_lines: optional number

            • BetaTextEditorCodeExecutionCreateResultBlockParam object { is_file_update, type }

              • is_file_update: boolean

              • type: "text_editor_code_execution_create_result"

                • "text_editor_code_execution_create_result"

            • BetaTextEditorCodeExecutionStrReplaceResultBlockParam object { type, lines, new_lines, 3 more }

              • type: "text_editor_code_execution_str_replace_result"

                • "text_editor_code_execution_str_replace_result"

              • lines: optional array of string

              • new_lines: optional number

              • new_start: optional number

              • old_lines: optional number

              • old_start: optional number

          • tool_use_id: string

          • type: "text_editor_code_execution_tool_result"

            • "text_editor_code_execution_tool_result"

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

        • BetaToolSearchToolResultBlockParam object { content, tool_use_id, type, cache_control }

          • content: BetaToolSearchToolResultErrorParam or BetaToolSearchToolSearchResultBlockParam

            • BetaToolSearchToolResultErrorParam object { error_code, type }

              • error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "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 object { tool_references, type }

              • tool_references: array of BetaToolReferenceBlockParam

                • tool_name: string

                • type: "tool_reference"

                • cache_control: optional BetaCacheControlEphemeral

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

            Create a cache control breakpoint at this content block.

        • BetaMCPToolUseBlockParam object { id, input, name, 3 more }

          • id: string

          • input: map[unknown]

          • name: string

          • server_name: string

            The name of the MCP server

          • type: "mcp_tool_use"

            • "mcp_tool_use"

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

        • BetaRequestMCPToolResultBlockParam object { tool_use_id, type, cache_control, 2 more }

          • tool_use_id: string

          • type: "mcp_tool_result"

            • "mcp_tool_result"

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

          • content: optional string or array of BetaTextBlockParam

            • string

            • BetaMCPToolResultBlockParamContent = array of BetaTextBlockParam

              • text: string

              • type: "text"

              • cache_control: optional BetaCacheControlEphemeral

                Create a cache control breakpoint at this content block.

              • citations: optional array of BetaTextCitationParam

          • is_error: optional boolean

        • BetaContainerUploadBlockParam object { file_id, type, cache_control }

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

          • file_id: string

          • type: "container_upload"

            • "container_upload"

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

        • BetaCompactionBlockParam object { content, type, cache_control, encrypted_content }

          A compaction block containing summary of previous context.

          Users should round-trip these blocks from responses to subsequent requests to maintain context across compaction boundaries.

          When content is None, the block represents a failed compaction. The server treats these as no-ops. Empty string content is not allowed.

          • content: string

            Summary of previously compacted content, or null if compaction failed

          • type: "compaction"

            • "compaction"

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

          • encrypted_content: optional string

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

    • role: "user" or "assistant"

      • "user"

      • "assistant"

  • model: Model

    The model that will complete your prompt.

    See models for additional details and options.

    • "claude-opus-4-7" or "claude-mythos-preview" or "claude-opus-4-6" or 14 more

      The model that will complete your prompt.

      See models for additional details and options.

      • "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: optional BetaCacheControlEphemeral

    Top-level cache control automatically applies a cache_control marker to the last cacheable block in the request.

  • context_management: optional BetaContextManagementConfig

    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: optional array of BetaClearToolUses20250919Edit or BetaClearThinking20251015Edit or BetaCompact20260112Edit

      List of context management edits to apply

      • BetaClearToolUses20250919Edit object { type, clear_at_least, clear_tool_inputs, 3 more }

        • type: "clear_tool_uses_20250919"

          • "clear_tool_uses_20250919"

        • clear_at_least: optional BetaInputTokensClearAtLeast

          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: optional boolean or array of string

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

          • boolean

          • array of string

        • exclude_tools: optional array of string

          Tool names whose uses are preserved from clearing

        • keep: optional BetaToolUsesKeep

          Number of tool uses to retain in the conversation

          • type: "tool_uses"

            • "tool_uses"

          • value: number

        • trigger: optional BetaInputTokensTrigger or BetaToolUsesTrigger

          Condition that triggers the context management strategy

          • BetaInputTokensTrigger object { type, value }

            • type: "input_tokens"

              • "input_tokens"

            • value: number

          • BetaToolUsesTrigger object { type, value }

            • type: "tool_uses"

              • "tool_uses"

            • value: number

      • BetaClearThinking20251015Edit object { type, keep }

        • type: "clear_thinking_20251015"

          • "clear_thinking_20251015"

        • keep: optional BetaThinkingTurns or BetaAllThinkingTurns or "all"

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

          • BetaThinkingTurns object { type, value }

            • type: "thinking_turns"

              • "thinking_turns"

            • value: number

          • BetaAllThinkingTurns object { type }

            • type: "all"

              • "all"

          • "all"

            • "all"

      • BetaCompact20260112Edit object { type, instructions, pause_after_compaction, trigger }

        Automatically compact older context when reaching the configured trigger threshold.

        • type: "compact_20260112"

          • "compact_20260112"

        • instructions: optional string

          Additional instructions for summarization.

        • pause_after_compaction: optional boolean

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

        • trigger: optional BetaInputTokensTrigger

          When to trigger compaction. Defaults to 150000 input tokens.

  • mcp_servers: optional array of BetaRequestMCPServerURLDefinition

    MCP servers to be utilized in this request

    • name: string

    • type: "url"

      • "url"

    • url: string

    • authorization_token: optional string

    • tool_configuration: optional BetaRequestMCPServerToolConfiguration

      • allowed_tools: optional array of string

      • enabled: optional boolean

  • output_config: optional BetaOutputConfig

    Configuration options for the model's output, such as the output format.

    • effort: optional "low" or "medium" or "high" or 2 more

      All possible effort levels.

      • "low"

      • "medium"

      • "high"

      • "xhigh"

      • "max"

    • format: optional BetaJSONOutputFormat

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

      • schema: map[unknown]

        The JSON schema of the format

      • type: "json_schema"

        • "json_schema"

    • task_budget: optional 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: optional number

        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: optional BetaJSONOutputFormat

    Deprecated: Use output_config.format instead. See structured outputs

    A schema to specify Claude's output format in responses. This parameter will be removed in a future release.

  • speed: optional "standard" or "fast"

    The inference speed mode for this request. "fast" enables high output-tokens-per-second inference.

    • "standard"

    • "fast"

  • system: optional string or array of BetaTextBlockParam

    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.

    • string

    • array of BetaTextBlockParam

      • text: string

      • type: "text"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • citations: optional array of BetaTextCitationParam

  • thinking: optional 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 for details.

    • BetaThinkingConfigEnabled object { budget_tokens, type, display }

      • 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 for details.

      • type: "enabled"

        • "enabled"

      • display: optional "summarized" or "omitted"

        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 object { type }

      • type: "disabled"

        • "disabled"

    • BetaThinkingConfigAdaptive object { type, display }

      • type: "adaptive"

        • "adaptive"

      • display: optional "summarized" or "omitted"

        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: optional 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 object { type, disable_parallel_tool_use }

      The model will automatically decide whether to use tools.

      • type: "auto"

        • "auto"

      • disable_parallel_tool_use: optional boolean

        Whether to disable parallel tool use.

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

    • BetaToolChoiceAny object { type, disable_parallel_tool_use }

      The model will use any available tools.

      • type: "any"

        • "any"

      • disable_parallel_tool_use: optional boolean

        Whether to disable parallel tool use.

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

    • BetaToolChoiceTool object { name, type, disable_parallel_tool_use }

      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: optional boolean

        Whether to disable parallel tool use.

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

    • BetaToolChoiceNone object { type }

      The model will not be allowed to use tools.

      • type: "none"

        • "none"

  • tools: optional array of BetaTool or BetaToolBash20241022 or BetaToolBash20250124 or 20 more

    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, see their individual documentation as each has its own behavior (e.g., the 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 for the tool input shape that the model will produce in tool_use output content blocks.

    For example, if you defined tools as:

    [
  {
    "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:

    [
  {
    "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:

    [
  {
    "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 for more details.

    • BetaTool object { input_schema, name, allowed_callers, 7 more }

      • input_schema: object { type, properties, required }

        JSON schema for this tool's input.

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

        • type: "object"

          • "object"

        • properties: optional map[unknown]

        • required: optional array of string

      • name: string

        Name of the tool.

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

      • allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

        • "direct"

        • "code_execution_20250825"

        • "code_execution_20260120"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • defer_loading: optional boolean

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

      • description: optional 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: optional boolean

        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: optional array of map[unknown]

      • strict: optional boolean

        When true, guarantees schema validation on tool names and inputs

      • type: optional "custom"

        • "custom"

    • BetaToolBash20241022 object { name, type, allowed_callers, 4 more }

      • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

        • "direct"

        • "code_execution_20250825"

        • "code_execution_20260120"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • defer_loading: optional boolean

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

      • input_examples: optional array of map[unknown]

      • strict: optional boolean

        When true, guarantees schema validation on tool names and inputs

    • BetaToolBash20250124 object { name, type, allowed_callers, 4 more }

      • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

        • "direct"

        • "code_execution_20250825"

        • "code_execution_20260120"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • defer_loading: optional boolean

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

      • input_examples: optional array of map[unknown]

      • strict: optional boolean

        When true, guarantees schema validation on tool names and inputs

    • BetaCodeExecutionTool20250522 object { name, type, allowed_callers, 3 more }

      • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

        • "direct"

        • "code_execution_20250825"

        • "code_execution_20260120"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • defer_loading: optional boolean

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

      • strict: optional boolean

        When true, guarantees schema validation on tool names and inputs

    • BetaCodeExecutionTool20250825 object { name, type, allowed_callers, 3 more }

      • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

        • "direct"

        • "code_execution_20250825"

        • "code_execution_20260120"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • defer_loading: optional boolean

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

      • strict: optional boolean

        When true, guarantees schema validation on tool names and inputs

    • BetaCodeExecutionTool20260120 object { name, type, allowed_callers, 3 more }

      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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

        • "direct"

        • "code_execution_20250825"

        • "code_execution_20260120"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • defer_loading: optional boolean

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

      • strict: optional boolean

        When true, guarantees schema validation on tool names and inputs

    • BetaToolComputerUse20241022 object { display_height_px, display_width_px, name, 7 more }

      • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

        • "direct"

        • "code_execution_20250825"

        • "code_execution_20260120"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • defer_loading: optional boolean

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

      • display_number: optional number

        The X11 display number (e.g. 0, 1) for the display.

      • input_examples: optional array of map[unknown]

      • strict: optional boolean

        When true, guarantees schema validation on tool names and inputs

    • BetaMemoryTool20250818 object { name, type, allowed_callers, 4 more }

      • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

        • "direct"

        • "code_execution_20250825"

        • "code_execution_20260120"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • defer_loading: optional boolean

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

      • input_examples: optional array of map[unknown]

      • strict: optional boolean

        When true, guarantees schema validation on tool names and inputs

    • BetaToolComputerUse20250124 object { display_height_px, display_width_px, name, 7 more }

      • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

        • "direct"

        • "code_execution_20250825"

        • "code_execution_20260120"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • defer_loading: optional boolean

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

      • display_number: optional number

        The X11 display number (e.g. 0, 1) for the display.

      • input_examples: optional array of map[unknown]

      • strict: optional boolean

        When true, guarantees schema validation on tool names and inputs

    • BetaToolTextEditor20241022 object { name, type, allowed_callers, 4 more }

      • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

        • "direct"

        • "code_execution_20250825"

        • "code_execution_20260120"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • defer_loading: optional boolean

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

      • input_examples: optional array of map[unknown]

      • strict: optional boolean

        When true, guarantees schema validation on tool names and inputs

    • BetaToolComputerUse20251124 object { display_height_px, display_width_px, name, 8 more }

      • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

        • "direct"

        • "code_execution_20250825"

        • "code_execution_20260120"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • defer_loading: optional boolean

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

      • display_number: optional number

        The X11 display number (e.g. 0, 1) for the display.

      • enable_zoom: optional boolean

        Whether to enable an action to take a zoomed-in screenshot of the screen.

      • input_examples: optional array of map[unknown]

      • strict: optional boolean

        When true, guarantees schema validation on tool names and inputs

    • BetaToolTextEditor20250124 object { name, type, allowed_callers, 4 more }

      • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

        • "direct"

        • "code_execution_20250825"

        • "code_execution_20260120"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • defer_loading: optional boolean

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

      • input_examples: optional array of map[unknown]

      • strict: optional boolean

        When true, guarantees schema validation on tool names and inputs

    • BetaToolTextEditor20250429 object { name, type, allowed_callers, 4 more }

      • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

        • "direct"

        • "code_execution_20250825"

        • "code_execution_20260120"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • defer_loading: optional boolean

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

      • input_examples: optional array of map[unknown]

      • strict: optional boolean

        When true, guarantees schema validation on tool names and inputs

    • BetaToolTextEditor20250728 object { name, type, allowed_callers, 5 more }

      • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

        • "direct"

        • "code_execution_20250825"

        • "code_execution_20260120"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • defer_loading: optional boolean

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

      • input_examples: optional array of map[unknown]

      • max_characters: optional number

        Maximum number of characters to display when viewing a file. If not specified, defaults to displaying the full file.

      • strict: optional boolean

        When true, guarantees schema validation on tool names and inputs

    • BetaWebSearchTool20250305 object { name, type, allowed_callers, 7 more }

      • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

        • "direct"

        • "code_execution_20250825"

        • "code_execution_20260120"

      • allowed_domains: optional array of string

        If provided, only these domains will be included in results. Cannot be used alongside blocked_domains.

      • blocked_domains: optional array of string

        If provided, these domains will never appear in results. Cannot be used alongside allowed_domains.

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • defer_loading: optional boolean

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

      • max_uses: optional number

        Maximum number of times the tool can be used in the API request.

      • strict: optional boolean

        When true, guarantees schema validation on tool names and inputs

      • user_location: optional BetaUserLocation

        Parameters for the user's location. Used to provide more relevant search results.

        • type: "approximate"

          • "approximate"

        • city: optional string

          The city of the user.

        • country: optional string

          The two letter ISO country code of the user.

        • region: optional string

          The region of the user.

        • timezone: optional string

          The IANA timezone of the user.

    • BetaWebFetchTool20250910 object { name, type, allowed_callers, 8 more }

      • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

        • "direct"

        • "code_execution_20250825"

        • "code_execution_20260120"

      • allowed_domains: optional array of string

        List of domains to allow fetching from

      • blocked_domains: optional array of string

        List of domains to block fetching from

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • citations: optional BetaCitationsConfigParam

        Citations configuration for fetched documents. Citations are disabled by default.

      • defer_loading: optional 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: optional number

        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: optional number

        Maximum number of times the tool can be used in the API request.

      • strict: optional boolean

        When true, guarantees schema validation on tool names and inputs

    • BetaWebSearchTool20260209 object { name, type, allowed_callers, 7 more }

      • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

        • "direct"

        • "code_execution_20250825"

        • "code_execution_20260120"

      • allowed_domains: optional array of string

        If provided, only these domains will be included in results. Cannot be used alongside blocked_domains.

      • blocked_domains: optional array of string

        If provided, these domains will never appear in results. Cannot be used alongside allowed_domains.

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • defer_loading: optional boolean

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

      • max_uses: optional number

        Maximum number of times the tool can be used in the API request.

      • strict: optional boolean

        When true, guarantees schema validation on tool names and inputs

      • user_location: optional BetaUserLocation

        Parameters for the user's location. Used to provide more relevant search results.

    • BetaWebFetchTool20260209 object { name, type, allowed_callers, 8 more }

      • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

        • "direct"

        • "code_execution_20250825"

        • "code_execution_20260120"

      • allowed_domains: optional array of string

        List of domains to allow fetching from

      • blocked_domains: optional array of string

        List of domains to block fetching from

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • citations: optional BetaCitationsConfigParam

        Citations configuration for fetched documents. Citations are disabled by default.

      • defer_loading: optional 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: optional number

        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: optional number

        Maximum number of times the tool can be used in the API request.

      • strict: optional boolean

        When true, guarantees schema validation on tool names and inputs

    • BetaWebFetchTool20260309 object { name, type, allowed_callers, 9 more }

      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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

        • "direct"

        • "code_execution_20250825"

        • "code_execution_20260120"

      • allowed_domains: optional array of string

        List of domains to allow fetching from

      • blocked_domains: optional array of string

        List of domains to block fetching from

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • citations: optional BetaCitationsConfigParam

        Citations configuration for fetched documents. Citations are disabled by default.

      • defer_loading: optional 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: optional number

        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: optional number

        Maximum number of times the tool can be used in the API request.

      • strict: optional boolean

        When true, guarantees schema validation on tool names and inputs

      • use_cache: optional 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 object { model, name, type, 6 more }

      • model: Model

        The model that will complete your prompt.

        See models 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

        • "direct"

        • "code_execution_20250825"

        • "code_execution_20260120"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • caching: optional BetaCacheControlEphemeral

        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: optional boolean

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

      • max_uses: optional number

        Maximum number of times the tool can be used in the API request.

      • strict: optional boolean

        When true, guarantees schema validation on tool names and inputs

    • BetaToolSearchToolBm25_20251119 object { name, type, allowed_callers, 3 more }

      • 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" or "tool_search_tool_bm25"

        • "tool_search_tool_bm25_20251119"

        • "tool_search_tool_bm25"

      • allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

        • "direct"

        • "code_execution_20250825"

        • "code_execution_20260120"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • defer_loading: optional boolean

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

      • strict: optional boolean

        When true, guarantees schema validation on tool names and inputs

    • BetaToolSearchToolRegex20251119 object { name, type, allowed_callers, 3 more }

      • 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" or "tool_search_tool_regex"

        • "tool_search_tool_regex_20251119"

        • "tool_search_tool_regex"

      • allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

        • "direct"

        • "code_execution_20250825"

        • "code_execution_20260120"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • defer_loading: optional boolean

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

      • strict: optional boolean

        When true, guarantees schema validation on tool names and inputs

    • BetaMCPToolset object { mcp_server_name, type, cache_control, 2 more }

      Configuration for a group of tools from an MCP server.

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

      • mcp_server_name: string

        Name of the MCP server to configure tools for

      • type: "mcp_toolset"

        • "mcp_toolset"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • configs: optional map[BetaMCPToolConfig]

        Configuration overrides for specific tools, keyed by tool name

        • defer_loading: optional boolean

        • enabled: optional boolean

      • default_config: optional BetaMCPToolDefaultConfig

        Default configuration applied to all tools from this server

        • defer_loading: optional boolean

        • enabled: optional boolean

Returns

  • BetaMessageTokensCount object { context_management, input_tokens }

    • context_management: BetaCountTokensContextManagementResponse

      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

curl https://api.anthropic.com/v1/messages/count_tokens \
    -H 'Content-Type: application/json' \
    -H 'anthropic-version: 2023-06-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY" \
    -d "{
          \"messages\": [
            {
              \"content\": \"Hello, world\",
              \"role\": \"user\"
            }
          ],
          \"model\": \"claude-opus-4-6\",
          \"system\": [
            {
              \"text\": \"Today's date is 2024-06-01.\",
              \"type\": \"text\"
            }
          ],
          \"thinking\": {
            \"type\": \"adaptive\"
          },
          \"tools\": [
            {
              \"input_schema\": {
                \"type\": \"object\",
                \"properties\": {
                  \"location\": \"bar\",
                  \"unit\": \"bar\"
                },
                \"required\": [
                  \"location\"
                ]
              },
              \"name\": \"name\"
            }
          ]
        }"

Response

{
  "context_management": {
    "original_input_tokens": 0
  },
  "input_tokens": 2095
}

Domain Types

Beta Advisor Message Iteration Usage

  • BetaAdvisorMessageIterationUsage object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 4 more }

    Token usage for an advisor sub-inference iteration.

    • cache_creation: BetaCacheCreation

      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 for additional details and options.

      • "claude-opus-4-7" or "claude-mythos-preview" or "claude-opus-4-6" or 14 more

        The model that will complete your prompt.

        See models for additional details and options.

        • "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 object { encrypted_content, type }

    • encrypted_content: string

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

    • type: "advisor_redacted_result"

      • "advisor_redacted_result"

Beta Advisor Redacted Result Block Param

  • BetaAdvisorRedactedResultBlockParam object { encrypted_content, type }

    • encrypted_content: string

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

    • type: "advisor_redacted_result"

      • "advisor_redacted_result"

Beta Advisor Result Block

  • BetaAdvisorResultBlock object { text, type }

    • text: string

    • type: "advisor_result"

      • "advisor_result"

Beta Advisor Result Block Param

  • BetaAdvisorResultBlockParam object { text, type }

    • text: string

    • type: "advisor_result"

      • "advisor_result"

Beta Advisor Tool 20260301

  • BetaAdvisorTool20260301 object { model, name, type, 6 more }

    • model: Model

      The model that will complete your prompt.

      See models for additional details and options.

      • "claude-opus-4-7" or "claude-mythos-preview" or "claude-opus-4-6" or 14 more

        The model that will complete your prompt.

        See models for additional details and options.

        • "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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

      • "direct"

      • "code_execution_20250825"

      • "code_execution_20260120"

    • cache_control: optional BetaCacheControlEphemeral

      Create a cache control breakpoint at this content block.

      • type: "ephemeral"

        • "ephemeral"

      • ttl: optional "5m" or "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: optional BetaCacheControlEphemeral

      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: optional boolean

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

    • max_uses: optional number

      Maximum number of times the tool can be used in the API request.

    • strict: optional boolean

      When true, guarantees schema validation on tool names and inputs

Beta Advisor Tool Result Block

  • BetaAdvisorToolResultBlock object { content, tool_use_id, type }

    • content: BetaAdvisorToolResultError or BetaAdvisorResultBlock or BetaAdvisorRedactedResultBlock

      • BetaAdvisorToolResultError object { error_code, type }

        • error_code: "max_uses_exceeded" or "prompt_too_long" or "too_many_requests" or 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 object { text, type }

        • text: string

        • type: "advisor_result"

          • "advisor_result"

      • BetaAdvisorRedactedResultBlock object { encrypted_content, type }

        • encrypted_content: string

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

        • 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 object { content, tool_use_id, type, cache_control }

    • content: BetaAdvisorToolResultErrorParam or BetaAdvisorResultBlockParam or BetaAdvisorRedactedResultBlockParam

      • BetaAdvisorToolResultErrorParam object { error_code, type }

        • error_code: "max_uses_exceeded" or "prompt_too_long" or "too_many_requests" or 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 object { text, type }

        • text: string

        • type: "advisor_result"

          • "advisor_result"

      • BetaAdvisorRedactedResultBlockParam object { encrypted_content, type }

        • encrypted_content: string

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

        • type: "advisor_redacted_result"

          • "advisor_redacted_result"

    • tool_use_id: string

    • type: "advisor_tool_result"

      • "advisor_tool_result"

    • cache_control: optional BetaCacheControlEphemeral

      Create a cache control breakpoint at this content block.

      • type: "ephemeral"

        • "ephemeral"

      • ttl: optional "5m" or "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 object { error_code, type }

    • error_code: "max_uses_exceeded" or "prompt_too_long" or "too_many_requests" or 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 object { error_code, type }

    • error_code: "max_uses_exceeded" or "prompt_too_long" or "too_many_requests" or 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 object { type }

    • type: "all"

      • "all"

Beta Base64 Image Source

  • BetaBase64ImageSource object { data, media_type, type }

    • data: string

    • media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"

      • "image/jpeg"

      • "image/png"

      • "image/gif"

      • "image/webp"

    • type: "base64"

      • "base64"

Beta Base64 PDF Source

  • BetaBase64PDFSource object { data, media_type, type }

    • data: string

    • media_type: "application/pdf"

      • "application/pdf"

    • type: "base64"

      • "base64"

Beta Bash Code Execution Output Block

  • BetaBashCodeExecutionOutputBlock object { file_id, type }

    • file_id: string

    • type: "bash_code_execution_output"

      • "bash_code_execution_output"

Beta Bash Code Execution Output Block Param

  • BetaBashCodeExecutionOutputBlockParam object { file_id, type }

    • file_id: string

    • type: "bash_code_execution_output"

      • "bash_code_execution_output"

Beta Bash Code Execution Result Block

  • BetaBashCodeExecutionResultBlock object { content, return_code, stderr, 2 more }

    • content: array of BetaBashCodeExecutionOutputBlock

      • 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 object { content, return_code, stderr, 2 more }

    • content: array of BetaBashCodeExecutionOutputBlockParam

      • 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 object { content, tool_use_id, type }

    • content: BetaBashCodeExecutionToolResultError or BetaBashCodeExecutionResultBlock

      • BetaBashCodeExecutionToolResultError object { error_code, type }

        • error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 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 object { content, return_code, stderr, 2 more }

        • content: array of BetaBashCodeExecutionOutputBlock

          • 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 object { content, tool_use_id, type, cache_control }

    • content: BetaBashCodeExecutionToolResultErrorParam or BetaBashCodeExecutionResultBlockParam

      • BetaBashCodeExecutionToolResultErrorParam object { error_code, type }

        • error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 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 object { content, return_code, stderr, 2 more }

        • content: array of BetaBashCodeExecutionOutputBlockParam

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

      Create a cache control breakpoint at this content block.

      • type: "ephemeral"

        • "ephemeral"

      • ttl: optional "5m" or "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 object { error_code, type }

    • error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 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 object { error_code, type }

    • error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 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 object { type, ttl }

    • type: "ephemeral"

      • "ephemeral"

    • ttl: optional "5m" or "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 object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }

    • ephemeral_1h_input_tokens: number

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

    • ephemeral_5m_input_tokens: number

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

Beta Cache Miss Messages Changed

  • BetaCacheMissMessagesChanged object { cache_missed_input_tokens, type }

    • 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 object { cache_missed_input_tokens, type }

    • 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 object { type }

    • type: "previous_message_not_found"

      • "previous_message_not_found"

Beta Cache Miss System Changed

  • BetaCacheMissSystemChanged object { cache_missed_input_tokens, type }

    • 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 object { cache_missed_input_tokens, type }

    • 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 object { type }

    • type: "unavailable"

      • "unavailable"

Beta Citation Char Location

  • BetaCitationCharLocation object { cited_text, document_index, document_title, 4 more }

    • cited_text: string

    • document_index: number

    • document_title: string

    • end_char_index: number

    • file_id: string

    • start_char_index: number

    • type: "char_location"

      • "char_location"

Beta Citation Char Location Param

  • BetaCitationCharLocationParam object { cited_text, document_index, document_title, 3 more }

    • cited_text: string

    • document_index: number

    • document_title: string

    • end_char_index: number

    • start_char_index: number

    • type: "char_location"

      • "char_location"

Beta Citation Config

  • BetaCitationConfig object { enabled }

    • enabled: boolean

Beta Citation Content Block Location

  • BetaCitationContentBlockLocation object { cited_text, document_index, document_title, 4 more }

    • 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

    • 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

    • 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 object { cited_text, document_index, document_title, 3 more }

    • 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

    • 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 object { cited_text, document_index, document_title, 4 more }

    • cited_text: string

    • document_index: number

    • document_title: string

    • end_page_number: number

    • file_id: string

    • start_page_number: number

    • type: "page_location"

      • "page_location"

Beta Citation Page Location Param

  • BetaCitationPageLocationParam object { cited_text, document_index, document_title, 3 more }

    • cited_text: string

    • document_index: number

    • document_title: string

    • end_page_number: number

    • start_page_number: number

    • type: "page_location"

      • "page_location"

Beta Citation Search Result Location

  • BetaCitationSearchResultLocation object { cited_text, end_block_index, search_result_index, 4 more }

    • 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

    • type: "search_result_location"

      • "search_result_location"

Beta Citation Search Result Location Param

  • BetaCitationSearchResultLocationParam object { cited_text, end_block_index, search_result_index, 4 more }

    • 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

    • type: "search_result_location"

      • "search_result_location"

Beta Citation Web Search Result Location Param

  • BetaCitationWebSearchResultLocationParam object { cited_text, encrypted_index, title, 2 more }

    • cited_text: string

    • encrypted_index: string

    • title: string

    • type: "web_search_result_location"

      • "web_search_result_location"

    • url: string

Beta Citations Config Param

  • BetaCitationsConfigParam object { enabled }

    • enabled: optional boolean

Beta Citations Delta

  • BetaCitationsDelta object { citation, type }

    • citation: BetaCitationCharLocation or BetaCitationPageLocation or BetaCitationContentBlockLocation or 2 more

      • BetaCitationCharLocation object { cited_text, document_index, document_title, 4 more }

        • cited_text: string

        • document_index: number

        • document_title: string

        • end_char_index: number

        • file_id: string

        • start_char_index: number

        • type: "char_location"

          • "char_location"

      • BetaCitationPageLocation object { cited_text, document_index, document_title, 4 more }

        • cited_text: string

        • document_index: number

        • document_title: string

        • end_page_number: number

        • file_id: string

        • start_page_number: number

        • type: "page_location"

          • "page_location"

      • BetaCitationContentBlockLocation object { cited_text, document_index, document_title, 4 more }

        • 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

        • 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

        • 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 object { cited_text, encrypted_index, title, 2 more }

        • cited_text: string

        • encrypted_index: string

        • title: string

        • type: "web_search_result_location"

          • "web_search_result_location"

        • url: string

      • BetaCitationSearchResultLocation object { cited_text, end_block_index, search_result_index, 4 more }

        • 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

        • type: "search_result_location"

          • "search_result_location"

    • type: "citations_delta"

      • "citations_delta"

Beta Citations Web Search Result Location

  • BetaCitationsWebSearchResultLocation object { cited_text, encrypted_index, title, 2 more }

    • cited_text: string

    • encrypted_index: string

    • title: string

    • type: "web_search_result_location"

      • "web_search_result_location"

    • url: string

Beta Clear Thinking 20251015 Edit

  • BetaClearThinking20251015Edit object { type, keep }

    • type: "clear_thinking_20251015"

      • "clear_thinking_20251015"

    • keep: optional BetaThinkingTurns or BetaAllThinkingTurns or "all"

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

      • BetaThinkingTurns object { type, value }

        • type: "thinking_turns"

          • "thinking_turns"

        • value: number

      • BetaAllThinkingTurns object { type }

        • type: "all"

          • "all"

      • "all"

        • "all"

Beta Clear Thinking 20251015 Edit Response

  • BetaClearThinking20251015EditResponse object { cleared_input_tokens, cleared_thinking_turns, type }

    • cleared_input_tokens: number

      Number of input tokens cleared by this edit.

    • cleared_thinking_turns: number

      Number of thinking turns that were cleared.

    • type: "clear_thinking_20251015"

      The type of context management edit applied.

      • "clear_thinking_20251015"

Beta Clear Tool Uses 20250919 Edit

  • BetaClearToolUses20250919Edit object { type, clear_at_least, clear_tool_inputs, 3 more }

    • type: "clear_tool_uses_20250919"

      • "clear_tool_uses_20250919"

    • clear_at_least: optional BetaInputTokensClearAtLeast

      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: optional boolean or array of string

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

      • boolean

      • array of string

    • exclude_tools: optional array of string

      Tool names whose uses are preserved from clearing

    • keep: optional BetaToolUsesKeep

      Number of tool uses to retain in the conversation

      • type: "tool_uses"

        • "tool_uses"

      • value: number

    • trigger: optional BetaInputTokensTrigger or BetaToolUsesTrigger

      Condition that triggers the context management strategy

      • BetaInputTokensTrigger object { type, value }

        • type: "input_tokens"

          • "input_tokens"

        • value: number

      • BetaToolUsesTrigger object { type, value }

        • type: "tool_uses"

          • "tool_uses"

        • value: number

Beta Clear Tool Uses 20250919 Edit Response

  • BetaClearToolUses20250919EditResponse object { cleared_input_tokens, cleared_tool_uses, type }

    • cleared_input_tokens: number

      Number of input tokens cleared by this edit.

    • cleared_tool_uses: number

      Number of tool uses that were cleared.

    • type: "clear_tool_uses_20250919"

      The type of context management edit applied.

      • "clear_tool_uses_20250919"

Beta Code Execution Output Block

  • BetaCodeExecutionOutputBlock object { file_id, type }

    • file_id: string

    • type: "code_execution_output"

      • "code_execution_output"

Beta Code Execution Output Block Param

  • BetaCodeExecutionOutputBlockParam object { file_id, type }

    • file_id: string

    • type: "code_execution_output"

      • "code_execution_output"

Beta Code Execution Result Block

  • BetaCodeExecutionResultBlock object { content, return_code, stderr, 2 more }

    • content: array of BetaCodeExecutionOutputBlock

      • 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 object { content, return_code, stderr, 2 more }

    • content: array of BetaCodeExecutionOutputBlockParam

      • 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 object { name, type, allowed_callers, 3 more }

    • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

      • "direct"

      • "code_execution_20250825"

      • "code_execution_20260120"

    • cache_control: optional BetaCacheControlEphemeral

      Create a cache control breakpoint at this content block.

      • type: "ephemeral"

        • "ephemeral"

      • ttl: optional "5m" or "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: optional boolean

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

    • strict: optional boolean

      When true, guarantees schema validation on tool names and inputs

Beta Code Execution Tool 20250825

  • BetaCodeExecutionTool20250825 object { name, type, allowed_callers, 3 more }

    • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

      • "direct"

      • "code_execution_20250825"

      • "code_execution_20260120"

    • cache_control: optional BetaCacheControlEphemeral

      Create a cache control breakpoint at this content block.

      • type: "ephemeral"

        • "ephemeral"

      • ttl: optional "5m" or "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: optional boolean

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

    • strict: optional boolean

      When true, guarantees schema validation on tool names and inputs

Beta Code Execution Tool 20260120

  • BetaCodeExecutionTool20260120 object { name, type, allowed_callers, 3 more }

    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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

      • "direct"

      • "code_execution_20250825"

      • "code_execution_20260120"

    • cache_control: optional BetaCacheControlEphemeral

      Create a cache control breakpoint at this content block.

      • type: "ephemeral"

        • "ephemeral"

      • ttl: optional "5m" or "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: optional boolean

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

    • strict: optional boolean

      When true, guarantees schema validation on tool names and inputs

Beta Code Execution Tool Result Block

  • BetaCodeExecutionToolResultBlock object { content, tool_use_id, type }

    • content: BetaCodeExecutionToolResultBlockContent

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

      • BetaCodeExecutionToolResultError object { error_code, type }

        • 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 object { content, return_code, stderr, 2 more }

        • content: array of BetaCodeExecutionOutputBlock

          • 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 object { content, encrypted_stdout, return_code, 2 more }

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

        • content: array of BetaCodeExecutionOutputBlock

          • 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 or BetaCodeExecutionResultBlock or BetaEncryptedCodeExecutionResultBlock

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

    • BetaCodeExecutionToolResultError object { error_code, type }

      • 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 object { content, return_code, stderr, 2 more }

      • content: array of BetaCodeExecutionOutputBlock

        • 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 object { content, encrypted_stdout, return_code, 2 more }

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

      • content: array of BetaCodeExecutionOutputBlock

        • 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 object { content, tool_use_id, type, cache_control }

    • content: BetaCodeExecutionToolResultBlockParamContent

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

      • BetaCodeExecutionToolResultErrorParam object { error_code, type }

        • 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 object { content, return_code, stderr, 2 more }

        • content: array of BetaCodeExecutionOutputBlockParam

          • 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 object { content, encrypted_stdout, return_code, 2 more }

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

        • content: array of BetaCodeExecutionOutputBlockParam

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

      Create a cache control breakpoint at this content block.

      • type: "ephemeral"

        • "ephemeral"

      • ttl: optional "5m" or "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 or BetaCodeExecutionResultBlockParam or BetaEncryptedCodeExecutionResultBlockParam

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

    • BetaCodeExecutionToolResultErrorParam object { error_code, type }

      • 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 object { content, return_code, stderr, 2 more }

      • content: array of BetaCodeExecutionOutputBlockParam

        • 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 object { content, encrypted_stdout, return_code, 2 more }

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

      • content: array of BetaCodeExecutionOutputBlockParam

        • 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 object { error_code, type }

    • 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" or "unavailable" or "too_many_requests" or "execution_time_exceeded"

    • "invalid_tool_input"

    • "unavailable"

    • "too_many_requests"

    • "execution_time_exceeded"

Beta Code Execution Tool Result Error Param

  • BetaCodeExecutionToolResultErrorParam object { error_code, type }

    • 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 object { type, instructions, pause_after_compaction, trigger }

    Automatically compact older context when reaching the configured trigger threshold.

    • type: "compact_20260112"

      • "compact_20260112"

    • instructions: optional string

      Additional instructions for summarization.

    • pause_after_compaction: optional boolean

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

    • trigger: optional BetaInputTokensTrigger

      When to trigger compaction. Defaults to 150000 input tokens.

      • type: "input_tokens"

        • "input_tokens"

      • value: number

Beta Compaction Block

  • BetaCompactionBlock object { content, encrypted_content, type }

    A compaction block returned when autocompact is triggered.

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

    • content: string

      Summary of compacted content, or null if compaction failed

    • encrypted_content: string

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

    • type: "compaction"

      • "compaction"

Beta Compaction Block Param

  • BetaCompactionBlockParam object { content, type, cache_control, encrypted_content }

    A compaction block containing summary of previous context.

    Users should round-trip these blocks from responses to subsequent requests to maintain context across compaction boundaries.

    When content is None, the block represents a failed compaction. The server treats these as no-ops. Empty string content is not allowed.

    • content: string

      Summary of previously compacted content, or null if compaction failed

    • type: "compaction"

      • "compaction"

    • cache_control: optional BetaCacheControlEphemeral

      Create a cache control breakpoint at this content block.

      • type: "ephemeral"

        • "ephemeral"

      • ttl: optional "5m" or "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"

    • encrypted_content: optional string

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

Beta Compaction Content Block Delta

  • BetaCompactionContentBlockDelta object { content, encrypted_content, type }

    • content: string

    • encrypted_content: string

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

    • type: "compaction_delta"

      • "compaction_delta"

Beta Compaction Iteration Usage

  • BetaCompactionIterationUsage object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }

    Token usage for a compaction iteration.

    • cache_creation: BetaCacheCreation

      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 object { id, expires_at, skills }

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

    • id: string

      Identifier for the container used in this request

    • expires_at: string

      The time at which the container will expire.

    • skills: array of BetaSkill

      Skills loaded in the container

      • skill_id: string

        Skill ID

      • type: "anthropic" or "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 object { id, skills }

    Container parameters with skills to be loaded.

    • id: optional string

      Container id

    • skills: optional array of BetaSkillParams

      List of skills to load in the container

      • skill_id: string

        Skill ID

      • type: "anthropic" or "custom"

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

        • "anthropic"

        • "custom"

      • version: optional string

        Skill version or 'latest' for most recent version

Beta Container Upload Block

  • BetaContainerUploadBlock object { file_id, type }

    Response model for a file uploaded to the container.

    • file_id: string

    • type: "container_upload"

      • "container_upload"

Beta Container Upload Block Param

  • BetaContainerUploadBlockParam object { file_id, type, cache_control }

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

    • file_id: string

    • type: "container_upload"

      • "container_upload"

    • cache_control: optional BetaCacheControlEphemeral

      Create a cache control breakpoint at this content block.

      • type: "ephemeral"

        • "ephemeral"

      • ttl: optional "5m" or "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 or BetaThinkingBlock or BetaRedactedThinkingBlock or 13 more

    Response model for a file uploaded to the container.

    • BetaTextBlock object { citations, text, type }

      • citations: array of BetaTextCitation

        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 object { cited_text, document_index, document_title, 4 more }

          • cited_text: string

          • document_index: number

          • document_title: string

          • end_char_index: number

          • file_id: string

          • start_char_index: number

          • type: "char_location"

            • "char_location"

        • BetaCitationPageLocation object { cited_text, document_index, document_title, 4 more }

          • cited_text: string

          • document_index: number

          • document_title: string

          • end_page_number: number

          • file_id: string

          • start_page_number: number

          • type: "page_location"

            • "page_location"

        • BetaCitationContentBlockLocation object { cited_text, document_index, document_title, 4 more }

          • 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

          • 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

          • 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 object { cited_text, encrypted_index, title, 2 more }

          • cited_text: string

          • encrypted_index: string

          • title: string

          • type: "web_search_result_location"

            • "web_search_result_location"

          • url: string

        • BetaCitationSearchResultLocation object { cited_text, end_block_index, search_result_index, 4 more }

          • 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

          • type: "search_result_location"

            • "search_result_location"

      • text: string

      • type: "text"

        • "text"

    • BetaThinkingBlock object { signature, thinking, type }

      • signature: string

      • thinking: string

      • type: "thinking"

        • "thinking"

    • BetaRedactedThinkingBlock object { data, type }

      • data: string

      • type: "redacted_thinking"

        • "redacted_thinking"

    • BetaToolUseBlock object { id, input, name, 2 more }

      • id: string

      • input: map[unknown]

      • name: string

      • type: "tool_use"

        • "tool_use"

      • caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

        Tool invocation directly from the model.

        • BetaDirectCaller object { type }

          Tool invocation directly from the model.

          • type: "direct"

            • "direct"

        • BetaServerToolCaller object { tool_id, type }

          Tool invocation generated by a server-side tool.

          • tool_id: string

          • type: "code_execution_20250825"

            • "code_execution_20250825"

        • BetaServerToolCaller20260120 object { tool_id, type }

          • tool_id: string

          • type: "code_execution_20260120"

            • "code_execution_20260120"

    • BetaServerToolUseBlock object { id, input, name, 2 more }

      • id: string

      • input: map[unknown]

      • name: "advisor" or "web_search" or "web_fetch" or 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: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

        Tool invocation directly from the model.

        • BetaDirectCaller object { type }

          Tool invocation directly from the model.

        • BetaServerToolCaller object { tool_id, type }

          Tool invocation generated by a server-side tool.

        • BetaServerToolCaller20260120 object { tool_id, type }

    • BetaWebSearchToolResultBlock object { content, tool_use_id, type, caller }

      • content: BetaWebSearchToolResultBlockContent

        • BetaWebSearchToolResultError object { error_code, type }

          • 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 of BetaWebSearchResultBlock

          • encrypted_content: string

          • page_age: string

          • 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: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

        Tool invocation directly from the model.

        • BetaDirectCaller object { type }

          Tool invocation directly from the model.

        • BetaServerToolCaller object { tool_id, type }

          Tool invocation generated by a server-side tool.

        • BetaServerToolCaller20260120 object { tool_id, type }

    • BetaWebFetchToolResultBlock object { content, tool_use_id, type, caller }

      • content: BetaWebFetchToolResultErrorBlock or BetaWebFetchBlock

        • BetaWebFetchToolResultErrorBlock object { error_code, type }

          • error_code: BetaWebFetchToolResultErrorCode

            • "invalid_tool_input"

            • "url_too_long"

            • "url_not_allowed"

            • "url_not_accessible"

            • "unsupported_content_type"

            • "too_many_requests"

            • "max_uses_exceeded"

            • "unavailable"

          • type: "web_fetch_tool_result_error"

            • "web_fetch_tool_result_error"

        • BetaWebFetchBlock object { content, retrieved_at, type, url }

          • content: BetaDocumentBlock

            • citations: BetaCitationConfig

              Citation configuration for the document

              • enabled: boolean

            • source: BetaBase64PDFSource or BetaPlainTextSource

              • BetaBase64PDFSource object { data, media_type, type }

                • data: string

                • media_type: "application/pdf"

                  • "application/pdf"

                • type: "base64"

                  • "base64"

              • BetaPlainTextSource object { data, media_type, type }

                • data: string

                • media_type: "text/plain"

                  • "text/plain"

                • type: "text"

                  • "text"

            • title: string

              The title of the document

            • type: "document"

              • "document"

          • retrieved_at: string

            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: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

        Tool invocation directly from the model.

        • BetaDirectCaller object { type }

          Tool invocation directly from the model.

        • BetaServerToolCaller object { tool_id, type }

          Tool invocation generated by a server-side tool.

        • BetaServerToolCaller20260120 object { tool_id, type }

    • BetaAdvisorToolResultBlock object { content, tool_use_id, type }

      • content: BetaAdvisorToolResultError or BetaAdvisorResultBlock or BetaAdvisorRedactedResultBlock

        • BetaAdvisorToolResultError object { error_code, type }

          • error_code: "max_uses_exceeded" or "prompt_too_long" or "too_many_requests" or 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 object { text, type }

          • text: string

          • type: "advisor_result"

            • "advisor_result"

        • BetaAdvisorRedactedResultBlock object { encrypted_content, type }

          • encrypted_content: string

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

          • type: "advisor_redacted_result"

            • "advisor_redacted_result"

      • tool_use_id: string

      • type: "advisor_tool_result"

        • "advisor_tool_result"

    • BetaCodeExecutionToolResultBlock object { content, tool_use_id, type }

      • content: BetaCodeExecutionToolResultBlockContent

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

        • BetaCodeExecutionToolResultError object { error_code, type }

          • 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 object { content, return_code, stderr, 2 more }

          • content: array of BetaCodeExecutionOutputBlock

            • 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 object { content, encrypted_stdout, return_code, 2 more }

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

          • content: array of BetaCodeExecutionOutputBlock

            • 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 object { content, tool_use_id, type }

      • content: BetaBashCodeExecutionToolResultError or BetaBashCodeExecutionResultBlock

        • BetaBashCodeExecutionToolResultError object { error_code, type }

          • error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 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 object { content, return_code, stderr, 2 more }

          • content: array of BetaBashCodeExecutionOutputBlock

            • 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 object { content, tool_use_id, type }

      • content: BetaTextEditorCodeExecutionToolResultError or BetaTextEditorCodeExecutionViewResultBlock or BetaTextEditorCodeExecutionCreateResultBlock or BetaTextEditorCodeExecutionStrReplaceResultBlock

        • BetaTextEditorCodeExecutionToolResultError object { error_code, error_message, type }

          • error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more

            • "invalid_tool_input"

            • "unavailable"

            • "too_many_requests"

            • "execution_time_exceeded"

            • "file_not_found"

          • error_message: string

          • type: "text_editor_code_execution_tool_result_error"

            • "text_editor_code_execution_tool_result_error"

        • BetaTextEditorCodeExecutionViewResultBlock object { content, file_type, num_lines, 3 more }

          • content: string

          • file_type: "text" or "image" or "pdf"

            • "text"

            • "image"

            • "pdf"

          • num_lines: number

          • start_line: number

          • total_lines: number

          • type: "text_editor_code_execution_view_result"

            • "text_editor_code_execution_view_result"

        • BetaTextEditorCodeExecutionCreateResultBlock object { is_file_update, type }

          • is_file_update: boolean

          • type: "text_editor_code_execution_create_result"

            • "text_editor_code_execution_create_result"

        • BetaTextEditorCodeExecutionStrReplaceResultBlock object { lines, new_lines, new_start, 3 more }

          • lines: array of string

          • new_lines: number

          • new_start: number

          • old_lines: number

          • old_start: number

          • 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 object { content, tool_use_id, type }

      • content: BetaToolSearchToolResultError or BetaToolSearchToolSearchResultBlock

        • BetaToolSearchToolResultError object { error_code, error_message, type }

          • error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"

            • "invalid_tool_input"

            • "unavailable"

            • "too_many_requests"

            • "execution_time_exceeded"

          • error_message: string

          • type: "tool_search_tool_result_error"

            • "tool_search_tool_result_error"

        • BetaToolSearchToolSearchResultBlock object { tool_references, type }

          • tool_references: array of BetaToolReferenceBlock

            • 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 object { id, input, name, 2 more }

      • id: string

      • input: map[unknown]

      • 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 object { content, is_error, tool_use_id, type }

      • content: string or array of BetaTextBlock

        • string

        • BetaMCPToolResultBlockContent = array of BetaTextBlock

          • citations: array of BetaTextCitation

            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 object { file_id, type }

      Response model for a file uploaded to the container.

      • file_id: string

      • type: "container_upload"

        • "container_upload"

    • BetaCompactionBlock object { content, encrypted_content, type }

      A compaction block returned when autocompact is triggered.

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

      • content: string

        Summary of compacted content, or null if compaction failed

      • encrypted_content: string

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

      • type: "compaction"

        • "compaction"

Beta Content Block Param

  • BetaContentBlockParam = BetaTextBlockParam or BetaImageBlockParam or BetaRequestDocumentBlock or 17 more

    Regular text content.

    • BetaTextBlockParam object { text, type, cache_control, citations }

      • text: string

      • type: "text"

        • "text"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

        • type: "ephemeral"

          • "ephemeral"

        • ttl: optional "5m" or "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: optional array of BetaTextCitationParam

        • BetaCitationCharLocationParam object { cited_text, document_index, document_title, 3 more }

          • cited_text: string

          • document_index: number

          • document_title: string

          • end_char_index: number

          • start_char_index: number

          • type: "char_location"

            • "char_location"

        • BetaCitationPageLocationParam object { cited_text, document_index, document_title, 3 more }

          • cited_text: string

          • document_index: number

          • document_title: string

          • end_page_number: number

          • start_page_number: number

          • type: "page_location"

            • "page_location"

        • BetaCitationContentBlockLocationParam object { cited_text, document_index, document_title, 3 more }

          • 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

          • 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 object { cited_text, encrypted_index, title, 2 more }

          • cited_text: string

          • encrypted_index: string

          • title: string

          • type: "web_search_result_location"

            • "web_search_result_location"

          • url: string

        • BetaCitationSearchResultLocationParam object { cited_text, end_block_index, search_result_index, 4 more }

          • 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

          • type: "search_result_location"

            • "search_result_location"

    • BetaImageBlockParam object { source, type, cache_control }

      • source: BetaBase64ImageSource or BetaURLImageSource or BetaFileImageSource

        • BetaBase64ImageSource object { data, media_type, type }

          • data: string

          • media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"

            • "image/jpeg"

            • "image/png"

            • "image/gif"

            • "image/webp"

          • type: "base64"

            • "base64"

        • BetaURLImageSource object { type, url }

          • type: "url"

            • "url"

          • url: string

        • BetaFileImageSource object { file_id, type }

          • file_id: string

          • type: "file"

            • "file"

      • type: "image"

        • "image"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

    • BetaRequestDocumentBlock object { source, type, cache_control, 3 more }

      • source: BetaBase64PDFSource or BetaPlainTextSource or BetaContentBlockSource or 2 more

        • BetaBase64PDFSource object { data, media_type, type }

          • data: string

          • media_type: "application/pdf"

            • "application/pdf"

          • type: "base64"

            • "base64"

        • BetaPlainTextSource object { data, media_type, type }

          • data: string

          • media_type: "text/plain"

            • "text/plain"

          • type: "text"

            • "text"

        • BetaContentBlockSource object { content, type }

          • content: string or array of BetaContentBlockSourceContent

            • string

            • BetaContentBlockSourceContent = array of BetaContentBlockSourceContent

              • BetaTextBlockParam object { text, type, cache_control, citations }

              • BetaImageBlockParam object { source, type, cache_control }

          • type: "content"

            • "content"

        • BetaURLPDFSource object { type, url }

          • type: "url"

            • "url"

          • url: string

        • BetaFileDocumentSource object { file_id, type }

          • file_id: string

          • type: "file"

            • "file"

      • type: "document"

        • "document"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • citations: optional BetaCitationsConfigParam

        • enabled: optional boolean

      • context: optional string

      • title: optional string

    • BetaSearchResultBlockParam object { content, source, title, 3 more }

      • content: array of BetaTextBlockParam

        • text: string

        • type: "text"

        • cache_control: optional BetaCacheControlEphemeral

          Create a cache control breakpoint at this content block.

        • citations: optional array of BetaTextCitationParam

      • source: string

      • title: string

      • type: "search_result"

        • "search_result"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • citations: optional BetaCitationsConfigParam

    • BetaThinkingBlockParam object { signature, thinking, type }

      • signature: string

      • thinking: string

      • type: "thinking"

        • "thinking"

    • BetaRedactedThinkingBlockParam object { data, type }

      • data: string

      • type: "redacted_thinking"

        • "redacted_thinking"

    • BetaToolUseBlockParam object { id, input, name, 3 more }

      • id: string

      • input: map[unknown]

      • name: string

      • type: "tool_use"

        • "tool_use"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

        Tool invocation directly from the model.

        • BetaDirectCaller object { type }

          Tool invocation directly from the model.

          • type: "direct"

            • "direct"

        • BetaServerToolCaller object { tool_id, type }

          Tool invocation generated by a server-side tool.

          • tool_id: string

          • type: "code_execution_20250825"

            • "code_execution_20250825"

        • BetaServerToolCaller20260120 object { tool_id, type }

          • tool_id: string

          • type: "code_execution_20260120"

            • "code_execution_20260120"

    • BetaToolResultBlockParam object { tool_use_id, type, cache_control, 2 more }

      • tool_use_id: string

      • type: "tool_result"

        • "tool_result"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • content: optional string or array of BetaTextBlockParam or BetaImageBlockParam or BetaSearchResultBlockParam or 2 more

        • string

        • array of BetaTextBlockParam or BetaImageBlockParam or BetaSearchResultBlockParam or 2 more

          • BetaTextBlockParam object { text, type, cache_control, citations }

          • BetaImageBlockParam object { source, type, cache_control }

          • BetaSearchResultBlockParam object { content, source, title, 3 more }

          • BetaRequestDocumentBlock object { source, type, cache_control, 3 more }

          • BetaToolReferenceBlockParam object { tool_name, type, cache_control }

            Tool reference block that can be included in tool_result content.

            • tool_name: string

            • type: "tool_reference"

              • "tool_reference"

            • cache_control: optional BetaCacheControlEphemeral

              Create a cache control breakpoint at this content block.

      • is_error: optional boolean

    • BetaServerToolUseBlockParam object { id, input, name, 3 more }

      • id: string

      • input: map[unknown]

      • name: "advisor" or "web_search" or "web_fetch" or 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: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

        Tool invocation directly from the model.

        • BetaDirectCaller object { type }

          Tool invocation directly from the model.

        • BetaServerToolCaller object { tool_id, type }

          Tool invocation generated by a server-side tool.

        • BetaServerToolCaller20260120 object { tool_id, type }

    • BetaWebSearchToolResultBlockParam object { content, tool_use_id, type, 2 more }

      • content: BetaWebSearchToolResultBlockParamContent

        • ResultBlock = array of BetaWebSearchResultBlockParam

          • encrypted_content: string

          • title: string

          • type: "web_search_result"

            • "web_search_result"

          • url: string

          • page_age: optional string

        • BetaWebSearchToolRequestError object { error_code, type }

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

        Create a cache control breakpoint at this content block.

      • caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

        Tool invocation directly from the model.

        • BetaDirectCaller object { type }

          Tool invocation directly from the model.

        • BetaServerToolCaller object { tool_id, type }

          Tool invocation generated by a server-side tool.

        • BetaServerToolCaller20260120 object { tool_id, type }

    • BetaWebFetchToolResultBlockParam object { content, tool_use_id, type, 2 more }

      • content: BetaWebFetchToolResultErrorBlockParam or BetaWebFetchBlockParam

        • BetaWebFetchToolResultErrorBlockParam object { error_code, type }

          • error_code: BetaWebFetchToolResultErrorCode

            • "invalid_tool_input"

            • "url_too_long"

            • "url_not_allowed"

            • "url_not_accessible"

            • "unsupported_content_type"

            • "too_many_requests"

            • "max_uses_exceeded"

            • "unavailable"

          • type: "web_fetch_tool_result_error"

            • "web_fetch_tool_result_error"

        • BetaWebFetchBlockParam object { content, type, url, retrieved_at }

          • content: BetaRequestDocumentBlock

          • type: "web_fetch_result"

            • "web_fetch_result"

          • url: string

            Fetched content URL

          • retrieved_at: optional string

            ISO 8601 timestamp when the content was retrieved

      • tool_use_id: string

      • type: "web_fetch_tool_result"

        • "web_fetch_tool_result"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

        Tool invocation directly from the model.

        • BetaDirectCaller object { type }

          Tool invocation directly from the model.

        • BetaServerToolCaller object { tool_id, type }

          Tool invocation generated by a server-side tool.

        • BetaServerToolCaller20260120 object { tool_id, type }

    • BetaAdvisorToolResultBlockParam object { content, tool_use_id, type, cache_control }

      • content: BetaAdvisorToolResultErrorParam or BetaAdvisorResultBlockParam or BetaAdvisorRedactedResultBlockParam

        • BetaAdvisorToolResultErrorParam object { error_code, type }

          • error_code: "max_uses_exceeded" or "prompt_too_long" or "too_many_requests" or 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 object { text, type }

          • text: string

          • type: "advisor_result"

            • "advisor_result"

        • BetaAdvisorRedactedResultBlockParam object { encrypted_content, type }

          • encrypted_content: string

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

          • type: "advisor_redacted_result"

            • "advisor_redacted_result"

      • tool_use_id: string

      • type: "advisor_tool_result"

        • "advisor_tool_result"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

    • BetaCodeExecutionToolResultBlockParam object { content, tool_use_id, type, cache_control }

      • content: BetaCodeExecutionToolResultBlockParamContent

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

        • BetaCodeExecutionToolResultErrorParam object { error_code, type }

          • 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 object { content, return_code, stderr, 2 more }

          • content: array of BetaCodeExecutionOutputBlockParam

            • 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 object { content, encrypted_stdout, return_code, 2 more }

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

          • content: array of BetaCodeExecutionOutputBlockParam

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

        Create a cache control breakpoint at this content block.

    • BetaBashCodeExecutionToolResultBlockParam object { content, tool_use_id, type, cache_control }

      • content: BetaBashCodeExecutionToolResultErrorParam or BetaBashCodeExecutionResultBlockParam

        • BetaBashCodeExecutionToolResultErrorParam object { error_code, type }

          • error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 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 object { content, return_code, stderr, 2 more }

          • content: array of BetaBashCodeExecutionOutputBlockParam

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

        Create a cache control breakpoint at this content block.

    • BetaTextEditorCodeExecutionToolResultBlockParam object { content, tool_use_id, type, cache_control }

      • content: BetaTextEditorCodeExecutionToolResultErrorParam or BetaTextEditorCodeExecutionViewResultBlockParam or BetaTextEditorCodeExecutionCreateResultBlockParam or BetaTextEditorCodeExecutionStrReplaceResultBlockParam

        • BetaTextEditorCodeExecutionToolResultErrorParam object { error_code, type, error_message }

          • error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 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: optional string

        • BetaTextEditorCodeExecutionViewResultBlockParam object { content, file_type, type, 3 more }

          • content: string

          • file_type: "text" or "image" or "pdf"

            • "text"

            • "image"

            • "pdf"

          • type: "text_editor_code_execution_view_result"

            • "text_editor_code_execution_view_result"

          • num_lines: optional number

          • start_line: optional number

          • total_lines: optional number

        • BetaTextEditorCodeExecutionCreateResultBlockParam object { is_file_update, type }

          • is_file_update: boolean

          • type: "text_editor_code_execution_create_result"

            • "text_editor_code_execution_create_result"

        • BetaTextEditorCodeExecutionStrReplaceResultBlockParam object { type, lines, new_lines, 3 more }

          • type: "text_editor_code_execution_str_replace_result"

            • "text_editor_code_execution_str_replace_result"

          • lines: optional array of string

          • new_lines: optional number

          • new_start: optional number

          • old_lines: optional number

          • old_start: optional number

      • tool_use_id: string

      • type: "text_editor_code_execution_tool_result"

        • "text_editor_code_execution_tool_result"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

    • BetaToolSearchToolResultBlockParam object { content, tool_use_id, type, cache_control }

      • content: BetaToolSearchToolResultErrorParam or BetaToolSearchToolSearchResultBlockParam

        • BetaToolSearchToolResultErrorParam object { error_code, type }

          • error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "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 object { tool_references, type }

          • tool_references: array of BetaToolReferenceBlockParam

            • tool_name: string

            • type: "tool_reference"

            • cache_control: optional BetaCacheControlEphemeral

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

        Create a cache control breakpoint at this content block.

    • BetaMCPToolUseBlockParam object { id, input, name, 3 more }

      • id: string

      • input: map[unknown]

      • name: string

      • server_name: string

        The name of the MCP server

      • type: "mcp_tool_use"

        • "mcp_tool_use"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

    • BetaRequestMCPToolResultBlockParam object { tool_use_id, type, cache_control, 2 more }

      • tool_use_id: string

      • type: "mcp_tool_result"

        • "mcp_tool_result"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • content: optional string or array of BetaTextBlockParam

        • string

        • BetaMCPToolResultBlockParamContent = array of BetaTextBlockParam

          • text: string

          • type: "text"

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

          • citations: optional array of BetaTextCitationParam

      • is_error: optional boolean

    • BetaContainerUploadBlockParam object { file_id, type, cache_control }

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

      • file_id: string

      • type: "container_upload"

        • "container_upload"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

    • BetaCompactionBlockParam object { content, type, cache_control, encrypted_content }

      A compaction block containing summary of previous context.

      Users should round-trip these blocks from responses to subsequent requests to maintain context across compaction boundaries.

      When content is None, the block represents a failed compaction. The server treats these as no-ops. Empty string content is not allowed.

      • content: string

        Summary of previously compacted content, or null if compaction failed

      • type: "compaction"

        • "compaction"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • encrypted_content: optional string

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

Beta Content Block Source

  • BetaContentBlockSource object { content, type }

    • content: string or array of BetaContentBlockSourceContent

      • string

      • BetaContentBlockSourceContent = array of BetaContentBlockSourceContent

        • BetaTextBlockParam object { text, type, cache_control, citations }

          • text: string

          • type: "text"

            • "text"

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

            • type: "ephemeral"

              • "ephemeral"

            • ttl: optional "5m" or "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: optional array of BetaTextCitationParam

            • BetaCitationCharLocationParam object { cited_text, document_index, document_title, 3 more }

              • cited_text: string

              • document_index: number

              • document_title: string

              • end_char_index: number

              • start_char_index: number

              • type: "char_location"

                • "char_location"

            • BetaCitationPageLocationParam object { cited_text, document_index, document_title, 3 more }

              • cited_text: string

              • document_index: number

              • document_title: string

              • end_page_number: number

              • start_page_number: number

              • type: "page_location"

                • "page_location"

            • BetaCitationContentBlockLocationParam object { cited_text, document_index, document_title, 3 more }

              • 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

              • 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 object { cited_text, encrypted_index, title, 2 more }

              • cited_text: string

              • encrypted_index: string

              • title: string

              • type: "web_search_result_location"

                • "web_search_result_location"

              • url: string

            • BetaCitationSearchResultLocationParam object { cited_text, end_block_index, search_result_index, 4 more }

              • 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

              • type: "search_result_location"

                • "search_result_location"

        • BetaImageBlockParam object { source, type, cache_control }

          • source: BetaBase64ImageSource or BetaURLImageSource or BetaFileImageSource

            • BetaBase64ImageSource object { data, media_type, type }

              • data: string

              • media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"

                • "image/jpeg"

                • "image/png"

                • "image/gif"

                • "image/webp"

              • type: "base64"

                • "base64"

            • BetaURLImageSource object { type, url }

              • type: "url"

                • "url"

              • url: string

            • BetaFileImageSource object { file_id, type }

              • file_id: string

              • type: "file"

                • "file"

          • type: "image"

            • "image"

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

    • type: "content"

      • "content"

Beta Content Block Source Content

  • BetaContentBlockSourceContent = BetaTextBlockParam or BetaImageBlockParam

    • BetaTextBlockParam object { text, type, cache_control, citations }

      • text: string

      • type: "text"

        • "text"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

        • type: "ephemeral"

          • "ephemeral"

        • ttl: optional "5m" or "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: optional array of BetaTextCitationParam

        • BetaCitationCharLocationParam object { cited_text, document_index, document_title, 3 more }

          • cited_text: string

          • document_index: number

          • document_title: string

          • end_char_index: number

          • start_char_index: number

          • type: "char_location"

            • "char_location"

        • BetaCitationPageLocationParam object { cited_text, document_index, document_title, 3 more }

          • cited_text: string

          • document_index: number

          • document_title: string

          • end_page_number: number

          • start_page_number: number

          • type: "page_location"

            • "page_location"

        • BetaCitationContentBlockLocationParam object { cited_text, document_index, document_title, 3 more }

          • 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

          • 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 object { cited_text, encrypted_index, title, 2 more }

          • cited_text: string

          • encrypted_index: string

          • title: string

          • type: "web_search_result_location"

            • "web_search_result_location"

          • url: string

        • BetaCitationSearchResultLocationParam object { cited_text, end_block_index, search_result_index, 4 more }

          • 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

          • type: "search_result_location"

            • "search_result_location"

    • BetaImageBlockParam object { source, type, cache_control }

      • source: BetaBase64ImageSource or BetaURLImageSource or BetaFileImageSource

        • BetaBase64ImageSource object { data, media_type, type }

          • data: string

          • media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"

            • "image/jpeg"

            • "image/png"

            • "image/gif"

            • "image/webp"

          • type: "base64"

            • "base64"

        • BetaURLImageSource object { type, url }

          • type: "url"

            • "url"

          • url: string

        • BetaFileImageSource object { file_id, type }

          • file_id: string

          • type: "file"

            • "file"

      • type: "image"

        • "image"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

Beta Context Management Config

  • BetaContextManagementConfig object { edits }

    • edits: optional array of BetaClearToolUses20250919Edit or BetaClearThinking20251015Edit or BetaCompact20260112Edit

      List of context management edits to apply

      • BetaClearToolUses20250919Edit object { type, clear_at_least, clear_tool_inputs, 3 more }

        • type: "clear_tool_uses_20250919"

          • "clear_tool_uses_20250919"

        • clear_at_least: optional BetaInputTokensClearAtLeast

          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: optional boolean or array of string

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

          • boolean

          • array of string

        • exclude_tools: optional array of string

          Tool names whose uses are preserved from clearing

        • keep: optional BetaToolUsesKeep

          Number of tool uses to retain in the conversation

          • type: "tool_uses"

            • "tool_uses"

          • value: number

        • trigger: optional BetaInputTokensTrigger or BetaToolUsesTrigger

          Condition that triggers the context management strategy

          • BetaInputTokensTrigger object { type, value }

            • type: "input_tokens"

              • "input_tokens"

            • value: number

          • BetaToolUsesTrigger object { type, value }

            • type: "tool_uses"

              • "tool_uses"

            • value: number

      • BetaClearThinking20251015Edit object { type, keep }

        • type: "clear_thinking_20251015"

          • "clear_thinking_20251015"

        • keep: optional BetaThinkingTurns or BetaAllThinkingTurns or "all"

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

          • BetaThinkingTurns object { type, value }

            • type: "thinking_turns"

              • "thinking_turns"

            • value: number

          • BetaAllThinkingTurns object { type }

            • type: "all"

              • "all"

          • "all"

            • "all"

      • BetaCompact20260112Edit object { type, instructions, pause_after_compaction, trigger }

        Automatically compact older context when reaching the configured trigger threshold.

        • type: "compact_20260112"

          • "compact_20260112"

        • instructions: optional string

          Additional instructions for summarization.

        • pause_after_compaction: optional boolean

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

        • trigger: optional BetaInputTokensTrigger

          When to trigger compaction. Defaults to 150000 input tokens.

Beta Context Management Response

  • BetaContextManagementResponse object { applied_edits }

    • applied_edits: array of BetaClearToolUses20250919EditResponse or BetaClearThinking20251015EditResponse

      List of context management edits that were applied.

      • BetaClearToolUses20250919EditResponse object { cleared_input_tokens, cleared_tool_uses, type }

        • cleared_input_tokens: number

          Number of input tokens cleared by this edit.

        • cleared_tool_uses: number

          Number of tool uses that were cleared.

        • type: "clear_tool_uses_20250919"

          The type of context management edit applied.

          • "clear_tool_uses_20250919"

      • BetaClearThinking20251015EditResponse object { cleared_input_tokens, cleared_thinking_turns, type }

        • cleared_input_tokens: number

          Number of input tokens cleared by this edit.

        • cleared_thinking_turns: number

          Number of thinking turns that were cleared.

        • type: "clear_thinking_20251015"

          The type of context management edit applied.

          • "clear_thinking_20251015"

Beta Count Tokens Context Management Response

  • BetaCountTokensContextManagementResponse object { original_input_tokens }

    • original_input_tokens: number

      The original token count before context management was applied

Beta Diagnostics

  • BetaDiagnostics object { cache_miss_reason }

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

    • cache_miss_reason: BetaCacheMissModelChanged or BetaCacheMissSystemChanged or BetaCacheMissToolsChanged or 3 more

      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 object { cache_missed_input_tokens, type }

        • 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 object { cache_missed_input_tokens, type }

        • 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 object { cache_missed_input_tokens, type }

        • 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 object { cache_missed_input_tokens, type }

        • 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 object { type }

        • type: "previous_message_not_found"

          • "previous_message_not_found"

      • BetaCacheMissUnavailable object { type }

        • type: "unavailable"

          • "unavailable"

Beta Diagnostics Param

  • BetaDiagnosticsParam object { previous_message_id }

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

    • previous_message_id: optional string

      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 object { type }

    Tool invocation directly from the model.

    • type: "direct"

      • "direct"

Beta Document Block

  • BetaDocumentBlock object { citations, source, title, type }

    • citations: BetaCitationConfig

      Citation configuration for the document

      • enabled: boolean

    • source: BetaBase64PDFSource or BetaPlainTextSource

      • BetaBase64PDFSource object { data, media_type, type }

        • data: string

        • media_type: "application/pdf"

          • "application/pdf"

        • type: "base64"

          • "base64"

      • BetaPlainTextSource object { data, media_type, type }

        • data: string

        • media_type: "text/plain"

          • "text/plain"

        • type: "text"

          • "text"

    • title: string

      The title of the document

    • type: "document"

      • "document"

Beta Encrypted Code Execution Result Block

  • BetaEncryptedCodeExecutionResultBlock object { content, encrypted_stdout, return_code, 2 more }

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

    • content: array of BetaCodeExecutionOutputBlock

      • 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 object { content, encrypted_stdout, return_code, 2 more }

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

    • content: array of BetaCodeExecutionOutputBlockParam

      • 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 object { file_id, type }

    • file_id: string

    • type: "file"

      • "file"

Beta File Image Source

  • BetaFileImageSource object { file_id, type }

    • file_id: string

    • type: "file"

      • "file"

Beta Image Block Param

  • BetaImageBlockParam object { source, type, cache_control }

    • source: BetaBase64ImageSource or BetaURLImageSource or BetaFileImageSource

      • BetaBase64ImageSource object { data, media_type, type }

        • data: string

        • media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"

          • "image/jpeg"

          • "image/png"

          • "image/gif"

          • "image/webp"

        • type: "base64"

          • "base64"

      • BetaURLImageSource object { type, url }

        • type: "url"

          • "url"

        • url: string

      • BetaFileImageSource object { file_id, type }

        • file_id: string

        • type: "file"

          • "file"

    • type: "image"

      • "image"

    • cache_control: optional BetaCacheControlEphemeral

      Create a cache control breakpoint at this content block.

      • type: "ephemeral"

        • "ephemeral"

      • ttl: optional "5m" or "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 object { partial_json, type }

    • partial_json: string

    • type: "input_json_delta"

      • "input_json_delta"

Beta Input Tokens Clear At Least

  • BetaInputTokensClearAtLeast object { type, value }

    • type: "input_tokens"

      • "input_tokens"

    • value: number

Beta Input Tokens Trigger

  • BetaInputTokensTrigger object { type, value }

    • type: "input_tokens"

      • "input_tokens"

    • value: number

Beta Iterations Usage

  • BetaIterationsUsage = array of BetaMessageIterationUsage or BetaCompactionIterationUsage or BetaAdvisorMessageIterationUsage

    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 object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }

      Token usage for a sampling iteration.

      • cache_creation: BetaCacheCreation

        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 object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }

      Token usage for a compaction iteration.

      • cache_creation: BetaCacheCreation

        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 object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 4 more }

      Token usage for an advisor sub-inference iteration.

      • cache_creation: BetaCacheCreation

        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 for additional details and options.

        • "claude-opus-4-7" or "claude-mythos-preview" or "claude-opus-4-6" or 14 more

          The model that will complete your prompt.

          See models for additional details and options.

          • "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 object { schema, type }

    • schema: map[unknown]

      The JSON schema of the format

    • type: "json_schema"

      • "json_schema"

Beta MCP Tool Config

  • BetaMCPToolConfig object { defer_loading, enabled }

    Configuration for a specific tool in an MCP toolset.

    • defer_loading: optional boolean

    • enabled: optional boolean

Beta MCP Tool Default Config

  • BetaMCPToolDefaultConfig object { defer_loading, enabled }

    Default configuration for tools in an MCP toolset.

    • defer_loading: optional boolean

    • enabled: optional boolean

Beta MCP Tool Result Block

  • BetaMCPToolResultBlock object { content, is_error, tool_use_id, type }

    • content: string or array of BetaTextBlock

      • string

      • BetaMCPToolResultBlockContent = array of BetaTextBlock

        • citations: array of BetaTextCitation

          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 object { cited_text, document_index, document_title, 4 more }

            • cited_text: string

            • document_index: number

            • document_title: string

            • end_char_index: number

            • file_id: string

            • start_char_index: number

            • type: "char_location"

              • "char_location"

          • BetaCitationPageLocation object { cited_text, document_index, document_title, 4 more }

            • cited_text: string

            • document_index: number

            • document_title: string

            • end_page_number: number

            • file_id: string

            • start_page_number: number

            • type: "page_location"

              • "page_location"

          • BetaCitationContentBlockLocation object { cited_text, document_index, document_title, 4 more }

            • 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

            • 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

            • 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 object { cited_text, encrypted_index, title, 2 more }

            • cited_text: string

            • encrypted_index: string

            • title: string

            • type: "web_search_result_location"

              • "web_search_result_location"

            • url: string

          • BetaCitationSearchResultLocation object { cited_text, end_block_index, search_result_index, 4 more }

            • 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

            • 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 object { id, input, name, 2 more }

    • id: string

    • input: map[unknown]

    • 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 object { id, input, name, 3 more }

    • id: string

    • input: map[unknown]

    • name: string

    • server_name: string

      The name of the MCP server

    • type: "mcp_tool_use"

      • "mcp_tool_use"

    • cache_control: optional BetaCacheControlEphemeral

      Create a cache control breakpoint at this content block.

      • type: "ephemeral"

        • "ephemeral"

      • ttl: optional "5m" or "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 object { mcp_server_name, type, cache_control, 2 more }

    Configuration for a group of tools from an MCP server.

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

    • mcp_server_name: string

      Name of the MCP server to configure tools for

    • type: "mcp_toolset"

      • "mcp_toolset"

    • cache_control: optional BetaCacheControlEphemeral

      Create a cache control breakpoint at this content block.

      • type: "ephemeral"

        • "ephemeral"

      • ttl: optional "5m" or "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: optional map[BetaMCPToolConfig]

      Configuration overrides for specific tools, keyed by tool name

      • defer_loading: optional boolean

      • enabled: optional boolean

    • default_config: optional BetaMCPToolDefaultConfig

      Default configuration applied to all tools from this server

      • defer_loading: optional boolean

      • enabled: optional boolean

Beta Memory Tool 20250818

  • BetaMemoryTool20250818 object { name, type, allowed_callers, 4 more }

    • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

      • "direct"

      • "code_execution_20250825"

      • "code_execution_20260120"

    • cache_control: optional BetaCacheControlEphemeral

      Create a cache control breakpoint at this content block.

      • type: "ephemeral"

        • "ephemeral"

      • ttl: optional "5m" or "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: optional boolean

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

    • input_examples: optional array of map[unknown]

    • strict: optional boolean

      When true, guarantees schema validation on tool names and inputs

Beta Memory Tool 20250818 Command

  • BetaMemoryTool20250818Command = BetaMemoryTool20250818ViewCommand or BetaMemoryTool20250818CreateCommand or BetaMemoryTool20250818StrReplaceCommand or 3 more

    • BetaMemoryTool20250818ViewCommand object { command, path, view_range }

      • command: "view"

        Command type identifier

        • "view"

      • path: string

        Path to directory or file to view

      • view_range: optional array of number

        Optional line range for viewing specific lines

    • BetaMemoryTool20250818CreateCommand object { command, file_text, path }

      • 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 object { command, new_str, old_str, path }

      • 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 object { command, insert_line, insert_text, path }

      • 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 object { command, path }

      • command: "delete"

        Command type identifier

        • "delete"

      • path: string

        Path to the file or directory to delete

    • BetaMemoryTool20250818RenameCommand object { command, new_path, old_path }

      • 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 object { command, file_text, path }

    • 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 object { command, path }

    • command: "delete"

      Command type identifier

      • "delete"

    • path: string

      Path to the file or directory to delete

Beta Memory Tool 20250818 Insert Command

  • BetaMemoryTool20250818InsertCommand object { command, insert_line, insert_text, path }

    • 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 object { command, new_path, old_path }

    • 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 object { command, new_str, old_str, path }

    • 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 object { command, path, view_range }

    • command: "view"

      Command type identifier

      • "view"

    • path: string

      Path to directory or file to view

    • view_range: optional array of number

      Optional line range for viewing specific lines

Beta Message

  • BetaMessage object { id, container, content, 9 more }

    • id: string

      Unique object identifier.

      The format and length of IDs may change over time.

    • 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 of BetaSkill

        Skills loaded in the container

        • skill_id: string

          Skill ID

        • type: "anthropic" or "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 of BetaContentBlock

      Content generated by the model.

      This is an array of content blocks, each of which has a type that determines its shape.

      Example:

      [{"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:

      [
  {"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:

      [{"type": "text", "text": "B)"}]

      • BetaTextBlock object { citations, text, type }

        • citations: array of BetaTextCitation

          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 object { cited_text, document_index, document_title, 4 more }

            • cited_text: string

            • document_index: number

            • document_title: string

            • end_char_index: number

            • file_id: string

            • start_char_index: number

            • type: "char_location"

              • "char_location"

          • BetaCitationPageLocation object { cited_text, document_index, document_title, 4 more }

            • cited_text: string

            • document_index: number

            • document_title: string

            • end_page_number: number

            • file_id: string

            • start_page_number: number

            • type: "page_location"

              • "page_location"

          • BetaCitationContentBlockLocation object { cited_text, document_index, document_title, 4 more }

            • 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

            • 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

            • 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 object { cited_text, encrypted_index, title, 2 more }

            • cited_text: string

            • encrypted_index: string

            • title: string

            • type: "web_search_result_location"

              • "web_search_result_location"

            • url: string

          • BetaCitationSearchResultLocation object { cited_text, end_block_index, search_result_index, 4 more }

            • 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

            • type: "search_result_location"

              • "search_result_location"

        • text: string

        • type: "text"

          • "text"

      • BetaThinkingBlock object { signature, thinking, type }

        • signature: string

        • thinking: string

        • type: "thinking"

          • "thinking"

      • BetaRedactedThinkingBlock object { data, type }

        • data: string

        • type: "redacted_thinking"

          • "redacted_thinking"

      • BetaToolUseBlock object { id, input, name, 2 more }

        • id: string

        • input: map[unknown]

        • name: string

        • type: "tool_use"

          • "tool_use"

        • caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

          Tool invocation directly from the model.

          • BetaDirectCaller object { type }

            Tool invocation directly from the model.

            • type: "direct"

              • "direct"

          • BetaServerToolCaller object { tool_id, type }

            Tool invocation generated by a server-side tool.

            • tool_id: string

            • type: "code_execution_20250825"

              • "code_execution_20250825"

          • BetaServerToolCaller20260120 object { tool_id, type }

            • tool_id: string

            • type: "code_execution_20260120"

              • "code_execution_20260120"

      • BetaServerToolUseBlock object { id, input, name, 2 more }

        • id: string

        • input: map[unknown]

        • name: "advisor" or "web_search" or "web_fetch" or 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: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

          Tool invocation directly from the model.

          • BetaDirectCaller object { type }

            Tool invocation directly from the model.

          • BetaServerToolCaller object { tool_id, type }

            Tool invocation generated by a server-side tool.

          • BetaServerToolCaller20260120 object { tool_id, type }

      • BetaWebSearchToolResultBlock object { content, tool_use_id, type, caller }

        • content: BetaWebSearchToolResultBlockContent

          • BetaWebSearchToolResultError object { error_code, type }

            • 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 of BetaWebSearchResultBlock

            • encrypted_content: string

            • page_age: string

            • 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: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

          Tool invocation directly from the model.

          • BetaDirectCaller object { type }

            Tool invocation directly from the model.

          • BetaServerToolCaller object { tool_id, type }

            Tool invocation generated by a server-side tool.

          • BetaServerToolCaller20260120 object { tool_id, type }

      • BetaWebFetchToolResultBlock object { content, tool_use_id, type, caller }

        • content: BetaWebFetchToolResultErrorBlock or BetaWebFetchBlock

          • BetaWebFetchToolResultErrorBlock object { error_code, type }

            • error_code: BetaWebFetchToolResultErrorCode

              • "invalid_tool_input"

              • "url_too_long"

              • "url_not_allowed"

              • "url_not_accessible"

              • "unsupported_content_type"

              • "too_many_requests"

              • "max_uses_exceeded"

              • "unavailable"

            • type: "web_fetch_tool_result_error"

              • "web_fetch_tool_result_error"

          • BetaWebFetchBlock object { content, retrieved_at, type, url }

            • content: BetaDocumentBlock

              • citations: BetaCitationConfig

                Citation configuration for the document

                • enabled: boolean

              • source: BetaBase64PDFSource or BetaPlainTextSource

                • BetaBase64PDFSource object { data, media_type, type }

                  • data: string

                  • media_type: "application/pdf"

                    • "application/pdf"

                  • type: "base64"

                    • "base64"

                • BetaPlainTextSource object { data, media_type, type }

                  • data: string

                  • media_type: "text/plain"

                    • "text/plain"

                  • type: "text"

                    • "text"

              • title: string

                The title of the document

              • type: "document"

                • "document"

            • retrieved_at: string

              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: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

          Tool invocation directly from the model.

          • BetaDirectCaller object { type }

            Tool invocation directly from the model.

          • BetaServerToolCaller object { tool_id, type }

            Tool invocation generated by a server-side tool.

          • BetaServerToolCaller20260120 object { tool_id, type }

      • BetaAdvisorToolResultBlock object { content, tool_use_id, type }

        • content: BetaAdvisorToolResultError or BetaAdvisorResultBlock or BetaAdvisorRedactedResultBlock

          • BetaAdvisorToolResultError object { error_code, type }

            • error_code: "max_uses_exceeded" or "prompt_too_long" or "too_many_requests" or 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 object { text, type }

            • text: string

            • type: "advisor_result"

              • "advisor_result"

          • BetaAdvisorRedactedResultBlock object { encrypted_content, type }

            • encrypted_content: string

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

            • type: "advisor_redacted_result"

              • "advisor_redacted_result"

        • tool_use_id: string

        • type: "advisor_tool_result"

          • "advisor_tool_result"

      • BetaCodeExecutionToolResultBlock object { content, tool_use_id, type }

        • content: BetaCodeExecutionToolResultBlockContent

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

          • BetaCodeExecutionToolResultError object { error_code, type }

            • 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 object { content, return_code, stderr, 2 more }

            • content: array of BetaCodeExecutionOutputBlock

              • 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 object { content, encrypted_stdout, return_code, 2 more }

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

            • content: array of BetaCodeExecutionOutputBlock

              • 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 object { content, tool_use_id, type }

        • content: BetaBashCodeExecutionToolResultError or BetaBashCodeExecutionResultBlock

          • BetaBashCodeExecutionToolResultError object { error_code, type }

            • error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 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 object { content, return_code, stderr, 2 more }

            • content: array of BetaBashCodeExecutionOutputBlock

              • 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 object { content, tool_use_id, type }

        • content: BetaTextEditorCodeExecutionToolResultError or BetaTextEditorCodeExecutionViewResultBlock or BetaTextEditorCodeExecutionCreateResultBlock or BetaTextEditorCodeExecutionStrReplaceResultBlock

          • BetaTextEditorCodeExecutionToolResultError object { error_code, error_message, type }

            • error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more

              • "invalid_tool_input"

              • "unavailable"

              • "too_many_requests"

              • "execution_time_exceeded"

              • "file_not_found"

            • error_message: string

            • type: "text_editor_code_execution_tool_result_error"

              • "text_editor_code_execution_tool_result_error"

          • BetaTextEditorCodeExecutionViewResultBlock object { content, file_type, num_lines, 3 more }

            • content: string

            • file_type: "text" or "image" or "pdf"

              • "text"

              • "image"

              • "pdf"

            • num_lines: number

            • start_line: number

            • total_lines: number

            • type: "text_editor_code_execution_view_result"

              • "text_editor_code_execution_view_result"

          • BetaTextEditorCodeExecutionCreateResultBlock object { is_file_update, type }

            • is_file_update: boolean

            • type: "text_editor_code_execution_create_result"

              • "text_editor_code_execution_create_result"

          • BetaTextEditorCodeExecutionStrReplaceResultBlock object { lines, new_lines, new_start, 3 more }

            • lines: array of string

            • new_lines: number

            • new_start: number

            • old_lines: number

            • old_start: number

            • 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 object { content, tool_use_id, type }

        • content: BetaToolSearchToolResultError or BetaToolSearchToolSearchResultBlock

          • BetaToolSearchToolResultError object { error_code, error_message, type }

            • error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"

              • "invalid_tool_input"

              • "unavailable"

              • "too_many_requests"

              • "execution_time_exceeded"

            • error_message: string

            • type: "tool_search_tool_result_error"

              • "tool_search_tool_result_error"

          • BetaToolSearchToolSearchResultBlock object { tool_references, type }

            • tool_references: array of BetaToolReferenceBlock

              • 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 object { id, input, name, 2 more }

        • id: string

        • input: map[unknown]

        • 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 object { content, is_error, tool_use_id, type }

        • content: string or array of BetaTextBlock

          • string

          • BetaMCPToolResultBlockContent = array of BetaTextBlock

            • citations: array of BetaTextCitation

              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 object { file_id, type }

        Response model for a file uploaded to the container.

        • file_id: string

        • type: "container_upload"

          • "container_upload"

      • BetaCompactionBlock object { content, encrypted_content, type }

        A compaction block returned when autocompact is triggered.

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

        • content: string

          Summary of compacted content, or null if compaction failed

        • encrypted_content: string

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

        • type: "compaction"

          • "compaction"

    • context_management: BetaContextManagementResponse

      Context management response.

      Information about context management strategies applied during the request.

      • applied_edits: array of BetaClearToolUses20250919EditResponse or BetaClearThinking20251015EditResponse

        List of context management edits that were applied.

        • BetaClearToolUses20250919EditResponse object { cleared_input_tokens, cleared_tool_uses, type }

          • cleared_input_tokens: number

            Number of input tokens cleared by this edit.

          • cleared_tool_uses: number

            Number of tool uses that were cleared.

          • type: "clear_tool_uses_20250919"

            The type of context management edit applied.

            • "clear_tool_uses_20250919"

        • BetaClearThinking20251015EditResponse object { cleared_input_tokens, cleared_thinking_turns, type }

          • cleared_input_tokens: number

            Number of input tokens cleared by this edit.

          • cleared_thinking_turns: number

            Number of thinking turns that were cleared.

          • type: "clear_thinking_20251015"

            The type of context management edit applied.

            • "clear_thinking_20251015"

    • diagnostics: BetaDiagnostics

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

      • cache_miss_reason: BetaCacheMissModelChanged or BetaCacheMissSystemChanged or BetaCacheMissToolsChanged or 3 more

        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 object { cache_missed_input_tokens, type }

          • 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 object { cache_missed_input_tokens, type }

          • 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 object { cache_missed_input_tokens, type }

          • 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 object { cache_missed_input_tokens, type }

          • 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 object { type }

          • type: "previous_message_not_found"

            • "previous_message_not_found"

        • BetaCacheMissUnavailable object { type }

          • type: "unavailable"

            • "unavailable"

    • model: Model

      The model that will complete your prompt.

      See models for additional details and options.

      • "claude-opus-4-7" or "claude-mythos-preview" or "claude-opus-4-6" or 14 more

        The model that will complete your prompt.

        See models for additional details and options.

        • "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

      Structured information about a refusal.

      • category: "cyber" or "bio"

        The policy category that triggered the refusal.

        null when the refusal doesn't map to a named category.

        • "cyber"

        • "bio"

      • explanation: string

        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

      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

      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

        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.

      • inference_geo: string

        The geographic region where inference was performed for this request.

      • input_tokens: number

        The number of input tokens which were used.

      • iterations: BetaIterationsUsage

        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 object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }

          Token usage for a sampling iteration.

          • cache_creation: BetaCacheCreation

            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 object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }

          Token usage for a compaction iteration.

          • cache_creation: BetaCacheCreation

            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 object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 4 more }

          Token usage for an advisor sub-inference iteration.

          • cache_creation: BetaCacheCreation

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

      • server_tool_use: BetaServerToolUsage

        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" or "priority" or "batch"

        If the request used the priority, standard, or batch tier.

        • "standard"

        • "priority"

        • "batch"

      • speed: "standard" or "fast"

        The inference speed mode used for this request.

        • "standard"

        • "fast"

Beta Message Delta Usage

  • BetaMessageDeltaUsage object { cache_creation_input_tokens, cache_read_input_tokens, input_tokens, 3 more }

    • cache_creation_input_tokens: number

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

    • cache_read_input_tokens: number

      The cumulative number of input tokens read from the cache.

    • input_tokens: number

      The cumulative number of input tokens which were used.

    • iterations: BetaIterationsUsage

      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 object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }

        Token usage for a sampling iteration.

        • cache_creation: BetaCacheCreation

          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 object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }

        Token usage for a compaction iteration.

        • cache_creation: BetaCacheCreation

          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 object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 4 more }

        Token usage for an advisor sub-inference iteration.

        • cache_creation: BetaCacheCreation

          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 for additional details and options.

          • "claude-opus-4-7" or "claude-mythos-preview" or "claude-opus-4-6" or 14 more

            The model that will complete your prompt.

            See models for additional details and options.

            • "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.

    • server_tool_use: BetaServerToolUsage

      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 object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }

    Token usage for a sampling iteration.

    • cache_creation: BetaCacheCreation

      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 object { content, role }

    • content: string or array of BetaContentBlockParam

      • string

      • array of BetaContentBlockParam

        • BetaTextBlockParam object { text, type, cache_control, citations }

          • text: string

          • type: "text"

            • "text"

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

            • type: "ephemeral"

              • "ephemeral"

            • ttl: optional "5m" or "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: optional array of BetaTextCitationParam

            • BetaCitationCharLocationParam object { cited_text, document_index, document_title, 3 more }

              • cited_text: string

              • document_index: number

              • document_title: string

              • end_char_index: number

              • start_char_index: number

              • type: "char_location"

                • "char_location"

            • BetaCitationPageLocationParam object { cited_text, document_index, document_title, 3 more }

              • cited_text: string

              • document_index: number

              • document_title: string

              • end_page_number: number

              • start_page_number: number

              • type: "page_location"

                • "page_location"

            • BetaCitationContentBlockLocationParam object { cited_text, document_index, document_title, 3 more }

              • 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

              • 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 object { cited_text, encrypted_index, title, 2 more }

              • cited_text: string

              • encrypted_index: string

              • title: string

              • type: "web_search_result_location"

                • "web_search_result_location"

              • url: string

            • BetaCitationSearchResultLocationParam object { cited_text, end_block_index, search_result_index, 4 more }

              • 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

              • type: "search_result_location"

                • "search_result_location"

        • BetaImageBlockParam object { source, type, cache_control }

          • source: BetaBase64ImageSource or BetaURLImageSource or BetaFileImageSource

            • BetaBase64ImageSource object { data, media_type, type }

              • data: string

              • media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"

                • "image/jpeg"

                • "image/png"

                • "image/gif"

                • "image/webp"

              • type: "base64"

                • "base64"

            • BetaURLImageSource object { type, url }

              • type: "url"

                • "url"

              • url: string

            • BetaFileImageSource object { file_id, type }

              • file_id: string

              • type: "file"

                • "file"

          • type: "image"

            • "image"

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

        • BetaRequestDocumentBlock object { source, type, cache_control, 3 more }

          • source: BetaBase64PDFSource or BetaPlainTextSource or BetaContentBlockSource or 2 more

            • BetaBase64PDFSource object { data, media_type, type }

              • data: string

              • media_type: "application/pdf"

                • "application/pdf"

              • type: "base64"

                • "base64"

            • BetaPlainTextSource object { data, media_type, type }

              • data: string

              • media_type: "text/plain"

                • "text/plain"

              • type: "text"

                • "text"

            • BetaContentBlockSource object { content, type }

              • content: string or array of BetaContentBlockSourceContent

                • string

                • BetaContentBlockSourceContent = array of BetaContentBlockSourceContent

                  • BetaTextBlockParam object { text, type, cache_control, citations }

                  • BetaImageBlockParam object { source, type, cache_control }

              • type: "content"

                • "content"

            • BetaURLPDFSource object { type, url }

              • type: "url"

                • "url"

              • url: string

            • BetaFileDocumentSource object { file_id, type }

              • file_id: string

              • type: "file"

                • "file"

          • type: "document"

            • "document"

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

          • citations: optional BetaCitationsConfigParam

            • enabled: optional boolean

          • context: optional string

          • title: optional string

        • BetaSearchResultBlockParam object { content, source, title, 3 more }

          • content: array of BetaTextBlockParam

            • text: string

            • type: "text"

            • cache_control: optional BetaCacheControlEphemeral

              Create a cache control breakpoint at this content block.

            • citations: optional array of BetaTextCitationParam

          • source: string

          • title: string

          • type: "search_result"

            • "search_result"

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

          • citations: optional BetaCitationsConfigParam

        • BetaThinkingBlockParam object { signature, thinking, type }

          • signature: string

          • thinking: string

          • type: "thinking"

            • "thinking"

        • BetaRedactedThinkingBlockParam object { data, type }

          • data: string

          • type: "redacted_thinking"

            • "redacted_thinking"

        • BetaToolUseBlockParam object { id, input, name, 3 more }

          • id: string

          • input: map[unknown]

          • name: string

          • type: "tool_use"

            • "tool_use"

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

          • caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

            Tool invocation directly from the model.

            • BetaDirectCaller object { type }

              Tool invocation directly from the model.

              • type: "direct"

                • "direct"

            • BetaServerToolCaller object { tool_id, type }

              Tool invocation generated by a server-side tool.

              • tool_id: string

              • type: "code_execution_20250825"

                • "code_execution_20250825"

            • BetaServerToolCaller20260120 object { tool_id, type }

              • tool_id: string

              • type: "code_execution_20260120"

                • "code_execution_20260120"

        • BetaToolResultBlockParam object { tool_use_id, type, cache_control, 2 more }

          • tool_use_id: string

          • type: "tool_result"

            • "tool_result"

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

          • content: optional string or array of BetaTextBlockParam or BetaImageBlockParam or BetaSearchResultBlockParam or 2 more

            • string

            • array of BetaTextBlockParam or BetaImageBlockParam or BetaSearchResultBlockParam or 2 more

              • BetaTextBlockParam object { text, type, cache_control, citations }

              • BetaImageBlockParam object { source, type, cache_control }

              • BetaSearchResultBlockParam object { content, source, title, 3 more }

              • BetaRequestDocumentBlock object { source, type, cache_control, 3 more }

              • BetaToolReferenceBlockParam object { tool_name, type, cache_control }

                Tool reference block that can be included in tool_result content.

                • tool_name: string

                • type: "tool_reference"

                  • "tool_reference"

                • cache_control: optional BetaCacheControlEphemeral

                  Create a cache control breakpoint at this content block.

          • is_error: optional boolean

        • BetaServerToolUseBlockParam object { id, input, name, 3 more }

          • id: string

          • input: map[unknown]

          • name: "advisor" or "web_search" or "web_fetch" or 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: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

          • caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

            Tool invocation directly from the model.

            • BetaDirectCaller object { type }

              Tool invocation directly from the model.

            • BetaServerToolCaller object { tool_id, type }

              Tool invocation generated by a server-side tool.

            • BetaServerToolCaller20260120 object { tool_id, type }

        • BetaWebSearchToolResultBlockParam object { content, tool_use_id, type, 2 more }

          • content: BetaWebSearchToolResultBlockParamContent

            • ResultBlock = array of BetaWebSearchResultBlockParam

              • encrypted_content: string

              • title: string

              • type: "web_search_result"

                • "web_search_result"

              • url: string

              • page_age: optional string

            • BetaWebSearchToolRequestError object { error_code, type }

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

            Create a cache control breakpoint at this content block.

          • caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

            Tool invocation directly from the model.

            • BetaDirectCaller object { type }

              Tool invocation directly from the model.

            • BetaServerToolCaller object { tool_id, type }

              Tool invocation generated by a server-side tool.

            • BetaServerToolCaller20260120 object { tool_id, type }

        • BetaWebFetchToolResultBlockParam object { content, tool_use_id, type, 2 more }

          • content: BetaWebFetchToolResultErrorBlockParam or BetaWebFetchBlockParam

            • BetaWebFetchToolResultErrorBlockParam object { error_code, type }

              • error_code: BetaWebFetchToolResultErrorCode

                • "invalid_tool_input"

                • "url_too_long"

                • "url_not_allowed"

                • "url_not_accessible"

                • "unsupported_content_type"

                • "too_many_requests"

                • "max_uses_exceeded"

                • "unavailable"

              • type: "web_fetch_tool_result_error"

                • "web_fetch_tool_result_error"

            • BetaWebFetchBlockParam object { content, type, url, retrieved_at }

              • content: BetaRequestDocumentBlock

              • type: "web_fetch_result"

                • "web_fetch_result"

              • url: string

                Fetched content URL

              • retrieved_at: optional string

                ISO 8601 timestamp when the content was retrieved

          • tool_use_id: string

          • type: "web_fetch_tool_result"

            • "web_fetch_tool_result"

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

          • caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

            Tool invocation directly from the model.

            • BetaDirectCaller object { type }

              Tool invocation directly from the model.

            • BetaServerToolCaller object { tool_id, type }

              Tool invocation generated by a server-side tool.

            • BetaServerToolCaller20260120 object { tool_id, type }

        • BetaAdvisorToolResultBlockParam object { content, tool_use_id, type, cache_control }

          • content: BetaAdvisorToolResultErrorParam or BetaAdvisorResultBlockParam or BetaAdvisorRedactedResultBlockParam

            • BetaAdvisorToolResultErrorParam object { error_code, type }

              • error_code: "max_uses_exceeded" or "prompt_too_long" or "too_many_requests" or 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 object { text, type }

              • text: string

              • type: "advisor_result"

                • "advisor_result"

            • BetaAdvisorRedactedResultBlockParam object { encrypted_content, type }

              • encrypted_content: string

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

              • type: "advisor_redacted_result"

                • "advisor_redacted_result"

          • tool_use_id: string

          • type: "advisor_tool_result"

            • "advisor_tool_result"

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

        • BetaCodeExecutionToolResultBlockParam object { content, tool_use_id, type, cache_control }

          • content: BetaCodeExecutionToolResultBlockParamContent

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

            • BetaCodeExecutionToolResultErrorParam object { error_code, type }

              • 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 object { content, return_code, stderr, 2 more }

              • content: array of BetaCodeExecutionOutputBlockParam

                • 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 object { content, encrypted_stdout, return_code, 2 more }

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

              • content: array of BetaCodeExecutionOutputBlockParam

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

            Create a cache control breakpoint at this content block.

        • BetaBashCodeExecutionToolResultBlockParam object { content, tool_use_id, type, cache_control }

          • content: BetaBashCodeExecutionToolResultErrorParam or BetaBashCodeExecutionResultBlockParam

            • BetaBashCodeExecutionToolResultErrorParam object { error_code, type }

              • error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 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 object { content, return_code, stderr, 2 more }

              • content: array of BetaBashCodeExecutionOutputBlockParam

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

            Create a cache control breakpoint at this content block.

        • BetaTextEditorCodeExecutionToolResultBlockParam object { content, tool_use_id, type, cache_control }

          • content: BetaTextEditorCodeExecutionToolResultErrorParam or BetaTextEditorCodeExecutionViewResultBlockParam or BetaTextEditorCodeExecutionCreateResultBlockParam or BetaTextEditorCodeExecutionStrReplaceResultBlockParam

            • BetaTextEditorCodeExecutionToolResultErrorParam object { error_code, type, error_message }

              • error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 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: optional string

            • BetaTextEditorCodeExecutionViewResultBlockParam object { content, file_type, type, 3 more }

              • content: string

              • file_type: "text" or "image" or "pdf"

                • "text"

                • "image"

                • "pdf"

              • type: "text_editor_code_execution_view_result"

                • "text_editor_code_execution_view_result"

              • num_lines: optional number

              • start_line: optional number

              • total_lines: optional number

            • BetaTextEditorCodeExecutionCreateResultBlockParam object { is_file_update, type }

              • is_file_update: boolean

              • type: "text_editor_code_execution_create_result"

                • "text_editor_code_execution_create_result"

            • BetaTextEditorCodeExecutionStrReplaceResultBlockParam object { type, lines, new_lines, 3 more }

              • type: "text_editor_code_execution_str_replace_result"

                • "text_editor_code_execution_str_replace_result"

              • lines: optional array of string

              • new_lines: optional number

              • new_start: optional number

              • old_lines: optional number

              • old_start: optional number

          • tool_use_id: string

          • type: "text_editor_code_execution_tool_result"

            • "text_editor_code_execution_tool_result"

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

        • BetaToolSearchToolResultBlockParam object { content, tool_use_id, type, cache_control }

          • content: BetaToolSearchToolResultErrorParam or BetaToolSearchToolSearchResultBlockParam

            • BetaToolSearchToolResultErrorParam object { error_code, type }

              • error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "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 object { tool_references, type }

              • tool_references: array of BetaToolReferenceBlockParam

                • tool_name: string

                • type: "tool_reference"

                • cache_control: optional BetaCacheControlEphemeral

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

            Create a cache control breakpoint at this content block.

        • BetaMCPToolUseBlockParam object { id, input, name, 3 more }

          • id: string

          • input: map[unknown]

          • name: string

          • server_name: string

            The name of the MCP server

          • type: "mcp_tool_use"

            • "mcp_tool_use"

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

        • BetaRequestMCPToolResultBlockParam object { tool_use_id, type, cache_control, 2 more }

          • tool_use_id: string

          • type: "mcp_tool_result"

            • "mcp_tool_result"

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

          • content: optional string or array of BetaTextBlockParam

            • string

            • BetaMCPToolResultBlockParamContent = array of BetaTextBlockParam

              • text: string

              • type: "text"

              • cache_control: optional BetaCacheControlEphemeral

                Create a cache control breakpoint at this content block.

              • citations: optional array of BetaTextCitationParam

          • is_error: optional boolean

        • BetaContainerUploadBlockParam object { file_id, type, cache_control }

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

          • file_id: string

          • type: "container_upload"

            • "container_upload"

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

        • BetaCompactionBlockParam object { content, type, cache_control, encrypted_content }

          A compaction block containing summary of previous context.

          Users should round-trip these blocks from responses to subsequent requests to maintain context across compaction boundaries.

          When content is None, the block represents a failed compaction. The server treats these as no-ops. Empty string content is not allowed.

          • content: string

            Summary of previously compacted content, or null if compaction failed

          • type: "compaction"

            • "compaction"

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

          • encrypted_content: optional string

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

    • role: "user" or "assistant"

      • "user"

      • "assistant"

Beta Message Tokens Count

  • BetaMessageTokensCount object { context_management, input_tokens }

    • context_management: BetaCountTokensContextManagementResponse

      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 object { user_id }

    • user_id: optional string

      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 Output Config

  • BetaOutputConfig object { effort, format, task_budget }

    • effort: optional "low" or "medium" or "high" or 2 more

      All possible effort levels.

      • "low"

      • "medium"

      • "high"

      • "xhigh"

      • "max"

    • format: optional BetaJSONOutputFormat

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

      • schema: map[unknown]

        The JSON schema of the format

      • type: "json_schema"

        • "json_schema"

    • task_budget: optional 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: optional number

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

Beta Plain Text Source

  • BetaPlainTextSource object { data, media_type, type }

    • data: string

    • media_type: "text/plain"

      • "text/plain"

    • type: "text"

      • "text"

Beta Raw Content Block Delta

  • BetaRawContentBlockDelta = BetaTextDelta or BetaInputJSONDelta or BetaCitationsDelta or 3 more

    • BetaTextDelta object { text, type }

      • text: string

      • type: "text_delta"

        • "text_delta"

    • BetaInputJSONDelta object { partial_json, type }

      • partial_json: string

      • type: "input_json_delta"

        • "input_json_delta"

    • BetaCitationsDelta object { citation, type }

      • citation: BetaCitationCharLocation or BetaCitationPageLocation or BetaCitationContentBlockLocation or 2 more

        • BetaCitationCharLocation object { cited_text, document_index, document_title, 4 more }

          • cited_text: string

          • document_index: number

          • document_title: string

          • end_char_index: number

          • file_id: string

          • start_char_index: number

          • type: "char_location"

            • "char_location"

        • BetaCitationPageLocation object { cited_text, document_index, document_title, 4 more }

          • cited_text: string

          • document_index: number

          • document_title: string

          • end_page_number: number

          • file_id: string

          • start_page_number: number

          • type: "page_location"

            • "page_location"

        • BetaCitationContentBlockLocation object { cited_text, document_index, document_title, 4 more }

          • 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

          • 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

          • 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 object { cited_text, encrypted_index, title, 2 more }

          • cited_text: string

          • encrypted_index: string

          • title: string

          • type: "web_search_result_location"

            • "web_search_result_location"

          • url: string

        • BetaCitationSearchResultLocation object { cited_text, end_block_index, search_result_index, 4 more }

          • 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

          • type: "search_result_location"

            • "search_result_location"

      • type: "citations_delta"

        • "citations_delta"

    • BetaThinkingDelta object { thinking, type }

      • thinking: string

      • type: "thinking_delta"

        • "thinking_delta"

    • BetaSignatureDelta object { signature, type }

      • signature: string

      • type: "signature_delta"

        • "signature_delta"

    • BetaCompactionContentBlockDelta object { content, encrypted_content, type }

      • content: string

      • encrypted_content: string

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

      • type: "compaction_delta"

        • "compaction_delta"

Beta Raw Content Block Delta Event

  • BetaRawContentBlockDeltaEvent object { delta, index, type }

    • delta: BetaRawContentBlockDelta

      • BetaTextDelta object { text, type }

        • text: string

        • type: "text_delta"

          • "text_delta"

      • BetaInputJSONDelta object { partial_json, type }

        • partial_json: string

        • type: "input_json_delta"

          • "input_json_delta"

      • BetaCitationsDelta object { citation, type }

        • citation: BetaCitationCharLocation or BetaCitationPageLocation or BetaCitationContentBlockLocation or 2 more

          • BetaCitationCharLocation object { cited_text, document_index, document_title, 4 more }

            • cited_text: string

            • document_index: number

            • document_title: string

            • end_char_index: number

            • file_id: string

            • start_char_index: number

            • type: "char_location"

              • "char_location"

          • BetaCitationPageLocation object { cited_text, document_index, document_title, 4 more }

            • cited_text: string

            • document_index: number

            • document_title: string

            • end_page_number: number

            • file_id: string

            • start_page_number: number

            • type: "page_location"

              • "page_location"

          • BetaCitationContentBlockLocation object { cited_text, document_index, document_title, 4 more }

            • 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

            • 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

            • 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 object { cited_text, encrypted_index, title, 2 more }

            • cited_text: string

            • encrypted_index: string

            • title: string

            • type: "web_search_result_location"

              • "web_search_result_location"

            • url: string

          • BetaCitationSearchResultLocation object { cited_text, end_block_index, search_result_index, 4 more }

            • 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

            • type: "search_result_location"

              • "search_result_location"

        • type: "citations_delta"

          • "citations_delta"

      • BetaThinkingDelta object { thinking, type }

        • thinking: string

        • type: "thinking_delta"

          • "thinking_delta"

      • BetaSignatureDelta object { signature, type }

        • signature: string

        • type: "signature_delta"

          • "signature_delta"

      • BetaCompactionContentBlockDelta object { content, encrypted_content, type }

        • content: string

        • encrypted_content: string

          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 object { content_block, index, type }

    • content_block: BetaTextBlock or BetaThinkingBlock or BetaRedactedThinkingBlock or 13 more

      Response model for a file uploaded to the container.

      • BetaTextBlock object { citations, text, type }

        • citations: array of BetaTextCitation

          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 object { cited_text, document_index, document_title, 4 more }

            • cited_text: string

            • document_index: number

            • document_title: string

            • end_char_index: number

            • file_id: string

            • start_char_index: number

            • type: "char_location"

              • "char_location"

          • BetaCitationPageLocation object { cited_text, document_index, document_title, 4 more }

            • cited_text: string

            • document_index: number

            • document_title: string

            • end_page_number: number

            • file_id: string

            • start_page_number: number

            • type: "page_location"

              • "page_location"

          • BetaCitationContentBlockLocation object { cited_text, document_index, document_title, 4 more }

            • 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

            • 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

            • 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 object { cited_text, encrypted_index, title, 2 more }

            • cited_text: string

            • encrypted_index: string

            • title: string

            • type: "web_search_result_location"

              • "web_search_result_location"

            • url: string

          • BetaCitationSearchResultLocation object { cited_text, end_block_index, search_result_index, 4 more }

            • 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

            • type: "search_result_location"

              • "search_result_location"

        • text: string

        • type: "text"

          • "text"

      • BetaThinkingBlock object { signature, thinking, type }

        • signature: string

        • thinking: string

        • type: "thinking"

          • "thinking"

      • BetaRedactedThinkingBlock object { data, type }

        • data: string

        • type: "redacted_thinking"

          • "redacted_thinking"

      • BetaToolUseBlock object { id, input, name, 2 more }

        • id: string

        • input: map[unknown]

        • name: string

        • type: "tool_use"

          • "tool_use"

        • caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

          Tool invocation directly from the model.

          • BetaDirectCaller object { type }

            Tool invocation directly from the model.

            • type: "direct"

              • "direct"

          • BetaServerToolCaller object { tool_id, type }

            Tool invocation generated by a server-side tool.

            • tool_id: string

            • type: "code_execution_20250825"

              • "code_execution_20250825"

          • BetaServerToolCaller20260120 object { tool_id, type }

            • tool_id: string

            • type: "code_execution_20260120"

              • "code_execution_20260120"

      • BetaServerToolUseBlock object { id, input, name, 2 more }

        • id: string

        • input: map[unknown]

        • name: "advisor" or "web_search" or "web_fetch" or 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: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

          Tool invocation directly from the model.

          • BetaDirectCaller object { type }

            Tool invocation directly from the model.

          • BetaServerToolCaller object { tool_id, type }

            Tool invocation generated by a server-side tool.

          • BetaServerToolCaller20260120 object { tool_id, type }

      • BetaWebSearchToolResultBlock object { content, tool_use_id, type, caller }

        • content: BetaWebSearchToolResultBlockContent

          • BetaWebSearchToolResultError object { error_code, type }

            • 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 of BetaWebSearchResultBlock

            • encrypted_content: string

            • page_age: string

            • 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: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

          Tool invocation directly from the model.

          • BetaDirectCaller object { type }

            Tool invocation directly from the model.

          • BetaServerToolCaller object { tool_id, type }

            Tool invocation generated by a server-side tool.

          • BetaServerToolCaller20260120 object { tool_id, type }

      • BetaWebFetchToolResultBlock object { content, tool_use_id, type, caller }

        • content: BetaWebFetchToolResultErrorBlock or BetaWebFetchBlock

          • BetaWebFetchToolResultErrorBlock object { error_code, type }

            • error_code: BetaWebFetchToolResultErrorCode

              • "invalid_tool_input"

              • "url_too_long"

              • "url_not_allowed"

              • "url_not_accessible"

              • "unsupported_content_type"

              • "too_many_requests"

              • "max_uses_exceeded"

              • "unavailable"

            • type: "web_fetch_tool_result_error"

              • "web_fetch_tool_result_error"

          • BetaWebFetchBlock object { content, retrieved_at, type, url }

            • content: BetaDocumentBlock

              • citations: BetaCitationConfig

                Citation configuration for the document

                • enabled: boolean

              • source: BetaBase64PDFSource or BetaPlainTextSource

                • BetaBase64PDFSource object { data, media_type, type }

                  • data: string

                  • media_type: "application/pdf"

                    • "application/pdf"

                  • type: "base64"

                    • "base64"

                • BetaPlainTextSource object { data, media_type, type }

                  • data: string

                  • media_type: "text/plain"

                    • "text/plain"

                  • type: "text"

                    • "text"

              • title: string

                The title of the document

              • type: "document"

                • "document"

            • retrieved_at: string

              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: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

          Tool invocation directly from the model.

          • BetaDirectCaller object { type }

            Tool invocation directly from the model.

          • BetaServerToolCaller object { tool_id, type }

            Tool invocation generated by a server-side tool.

          • BetaServerToolCaller20260120 object { tool_id, type }

      • BetaAdvisorToolResultBlock object { content, tool_use_id, type }

        • content: BetaAdvisorToolResultError or BetaAdvisorResultBlock or BetaAdvisorRedactedResultBlock

          • BetaAdvisorToolResultError object { error_code, type }

            • error_code: "max_uses_exceeded" or "prompt_too_long" or "too_many_requests" or 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 object { text, type }

            • text: string

            • type: "advisor_result"

              • "advisor_result"

          • BetaAdvisorRedactedResultBlock object { encrypted_content, type }

            • encrypted_content: string

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

            • type: "advisor_redacted_result"

              • "advisor_redacted_result"

        • tool_use_id: string

        • type: "advisor_tool_result"

          • "advisor_tool_result"

      • BetaCodeExecutionToolResultBlock object { content, tool_use_id, type }

        • content: BetaCodeExecutionToolResultBlockContent

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

          • BetaCodeExecutionToolResultError object { error_code, type }

            • 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 object { content, return_code, stderr, 2 more }

            • content: array of BetaCodeExecutionOutputBlock

              • 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 object { content, encrypted_stdout, return_code, 2 more }

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

            • content: array of BetaCodeExecutionOutputBlock

              • 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 object { content, tool_use_id, type }

        • content: BetaBashCodeExecutionToolResultError or BetaBashCodeExecutionResultBlock

          • BetaBashCodeExecutionToolResultError object { error_code, type }

            • error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 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 object { content, return_code, stderr, 2 more }

            • content: array of BetaBashCodeExecutionOutputBlock

              • 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 object { content, tool_use_id, type }

        • content: BetaTextEditorCodeExecutionToolResultError or BetaTextEditorCodeExecutionViewResultBlock or BetaTextEditorCodeExecutionCreateResultBlock or BetaTextEditorCodeExecutionStrReplaceResultBlock

          • BetaTextEditorCodeExecutionToolResultError object { error_code, error_message, type }

            • error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more

              • "invalid_tool_input"

              • "unavailable"

              • "too_many_requests"

              • "execution_time_exceeded"

              • "file_not_found"

            • error_message: string

            • type: "text_editor_code_execution_tool_result_error"

              • "text_editor_code_execution_tool_result_error"

          • BetaTextEditorCodeExecutionViewResultBlock object { content, file_type, num_lines, 3 more }

            • content: string

            • file_type: "text" or "image" or "pdf"

              • "text"

              • "image"

              • "pdf"

            • num_lines: number

            • start_line: number

            • total_lines: number

            • type: "text_editor_code_execution_view_result"

              • "text_editor_code_execution_view_result"

          • BetaTextEditorCodeExecutionCreateResultBlock object { is_file_update, type }

            • is_file_update: boolean

            • type: "text_editor_code_execution_create_result"

              • "text_editor_code_execution_create_result"

          • BetaTextEditorCodeExecutionStrReplaceResultBlock object { lines, new_lines, new_start, 3 more }

            • lines: array of string

            • new_lines: number

            • new_start: number

            • old_lines: number

            • old_start: number

            • 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 object { content, tool_use_id, type }

        • content: BetaToolSearchToolResultError or BetaToolSearchToolSearchResultBlock

          • BetaToolSearchToolResultError object { error_code, error_message, type }

            • error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"

              • "invalid_tool_input"

              • "unavailable"

              • "too_many_requests"

              • "execution_time_exceeded"

            • error_message: string

            • type: "tool_search_tool_result_error"

              • "tool_search_tool_result_error"

          • BetaToolSearchToolSearchResultBlock object { tool_references, type }

            • tool_references: array of BetaToolReferenceBlock

              • 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 object { id, input, name, 2 more }

        • id: string

        • input: map[unknown]

        • 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 object { content, is_error, tool_use_id, type }

        • content: string or array of BetaTextBlock

          • string

          • BetaMCPToolResultBlockContent = array of BetaTextBlock

            • citations: array of BetaTextCitation

              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 object { file_id, type }

        Response model for a file uploaded to the container.

        • file_id: string

        • type: "container_upload"

          • "container_upload"

      • BetaCompactionBlock object { content, encrypted_content, type }

        A compaction block returned when autocompact is triggered.

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

        • content: string

          Summary of compacted content, or null if compaction failed

        • encrypted_content: string

          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 object { index, type }

    • index: number

    • type: "content_block_stop"

      • "content_block_stop"

Beta Raw Message Delta Event

  • BetaRawMessageDeltaEvent object { context_management, delta, type, usage }

    • context_management: BetaContextManagementResponse

      Information about context management strategies applied during the request

      • applied_edits: array of BetaClearToolUses20250919EditResponse or BetaClearThinking20251015EditResponse

        List of context management edits that were applied.

        • BetaClearToolUses20250919EditResponse object { cleared_input_tokens, cleared_tool_uses, type }

          • cleared_input_tokens: number

            Number of input tokens cleared by this edit.

          • cleared_tool_uses: number

            Number of tool uses that were cleared.

          • type: "clear_tool_uses_20250919"

            The type of context management edit applied.

            • "clear_tool_uses_20250919"

        • BetaClearThinking20251015EditResponse object { cleared_input_tokens, cleared_thinking_turns, type }

          • cleared_input_tokens: number

            Number of input tokens cleared by this edit.

          • cleared_thinking_turns: number

            Number of thinking turns that were cleared.

          • type: "clear_thinking_20251015"

            The type of context management edit applied.

            • "clear_thinking_20251015"

    • delta: object { container, stop_details, stop_reason, stop_sequence }

      • 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 of BetaSkill

          Skills loaded in the container

          • skill_id: string

            Skill ID

          • type: "anthropic" or "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

        Structured information about a refusal.

        • category: "cyber" or "bio"

          The policy category that triggered the refusal.

          null when the refusal doesn't map to a named category.

          • "cyber"

          • "bio"

        • explanation: string

          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

        • "end_turn"

        • "max_tokens"

        • "stop_sequence"

        • "tool_use"

        • "pause_turn"

        • "compaction"

        • "refusal"

        • "model_context_window_exceeded"

      • stop_sequence: string

    • 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

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

      • cache_read_input_tokens: number

        The cumulative number of input tokens read from the cache.

      • input_tokens: number

        The cumulative number of input tokens which were used.

      • iterations: BetaIterationsUsage

        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 object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }

          Token usage for a sampling iteration.

          • cache_creation: BetaCacheCreation

            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 object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }

          Token usage for a compaction iteration.

          • cache_creation: BetaCacheCreation

            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 object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 4 more }

          Token usage for an advisor sub-inference iteration.

          • cache_creation: BetaCacheCreation

            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 for additional details and options.

            • "claude-opus-4-7" or "claude-mythos-preview" or "claude-opus-4-6" or 14 more

              The model that will complete your prompt.

              See models for additional details and options.

              • "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.

      • server_tool_use: BetaServerToolUsage

        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 object { message, type }

    • message: BetaMessage

      • id: string

        Unique object identifier.

        The format and length of IDs may change over time.

      • 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 of BetaSkill

          Skills loaded in the container

          • skill_id: string

            Skill ID

          • type: "anthropic" or "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 of BetaContentBlock

        Content generated by the model.

        This is an array of content blocks, each of which has a type that determines its shape.

        Example:

        [{"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:

        [
  {"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:

        [{"type": "text", "text": "B)"}]

        • BetaTextBlock object { citations, text, type }

          • citations: array of BetaTextCitation

            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 object { cited_text, document_index, document_title, 4 more }

              • cited_text: string

              • document_index: number

              • document_title: string

              • end_char_index: number

              • file_id: string

              • start_char_index: number

              • type: "char_location"

                • "char_location"

            • BetaCitationPageLocation object { cited_text, document_index, document_title, 4 more }

              • cited_text: string

              • document_index: number

              • document_title: string

              • end_page_number: number

              • file_id: string

              • start_page_number: number

              • type: "page_location"

                • "page_location"

            • BetaCitationContentBlockLocation object { cited_text, document_index, document_title, 4 more }

              • 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

              • 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

              • 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 object { cited_text, encrypted_index, title, 2 more }

              • cited_text: string

              • encrypted_index: string

              • title: string

              • type: "web_search_result_location"

                • "web_search_result_location"

              • url: string

            • BetaCitationSearchResultLocation object { cited_text, end_block_index, search_result_index, 4 more }

              • 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

              • type: "search_result_location"

                • "search_result_location"

          • text: string

          • type: "text"

            • "text"

        • BetaThinkingBlock object { signature, thinking, type }

          • signature: string

          • thinking: string

          • type: "thinking"

            • "thinking"

        • BetaRedactedThinkingBlock object { data, type }

          • data: string

          • type: "redacted_thinking"

            • "redacted_thinking"

        • BetaToolUseBlock object { id, input, name, 2 more }

          • id: string

          • input: map[unknown]

          • name: string

          • type: "tool_use"

            • "tool_use"

          • caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

            Tool invocation directly from the model.

            • BetaDirectCaller object { type }

              Tool invocation directly from the model.

              • type: "direct"

                • "direct"

            • BetaServerToolCaller object { tool_id, type }

              Tool invocation generated by a server-side tool.

              • tool_id: string

              • type: "code_execution_20250825"

                • "code_execution_20250825"

            • BetaServerToolCaller20260120 object { tool_id, type }

              • tool_id: string

              • type: "code_execution_20260120"

                • "code_execution_20260120"

        • BetaServerToolUseBlock object { id, input, name, 2 more }

          • id: string

          • input: map[unknown]

          • name: "advisor" or "web_search" or "web_fetch" or 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: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

            Tool invocation directly from the model.

            • BetaDirectCaller object { type }

              Tool invocation directly from the model.

            • BetaServerToolCaller object { tool_id, type }

              Tool invocation generated by a server-side tool.

            • BetaServerToolCaller20260120 object { tool_id, type }

        • BetaWebSearchToolResultBlock object { content, tool_use_id, type, caller }

          • content: BetaWebSearchToolResultBlockContent

            • BetaWebSearchToolResultError object { error_code, type }

              • 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 of BetaWebSearchResultBlock

              • encrypted_content: string

              • page_age: string

              • 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: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

            Tool invocation directly from the model.

            • BetaDirectCaller object { type }

              Tool invocation directly from the model.

            • BetaServerToolCaller object { tool_id, type }

              Tool invocation generated by a server-side tool.

            • BetaServerToolCaller20260120 object { tool_id, type }

        • BetaWebFetchToolResultBlock object { content, tool_use_id, type, caller }

          • content: BetaWebFetchToolResultErrorBlock or BetaWebFetchBlock

            • BetaWebFetchToolResultErrorBlock object { error_code, type }

              • error_code: BetaWebFetchToolResultErrorCode

                • "invalid_tool_input"

                • "url_too_long"

                • "url_not_allowed"

                • "url_not_accessible"

                • "unsupported_content_type"

                • "too_many_requests"

                • "max_uses_exceeded"

                • "unavailable"

              • type: "web_fetch_tool_result_error"

                • "web_fetch_tool_result_error"

            • BetaWebFetchBlock object { content, retrieved_at, type, url }

              • content: BetaDocumentBlock

                • citations: BetaCitationConfig

                  Citation configuration for the document

                  • enabled: boolean

                • source: BetaBase64PDFSource or BetaPlainTextSource

                  • BetaBase64PDFSource object { data, media_type, type }

                    • data: string

                    • media_type: "application/pdf"

                      • "application/pdf"

                    • type: "base64"

                      • "base64"

                  • BetaPlainTextSource object { data, media_type, type }

                    • data: string

                    • media_type: "text/plain"

                      • "text/plain"

                    • type: "text"

                      • "text"

                • title: string

                  The title of the document

                • type: "document"

                  • "document"

              • retrieved_at: string

                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: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

            Tool invocation directly from the model.

            • BetaDirectCaller object { type }

              Tool invocation directly from the model.

            • BetaServerToolCaller object { tool_id, type }

              Tool invocation generated by a server-side tool.

            • BetaServerToolCaller20260120 object { tool_id, type }

        • BetaAdvisorToolResultBlock object { content, tool_use_id, type }

          • content: BetaAdvisorToolResultError or BetaAdvisorResultBlock or BetaAdvisorRedactedResultBlock

            • BetaAdvisorToolResultError object { error_code, type }

              • error_code: "max_uses_exceeded" or "prompt_too_long" or "too_many_requests" or 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 object { text, type }

              • text: string

              • type: "advisor_result"

                • "advisor_result"

            • BetaAdvisorRedactedResultBlock object { encrypted_content, type }

              • encrypted_content: string

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

              • type: "advisor_redacted_result"

                • "advisor_redacted_result"

          • tool_use_id: string

          • type: "advisor_tool_result"

            • "advisor_tool_result"

        • BetaCodeExecutionToolResultBlock object { content, tool_use_id, type }

          • content: BetaCodeExecutionToolResultBlockContent

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

            • BetaCodeExecutionToolResultError object { error_code, type }

              • 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 object { content, return_code, stderr, 2 more }

              • content: array of BetaCodeExecutionOutputBlock

                • 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 object { content, encrypted_stdout, return_code, 2 more }

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

              • content: array of BetaCodeExecutionOutputBlock

                • 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 object { content, tool_use_id, type }

          • content: BetaBashCodeExecutionToolResultError or BetaBashCodeExecutionResultBlock

            • BetaBashCodeExecutionToolResultError object { error_code, type }

              • error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 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 object { content, return_code, stderr, 2 more }

              • content: array of BetaBashCodeExecutionOutputBlock

                • 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 object { content, tool_use_id, type }

          • content: BetaTextEditorCodeExecutionToolResultError or BetaTextEditorCodeExecutionViewResultBlock or BetaTextEditorCodeExecutionCreateResultBlock or BetaTextEditorCodeExecutionStrReplaceResultBlock

            • BetaTextEditorCodeExecutionToolResultError object { error_code, error_message, type }

              • error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more

                • "invalid_tool_input"

                • "unavailable"

                • "too_many_requests"

                • "execution_time_exceeded"

                • "file_not_found"

              • error_message: string

              • type: "text_editor_code_execution_tool_result_error"

                • "text_editor_code_execution_tool_result_error"

            • BetaTextEditorCodeExecutionViewResultBlock object { content, file_type, num_lines, 3 more }

              • content: string

              • file_type: "text" or "image" or "pdf"

                • "text"

                • "image"

                • "pdf"

              • num_lines: number

              • start_line: number

              • total_lines: number

              • type: "text_editor_code_execution_view_result"

                • "text_editor_code_execution_view_result"

            • BetaTextEditorCodeExecutionCreateResultBlock object { is_file_update, type }

              • is_file_update: boolean

              • type: "text_editor_code_execution_create_result"

                • "text_editor_code_execution_create_result"

            • BetaTextEditorCodeExecutionStrReplaceResultBlock object { lines, new_lines, new_start, 3 more }

              • lines: array of string

              • new_lines: number

              • new_start: number

              • old_lines: number

              • old_start: number

              • 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 object { content, tool_use_id, type }

          • content: BetaToolSearchToolResultError or BetaToolSearchToolSearchResultBlock

            • BetaToolSearchToolResultError object { error_code, error_message, type }

              • error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"

                • "invalid_tool_input"

                • "unavailable"

                • "too_many_requests"

                • "execution_time_exceeded"

              • error_message: string

              • type: "tool_search_tool_result_error"

                • "tool_search_tool_result_error"

            • BetaToolSearchToolSearchResultBlock object { tool_references, type }

              • tool_references: array of BetaToolReferenceBlock

                • 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 object { id, input, name, 2 more }

          • id: string

          • input: map[unknown]

          • 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 object { content, is_error, tool_use_id, type }

          • content: string or array of BetaTextBlock

            • string

            • BetaMCPToolResultBlockContent = array of BetaTextBlock

              • citations: array of BetaTextCitation

                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 object { file_id, type }

          Response model for a file uploaded to the container.

          • file_id: string

          • type: "container_upload"

            • "container_upload"

        • BetaCompactionBlock object { content, encrypted_content, type }

          A compaction block returned when autocompact is triggered.

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

          • content: string

            Summary of compacted content, or null if compaction failed

          • encrypted_content: string

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

          • type: "compaction"

            • "compaction"

      • context_management: BetaContextManagementResponse

        Context management response.

        Information about context management strategies applied during the request.

        • applied_edits: array of BetaClearToolUses20250919EditResponse or BetaClearThinking20251015EditResponse

          List of context management edits that were applied.

          • BetaClearToolUses20250919EditResponse object { cleared_input_tokens, cleared_tool_uses, type }

            • cleared_input_tokens: number

              Number of input tokens cleared by this edit.

            • cleared_tool_uses: number

              Number of tool uses that were cleared.

            • type: "clear_tool_uses_20250919"

              The type of context management edit applied.

              • "clear_tool_uses_20250919"

          • BetaClearThinking20251015EditResponse object { cleared_input_tokens, cleared_thinking_turns, type }

            • cleared_input_tokens: number

              Number of input tokens cleared by this edit.

            • cleared_thinking_turns: number

              Number of thinking turns that were cleared.

            • type: "clear_thinking_20251015"

              The type of context management edit applied.

              • "clear_thinking_20251015"

      • diagnostics: BetaDiagnostics

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

        • cache_miss_reason: BetaCacheMissModelChanged or BetaCacheMissSystemChanged or BetaCacheMissToolsChanged or 3 more

          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 object { cache_missed_input_tokens, type }

            • 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 object { cache_missed_input_tokens, type }

            • 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 object { cache_missed_input_tokens, type }

            • 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 object { cache_missed_input_tokens, type }

            • 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 object { type }

            • type: "previous_message_not_found"

              • "previous_message_not_found"

          • BetaCacheMissUnavailable object { type }

            • type: "unavailable"

              • "unavailable"

      • model: Model

        The model that will complete your prompt.

        See models for additional details and options.

        • "claude-opus-4-7" or "claude-mythos-preview" or "claude-opus-4-6" or 14 more

          The model that will complete your prompt.

          See models for additional details and options.

          • "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

        Structured information about a refusal.

        • category: "cyber" or "bio"

          The policy category that triggered the refusal.

          null when the refusal doesn't map to a named category.

          • "cyber"

          • "bio"

        • explanation: string

          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

        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

        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

          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.

        • inference_geo: string

          The geographic region where inference was performed for this request.

        • input_tokens: number

          The number of input tokens which were used.

        • iterations: BetaIterationsUsage

          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 object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }

            Token usage for a sampling iteration.

            • cache_creation: BetaCacheCreation

              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 object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }

            Token usage for a compaction iteration.

            • cache_creation: BetaCacheCreation

              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 object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 4 more }

            Token usage for an advisor sub-inference iteration.

            • cache_creation: BetaCacheCreation

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

        • server_tool_use: BetaServerToolUsage

          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" or "priority" or "batch"

          If the request used the priority, standard, or batch tier.

          • "standard"

          • "priority"

          • "batch"

        • speed: "standard" or "fast"

          The inference speed mode used for this request.

          • "standard"

          • "fast"

    • type: "message_start"

      • "message_start"

Beta Raw Message Stop Event

  • BetaRawMessageStopEvent object { type }

    • type: "message_stop"

      • "message_stop"

Beta Raw Message Stream Event

  • BetaRawMessageStreamEvent = BetaRawMessageStartEvent or BetaRawMessageDeltaEvent or BetaRawMessageStopEvent or 3 more

    • BetaRawMessageStartEvent object { message, type }

      • message: BetaMessage

        • id: string

          Unique object identifier.

          The format and length of IDs may change over time.

        • 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 of BetaSkill

            Skills loaded in the container

            • skill_id: string

              Skill ID

            • type: "anthropic" or "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 of BetaContentBlock

          Content generated by the model.

          This is an array of content blocks, each of which has a type that determines its shape.

          Example:

          [{"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:

          [
  {"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:

          [{"type": "text", "text": "B)"}]

          • BetaTextBlock object { citations, text, type }

            • citations: array of BetaTextCitation

              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 object { cited_text, document_index, document_title, 4 more }

                • cited_text: string

                • document_index: number

                • document_title: string

                • end_char_index: number

                • file_id: string

                • start_char_index: number

                • type: "char_location"

                  • "char_location"

              • BetaCitationPageLocation object { cited_text, document_index, document_title, 4 more }

                • cited_text: string

                • document_index: number

                • document_title: string

                • end_page_number: number

                • file_id: string

                • start_page_number: number

                • type: "page_location"

                  • "page_location"

              • BetaCitationContentBlockLocation object { cited_text, document_index, document_title, 4 more }

                • 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

                • 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

                • 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 object { cited_text, encrypted_index, title, 2 more }

                • cited_text: string

                • encrypted_index: string

                • title: string

                • type: "web_search_result_location"

                  • "web_search_result_location"

                • url: string

              • BetaCitationSearchResultLocation object { cited_text, end_block_index, search_result_index, 4 more }

                • 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

                • type: "search_result_location"

                  • "search_result_location"

            • text: string

            • type: "text"

              • "text"

          • BetaThinkingBlock object { signature, thinking, type }

            • signature: string

            • thinking: string

            • type: "thinking"

              • "thinking"

          • BetaRedactedThinkingBlock object { data, type }

            • data: string

            • type: "redacted_thinking"

              • "redacted_thinking"

          • BetaToolUseBlock object { id, input, name, 2 more }

            • id: string

            • input: map[unknown]

            • name: string

            • type: "tool_use"

              • "tool_use"

            • caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

              Tool invocation directly from the model.

              • BetaDirectCaller object { type }

                Tool invocation directly from the model.

                • type: "direct"

                  • "direct"

              • BetaServerToolCaller object { tool_id, type }

                Tool invocation generated by a server-side tool.

                • tool_id: string

                • type: "code_execution_20250825"

                  • "code_execution_20250825"

              • BetaServerToolCaller20260120 object { tool_id, type }

                • tool_id: string

                • type: "code_execution_20260120"

                  • "code_execution_20260120"

          • BetaServerToolUseBlock object { id, input, name, 2 more }

            • id: string

            • input: map[unknown]

            • name: "advisor" or "web_search" or "web_fetch" or 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: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

              Tool invocation directly from the model.

              • BetaDirectCaller object { type }

                Tool invocation directly from the model.

              • BetaServerToolCaller object { tool_id, type }

                Tool invocation generated by a server-side tool.

              • BetaServerToolCaller20260120 object { tool_id, type }

          • BetaWebSearchToolResultBlock object { content, tool_use_id, type, caller }

            • content: BetaWebSearchToolResultBlockContent

              • BetaWebSearchToolResultError object { error_code, type }

                • 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 of BetaWebSearchResultBlock

                • encrypted_content: string

                • page_age: string

                • 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: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

              Tool invocation directly from the model.

              • BetaDirectCaller object { type }

                Tool invocation directly from the model.

              • BetaServerToolCaller object { tool_id, type }

                Tool invocation generated by a server-side tool.

              • BetaServerToolCaller20260120 object { tool_id, type }

          • BetaWebFetchToolResultBlock object { content, tool_use_id, type, caller }

            • content: BetaWebFetchToolResultErrorBlock or BetaWebFetchBlock

              • BetaWebFetchToolResultErrorBlock object { error_code, type }

                • error_code: BetaWebFetchToolResultErrorCode

                  • "invalid_tool_input"

                  • "url_too_long"

                  • "url_not_allowed"

                  • "url_not_accessible"

                  • "unsupported_content_type"

                  • "too_many_requests"

                  • "max_uses_exceeded"

                  • "unavailable"

                • type: "web_fetch_tool_result_error"

                  • "web_fetch_tool_result_error"

              • BetaWebFetchBlock object { content, retrieved_at, type, url }

                • content: BetaDocumentBlock

                  • citations: BetaCitationConfig

                    Citation configuration for the document

                    • enabled: boolean

                  • source: BetaBase64PDFSource or BetaPlainTextSource

                    • BetaBase64PDFSource object { data, media_type, type }

                      • data: string

                      • media_type: "application/pdf"

                        • "application/pdf"

                      • type: "base64"

                        • "base64"

                    • BetaPlainTextSource object { data, media_type, type }

                      • data: string

                      • media_type: "text/plain"

                        • "text/plain"

                      • type: "text"

                        • "text"

                  • title: string

                    The title of the document

                  • type: "document"

                    • "document"

                • retrieved_at: string

                  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: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

              Tool invocation directly from the model.

              • BetaDirectCaller object { type }

                Tool invocation directly from the model.

              • BetaServerToolCaller object { tool_id, type }

                Tool invocation generated by a server-side tool.

              • BetaServerToolCaller20260120 object { tool_id, type }

          • BetaAdvisorToolResultBlock object { content, tool_use_id, type }

            • content: BetaAdvisorToolResultError or BetaAdvisorResultBlock or BetaAdvisorRedactedResultBlock

              • BetaAdvisorToolResultError object { error_code, type }

                • error_code: "max_uses_exceeded" or "prompt_too_long" or "too_many_requests" or 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 object { text, type }

                • text: string

                • type: "advisor_result"

                  • "advisor_result"

              • BetaAdvisorRedactedResultBlock object { encrypted_content, type }

                • encrypted_content: string

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

                • type: "advisor_redacted_result"

                  • "advisor_redacted_result"

            • tool_use_id: string

            • type: "advisor_tool_result"

              • "advisor_tool_result"

          • BetaCodeExecutionToolResultBlock object { content, tool_use_id, type }

            • content: BetaCodeExecutionToolResultBlockContent

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

              • BetaCodeExecutionToolResultError object { error_code, type }

                • 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 object { content, return_code, stderr, 2 more }

                • content: array of BetaCodeExecutionOutputBlock

                  • 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 object { content, encrypted_stdout, return_code, 2 more }

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

                • content: array of BetaCodeExecutionOutputBlock

                  • 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 object { content, tool_use_id, type }

            • content: BetaBashCodeExecutionToolResultError or BetaBashCodeExecutionResultBlock

              • BetaBashCodeExecutionToolResultError object { error_code, type }

                • error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 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 object { content, return_code, stderr, 2 more }

                • content: array of BetaBashCodeExecutionOutputBlock

                  • 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 object { content, tool_use_id, type }

            • content: BetaTextEditorCodeExecutionToolResultError or BetaTextEditorCodeExecutionViewResultBlock or BetaTextEditorCodeExecutionCreateResultBlock or BetaTextEditorCodeExecutionStrReplaceResultBlock

              • BetaTextEditorCodeExecutionToolResultError object { error_code, error_message, type }

                • error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more

                  • "invalid_tool_input"

                  • "unavailable"

                  • "too_many_requests"

                  • "execution_time_exceeded"

                  • "file_not_found"

                • error_message: string

                • type: "text_editor_code_execution_tool_result_error"

                  • "text_editor_code_execution_tool_result_error"

              • BetaTextEditorCodeExecutionViewResultBlock object { content, file_type, num_lines, 3 more }

                • content: string

                • file_type: "text" or "image" or "pdf"

                  • "text"

                  • "image"

                  • "pdf"

                • num_lines: number

                • start_line: number

                • total_lines: number

                • type: "text_editor_code_execution_view_result"

                  • "text_editor_code_execution_view_result"

              • BetaTextEditorCodeExecutionCreateResultBlock object { is_file_update, type }

                • is_file_update: boolean

                • type: "text_editor_code_execution_create_result"

                  • "text_editor_code_execution_create_result"

              • BetaTextEditorCodeExecutionStrReplaceResultBlock object { lines, new_lines, new_start, 3 more }

                • lines: array of string

                • new_lines: number

                • new_start: number

                • old_lines: number

                • old_start: number

                • 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 object { content, tool_use_id, type }

            • content: BetaToolSearchToolResultError or BetaToolSearchToolSearchResultBlock

              • BetaToolSearchToolResultError object { error_code, error_message, type }

                • error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"

                  • "invalid_tool_input"

                  • "unavailable"

                  • "too_many_requests"

                  • "execution_time_exceeded"

                • error_message: string

                • type: "tool_search_tool_result_error"

                  • "tool_search_tool_result_error"

              • BetaToolSearchToolSearchResultBlock object { tool_references, type }

                • tool_references: array of BetaToolReferenceBlock

                  • 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 object { id, input, name, 2 more }

            • id: string

            • input: map[unknown]

            • 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 object { content, is_error, tool_use_id, type }

            • content: string or array of BetaTextBlock

              • string

              • BetaMCPToolResultBlockContent = array of BetaTextBlock

                • citations: array of BetaTextCitation

                  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 object { file_id, type }

            Response model for a file uploaded to the container.

            • file_id: string

            • type: "container_upload"

              • "container_upload"

          • BetaCompactionBlock object { content, encrypted_content, type }

            A compaction block returned when autocompact is triggered.

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

            • content: string

              Summary of compacted content, or null if compaction failed

            • encrypted_content: string

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

            • type: "compaction"

              • "compaction"

        • context_management: BetaContextManagementResponse

          Context management response.

          Information about context management strategies applied during the request.

          • applied_edits: array of BetaClearToolUses20250919EditResponse or BetaClearThinking20251015EditResponse

            List of context management edits that were applied.

            • BetaClearToolUses20250919EditResponse object { cleared_input_tokens, cleared_tool_uses, type }

              • cleared_input_tokens: number

                Number of input tokens cleared by this edit.

              • cleared_tool_uses: number

                Number of tool uses that were cleared.

              • type: "clear_tool_uses_20250919"

                The type of context management edit applied.

                • "clear_tool_uses_20250919"

            • BetaClearThinking20251015EditResponse object { cleared_input_tokens, cleared_thinking_turns, type }

              • cleared_input_tokens: number

                Number of input tokens cleared by this edit.

              • cleared_thinking_turns: number

                Number of thinking turns that were cleared.

              • type: "clear_thinking_20251015"

                The type of context management edit applied.

                • "clear_thinking_20251015"

        • diagnostics: BetaDiagnostics

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

          • cache_miss_reason: BetaCacheMissModelChanged or BetaCacheMissSystemChanged or BetaCacheMissToolsChanged or 3 more

            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 object { cache_missed_input_tokens, type }

              • 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 object { cache_missed_input_tokens, type }

              • 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 object { cache_missed_input_tokens, type }

              • 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 object { cache_missed_input_tokens, type }

              • 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 object { type }

              • type: "previous_message_not_found"

                • "previous_message_not_found"

            • BetaCacheMissUnavailable object { type }

              • type: "unavailable"

                • "unavailable"

        • model: Model

          The model that will complete your prompt.

          See models for additional details and options.

          • "claude-opus-4-7" or "claude-mythos-preview" or "claude-opus-4-6" or 14 more

            The model that will complete your prompt.

            See models for additional details and options.

            • "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

          Structured information about a refusal.

          • category: "cyber" or "bio"

            The policy category that triggered the refusal.

            null when the refusal doesn't map to a named category.

            • "cyber"

            • "bio"

          • explanation: string

            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

          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

          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

            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.

          • inference_geo: string

            The geographic region where inference was performed for this request.

          • input_tokens: number

            The number of input tokens which were used.

          • iterations: BetaIterationsUsage

            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 object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }

              Token usage for a sampling iteration.

              • cache_creation: BetaCacheCreation

                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 object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }

              Token usage for a compaction iteration.

              • cache_creation: BetaCacheCreation

                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 object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 4 more }

              Token usage for an advisor sub-inference iteration.

              • cache_creation: BetaCacheCreation

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

          • server_tool_use: BetaServerToolUsage

            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" or "priority" or "batch"

            If the request used the priority, standard, or batch tier.

            • "standard"

            • "priority"

            • "batch"

          • speed: "standard" or "fast"

            The inference speed mode used for this request.

            • "standard"

            • "fast"

      • type: "message_start"

        • "message_start"

    • BetaRawMessageDeltaEvent object { context_management, delta, type, usage }

      • context_management: BetaContextManagementResponse

        Information about context management strategies applied during the request

      • delta: object { container, stop_details, stop_reason, stop_sequence }

        • container: BetaContainer

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

        • stop_details: BetaRefusalStopDetails

          Structured information about a refusal.

        • stop_reason: BetaStopReason

        • stop_sequence: string

      • 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

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

        • cache_read_input_tokens: number

          The cumulative number of input tokens read from the cache.

        • input_tokens: number

          The cumulative number of input tokens which were used.

        • iterations: BetaIterationsUsage

          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.

        • server_tool_use: BetaServerToolUsage

          The number of server tool requests.

    • BetaRawMessageStopEvent object { type }

      • type: "message_stop"

        • "message_stop"

    • BetaRawContentBlockStartEvent object { content_block, index, type }

      • content_block: BetaTextBlock or BetaThinkingBlock or BetaRedactedThinkingBlock or 13 more

        Response model for a file uploaded to the container.

        • BetaTextBlock object { citations, text, type }

        • BetaThinkingBlock object { signature, thinking, type }

        • BetaRedactedThinkingBlock object { data, type }

        • BetaToolUseBlock object { id, input, name, 2 more }

        • BetaServerToolUseBlock object { id, input, name, 2 more }

        • BetaWebSearchToolResultBlock object { content, tool_use_id, type, caller }

        • BetaWebFetchToolResultBlock object { content, tool_use_id, type, caller }

        • BetaAdvisorToolResultBlock object { content, tool_use_id, type }

        • BetaCodeExecutionToolResultBlock object { content, tool_use_id, type }

        • BetaBashCodeExecutionToolResultBlock object { content, tool_use_id, type }

        • BetaTextEditorCodeExecutionToolResultBlock object { content, tool_use_id, type }

        • BetaToolSearchToolResultBlock object { content, tool_use_id, type }

        • BetaMCPToolUseBlock object { id, input, name, 2 more }

        • BetaMCPToolResultBlock object { content, is_error, tool_use_id, type }

        • BetaContainerUploadBlock object { file_id, type }

          Response model for a file uploaded to the container.

        • BetaCompactionBlock object { content, encrypted_content, type }

          A compaction block returned when autocompact is triggered.

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

      • index: number

      • type: "content_block_start"

        • "content_block_start"

    • BetaRawContentBlockDeltaEvent object { delta, index, type }

      • delta: BetaRawContentBlockDelta

        • BetaTextDelta object { text, type }

          • text: string

          • type: "text_delta"

            • "text_delta"

        • BetaInputJSONDelta object { partial_json, type }

          • partial_json: string

          • type: "input_json_delta"

            • "input_json_delta"

        • BetaCitationsDelta object { citation, type }

          • citation: BetaCitationCharLocation or BetaCitationPageLocation or BetaCitationContentBlockLocation or 2 more

            • BetaCitationCharLocation object { cited_text, document_index, document_title, 4 more }

            • BetaCitationPageLocation object { cited_text, document_index, document_title, 4 more }

            • BetaCitationContentBlockLocation object { cited_text, document_index, document_title, 4 more }

            • BetaCitationsWebSearchResultLocation object { cited_text, encrypted_index, title, 2 more }

            • BetaCitationSearchResultLocation object { cited_text, end_block_index, search_result_index, 4 more }

          • type: "citations_delta"

            • "citations_delta"

        • BetaThinkingDelta object { thinking, type }

          • thinking: string

          • type: "thinking_delta"

            • "thinking_delta"

        • BetaSignatureDelta object { signature, type }

          • signature: string

          • type: "signature_delta"

            • "signature_delta"

        • BetaCompactionContentBlockDelta object { content, encrypted_content, type }

          • content: string

          • encrypted_content: string

            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 object { index, type }

      • index: number

      • type: "content_block_stop"

        • "content_block_stop"

Beta Redacted Thinking Block

  • BetaRedactedThinkingBlock object { data, type }

    • data: string

    • type: "redacted_thinking"

      • "redacted_thinking"

Beta Redacted Thinking Block Param

  • BetaRedactedThinkingBlockParam object { data, type }

    • data: string

    • type: "redacted_thinking"

      • "redacted_thinking"

Beta Refusal Stop Details

  • BetaRefusalStopDetails object { category, explanation, type }

    Structured information about a refusal.

    • category: "cyber" or "bio"

      The policy category that triggered the refusal.

      null when the refusal doesn't map to a named category.

      • "cyber"

      • "bio"

    • explanation: string

      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 object { source, type, cache_control, 3 more }

    • source: BetaBase64PDFSource or BetaPlainTextSource or BetaContentBlockSource or 2 more

      • BetaBase64PDFSource object { data, media_type, type }

        • data: string

        • media_type: "application/pdf"

          • "application/pdf"

        • type: "base64"

          • "base64"

      • BetaPlainTextSource object { data, media_type, type }

        • data: string

        • media_type: "text/plain"

          • "text/plain"

        • type: "text"

          • "text"

      • BetaContentBlockSource object { content, type }

        • content: string or array of BetaContentBlockSourceContent

          • string

          • BetaContentBlockSourceContent = array of BetaContentBlockSourceContent

            • BetaTextBlockParam object { text, type, cache_control, citations }

              • text: string

              • type: "text"

                • "text"

              • cache_control: optional BetaCacheControlEphemeral

                Create a cache control breakpoint at this content block.

                • type: "ephemeral"

                  • "ephemeral"

                • ttl: optional "5m" or "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: optional array of BetaTextCitationParam

                • BetaCitationCharLocationParam object { cited_text, document_index, document_title, 3 more }

                  • cited_text: string

                  • document_index: number

                  • document_title: string

                  • end_char_index: number

                  • start_char_index: number

                  • type: "char_location"

                    • "char_location"

                • BetaCitationPageLocationParam object { cited_text, document_index, document_title, 3 more }

                  • cited_text: string

                  • document_index: number

                  • document_title: string

                  • end_page_number: number

                  • start_page_number: number

                  • type: "page_location"

                    • "page_location"

                • BetaCitationContentBlockLocationParam object { cited_text, document_index, document_title, 3 more }

                  • 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

                  • 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 object { cited_text, encrypted_index, title, 2 more }

                  • cited_text: string

                  • encrypted_index: string

                  • title: string

                  • type: "web_search_result_location"

                    • "web_search_result_location"

                  • url: string

                • BetaCitationSearchResultLocationParam object { cited_text, end_block_index, search_result_index, 4 more }

                  • 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

                  • type: "search_result_location"

                    • "search_result_location"

            • BetaImageBlockParam object { source, type, cache_control }

              • source: BetaBase64ImageSource or BetaURLImageSource or BetaFileImageSource

                • BetaBase64ImageSource object { data, media_type, type }

                  • data: string

                  • media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"

                    • "image/jpeg"

                    • "image/png"

                    • "image/gif"

                    • "image/webp"

                  • type: "base64"

                    • "base64"

                • BetaURLImageSource object { type, url }

                  • type: "url"

                    • "url"

                  • url: string

                • BetaFileImageSource object { file_id, type }

                  • file_id: string

                  • type: "file"

                    • "file"

              • type: "image"

                • "image"

              • cache_control: optional BetaCacheControlEphemeral

                Create a cache control breakpoint at this content block.

        • type: "content"

          • "content"

      • BetaURLPDFSource object { type, url }

        • type: "url"

          • "url"

        • url: string

      • BetaFileDocumentSource object { file_id, type }

        • file_id: string

        • type: "file"

          • "file"

    • type: "document"

      • "document"

    • cache_control: optional BetaCacheControlEphemeral

      Create a cache control breakpoint at this content block.

    • citations: optional BetaCitationsConfigParam

      • enabled: optional boolean

    • context: optional string

    • title: optional string

Beta Request MCP Server Tool Configuration

  • BetaRequestMCPServerToolConfiguration object { allowed_tools, enabled }

    • allowed_tools: optional array of string

    • enabled: optional boolean

Beta Request MCP Server URL Definition

  • BetaRequestMCPServerURLDefinition object { name, type, url, 2 more }

    • name: string

    • type: "url"

      • "url"

    • url: string

    • authorization_token: optional string

    • tool_configuration: optional BetaRequestMCPServerToolConfiguration

      • allowed_tools: optional array of string

      • enabled: optional boolean

Beta Request MCP Tool Result Block Param

  • BetaRequestMCPToolResultBlockParam object { tool_use_id, type, cache_control, 2 more }

    • tool_use_id: string

    • type: "mcp_tool_result"

      • "mcp_tool_result"

    • cache_control: optional BetaCacheControlEphemeral

      Create a cache control breakpoint at this content block.

      • type: "ephemeral"

        • "ephemeral"

      • ttl: optional "5m" or "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: optional string or array of BetaTextBlockParam

      • string

      • BetaMCPToolResultBlockParamContent = array of BetaTextBlockParam

        • text: string

        • type: "text"

          • "text"

        • cache_control: optional BetaCacheControlEphemeral

          Create a cache control breakpoint at this content block.

        • citations: optional array of BetaTextCitationParam

          • BetaCitationCharLocationParam object { cited_text, document_index, document_title, 3 more }

            • cited_text: string

            • document_index: number

            • document_title: string

            • end_char_index: number

            • start_char_index: number

            • type: "char_location"

              • "char_location"

          • BetaCitationPageLocationParam object { cited_text, document_index, document_title, 3 more }

            • cited_text: string

            • document_index: number

            • document_title: string

            • end_page_number: number

            • start_page_number: number

            • type: "page_location"

              • "page_location"

          • BetaCitationContentBlockLocationParam object { cited_text, document_index, document_title, 3 more }

            • 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

            • 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 object { cited_text, encrypted_index, title, 2 more }

            • cited_text: string

            • encrypted_index: string

            • title: string

            • type: "web_search_result_location"

              • "web_search_result_location"

            • url: string

          • BetaCitationSearchResultLocationParam object { cited_text, end_block_index, search_result_index, 4 more }

            • 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

            • type: "search_result_location"

              • "search_result_location"

    • is_error: optional boolean

Beta Search Result Block Param

  • BetaSearchResultBlockParam object { content, source, title, 3 more }

    • content: array of BetaTextBlockParam

      • text: string

      • type: "text"

        • "text"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

        • type: "ephemeral"

          • "ephemeral"

        • ttl: optional "5m" or "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: optional array of BetaTextCitationParam

        • BetaCitationCharLocationParam object { cited_text, document_index, document_title, 3 more }

          • cited_text: string

          • document_index: number

          • document_title: string

          • end_char_index: number

          • start_char_index: number

          • type: "char_location"

            • "char_location"

        • BetaCitationPageLocationParam object { cited_text, document_index, document_title, 3 more }

          • cited_text: string

          • document_index: number

          • document_title: string

          • end_page_number: number

          • start_page_number: number

          • type: "page_location"

            • "page_location"

        • BetaCitationContentBlockLocationParam object { cited_text, document_index, document_title, 3 more }

          • 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

          • 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 object { cited_text, encrypted_index, title, 2 more }

          • cited_text: string

          • encrypted_index: string

          • title: string

          • type: "web_search_result_location"

            • "web_search_result_location"

          • url: string

        • BetaCitationSearchResultLocationParam object { cited_text, end_block_index, search_result_index, 4 more }

          • 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

          • type: "search_result_location"

            • "search_result_location"

    • source: string

    • title: string

    • type: "search_result"

      • "search_result"

    • cache_control: optional BetaCacheControlEphemeral

      Create a cache control breakpoint at this content block.

    • citations: optional BetaCitationsConfigParam

      • enabled: optional boolean

Beta Server Tool Caller

  • BetaServerToolCaller object { tool_id, type }

    Tool invocation generated by a server-side tool.

    • tool_id: string

    • type: "code_execution_20250825"

      • "code_execution_20250825"

Beta Server Tool Caller 20260120

  • BetaServerToolCaller20260120 object { tool_id, type }

    • tool_id: string

    • type: "code_execution_20260120"

      • "code_execution_20260120"

Beta Server Tool Usage

  • BetaServerToolUsage object { web_fetch_requests, web_search_requests }

    • 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 object { id, input, name, 2 more }

    • id: string

    • input: map[unknown]

    • name: "advisor" or "web_search" or "web_fetch" or 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: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

      Tool invocation directly from the model.

      • BetaDirectCaller object { type }

        Tool invocation directly from the model.

        • type: "direct"

          • "direct"

      • BetaServerToolCaller object { tool_id, type }

        Tool invocation generated by a server-side tool.

        • tool_id: string

        • type: "code_execution_20250825"

          • "code_execution_20250825"

      • BetaServerToolCaller20260120 object { tool_id, type }

        • tool_id: string

        • type: "code_execution_20260120"

          • "code_execution_20260120"

Beta Server Tool Use Block Param

  • BetaServerToolUseBlockParam object { id, input, name, 3 more }

    • id: string

    • input: map[unknown]

    • name: "advisor" or "web_search" or "web_fetch" or 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: optional BetaCacheControlEphemeral

      Create a cache control breakpoint at this content block.

      • type: "ephemeral"

        • "ephemeral"

      • ttl: optional "5m" or "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: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

      Tool invocation directly from the model.

      • BetaDirectCaller object { type }

        Tool invocation directly from the model.

        • type: "direct"

          • "direct"

      • BetaServerToolCaller object { tool_id, type }

        Tool invocation generated by a server-side tool.

        • tool_id: string

        • type: "code_execution_20250825"

          • "code_execution_20250825"

      • BetaServerToolCaller20260120 object { tool_id, type }

        • tool_id: string

        • type: "code_execution_20260120"

          • "code_execution_20260120"

Beta Signature Delta

  • BetaSignatureDelta object { signature, type }

    • signature: string

    • type: "signature_delta"

      • "signature_delta"

Beta Skill

  • BetaSkill object { skill_id, type, version }

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

    • skill_id: string

      Skill ID

    • type: "anthropic" or "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 object { skill_id, type, version }

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

    • skill_id: string

      Skill ID

    • type: "anthropic" or "custom"

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

      • "anthropic"

      • "custom"

    • version: optional string

      Skill version or 'latest' for most recent version

Beta Stop Reason

  • BetaStopReason = "end_turn" or "max_tokens" or "stop_sequence" or 5 more

    • "end_turn"

    • "max_tokens"

    • "stop_sequence"

    • "tool_use"

    • "pause_turn"

    • "compaction"

    • "refusal"

    • "model_context_window_exceeded"

Beta Text Block

  • BetaTextBlock object { citations, text, type }

    • citations: array of BetaTextCitation

      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 object { cited_text, document_index, document_title, 4 more }

        • cited_text: string

        • document_index: number

        • document_title: string

        • end_char_index: number

        • file_id: string

        • start_char_index: number

        • type: "char_location"

          • "char_location"

      • BetaCitationPageLocation object { cited_text, document_index, document_title, 4 more }

        • cited_text: string

        • document_index: number

        • document_title: string

        • end_page_number: number

        • file_id: string

        • start_page_number: number

        • type: "page_location"

          • "page_location"

      • BetaCitationContentBlockLocation object { cited_text, document_index, document_title, 4 more }

        • 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

        • 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

        • 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 object { cited_text, encrypted_index, title, 2 more }

        • cited_text: string

        • encrypted_index: string

        • title: string

        • type: "web_search_result_location"

          • "web_search_result_location"

        • url: string

      • BetaCitationSearchResultLocation object { cited_text, end_block_index, search_result_index, 4 more }

        • 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

        • type: "search_result_location"

          • "search_result_location"

    • text: string

    • type: "text"

      • "text"

Beta Text Block Param

  • BetaTextBlockParam object { text, type, cache_control, citations }

    • text: string

    • type: "text"

      • "text"

    • cache_control: optional BetaCacheControlEphemeral

      Create a cache control breakpoint at this content block.

      • type: "ephemeral"

        • "ephemeral"

      • ttl: optional "5m" or "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: optional array of BetaTextCitationParam

      • BetaCitationCharLocationParam object { cited_text, document_index, document_title, 3 more }

        • cited_text: string

        • document_index: number

        • document_title: string

        • end_char_index: number

        • start_char_index: number

        • type: "char_location"

          • "char_location"

      • BetaCitationPageLocationParam object { cited_text, document_index, document_title, 3 more }

        • cited_text: string

        • document_index: number

        • document_title: string

        • end_page_number: number

        • start_page_number: number

        • type: "page_location"

          • "page_location"

      • BetaCitationContentBlockLocationParam object { cited_text, document_index, document_title, 3 more }

        • 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

        • 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 object { cited_text, encrypted_index, title, 2 more }

        • cited_text: string

        • encrypted_index: string

        • title: string

        • type: "web_search_result_location"

          • "web_search_result_location"

        • url: string

      • BetaCitationSearchResultLocationParam object { cited_text, end_block_index, search_result_index, 4 more }

        • 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

        • type: "search_result_location"

          • "search_result_location"

Beta Text Citation

  • BetaTextCitation = BetaCitationCharLocation or BetaCitationPageLocation or BetaCitationContentBlockLocation or 2 more

    • BetaCitationCharLocation object { cited_text, document_index, document_title, 4 more }

      • cited_text: string

      • document_index: number

      • document_title: string

      • end_char_index: number

      • file_id: string

      • start_char_index: number

      • type: "char_location"

        • "char_location"

    • BetaCitationPageLocation object { cited_text, document_index, document_title, 4 more }

      • cited_text: string

      • document_index: number

      • document_title: string

      • end_page_number: number

      • file_id: string

      • start_page_number: number

      • type: "page_location"

        • "page_location"

    • BetaCitationContentBlockLocation object { cited_text, document_index, document_title, 4 more }

      • 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

      • 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

      • 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 object { cited_text, encrypted_index, title, 2 more }

      • cited_text: string

      • encrypted_index: string

      • title: string

      • type: "web_search_result_location"

        • "web_search_result_location"

      • url: string

    • BetaCitationSearchResultLocation object { cited_text, end_block_index, search_result_index, 4 more }

      • 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

      • type: "search_result_location"

        • "search_result_location"

Beta Text Citation Param

  • BetaTextCitationParam = BetaCitationCharLocationParam or BetaCitationPageLocationParam or BetaCitationContentBlockLocationParam or 2 more

    • BetaCitationCharLocationParam object { cited_text, document_index, document_title, 3 more }

      • cited_text: string

      • document_index: number

      • document_title: string

      • end_char_index: number

      • start_char_index: number

      • type: "char_location"

        • "char_location"

    • BetaCitationPageLocationParam object { cited_text, document_index, document_title, 3 more }

      • cited_text: string

      • document_index: number

      • document_title: string

      • end_page_number: number

      • start_page_number: number

      • type: "page_location"

        • "page_location"

    • BetaCitationContentBlockLocationParam object { cited_text, document_index, document_title, 3 more }

      • 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

      • 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 object { cited_text, encrypted_index, title, 2 more }

      • cited_text: string

      • encrypted_index: string

      • title: string

      • type: "web_search_result_location"

        • "web_search_result_location"

      • url: string

    • BetaCitationSearchResultLocationParam object { cited_text, end_block_index, search_result_index, 4 more }

      • 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

      • type: "search_result_location"

        • "search_result_location"

Beta Text Delta

  • BetaTextDelta object { text, type }

    • text: string

    • type: "text_delta"

      • "text_delta"

Beta Text Editor Code Execution Create Result Block

  • BetaTextEditorCodeExecutionCreateResultBlock object { is_file_update, type }

    • 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 object { is_file_update, type }

    • 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 object { lines, new_lines, new_start, 3 more }

    • lines: array of string

    • new_lines: number

    • new_start: number

    • old_lines: number

    • old_start: number

    • 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 object { type, lines, new_lines, 3 more }

    • type: "text_editor_code_execution_str_replace_result"

      • "text_editor_code_execution_str_replace_result"

    • lines: optional array of string

    • new_lines: optional number

    • new_start: optional number

    • old_lines: optional number

    • old_start: optional number

Beta Text Editor Code Execution Tool Result Block

  • BetaTextEditorCodeExecutionToolResultBlock object { content, tool_use_id, type }

    • content: BetaTextEditorCodeExecutionToolResultError or BetaTextEditorCodeExecutionViewResultBlock or BetaTextEditorCodeExecutionCreateResultBlock or BetaTextEditorCodeExecutionStrReplaceResultBlock

      • BetaTextEditorCodeExecutionToolResultError object { error_code, error_message, type }

        • error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more

          • "invalid_tool_input"

          • "unavailable"

          • "too_many_requests"

          • "execution_time_exceeded"

          • "file_not_found"

        • error_message: string

        • type: "text_editor_code_execution_tool_result_error"

          • "text_editor_code_execution_tool_result_error"

      • BetaTextEditorCodeExecutionViewResultBlock object { content, file_type, num_lines, 3 more }

        • content: string

        • file_type: "text" or "image" or "pdf"

          • "text"

          • "image"

          • "pdf"

        • num_lines: number

        • start_line: number

        • total_lines: number

        • type: "text_editor_code_execution_view_result"

          • "text_editor_code_execution_view_result"

      • BetaTextEditorCodeExecutionCreateResultBlock object { is_file_update, type }

        • is_file_update: boolean

        • type: "text_editor_code_execution_create_result"

          • "text_editor_code_execution_create_result"

      • BetaTextEditorCodeExecutionStrReplaceResultBlock object { lines, new_lines, new_start, 3 more }

        • lines: array of string

        • new_lines: number

        • new_start: number

        • old_lines: number

        • old_start: number

        • 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 object { content, tool_use_id, type, cache_control }

    • content: BetaTextEditorCodeExecutionToolResultErrorParam or BetaTextEditorCodeExecutionViewResultBlockParam or BetaTextEditorCodeExecutionCreateResultBlockParam or BetaTextEditorCodeExecutionStrReplaceResultBlockParam

      • BetaTextEditorCodeExecutionToolResultErrorParam object { error_code, type, error_message }

        • error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 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: optional string

      • BetaTextEditorCodeExecutionViewResultBlockParam object { content, file_type, type, 3 more }

        • content: string

        • file_type: "text" or "image" or "pdf"

          • "text"

          • "image"

          • "pdf"

        • type: "text_editor_code_execution_view_result"

          • "text_editor_code_execution_view_result"

        • num_lines: optional number

        • start_line: optional number

        • total_lines: optional number

      • BetaTextEditorCodeExecutionCreateResultBlockParam object { is_file_update, type }

        • is_file_update: boolean

        • type: "text_editor_code_execution_create_result"

          • "text_editor_code_execution_create_result"

      • BetaTextEditorCodeExecutionStrReplaceResultBlockParam object { type, lines, new_lines, 3 more }

        • type: "text_editor_code_execution_str_replace_result"

          • "text_editor_code_execution_str_replace_result"

        • lines: optional array of string

        • new_lines: optional number

        • new_start: optional number

        • old_lines: optional number

        • old_start: optional number

    • tool_use_id: string

    • type: "text_editor_code_execution_tool_result"

      • "text_editor_code_execution_tool_result"

    • cache_control: optional BetaCacheControlEphemeral

      Create a cache control breakpoint at this content block.

      • type: "ephemeral"

        • "ephemeral"

      • ttl: optional "5m" or "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 object { error_code, error_message, type }

    • error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more

      • "invalid_tool_input"

      • "unavailable"

      • "too_many_requests"

      • "execution_time_exceeded"

      • "file_not_found"

    • error_message: string

    • 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 object { error_code, type, error_message }

    • error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 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: optional string

Beta Text Editor Code Execution View Result Block

  • BetaTextEditorCodeExecutionViewResultBlock object { content, file_type, num_lines, 3 more }

    • content: string

    • file_type: "text" or "image" or "pdf"

      • "text"

      • "image"

      • "pdf"

    • num_lines: number

    • start_line: number

    • total_lines: number

    • type: "text_editor_code_execution_view_result"

      • "text_editor_code_execution_view_result"

Beta Text Editor Code Execution View Result Block Param

  • BetaTextEditorCodeExecutionViewResultBlockParam object { content, file_type, type, 3 more }

    • content: string

    • file_type: "text" or "image" or "pdf"

      • "text"

      • "image"

      • "pdf"

    • type: "text_editor_code_execution_view_result"

      • "text_editor_code_execution_view_result"

    • num_lines: optional number

    • start_line: optional number

    • total_lines: optional number

Beta Thinking Block

  • BetaThinkingBlock object { signature, thinking, type }

    • signature: string

    • thinking: string

    • type: "thinking"

      • "thinking"

Beta Thinking Block Param

  • BetaThinkingBlockParam object { signature, thinking, type }

    • signature: string

    • thinking: string

    • type: "thinking"

      • "thinking"

Beta Thinking Config Adaptive

  • BetaThinkingConfigAdaptive object { type, display }

    • type: "adaptive"

      • "adaptive"

    • display: optional "summarized" or "omitted"

      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 object { type }

    • type: "disabled"

      • "disabled"

Beta Thinking Config Enabled

  • BetaThinkingConfigEnabled object { budget_tokens, type, display }

    • 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 for details.

    • type: "enabled"

      • "enabled"

    • display: optional "summarized" or "omitted"

      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 or BetaThinkingConfigDisabled or 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 for details.

    • BetaThinkingConfigEnabled object { budget_tokens, type, display }

      • 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 for details.

      • type: "enabled"

        • "enabled"

      • display: optional "summarized" or "omitted"

        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 object { type }

      • type: "disabled"

        • "disabled"

    • BetaThinkingConfigAdaptive object { type, display }

      • type: "adaptive"

        • "adaptive"

      • display: optional "summarized" or "omitted"

        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 object { thinking, type }

    • thinking: string

    • type: "thinking_delta"

      • "thinking_delta"

Beta Thinking Turns

  • BetaThinkingTurns object { type, value }

    • type: "thinking_turns"

      • "thinking_turns"

    • value: number

Beta Token Task Budget

  • BetaTokenTaskBudget object { total, type, remaining }

    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: optional number

      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 object { input_schema, name, allowed_callers, 7 more }

    • input_schema: object { type, properties, required }

      JSON schema for this tool's input.

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

      • type: "object"

        • "object"

      • properties: optional map[unknown]

      • required: optional array of string

    • name: string

      Name of the tool.

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

    • allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

      • "direct"

      • "code_execution_20250825"

      • "code_execution_20260120"

    • cache_control: optional BetaCacheControlEphemeral

      Create a cache control breakpoint at this content block.

      • type: "ephemeral"

        • "ephemeral"

      • ttl: optional "5m" or "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: optional boolean

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

    • description: optional 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: optional boolean

      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: optional array of map[unknown]

    • strict: optional boolean

      When true, guarantees schema validation on tool names and inputs

    • type: optional "custom"

      • "custom"

Beta Tool Bash 20241022

  • BetaToolBash20241022 object { name, type, allowed_callers, 4 more }

    • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

      • "direct"

      • "code_execution_20250825"

      • "code_execution_20260120"

    • cache_control: optional BetaCacheControlEphemeral

      Create a cache control breakpoint at this content block.

      • type: "ephemeral"

        • "ephemeral"

      • ttl: optional "5m" or "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: optional boolean

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

    • input_examples: optional array of map[unknown]

    • strict: optional boolean

      When true, guarantees schema validation on tool names and inputs

Beta Tool Bash 20250124

  • BetaToolBash20250124 object { name, type, allowed_callers, 4 more }

    • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

      • "direct"

      • "code_execution_20250825"

      • "code_execution_20260120"

    • cache_control: optional BetaCacheControlEphemeral

      Create a cache control breakpoint at this content block.

      • type: "ephemeral"

        • "ephemeral"

      • ttl: optional "5m" or "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: optional boolean

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

    • input_examples: optional array of map[unknown]

    • strict: optional boolean

      When true, guarantees schema validation on tool names and inputs

Beta Tool Choice

  • BetaToolChoice = BetaToolChoiceAuto or BetaToolChoiceAny or BetaToolChoiceTool or 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 object { type, disable_parallel_tool_use }

      The model will automatically decide whether to use tools.

      • type: "auto"

        • "auto"

      • disable_parallel_tool_use: optional boolean

        Whether to disable parallel tool use.

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

    • BetaToolChoiceAny object { type, disable_parallel_tool_use }

      The model will use any available tools.

      • type: "any"

        • "any"

      • disable_parallel_tool_use: optional boolean

        Whether to disable parallel tool use.

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

    • BetaToolChoiceTool object { name, type, disable_parallel_tool_use }

      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: optional boolean

        Whether to disable parallel tool use.

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

    • BetaToolChoiceNone object { type }

      The model will not be allowed to use tools.

      • type: "none"

        • "none"

Beta Tool Choice Any

  • BetaToolChoiceAny object { type, disable_parallel_tool_use }

    The model will use any available tools.

    • type: "any"

      • "any"

    • disable_parallel_tool_use: optional 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 object { type, disable_parallel_tool_use }

    The model will automatically decide whether to use tools.

    • type: "auto"

      • "auto"

    • disable_parallel_tool_use: optional 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 object { type }

    The model will not be allowed to use tools.

    • type: "none"

      • "none"

Beta Tool Choice Tool

  • BetaToolChoiceTool object { name, type, disable_parallel_tool_use }

    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: optional 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 object { display_height_px, display_width_px, name, 7 more }

    • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

      • "direct"

      • "code_execution_20250825"

      • "code_execution_20260120"

    • cache_control: optional BetaCacheControlEphemeral

      Create a cache control breakpoint at this content block.

      • type: "ephemeral"

        • "ephemeral"

      • ttl: optional "5m" or "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: optional boolean

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

    • display_number: optional number

      The X11 display number (e.g. 0, 1) for the display.

    • input_examples: optional array of map[unknown]

    • strict: optional boolean

      When true, guarantees schema validation on tool names and inputs

Beta Tool Computer Use 20250124

  • BetaToolComputerUse20250124 object { display_height_px, display_width_px, name, 7 more }

    • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

      • "direct"

      • "code_execution_20250825"

      • "code_execution_20260120"

    • cache_control: optional BetaCacheControlEphemeral

      Create a cache control breakpoint at this content block.

      • type: "ephemeral"

        • "ephemeral"

      • ttl: optional "5m" or "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: optional boolean

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

    • display_number: optional number

      The X11 display number (e.g. 0, 1) for the display.

    • input_examples: optional array of map[unknown]

    • strict: optional boolean

      When true, guarantees schema validation on tool names and inputs

Beta Tool Computer Use 20251124

  • BetaToolComputerUse20251124 object { display_height_px, display_width_px, name, 8 more }

    • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

      • "direct"

      • "code_execution_20250825"

      • "code_execution_20260120"

    • cache_control: optional BetaCacheControlEphemeral

      Create a cache control breakpoint at this content block.

      • type: "ephemeral"

        • "ephemeral"

      • ttl: optional "5m" or "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: optional boolean

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

    • display_number: optional number

      The X11 display number (e.g. 0, 1) for the display.

    • enable_zoom: optional boolean

      Whether to enable an action to take a zoomed-in screenshot of the screen.

    • input_examples: optional array of map[unknown]

    • strict: optional boolean

      When true, guarantees schema validation on tool names and inputs

Beta Tool Reference Block

  • BetaToolReferenceBlock object { tool_name, type }

    • tool_name: string

    • type: "tool_reference"

      • "tool_reference"

Beta Tool Reference Block Param

  • BetaToolReferenceBlockParam object { tool_name, type, cache_control }

    Tool reference block that can be included in tool_result content.

    • tool_name: string

    • type: "tool_reference"

      • "tool_reference"

    • cache_control: optional BetaCacheControlEphemeral

      Create a cache control breakpoint at this content block.

      • type: "ephemeral"

        • "ephemeral"

      • ttl: optional "5m" or "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 object { tool_use_id, type, cache_control, 2 more }

    • tool_use_id: string

    • type: "tool_result"

      • "tool_result"

    • cache_control: optional BetaCacheControlEphemeral

      Create a cache control breakpoint at this content block.

      • type: "ephemeral"

        • "ephemeral"

      • ttl: optional "5m" or "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: optional string or array of BetaTextBlockParam or BetaImageBlockParam or BetaSearchResultBlockParam or 2 more

      • string

      • array of BetaTextBlockParam or BetaImageBlockParam or BetaSearchResultBlockParam or 2 more

        • BetaTextBlockParam object { text, type, cache_control, citations }

          • text: string

          • type: "text"

            • "text"

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

          • citations: optional array of BetaTextCitationParam

            • BetaCitationCharLocationParam object { cited_text, document_index, document_title, 3 more }

              • cited_text: string

              • document_index: number

              • document_title: string

              • end_char_index: number

              • start_char_index: number

              • type: "char_location"

                • "char_location"

            • BetaCitationPageLocationParam object { cited_text, document_index, document_title, 3 more }

              • cited_text: string

              • document_index: number

              • document_title: string

              • end_page_number: number

              • start_page_number: number

              • type: "page_location"

                • "page_location"

            • BetaCitationContentBlockLocationParam object { cited_text, document_index, document_title, 3 more }

              • 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

              • 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 object { cited_text, encrypted_index, title, 2 more }

              • cited_text: string

              • encrypted_index: string

              • title: string

              • type: "web_search_result_location"

                • "web_search_result_location"

              • url: string

            • BetaCitationSearchResultLocationParam object { cited_text, end_block_index, search_result_index, 4 more }

              • 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

              • type: "search_result_location"

                • "search_result_location"

        • BetaImageBlockParam object { source, type, cache_control }

          • source: BetaBase64ImageSource or BetaURLImageSource or BetaFileImageSource

            • BetaBase64ImageSource object { data, media_type, type }

              • data: string

              • media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"

                • "image/jpeg"

                • "image/png"

                • "image/gif"

                • "image/webp"

              • type: "base64"

                • "base64"

            • BetaURLImageSource object { type, url }

              • type: "url"

                • "url"

              • url: string

            • BetaFileImageSource object { file_id, type }

              • file_id: string

              • type: "file"

                • "file"

          • type: "image"

            • "image"

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

        • BetaSearchResultBlockParam object { content, source, title, 3 more }

          • content: array of BetaTextBlockParam

            • text: string

            • type: "text"

            • cache_control: optional BetaCacheControlEphemeral

              Create a cache control breakpoint at this content block.

            • citations: optional array of BetaTextCitationParam

          • source: string

          • title: string

          • type: "search_result"

            • "search_result"

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

          • citations: optional BetaCitationsConfigParam

            • enabled: optional boolean

        • BetaRequestDocumentBlock object { source, type, cache_control, 3 more }

          • source: BetaBase64PDFSource or BetaPlainTextSource or BetaContentBlockSource or 2 more

            • BetaBase64PDFSource object { data, media_type, type }

              • data: string

              • media_type: "application/pdf"

                • "application/pdf"

              • type: "base64"

                • "base64"

            • BetaPlainTextSource object { data, media_type, type }

              • data: string

              • media_type: "text/plain"

                • "text/plain"

              • type: "text"

                • "text"

            • BetaContentBlockSource object { content, type }

              • content: string or array of BetaContentBlockSourceContent

                • string

                • BetaContentBlockSourceContent = array of BetaContentBlockSourceContent

                  • BetaTextBlockParam object { text, type, cache_control, citations }

                  • BetaImageBlockParam object { source, type, cache_control }

              • type: "content"

                • "content"

            • BetaURLPDFSource object { type, url }

              • type: "url"

                • "url"

              • url: string

            • BetaFileDocumentSource object { file_id, type }

              • file_id: string

              • type: "file"

                • "file"

          • type: "document"

            • "document"

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

          • citations: optional BetaCitationsConfigParam

          • context: optional string

          • title: optional string

        • BetaToolReferenceBlockParam object { tool_name, type, cache_control }

          Tool reference block that can be included in tool_result content.

          • tool_name: string

          • type: "tool_reference"

            • "tool_reference"

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

    • is_error: optional boolean

Beta Tool Search Tool Bm25 20251119

  • BetaToolSearchToolBm25_20251119 object { name, type, allowed_callers, 3 more }

    • 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" or "tool_search_tool_bm25"

      • "tool_search_tool_bm25_20251119"

      • "tool_search_tool_bm25"

    • allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

      • "direct"

      • "code_execution_20250825"

      • "code_execution_20260120"

    • cache_control: optional BetaCacheControlEphemeral

      Create a cache control breakpoint at this content block.

      • type: "ephemeral"

        • "ephemeral"

      • ttl: optional "5m" or "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: optional boolean

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

    • strict: optional boolean

      When true, guarantees schema validation on tool names and inputs

Beta Tool Search Tool Regex 20251119

  • BetaToolSearchToolRegex20251119 object { name, type, allowed_callers, 3 more }

    • 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" or "tool_search_tool_regex"

      • "tool_search_tool_regex_20251119"

      • "tool_search_tool_regex"

    • allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

      • "direct"

      • "code_execution_20250825"

      • "code_execution_20260120"

    • cache_control: optional BetaCacheControlEphemeral

      Create a cache control breakpoint at this content block.

      • type: "ephemeral"

        • "ephemeral"

      • ttl: optional "5m" or "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: optional boolean

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

    • strict: optional boolean

      When true, guarantees schema validation on tool names and inputs

Beta Tool Search Tool Result Block

  • BetaToolSearchToolResultBlock object { content, tool_use_id, type }

    • content: BetaToolSearchToolResultError or BetaToolSearchToolSearchResultBlock

      • BetaToolSearchToolResultError object { error_code, error_message, type }

        • error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"

          • "invalid_tool_input"

          • "unavailable"

          • "too_many_requests"

          • "execution_time_exceeded"

        • error_message: string

        • type: "tool_search_tool_result_error"

          • "tool_search_tool_result_error"

      • BetaToolSearchToolSearchResultBlock object { tool_references, type }

        • tool_references: array of BetaToolReferenceBlock

          • 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 object { content, tool_use_id, type, cache_control }

    • content: BetaToolSearchToolResultErrorParam or BetaToolSearchToolSearchResultBlockParam

      • BetaToolSearchToolResultErrorParam object { error_code, type }

        • error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "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 object { tool_references, type }

        • tool_references: array of BetaToolReferenceBlockParam

          • tool_name: string

          • type: "tool_reference"

            • "tool_reference"

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

            • type: "ephemeral"

              • "ephemeral"

            • ttl: optional "5m" or "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: optional BetaCacheControlEphemeral

      Create a cache control breakpoint at this content block.

Beta Tool Search Tool Result Error

  • BetaToolSearchToolResultError object { error_code, error_message, type }

    • error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"

      • "invalid_tool_input"

      • "unavailable"

      • "too_many_requests"

      • "execution_time_exceeded"

    • error_message: string

    • type: "tool_search_tool_result_error"

      • "tool_search_tool_result_error"

Beta Tool Search Tool Result Error Param

  • BetaToolSearchToolResultErrorParam object { error_code, type }

    • error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "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 object { tool_references, type }

    • tool_references: array of BetaToolReferenceBlock

      • 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 object { tool_references, type }

    • tool_references: array of BetaToolReferenceBlockParam

      • tool_name: string

      • type: "tool_reference"

        • "tool_reference"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

        • type: "ephemeral"

          • "ephemeral"

        • ttl: optional "5m" or "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 object { name, type, allowed_callers, 4 more }

    • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

      • "direct"

      • "code_execution_20250825"

      • "code_execution_20260120"

    • cache_control: optional BetaCacheControlEphemeral

      Create a cache control breakpoint at this content block.

      • type: "ephemeral"

        • "ephemeral"

      • ttl: optional "5m" or "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: optional boolean

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

    • input_examples: optional array of map[unknown]

    • strict: optional boolean

      When true, guarantees schema validation on tool names and inputs

Beta Tool Text Editor 20250124

  • BetaToolTextEditor20250124 object { name, type, allowed_callers, 4 more }

    • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

      • "direct"

      • "code_execution_20250825"

      • "code_execution_20260120"

    • cache_control: optional BetaCacheControlEphemeral

      Create a cache control breakpoint at this content block.

      • type: "ephemeral"

        • "ephemeral"

      • ttl: optional "5m" or "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: optional boolean

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

    • input_examples: optional array of map[unknown]

    • strict: optional boolean

      When true, guarantees schema validation on tool names and inputs

Beta Tool Text Editor 20250429

  • BetaToolTextEditor20250429 object { name, type, allowed_callers, 4 more }

    • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

      • "direct"

      • "code_execution_20250825"

      • "code_execution_20260120"

    • cache_control: optional BetaCacheControlEphemeral

      Create a cache control breakpoint at this content block.

      • type: "ephemeral"

        • "ephemeral"

      • ttl: optional "5m" or "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: optional boolean

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

    • input_examples: optional array of map[unknown]

    • strict: optional boolean

      When true, guarantees schema validation on tool names and inputs

Beta Tool Text Editor 20250728

  • BetaToolTextEditor20250728 object { name, type, allowed_callers, 5 more }

    • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

      • "direct"

      • "code_execution_20250825"

      • "code_execution_20260120"

    • cache_control: optional BetaCacheControlEphemeral

      Create a cache control breakpoint at this content block.

      • type: "ephemeral"

        • "ephemeral"

      • ttl: optional "5m" or "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: optional boolean

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

    • input_examples: optional array of map[unknown]

    • max_characters: optional number

      Maximum number of characters to display when viewing a file. If not specified, defaults to displaying the full file.

    • strict: optional boolean

      When true, guarantees schema validation on tool names and inputs

Beta Tool Union

  • BetaToolUnion = BetaTool or BetaToolBash20241022 or BetaToolBash20250124 or 20 more

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

    • BetaTool object { input_schema, name, allowed_callers, 7 more }

      • input_schema: object { type, properties, required }

        JSON schema for this tool's input.

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

        • type: "object"

          • "object"

        • properties: optional map[unknown]

        • required: optional array of string

      • name: string

        Name of the tool.

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

      • allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

        • "direct"

        • "code_execution_20250825"

        • "code_execution_20260120"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

        • type: "ephemeral"

          • "ephemeral"

        • ttl: optional "5m" or "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: optional boolean

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

      • description: optional 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: optional boolean

        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: optional array of map[unknown]

      • strict: optional boolean

        When true, guarantees schema validation on tool names and inputs

      • type: optional "custom"

        • "custom"

    • BetaToolBash20241022 object { name, type, allowed_callers, 4 more }

      • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

        • "direct"

        • "code_execution_20250825"

        • "code_execution_20260120"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • defer_loading: optional boolean

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

      • input_examples: optional array of map[unknown]

      • strict: optional boolean

        When true, guarantees schema validation on tool names and inputs

    • BetaToolBash20250124 object { name, type, allowed_callers, 4 more }

      • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

        • "direct"

        • "code_execution_20250825"

        • "code_execution_20260120"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • defer_loading: optional boolean

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

      • input_examples: optional array of map[unknown]

      • strict: optional boolean

        When true, guarantees schema validation on tool names and inputs

    • BetaCodeExecutionTool20250522 object { name, type, allowed_callers, 3 more }

      • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

        • "direct"

        • "code_execution_20250825"

        • "code_execution_20260120"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • defer_loading: optional boolean

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

      • strict: optional boolean

        When true, guarantees schema validation on tool names and inputs

    • BetaCodeExecutionTool20250825 object { name, type, allowed_callers, 3 more }

      • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

        • "direct"

        • "code_execution_20250825"

        • "code_execution_20260120"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • defer_loading: optional boolean

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

      • strict: optional boolean

        When true, guarantees schema validation on tool names and inputs

    • BetaCodeExecutionTool20260120 object { name, type, allowed_callers, 3 more }

      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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

        • "direct"

        • "code_execution_20250825"

        • "code_execution_20260120"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • defer_loading: optional boolean

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

      • strict: optional boolean

        When true, guarantees schema validation on tool names and inputs

    • BetaToolComputerUse20241022 object { display_height_px, display_width_px, name, 7 more }

      • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

        • "direct"

        • "code_execution_20250825"

        • "code_execution_20260120"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • defer_loading: optional boolean

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

      • display_number: optional number

        The X11 display number (e.g. 0, 1) for the display.

      • input_examples: optional array of map[unknown]

      • strict: optional boolean

        When true, guarantees schema validation on tool names and inputs

    • BetaMemoryTool20250818 object { name, type, allowed_callers, 4 more }

      • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

        • "direct"

        • "code_execution_20250825"

        • "code_execution_20260120"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • defer_loading: optional boolean

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

      • input_examples: optional array of map[unknown]

      • strict: optional boolean

        When true, guarantees schema validation on tool names and inputs

    • BetaToolComputerUse20250124 object { display_height_px, display_width_px, name, 7 more }

      • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

        • "direct"

        • "code_execution_20250825"

        • "code_execution_20260120"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • defer_loading: optional boolean

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

      • display_number: optional number

        The X11 display number (e.g. 0, 1) for the display.

      • input_examples: optional array of map[unknown]

      • strict: optional boolean

        When true, guarantees schema validation on tool names and inputs

    • BetaToolTextEditor20241022 object { name, type, allowed_callers, 4 more }

      • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

        • "direct"

        • "code_execution_20250825"

        • "code_execution_20260120"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • defer_loading: optional boolean

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

      • input_examples: optional array of map[unknown]

      • strict: optional boolean

        When true, guarantees schema validation on tool names and inputs

    • BetaToolComputerUse20251124 object { display_height_px, display_width_px, name, 8 more }

      • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

        • "direct"

        • "code_execution_20250825"

        • "code_execution_20260120"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • defer_loading: optional boolean

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

      • display_number: optional number

        The X11 display number (e.g. 0, 1) for the display.

      • enable_zoom: optional boolean

        Whether to enable an action to take a zoomed-in screenshot of the screen.

      • input_examples: optional array of map[unknown]

      • strict: optional boolean

        When true, guarantees schema validation on tool names and inputs

    • BetaToolTextEditor20250124 object { name, type, allowed_callers, 4 more }

      • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

        • "direct"

        • "code_execution_20250825"

        • "code_execution_20260120"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • defer_loading: optional boolean

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

      • input_examples: optional array of map[unknown]

      • strict: optional boolean

        When true, guarantees schema validation on tool names and inputs

    • BetaToolTextEditor20250429 object { name, type, allowed_callers, 4 more }

      • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

        • "direct"

        • "code_execution_20250825"

        • "code_execution_20260120"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • defer_loading: optional boolean

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

      • input_examples: optional array of map[unknown]

      • strict: optional boolean

        When true, guarantees schema validation on tool names and inputs

    • BetaToolTextEditor20250728 object { name, type, allowed_callers, 5 more }

      • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

        • "direct"

        • "code_execution_20250825"

        • "code_execution_20260120"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • defer_loading: optional boolean

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

      • input_examples: optional array of map[unknown]

      • max_characters: optional number

        Maximum number of characters to display when viewing a file. If not specified, defaults to displaying the full file.

      • strict: optional boolean

        When true, guarantees schema validation on tool names and inputs

    • BetaWebSearchTool20250305 object { name, type, allowed_callers, 7 more }

      • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

        • "direct"

        • "code_execution_20250825"

        • "code_execution_20260120"

      • allowed_domains: optional array of string

        If provided, only these domains will be included in results. Cannot be used alongside blocked_domains.

      • blocked_domains: optional array of string

        If provided, these domains will never appear in results. Cannot be used alongside allowed_domains.

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • defer_loading: optional boolean

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

      • max_uses: optional number

        Maximum number of times the tool can be used in the API request.

      • strict: optional boolean

        When true, guarantees schema validation on tool names and inputs

      • user_location: optional BetaUserLocation

        Parameters for the user's location. Used to provide more relevant search results.

        • type: "approximate"

          • "approximate"

        • city: optional string

          The city of the user.

        • country: optional string

          The two letter ISO country code of the user.

        • region: optional string

          The region of the user.

        • timezone: optional string

          The IANA timezone of the user.

    • BetaWebFetchTool20250910 object { name, type, allowed_callers, 8 more }

      • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

        • "direct"

        • "code_execution_20250825"

        • "code_execution_20260120"

      • allowed_domains: optional array of string

        List of domains to allow fetching from

      • blocked_domains: optional array of string

        List of domains to block fetching from

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • citations: optional BetaCitationsConfigParam

        Citations configuration for fetched documents. Citations are disabled by default.

        • enabled: optional boolean

      • defer_loading: optional 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: optional number

        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: optional number

        Maximum number of times the tool can be used in the API request.

      • strict: optional boolean

        When true, guarantees schema validation on tool names and inputs

    • BetaWebSearchTool20260209 object { name, type, allowed_callers, 7 more }

      • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

        • "direct"

        • "code_execution_20250825"

        • "code_execution_20260120"

      • allowed_domains: optional array of string

        If provided, only these domains will be included in results. Cannot be used alongside blocked_domains.

      • blocked_domains: optional array of string

        If provided, these domains will never appear in results. Cannot be used alongside allowed_domains.

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • defer_loading: optional boolean

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

      • max_uses: optional number

        Maximum number of times the tool can be used in the API request.

      • strict: optional boolean

        When true, guarantees schema validation on tool names and inputs

      • user_location: optional BetaUserLocation

        Parameters for the user's location. Used to provide more relevant search results.

    • BetaWebFetchTool20260209 object { name, type, allowed_callers, 8 more }

      • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

        • "direct"

        • "code_execution_20250825"

        • "code_execution_20260120"

      • allowed_domains: optional array of string

        List of domains to allow fetching from

      • blocked_domains: optional array of string

        List of domains to block fetching from

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • citations: optional BetaCitationsConfigParam

        Citations configuration for fetched documents. Citations are disabled by default.

      • defer_loading: optional 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: optional number

        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: optional number

        Maximum number of times the tool can be used in the API request.

      • strict: optional boolean

        When true, guarantees schema validation on tool names and inputs

    • BetaWebFetchTool20260309 object { name, type, allowed_callers, 9 more }

      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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

        • "direct"

        • "code_execution_20250825"

        • "code_execution_20260120"

      • allowed_domains: optional array of string

        List of domains to allow fetching from

      • blocked_domains: optional array of string

        List of domains to block fetching from

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • citations: optional BetaCitationsConfigParam

        Citations configuration for fetched documents. Citations are disabled by default.

      • defer_loading: optional 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: optional number

        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: optional number

        Maximum number of times the tool can be used in the API request.

      • strict: optional boolean

        When true, guarantees schema validation on tool names and inputs

      • use_cache: optional 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 object { model, name, type, 6 more }

      • model: Model

        The model that will complete your prompt.

        See models for additional details and options.

        • "claude-opus-4-7" or "claude-mythos-preview" or "claude-opus-4-6" or 14 more

          The model that will complete your prompt.

          See models for additional details and options.

          • "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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

        • "direct"

        • "code_execution_20250825"

        • "code_execution_20260120"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • caching: optional BetaCacheControlEphemeral

        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: optional boolean

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

      • max_uses: optional number

        Maximum number of times the tool can be used in the API request.

      • strict: optional boolean

        When true, guarantees schema validation on tool names and inputs

    • BetaToolSearchToolBm25_20251119 object { name, type, allowed_callers, 3 more }

      • 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" or "tool_search_tool_bm25"

        • "tool_search_tool_bm25_20251119"

        • "tool_search_tool_bm25"

      • allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

        • "direct"

        • "code_execution_20250825"

        • "code_execution_20260120"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • defer_loading: optional boolean

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

      • strict: optional boolean

        When true, guarantees schema validation on tool names and inputs

    • BetaToolSearchToolRegex20251119 object { name, type, allowed_callers, 3 more }

      • 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" or "tool_search_tool_regex"

        • "tool_search_tool_regex_20251119"

        • "tool_search_tool_regex"

      • allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

        • "direct"

        • "code_execution_20250825"

        • "code_execution_20260120"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • defer_loading: optional boolean

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

      • strict: optional boolean

        When true, guarantees schema validation on tool names and inputs

    • BetaMCPToolset object { mcp_server_name, type, cache_control, 2 more }

      Configuration for a group of tools from an MCP server.

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

      • mcp_server_name: string

        Name of the MCP server to configure tools for

      • type: "mcp_toolset"

        • "mcp_toolset"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • configs: optional map[BetaMCPToolConfig]

        Configuration overrides for specific tools, keyed by tool name

        • defer_loading: optional boolean

        • enabled: optional boolean

      • default_config: optional BetaMCPToolDefaultConfig

        Default configuration applied to all tools from this server

        • defer_loading: optional boolean

        • enabled: optional boolean

Beta Tool Use Block

  • BetaToolUseBlock object { id, input, name, 2 more }

    • id: string

    • input: map[unknown]

    • name: string

    • type: "tool_use"

      • "tool_use"

    • caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

      Tool invocation directly from the model.

      • BetaDirectCaller object { type }

        Tool invocation directly from the model.

        • type: "direct"

          • "direct"

      • BetaServerToolCaller object { tool_id, type }

        Tool invocation generated by a server-side tool.

        • tool_id: string

        • type: "code_execution_20250825"

          • "code_execution_20250825"

      • BetaServerToolCaller20260120 object { tool_id, type }

        • tool_id: string

        • type: "code_execution_20260120"

          • "code_execution_20260120"

Beta Tool Use Block Param

  • BetaToolUseBlockParam object { id, input, name, 3 more }

    • id: string

    • input: map[unknown]

    • name: string

    • type: "tool_use"

      • "tool_use"

    • cache_control: optional BetaCacheControlEphemeral

      Create a cache control breakpoint at this content block.

      • type: "ephemeral"

        • "ephemeral"

      • ttl: optional "5m" or "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: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

      Tool invocation directly from the model.

      • BetaDirectCaller object { type }

        Tool invocation directly from the model.

        • type: "direct"

          • "direct"

      • BetaServerToolCaller object { tool_id, type }

        Tool invocation generated by a server-side tool.

        • tool_id: string

        • type: "code_execution_20250825"

          • "code_execution_20250825"

      • BetaServerToolCaller20260120 object { tool_id, type }

        • tool_id: string

        • type: "code_execution_20260120"

          • "code_execution_20260120"

Beta Tool Uses Keep

  • BetaToolUsesKeep object { type, value }

    • type: "tool_uses"

      • "tool_uses"

    • value: number

Beta Tool Uses Trigger

  • BetaToolUsesTrigger object { type, value }

    • type: "tool_uses"

      • "tool_uses"

    • value: number

Beta URL Image Source

  • BetaURLImageSource object { type, url }

    • type: "url"

      • "url"

    • url: string

Beta URL PDF Source

  • BetaURLPDFSource object { type, url }

    • type: "url"

      • "url"

    • url: string

Beta Usage

  • BetaUsage object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 7 more }

    • cache_creation: BetaCacheCreation

      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.

    • inference_geo: string

      The geographic region where inference was performed for this request.

    • input_tokens: number

      The number of input tokens which were used.

    • iterations: BetaIterationsUsage

      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 object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }

        Token usage for a sampling iteration.

        • cache_creation: BetaCacheCreation

          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 object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }

        Token usage for a compaction iteration.

        • cache_creation: BetaCacheCreation

          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 object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 4 more }

        Token usage for an advisor sub-inference iteration.

        • cache_creation: BetaCacheCreation

          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 for additional details and options.

          • "claude-opus-4-7" or "claude-mythos-preview" or "claude-opus-4-6" or 14 more

            The model that will complete your prompt.

            See models for additional details and options.

            • "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.

    • server_tool_use: BetaServerToolUsage

      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" or "priority" or "batch"

      If the request used the priority, standard, or batch tier.

      • "standard"

      • "priority"

      • "batch"

    • speed: "standard" or "fast"

      The inference speed mode used for this request.

      • "standard"

      • "fast"

Beta User Location

  • BetaUserLocation object { type, city, country, 2 more }

    • type: "approximate"

      • "approximate"

    • city: optional string

      The city of the user.

    • country: optional string

      The two letter ISO country code of the user.

    • region: optional string

      The region of the user.

    • timezone: optional string

      The IANA timezone of the user.

Beta Web Fetch Block

  • BetaWebFetchBlock object { content, retrieved_at, type, url }

    • content: BetaDocumentBlock

      • citations: BetaCitationConfig

        Citation configuration for the document

        • enabled: boolean

      • source: BetaBase64PDFSource or BetaPlainTextSource

        • BetaBase64PDFSource object { data, media_type, type }

          • data: string

          • media_type: "application/pdf"

            • "application/pdf"

          • type: "base64"

            • "base64"

        • BetaPlainTextSource object { data, media_type, type }

          • data: string

          • media_type: "text/plain"

            • "text/plain"

          • type: "text"

            • "text"

      • title: string

        The title of the document

      • type: "document"

        • "document"

    • retrieved_at: string

      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 object { content, type, url, retrieved_at }

    • content: BetaRequestDocumentBlock

      • source: BetaBase64PDFSource or BetaPlainTextSource or BetaContentBlockSource or 2 more

        • BetaBase64PDFSource object { data, media_type, type }

          • data: string

          • media_type: "application/pdf"

            • "application/pdf"

          • type: "base64"

            • "base64"

        • BetaPlainTextSource object { data, media_type, type }

          • data: string

          • media_type: "text/plain"

            • "text/plain"

          • type: "text"

            • "text"

        • BetaContentBlockSource object { content, type }

          • content: string or array of BetaContentBlockSourceContent

            • string

            • BetaContentBlockSourceContent = array of BetaContentBlockSourceContent

              • BetaTextBlockParam object { text, type, cache_control, citations }

                • text: string

                • type: "text"

                  • "text"

                • cache_control: optional BetaCacheControlEphemeral

                  Create a cache control breakpoint at this content block.

                  • type: "ephemeral"

                    • "ephemeral"

                  • ttl: optional "5m" or "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: optional array of BetaTextCitationParam

                  • BetaCitationCharLocationParam object { cited_text, document_index, document_title, 3 more }

                    • cited_text: string

                    • document_index: number

                    • document_title: string

                    • end_char_index: number

                    • start_char_index: number

                    • type: "char_location"

                      • "char_location"

                  • BetaCitationPageLocationParam object { cited_text, document_index, document_title, 3 more }

                    • cited_text: string

                    • document_index: number

                    • document_title: string

                    • end_page_number: number

                    • start_page_number: number

                    • type: "page_location"

                      • "page_location"

                  • BetaCitationContentBlockLocationParam object { cited_text, document_index, document_title, 3 more }

                    • 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

                    • 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 object { cited_text, encrypted_index, title, 2 more }

                    • cited_text: string

                    • encrypted_index: string

                    • title: string

                    • type: "web_search_result_location"

                      • "web_search_result_location"

                    • url: string

                  • BetaCitationSearchResultLocationParam object { cited_text, end_block_index, search_result_index, 4 more }

                    • 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

                    • type: "search_result_location"

                      • "search_result_location"

              • BetaImageBlockParam object { source, type, cache_control }

                • source: BetaBase64ImageSource or BetaURLImageSource or BetaFileImageSource

                  • BetaBase64ImageSource object { data, media_type, type }

                    • data: string

                    • media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"

                      • "image/jpeg"

                      • "image/png"

                      • "image/gif"

                      • "image/webp"

                    • type: "base64"

                      • "base64"

                  • BetaURLImageSource object { type, url }

                    • type: "url"

                      • "url"

                    • url: string

                  • BetaFileImageSource object { file_id, type }

                    • file_id: string

                    • type: "file"

                      • "file"

                • type: "image"

                  • "image"

                • cache_control: optional BetaCacheControlEphemeral

                  Create a cache control breakpoint at this content block.

          • type: "content"

            • "content"

        • BetaURLPDFSource object { type, url }

          • type: "url"

            • "url"

          • url: string

        • BetaFileDocumentSource object { file_id, type }

          • file_id: string

          • type: "file"

            • "file"

      • type: "document"

        • "document"

      • cache_control: optional BetaCacheControlEphemeral

        Create a cache control breakpoint at this content block.

      • citations: optional BetaCitationsConfigParam

        • enabled: optional boolean

      • context: optional string

      • title: optional string

    • type: "web_fetch_result"

      • "web_fetch_result"

    • url: string

      Fetched content URL

    • retrieved_at: optional string

      ISO 8601 timestamp when the content was retrieved

Beta Web Fetch Tool 20250910

  • BetaWebFetchTool20250910 object { name, type, allowed_callers, 8 more }

    • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

      • "direct"

      • "code_execution_20250825"

      • "code_execution_20260120"

    • allowed_domains: optional array of string

      List of domains to allow fetching from

    • blocked_domains: optional array of string

      List of domains to block fetching from

    • cache_control: optional BetaCacheControlEphemeral

      Create a cache control breakpoint at this content block.

      • type: "ephemeral"

        • "ephemeral"

      • ttl: optional "5m" or "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: optional BetaCitationsConfigParam

      Citations configuration for fetched documents. Citations are disabled by default.

      • enabled: optional boolean

    • defer_loading: optional 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: optional number

      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: optional number

      Maximum number of times the tool can be used in the API request.

    • strict: optional boolean

      When true, guarantees schema validation on tool names and inputs

Beta Web Fetch Tool 20260209

  • BetaWebFetchTool20260209 object { name, type, allowed_callers, 8 more }

    • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

      • "direct"

      • "code_execution_20250825"

      • "code_execution_20260120"

    • allowed_domains: optional array of string

      List of domains to allow fetching from

    • blocked_domains: optional array of string

      List of domains to block fetching from

    • cache_control: optional BetaCacheControlEphemeral

      Create a cache control breakpoint at this content block.

      • type: "ephemeral"

        • "ephemeral"

      • ttl: optional "5m" or "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: optional BetaCitationsConfigParam

      Citations configuration for fetched documents. Citations are disabled by default.

      • enabled: optional boolean

    • defer_loading: optional 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: optional number

      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: optional number

      Maximum number of times the tool can be used in the API request.

    • strict: optional boolean

      When true, guarantees schema validation on tool names and inputs

Beta Web Fetch Tool 20260309

  • BetaWebFetchTool20260309 object { name, type, allowed_callers, 9 more }

    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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

      • "direct"

      • "code_execution_20250825"

      • "code_execution_20260120"

    • allowed_domains: optional array of string

      List of domains to allow fetching from

    • blocked_domains: optional array of string

      List of domains to block fetching from

    • cache_control: optional BetaCacheControlEphemeral

      Create a cache control breakpoint at this content block.

      • type: "ephemeral"

        • "ephemeral"

      • ttl: optional "5m" or "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: optional BetaCitationsConfigParam

      Citations configuration for fetched documents. Citations are disabled by default.

      • enabled: optional boolean

    • defer_loading: optional 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: optional number

      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: optional number

      Maximum number of times the tool can be used in the API request.

    • strict: optional boolean

      When true, guarantees schema validation on tool names and inputs

    • use_cache: optional 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 object { content, tool_use_id, type, caller }

    • content: BetaWebFetchToolResultErrorBlock or BetaWebFetchBlock

      • BetaWebFetchToolResultErrorBlock object { error_code, type }

        • error_code: BetaWebFetchToolResultErrorCode

          • "invalid_tool_input"

          • "url_too_long"

          • "url_not_allowed"

          • "url_not_accessible"

          • "unsupported_content_type"

          • "too_many_requests"

          • "max_uses_exceeded"

          • "unavailable"

        • type: "web_fetch_tool_result_error"

          • "web_fetch_tool_result_error"

      • BetaWebFetchBlock object { content, retrieved_at, type, url }

        • content: BetaDocumentBlock

          • citations: BetaCitationConfig

            Citation configuration for the document

            • enabled: boolean

          • source: BetaBase64PDFSource or BetaPlainTextSource

            • BetaBase64PDFSource object { data, media_type, type }

              • data: string

              • media_type: "application/pdf"

                • "application/pdf"

              • type: "base64"

                • "base64"

            • BetaPlainTextSource object { data, media_type, type }

              • data: string

              • media_type: "text/plain"

                • "text/plain"

              • type: "text"

                • "text"

          • title: string

            The title of the document

          • type: "document"

            • "document"

        • retrieved_at: string

          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: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

      Tool invocation directly from the model.

      • BetaDirectCaller object { type }

        Tool invocation directly from the model.

        • type: "direct"

          • "direct"

      • BetaServerToolCaller object { tool_id, type }

        Tool invocation generated by a server-side tool.

        • tool_id: string

        • type: "code_execution_20250825"

          • "code_execution_20250825"

      • BetaServerToolCaller20260120 object { tool_id, type }

        • tool_id: string

        • type: "code_execution_20260120"

          • "code_execution_20260120"

Beta Web Fetch Tool Result Block Param

  • BetaWebFetchToolResultBlockParam object { content, tool_use_id, type, 2 more }

    • content: BetaWebFetchToolResultErrorBlockParam or BetaWebFetchBlockParam

      • BetaWebFetchToolResultErrorBlockParam object { error_code, type }

        • error_code: BetaWebFetchToolResultErrorCode

          • "invalid_tool_input"

          • "url_too_long"

          • "url_not_allowed"

          • "url_not_accessible"

          • "unsupported_content_type"

          • "too_many_requests"

          • "max_uses_exceeded"

          • "unavailable"

        • type: "web_fetch_tool_result_error"

          • "web_fetch_tool_result_error"

      • BetaWebFetchBlockParam object { content, type, url, retrieved_at }

        • content: BetaRequestDocumentBlock

          • source: BetaBase64PDFSource or BetaPlainTextSource or BetaContentBlockSource or 2 more

            • BetaBase64PDFSource object { data, media_type, type }

              • data: string

              • media_type: "application/pdf"

                • "application/pdf"

              • type: "base64"

                • "base64"

            • BetaPlainTextSource object { data, media_type, type }

              • data: string

              • media_type: "text/plain"

                • "text/plain"

              • type: "text"

                • "text"

            • BetaContentBlockSource object { content, type }

              • content: string or array of BetaContentBlockSourceContent

                • string

                • BetaContentBlockSourceContent = array of BetaContentBlockSourceContent

                  • BetaTextBlockParam object { text, type, cache_control, citations }

                    • text: string

                    • type: "text"

                      • "text"

                    • cache_control: optional BetaCacheControlEphemeral

                      Create a cache control breakpoint at this content block.

                      • type: "ephemeral"

                        • "ephemeral"

                      • ttl: optional "5m" or "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: optional array of BetaTextCitationParam

                      • BetaCitationCharLocationParam object { cited_text, document_index, document_title, 3 more }

                        • cited_text: string

                        • document_index: number

                        • document_title: string

                        • end_char_index: number

                        • start_char_index: number

                        • type: "char_location"

                          • "char_location"

                      • BetaCitationPageLocationParam object { cited_text, document_index, document_title, 3 more }

                        • cited_text: string

                        • document_index: number

                        • document_title: string

                        • end_page_number: number

                        • start_page_number: number

                        • type: "page_location"

                          • "page_location"

                      • BetaCitationContentBlockLocationParam object { cited_text, document_index, document_title, 3 more }

                        • 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

                        • 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 object { cited_text, encrypted_index, title, 2 more }

                        • cited_text: string

                        • encrypted_index: string

                        • title: string

                        • type: "web_search_result_location"

                          • "web_search_result_location"

                        • url: string

                      • BetaCitationSearchResultLocationParam object { cited_text, end_block_index, search_result_index, 4 more }

                        • 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

                        • type: "search_result_location"

                          • "search_result_location"

                  • BetaImageBlockParam object { source, type, cache_control }

                    • source: BetaBase64ImageSource or BetaURLImageSource or BetaFileImageSource

                      • BetaBase64ImageSource object { data, media_type, type }

                        • data: string

                        • media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"

                          • "image/jpeg"

                          • "image/png"

                          • "image/gif"

                          • "image/webp"

                        • type: "base64"

                          • "base64"

                      • BetaURLImageSource object { type, url }

                        • type: "url"

                          • "url"

                        • url: string

                      • BetaFileImageSource object { file_id, type }

                        • file_id: string

                        • type: "file"

                          • "file"

                    • type: "image"

                      • "image"

                    • cache_control: optional BetaCacheControlEphemeral

                      Create a cache control breakpoint at this content block.

              • type: "content"

                • "content"

            • BetaURLPDFSource object { type, url }

              • type: "url"

                • "url"

              • url: string

            • BetaFileDocumentSource object { file_id, type }

              • file_id: string

              • type: "file"

                • "file"

          • type: "document"

            • "document"

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

          • citations: optional BetaCitationsConfigParam

            • enabled: optional boolean

          • context: optional string

          • title: optional string

        • type: "web_fetch_result"

          • "web_fetch_result"

        • url: string

          Fetched content URL

        • retrieved_at: optional string

          ISO 8601 timestamp when the content was retrieved

    • tool_use_id: string

    • type: "web_fetch_tool_result"

      • "web_fetch_tool_result"

    • cache_control: optional BetaCacheControlEphemeral

      Create a cache control breakpoint at this content block.

    • caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

      Tool invocation directly from the model.

      • BetaDirectCaller object { type }

        Tool invocation directly from the model.

        • type: "direct"

          • "direct"

      • BetaServerToolCaller object { tool_id, type }

        Tool invocation generated by a server-side tool.

        • tool_id: string

        • type: "code_execution_20250825"

          • "code_execution_20250825"

      • BetaServerToolCaller20260120 object { tool_id, type }

        • tool_id: string

        • type: "code_execution_20260120"

          • "code_execution_20260120"

Beta Web Fetch Tool Result Error Block

  • BetaWebFetchToolResultErrorBlock object { error_code, type }

    • error_code: BetaWebFetchToolResultErrorCode

      • "invalid_tool_input"

      • "url_too_long"

      • "url_not_allowed"

      • "url_not_accessible"

      • "unsupported_content_type"

      • "too_many_requests"

      • "max_uses_exceeded"

      • "unavailable"

    • type: "web_fetch_tool_result_error"

      • "web_fetch_tool_result_error"

Beta Web Fetch Tool Result Error Block Param

  • BetaWebFetchToolResultErrorBlockParam object { error_code, type }

    • error_code: BetaWebFetchToolResultErrorCode

      • "invalid_tool_input"

      • "url_too_long"

      • "url_not_allowed"

      • "url_not_accessible"

      • "unsupported_content_type"

      • "too_many_requests"

      • "max_uses_exceeded"

      • "unavailable"

    • type: "web_fetch_tool_result_error"

      • "web_fetch_tool_result_error"

Beta Web Fetch Tool Result Error Code

  • BetaWebFetchToolResultErrorCode = "invalid_tool_input" or "url_too_long" or "url_not_allowed" or 5 more

    • "invalid_tool_input"

    • "url_too_long"

    • "url_not_allowed"

    • "url_not_accessible"

    • "unsupported_content_type"

    • "too_many_requests"

    • "max_uses_exceeded"

    • "unavailable"

Beta Web Search Result Block

  • BetaWebSearchResultBlock object { encrypted_content, page_age, title, 2 more }

    • encrypted_content: string

    • page_age: string

    • title: string

    • type: "web_search_result"

      • "web_search_result"

    • url: string

Beta Web Search Result Block Param

  • BetaWebSearchResultBlockParam object { encrypted_content, title, type, 2 more }

    • encrypted_content: string

    • title: string

    • type: "web_search_result"

      • "web_search_result"

    • url: string

    • page_age: optional string

Beta Web Search Tool 20250305

  • BetaWebSearchTool20250305 object { name, type, allowed_callers, 7 more }

    • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

      • "direct"

      • "code_execution_20250825"

      • "code_execution_20260120"

    • allowed_domains: optional array of string

      If provided, only these domains will be included in results. Cannot be used alongside blocked_domains.

    • blocked_domains: optional array of string

      If provided, these domains will never appear in results. Cannot be used alongside allowed_domains.

    • cache_control: optional BetaCacheControlEphemeral

      Create a cache control breakpoint at this content block.

      • type: "ephemeral"

        • "ephemeral"

      • ttl: optional "5m" or "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: optional boolean

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

    • max_uses: optional number

      Maximum number of times the tool can be used in the API request.

    • strict: optional boolean

      When true, guarantees schema validation on tool names and inputs

    • user_location: optional BetaUserLocation

      Parameters for the user's location. Used to provide more relevant search results.

      • type: "approximate"

        • "approximate"

      • city: optional string

        The city of the user.

      • country: optional string

        The two letter ISO country code of the user.

      • region: optional string

        The region of the user.

      • timezone: optional string

        The IANA timezone of the user.

Beta Web Search Tool 20260209

  • BetaWebSearchTool20260209 object { name, type, allowed_callers, 7 more }

    • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

      • "direct"

      • "code_execution_20250825"

      • "code_execution_20260120"

    • allowed_domains: optional array of string

      If provided, only these domains will be included in results. Cannot be used alongside blocked_domains.

    • blocked_domains: optional array of string

      If provided, these domains will never appear in results. Cannot be used alongside allowed_domains.

    • cache_control: optional BetaCacheControlEphemeral

      Create a cache control breakpoint at this content block.

      • type: "ephemeral"

        • "ephemeral"

      • ttl: optional "5m" or "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: optional boolean

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

    • max_uses: optional number

      Maximum number of times the tool can be used in the API request.

    • strict: optional boolean

      When true, guarantees schema validation on tool names and inputs

    • user_location: optional BetaUserLocation

      Parameters for the user's location. Used to provide more relevant search results.

      • type: "approximate"

        • "approximate"

      • city: optional string

        The city of the user.

      • country: optional string

        The two letter ISO country code of the user.

      • region: optional string

        The region of the user.

      • timezone: optional string

        The IANA timezone of the user.

Beta Web Search Tool Request Error

  • BetaWebSearchToolRequestError object { error_code, type }

    • 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 object { content, tool_use_id, type, caller }

    • content: BetaWebSearchToolResultBlockContent

      • BetaWebSearchToolResultError object { error_code, type }

        • 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 of BetaWebSearchResultBlock

        • encrypted_content: string

        • page_age: string

        • 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: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

      Tool invocation directly from the model.

      • BetaDirectCaller object { type }

        Tool invocation directly from the model.

        • type: "direct"

          • "direct"

      • BetaServerToolCaller object { tool_id, type }

        Tool invocation generated by a server-side tool.

        • tool_id: string

        • type: "code_execution_20250825"

          • "code_execution_20250825"

      • BetaServerToolCaller20260120 object { tool_id, type }

        • tool_id: string

        • type: "code_execution_20260120"

          • "code_execution_20260120"

Beta Web Search Tool Result Block Content

  • BetaWebSearchToolResultBlockContent = BetaWebSearchToolResultError or array of BetaWebSearchResultBlock

    • BetaWebSearchToolResultError object { error_code, type }

      • 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 of BetaWebSearchResultBlock

      • encrypted_content: string

      • page_age: string

      • title: string

      • type: "web_search_result"

        • "web_search_result"

      • url: string

Beta Web Search Tool Result Block Param

  • BetaWebSearchToolResultBlockParam object { content, tool_use_id, type, 2 more }

    • content: BetaWebSearchToolResultBlockParamContent

      • ResultBlock = array of BetaWebSearchResultBlockParam

        • encrypted_content: string

        • title: string

        • type: "web_search_result"

          • "web_search_result"

        • url: string

        • page_age: optional string

      • BetaWebSearchToolRequestError object { error_code, type }

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

      Create a cache control breakpoint at this content block.

      • type: "ephemeral"

        • "ephemeral"

      • ttl: optional "5m" or "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: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

      Tool invocation directly from the model.

      • BetaDirectCaller object { type }

        Tool invocation directly from the model.

        • type: "direct"

          • "direct"

      • BetaServerToolCaller object { tool_id, type }

        Tool invocation generated by a server-side tool.

        • tool_id: string

        • type: "code_execution_20250825"

          • "code_execution_20250825"

      • BetaServerToolCaller20260120 object { tool_id, type }

        • tool_id: string

        • type: "code_execution_20260120"

          • "code_execution_20260120"

Beta Web Search Tool Result Block Param Content

  • BetaWebSearchToolResultBlockParamContent = array of BetaWebSearchResultBlockParam or BetaWebSearchToolRequestError

    • ResultBlock = array of BetaWebSearchResultBlockParam

      • encrypted_content: string

      • title: string

      • type: "web_search_result"

        • "web_search_result"

      • url: string

      • page_age: optional string

    • BetaWebSearchToolRequestError object { error_code, type }

      • 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 object { error_code, type }

    • 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" or "unavailable" or "max_uses_exceeded" or 3 more

    • "invalid_tool_input"

    • "unavailable"

    • "max_uses_exceeded"

    • "too_many_requests"

    • "query_too_long"

    • "request_too_large"

Batches

Create a Message Batch

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

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Body Parameters

  • requests: array of object { custom_id, params }

    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: object { max_tokens, messages, model, 21 more }

      Messages API creation parameters for the individual request.

      See the Messages API reference 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 without generating a response.

        Different models have different maximum values for this parameter. See models for details.

      • messages: array of BetaMessageParam

        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:

        [{"role": "user", "content": "Hello, Claude"}]

        Example with multiple conversational turns:

        [
  {"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:

        [
  {"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:

        {"role": "user", "content": "Hello, Claude"}

        {"role": "user", "content": [{"type": "text", "text": "Hello, Claude"}]}

        See input examples.

        Note that if you want to include a system prompt, 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 or array of BetaContentBlockParam

          • string

          • array of BetaContentBlockParam

            • BetaTextBlockParam object { text, type, cache_control, citations }

              • text: string

              • type: "text"

                • "text"

              • cache_control: optional BetaCacheControlEphemeral

                Create a cache control breakpoint at this content block.

                • type: "ephemeral"

                  • "ephemeral"

                • ttl: optional "5m" or "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: optional array of BetaTextCitationParam

                • BetaCitationCharLocationParam object { cited_text, document_index, document_title, 3 more }

                  • cited_text: string

                  • document_index: number

                  • document_title: string

                  • end_char_index: number

                  • start_char_index: number

                  • type: "char_location"

                    • "char_location"

                • BetaCitationPageLocationParam object { cited_text, document_index, document_title, 3 more }

                  • cited_text: string

                  • document_index: number

                  • document_title: string

                  • end_page_number: number

                  • start_page_number: number

                  • type: "page_location"

                    • "page_location"

                • BetaCitationContentBlockLocationParam object { cited_text, document_index, document_title, 3 more }

                  • 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

                  • 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 object { cited_text, encrypted_index, title, 2 more }

                  • cited_text: string

                  • encrypted_index: string

                  • title: string

                  • type: "web_search_result_location"

                    • "web_search_result_location"

                  • url: string

                • BetaCitationSearchResultLocationParam object { cited_text, end_block_index, search_result_index, 4 more }

                  • 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

                  • type: "search_result_location"

                    • "search_result_location"

            • BetaImageBlockParam object { source, type, cache_control }

              • source: BetaBase64ImageSource or BetaURLImageSource or BetaFileImageSource

                • BetaBase64ImageSource object { data, media_type, type }

                  • data: string

                  • media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"

                    • "image/jpeg"

                    • "image/png"

                    • "image/gif"

                    • "image/webp"

                  • type: "base64"

                    • "base64"

                • BetaURLImageSource object { type, url }

                  • type: "url"

                    • "url"

                  • url: string

                • BetaFileImageSource object { file_id, type }

                  • file_id: string

                  • type: "file"

                    • "file"

              • type: "image"

                • "image"

              • cache_control: optional BetaCacheControlEphemeral

                Create a cache control breakpoint at this content block.

            • BetaRequestDocumentBlock object { source, type, cache_control, 3 more }

              • source: BetaBase64PDFSource or BetaPlainTextSource or BetaContentBlockSource or 2 more

                • BetaBase64PDFSource object { data, media_type, type }

                  • data: string

                  • media_type: "application/pdf"

                    • "application/pdf"

                  • type: "base64"

                    • "base64"

                • BetaPlainTextSource object { data, media_type, type }

                  • data: string

                  • media_type: "text/plain"

                    • "text/plain"

                  • type: "text"

                    • "text"

                • BetaContentBlockSource object { content, type }

                  • content: string or array of BetaContentBlockSourceContent

                    • string

                    • BetaContentBlockSourceContent = array of BetaContentBlockSourceContent

                      • BetaTextBlockParam object { text, type, cache_control, citations }

                      • BetaImageBlockParam object { source, type, cache_control }

                  • type: "content"

                    • "content"

                • BetaURLPDFSource object { type, url }

                  • type: "url"

                    • "url"

                  • url: string

                • BetaFileDocumentSource object { file_id, type }

                  • file_id: string

                  • type: "file"

                    • "file"

              • type: "document"

                • "document"

              • cache_control: optional BetaCacheControlEphemeral

                Create a cache control breakpoint at this content block.

              • citations: optional BetaCitationsConfigParam

                • enabled: optional boolean

              • context: optional string

              • title: optional string

            • BetaSearchResultBlockParam object { content, source, title, 3 more }

              • content: array of BetaTextBlockParam

                • text: string

                • type: "text"

                • cache_control: optional BetaCacheControlEphemeral

                  Create a cache control breakpoint at this content block.

                • citations: optional array of BetaTextCitationParam

              • source: string

              • title: string

              • type: "search_result"

                • "search_result"

              • cache_control: optional BetaCacheControlEphemeral

                Create a cache control breakpoint at this content block.

              • citations: optional BetaCitationsConfigParam

            • BetaThinkingBlockParam object { signature, thinking, type }

              • signature: string

              • thinking: string

              • type: "thinking"

                • "thinking"

            • BetaRedactedThinkingBlockParam object { data, type }

              • data: string

              • type: "redacted_thinking"

                • "redacted_thinking"

            • BetaToolUseBlockParam object { id, input, name, 3 more }

              • id: string

              • input: map[unknown]

              • name: string

              • type: "tool_use"

                • "tool_use"

              • cache_control: optional BetaCacheControlEphemeral

                Create a cache control breakpoint at this content block.

              • caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

                Tool invocation directly from the model.

                • BetaDirectCaller object { type }

                  Tool invocation directly from the model.

                  • type: "direct"

                    • "direct"

                • BetaServerToolCaller object { tool_id, type }

                  Tool invocation generated by a server-side tool.

                  • tool_id: string

                  • type: "code_execution_20250825"

                    • "code_execution_20250825"

                • BetaServerToolCaller20260120 object { tool_id, type }

                  • tool_id: string

                  • type: "code_execution_20260120"

                    • "code_execution_20260120"

            • BetaToolResultBlockParam object { tool_use_id, type, cache_control, 2 more }

              • tool_use_id: string

              • type: "tool_result"

                • "tool_result"

              • cache_control: optional BetaCacheControlEphemeral

                Create a cache control breakpoint at this content block.

              • content: optional string or array of BetaTextBlockParam or BetaImageBlockParam or BetaSearchResultBlockParam or 2 more

                • string

                • array of BetaTextBlockParam or BetaImageBlockParam or BetaSearchResultBlockParam or 2 more

                  • BetaTextBlockParam object { text, type, cache_control, citations }

                  • BetaImageBlockParam object { source, type, cache_control }

                  • BetaSearchResultBlockParam object { content, source, title, 3 more }

                  • BetaRequestDocumentBlock object { source, type, cache_control, 3 more }

                  • BetaToolReferenceBlockParam object { tool_name, type, cache_control }

                    Tool reference block that can be included in tool_result content.

                    • tool_name: string

                    • type: "tool_reference"

                      • "tool_reference"

                    • cache_control: optional BetaCacheControlEphemeral

                      Create a cache control breakpoint at this content block.

              • is_error: optional boolean

            • BetaServerToolUseBlockParam object { id, input, name, 3 more }

              • id: string

              • input: map[unknown]

              • name: "advisor" or "web_search" or "web_fetch" or 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: optional BetaCacheControlEphemeral

                Create a cache control breakpoint at this content block.

              • caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

                Tool invocation directly from the model.

                • BetaDirectCaller object { type }

                  Tool invocation directly from the model.

                • BetaServerToolCaller object { tool_id, type }

                  Tool invocation generated by a server-side tool.

                • BetaServerToolCaller20260120 object { tool_id, type }

            • BetaWebSearchToolResultBlockParam object { content, tool_use_id, type, 2 more }

              • content: BetaWebSearchToolResultBlockParamContent

                • ResultBlock = array of BetaWebSearchResultBlockParam

                  • encrypted_content: string

                  • title: string

                  • type: "web_search_result"

                    • "web_search_result"

                  • url: string

                  • page_age: optional string

                • BetaWebSearchToolRequestError object { error_code, type }

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

                Create a cache control breakpoint at this content block.

              • caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

                Tool invocation directly from the model.

                • BetaDirectCaller object { type }

                  Tool invocation directly from the model.

                • BetaServerToolCaller object { tool_id, type }

                  Tool invocation generated by a server-side tool.

                • BetaServerToolCaller20260120 object { tool_id, type }

            • BetaWebFetchToolResultBlockParam object { content, tool_use_id, type, 2 more }

              • content: BetaWebFetchToolResultErrorBlockParam or BetaWebFetchBlockParam

                • BetaWebFetchToolResultErrorBlockParam object { error_code, type }

                  • error_code: BetaWebFetchToolResultErrorCode

                    • "invalid_tool_input"

                    • "url_too_long"

                    • "url_not_allowed"

                    • "url_not_accessible"

                    • "unsupported_content_type"

                    • "too_many_requests"

                    • "max_uses_exceeded"

                    • "unavailable"

                  • type: "web_fetch_tool_result_error"

                    • "web_fetch_tool_result_error"

                • BetaWebFetchBlockParam object { content, type, url, retrieved_at }

                  • content: BetaRequestDocumentBlock

                  • type: "web_fetch_result"

                    • "web_fetch_result"

                  • url: string

                    Fetched content URL

                  • retrieved_at: optional string

                    ISO 8601 timestamp when the content was retrieved

              • tool_use_id: string

              • type: "web_fetch_tool_result"

                • "web_fetch_tool_result"

              • cache_control: optional BetaCacheControlEphemeral

                Create a cache control breakpoint at this content block.

              • caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

                Tool invocation directly from the model.

                • BetaDirectCaller object { type }

                  Tool invocation directly from the model.

                • BetaServerToolCaller object { tool_id, type }

                  Tool invocation generated by a server-side tool.

                • BetaServerToolCaller20260120 object { tool_id, type }

            • BetaAdvisorToolResultBlockParam object { content, tool_use_id, type, cache_control }

              • content: BetaAdvisorToolResultErrorParam or BetaAdvisorResultBlockParam or BetaAdvisorRedactedResultBlockParam

                • BetaAdvisorToolResultErrorParam object { error_code, type }

                  • error_code: "max_uses_exceeded" or "prompt_too_long" or "too_many_requests" or 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 object { text, type }

                  • text: string

                  • type: "advisor_result"

                    • "advisor_result"

                • BetaAdvisorRedactedResultBlockParam object { encrypted_content, type }

                  • encrypted_content: string

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

                  • type: "advisor_redacted_result"

                    • "advisor_redacted_result"

              • tool_use_id: string

              • type: "advisor_tool_result"

                • "advisor_tool_result"

              • cache_control: optional BetaCacheControlEphemeral

                Create a cache control breakpoint at this content block.

            • BetaCodeExecutionToolResultBlockParam object { content, tool_use_id, type, cache_control }

              • content: BetaCodeExecutionToolResultBlockParamContent

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

                • BetaCodeExecutionToolResultErrorParam object { error_code, type }

                  • 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 object { content, return_code, stderr, 2 more }

                  • content: array of BetaCodeExecutionOutputBlockParam

                    • 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 object { content, encrypted_stdout, return_code, 2 more }

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

                  • content: array of BetaCodeExecutionOutputBlockParam

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

                Create a cache control breakpoint at this content block.

            • BetaBashCodeExecutionToolResultBlockParam object { content, tool_use_id, type, cache_control }

              • content: BetaBashCodeExecutionToolResultErrorParam or BetaBashCodeExecutionResultBlockParam

                • BetaBashCodeExecutionToolResultErrorParam object { error_code, type }

                  • error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 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 object { content, return_code, stderr, 2 more }

                  • content: array of BetaBashCodeExecutionOutputBlockParam

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

                Create a cache control breakpoint at this content block.

            • BetaTextEditorCodeExecutionToolResultBlockParam object { content, tool_use_id, type, cache_control }

              • content: BetaTextEditorCodeExecutionToolResultErrorParam or BetaTextEditorCodeExecutionViewResultBlockParam or BetaTextEditorCodeExecutionCreateResultBlockParam or BetaTextEditorCodeExecutionStrReplaceResultBlockParam

                • BetaTextEditorCodeExecutionToolResultErrorParam object { error_code, type, error_message }

                  • error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 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: optional string

                • BetaTextEditorCodeExecutionViewResultBlockParam object { content, file_type, type, 3 more }

                  • content: string

                  • file_type: "text" or "image" or "pdf"

                    • "text"

                    • "image"

                    • "pdf"

                  • type: "text_editor_code_execution_view_result"

                    • "text_editor_code_execution_view_result"

                  • num_lines: optional number

                  • start_line: optional number

                  • total_lines: optional number

                • BetaTextEditorCodeExecutionCreateResultBlockParam object { is_file_update, type }

                  • is_file_update: boolean

                  • type: "text_editor_code_execution_create_result"

                    • "text_editor_code_execution_create_result"

                • BetaTextEditorCodeExecutionStrReplaceResultBlockParam object { type, lines, new_lines, 3 more }

                  • type: "text_editor_code_execution_str_replace_result"

                    • "text_editor_code_execution_str_replace_result"

                  • lines: optional array of string

                  • new_lines: optional number

                  • new_start: optional number

                  • old_lines: optional number

                  • old_start: optional number

              • tool_use_id: string

              • type: "text_editor_code_execution_tool_result"

                • "text_editor_code_execution_tool_result"

              • cache_control: optional BetaCacheControlEphemeral

                Create a cache control breakpoint at this content block.

            • BetaToolSearchToolResultBlockParam object { content, tool_use_id, type, cache_control }

              • content: BetaToolSearchToolResultErrorParam or BetaToolSearchToolSearchResultBlockParam

                • BetaToolSearchToolResultErrorParam object { error_code, type }

                  • error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "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 object { tool_references, type }

                  • tool_references: array of BetaToolReferenceBlockParam

                    • tool_name: string

                    • type: "tool_reference"

                    • cache_control: optional BetaCacheControlEphemeral

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

                Create a cache control breakpoint at this content block.

            • BetaMCPToolUseBlockParam object { id, input, name, 3 more }

              • id: string

              • input: map[unknown]

              • name: string

              • server_name: string

                The name of the MCP server

              • type: "mcp_tool_use"

                • "mcp_tool_use"

              • cache_control: optional BetaCacheControlEphemeral

                Create a cache control breakpoint at this content block.

            • BetaRequestMCPToolResultBlockParam object { tool_use_id, type, cache_control, 2 more }

              • tool_use_id: string

              • type: "mcp_tool_result"

                • "mcp_tool_result"

              • cache_control: optional BetaCacheControlEphemeral

                Create a cache control breakpoint at this content block.

              • content: optional string or array of BetaTextBlockParam

                • string

                • BetaMCPToolResultBlockParamContent = array of BetaTextBlockParam

                  • text: string

                  • type: "text"

                  • cache_control: optional BetaCacheControlEphemeral

                    Create a cache control breakpoint at this content block.

                  • citations: optional array of BetaTextCitationParam

              • is_error: optional boolean

            • BetaContainerUploadBlockParam object { file_id, type, cache_control }

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

              • file_id: string

              • type: "container_upload"

                • "container_upload"

              • cache_control: optional BetaCacheControlEphemeral

                Create a cache control breakpoint at this content block.

            • BetaCompactionBlockParam object { content, type, cache_control, encrypted_content }

              A compaction block containing summary of previous context.

              Users should round-trip these blocks from responses to subsequent requests to maintain context across compaction boundaries.

              When content is None, the block represents a failed compaction. The server treats these as no-ops. Empty string content is not allowed.

              • content: string

                Summary of previously compacted content, or null if compaction failed

              • type: "compaction"

                • "compaction"

              • cache_control: optional BetaCacheControlEphemeral

                Create a cache control breakpoint at this content block.

              • encrypted_content: optional string

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

        • role: "user" or "assistant"

          • "user"

          • "assistant"

      • model: Model

        The model that will complete your prompt.

        See models for additional details and options.

        • "claude-opus-4-7" or "claude-mythos-preview" or "claude-opus-4-6" or 14 more

          The model that will complete your prompt.

          See models for additional details and options.

          • "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: optional BetaCacheControlEphemeral

        Top-level cache control automatically applies a cache_control marker to the last cacheable block in the request.

      • container: optional BetaContainerParams or string

        Container identifier for reuse across requests.

        • BetaContainerParams object { id, skills }

          Container parameters with skills to be loaded.

          • id: optional string

            Container id

          • skills: optional array of BetaSkillParams

            List of skills to load in the container

            • skill_id: string

              Skill ID

            • type: "anthropic" or "custom"

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

              • "anthropic"

              • "custom"

            • version: optional string

              Skill version or 'latest' for most recent version

        • string

      • context_management: optional BetaContextManagementConfig

        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: optional array of BetaClearToolUses20250919Edit or BetaClearThinking20251015Edit or BetaCompact20260112Edit

          List of context management edits to apply

          • BetaClearToolUses20250919Edit object { type, clear_at_least, clear_tool_inputs, 3 more }

            • type: "clear_tool_uses_20250919"

              • "clear_tool_uses_20250919"

            • clear_at_least: optional BetaInputTokensClearAtLeast

              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: optional boolean or array of string

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

              • boolean

              • array of string

            • exclude_tools: optional array of string

              Tool names whose uses are preserved from clearing

            • keep: optional BetaToolUsesKeep

              Number of tool uses to retain in the conversation

              • type: "tool_uses"

                • "tool_uses"

              • value: number

            • trigger: optional BetaInputTokensTrigger or BetaToolUsesTrigger

              Condition that triggers the context management strategy

              • BetaInputTokensTrigger object { type, value }

                • type: "input_tokens"

                  • "input_tokens"

                • value: number

              • BetaToolUsesTrigger object { type, value }

                • type: "tool_uses"

                  • "tool_uses"

                • value: number

          • BetaClearThinking20251015Edit object { type, keep }

            • type: "clear_thinking_20251015"

              • "clear_thinking_20251015"

            • keep: optional BetaThinkingTurns or BetaAllThinkingTurns or "all"

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

              • BetaThinkingTurns object { type, value }

                • type: "thinking_turns"

                  • "thinking_turns"

                • value: number

              • BetaAllThinkingTurns object { type }

                • type: "all"

                  • "all"

              • "all"

                • "all"

          • BetaCompact20260112Edit object { type, instructions, pause_after_compaction, trigger }

            Automatically compact older context when reaching the configured trigger threshold.

            • type: "compact_20260112"

              • "compact_20260112"

            • instructions: optional string

              Additional instructions for summarization.

            • pause_after_compaction: optional boolean

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

            • trigger: optional BetaInputTokensTrigger

              When to trigger compaction. Defaults to 150000 input tokens.

      • diagnostics: optional BetaDiagnosticsParam

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

        • previous_message_id: optional string

          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: optional string

        Specifies the geographic region for inference processing. If not specified, the workspace's default_inference_geo is used.

      • mcp_servers: optional array of BetaRequestMCPServerURLDefinition

        MCP servers to be utilized in this request

        • name: string

        • type: "url"

          • "url"

        • url: string

        • authorization_token: optional string

        • tool_configuration: optional BetaRequestMCPServerToolConfiguration

          • allowed_tools: optional array of string

          • enabled: optional boolean

      • metadata: optional BetaMetadata

        An object describing metadata about the request.

        • user_id: optional string

          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: optional BetaOutputConfig

        Configuration options for the model's output, such as the output format.

        • effort: optional "low" or "medium" or "high" or 2 more

          All possible effort levels.

          • "low"

          • "medium"

          • "high"

          • "xhigh"

          • "max"

        • format: optional BetaJSONOutputFormat

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

          • schema: map[unknown]

            The JSON schema of the format

          • type: "json_schema"

            • "json_schema"

        • task_budget: optional 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: optional number

            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: optional BetaJSONOutputFormat

        Deprecated: Use output_config.format instead. See structured outputs

        A schema to specify Claude's output format in responses. This parameter will be removed in a future release.

      • service_tier: optional "auto" or "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 for details.

        • "auto"

        • "standard_only"

      • speed: optional "standard" or "fast"

        The inference speed mode for this request. "fast" enables high output-tokens-per-second inference.

        • "standard"

        • "fast"

      • stop_sequences: optional array of string

        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: optional boolean

        Whether to incrementally stream the response using server-sent events.

        See streaming for details.

      • system: optional string or array of BetaTextBlockParam

        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.

        • string

        • array of BetaTextBlockParam

          • text: string

          • type: "text"

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

          • citations: optional array of BetaTextCitationParam

      • temperature: optional 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: optional 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 for details.

        • BetaThinkingConfigEnabled object { budget_tokens, type, display }

          • 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 for details.

          • type: "enabled"

            • "enabled"

          • display: optional "summarized" or "omitted"

            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 object { type }

          • type: "disabled"

            • "disabled"

        • BetaThinkingConfigAdaptive object { type, display }

          • type: "adaptive"

            • "adaptive"

          • display: optional "summarized" or "omitted"

            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: optional 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 object { type, disable_parallel_tool_use }

          The model will automatically decide whether to use tools.

          • type: "auto"

            • "auto"

          • disable_parallel_tool_use: optional boolean

            Whether to disable parallel tool use.

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

        • BetaToolChoiceAny object { type, disable_parallel_tool_use }

          The model will use any available tools.

          • type: "any"

            • "any"

          • disable_parallel_tool_use: optional boolean

            Whether to disable parallel tool use.

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

        • BetaToolChoiceTool object { name, type, disable_parallel_tool_use }

          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: optional boolean

            Whether to disable parallel tool use.

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

        • BetaToolChoiceNone object { type }

          The model will not be allowed to use tools.

          • type: "none"

            • "none"

      • tools: optional array of BetaToolUnion

        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, see their individual documentation as each has its own behavior (e.g., the 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 for the tool input shape that the model will produce in tool_use output content blocks.

        For example, if you defined tools as:

        [
  {
    "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:

        [
  {
    "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:

        [
  {
    "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 for more details.

        • BetaTool object { input_schema, name, allowed_callers, 7 more }

          • input_schema: object { type, properties, required }

            JSON schema for this tool's input.

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

            • type: "object"

              • "object"

            • properties: optional map[unknown]

            • required: optional array of string

          • name: string

            Name of the tool.

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

          • allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

            • "direct"

            • "code_execution_20250825"

            • "code_execution_20260120"

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

          • defer_loading: optional boolean

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

          • description: optional 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: optional boolean

            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: optional array of map[unknown]

          • strict: optional boolean

            When true, guarantees schema validation on tool names and inputs

          • type: optional "custom"

            • "custom"

        • BetaToolBash20241022 object { name, type, allowed_callers, 4 more }

          • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

            • "direct"

            • "code_execution_20250825"

            • "code_execution_20260120"

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

          • defer_loading: optional boolean

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

          • input_examples: optional array of map[unknown]

          • strict: optional boolean

            When true, guarantees schema validation on tool names and inputs

        • BetaToolBash20250124 object { name, type, allowed_callers, 4 more }

          • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

            • "direct"

            • "code_execution_20250825"

            • "code_execution_20260120"

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

          • defer_loading: optional boolean

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

          • input_examples: optional array of map[unknown]

          • strict: optional boolean

            When true, guarantees schema validation on tool names and inputs

        • BetaCodeExecutionTool20250522 object { name, type, allowed_callers, 3 more }

          • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

            • "direct"

            • "code_execution_20250825"

            • "code_execution_20260120"

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

          • defer_loading: optional boolean

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

          • strict: optional boolean

            When true, guarantees schema validation on tool names and inputs

        • BetaCodeExecutionTool20250825 object { name, type, allowed_callers, 3 more }

          • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

            • "direct"

            • "code_execution_20250825"

            • "code_execution_20260120"

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

          • defer_loading: optional boolean

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

          • strict: optional boolean

            When true, guarantees schema validation on tool names and inputs

        • BetaCodeExecutionTool20260120 object { name, type, allowed_callers, 3 more }

          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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

            • "direct"

            • "code_execution_20250825"

            • "code_execution_20260120"

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

          • defer_loading: optional boolean

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

          • strict: optional boolean

            When true, guarantees schema validation on tool names and inputs

        • BetaToolComputerUse20241022 object { display_height_px, display_width_px, name, 7 more }

          • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

            • "direct"

            • "code_execution_20250825"

            • "code_execution_20260120"

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

          • defer_loading: optional boolean

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

          • display_number: optional number

            The X11 display number (e.g. 0, 1) for the display.

          • input_examples: optional array of map[unknown]

          • strict: optional boolean

            When true, guarantees schema validation on tool names and inputs

        • BetaMemoryTool20250818 object { name, type, allowed_callers, 4 more }

          • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

            • "direct"

            • "code_execution_20250825"

            • "code_execution_20260120"

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

          • defer_loading: optional boolean

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

          • input_examples: optional array of map[unknown]

          • strict: optional boolean

            When true, guarantees schema validation on tool names and inputs

        • BetaToolComputerUse20250124 object { display_height_px, display_width_px, name, 7 more }

          • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

            • "direct"

            • "code_execution_20250825"

            • "code_execution_20260120"

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

          • defer_loading: optional boolean

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

          • display_number: optional number

            The X11 display number (e.g. 0, 1) for the display.

          • input_examples: optional array of map[unknown]

          • strict: optional boolean

            When true, guarantees schema validation on tool names and inputs

        • BetaToolTextEditor20241022 object { name, type, allowed_callers, 4 more }

          • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

            • "direct"

            • "code_execution_20250825"

            • "code_execution_20260120"

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

          • defer_loading: optional boolean

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

          • input_examples: optional array of map[unknown]

          • strict: optional boolean

            When true, guarantees schema validation on tool names and inputs

        • BetaToolComputerUse20251124 object { display_height_px, display_width_px, name, 8 more }

          • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

            • "direct"

            • "code_execution_20250825"

            • "code_execution_20260120"

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

          • defer_loading: optional boolean

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

          • display_number: optional number

            The X11 display number (e.g. 0, 1) for the display.

          • enable_zoom: optional boolean

            Whether to enable an action to take a zoomed-in screenshot of the screen.

          • input_examples: optional array of map[unknown]

          • strict: optional boolean

            When true, guarantees schema validation on tool names and inputs

        • BetaToolTextEditor20250124 object { name, type, allowed_callers, 4 more }

          • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

            • "direct"

            • "code_execution_20250825"

            • "code_execution_20260120"

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

          • defer_loading: optional boolean

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

          • input_examples: optional array of map[unknown]

          • strict: optional boolean

            When true, guarantees schema validation on tool names and inputs

        • BetaToolTextEditor20250429 object { name, type, allowed_callers, 4 more }

          • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

            • "direct"

            • "code_execution_20250825"

            • "code_execution_20260120"

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

          • defer_loading: optional boolean

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

          • input_examples: optional array of map[unknown]

          • strict: optional boolean

            When true, guarantees schema validation on tool names and inputs

        • BetaToolTextEditor20250728 object { name, type, allowed_callers, 5 more }

          • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

            • "direct"

            • "code_execution_20250825"

            • "code_execution_20260120"

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

          • defer_loading: optional boolean

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

          • input_examples: optional array of map[unknown]

          • max_characters: optional number

            Maximum number of characters to display when viewing a file. If not specified, defaults to displaying the full file.

          • strict: optional boolean

            When true, guarantees schema validation on tool names and inputs

        • BetaWebSearchTool20250305 object { name, type, allowed_callers, 7 more }

          • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

            • "direct"

            • "code_execution_20250825"

            • "code_execution_20260120"

          • allowed_domains: optional array of string

            If provided, only these domains will be included in results. Cannot be used alongside blocked_domains.

          • blocked_domains: optional array of string

            If provided, these domains will never appear in results. Cannot be used alongside allowed_domains.

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

          • defer_loading: optional boolean

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

          • max_uses: optional number

            Maximum number of times the tool can be used in the API request.

          • strict: optional boolean

            When true, guarantees schema validation on tool names and inputs

          • user_location: optional BetaUserLocation

            Parameters for the user's location. Used to provide more relevant search results.

            • type: "approximate"

              • "approximate"

            • city: optional string

              The city of the user.

            • country: optional string

              The two letter ISO country code of the user.

            • region: optional string

              The region of the user.

            • timezone: optional string

              The IANA timezone of the user.

        • BetaWebFetchTool20250910 object { name, type, allowed_callers, 8 more }

          • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

            • "direct"

            • "code_execution_20250825"

            • "code_execution_20260120"

          • allowed_domains: optional array of string

            List of domains to allow fetching from

          • blocked_domains: optional array of string

            List of domains to block fetching from

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

          • citations: optional BetaCitationsConfigParam

            Citations configuration for fetched documents. Citations are disabled by default.

          • defer_loading: optional 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: optional number

            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: optional number

            Maximum number of times the tool can be used in the API request.

          • strict: optional boolean

            When true, guarantees schema validation on tool names and inputs

        • BetaWebSearchTool20260209 object { name, type, allowed_callers, 7 more }

          • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

            • "direct"

            • "code_execution_20250825"

            • "code_execution_20260120"

          • allowed_domains: optional array of string

            If provided, only these domains will be included in results. Cannot be used alongside blocked_domains.

          • blocked_domains: optional array of string

            If provided, these domains will never appear in results. Cannot be used alongside allowed_domains.

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

          • defer_loading: optional boolean

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

          • max_uses: optional number

            Maximum number of times the tool can be used in the API request.

          • strict: optional boolean

            When true, guarantees schema validation on tool names and inputs

          • user_location: optional BetaUserLocation

            Parameters for the user's location. Used to provide more relevant search results.

        • BetaWebFetchTool20260209 object { name, type, allowed_callers, 8 more }

          • 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

            • "direct"

            • "code_execution_20250825"

            • "code_execution_20260120"

          • allowed_domains: optional array of string

            List of domains to allow fetching from

          • blocked_domains: optional array of string

            List of domains to block fetching from

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

          • citations: optional BetaCitationsConfigParam

            Citations configuration for fetched documents. Citations are disabled by default.

          • defer_loading: optional 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: optional number

            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: optional number

            Maximum number of times the tool can be used in the API request.

          • strict: optional boolean

            When true, guarantees schema validation on tool names and inputs

        • BetaWebFetchTool20260309 object { name, type, allowed_callers, 9 more }

          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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

            • "direct"

            • "code_execution_20250825"

            • "code_execution_20260120"

          • allowed_domains: optional array of string

            List of domains to allow fetching from

          • blocked_domains: optional array of string

            List of domains to block fetching from

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

          • citations: optional BetaCitationsConfigParam

            Citations configuration for fetched documents. Citations are disabled by default.

          • defer_loading: optional 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: optional number

            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: optional number

            Maximum number of times the tool can be used in the API request.

          • strict: optional boolean

            When true, guarantees schema validation on tool names and inputs

          • use_cache: optional 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 object { model, name, type, 6 more }

          • model: Model

            The model that will complete your prompt.

            See models 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: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

            • "direct"

            • "code_execution_20250825"

            • "code_execution_20260120"

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

          • caching: optional BetaCacheControlEphemeral

            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: optional boolean

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

          • max_uses: optional number

            Maximum number of times the tool can be used in the API request.

          • strict: optional boolean

            When true, guarantees schema validation on tool names and inputs

        • BetaToolSearchToolBm25_20251119 object { name, type, allowed_callers, 3 more }

          • 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" or "tool_search_tool_bm25"

            • "tool_search_tool_bm25_20251119"

            • "tool_search_tool_bm25"

          • allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

            • "direct"

            • "code_execution_20250825"

            • "code_execution_20260120"

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

          • defer_loading: optional boolean

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

          • strict: optional boolean

            When true, guarantees schema validation on tool names and inputs

        • BetaToolSearchToolRegex20251119 object { name, type, allowed_callers, 3 more }

          • 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" or "tool_search_tool_regex"

            • "tool_search_tool_regex_20251119"

            • "tool_search_tool_regex"

          • allowed_callers: optional array of "direct" or "code_execution_20250825" or "code_execution_20260120"

            • "direct"

            • "code_execution_20250825"

            • "code_execution_20260120"

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

          • defer_loading: optional boolean

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

          • strict: optional boolean

            When true, guarantees schema validation on tool names and inputs

        • BetaMCPToolset object { mcp_server_name, type, cache_control, 2 more }

          Configuration for a group of tools from an MCP server.

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

          • mcp_server_name: string

            Name of the MCP server to configure tools for

          • type: "mcp_toolset"

            • "mcp_toolset"

          • cache_control: optional BetaCacheControlEphemeral

            Create a cache control breakpoint at this content block.

          • configs: optional map[BetaMCPToolConfig]

            Configuration overrides for specific tools, keyed by tool name

            • defer_loading: optional boolean

            • enabled: optional boolean

          • default_config: optional BetaMCPToolDefaultConfig

            Default configuration applied to all tools from this server

            • defer_loading: optional boolean

            • enabled: optional boolean

      • top_k: optional 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.

        Recommended for advanced use cases only.

      • top_p: optional 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: optional string

        The user profile ID to attribute this request to. Use when acting on behalf of a party other than your organization.

Returns

  • BetaMessageBatch object { id, archived_at, cancel_initiated_at, 7 more }

    • id: string

      Unique object identifier.

      The format and length of IDs may change over time.

    • archived_at: string

      RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable.

    • cancel_initiated_at: string

      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

      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" or "canceling" or "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

      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

curl https://api.anthropic.com/v1/messages/batches \
    -H 'Content-Type: application/json' \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: message-batches-2024-09-24' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY" \
    -d '{
          "requests": [
            {
              "custom_id": "my-custom-id-1",
              "params": {
                "max_tokens": 1024,
                "messages": [
                  {
                    "content": "Hello, world",
                    "role": "user"
                  }
                ],
                "model": "claude-opus-4-6"
              }
            }
          ]
        }'

Response

{
  "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

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

Path Parameters

  • message_batch_id: string

    ID of the Message Batch.

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Returns

  • BetaMessageBatch object { id, archived_at, cancel_initiated_at, 7 more }

    • id: string

      Unique object identifier.

      The format and length of IDs may change over time.

    • archived_at: string

      RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable.

    • cancel_initiated_at: string

      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

      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" or "canceling" or "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

      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

curl https://api.anthropic.com/v1/messages/batches/$MESSAGE_BATCH_ID \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: message-batches-2024-09-24' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

Response

{
  "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

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

Query Parameters

  • after_id: optional string

    ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object.

  • before_id: optional string

    ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object.

  • limit: optional number

    Number of items to return per page.

    Defaults to 20. Ranges from 1 to 1000.

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Returns

  • data: array of BetaMessageBatch

    • id: string

      Unique object identifier.

      The format and length of IDs may change over time.

    • archived_at: string

      RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable.

    • cancel_initiated_at: string

      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

      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" or "canceling" or "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

      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"

  • first_id: string

    First ID in the data list. Can be used as the before_id for the previous page.

  • has_more: boolean

    Indicates if there are more results in the requested page direction.

  • last_id: string

    Last ID in the data list. Can be used as the after_id for the next page.

Example

curl https://api.anthropic.com/v1/messages/batches \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: message-batches-2024-09-24' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

Response

{
  "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

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

Path Parameters

  • message_batch_id: string

    ID of the Message Batch.

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Returns

  • BetaMessageBatch object { id, archived_at, cancel_initiated_at, 7 more }

    • id: string

      Unique object identifier.

      The format and length of IDs may change over time.

    • archived_at: string

      RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable.

    • cancel_initiated_at: string

      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

      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" or "canceling" or "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

      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

curl https://api.anthropic.com/v1/messages/batches/$MESSAGE_BATCH_ID/cancel \
    -X POST \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: message-batches-2024-09-24' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

Response

{
  "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

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

Path Parameters

  • message_batch_id: string

    ID of the Message Batch.

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Returns

  • BetaDeletedMessageBatch object { id, type }

    • 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

curl https://api.anthropic.com/v1/messages/batches/$MESSAGE_BATCH_ID \
    -X DELETE \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: message-batches-2024-09-24' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

Response

{
  "id": "msgbatch_013Zva2CMHLNnXjNJJKqJ2EF",
  "type": "message_batch_deleted"
}

Retrieve Message Batch results

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

Path Parameters

  • message_batch_id: string

    ID of the Message Batch.

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Returns

  • BetaMessageBatchIndividualResponse object { custom_id, result }

    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 object { message, type }

        • message: BetaMessage

          • id: string

            Unique object identifier.

            The format and length of IDs may change over time.

          • 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 of BetaSkill

              Skills loaded in the container

              • skill_id: string

                Skill ID

              • type: "anthropic" or "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 of BetaContentBlock

            Content generated by the model.

            This is an array of content blocks, each of which has a type that determines its shape.

            Example:

            [{"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:

            [
  {"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:

            [{"type": "text", "text": "B)"}]

            • BetaTextBlock object { citations, text, type }

              • citations: array of BetaTextCitation

                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 object { cited_text, document_index, document_title, 4 more }

                  • cited_text: string

                  • document_index: number

                  • document_title: string

                  • end_char_index: number

                  • file_id: string

                  • start_char_index: number

                  • type: "char_location"

                    • "char_location"

                • BetaCitationPageLocation object { cited_text, document_index, document_title, 4 more }

                  • cited_text: string

                  • document_index: number

                  • document_title: string

                  • end_page_number: number

                  • file_id: string

                  • start_page_number: number

                  • type: "page_location"

                    • "page_location"

                • BetaCitationContentBlockLocation object { cited_text, document_index, document_title, 4 more }

                  • 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

                  • 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

                  • 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 object { cited_text, encrypted_index, title, 2 more }

                  • cited_text: string

                  • encrypted_index: string

                  • title: string

                  • type: "web_search_result_location"

                    • "web_search_result_location"

                  • url: string

                • BetaCitationSearchResultLocation object { cited_text, end_block_index, search_result_index, 4 more }

                  • 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

                  • type: "search_result_location"

                    • "search_result_location"

              • text: string

              • type: "text"

                • "text"

            • BetaThinkingBlock object { signature, thinking, type }

              • signature: string

              • thinking: string

              • type: "thinking"

                • "thinking"

            • BetaRedactedThinkingBlock object { data, type }

              • data: string

              • type: "redacted_thinking"

                • "redacted_thinking"

            • BetaToolUseBlock object { id, input, name, 2 more }

              • id: string

              • input: map[unknown]

              • name: string

              • type: "tool_use"

                • "tool_use"

              • caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

                Tool invocation directly from the model.

                • BetaDirectCaller object { type }

                  Tool invocation directly from the model.

                  • type: "direct"

                    • "direct"

                • BetaServerToolCaller object { tool_id, type }

                  Tool invocation generated by a server-side tool.

                  • tool_id: string

                  • type: "code_execution_20250825"

                    • "code_execution_20250825"

                • BetaServerToolCaller20260120 object { tool_id, type }

                  • tool_id: string

                  • type: "code_execution_20260120"

                    • "code_execution_20260120"

            • BetaServerToolUseBlock object { id, input, name, 2 more }

              • id: string

              • input: map[unknown]

              • name: "advisor" or "web_search" or "web_fetch" or 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: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

                Tool invocation directly from the model.

                • BetaDirectCaller object { type }

                  Tool invocation directly from the model.

                • BetaServerToolCaller object { tool_id, type }

                  Tool invocation generated by a server-side tool.

                • BetaServerToolCaller20260120 object { tool_id, type }

            • BetaWebSearchToolResultBlock object { content, tool_use_id, type, caller }

              • content: BetaWebSearchToolResultBlockContent

                • BetaWebSearchToolResultError object { error_code, type }

                  • 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 of BetaWebSearchResultBlock

                  • encrypted_content: string

                  • page_age: string

                  • 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: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

                Tool invocation directly from the model.

                • BetaDirectCaller object { type }

                  Tool invocation directly from the model.

                • BetaServerToolCaller object { tool_id, type }

                  Tool invocation generated by a server-side tool.

                • BetaServerToolCaller20260120 object { tool_id, type }

            • BetaWebFetchToolResultBlock object { content, tool_use_id, type, caller }

              • content: BetaWebFetchToolResultErrorBlock or BetaWebFetchBlock

                • BetaWebFetchToolResultErrorBlock object { error_code, type }

                  • error_code: BetaWebFetchToolResultErrorCode

                    • "invalid_tool_input"

                    • "url_too_long"

                    • "url_not_allowed"

                    • "url_not_accessible"

                    • "unsupported_content_type"

                    • "too_many_requests"

                    • "max_uses_exceeded"

                    • "unavailable"

                  • type: "web_fetch_tool_result_error"

                    • "web_fetch_tool_result_error"

                • BetaWebFetchBlock object { content, retrieved_at, type, url }

                  • content: BetaDocumentBlock

                    • citations: BetaCitationConfig

                      Citation configuration for the document

                      • enabled: boolean

                    • source: BetaBase64PDFSource or BetaPlainTextSource

                      • BetaBase64PDFSource object { data, media_type, type }

                        • data: string

                        • media_type: "application/pdf"

                          • "application/pdf"

                        • type: "base64"

                          • "base64"

                      • BetaPlainTextSource object { data, media_type, type }

                        • data: string

                        • media_type: "text/plain"

                          • "text/plain"

                        • type: "text"

                          • "text"

                    • title: string

                      The title of the document

                    • type: "document"

                      • "document"

                  • retrieved_at: string

                    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: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

                Tool invocation directly from the model.

                • BetaDirectCaller object { type }

                  Tool invocation directly from the model.

                • BetaServerToolCaller object { tool_id, type }

                  Tool invocation generated by a server-side tool.

                • BetaServerToolCaller20260120 object { tool_id, type }

            • BetaAdvisorToolResultBlock object { content, tool_use_id, type }

              • content: BetaAdvisorToolResultError or BetaAdvisorResultBlock or BetaAdvisorRedactedResultBlock

                • BetaAdvisorToolResultError object { error_code, type }

                  • error_code: "max_uses_exceeded" or "prompt_too_long" or "too_many_requests" or 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 object { text, type }

                  • text: string

                  • type: "advisor_result"

                    • "advisor_result"

                • BetaAdvisorRedactedResultBlock object { encrypted_content, type }

                  • encrypted_content: string

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

                  • type: "advisor_redacted_result"

                    • "advisor_redacted_result"

              • tool_use_id: string

              • type: "advisor_tool_result"

                • "advisor_tool_result"

            • BetaCodeExecutionToolResultBlock object { content, tool_use_id, type }

              • content: BetaCodeExecutionToolResultBlockContent

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

                • BetaCodeExecutionToolResultError object { error_code, type }

                  • 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 object { content, return_code, stderr, 2 more }

                  • content: array of BetaCodeExecutionOutputBlock

                    • 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 object { content, encrypted_stdout, return_code, 2 more }

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

                  • content: array of BetaCodeExecutionOutputBlock

                    • 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 object { content, tool_use_id, type }

              • content: BetaBashCodeExecutionToolResultError or BetaBashCodeExecutionResultBlock

                • BetaBashCodeExecutionToolResultError object { error_code, type }

                  • error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 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 object { content, return_code, stderr, 2 more }

                  • content: array of BetaBashCodeExecutionOutputBlock

                    • 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 object { content, tool_use_id, type }

              • content: BetaTextEditorCodeExecutionToolResultError or BetaTextEditorCodeExecutionViewResultBlock or BetaTextEditorCodeExecutionCreateResultBlock or BetaTextEditorCodeExecutionStrReplaceResultBlock

                • BetaTextEditorCodeExecutionToolResultError object { error_code, error_message, type }

                  • error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more

                    • "invalid_tool_input"

                    • "unavailable"

                    • "too_many_requests"

                    • "execution_time_exceeded"

                    • "file_not_found"

                  • error_message: string

                  • type: "text_editor_code_execution_tool_result_error"

                    • "text_editor_code_execution_tool_result_error"

                • BetaTextEditorCodeExecutionViewResultBlock object { content, file_type, num_lines, 3 more }

                  • content: string

                  • file_type: "text" or "image" or "pdf"

                    • "text"

                    • "image"

                    • "pdf"

                  • num_lines: number

                  • start_line: number

                  • total_lines: number

                  • type: "text_editor_code_execution_view_result"

                    • "text_editor_code_execution_view_result"

                • BetaTextEditorCodeExecutionCreateResultBlock object { is_file_update, type }

                  • is_file_update: boolean

                  • type: "text_editor_code_execution_create_result"

                    • "text_editor_code_execution_create_result"

                • BetaTextEditorCodeExecutionStrReplaceResultBlock object { lines, new_lines, new_start, 3 more }

                  • lines: array of string

                  • new_lines: number

                  • new_start: number

                  • old_lines: number

                  • old_start: number

                  • 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 object { content, tool_use_id, type }

              • content: BetaToolSearchToolResultError or BetaToolSearchToolSearchResultBlock

                • BetaToolSearchToolResultError object { error_code, error_message, type }

                  • error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"

                    • "invalid_tool_input"

                    • "unavailable"

                    • "too_many_requests"

                    • "execution_time_exceeded"

                  • error_message: string

                  • type: "tool_search_tool_result_error"

                    • "tool_search_tool_result_error"

                • BetaToolSearchToolSearchResultBlock object { tool_references, type }

                  • tool_references: array of BetaToolReferenceBlock

                    • 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 object { id, input, name, 2 more }

              • id: string

              • input: map[unknown]

              • 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 object { content, is_error, tool_use_id, type }

              • content: string or array of BetaTextBlock

                • string

                • BetaMCPToolResultBlockContent = array of BetaTextBlock

                  • citations: array of BetaTextCitation

                    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 object { file_id, type }

              Response model for a file uploaded to the container.

              • file_id: string

              • type: "container_upload"

                • "container_upload"

            • BetaCompactionBlock object { content, encrypted_content, type }

              A compaction block returned when autocompact is triggered.

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

              • content: string

                Summary of compacted content, or null if compaction failed

              • encrypted_content: string

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

              • type: "compaction"

                • "compaction"

          • context_management: BetaContextManagementResponse

            Context management response.

            Information about context management strategies applied during the request.

            • applied_edits: array of BetaClearToolUses20250919EditResponse or BetaClearThinking20251015EditResponse

              List of context management edits that were applied.

              • BetaClearToolUses20250919EditResponse object { cleared_input_tokens, cleared_tool_uses, type }

                • cleared_input_tokens: number

                  Number of input tokens cleared by this edit.

                • cleared_tool_uses: number

                  Number of tool uses that were cleared.

                • type: "clear_tool_uses_20250919"

                  The type of context management edit applied.

                  • "clear_tool_uses_20250919"

              • BetaClearThinking20251015EditResponse object { cleared_input_tokens, cleared_thinking_turns, type }

                • cleared_input_tokens: number

                  Number of input tokens cleared by this edit.

                • cleared_thinking_turns: number

                  Number of thinking turns that were cleared.

                • type: "clear_thinking_20251015"

                  The type of context management edit applied.

                  • "clear_thinking_20251015"

          • diagnostics: BetaDiagnostics

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

            • cache_miss_reason: BetaCacheMissModelChanged or BetaCacheMissSystemChanged or BetaCacheMissToolsChanged or 3 more

              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 object { cache_missed_input_tokens, type }

                • 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 object { cache_missed_input_tokens, type }

                • 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 object { cache_missed_input_tokens, type }

                • 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 object { cache_missed_input_tokens, type }

                • 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 object { type }

                • type: "previous_message_not_found"

                  • "previous_message_not_found"

              • BetaCacheMissUnavailable object { type }

                • type: "unavailable"

                  • "unavailable"

          • model: Model

            The model that will complete your prompt.

            See models for additional details and options.

            • "claude-opus-4-7" or "claude-mythos-preview" or "claude-opus-4-6" or 14 more

              The model that will complete your prompt.

              See models for additional details and options.

              • "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

            Structured information about a refusal.

            • category: "cyber" or "bio"

              The policy category that triggered the refusal.

              null when the refusal doesn't map to a named category.

              • "cyber"

              • "bio"

            • explanation: string

              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

            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

            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

              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.

            • inference_geo: string

              The geographic region where inference was performed for this request.

            • input_tokens: number

              The number of input tokens which were used.

            • iterations: BetaIterationsUsage

              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 object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }

                Token usage for a sampling iteration.

                • cache_creation: BetaCacheCreation

                  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 object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }

                Token usage for a compaction iteration.

                • cache_creation: BetaCacheCreation

                  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 object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 4 more }

                Token usage for an advisor sub-inference iteration.

                • cache_creation: BetaCacheCreation

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

            • server_tool_use: BetaServerToolUsage

              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" or "priority" or "batch"

              If the request used the priority, standard, or batch tier.

              • "standard"

              • "priority"

              • "batch"

            • speed: "standard" or "fast"

              The inference speed mode used for this request.

              • "standard"

              • "fast"

        • type: "succeeded"

          • "succeeded"

      • BetaMessageBatchErroredResult object { error, type }

        • error: BetaErrorResponse

          • error: BetaError

            • BetaInvalidRequestError object { message, type }

              • message: string

              • type: "invalid_request_error"

                • "invalid_request_error"

            • BetaAuthenticationError object { message, type }

              • message: string

              • type: "authentication_error"

                • "authentication_error"

            • BetaBillingError object { message, type }

              • message: string

              • type: "billing_error"

                • "billing_error"

            • BetaPermissionError object { message, type }

              • message: string

              • type: "permission_error"

                • "permission_error"

            • BetaNotFoundError object { message, type }

              • message: string

              • type: "not_found_error"

                • "not_found_error"

            • BetaRateLimitError object { message, type }

              • message: string

              • type: "rate_limit_error"

                • "rate_limit_error"

            • BetaGatewayTimeoutError object { message, type }

              • message: string

              • type: "timeout_error"

                • "timeout_error"

            • BetaAPIError object { message, type }

              • message: string

              • type: "api_error"

                • "api_error"

            • BetaOverloadedError object { message, type }

              • message: string

              • type: "overloaded_error"

                • "overloaded_error"

          • request_id: string

          • type: "error"

            • "error"

        • type: "errored"

          • "errored"

      • BetaMessageBatchCanceledResult object { type }

        • type: "canceled"

          • "canceled"

      • BetaMessageBatchExpiredResult object { type }

        • type: "expired"

          • "expired"

Example

curl https://api.anthropic.com/v1/messages/batches/$MESSAGE_BATCH_ID/results \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: message-batches-2024-09-24' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

Domain Types

Beta Deleted Message Batch

  • BetaDeletedMessageBatch object { id, type }

    • 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 object { id, archived_at, cancel_initiated_at, 7 more }

    • id: string

      Unique object identifier.

      The format and length of IDs may change over time.

    • archived_at: string

      RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable.

    • cancel_initiated_at: string

      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

      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" or "canceling" or "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

      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 object { type }

    • type: "canceled"

      • "canceled"

Beta Message Batch Errored Result

  • BetaMessageBatchErroredResult object { error, type }

    • error: BetaErrorResponse

      • error: BetaError

        • BetaInvalidRequestError object { message, type }

          • message: string

          • type: "invalid_request_error"

            • "invalid_request_error"

        • BetaAuthenticationError object { message, type }

          • message: string

          • type: "authentication_error"

            • "authentication_error"

        • BetaBillingError object { message, type }

          • message: string

          • type: "billing_error"

            • "billing_error"

        • BetaPermissionError object { message, type }

          • message: string

          • type: "permission_error"

            • "permission_error"

        • BetaNotFoundError object { message, type }

          • message: string

          • type: "not_found_error"

            • "not_found_error"

        • BetaRateLimitError object { message, type }

          • message: string

          • type: "rate_limit_error"

            • "rate_limit_error"

        • BetaGatewayTimeoutError object { message, type }

          • message: string

          • type: "timeout_error"

            • "timeout_error"

        • BetaAPIError object { message, type }

          • message: string

          • type: "api_error"

            • "api_error"

        • BetaOverloadedError object { message, type }

          • message: string

          • type: "overloaded_error"

            • "overloaded_error"

      • request_id: string

      • type: "error"

        • "error"

    • type: "errored"

      • "errored"

Beta Message Batch Expired Result

  • BetaMessageBatchExpiredResult object { type }

    • type: "expired"

      • "expired"

Beta Message Batch Individual Response

  • BetaMessageBatchIndividualResponse object { custom_id, result }

    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 object { message, type }

        • message: BetaMessage

          • id: string

            Unique object identifier.

            The format and length of IDs may change over time.

          • 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 of BetaSkill

              Skills loaded in the container

              • skill_id: string

                Skill ID

              • type: "anthropic" or "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 of BetaContentBlock

            Content generated by the model.

            This is an array of content blocks, each of which has a type that determines its shape.

            Example:

            [{"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:

            [
  {"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:

            [{"type": "text", "text": "B)"}]

            • BetaTextBlock object { citations, text, type }

              • citations: array of BetaTextCitation

                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 object { cited_text, document_index, document_title, 4 more }

                  • cited_text: string

                  • document_index: number

                  • document_title: string

                  • end_char_index: number

                  • file_id: string

                  • start_char_index: number

                  • type: "char_location"

                    • "char_location"

                • BetaCitationPageLocation object { cited_text, document_index, document_title, 4 more }

                  • cited_text: string

                  • document_index: number

                  • document_title: string

                  • end_page_number: number

                  • file_id: string

                  • start_page_number: number

                  • type: "page_location"

                    • "page_location"

                • BetaCitationContentBlockLocation object { cited_text, document_index, document_title, 4 more }

                  • 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

                  • 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

                  • 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 object { cited_text, encrypted_index, title, 2 more }

                  • cited_text: string

                  • encrypted_index: string

                  • title: string

                  • type: "web_search_result_location"

                    • "web_search_result_location"

                  • url: string

                • BetaCitationSearchResultLocation object { cited_text, end_block_index, search_result_index, 4 more }

                  • 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

                  • type: "search_result_location"

                    • "search_result_location"

              • text: string

              • type: "text"

                • "text"

            • BetaThinkingBlock object { signature, thinking, type }

              • signature: string

              • thinking: string

              • type: "thinking"

                • "thinking"

            • BetaRedactedThinkingBlock object { data, type }

              • data: string

              • type: "redacted_thinking"

                • "redacted_thinking"

            • BetaToolUseBlock object { id, input, name, 2 more }

              • id: string

              • input: map[unknown]

              • name: string

              • type: "tool_use"

                • "tool_use"

              • caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

                Tool invocation directly from the model.

                • BetaDirectCaller object { type }

                  Tool invocation directly from the model.

                  • type: "direct"

                    • "direct"

                • BetaServerToolCaller object { tool_id, type }

                  Tool invocation generated by a server-side tool.

                  • tool_id: string

                  • type: "code_execution_20250825"

                    • "code_execution_20250825"

                • BetaServerToolCaller20260120 object { tool_id, type }

                  • tool_id: string

                  • type: "code_execution_20260120"

                    • "code_execution_20260120"

            • BetaServerToolUseBlock object { id, input, name, 2 more }

              • id: string

              • input: map[unknown]

              • name: "advisor" or "web_search" or "web_fetch" or 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: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

                Tool invocation directly from the model.

                • BetaDirectCaller object { type }

                  Tool invocation directly from the model.

                • BetaServerToolCaller object { tool_id, type }

                  Tool invocation generated by a server-side tool.

                • BetaServerToolCaller20260120 object { tool_id, type }

            • BetaWebSearchToolResultBlock object { content, tool_use_id, type, caller }

              • content: BetaWebSearchToolResultBlockContent

                • BetaWebSearchToolResultError object { error_code, type }

                  • 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 of BetaWebSearchResultBlock

                  • encrypted_content: string

                  • page_age: string

                  • 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: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

                Tool invocation directly from the model.

                • BetaDirectCaller object { type }

                  Tool invocation directly from the model.

                • BetaServerToolCaller object { tool_id, type }

                  Tool invocation generated by a server-side tool.

                • BetaServerToolCaller20260120 object { tool_id, type }

            • BetaWebFetchToolResultBlock object { content, tool_use_id, type, caller }

              • content: BetaWebFetchToolResultErrorBlock or BetaWebFetchBlock

                • BetaWebFetchToolResultErrorBlock object { error_code, type }

                  • error_code: BetaWebFetchToolResultErrorCode

                    • "invalid_tool_input"

                    • "url_too_long"

                    • "url_not_allowed"

                    • "url_not_accessible"

                    • "unsupported_content_type"

                    • "too_many_requests"

                    • "max_uses_exceeded"

                    • "unavailable"

                  • type: "web_fetch_tool_result_error"

                    • "web_fetch_tool_result_error"

                • BetaWebFetchBlock object { content, retrieved_at, type, url }

                  • content: BetaDocumentBlock

                    • citations: BetaCitationConfig

                      Citation configuration for the document

                      • enabled: boolean

                    • source: BetaBase64PDFSource or BetaPlainTextSource

                      • BetaBase64PDFSource object { data, media_type, type }

                        • data: string

                        • media_type: "application/pdf"

                          • "application/pdf"

                        • type: "base64"

                          • "base64"

                      • BetaPlainTextSource object { data, media_type, type }

                        • data: string

                        • media_type: "text/plain"

                          • "text/plain"

                        • type: "text"

                          • "text"

                    • title: string

                      The title of the document

                    • type: "document"

                      • "document"

                  • retrieved_at: string

                    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: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

                Tool invocation directly from the model.

                • BetaDirectCaller object { type }

                  Tool invocation directly from the model.

                • BetaServerToolCaller object { tool_id, type }

                  Tool invocation generated by a server-side tool.

                • BetaServerToolCaller20260120 object { tool_id, type }

            • BetaAdvisorToolResultBlock object { content, tool_use_id, type }

              • content: BetaAdvisorToolResultError or BetaAdvisorResultBlock or BetaAdvisorRedactedResultBlock

                • BetaAdvisorToolResultError object { error_code, type }

                  • error_code: "max_uses_exceeded" or "prompt_too_long" or "too_many_requests" or 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 object { text, type }

                  • text: string

                  • type: "advisor_result"

                    • "advisor_result"

                • BetaAdvisorRedactedResultBlock object { encrypted_content, type }

                  • encrypted_content: string

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

                  • type: "advisor_redacted_result"

                    • "advisor_redacted_result"

              • tool_use_id: string

              • type: "advisor_tool_result"

                • "advisor_tool_result"

            • BetaCodeExecutionToolResultBlock object { content, tool_use_id, type }

              • content: BetaCodeExecutionToolResultBlockContent

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

                • BetaCodeExecutionToolResultError object { error_code, type }

                  • 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 object { content, return_code, stderr, 2 more }

                  • content: array of BetaCodeExecutionOutputBlock

                    • 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 object { content, encrypted_stdout, return_code, 2 more }

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

                  • content: array of BetaCodeExecutionOutputBlock

                    • 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 object { content, tool_use_id, type }

              • content: BetaBashCodeExecutionToolResultError or BetaBashCodeExecutionResultBlock

                • BetaBashCodeExecutionToolResultError object { error_code, type }

                  • error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 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 object { content, return_code, stderr, 2 more }

                  • content: array of BetaBashCodeExecutionOutputBlock

                    • 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 object { content, tool_use_id, type }

              • content: BetaTextEditorCodeExecutionToolResultError or BetaTextEditorCodeExecutionViewResultBlock or BetaTextEditorCodeExecutionCreateResultBlock or BetaTextEditorCodeExecutionStrReplaceResultBlock

                • BetaTextEditorCodeExecutionToolResultError object { error_code, error_message, type }

                  • error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more

                    • "invalid_tool_input"

                    • "unavailable"

                    • "too_many_requests"

                    • "execution_time_exceeded"

                    • "file_not_found"

                  • error_message: string

                  • type: "text_editor_code_execution_tool_result_error"

                    • "text_editor_code_execution_tool_result_error"

                • BetaTextEditorCodeExecutionViewResultBlock object { content, file_type, num_lines, 3 more }

                  • content: string

                  • file_type: "text" or "image" or "pdf"

                    • "text"

                    • "image"

                    • "pdf"

                  • num_lines: number

                  • start_line: number

                  • total_lines: number

                  • type: "text_editor_code_execution_view_result"

                    • "text_editor_code_execution_view_result"

                • BetaTextEditorCodeExecutionCreateResultBlock object { is_file_update, type }

                  • is_file_update: boolean

                  • type: "text_editor_code_execution_create_result"

                    • "text_editor_code_execution_create_result"

                • BetaTextEditorCodeExecutionStrReplaceResultBlock object { lines, new_lines, new_start, 3 more }

                  • lines: array of string

                  • new_lines: number

                  • new_start: number

                  • old_lines: number

                  • old_start: number

                  • 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 object { content, tool_use_id, type }

              • content: BetaToolSearchToolResultError or BetaToolSearchToolSearchResultBlock

                • BetaToolSearchToolResultError object { error_code, error_message, type }

                  • error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"

                    • "invalid_tool_input"

                    • "unavailable"

                    • "too_many_requests"

                    • "execution_time_exceeded"

                  • error_message: string

                  • type: "tool_search_tool_result_error"

                    • "tool_search_tool_result_error"

                • BetaToolSearchToolSearchResultBlock object { tool_references, type }

                  • tool_references: array of BetaToolReferenceBlock

                    • 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 object { id, input, name, 2 more }

              • id: string

              • input: map[unknown]

              • 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 object { content, is_error, tool_use_id, type }

              • content: string or array of BetaTextBlock

                • string

                • BetaMCPToolResultBlockContent = array of BetaTextBlock

                  • citations: array of BetaTextCitation

                    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 object { file_id, type }

              Response model for a file uploaded to the container.

              • file_id: string

              • type: "container_upload"

                • "container_upload"

            • BetaCompactionBlock object { content, encrypted_content, type }

              A compaction block returned when autocompact is triggered.

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

              • content: string

                Summary of compacted content, or null if compaction failed

              • encrypted_content: string

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

              • type: "compaction"

                • "compaction"

          • context_management: BetaContextManagementResponse

            Context management response.

            Information about context management strategies applied during the request.

            • applied_edits: array of BetaClearToolUses20250919EditResponse or BetaClearThinking20251015EditResponse

              List of context management edits that were applied.

              • BetaClearToolUses20250919EditResponse object { cleared_input_tokens, cleared_tool_uses, type }

                • cleared_input_tokens: number

                  Number of input tokens cleared by this edit.

                • cleared_tool_uses: number

                  Number of tool uses that were cleared.

                • type: "clear_tool_uses_20250919"

                  The type of context management edit applied.

                  • "clear_tool_uses_20250919"

              • BetaClearThinking20251015EditResponse object { cleared_input_tokens, cleared_thinking_turns, type }

                • cleared_input_tokens: number

                  Number of input tokens cleared by this edit.

                • cleared_thinking_turns: number

                  Number of thinking turns that were cleared.

                • type: "clear_thinking_20251015"

                  The type of context management edit applied.

                  • "clear_thinking_20251015"

          • diagnostics: BetaDiagnostics

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

            • cache_miss_reason: BetaCacheMissModelChanged or BetaCacheMissSystemChanged or BetaCacheMissToolsChanged or 3 more

              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 object { cache_missed_input_tokens, type }

                • 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 object { cache_missed_input_tokens, type }

                • 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 object { cache_missed_input_tokens, type }

                • 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 object { cache_missed_input_tokens, type }

                • 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 object { type }

                • type: "previous_message_not_found"

                  • "previous_message_not_found"

              • BetaCacheMissUnavailable object { type }

                • type: "unavailable"

                  • "unavailable"

          • model: Model

            The model that will complete your prompt.

            See models for additional details and options.

            • "claude-opus-4-7" or "claude-mythos-preview" or "claude-opus-4-6" or 14 more

              The model that will complete your prompt.

              See models for additional details and options.

              • "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

            Structured information about a refusal.

            • category: "cyber" or "bio"

              The policy category that triggered the refusal.

              null when the refusal doesn't map to a named category.

              • "cyber"

              • "bio"

            • explanation: string

              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

            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

            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

              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.

            • inference_geo: string

              The geographic region where inference was performed for this request.

            • input_tokens: number

              The number of input tokens which were used.

            • iterations: BetaIterationsUsage

              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 object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }

                Token usage for a sampling iteration.

                • cache_creation: BetaCacheCreation

                  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 object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }

                Token usage for a compaction iteration.

                • cache_creation: BetaCacheCreation

                  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 object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 4 more }

                Token usage for an advisor sub-inference iteration.

                • cache_creation: BetaCacheCreation

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

            • server_tool_use: BetaServerToolUsage

              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" or "priority" or "batch"

              If the request used the priority, standard, or batch tier.

              • "standard"

              • "priority"

              • "batch"

            • speed: "standard" or "fast"

              The inference speed mode used for this request.

              • "standard"

              • "fast"

        • type: "succeeded"

          • "succeeded"

      • BetaMessageBatchErroredResult object { error, type }

        • error: BetaErrorResponse

          • error: BetaError

            • BetaInvalidRequestError object { message, type }

              • message: string

              • type: "invalid_request_error"

                • "invalid_request_error"

            • BetaAuthenticationError object { message, type }

              • message: string

              • type: "authentication_error"

                • "authentication_error"

            • BetaBillingError object { message, type }

              • message: string

              • type: "billing_error"

                • "billing_error"

            • BetaPermissionError object { message, type }

              • message: string

              • type: "permission_error"

                • "permission_error"

            • BetaNotFoundError object { message, type }

              • message: string

              • type: "not_found_error"

                • "not_found_error"

            • BetaRateLimitError object { message, type }

              • message: string

              • type: "rate_limit_error"

                • "rate_limit_error"

            • BetaGatewayTimeoutError object { message, type }

              • message: string

              • type: "timeout_error"

                • "timeout_error"

            • BetaAPIError object { message, type }

              • message: string

              • type: "api_error"

                • "api_error"

            • BetaOverloadedError object { message, type }

              • message: string

              • type: "overloaded_error"

                • "overloaded_error"

          • request_id: string

          • type: "error"

            • "error"

        • type: "errored"

          • "errored"

      • BetaMessageBatchCanceledResult object { type }

        • type: "canceled"

          • "canceled"

      • BetaMessageBatchExpiredResult object { type }

        • type: "expired"

          • "expired"

Beta Message Batch Request Counts

  • BetaMessageBatchRequestCounts object { canceled, errored, expired, 2 more }

    • 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 or BetaMessageBatchErroredResult or BetaMessageBatchCanceledResult or 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 object { message, type }

      • message: BetaMessage

        • id: string

          Unique object identifier.

          The format and length of IDs may change over time.

        • 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 of BetaSkill

            Skills loaded in the container

            • skill_id: string

              Skill ID

            • type: "anthropic" or "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 of BetaContentBlock

          Content generated by the model.

          This is an array of content blocks, each of which has a type that determines its shape.

          Example:

          [{"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:

          [
  {"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:

          [{"type": "text", "text": "B)"}]

          • BetaTextBlock object { citations, text, type }

            • citations: array of BetaTextCitation

              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 object { cited_text, document_index, document_title, 4 more }

                • cited_text: string

                • document_index: number

                • document_title: string

                • end_char_index: number

                • file_id: string

                • start_char_index: number

                • type: "char_location"

                  • "char_location"

              • BetaCitationPageLocation object { cited_text, document_index, document_title, 4 more }

                • cited_text: string

                • document_index: number

                • document_title: string

                • end_page_number: number

                • file_id: string

                • start_page_number: number

                • type: "page_location"

                  • "page_location"

              • BetaCitationContentBlockLocation object { cited_text, document_index, document_title, 4 more }

                • 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

                • 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

                • 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 object { cited_text, encrypted_index, title, 2 more }

                • cited_text: string

                • encrypted_index: string

                • title: string

                • type: "web_search_result_location"

                  • "web_search_result_location"

                • url: string

              • BetaCitationSearchResultLocation object { cited_text, end_block_index, search_result_index, 4 more }

                • 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

                • type: "search_result_location"

                  • "search_result_location"

            • text: string

            • type: "text"

              • "text"

          • BetaThinkingBlock object { signature, thinking, type }

            • signature: string

            • thinking: string

            • type: "thinking"

              • "thinking"

          • BetaRedactedThinkingBlock object { data, type }

            • data: string

            • type: "redacted_thinking"

              • "redacted_thinking"

          • BetaToolUseBlock object { id, input, name, 2 more }

            • id: string

            • input: map[unknown]

            • name: string

            • type: "tool_use"

              • "tool_use"

            • caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

              Tool invocation directly from the model.

              • BetaDirectCaller object { type }

                Tool invocation directly from the model.

                • type: "direct"

                  • "direct"

              • BetaServerToolCaller object { tool_id, type }

                Tool invocation generated by a server-side tool.

                • tool_id: string

                • type: "code_execution_20250825"

                  • "code_execution_20250825"

              • BetaServerToolCaller20260120 object { tool_id, type }

                • tool_id: string

                • type: "code_execution_20260120"

                  • "code_execution_20260120"

          • BetaServerToolUseBlock object { id, input, name, 2 more }

            • id: string

            • input: map[unknown]

            • name: "advisor" or "web_search" or "web_fetch" or 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: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

              Tool invocation directly from the model.

              • BetaDirectCaller object { type }

                Tool invocation directly from the model.

              • BetaServerToolCaller object { tool_id, type }

                Tool invocation generated by a server-side tool.

              • BetaServerToolCaller20260120 object { tool_id, type }

          • BetaWebSearchToolResultBlock object { content, tool_use_id, type, caller }

            • content: BetaWebSearchToolResultBlockContent

              • BetaWebSearchToolResultError object { error_code, type }

                • 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 of BetaWebSearchResultBlock

                • encrypted_content: string

                • page_age: string

                • 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: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

              Tool invocation directly from the model.

              • BetaDirectCaller object { type }

                Tool invocation directly from the model.

              • BetaServerToolCaller object { tool_id, type }

                Tool invocation generated by a server-side tool.

              • BetaServerToolCaller20260120 object { tool_id, type }

          • BetaWebFetchToolResultBlock object { content, tool_use_id, type, caller }

            • content: BetaWebFetchToolResultErrorBlock or BetaWebFetchBlock

              • BetaWebFetchToolResultErrorBlock object { error_code, type }

                • error_code: BetaWebFetchToolResultErrorCode

                  • "invalid_tool_input"

                  • "url_too_long"

                  • "url_not_allowed"

                  • "url_not_accessible"

                  • "unsupported_content_type"

                  • "too_many_requests"

                  • "max_uses_exceeded"

                  • "unavailable"

                • type: "web_fetch_tool_result_error"

                  • "web_fetch_tool_result_error"

              • BetaWebFetchBlock object { content, retrieved_at, type, url }

                • content: BetaDocumentBlock

                  • citations: BetaCitationConfig

                    Citation configuration for the document

                    • enabled: boolean

                  • source: BetaBase64PDFSource or BetaPlainTextSource

                    • BetaBase64PDFSource object { data, media_type, type }

                      • data: string

                      • media_type: "application/pdf"

                        • "application/pdf"

                      • type: "base64"

                        • "base64"

                    • BetaPlainTextSource object { data, media_type, type }

                      • data: string

                      • media_type: "text/plain"

                        • "text/plain"

                      • type: "text"

                        • "text"

                  • title: string

                    The title of the document

                  • type: "document"

                    • "document"

                • retrieved_at: string

                  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: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

              Tool invocation directly from the model.

              • BetaDirectCaller object { type }

                Tool invocation directly from the model.

              • BetaServerToolCaller object { tool_id, type }

                Tool invocation generated by a server-side tool.

              • BetaServerToolCaller20260120 object { tool_id, type }

          • BetaAdvisorToolResultBlock object { content, tool_use_id, type }

            • content: BetaAdvisorToolResultError or BetaAdvisorResultBlock or BetaAdvisorRedactedResultBlock

              • BetaAdvisorToolResultError object { error_code, type }

                • error_code: "max_uses_exceeded" or "prompt_too_long" or "too_many_requests" or 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 object { text, type }

                • text: string

                • type: "advisor_result"

                  • "advisor_result"

              • BetaAdvisorRedactedResultBlock object { encrypted_content, type }

                • encrypted_content: string

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

                • type: "advisor_redacted_result"

                  • "advisor_redacted_result"

            • tool_use_id: string

            • type: "advisor_tool_result"

              • "advisor_tool_result"

          • BetaCodeExecutionToolResultBlock object { content, tool_use_id, type }

            • content: BetaCodeExecutionToolResultBlockContent

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

              • BetaCodeExecutionToolResultError object { error_code, type }

                • 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 object { content, return_code, stderr, 2 more }

                • content: array of BetaCodeExecutionOutputBlock

                  • 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 object { content, encrypted_stdout, return_code, 2 more }

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

                • content: array of BetaCodeExecutionOutputBlock

                  • 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 object { content, tool_use_id, type }

            • content: BetaBashCodeExecutionToolResultError or BetaBashCodeExecutionResultBlock

              • BetaBashCodeExecutionToolResultError object { error_code, type }

                • error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 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 object { content, return_code, stderr, 2 more }

                • content: array of BetaBashCodeExecutionOutputBlock

                  • 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 object { content, tool_use_id, type }

            • content: BetaTextEditorCodeExecutionToolResultError or BetaTextEditorCodeExecutionViewResultBlock or BetaTextEditorCodeExecutionCreateResultBlock or BetaTextEditorCodeExecutionStrReplaceResultBlock

              • BetaTextEditorCodeExecutionToolResultError object { error_code, error_message, type }

                • error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more

                  • "invalid_tool_input"

                  • "unavailable"

                  • "too_many_requests"

                  • "execution_time_exceeded"

                  • "file_not_found"

                • error_message: string

                • type: "text_editor_code_execution_tool_result_error"

                  • "text_editor_code_execution_tool_result_error"

              • BetaTextEditorCodeExecutionViewResultBlock object { content, file_type, num_lines, 3 more }

                • content: string

                • file_type: "text" or "image" or "pdf"

                  • "text"

                  • "image"

                  • "pdf"

                • num_lines: number

                • start_line: number

                • total_lines: number

                • type: "text_editor_code_execution_view_result"

                  • "text_editor_code_execution_view_result"

              • BetaTextEditorCodeExecutionCreateResultBlock object { is_file_update, type }

                • is_file_update: boolean

                • type: "text_editor_code_execution_create_result"

                  • "text_editor_code_execution_create_result"

              • BetaTextEditorCodeExecutionStrReplaceResultBlock object { lines, new_lines, new_start, 3 more }

                • lines: array of string

                • new_lines: number

                • new_start: number

                • old_lines: number

                • old_start: number

                • 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 object { content, tool_use_id, type }

            • content: BetaToolSearchToolResultError or BetaToolSearchToolSearchResultBlock

              • BetaToolSearchToolResultError object { error_code, error_message, type }

                • error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"

                  • "invalid_tool_input"

                  • "unavailable"

                  • "too_many_requests"

                  • "execution_time_exceeded"

                • error_message: string

                • type: "tool_search_tool_result_error"

                  • "tool_search_tool_result_error"

              • BetaToolSearchToolSearchResultBlock object { tool_references, type }

                • tool_references: array of BetaToolReferenceBlock

                  • 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 object { id, input, name, 2 more }

            • id: string

            • input: map[unknown]

            • 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 object { content, is_error, tool_use_id, type }

            • content: string or array of BetaTextBlock

              • string

              • BetaMCPToolResultBlockContent = array of BetaTextBlock

                • citations: array of BetaTextCitation

                  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 object { file_id, type }

            Response model for a file uploaded to the container.

            • file_id: string

            • type: "container_upload"

              • "container_upload"

          • BetaCompactionBlock object { content, encrypted_content, type }

            A compaction block returned when autocompact is triggered.

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

            • content: string

              Summary of compacted content, or null if compaction failed

            • encrypted_content: string

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

            • type: "compaction"

              • "compaction"

        • context_management: BetaContextManagementResponse

          Context management response.

          Information about context management strategies applied during the request.

          • applied_edits: array of BetaClearToolUses20250919EditResponse or BetaClearThinking20251015EditResponse

            List of context management edits that were applied.

            • BetaClearToolUses20250919EditResponse object { cleared_input_tokens, cleared_tool_uses, type }

              • cleared_input_tokens: number

                Number of input tokens cleared by this edit.

              • cleared_tool_uses: number

                Number of tool uses that were cleared.

              • type: "clear_tool_uses_20250919"

                The type of context management edit applied.

                • "clear_tool_uses_20250919"

            • BetaClearThinking20251015EditResponse object { cleared_input_tokens, cleared_thinking_turns, type }

              • cleared_input_tokens: number

                Number of input tokens cleared by this edit.

              • cleared_thinking_turns: number

                Number of thinking turns that were cleared.

              • type: "clear_thinking_20251015"

                The type of context management edit applied.

                • "clear_thinking_20251015"

        • diagnostics: BetaDiagnostics

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

          • cache_miss_reason: BetaCacheMissModelChanged or BetaCacheMissSystemChanged or BetaCacheMissToolsChanged or 3 more

            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 object { cache_missed_input_tokens, type }

              • 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 object { cache_missed_input_tokens, type }

              • 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 object { cache_missed_input_tokens, type }

              • 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 object { cache_missed_input_tokens, type }

              • 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 object { type }

              • type: "previous_message_not_found"

                • "previous_message_not_found"

            • BetaCacheMissUnavailable object { type }

              • type: "unavailable"

                • "unavailable"

        • model: Model

          The model that will complete your prompt.

          See models for additional details and options.

          • "claude-opus-4-7" or "claude-mythos-preview" or "claude-opus-4-6" or 14 more

            The model that will complete your prompt.

            See models for additional details and options.

            • "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

          Structured information about a refusal.

          • category: "cyber" or "bio"

            The policy category that triggered the refusal.

            null when the refusal doesn't map to a named category.

            • "cyber"

            • "bio"

          • explanation: string

            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

          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

          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

            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.

          • inference_geo: string

            The geographic region where inference was performed for this request.

          • input_tokens: number

            The number of input tokens which were used.

          • iterations: BetaIterationsUsage

            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 object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }

              Token usage for a sampling iteration.

              • cache_creation: BetaCacheCreation

                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 object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }

              Token usage for a compaction iteration.

              • cache_creation: BetaCacheCreation

                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 object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 4 more }

              Token usage for an advisor sub-inference iteration.

              • cache_creation: BetaCacheCreation

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

          • server_tool_use: BetaServerToolUsage

            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" or "priority" or "batch"

            If the request used the priority, standard, or batch tier.

            • "standard"

            • "priority"

            • "batch"

          • speed: "standard" or "fast"

            The inference speed mode used for this request.

            • "standard"

            • "fast"

      • type: "succeeded"

        • "succeeded"

    • BetaMessageBatchErroredResult object { error, type }

      • error: BetaErrorResponse

        • error: BetaError

          • BetaInvalidRequestError object { message, type }

            • message: string

            • type: "invalid_request_error"

              • "invalid_request_error"

          • BetaAuthenticationError object { message, type }

            • message: string

            • type: "authentication_error"

              • "authentication_error"

          • BetaBillingError object { message, type }

            • message: string

            • type: "billing_error"

              • "billing_error"

          • BetaPermissionError object { message, type }

            • message: string

            • type: "permission_error"

              • "permission_error"

          • BetaNotFoundError object { message, type }

            • message: string

            • type: "not_found_error"

              • "not_found_error"

          • BetaRateLimitError object { message, type }

            • message: string

            • type: "rate_limit_error"

              • "rate_limit_error"

          • BetaGatewayTimeoutError object { message, type }

            • message: string

            • type: "timeout_error"

              • "timeout_error"

          • BetaAPIError object { message, type }

            • message: string

            • type: "api_error"

              • "api_error"

          • BetaOverloadedError object { message, type }

            • message: string

            • type: "overloaded_error"

              • "overloaded_error"

        • request_id: string

        • type: "error"

          • "error"

      • type: "errored"

        • "errored"

    • BetaMessageBatchCanceledResult object { type }

      • type: "canceled"

        • "canceled"

    • BetaMessageBatchExpiredResult object { type }

      • type: "expired"

        • "expired"

Beta Message Batch Succeeded Result

  • BetaMessageBatchSucceededResult object { message, type }

    • message: BetaMessage

      • id: string

        Unique object identifier.

        The format and length of IDs may change over time.

      • 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 of BetaSkill

          Skills loaded in the container

          • skill_id: string

            Skill ID

          • type: "anthropic" or "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 of BetaContentBlock

        Content generated by the model.

        This is an array of content blocks, each of which has a type that determines its shape.

        Example:

        [{"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:

        [
  {"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:

        [{"type": "text", "text": "B)"}]

        • BetaTextBlock object { citations, text, type }

          • citations: array of BetaTextCitation

            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 object { cited_text, document_index, document_title, 4 more }

              • cited_text: string

              • document_index: number

              • document_title: string

              • end_char_index: number

              • file_id: string

              • start_char_index: number

              • type: "char_location"

                • "char_location"

            • BetaCitationPageLocation object { cited_text, document_index, document_title, 4 more }

              • cited_text: string

              • document_index: number

              • document_title: string

              • end_page_number: number

              • file_id: string

              • start_page_number: number

              • type: "page_location"

                • "page_location"

            • BetaCitationContentBlockLocation object { cited_text, document_index, document_title, 4 more }

              • 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

              • 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

              • 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 object { cited_text, encrypted_index, title, 2 more }

              • cited_text: string

              • encrypted_index: string

              • title: string

              • type: "web_search_result_location"

                • "web_search_result_location"

              • url: string

            • BetaCitationSearchResultLocation object { cited_text, end_block_index, search_result_index, 4 more }

              • 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

              • type: "search_result_location"

                • "search_result_location"

          • text: string

          • type: "text"

            • "text"

        • BetaThinkingBlock object { signature, thinking, type }

          • signature: string

          • thinking: string

          • type: "thinking"

            • "thinking"

        • BetaRedactedThinkingBlock object { data, type }

          • data: string

          • type: "redacted_thinking"

            • "redacted_thinking"

        • BetaToolUseBlock object { id, input, name, 2 more }

          • id: string

          • input: map[unknown]

          • name: string

          • type: "tool_use"

            • "tool_use"

          • caller: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

            Tool invocation directly from the model.

            • BetaDirectCaller object { type }

              Tool invocation directly from the model.

              • type: "direct"

                • "direct"

            • BetaServerToolCaller object { tool_id, type }

              Tool invocation generated by a server-side tool.

              • tool_id: string

              • type: "code_execution_20250825"

                • "code_execution_20250825"

            • BetaServerToolCaller20260120 object { tool_id, type }

              • tool_id: string

              • type: "code_execution_20260120"

                • "code_execution_20260120"

        • BetaServerToolUseBlock object { id, input, name, 2 more }

          • id: string

          • input: map[unknown]

          • name: "advisor" or "web_search" or "web_fetch" or 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: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

            Tool invocation directly from the model.

            • BetaDirectCaller object { type }

              Tool invocation directly from the model.

            • BetaServerToolCaller object { tool_id, type }

              Tool invocation generated by a server-side tool.

            • BetaServerToolCaller20260120 object { tool_id, type }

        • BetaWebSearchToolResultBlock object { content, tool_use_id, type, caller }

          • content: BetaWebSearchToolResultBlockContent

            • BetaWebSearchToolResultError object { error_code, type }

              • 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 of BetaWebSearchResultBlock

              • encrypted_content: string

              • page_age: string

              • 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: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

            Tool invocation directly from the model.

            • BetaDirectCaller object { type }

              Tool invocation directly from the model.

            • BetaServerToolCaller object { tool_id, type }

              Tool invocation generated by a server-side tool.

            • BetaServerToolCaller20260120 object { tool_id, type }

        • BetaWebFetchToolResultBlock object { content, tool_use_id, type, caller }

          • content: BetaWebFetchToolResultErrorBlock or BetaWebFetchBlock

            • BetaWebFetchToolResultErrorBlock object { error_code, type }

              • error_code: BetaWebFetchToolResultErrorCode

                • "invalid_tool_input"

                • "url_too_long"

                • "url_not_allowed"

                • "url_not_accessible"

                • "unsupported_content_type"

                • "too_many_requests"

                • "max_uses_exceeded"

                • "unavailable"

              • type: "web_fetch_tool_result_error"

                • "web_fetch_tool_result_error"

            • BetaWebFetchBlock object { content, retrieved_at, type, url }

              • content: BetaDocumentBlock

                • citations: BetaCitationConfig

                  Citation configuration for the document

                  • enabled: boolean

                • source: BetaBase64PDFSource or BetaPlainTextSource

                  • BetaBase64PDFSource object { data, media_type, type }

                    • data: string

                    • media_type: "application/pdf"

                      • "application/pdf"

                    • type: "base64"

                      • "base64"

                  • BetaPlainTextSource object { data, media_type, type }

                    • data: string

                    • media_type: "text/plain"

                      • "text/plain"

                    • type: "text"

                      • "text"

                • title: string

                  The title of the document

                • type: "document"

                  • "document"

              • retrieved_at: string

                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: optional BetaDirectCaller or BetaServerToolCaller or BetaServerToolCaller20260120

            Tool invocation directly from the model.

            • BetaDirectCaller object { type }

              Tool invocation directly from the model.

            • BetaServerToolCaller object { tool_id, type }

              Tool invocation generated by a server-side tool.

            • BetaServerToolCaller20260120 object { tool_id, type }

        • BetaAdvisorToolResultBlock object { content, tool_use_id, type }

          • content: BetaAdvisorToolResultError or BetaAdvisorResultBlock or BetaAdvisorRedactedResultBlock

            • BetaAdvisorToolResultError object { error_code, type }

              • error_code: "max_uses_exceeded" or "prompt_too_long" or "too_many_requests" or 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 object { text, type }

              • text: string

              • type: "advisor_result"

                • "advisor_result"

            • BetaAdvisorRedactedResultBlock object { encrypted_content, type }

              • encrypted_content: string

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

              • type: "advisor_redacted_result"

                • "advisor_redacted_result"

          • tool_use_id: string

          • type: "advisor_tool_result"

            • "advisor_tool_result"

        • BetaCodeExecutionToolResultBlock object { content, tool_use_id, type }

          • content: BetaCodeExecutionToolResultBlockContent

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

            • BetaCodeExecutionToolResultError object { error_code, type }

              • 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 object { content, return_code, stderr, 2 more }

              • content: array of BetaCodeExecutionOutputBlock

                • 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 object { content, encrypted_stdout, return_code, 2 more }

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

              • content: array of BetaCodeExecutionOutputBlock

                • 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 object { content, tool_use_id, type }

          • content: BetaBashCodeExecutionToolResultError or BetaBashCodeExecutionResultBlock

            • BetaBashCodeExecutionToolResultError object { error_code, type }

              • error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 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 object { content, return_code, stderr, 2 more }

              • content: array of BetaBashCodeExecutionOutputBlock

                • 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 object { content, tool_use_id, type }

          • content: BetaTextEditorCodeExecutionToolResultError or BetaTextEditorCodeExecutionViewResultBlock or BetaTextEditorCodeExecutionCreateResultBlock or BetaTextEditorCodeExecutionStrReplaceResultBlock

            • BetaTextEditorCodeExecutionToolResultError object { error_code, error_message, type }

              • error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or 2 more

                • "invalid_tool_input"

                • "unavailable"

                • "too_many_requests"

                • "execution_time_exceeded"

                • "file_not_found"

              • error_message: string

              • type: "text_editor_code_execution_tool_result_error"

                • "text_editor_code_execution_tool_result_error"

            • BetaTextEditorCodeExecutionViewResultBlock object { content, file_type, num_lines, 3 more }

              • content: string

              • file_type: "text" or "image" or "pdf"

                • "text"

                • "image"

                • "pdf"

              • num_lines: number

              • start_line: number

              • total_lines: number

              • type: "text_editor_code_execution_view_result"

                • "text_editor_code_execution_view_result"

            • BetaTextEditorCodeExecutionCreateResultBlock object { is_file_update, type }

              • is_file_update: boolean

              • type: "text_editor_code_execution_create_result"

                • "text_editor_code_execution_create_result"

            • BetaTextEditorCodeExecutionStrReplaceResultBlock object { lines, new_lines, new_start, 3 more }

              • lines: array of string

              • new_lines: number

              • new_start: number

              • old_lines: number

              • old_start: number

              • 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 object { content, tool_use_id, type }

          • content: BetaToolSearchToolResultError or BetaToolSearchToolSearchResultBlock

            • BetaToolSearchToolResultError object { error_code, error_message, type }

              • error_code: "invalid_tool_input" or "unavailable" or "too_many_requests" or "execution_time_exceeded"

                • "invalid_tool_input"

                • "unavailable"

                • "too_many_requests"

                • "execution_time_exceeded"

              • error_message: string

              • type: "tool_search_tool_result_error"

                • "tool_search_tool_result_error"

            • BetaToolSearchToolSearchResultBlock object { tool_references, type }

              • tool_references: array of BetaToolReferenceBlock

                • 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 object { id, input, name, 2 more }

          • id: string

          • input: map[unknown]

          • 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 object { content, is_error, tool_use_id, type }

          • content: string or array of BetaTextBlock

            • string

            • BetaMCPToolResultBlockContent = array of BetaTextBlock

              • citations: array of BetaTextCitation

                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 object { file_id, type }

          Response model for a file uploaded to the container.

          • file_id: string

          • type: "container_upload"

            • "container_upload"

        • BetaCompactionBlock object { content, encrypted_content, type }

          A compaction block returned when autocompact is triggered.

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

          • content: string

            Summary of compacted content, or null if compaction failed

          • encrypted_content: string

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

          • type: "compaction"

            • "compaction"

      • context_management: BetaContextManagementResponse

        Context management response.

        Information about context management strategies applied during the request.

        • applied_edits: array of BetaClearToolUses20250919EditResponse or BetaClearThinking20251015EditResponse

          List of context management edits that were applied.

          • BetaClearToolUses20250919EditResponse object { cleared_input_tokens, cleared_tool_uses, type }

            • cleared_input_tokens: number

              Number of input tokens cleared by this edit.

            • cleared_tool_uses: number

              Number of tool uses that were cleared.

            • type: "clear_tool_uses_20250919"

              The type of context management edit applied.

              • "clear_tool_uses_20250919"

          • BetaClearThinking20251015EditResponse object { cleared_input_tokens, cleared_thinking_turns, type }

            • cleared_input_tokens: number

              Number of input tokens cleared by this edit.

            • cleared_thinking_turns: number

              Number of thinking turns that were cleared.

            • type: "clear_thinking_20251015"

              The type of context management edit applied.

              • "clear_thinking_20251015"

      • diagnostics: BetaDiagnostics

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

        • cache_miss_reason: BetaCacheMissModelChanged or BetaCacheMissSystemChanged or BetaCacheMissToolsChanged or 3 more

          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 object { cache_missed_input_tokens, type }

            • 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 object { cache_missed_input_tokens, type }

            • 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 object { cache_missed_input_tokens, type }

            • 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 object { cache_missed_input_tokens, type }

            • 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 object { type }

            • type: "previous_message_not_found"

              • "previous_message_not_found"

          • BetaCacheMissUnavailable object { type }

            • type: "unavailable"

              • "unavailable"

      • model: Model

        The model that will complete your prompt.

        See models for additional details and options.

        • "claude-opus-4-7" or "claude-mythos-preview" or "claude-opus-4-6" or 14 more

          The model that will complete your prompt.

          See models for additional details and options.

          • "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

        Structured information about a refusal.

        • category: "cyber" or "bio"

          The policy category that triggered the refusal.

          null when the refusal doesn't map to a named category.

          • "cyber"

          • "bio"

        • explanation: string

          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

        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

        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

          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.

        • inference_geo: string

          The geographic region where inference was performed for this request.

        • input_tokens: number

          The number of input tokens which were used.

        • iterations: BetaIterationsUsage

          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 object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }

            Token usage for a sampling iteration.

            • cache_creation: BetaCacheCreation

              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 object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 3 more }

            Token usage for a compaction iteration.

            • cache_creation: BetaCacheCreation

              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 object { cache_creation, cache_creation_input_tokens, cache_read_input_tokens, 4 more }

            Token usage for an advisor sub-inference iteration.

            • cache_creation: BetaCacheCreation

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

        • server_tool_use: BetaServerToolUsage

          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" or "priority" or "batch"

          If the request used the priority, standard, or batch tier.

          • "standard"

          • "priority"

          • "batch"

        • speed: "standard" or "fast"

          The inference speed mode used for this request.

          • "standard"

          • "fast"

    • type: "succeeded"

      • "succeeded"

Agents

Create Agent

post /v1/agents

Create Agent

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Body Parameters

  • model: BetaManagedAgentsModel or BetaManagedAgentsModelConfigParams

    Model identifier. Accepts the model string, e.g. claude-opus-4-6, or a model_config object for additional configuration control

    • BetaManagedAgentsModel = "claude-opus-4-7" or "claude-opus-4-6" or "claude-sonnet-4-6" or 6 more or string

      The model that will power your agent.

      See models for additional details and options.

      • "claude-opus-4-7" or "claude-opus-4-6" or "claude-sonnet-4-6" or 6 more

        The model that will power your agent.

        See models for additional details and options.

        • "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 object { id, speed }

      An object that defines additional configuration control over model use

      • id: BetaManagedAgentsModel

        The model that will power your agent.

        See models for additional details and options.

      • speed: optional "standard" or "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

    Human-readable name for the agent. 1-256 characters.

  • description: optional string

    Description of what the agent does. Up to 2048 characters.

  • mcp_servers: optional array of BetaManagedAgentsURLMCPServerParams

    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: optional map[string]

    Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars.

  • multiagent: optional 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 of BetaManagedAgentsMultiagentRosterEntryParams

      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 object { id, type, version }

        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: optional number

          The specific agent version to use. Omit to use the latest version. Must be at least 1 if specified.

      • BetaManagedAgentsMultiagentSelfParams object { type }

        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: optional array of BetaManagedAgentsSkillParams

    Skills available to the agent. Maximum 20.

    • BetaManagedAgentsAnthropicSkillParams object { skill_id, type, version }

      An Anthropic-managed skill.

      • skill_id: string

        Identifier of the Anthropic skill (e.g., "xlsx").

      • type: "anthropic"

        • "anthropic"

      • version: optional string

        Version to pin. Defaults to latest if omitted.

    • BetaManagedAgentsCustomSkillParams object { skill_id, type, version }

      A user-created custom skill.

      • skill_id: string

        Tagged ID of the custom skill (e.g., "skill_01XJ5...").

      • type: "custom"

        • "custom"

      • version: optional string

        Version to pin. Defaults to latest if omitted.

  • system: optional string

    System prompt for the agent. Up to 100,000 characters.

  • tools: optional array of BetaManagedAgentsAgentToolset20260401Params or BetaManagedAgentsMCPToolsetParams or BetaManagedAgentsCustomToolParams

    Tool configurations available to the agent. Maximum of 128 tools across all toolsets allowed.

    • BetaManagedAgentsAgentToolset20260401Params object { type, configs, default_config }

      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: optional array of BetaManagedAgentsAgentToolConfigParams

        Per-tool configuration overrides.

        • name: "bash" or "edit" or "read" or 5 more

          Built-in agent tool identifier.

          • "bash"

          • "edit"

          • "read"

          • "write"

          • "glob"

          • "grep"

          • "web_fetch"

          • "web_search"

        • enabled: optional boolean

          Whether this tool is enabled and available to Claude. Overrides the default_config setting.

        • permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

          Permission policy for tool execution.

          • BetaManagedAgentsAlwaysAllowPolicy object { type }

            Tool calls are automatically approved without user confirmation.

            • type: "always_allow"

              • "always_allow"

          • BetaManagedAgentsAlwaysAskPolicy object { type }

            Tool calls require user confirmation before execution.

            • type: "always_ask"

              • "always_ask"

      • default_config: optional BetaManagedAgentsAgentToolsetDefaultConfigParams

        Default configuration for all tools in a toolset.

        • enabled: optional boolean

          Whether tools are enabled and available to Claude by default. Defaults to true if not specified.

        • permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

          Permission policy for tool execution.

          • BetaManagedAgentsAlwaysAllowPolicy object { type }

            Tool calls are automatically approved without user confirmation.

          • BetaManagedAgentsAlwaysAskPolicy object { type }

            Tool calls require user confirmation before execution.

    • BetaManagedAgentsMCPToolsetParams object { mcp_server_name, type, configs, default_config }

      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: optional array of BetaManagedAgentsMCPToolConfigParams

        Per-tool configuration overrides.

        • name: string

          Name of the MCP tool to configure. 1-128 characters.

        • enabled: optional boolean

          Whether this tool is enabled. Overrides the default_config setting.

        • permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

          Permission policy for tool execution.

          • BetaManagedAgentsAlwaysAllowPolicy object { type }

            Tool calls are automatically approved without user confirmation.

          • BetaManagedAgentsAlwaysAskPolicy object { type }

            Tool calls require user confirmation before execution.

      • default_config: optional BetaManagedAgentsMCPToolsetDefaultConfigParams

        Default configuration for all tools from an MCP server.

        • enabled: optional boolean

          Whether tools are enabled by default. Defaults to true if not specified.

        • permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

          Permission policy for tool execution.

          • BetaManagedAgentsAlwaysAllowPolicy object { type }

            Tool calls are automatically approved without user confirmation.

          • BetaManagedAgentsAlwaysAskPolicy object { type }

            Tool calls require user confirmation before execution.

    • BetaManagedAgentsCustomToolParams object { description, input_schema, name, type }

      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: optional map[unknown]

          JSON Schema properties defining the tool's input parameters.

        • required: optional array of string

          List of required property names.

        • type: optional "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"

Returns

  • BetaManagedAgentsAgent object { id, archived_at, created_at, 12 more }

    A Managed Agents agent.

    • id: string

    • archived_at: string

      A timestamp in RFC 3339 format

    • created_at: string

      A timestamp in RFC 3339 format

    • description: string

    • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

      • name: string

      • type: "url"

        • "url"

      • url: string

    • metadata: map[string]

    • model: BetaManagedAgentsModelConfig

      Model identifier and configuration.

      • id: BetaManagedAgentsModel

        The model that will power your agent.

        See models for additional details and options.

        • "claude-opus-4-7" or "claude-opus-4-6" or "claude-sonnet-4-6" or 6 more

          The model that will power your agent.

          See models for additional details and options.

          • "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: optional "standard" or "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

      Resolved coordinator topology with a concrete agent roster.

      • agents: array of BetaManagedAgentsAgentReference

        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 of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

      • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

        A resolved Anthropic-managed skill.

        • skill_id: string

        • type: "anthropic"

          • "anthropic"

        • version: string

      • BetaManagedAgentsCustomSkill object { skill_id, type, version }

        A resolved user-created custom skill.

        • skill_id: string

        • type: "custom"

          • "custom"

        • version: string

    • system: string

    • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

      • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

        • configs: array of BetaManagedAgentsAgentToolConfig

          • enabled: boolean

          • name: "bash" or "edit" or "read" or 5 more

            Built-in agent tool identifier.

            • "bash"

            • "edit"

            • "read"

            • "write"

            • "glob"

            • "grep"

            • "web_fetch"

            • "web_search"

          • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

            Permission policy for tool execution.

            • BetaManagedAgentsAlwaysAllowPolicy object { type }

              Tool calls are automatically approved without user confirmation.

              • type: "always_allow"

                • "always_allow"

            • BetaManagedAgentsAlwaysAskPolicy object { type }

              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 or BetaManagedAgentsAlwaysAskPolicy

            Permission policy for tool execution.

            • BetaManagedAgentsAlwaysAllowPolicy object { type }

              Tool calls are automatically approved without user confirmation.

            • BetaManagedAgentsAlwaysAskPolicy object { type }

              Tool calls require user confirmation before execution.

        • type: "agent_toolset_20260401"

          • "agent_toolset_20260401"

      • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

        • configs: array of BetaManagedAgentsMCPToolConfig

          • enabled: boolean

          • name: string

          • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

            Permission policy for tool execution.

            • BetaManagedAgentsAlwaysAllowPolicy object { type }

              Tool calls are automatically approved without user confirmation.

            • BetaManagedAgentsAlwaysAskPolicy object { type }

              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 or BetaManagedAgentsAlwaysAskPolicy

            Permission policy for tool execution.

            • BetaManagedAgentsAlwaysAllowPolicy object { type }

              Tool calls are automatically approved without user confirmation.

            • BetaManagedAgentsAlwaysAskPolicy object { type }

              Tool calls require user confirmation before execution.

        • mcp_server_name: string

        • type: "mcp_toolset"

          • "mcp_toolset"

      • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

        A custom tool as returned in API responses.

        • description: string

        • input_schema: BetaManagedAgentsCustomToolInputSchema

          JSON Schema for custom tool input parameters.

          • properties: optional map[unknown]

            JSON Schema properties defining the tool's input parameters.

          • required: optional array of string

            List of required property names.

          • type: optional "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

curl https://api.anthropic.com/v1/agents \
    -H 'Content-Type: application/json' \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: managed-agents-2026-04-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY" \
    -d "{
          \"model\": \"claude-sonnet-4-6\",
          \"name\": \"My First Agent\",
          \"description\": \"A general-purpose starter agent.\",
          \"metadata\": {
            \"foo\": \"bar\"
          },
          \"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\": [
            {
              \"type\": \"agent_toolset_20260401\"
            }
          ]
        }"

Response

{
  "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

get /v1/agents

List Agents

Query Parameters

  • "created_at[gte]": optional string

    Return agents created at or after this time (inclusive).

  • "created_at[lte]": optional string

    Return agents created at or before this time (inclusive).

  • include_archived: optional boolean

    Include archived agents in results. Defaults to false.

  • limit: optional number

    Maximum results per page. Default 20, maximum 100.

  • page: optional string

    Opaque pagination cursor from a previous response.

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Returns

  • data: optional array of BetaManagedAgentsAgent

    List of agents.

    • id: string

    • archived_at: string

      A timestamp in RFC 3339 format

    • created_at: string

      A timestamp in RFC 3339 format

    • description: string

    • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

      • name: string

      • type: "url"

        • "url"

      • url: string

    • metadata: map[string]

    • model: BetaManagedAgentsModelConfig

      Model identifier and configuration.

      • id: BetaManagedAgentsModel

        The model that will power your agent.

        See models for additional details and options.

        • "claude-opus-4-7" or "claude-opus-4-6" or "claude-sonnet-4-6" or 6 more

          The model that will power your agent.

          See models for additional details and options.

          • "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: optional "standard" or "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

      Resolved coordinator topology with a concrete agent roster.

      • agents: array of BetaManagedAgentsAgentReference

        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 of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

      • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

        A resolved Anthropic-managed skill.

        • skill_id: string

        • type: "anthropic"

          • "anthropic"

        • version: string

      • BetaManagedAgentsCustomSkill object { skill_id, type, version }

        A resolved user-created custom skill.

        • skill_id: string

        • type: "custom"

          • "custom"

        • version: string

    • system: string

    • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

      • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

        • configs: array of BetaManagedAgentsAgentToolConfig

          • enabled: boolean

          • name: "bash" or "edit" or "read" or 5 more

            Built-in agent tool identifier.

            • "bash"

            • "edit"

            • "read"

            • "write"

            • "glob"

            • "grep"

            • "web_fetch"

            • "web_search"

          • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

            Permission policy for tool execution.

            • BetaManagedAgentsAlwaysAllowPolicy object { type }

              Tool calls are automatically approved without user confirmation.

              • type: "always_allow"

                • "always_allow"

            • BetaManagedAgentsAlwaysAskPolicy object { type }

              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 or BetaManagedAgentsAlwaysAskPolicy

            Permission policy for tool execution.

            • BetaManagedAgentsAlwaysAllowPolicy object { type }

              Tool calls are automatically approved without user confirmation.

            • BetaManagedAgentsAlwaysAskPolicy object { type }

              Tool calls require user confirmation before execution.

        • type: "agent_toolset_20260401"

          • "agent_toolset_20260401"

      • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

        • configs: array of BetaManagedAgentsMCPToolConfig

          • enabled: boolean

          • name: string

          • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

            Permission policy for tool execution.

            • BetaManagedAgentsAlwaysAllowPolicy object { type }

              Tool calls are automatically approved without user confirmation.

            • BetaManagedAgentsAlwaysAskPolicy object { type }

              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 or BetaManagedAgentsAlwaysAskPolicy

            Permission policy for tool execution.

            • BetaManagedAgentsAlwaysAllowPolicy object { type }

              Tool calls are automatically approved without user confirmation.

            • BetaManagedAgentsAlwaysAskPolicy object { type }

              Tool calls require user confirmation before execution.

        • mcp_server_name: string

        • type: "mcp_toolset"

          • "mcp_toolset"

      • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

        A custom tool as returned in API responses.

        • description: string

        • input_schema: BetaManagedAgentsCustomToolInputSchema

          JSON Schema for custom tool input parameters.

          • properties: optional map[unknown]

            JSON Schema properties defining the tool's input parameters.

          • required: optional array of string

            List of required property names.

          • type: optional "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.

  • next_page: optional string

    Opaque cursor for the next page. Null when no more results.

Example

curl https://api.anthropic.com/v1/agents \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: managed-agents-2026-04-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

Response

{
  "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

get /v1/agents/{agent_id}

Get Agent

Path Parameters

  • agent_id: string

Query Parameters

  • version: optional number

    Agent version. Omit for the most recent version. Must be at least 1 if specified.

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Returns

  • BetaManagedAgentsAgent object { id, archived_at, created_at, 12 more }

    A Managed Agents agent.

    • id: string

    • archived_at: string

      A timestamp in RFC 3339 format

    • created_at: string

      A timestamp in RFC 3339 format

    • description: string

    • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

      • name: string

      • type: "url"

        • "url"

      • url: string

    • metadata: map[string]

    • model: BetaManagedAgentsModelConfig

      Model identifier and configuration.

      • id: BetaManagedAgentsModel

        The model that will power your agent.

        See models for additional details and options.

        • "claude-opus-4-7" or "claude-opus-4-6" or "claude-sonnet-4-6" or 6 more

          The model that will power your agent.

          See models for additional details and options.

          • "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: optional "standard" or "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

      Resolved coordinator topology with a concrete agent roster.

      • agents: array of BetaManagedAgentsAgentReference

        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 of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

      • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

        A resolved Anthropic-managed skill.

        • skill_id: string

        • type: "anthropic"

          • "anthropic"

        • version: string

      • BetaManagedAgentsCustomSkill object { skill_id, type, version }

        A resolved user-created custom skill.

        • skill_id: string

        • type: "custom"

          • "custom"

        • version: string

    • system: string

    • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

      • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

        • configs: array of BetaManagedAgentsAgentToolConfig

          • enabled: boolean

          • name: "bash" or "edit" or "read" or 5 more

            Built-in agent tool identifier.

            • "bash"

            • "edit"

            • "read"

            • "write"

            • "glob"

            • "grep"

            • "web_fetch"

            • "web_search"

          • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

            Permission policy for tool execution.

            • BetaManagedAgentsAlwaysAllowPolicy object { type }

              Tool calls are automatically approved without user confirmation.

              • type: "always_allow"

                • "always_allow"

            • BetaManagedAgentsAlwaysAskPolicy object { type }

              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 or BetaManagedAgentsAlwaysAskPolicy

            Permission policy for tool execution.

            • BetaManagedAgentsAlwaysAllowPolicy object { type }

              Tool calls are automatically approved without user confirmation.

            • BetaManagedAgentsAlwaysAskPolicy object { type }

              Tool calls require user confirmation before execution.

        • type: "agent_toolset_20260401"

          • "agent_toolset_20260401"

      • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

        • configs: array of BetaManagedAgentsMCPToolConfig

          • enabled: boolean

          • name: string

          • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

            Permission policy for tool execution.

            • BetaManagedAgentsAlwaysAllowPolicy object { type }

              Tool calls are automatically approved without user confirmation.

            • BetaManagedAgentsAlwaysAskPolicy object { type }

              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 or BetaManagedAgentsAlwaysAskPolicy

            Permission policy for tool execution.

            • BetaManagedAgentsAlwaysAllowPolicy object { type }

              Tool calls are automatically approved without user confirmation.

            • BetaManagedAgentsAlwaysAskPolicy object { type }

              Tool calls require user confirmation before execution.

        • mcp_server_name: string

        • type: "mcp_toolset"

          • "mcp_toolset"

      • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

        A custom tool as returned in API responses.

        • description: string

        • input_schema: BetaManagedAgentsCustomToolInputSchema

          JSON Schema for custom tool input parameters.

          • properties: optional map[unknown]

            JSON Schema properties defining the tool's input parameters.

          • required: optional array of string

            List of required property names.

          • type: optional "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

curl https://api.anthropic.com/v1/agents/$AGENT_ID \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: managed-agents-2026-04-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

Response

{
  "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

post /v1/agents/{agent_id}

Update Agent

Path Parameters

  • agent_id: string

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Body Parameters

  • version: number

    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: optional string

    Description. Up to 2048 characters. Omit to preserve; send empty string or null to clear.

  • mcp_servers: optional array of BetaManagedAgentsURLMCPServerParams

    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: optional map[string]

    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: optional BetaManagedAgentsModel or BetaManagedAgentsModelConfigParams

    Model identifier. Accepts the model string, 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-7" or "claude-opus-4-6" or "claude-sonnet-4-6" or 6 more or string

      The model that will power your agent.

      See models for additional details and options.

      • "claude-opus-4-7" or "claude-opus-4-6" or "claude-sonnet-4-6" or 6 more

        The model that will power your agent.

        See models for additional details and options.

        • "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 object { id, speed }

      An object that defines additional configuration control over model use

      • id: BetaManagedAgentsModel

        The model that will power your agent.

        See models for additional details and options.

      • speed: optional "standard" or "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: optional 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 of BetaManagedAgentsMultiagentRosterEntryParams

      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 object { id, type, version }

        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: optional number

          The specific agent version to use. Omit to use the latest version. Must be at least 1 if specified.

      • BetaManagedAgentsMultiagentSelfParams object { type }

        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: optional string

    Human-readable name. 1-256 characters. Omit to preserve. Cannot be cleared.

  • skills: optional array of BetaManagedAgentsSkillParams

    Skills. Full replacement. Omit to preserve; send empty array or null to clear. Maximum 20.

    • BetaManagedAgentsAnthropicSkillParams object { skill_id, type, version }

      An Anthropic-managed skill.

      • skill_id: string

        Identifier of the Anthropic skill (e.g., "xlsx").

      • type: "anthropic"

        • "anthropic"

      • version: optional string

        Version to pin. Defaults to latest if omitted.

    • BetaManagedAgentsCustomSkillParams object { skill_id, type, version }

      A user-created custom skill.

      • skill_id: string

        Tagged ID of the custom skill (e.g., "skill_01XJ5...").

      • type: "custom"

        • "custom"

      • version: optional string

        Version to pin. Defaults to latest if omitted.

  • system: optional string

    System prompt. Up to 100,000 characters. Omit to preserve; send empty string or null to clear.

  • tools: optional array of BetaManagedAgentsAgentToolset20260401Params or BetaManagedAgentsMCPToolsetParams or BetaManagedAgentsCustomToolParams

    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 object { type, configs, default_config }

      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: optional array of BetaManagedAgentsAgentToolConfigParams

        Per-tool configuration overrides.

        • name: "bash" or "edit" or "read" or 5 more

          Built-in agent tool identifier.

          • "bash"

          • "edit"

          • "read"

          • "write"

          • "glob"

          • "grep"

          • "web_fetch"

          • "web_search"

        • enabled: optional boolean

          Whether this tool is enabled and available to Claude. Overrides the default_config setting.

        • permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

          Permission policy for tool execution.

          • BetaManagedAgentsAlwaysAllowPolicy object { type }

            Tool calls are automatically approved without user confirmation.

            • type: "always_allow"

              • "always_allow"

          • BetaManagedAgentsAlwaysAskPolicy object { type }

            Tool calls require user confirmation before execution.

            • type: "always_ask"

              • "always_ask"

      • default_config: optional BetaManagedAgentsAgentToolsetDefaultConfigParams

        Default configuration for all tools in a toolset.

        • enabled: optional boolean

          Whether tools are enabled and available to Claude by default. Defaults to true if not specified.

        • permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

          Permission policy for tool execution.

          • BetaManagedAgentsAlwaysAllowPolicy object { type }

            Tool calls are automatically approved without user confirmation.

          • BetaManagedAgentsAlwaysAskPolicy object { type }

            Tool calls require user confirmation before execution.

    • BetaManagedAgentsMCPToolsetParams object { mcp_server_name, type, configs, default_config }

      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: optional array of BetaManagedAgentsMCPToolConfigParams

        Per-tool configuration overrides.

        • name: string

          Name of the MCP tool to configure. 1-128 characters.

        • enabled: optional boolean

          Whether this tool is enabled. Overrides the default_config setting.

        • permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

          Permission policy for tool execution.

          • BetaManagedAgentsAlwaysAllowPolicy object { type }

            Tool calls are automatically approved without user confirmation.

          • BetaManagedAgentsAlwaysAskPolicy object { type }

            Tool calls require user confirmation before execution.

      • default_config: optional BetaManagedAgentsMCPToolsetDefaultConfigParams

        Default configuration for all tools from an MCP server.

        • enabled: optional boolean

          Whether tools are enabled by default. Defaults to true if not specified.

        • permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

          Permission policy for tool execution.

          • BetaManagedAgentsAlwaysAllowPolicy object { type }

            Tool calls are automatically approved without user confirmation.

          • BetaManagedAgentsAlwaysAskPolicy object { type }

            Tool calls require user confirmation before execution.

    • BetaManagedAgentsCustomToolParams object { description, input_schema, name, type }

      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: optional map[unknown]

          JSON Schema properties defining the tool's input parameters.

        • required: optional array of string

          List of required property names.

        • type: optional "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"

Returns

  • BetaManagedAgentsAgent object { id, archived_at, created_at, 12 more }

    A Managed Agents agent.

    • id: string

    • archived_at: string

      A timestamp in RFC 3339 format

    • created_at: string

      A timestamp in RFC 3339 format

    • description: string

    • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

      • name: string

      • type: "url"

        • "url"

      • url: string

    • metadata: map[string]

    • model: BetaManagedAgentsModelConfig

      Model identifier and configuration.

      • id: BetaManagedAgentsModel

        The model that will power your agent.

        See models for additional details and options.

        • "claude-opus-4-7" or "claude-opus-4-6" or "claude-sonnet-4-6" or 6 more

          The model that will power your agent.

          See models for additional details and options.

          • "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: optional "standard" or "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

      Resolved coordinator topology with a concrete agent roster.

      • agents: array of BetaManagedAgentsAgentReference

        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 of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

      • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

        A resolved Anthropic-managed skill.

        • skill_id: string

        • type: "anthropic"

          • "anthropic"

        • version: string

      • BetaManagedAgentsCustomSkill object { skill_id, type, version }

        A resolved user-created custom skill.

        • skill_id: string

        • type: "custom"

          • "custom"

        • version: string

    • system: string

    • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

      • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

        • configs: array of BetaManagedAgentsAgentToolConfig

          • enabled: boolean

          • name: "bash" or "edit" or "read" or 5 more

            Built-in agent tool identifier.

            • "bash"

            • "edit"

            • "read"

            • "write"

            • "glob"

            • "grep"

            • "web_fetch"

            • "web_search"

          • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

            Permission policy for tool execution.

            • BetaManagedAgentsAlwaysAllowPolicy object { type }

              Tool calls are automatically approved without user confirmation.

              • type: "always_allow"

                • "always_allow"

            • BetaManagedAgentsAlwaysAskPolicy object { type }

              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 or BetaManagedAgentsAlwaysAskPolicy

            Permission policy for tool execution.

            • BetaManagedAgentsAlwaysAllowPolicy object { type }

              Tool calls are automatically approved without user confirmation.

            • BetaManagedAgentsAlwaysAskPolicy object { type }

              Tool calls require user confirmation before execution.

        • type: "agent_toolset_20260401"

          • "agent_toolset_20260401"

      • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

        • configs: array of BetaManagedAgentsMCPToolConfig

          • enabled: boolean

          • name: string

          • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

            Permission policy for tool execution.

            • BetaManagedAgentsAlwaysAllowPolicy object { type }

              Tool calls are automatically approved without user confirmation.

            • BetaManagedAgentsAlwaysAskPolicy object { type }

              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 or BetaManagedAgentsAlwaysAskPolicy

            Permission policy for tool execution.

            • BetaManagedAgentsAlwaysAllowPolicy object { type }

              Tool calls are automatically approved without user confirmation.

            • BetaManagedAgentsAlwaysAskPolicy object { type }

              Tool calls require user confirmation before execution.

        • mcp_server_name: string

        • type: "mcp_toolset"

          • "mcp_toolset"

      • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

        A custom tool as returned in API responses.

        • description: string

        • input_schema: BetaManagedAgentsCustomToolInputSchema

          JSON Schema for custom tool input parameters.

          • properties: optional map[unknown]

            JSON Schema properties defining the tool's input parameters.

          • required: optional array of string

            List of required property names.

          • type: optional "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

curl https://api.anthropic.com/v1/agents/$AGENT_ID \
    -H 'Content-Type: application/json' \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: managed-agents-2026-04-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY" \
    -d "{
          \"version\": 1,
          \"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.\"
        }"

Response

{
  "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

post /v1/agents/{agent_id}/archive

Archive Agent

Path Parameters

  • agent_id: string

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Returns

  • BetaManagedAgentsAgent object { id, archived_at, created_at, 12 more }

    A Managed Agents agent.

    • id: string

    • archived_at: string

      A timestamp in RFC 3339 format

    • created_at: string

      A timestamp in RFC 3339 format

    • description: string

    • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

      • name: string

      • type: "url"

        • "url"

      • url: string

    • metadata: map[string]

    • model: BetaManagedAgentsModelConfig

      Model identifier and configuration.

      • id: BetaManagedAgentsModel

        The model that will power your agent.

        See models for additional details and options.

        • "claude-opus-4-7" or "claude-opus-4-6" or "claude-sonnet-4-6" or 6 more

          The model that will power your agent.

          See models for additional details and options.

          • "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: optional "standard" or "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

      Resolved coordinator topology with a concrete agent roster.

      • agents: array of BetaManagedAgentsAgentReference

        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 of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

      • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

        A resolved Anthropic-managed skill.

        • skill_id: string

        • type: "anthropic"

          • "anthropic"

        • version: string

      • BetaManagedAgentsCustomSkill object { skill_id, type, version }

        A resolved user-created custom skill.

        • skill_id: string

        • type: "custom"

          • "custom"

        • version: string

    • system: string

    • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

      • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

        • configs: array of BetaManagedAgentsAgentToolConfig

          • enabled: boolean

          • name: "bash" or "edit" or "read" or 5 more

            Built-in agent tool identifier.

            • "bash"

            • "edit"

            • "read"

            • "write"

            • "glob"

            • "grep"

            • "web_fetch"

            • "web_search"

          • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

            Permission policy for tool execution.

            • BetaManagedAgentsAlwaysAllowPolicy object { type }

              Tool calls are automatically approved without user confirmation.

              • type: "always_allow"

                • "always_allow"

            • BetaManagedAgentsAlwaysAskPolicy object { type }

              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 or BetaManagedAgentsAlwaysAskPolicy

            Permission policy for tool execution.

            • BetaManagedAgentsAlwaysAllowPolicy object { type }

              Tool calls are automatically approved without user confirmation.

            • BetaManagedAgentsAlwaysAskPolicy object { type }

              Tool calls require user confirmation before execution.

        • type: "agent_toolset_20260401"

          • "agent_toolset_20260401"

      • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

        • configs: array of BetaManagedAgentsMCPToolConfig

          • enabled: boolean

          • name: string

          • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

            Permission policy for tool execution.

            • BetaManagedAgentsAlwaysAllowPolicy object { type }

              Tool calls are automatically approved without user confirmation.

            • BetaManagedAgentsAlwaysAskPolicy object { type }

              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 or BetaManagedAgentsAlwaysAskPolicy

            Permission policy for tool execution.

            • BetaManagedAgentsAlwaysAllowPolicy object { type }

              Tool calls are automatically approved without user confirmation.

            • BetaManagedAgentsAlwaysAskPolicy object { type }

              Tool calls require user confirmation before execution.

        • mcp_server_name: string

        • type: "mcp_toolset"

          • "mcp_toolset"

      • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

        A custom tool as returned in API responses.

        • description: string

        • input_schema: BetaManagedAgentsCustomToolInputSchema

          JSON Schema for custom tool input parameters.

          • properties: optional map[unknown]

            JSON Schema properties defining the tool's input parameters.

          • required: optional array of string

            List of required property names.

          • type: optional "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

curl https://api.anthropic.com/v1/agents/$AGENT_ID/archive \
    -X POST \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: managed-agents-2026-04-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

Response

{
  "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 object { id, archived_at, created_at, 12 more }

    A Managed Agents agent.

    • id: string

    • archived_at: string

      A timestamp in RFC 3339 format

    • created_at: string

      A timestamp in RFC 3339 format

    • description: string

    • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

      • name: string

      • type: "url"

        • "url"

      • url: string

    • metadata: map[string]

    • model: BetaManagedAgentsModelConfig

      Model identifier and configuration.

      • id: BetaManagedAgentsModel

        The model that will power your agent.

        See models for additional details and options.

        • "claude-opus-4-7" or "claude-opus-4-6" or "claude-sonnet-4-6" or 6 more

          The model that will power your agent.

          See models for additional details and options.

          • "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: optional "standard" or "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

      Resolved coordinator topology with a concrete agent roster.

      • agents: array of BetaManagedAgentsAgentReference

        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 of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

      • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

        A resolved Anthropic-managed skill.

        • skill_id: string

        • type: "anthropic"

          • "anthropic"

        • version: string

      • BetaManagedAgentsCustomSkill object { skill_id, type, version }

        A resolved user-created custom skill.

        • skill_id: string

        • type: "custom"

          • "custom"

        • version: string

    • system: string

    • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

      • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

        • configs: array of BetaManagedAgentsAgentToolConfig

          • enabled: boolean

          • name: "bash" or "edit" or "read" or 5 more

            Built-in agent tool identifier.

            • "bash"

            • "edit"

            • "read"

            • "write"

            • "glob"

            • "grep"

            • "web_fetch"

            • "web_search"

          • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

            Permission policy for tool execution.

            • BetaManagedAgentsAlwaysAllowPolicy object { type }

              Tool calls are automatically approved without user confirmation.

              • type: "always_allow"

                • "always_allow"

            • BetaManagedAgentsAlwaysAskPolicy object { type }

              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 or BetaManagedAgentsAlwaysAskPolicy

            Permission policy for tool execution.

            • BetaManagedAgentsAlwaysAllowPolicy object { type }

              Tool calls are automatically approved without user confirmation.

            • BetaManagedAgentsAlwaysAskPolicy object { type }

              Tool calls require user confirmation before execution.

        • type: "agent_toolset_20260401"

          • "agent_toolset_20260401"

      • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

        • configs: array of BetaManagedAgentsMCPToolConfig

          • enabled: boolean

          • name: string

          • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

            Permission policy for tool execution.

            • BetaManagedAgentsAlwaysAllowPolicy object { type }

              Tool calls are automatically approved without user confirmation.

            • BetaManagedAgentsAlwaysAskPolicy object { type }

              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 or BetaManagedAgentsAlwaysAskPolicy

            Permission policy for tool execution.

            • BetaManagedAgentsAlwaysAllowPolicy object { type }

              Tool calls are automatically approved without user confirmation.

            • BetaManagedAgentsAlwaysAskPolicy object { type }

              Tool calls require user confirmation before execution.

        • mcp_server_name: string

        • type: "mcp_toolset"

          • "mcp_toolset"

      • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

        A custom tool as returned in API responses.

        • description: string

        • input_schema: BetaManagedAgentsCustomToolInputSchema

          JSON Schema for custom tool input parameters.

          • properties: optional map[unknown]

            JSON Schema properties defining the tool's input parameters.

          • required: optional array of string

            List of required property names.

          • type: optional "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 object { id, type, version }

    A resolved agent reference with a concrete version.

    • id: string

    • type: "agent"

      • "agent"

    • version: number

Beta Managed Agents Agent Tool Config

  • BetaManagedAgentsAgentToolConfig object { enabled, name, permission_policy }

    Configuration for a specific agent tool.

    • enabled: boolean

    • name: "bash" or "edit" or "read" or 5 more

      Built-in agent tool identifier.

      • "bash"

      • "edit"

      • "read"

      • "write"

      • "glob"

      • "grep"

      • "web_fetch"

      • "web_search"

    • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

      Permission policy for tool execution.

      • BetaManagedAgentsAlwaysAllowPolicy object { type }

        Tool calls are automatically approved without user confirmation.

        • type: "always_allow"

          • "always_allow"

      • BetaManagedAgentsAlwaysAskPolicy object { type }

        Tool calls require user confirmation before execution.

        • type: "always_ask"

          • "always_ask"

Beta Managed Agents Agent Tool Config Params

  • BetaManagedAgentsAgentToolConfigParams object { name, enabled, permission_policy }

    Configuration override for a specific tool within a toolset.

    • name: "bash" or "edit" or "read" or 5 more

      Built-in agent tool identifier.

      • "bash"

      • "edit"

      • "read"

      • "write"

      • "glob"

      • "grep"

      • "web_fetch"

      • "web_search"

    • enabled: optional boolean

      Whether this tool is enabled and available to Claude. Overrides the default_config setting.

    • permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

      Permission policy for tool execution.

      • BetaManagedAgentsAlwaysAllowPolicy object { type }

        Tool calls are automatically approved without user confirmation.

        • type: "always_allow"

          • "always_allow"

      • BetaManagedAgentsAlwaysAskPolicy object { type }

        Tool calls require user confirmation before execution.

        • type: "always_ask"

          • "always_ask"

Beta Managed Agents Agent Toolset Default Config

  • BetaManagedAgentsAgentToolsetDefaultConfig object { enabled, permission_policy }

    Resolved default configuration for agent tools.

    • enabled: boolean

    • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

      Permission policy for tool execution.

      • BetaManagedAgentsAlwaysAllowPolicy object { type }

        Tool calls are automatically approved without user confirmation.

        • type: "always_allow"

          • "always_allow"

      • BetaManagedAgentsAlwaysAskPolicy object { type }

        Tool calls require user confirmation before execution.

        • type: "always_ask"

          • "always_ask"

Beta Managed Agents Agent Toolset Default Config Params

  • BetaManagedAgentsAgentToolsetDefaultConfigParams object { enabled, permission_policy }

    Default configuration for all tools in a toolset.

    • enabled: optional boolean

      Whether tools are enabled and available to Claude by default. Defaults to true if not specified.

    • permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

      Permission policy for tool execution.

      • BetaManagedAgentsAlwaysAllowPolicy object { type }

        Tool calls are automatically approved without user confirmation.

        • type: "always_allow"

          • "always_allow"

      • BetaManagedAgentsAlwaysAskPolicy object { type }

        Tool calls require user confirmation before execution.

        • type: "always_ask"

          • "always_ask"

Beta Managed Agents Agent Toolset20260401

  • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

    • configs: array of BetaManagedAgentsAgentToolConfig

      • enabled: boolean

      • name: "bash" or "edit" or "read" or 5 more

        Built-in agent tool identifier.

        • "bash"

        • "edit"

        • "read"

        • "write"

        • "glob"

        • "grep"

        • "web_fetch"

        • "web_search"

      • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

        Permission policy for tool execution.

        • BetaManagedAgentsAlwaysAllowPolicy object { type }

          Tool calls are automatically approved without user confirmation.

          • type: "always_allow"

            • "always_allow"

        • BetaManagedAgentsAlwaysAskPolicy object { type }

          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 or BetaManagedAgentsAlwaysAskPolicy

        Permission policy for tool execution.

        • BetaManagedAgentsAlwaysAllowPolicy object { type }

          Tool calls are automatically approved without user confirmation.

        • BetaManagedAgentsAlwaysAskPolicy object { type }

          Tool calls require user confirmation before execution.

    • type: "agent_toolset_20260401"

      • "agent_toolset_20260401"

Beta Managed Agents Agent Toolset20260401 Bash Input

  • BetaManagedAgentsAgentToolset20260401BashInput object { command, restart, timeout_ms }

    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: optional string

      Shell command to execute. Omit only when restart is true.

    • restart: optional 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: optional 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 object { file_path, new_string, old_string, replace_all }

    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: optional boolean

      When true, replace every occurrence of old_string instead of requiring a unique match.

Beta Managed Agents Agent Toolset20260401 Glob Input

  • BetaManagedAgentsAgentToolset20260401GlobInput object { pattern, path }

    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: optional string

      Optional directory root to search under. Defaults to the runner's working directory.

Beta Managed Agents Agent Toolset20260401 Grep Input

  • BetaManagedAgentsAgentToolset20260401GrepInput object { pattern, path }

    Input payload for the grep tool. Searches file contents for a regular expression, returning matching lines.

    • pattern: string

      Regular expression to search for.

    • path: optional string

      Optional directory root to search under. Defaults to the runner's working directory.

Beta Managed Agents Agent Toolset20260401 Params

  • BetaManagedAgentsAgentToolset20260401Params object { type, configs, default_config }

    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: optional array of BetaManagedAgentsAgentToolConfigParams

      Per-tool configuration overrides.

      • name: "bash" or "edit" or "read" or 5 more

        Built-in agent tool identifier.

        • "bash"

        • "edit"

        • "read"

        • "write"

        • "glob"

        • "grep"

        • "web_fetch"

        • "web_search"

      • enabled: optional boolean

        Whether this tool is enabled and available to Claude. Overrides the default_config setting.

      • permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

        Permission policy for tool execution.

        • BetaManagedAgentsAlwaysAllowPolicy object { type }

          Tool calls are automatically approved without user confirmation.

          • type: "always_allow"

            • "always_allow"

        • BetaManagedAgentsAlwaysAskPolicy object { type }

          Tool calls require user confirmation before execution.

          • type: "always_ask"

            • "always_ask"

    • default_config: optional BetaManagedAgentsAgentToolsetDefaultConfigParams

      Default configuration for all tools in a toolset.

      • enabled: optional boolean

        Whether tools are enabled and available to Claude by default. Defaults to true if not specified.

      • permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

        Permission policy for tool execution.

        • BetaManagedAgentsAlwaysAllowPolicy object { type }

          Tool calls are automatically approved without user confirmation.

        • BetaManagedAgentsAlwaysAskPolicy object { type }

          Tool calls require user confirmation before execution.

Beta Managed Agents Agent Toolset20260401 Read Input

  • BetaManagedAgentsAgentToolset20260401ReadInput object { file_path, view_range }

    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: optional array of number

      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 object { content, file_path }

    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 object { type }

    Tool calls are automatically approved without user confirmation.

    • type: "always_allow"

      • "always_allow"

Beta Managed Agents Always Ask Policy

  • BetaManagedAgentsAlwaysAskPolicy object { type }

    Tool calls require user confirmation before execution.

    • type: "always_ask"

      • "always_ask"

Beta Managed Agents Anthropic Skill

  • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

    A resolved Anthropic-managed skill.

    • skill_id: string

    • type: "anthropic"

      • "anthropic"

    • version: string

Beta Managed Agents Anthropic Skill Params

  • BetaManagedAgentsAnthropicSkillParams object { skill_id, type, version }

    An Anthropic-managed skill.

    • skill_id: string

      Identifier of the Anthropic skill (e.g., "xlsx").

    • type: "anthropic"

      • "anthropic"

    • version: optional string

      Version to pin. Defaults to latest if omitted.

Beta Managed Agents Custom Skill

  • BetaManagedAgentsCustomSkill object { skill_id, type, version }

    A resolved user-created custom skill.

    • skill_id: string

    • type: "custom"

      • "custom"

    • version: string

Beta Managed Agents Custom Skill Params

  • BetaManagedAgentsCustomSkillParams object { skill_id, type, version }

    A user-created custom skill.

    • skill_id: string

      Tagged ID of the custom skill (e.g., "skill_01XJ5...").

    • type: "custom"

      • "custom"

    • version: optional string

      Version to pin. Defaults to latest if omitted.

Beta Managed Agents Custom Tool

  • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

    A custom tool as returned in API responses.

    • description: string

    • input_schema: BetaManagedAgentsCustomToolInputSchema

      JSON Schema for custom tool input parameters.

      • properties: optional map[unknown]

        JSON Schema properties defining the tool's input parameters.

      • required: optional array of string

        List of required property names.

      • type: optional "object"

        Must be 'object' for tool input schemas.

        • "object"

    • name: string

    • type: "custom"

      • "custom"

Beta Managed Agents Custom Tool Input Schema

  • BetaManagedAgentsCustomToolInputSchema object { properties, required, type }

    JSON Schema for custom tool input parameters.

    • properties: optional map[unknown]

      JSON Schema properties defining the tool's input parameters.

    • required: optional array of string

      List of required property names.

    • type: optional "object"

      Must be 'object' for tool input schemas.

      • "object"

Beta Managed Agents Custom Tool Params

  • BetaManagedAgentsCustomToolParams object { description, input_schema, name, type }

    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: optional map[unknown]

        JSON Schema properties defining the tool's input parameters.

      • required: optional array of string

        List of required property names.

      • type: optional "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 object { name, type, url }

    URL-based MCP server connection as returned in API responses.

    • name: string

    • type: "url"

      • "url"

    • url: string

Beta Managed Agents MCP Tool Config

  • BetaManagedAgentsMCPToolConfig object { enabled, name, permission_policy }

    Resolved configuration for a specific MCP tool.

    • enabled: boolean

    • name: string

    • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

      Permission policy for tool execution.

      • BetaManagedAgentsAlwaysAllowPolicy object { type }

        Tool calls are automatically approved without user confirmation.

        • type: "always_allow"

          • "always_allow"

      • BetaManagedAgentsAlwaysAskPolicy object { type }

        Tool calls require user confirmation before execution.

        • type: "always_ask"

          • "always_ask"

Beta Managed Agents MCP Tool Config Params

  • BetaManagedAgentsMCPToolConfigParams object { name, enabled, permission_policy }

    Configuration override for a specific MCP tool.

    • name: string

      Name of the MCP tool to configure. 1-128 characters.

    • enabled: optional boolean

      Whether this tool is enabled. Overrides the default_config setting.

    • permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

      Permission policy for tool execution.

      • BetaManagedAgentsAlwaysAllowPolicy object { type }

        Tool calls are automatically approved without user confirmation.

        • type: "always_allow"

          • "always_allow"

      • BetaManagedAgentsAlwaysAskPolicy object { type }

        Tool calls require user confirmation before execution.

        • type: "always_ask"

          • "always_ask"

Beta Managed Agents MCP Toolset

  • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

    • configs: array of BetaManagedAgentsMCPToolConfig

      • enabled: boolean

      • name: string

      • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

        Permission policy for tool execution.

        • BetaManagedAgentsAlwaysAllowPolicy object { type }

          Tool calls are automatically approved without user confirmation.

          • type: "always_allow"

            • "always_allow"

        • BetaManagedAgentsAlwaysAskPolicy object { type }

          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 or BetaManagedAgentsAlwaysAskPolicy

        Permission policy for tool execution.

        • BetaManagedAgentsAlwaysAllowPolicy object { type }

          Tool calls are automatically approved without user confirmation.

        • BetaManagedAgentsAlwaysAskPolicy object { type }

          Tool calls require user confirmation before execution.

    • mcp_server_name: string

    • type: "mcp_toolset"

      • "mcp_toolset"

Beta Managed Agents MCP Toolset Default Config

  • BetaManagedAgentsMCPToolsetDefaultConfig object { enabled, permission_policy }

    Resolved default configuration for all tools from an MCP server.

    • enabled: boolean

    • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

      Permission policy for tool execution.

      • BetaManagedAgentsAlwaysAllowPolicy object { type }

        Tool calls are automatically approved without user confirmation.

        • type: "always_allow"

          • "always_allow"

      • BetaManagedAgentsAlwaysAskPolicy object { type }

        Tool calls require user confirmation before execution.

        • type: "always_ask"

          • "always_ask"

Beta Managed Agents MCP Toolset Default Config Params

  • BetaManagedAgentsMCPToolsetDefaultConfigParams object { enabled, permission_policy }

    Default configuration for all tools from an MCP server.

    • enabled: optional boolean

      Whether tools are enabled by default. Defaults to true if not specified.

    • permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

      Permission policy for tool execution.

      • BetaManagedAgentsAlwaysAllowPolicy object { type }

        Tool calls are automatically approved without user confirmation.

        • type: "always_allow"

          • "always_allow"

      • BetaManagedAgentsAlwaysAskPolicy object { type }

        Tool calls require user confirmation before execution.

        • type: "always_ask"

          • "always_ask"

Beta Managed Agents MCP Toolset Params

  • BetaManagedAgentsMCPToolsetParams object { mcp_server_name, type, configs, default_config }

    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: optional array of BetaManagedAgentsMCPToolConfigParams

      Per-tool configuration overrides.

      • name: string

        Name of the MCP tool to configure. 1-128 characters.

      • enabled: optional boolean

        Whether this tool is enabled. Overrides the default_config setting.

      • permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

        Permission policy for tool execution.

        • BetaManagedAgentsAlwaysAllowPolicy object { type }

          Tool calls are automatically approved without user confirmation.

          • type: "always_allow"

            • "always_allow"

        • BetaManagedAgentsAlwaysAskPolicy object { type }

          Tool calls require user confirmation before execution.

          • type: "always_ask"

            • "always_ask"

    • default_config: optional BetaManagedAgentsMCPToolsetDefaultConfigParams

      Default configuration for all tools from an MCP server.

      • enabled: optional boolean

        Whether tools are enabled by default. Defaults to true if not specified.

      • permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

        Permission policy for tool execution.

        • BetaManagedAgentsAlwaysAllowPolicy object { type }

          Tool calls are automatically approved without user confirmation.

        • BetaManagedAgentsAlwaysAskPolicy object { type }

          Tool calls require user confirmation before execution.

Beta Managed Agents Model

  • BetaManagedAgentsModel = "claude-opus-4-7" or "claude-opus-4-6" or "claude-sonnet-4-6" or 6 more or string

    The model that will power your agent.

    See models for additional details and options.

    • "claude-opus-4-7" or "claude-opus-4-6" or "claude-sonnet-4-6" or 6 more

      The model that will power your agent.

      See models for additional details and options.

      • "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 object { id, speed }

    Model identifier and configuration.

    • id: BetaManagedAgentsModel

      The model that will power your agent.

      See models for additional details and options.

      • "claude-opus-4-7" or "claude-opus-4-6" or "claude-sonnet-4-6" or 6 more

        The model that will power your agent.

        See models for additional details and options.

        • "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: optional "standard" or "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 object { id, speed }

    An object that defines additional configuration control over model use

    • id: BetaManagedAgentsModel

      The model that will power your agent.

      See models for additional details and options.

      • "claude-opus-4-7" or "claude-opus-4-6" or "claude-sonnet-4-6" or 6 more

        The model that will power your agent.

        See models for additional details and options.

        • "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: optional "standard" or "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 Multiagent Coordinator

  • BetaManagedAgentsMultiagentCoordinator object { agents, type }

    Resolved coordinator topology with a concrete agent roster.

    • agents: array of BetaManagedAgentsAgentReference

      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 object { agents, type }

    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 of BetaManagedAgentsMultiagentRosterEntryParams

      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 object { id, type, version }

        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: optional number

          The specific agent version to use. Omit to use the latest version. Must be at least 1 if specified.

      • BetaManagedAgentsMultiagentSelfParams object { type }

        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 object { type }

    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 object { id, description, mcp_servers, 7 more }

    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

    • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

      • name: string

      • type: "url"

        • "url"

      • url: string

    • model: BetaManagedAgentsModelConfig

      Model identifier and configuration.

      • id: BetaManagedAgentsModel

        The model that will power your agent.

        See models for additional details and options.

        • "claude-opus-4-7" or "claude-opus-4-6" or "claude-sonnet-4-6" or 6 more

          The model that will power your agent.

          See models for additional details and options.

          • "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: optional "standard" or "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 of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

      • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

        A resolved Anthropic-managed skill.

        • skill_id: string

        • type: "anthropic"

          • "anthropic"

        • version: string

      • BetaManagedAgentsCustomSkill object { skill_id, type, version }

        A resolved user-created custom skill.

        • skill_id: string

        • type: "custom"

          • "custom"

        • version: string

    • system: string

    • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

      • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

        • configs: array of BetaManagedAgentsAgentToolConfig

          • enabled: boolean

          • name: "bash" or "edit" or "read" or 5 more

            Built-in agent tool identifier.

            • "bash"

            • "edit"

            • "read"

            • "write"

            • "glob"

            • "grep"

            • "web_fetch"

            • "web_search"

          • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

            Permission policy for tool execution.

            • BetaManagedAgentsAlwaysAllowPolicy object { type }

              Tool calls are automatically approved without user confirmation.

              • type: "always_allow"

                • "always_allow"

            • BetaManagedAgentsAlwaysAskPolicy object { type }

              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 or BetaManagedAgentsAlwaysAskPolicy

            Permission policy for tool execution.

            • BetaManagedAgentsAlwaysAllowPolicy object { type }

              Tool calls are automatically approved without user confirmation.

            • BetaManagedAgentsAlwaysAskPolicy object { type }

              Tool calls require user confirmation before execution.

        • type: "agent_toolset_20260401"

          • "agent_toolset_20260401"

      • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

        • configs: array of BetaManagedAgentsMCPToolConfig

          • enabled: boolean

          • name: string

          • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

            Permission policy for tool execution.

            • BetaManagedAgentsAlwaysAllowPolicy object { type }

              Tool calls are automatically approved without user confirmation.

            • BetaManagedAgentsAlwaysAskPolicy object { type }

              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 or BetaManagedAgentsAlwaysAskPolicy

            Permission policy for tool execution.

            • BetaManagedAgentsAlwaysAllowPolicy object { type }

              Tool calls are automatically approved without user confirmation.

            • BetaManagedAgentsAlwaysAskPolicy object { type }

              Tool calls require user confirmation before execution.

        • mcp_server_name: string

        • type: "mcp_toolset"

          • "mcp_toolset"

      • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

        A custom tool as returned in API responses.

        • description: string

        • input_schema: BetaManagedAgentsCustomToolInputSchema

          JSON Schema for custom tool input parameters.

          • properties: optional map[unknown]

            JSON Schema properties defining the tool's input parameters.

          • required: optional array of string

            List of required property names.

          • type: optional "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 or BetaManagedAgentsCustomSkillParams

    Skill to load in the session container.

    • BetaManagedAgentsAnthropicSkillParams object { skill_id, type, version }

      An Anthropic-managed skill.

      • skill_id: string

        Identifier of the Anthropic skill (e.g., "xlsx").

      • type: "anthropic"

        • "anthropic"

      • version: optional string

        Version to pin. Defaults to latest if omitted.

    • BetaManagedAgentsCustomSkillParams object { skill_id, type, version }

      A user-created custom skill.

      • skill_id: string

        Tagged ID of the custom skill (e.g., "skill_01XJ5...").

      • type: "custom"

        • "custom"

      • version: optional string

        Version to pin. Defaults to latest if omitted.

Beta Managed Agents URL MCP Server Params

  • BetaManagedAgentsURLMCPServerParams object { name, type, url }

    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

get /v1/agents/{agent_id}/versions

List Agent Versions

Path Parameters

  • agent_id: string

Query Parameters

  • limit: optional number

    Maximum results per page. Default 20, maximum 100.

  • page: optional string

    Opaque pagination cursor.

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Returns

  • data: optional array of BetaManagedAgentsAgent

    Agent versions.

    • id: string

    • archived_at: string

      A timestamp in RFC 3339 format

    • created_at: string

      A timestamp in RFC 3339 format

    • description: string

    • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

      • name: string

      • type: "url"

        • "url"

      • url: string

    • metadata: map[string]

    • model: BetaManagedAgentsModelConfig

      Model identifier and configuration.

      • id: BetaManagedAgentsModel

        The model that will power your agent.

        See models for additional details and options.

        • "claude-opus-4-7" or "claude-opus-4-6" or "claude-sonnet-4-6" or 6 more

          The model that will power your agent.

          See models for additional details and options.

          • "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: optional "standard" or "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

      Resolved coordinator topology with a concrete agent roster.

      • agents: array of BetaManagedAgentsAgentReference

        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 of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

      • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

        A resolved Anthropic-managed skill.

        • skill_id: string

        • type: "anthropic"

          • "anthropic"

        • version: string

      • BetaManagedAgentsCustomSkill object { skill_id, type, version }

        A resolved user-created custom skill.

        • skill_id: string

        • type: "custom"

          • "custom"

        • version: string

    • system: string

    • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

      • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

        • configs: array of BetaManagedAgentsAgentToolConfig

          • enabled: boolean

          • name: "bash" or "edit" or "read" or 5 more

            Built-in agent tool identifier.

            • "bash"

            • "edit"

            • "read"

            • "write"

            • "glob"

            • "grep"

            • "web_fetch"

            • "web_search"

          • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

            Permission policy for tool execution.

            • BetaManagedAgentsAlwaysAllowPolicy object { type }

              Tool calls are automatically approved without user confirmation.

              • type: "always_allow"

                • "always_allow"

            • BetaManagedAgentsAlwaysAskPolicy object { type }

              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 or BetaManagedAgentsAlwaysAskPolicy

            Permission policy for tool execution.

            • BetaManagedAgentsAlwaysAllowPolicy object { type }

              Tool calls are automatically approved without user confirmation.

            • BetaManagedAgentsAlwaysAskPolicy object { type }

              Tool calls require user confirmation before execution.

        • type: "agent_toolset_20260401"

          • "agent_toolset_20260401"

      • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

        • configs: array of BetaManagedAgentsMCPToolConfig

          • enabled: boolean

          • name: string

          • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

            Permission policy for tool execution.

            • BetaManagedAgentsAlwaysAllowPolicy object { type }

              Tool calls are automatically approved without user confirmation.

            • BetaManagedAgentsAlwaysAskPolicy object { type }

              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 or BetaManagedAgentsAlwaysAskPolicy

            Permission policy for tool execution.

            • BetaManagedAgentsAlwaysAllowPolicy object { type }

              Tool calls are automatically approved without user confirmation.

            • BetaManagedAgentsAlwaysAskPolicy object { type }

              Tool calls require user confirmation before execution.

        • mcp_server_name: string

        • type: "mcp_toolset"

          • "mcp_toolset"

      • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

        A custom tool as returned in API responses.

        • description: string

        • input_schema: BetaManagedAgentsCustomToolInputSchema

          JSON Schema for custom tool input parameters.

          • properties: optional map[unknown]

            JSON Schema properties defining the tool's input parameters.

          • required: optional array of string

            List of required property names.

          • type: optional "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.

  • next_page: optional string

    Opaque cursor for the next page. Null when no more results.

Example

curl https://api.anthropic.com/v1/agents/$AGENT_ID/versions \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: managed-agents-2026-04-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

Response

{
  "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

post /v1/environments

Create a new environment with the specified configuration.

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Body Parameters

  • name: string

    Human-readable name for the environment

  • config: optional BetaCloudConfigParams or BetaSelfHostedConfigParams

    Environment configuration

    • BetaCloudConfigParams object { type, networking, packages }

      Request params for cloud environment configuration.

      Fields default to null; on update, omitted fields preserve the existing value.

      • type: "cloud"

        Environment type

        • "cloud"

      • networking: optional BetaUnrestrictedNetwork or BetaLimitedNetworkParams

        Network configuration policy. Omit on update to preserve the existing value.

        • BetaUnrestrictedNetwork object { type }

          Unrestricted network access.

          • type: "unrestricted"

            Network policy type

            • "unrestricted"

        • BetaLimitedNetworkParams object { type, allow_mcp_servers, allow_package_managers, allowed_hosts }

          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: optional boolean

            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: optional boolean

            Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the allowed_hosts array. Defaults to false.

          • allowed_hosts: optional array of string

            Specifies domains the container can reach.

      • packages: optional 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: optional array of string

          Ubuntu/Debian packages to install

        • cargo: optional array of string

          Rust packages to install

        • gem: optional array of string

          Ruby packages to install

        • go: optional array of string

          Go packages to install

        • npm: optional array of string

          Node.js packages to install

        • pip: optional array of string

          Python packages to install

        • type: optional "packages"

          Package configuration type

          • "packages"

    • BetaSelfHostedConfigParams object { type }

      Request params for self_hosted environment configuration.

      • type: "self_hosted"

        Environment type

        • "self_hosted"

  • description: optional string

    Optional description of the environment

  • metadata: optional map[string]

    User-provided metadata key-value pairs

  • scope: optional "organization" or "account"

    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"

Returns

  • BetaEnvironment object { id, archived_at, config, 7 more }

    Unified Environment resource for both cloud and self-hosted environments.

    • id: string

      Environment identifier (e.g., 'env_...')

    • archived_at: string

      RFC 3339 timestamp when environment was archived, or null if not archived

    • config: BetaCloudConfig or BetaSelfHostedConfig

      Environment configuration (either Anthropic Cloud or self-hosted)

      • BetaCloudConfig object { networking, packages, type }

        cloud environment configuration.

        • networking: BetaUnrestrictedNetwork or BetaLimitedNetwork

          Network configuration policy.

          • BetaUnrestrictedNetwork object { type }

            Unrestricted network access.

            • type: "unrestricted"

              Network policy type

              • "unrestricted"

          • BetaLimitedNetwork object { allow_mcp_servers, allow_package_managers, allowed_hosts, type }

            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 of string

              Specifies domains the container can reach.

            • type: "limited"

              Network policy type

              • "limited"

        • packages: BetaPackages

          Package manager configuration.

          • apt: array of string

            Ubuntu/Debian packages to install

          • cargo: array of string

            Rust packages to install

          • gem: array of string

            Ruby packages to install

          • go: array of string

            Go packages to install

          • npm: array of string

            Node.js packages to install

          • pip: array of string

            Python packages to install

          • type: optional "packages"

            Package configuration type

            • "packages"

        • type: "cloud"

          Environment type

          • "cloud"

      • BetaSelfHostedConfig object { type }

        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: map[string]

      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: optional "organization" or "account"

      The visibility scope for this environment. 'organization' means visible to all accounts. 'account' means visible only to the owning account.

      • "organization"

      • "account"

Example

curl https://api.anthropic.com/v1/environments \
    -H 'Content-Type: application/json' \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: managed-agents-2026-04-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY" \
    -d '{
          "name": "python-data-analysis",
          "config": {
            "type": "cloud",
            "networking": {
              "type": "limited",
              "allow_package_managers": true,
              "allowed_hosts": [
                "api.example.com"
              ]
            },
            "packages": {
              "pip": [
                "pandas",
                "numpy"
              ]
            }
          },
          "description": "Python environment with data-analysis packages."
        }'

Response

{
  "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

get /v1/environments

List environments with pagination support.

Query Parameters

  • include_archived: optional boolean

    Include archived environments in the response

  • limit: optional number

    Maximum number of environments to return

  • page: optional string

    Opaque cursor from previous response for pagination. Pass the next_page value from the previous response.

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Returns

  • data: array of BetaEnvironment

    List of environments.

    • id: string

      Environment identifier (e.g., 'env_...')

    • archived_at: string

      RFC 3339 timestamp when environment was archived, or null if not archived

    • config: BetaCloudConfig or BetaSelfHostedConfig

      Environment configuration (either Anthropic Cloud or self-hosted)

      • BetaCloudConfig object { networking, packages, type }

        cloud environment configuration.

        • networking: BetaUnrestrictedNetwork or BetaLimitedNetwork

          Network configuration policy.

          • BetaUnrestrictedNetwork object { type }

            Unrestricted network access.

            • type: "unrestricted"

              Network policy type

              • "unrestricted"

          • BetaLimitedNetwork object { allow_mcp_servers, allow_package_managers, allowed_hosts, type }

            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 of string

              Specifies domains the container can reach.

            • type: "limited"

              Network policy type

              • "limited"

        • packages: BetaPackages

          Package manager configuration.

          • apt: array of string

            Ubuntu/Debian packages to install

          • cargo: array of string

            Rust packages to install

          • gem: array of string

            Ruby packages to install

          • go: array of string

            Go packages to install

          • npm: array of string

            Node.js packages to install

          • pip: array of string

            Python packages to install

          • type: optional "packages"

            Package configuration type

            • "packages"

        • type: "cloud"

          Environment type

          • "cloud"

      • BetaSelfHostedConfig object { type }

        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: map[string]

      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: optional "organization" or "account"

      The visibility scope for this environment. 'organization' means visible to all accounts. 'account' means visible only to the owning account.

      • "organization"

      • "account"

  • next_page: string

    Token for fetching the next page of results. If null, there are no more results available. Pass this value to the page parameter in the next request.

Example

curl https://api.anthropic.com/v1/environments \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: managed-agents-2026-04-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

Response

{
  "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

get /v1/environments/{environment_id}

Retrieve a specific environment by ID.

Path Parameters

  • environment_id: string

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Returns

  • BetaEnvironment object { id, archived_at, config, 7 more }

    Unified Environment resource for both cloud and self-hosted environments.

    • id: string

      Environment identifier (e.g., 'env_...')

    • archived_at: string

      RFC 3339 timestamp when environment was archived, or null if not archived

    • config: BetaCloudConfig or BetaSelfHostedConfig

      Environment configuration (either Anthropic Cloud or self-hosted)

      • BetaCloudConfig object { networking, packages, type }

        cloud environment configuration.

        • networking: BetaUnrestrictedNetwork or BetaLimitedNetwork

          Network configuration policy.

          • BetaUnrestrictedNetwork object { type }

            Unrestricted network access.

            • type: "unrestricted"

              Network policy type

              • "unrestricted"

          • BetaLimitedNetwork object { allow_mcp_servers, allow_package_managers, allowed_hosts, type }

            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 of string

              Specifies domains the container can reach.

            • type: "limited"

              Network policy type

              • "limited"

        • packages: BetaPackages

          Package manager configuration.

          • apt: array of string

            Ubuntu/Debian packages to install

          • cargo: array of string

            Rust packages to install

          • gem: array of string

            Ruby packages to install

          • go: array of string

            Go packages to install

          • npm: array of string

            Node.js packages to install

          • pip: array of string

            Python packages to install

          • type: optional "packages"

            Package configuration type

            • "packages"

        • type: "cloud"

          Environment type

          • "cloud"

      • BetaSelfHostedConfig object { type }

        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: map[string]

      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: optional "organization" or "account"

      The visibility scope for this environment. 'organization' means visible to all accounts. 'account' means visible only to the owning account.

      • "organization"

      • "account"

Example

curl https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: managed-agents-2026-04-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

Response

{
  "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

post /v1/environments/{environment_id}

Update an existing environment's configuration.

Path Parameters

  • environment_id: string

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Body Parameters

  • config: optional BetaCloudConfigParams or BetaSelfHostedConfigParams

    Updated environment configuration

    • BetaCloudConfigParams object { type, networking, packages }

      Request params for cloud environment configuration.

      Fields default to null; on update, omitted fields preserve the existing value.

      • type: "cloud"

        Environment type

        • "cloud"

      • networking: optional BetaUnrestrictedNetwork or BetaLimitedNetworkParams

        Network configuration policy. Omit on update to preserve the existing value.

        • BetaUnrestrictedNetwork object { type }

          Unrestricted network access.

          • type: "unrestricted"

            Network policy type

            • "unrestricted"

        • BetaLimitedNetworkParams object { type, allow_mcp_servers, allow_package_managers, allowed_hosts }

          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: optional boolean

            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: optional boolean

            Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the allowed_hosts array. Defaults to false.

          • allowed_hosts: optional array of string

            Specifies domains the container can reach.

      • packages: optional 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: optional array of string

          Ubuntu/Debian packages to install

        • cargo: optional array of string

          Rust packages to install

        • gem: optional array of string

          Ruby packages to install

        • go: optional array of string

          Go packages to install

        • npm: optional array of string

          Node.js packages to install

        • pip: optional array of string

          Python packages to install

        • type: optional "packages"

          Package configuration type

          • "packages"

    • BetaSelfHostedConfigParams object { type }

      Request params for self_hosted environment configuration.

      • type: "self_hosted"

        Environment type

        • "self_hosted"

  • description: optional string

    Updated description of the environment

  • metadata: optional map[string]

    User-provided metadata key-value pairs. Set a value to null or empty string to delete the key.

  • name: optional string

    Updated name for the environment

  • scope: optional "organization" or "account"

    The visibility scope for this environment. 'organization' makes the environment visible to all accounts. 'account' restricts visibility to the owning account only.

    • "organization"

    • "account"

Returns

  • BetaEnvironment object { id, archived_at, config, 7 more }

    Unified Environment resource for both cloud and self-hosted environments.

    • id: string

      Environment identifier (e.g., 'env_...')

    • archived_at: string

      RFC 3339 timestamp when environment was archived, or null if not archived

    • config: BetaCloudConfig or BetaSelfHostedConfig

      Environment configuration (either Anthropic Cloud or self-hosted)

      • BetaCloudConfig object { networking, packages, type }

        cloud environment configuration.

        • networking: BetaUnrestrictedNetwork or BetaLimitedNetwork

          Network configuration policy.

          • BetaUnrestrictedNetwork object { type }

            Unrestricted network access.

            • type: "unrestricted"

              Network policy type

              • "unrestricted"

          • BetaLimitedNetwork object { allow_mcp_servers, allow_package_managers, allowed_hosts, type }

            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 of string

              Specifies domains the container can reach.

            • type: "limited"

              Network policy type

              • "limited"

        • packages: BetaPackages

          Package manager configuration.

          • apt: array of string

            Ubuntu/Debian packages to install

          • cargo: array of string

            Rust packages to install

          • gem: array of string

            Ruby packages to install

          • go: array of string

            Go packages to install

          • npm: array of string

            Node.js packages to install

          • pip: array of string

            Python packages to install

          • type: optional "packages"

            Package configuration type

            • "packages"

        • type: "cloud"

          Environment type

          • "cloud"

      • BetaSelfHostedConfig object { type }

        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: map[string]

      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: optional "organization" or "account"

      The visibility scope for this environment. 'organization' means visible to all accounts. 'account' means visible only to the owning account.

      • "organization"

      • "account"

Example

curl https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID \
    -H 'Content-Type: application/json' \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: managed-agents-2026-04-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY" \
    -d '{
          "description": "Python environment with data-analysis packages."
        }'

Response

{
  "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

delete /v1/environments/{environment_id}

Delete an environment by ID. Returns a confirmation of the deletion.

Path Parameters

  • environment_id: string

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Returns

  • BetaEnvironmentDeleteResponse object { id, type }

    Response after deleting an environment.

    • id: string

      Environment identifier

    • type: "environment_deleted"

      The type of response

      • "environment_deleted"

Example

curl https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID \
    -X DELETE \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: managed-agents-2026-04-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

Response

{
  "id": "env_011CZkZ9X2dpNyB7HsEFoRfW",
  "type": "environment_deleted"
}

Archive Environment

post /v1/environments/{environment_id}/archive

Archive an environment by ID. Archived environments cannot be used to create new sessions.

Path Parameters

  • environment_id: string

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Returns

  • BetaEnvironment object { id, archived_at, config, 7 more }

    Unified Environment resource for both cloud and self-hosted environments.

    • id: string

      Environment identifier (e.g., 'env_...')

    • archived_at: string

      RFC 3339 timestamp when environment was archived, or null if not archived

    • config: BetaCloudConfig or BetaSelfHostedConfig

      Environment configuration (either Anthropic Cloud or self-hosted)

      • BetaCloudConfig object { networking, packages, type }

        cloud environment configuration.

        • networking: BetaUnrestrictedNetwork or BetaLimitedNetwork

          Network configuration policy.

          • BetaUnrestrictedNetwork object { type }

            Unrestricted network access.

            • type: "unrestricted"

              Network policy type

              • "unrestricted"

          • BetaLimitedNetwork object { allow_mcp_servers, allow_package_managers, allowed_hosts, type }

            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 of string

              Specifies domains the container can reach.

            • type: "limited"

              Network policy type

              • "limited"

        • packages: BetaPackages

          Package manager configuration.

          • apt: array of string

            Ubuntu/Debian packages to install

          • cargo: array of string

            Rust packages to install

          • gem: array of string

            Ruby packages to install

          • go: array of string

            Go packages to install

          • npm: array of string

            Node.js packages to install

          • pip: array of string

            Python packages to install

          • type: optional "packages"

            Package configuration type

            • "packages"

        • type: "cloud"

          Environment type

          • "cloud"

      • BetaSelfHostedConfig object { type }

        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: map[string]

      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: optional "organization" or "account"

      The visibility scope for this environment. 'organization' means visible to all accounts. 'account' means visible only to the owning account.

      • "organization"

      • "account"

Example

curl https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID/archive \
    -X POST \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: managed-agents-2026-04-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

Response

{
  "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 object { networking, packages, type }

    cloud environment configuration.

    • networking: BetaUnrestrictedNetwork or BetaLimitedNetwork

      Network configuration policy.

      • BetaUnrestrictedNetwork object { type }

        Unrestricted network access.

        • type: "unrestricted"

          Network policy type

          • "unrestricted"

      • BetaLimitedNetwork object { allow_mcp_servers, allow_package_managers, allowed_hosts, type }

        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 of string

          Specifies domains the container can reach.

        • type: "limited"

          Network policy type

          • "limited"

    • packages: BetaPackages

      Package manager configuration.

      • apt: array of string

        Ubuntu/Debian packages to install

      • cargo: array of string

        Rust packages to install

      • gem: array of string

        Ruby packages to install

      • go: array of string

        Go packages to install

      • npm: array of string

        Node.js packages to install

      • pip: array of string

        Python packages to install

      • type: optional "packages"

        Package configuration type

        • "packages"

    • type: "cloud"

      Environment type

      • "cloud"

Beta Cloud Config Params

  • BetaCloudConfigParams object { type, networking, packages }

    Request params for cloud environment configuration.

    Fields default to null; on update, omitted fields preserve the existing value.

    • type: "cloud"

      Environment type

      • "cloud"

    • networking: optional BetaUnrestrictedNetwork or BetaLimitedNetworkParams

      Network configuration policy. Omit on update to preserve the existing value.

      • BetaUnrestrictedNetwork object { type }

        Unrestricted network access.

        • type: "unrestricted"

          Network policy type

          • "unrestricted"

      • BetaLimitedNetworkParams object { type, allow_mcp_servers, allow_package_managers, allowed_hosts }

        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: optional boolean

          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: optional boolean

          Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the allowed_hosts array. Defaults to false.

        • allowed_hosts: optional array of string

          Specifies domains the container can reach.

    • packages: optional 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: optional array of string

        Ubuntu/Debian packages to install

      • cargo: optional array of string

        Rust packages to install

      • gem: optional array of string

        Ruby packages to install

      • go: optional array of string

        Go packages to install

      • npm: optional array of string

        Node.js packages to install

      • pip: optional array of string

        Python packages to install

      • type: optional "packages"

        Package configuration type

        • "packages"

Beta Environment

  • BetaEnvironment object { id, archived_at, config, 7 more }

    Unified Environment resource for both cloud and self-hosted environments.

    • id: string

      Environment identifier (e.g., 'env_...')

    • archived_at: string

      RFC 3339 timestamp when environment was archived, or null if not archived

    • config: BetaCloudConfig or BetaSelfHostedConfig

      Environment configuration (either Anthropic Cloud or self-hosted)

      • BetaCloudConfig object { networking, packages, type }

        cloud environment configuration.

        • networking: BetaUnrestrictedNetwork or BetaLimitedNetwork

          Network configuration policy.

          • BetaUnrestrictedNetwork object { type }

            Unrestricted network access.

            • type: "unrestricted"

              Network policy type

              • "unrestricted"

          • BetaLimitedNetwork object { allow_mcp_servers, allow_package_managers, allowed_hosts, type }

            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 of string

              Specifies domains the container can reach.

            • type: "limited"

              Network policy type

              • "limited"

        • packages: BetaPackages

          Package manager configuration.

          • apt: array of string

            Ubuntu/Debian packages to install

          • cargo: array of string

            Rust packages to install

          • gem: array of string

            Ruby packages to install

          • go: array of string

            Go packages to install

          • npm: array of string

            Node.js packages to install

          • pip: array of string

            Python packages to install

          • type: optional "packages"

            Package configuration type

            • "packages"

        • type: "cloud"

          Environment type

          • "cloud"

      • BetaSelfHostedConfig object { type }

        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: map[string]

      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: optional "organization" or "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 object { id, type }

    Response after deleting an environment.

    • id: string

      Environment identifier

    • type: "environment_deleted"

      The type of response

      • "environment_deleted"

Beta Limited Network

  • BetaLimitedNetwork object { allow_mcp_servers, allow_package_managers, allowed_hosts, type }

    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 of string

      Specifies domains the container can reach.

    • type: "limited"

      Network policy type

      • "limited"

Beta Limited Network Params

  • BetaLimitedNetworkParams object { type, allow_mcp_servers, allow_package_managers, allowed_hosts }

    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: optional boolean

      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: optional boolean

      Permits outbound access to public package registries (PyPI, npm, etc.) beyond those listed in the allowed_hosts array. Defaults to false.

    • allowed_hosts: optional array of string

      Specifies domains the container can reach.

Beta Packages

  • BetaPackages object { apt, cargo, gem, 4 more }

    Packages (and their versions) available in this environment.

    • apt: array of string

      Ubuntu/Debian packages to install

    • cargo: array of string

      Rust packages to install

    • gem: array of string

      Ruby packages to install

    • go: array of string

      Go packages to install

    • npm: array of string

      Node.js packages to install

    • pip: array of string

      Python packages to install

    • type: optional "packages"

      Package configuration type

      • "packages"

Beta Packages Params

  • BetaPackagesParams object { apt, cargo, gem, 4 more }

    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: optional array of string

      Ubuntu/Debian packages to install

    • cargo: optional array of string

      Rust packages to install

    • gem: optional array of string

      Ruby packages to install

    • go: optional array of string

      Go packages to install

    • npm: optional array of string

      Node.js packages to install

    • pip: optional array of string

      Python packages to install

    • type: optional "packages"

      Package configuration type

      • "packages"

Beta Self Hosted Config

  • BetaSelfHostedConfig object { type }

    Configuration for self-hosted environments.

    • type: "self_hosted"

      Environment type

      • "self_hosted"

Beta Self Hosted Config Params

  • BetaSelfHostedConfigParams object { type }

    Request params for self_hosted environment configuration.

    • type: "self_hosted"

      Environment type

      • "self_hosted"

Beta Unrestricted Network

  • BetaUnrestrictedNetwork object { type }

    Unrestricted network access.

    • type: "unrestricted"

      Network policy type

      • "unrestricted"

Work

Get Work Item

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.

Path Parameters

  • environment_id: string

  • work_id: string

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Returns

  • BetaSelfHostedWork object { id, acknowledged_at, created_at, 9 more }

    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

      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

      RFC 3339 timestamp of the most recent heartbeat

    • metadata: map[string]

      User-provided metadata key-value pairs associated with this work item

    • started_at: string

      RFC 3339 timestamp when work execution started

    • state: "queued" or "starting" or "active" or 2 more

      Current state of the work item

      • "queued"

      • "starting"

      • "active"

      • "stopping"

      • "stopped"

    • stop_requested_at: string

      RFC 3339 timestamp when stop was requested

    • stopped_at: string

      RFC 3339 timestamp when work execution stopped

    • type: "work"

      The type of object (always 'work')

      • "work"

Example

curl https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID/work/$WORK_ID \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: managed-agents-2026-04-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

Response

{
  "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

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.

Path Parameters

  • environment_id: string

Query Parameters

  • block_ms: optional number

    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: optional number

    Reclaim unacknowledged work items older than this many milliseconds. If omitted, uses the default (5000ms).

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

  • "Anthropic-Worker-ID": optional string

    Unique identifier for the specific worker polling, used to track aggregated environment-level work metrics in Console

Returns

  • BetaSelfHostedWork object { id, acknowledged_at, created_at, 9 more }

    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

      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

      RFC 3339 timestamp of the most recent heartbeat

    • metadata: map[string]

      User-provided metadata key-value pairs associated with this work item

    • started_at: string

      RFC 3339 timestamp when work execution started

    • state: "queued" or "starting" or "active" or 2 more

      Current state of the work item

      • "queued"

      • "starting"

      • "active"

      • "stopping"

      • "stopped"

    • stop_requested_at: string

      RFC 3339 timestamp when stop was requested

    • stopped_at: string

      RFC 3339 timestamp when work execution stopped

    • type: "work"

      The type of object (always 'work')

      • "work"

Example

curl https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID/work/poll \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: managed-agents-2026-04-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

Response

{
  "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

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.

Path Parameters

  • environment_id: string

  • work_id: string

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Returns

  • BetaSelfHostedWork object { id, acknowledged_at, created_at, 9 more }

    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

      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

      RFC 3339 timestamp of the most recent heartbeat

    • metadata: map[string]

      User-provided metadata key-value pairs associated with this work item

    • started_at: string

      RFC 3339 timestamp when work execution started

    • state: "queued" or "starting" or "active" or 2 more

      Current state of the work item

      • "queued"

      • "starting"

      • "active"

      • "stopping"

      • "stopped"

    • stop_requested_at: string

      RFC 3339 timestamp when stop was requested

    • stopped_at: string

      RFC 3339 timestamp when work execution stopped

    • type: "work"

      The type of object (always 'work')

      • "work"

Example

curl https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID/work/$WORK_ID/ack \
    -X POST \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: managed-agents-2026-04-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

Response

{
  "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

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.

Path Parameters

  • environment_id: string

  • work_id: string

Query Parameters

  • desired_ttl_seconds: optional number

    Desired TTL in seconds

  • expected_last_heartbeat: optional string

    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.

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Returns

  • BetaSelfHostedWorkHeartbeatResponse object { last_heartbeat, lease_extended, state, 2 more }

    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" or "starting" or "active" or 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

curl https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID/work/$WORK_ID/heartbeat \
    -X POST \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: managed-agents-2026-04-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

Response

{
  "last_heartbeat": "last_heartbeat",
  "lease_extended": true,
  "state": "queued",
  "ttl_seconds": 0,
  "type": "work_heartbeat"
}

Stop Work

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.

Path Parameters

  • environment_id: string

  • work_id: string

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Body Parameters

  • force: optional boolean

    If true, immediately stop work without graceful shutdown

Returns

  • BetaSelfHostedWork object { id, acknowledged_at, created_at, 9 more }

    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

      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

      RFC 3339 timestamp of the most recent heartbeat

    • metadata: map[string]

      User-provided metadata key-value pairs associated with this work item

    • started_at: string

      RFC 3339 timestamp when work execution started

    • state: "queued" or "starting" or "active" or 2 more

      Current state of the work item

      • "queued"

      • "starting"

      • "active"

      • "stopping"

      • "stopped"

    • stop_requested_at: string

      RFC 3339 timestamp when stop was requested

    • stopped_at: string

      RFC 3339 timestamp when work execution stopped

    • type: "work"

      The type of object (always 'work')

      • "work"

Example

curl https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID/work/$WORK_ID/stop \
    -H 'Content-Type: application/json' \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: managed-agents-2026-04-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY" \
    -d '{}'

Response

{
  "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

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.

Path Parameters

  • environment_id: string

Query Parameters

  • limit: optional number

    Maximum number of work items to return

  • page: optional string

    Opaque cursor from previous response for pagination

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Returns

  • BetaSelfHostedWorkListResponse object { data, next_page }

    Response when listing work items with cursor-based pagination.

    • data: array of BetaSelfHostedWork

      List of work items

      • id: string

        Work identifier (e.g., 'work_...')

      • acknowledged_at: string

        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

        RFC 3339 timestamp of the most recent heartbeat

      • metadata: map[string]

        User-provided metadata key-value pairs associated with this work item

      • started_at: string

        RFC 3339 timestamp when work execution started

      • state: "queued" or "starting" or "active" or 2 more

        Current state of the work item

        • "queued"

        • "starting"

        • "active"

        • "stopping"

        • "stopped"

      • stop_requested_at: string

        RFC 3339 timestamp when stop was requested

      • stopped_at: string

        RFC 3339 timestamp when work execution stopped

      • type: "work"

        The type of object (always 'work')

        • "work"

    • next_page: string

      Opaque cursor for fetching the next page of results

Example

curl https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID/work \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: managed-agents-2026-04-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

Response

{
  "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

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.

Path Parameters

  • environment_id: string

  • work_id: string

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Body Parameters

  • metadata: map[string]

    Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve existing metadata.

Returns

  • BetaSelfHostedWork object { id, acknowledged_at, created_at, 9 more }

    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

      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

      RFC 3339 timestamp of the most recent heartbeat

    • metadata: map[string]

      User-provided metadata key-value pairs associated with this work item

    • started_at: string

      RFC 3339 timestamp when work execution started

    • state: "queued" or "starting" or "active" or 2 more

      Current state of the work item

      • "queued"

      • "starting"

      • "active"

      • "stopping"

      • "stopped"

    • stop_requested_at: string

      RFC 3339 timestamp when stop was requested

    • stopped_at: string

      RFC 3339 timestamp when work execution stopped

    • type: "work"

      The type of object (always 'work')

      • "work"

Example

curl https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID/work/$WORK_ID \
    -H 'Content-Type: application/json' \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: managed-agents-2026-04-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY" \
    -d '{
          "metadata": {
            "foo": "string"
          }
        }'

Response

{
  "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

get /v1/environments/{environment_id}/work/stats

Get statistics about the work queue for an environment.

Path Parameters

  • environment_id: string

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Returns

  • BetaSelfHostedWorkQueueStats object { depth, oldest_queued_at, pending, 2 more }

    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

      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

      Number of workers that have polled for work in the last 30 seconds. Requires worker_id to be sent with poll requests.

Example

curl https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID/work/stats \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: managed-agents-2026-04-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

Response

{
  "depth": 0,
  "oldest_queued_at": "oldest_queued_at",
  "pending": 0,
  "type": "work_queue_stats",
  "workers_polling": 0
}

Domain Types

Beta Self Hosted Work

  • BetaSelfHostedWork object { id, acknowledged_at, created_at, 9 more }

    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

      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

      RFC 3339 timestamp of the most recent heartbeat

    • metadata: map[string]

      User-provided metadata key-value pairs associated with this work item

    • started_at: string

      RFC 3339 timestamp when work execution started

    • state: "queued" or "starting" or "active" or 2 more

      Current state of the work item

      • "queued"

      • "starting"

      • "active"

      • "stopping"

      • "stopped"

    • stop_requested_at: string

      RFC 3339 timestamp when stop was requested

    • stopped_at: string

      RFC 3339 timestamp when work execution stopped

    • type: "work"

      The type of object (always 'work')

      • "work"

Beta Self Hosted Work Heartbeat Response

  • BetaSelfHostedWorkHeartbeatResponse object { last_heartbeat, lease_extended, state, 2 more }

    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" or "starting" or "active" or 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 object { data, next_page }

    Response when listing work items with cursor-based pagination.

    • data: array of BetaSelfHostedWork

      List of work items

      • id: string

        Work identifier (e.g., 'work_...')

      • acknowledged_at: string

        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

        RFC 3339 timestamp of the most recent heartbeat

      • metadata: map[string]

        User-provided metadata key-value pairs associated with this work item

      • started_at: string

        RFC 3339 timestamp when work execution started

      • state: "queued" or "starting" or "active" or 2 more

        Current state of the work item

        • "queued"

        • "starting"

        • "active"

        • "stopping"

        • "stopped"

      • stop_requested_at: string

        RFC 3339 timestamp when stop was requested

      • stopped_at: string

        RFC 3339 timestamp when work execution stopped

      • type: "work"

        The type of object (always 'work')

        • "work"

    • next_page: string

      Opaque cursor for fetching the next page of results

Beta Self Hosted Work Queue Stats

  • BetaSelfHostedWorkQueueStats object { depth, oldest_queued_at, pending, 2 more }

    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

      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

      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 object { force }

    Request to stop a work item.

    • force: optional boolean

      If true, immediately stop work without graceful shutdown

Beta Self Hosted Work Update Request

  • BetaSelfHostedWorkUpdateRequest object { metadata }

    Request to update work item metadata.

    • metadata: map[string]

      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 object { id, type }

    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

post /v1/sessions

Create Session

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Body Parameters

  • agent: string or BetaManagedAgentsAgentParams

    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 object { id, type, version }

      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: optional number

        The specific agent version to use. Omit to use the latest version. Must be at least 1 if specified.

  • environment_id: string

    ID of the environment defining the container configuration for this session.

  • metadata: optional map[string]

    Arbitrary key-value metadata attached to the session. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars.

  • resources: optional array of BetaManagedAgentsGitHubRepositoryResourceParams or BetaManagedAgentsFileResourceParams or BetaManagedAgentsMemoryStoreResourceParam

    Resources (e.g. repositories, files) to mount into the session's container.

    • BetaManagedAgentsGitHubRepositoryResourceParams object { authorization_token, type, url, 2 more }

      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: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout

        Branch or commit to check out. Defaults to the repository's default branch.

        • BetaManagedAgentsBranchCheckout object { name, type }

          • name: string

            Branch name to check out.

          • type: "branch"

            • "branch"

        • BetaManagedAgentsCommitCheckout object { sha, type }

          • sha: string

            Full commit SHA to check out.

          • type: "commit"

            • "commit"

      • mount_path: optional string

        Mount path in the container. Defaults to /workspace/<repo-name>.

    • BetaManagedAgentsFileResourceParams object { file_id, type, mount_path }

      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: optional string

        Mount path in the container. Defaults to /mnt/session/uploads/<file_id>.

    • BetaManagedAgentsMemoryStoreResourceParam object { memory_store_id, type, access, instructions }

      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: optional "read_write" or "read_only"

        Access mode for an attached memory store.

        • "read_write"

        • "read_only"

      • instructions: optional string

        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: optional string

    Human-readable session title.

  • vault_ids: optional array of string

    Vault IDs for stored credentials the agent can use during the session.

Returns

  • BetaManagedAgentsSession object { id, agent, archived_at, 12 more }

    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

      • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

        • name: string

        • type: "url"

          • "url"

        • url: string

      • model: BetaManagedAgentsModelConfig

        Model identifier and configuration.

        • id: BetaManagedAgentsModel

          The model that will power your agent.

          See models for additional details and options.

          • "claude-opus-4-7" or "claude-opus-4-6" or "claude-sonnet-4-6" or 6 more

            The model that will power your agent.

            See models for additional details and options.

            • "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: optional "standard" or "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

        Resolved coordinator topology with full agent definitions for each roster member.

        • agents: array of BetaManagedAgentsSessionThreadAgent

          Full agent definitions the coordinator may spawn as session threads.

          • id: string

          • description: string

          • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

            • name: string

            • type: "url"

            • url: string

          • model: BetaManagedAgentsModelConfig

            Model identifier and configuration.

          • name: string

          • skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

            • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

              A resolved Anthropic-managed skill.

              • skill_id: string

              • type: "anthropic"

                • "anthropic"

              • version: string

            • BetaManagedAgentsCustomSkill object { skill_id, type, version }

              A resolved user-created custom skill.

              • skill_id: string

              • type: "custom"

                • "custom"

              • version: string

          • system: string

          • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

            • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

              • configs: array of BetaManagedAgentsAgentToolConfig

                • enabled: boolean

                • name: "bash" or "edit" or "read" or 5 more

                  Built-in agent tool identifier.

                  • "bash"

                  • "edit"

                  • "read"

                  • "write"

                  • "glob"

                  • "grep"

                  • "web_fetch"

                  • "web_search"

                • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                  Permission policy for tool execution.

                  • BetaManagedAgentsAlwaysAllowPolicy object { type }

                    Tool calls are automatically approved without user confirmation.

                    • type: "always_allow"

                      • "always_allow"

                  • BetaManagedAgentsAlwaysAskPolicy object { type }

                    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 or BetaManagedAgentsAlwaysAskPolicy

                  Permission policy for tool execution.

                  • BetaManagedAgentsAlwaysAllowPolicy object { type }

                    Tool calls are automatically approved without user confirmation.

                  • BetaManagedAgentsAlwaysAskPolicy object { type }

                    Tool calls require user confirmation before execution.

              • type: "agent_toolset_20260401"

                • "agent_toolset_20260401"

            • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

              • configs: array of BetaManagedAgentsMCPToolConfig

                • enabled: boolean

                • name: string

                • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                  Permission policy for tool execution.

                  • BetaManagedAgentsAlwaysAllowPolicy object { type }

                    Tool calls are automatically approved without user confirmation.

                  • BetaManagedAgentsAlwaysAskPolicy object { type }

                    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 or BetaManagedAgentsAlwaysAskPolicy

                  Permission policy for tool execution.

                  • BetaManagedAgentsAlwaysAllowPolicy object { type }

                    Tool calls are automatically approved without user confirmation.

                  • BetaManagedAgentsAlwaysAskPolicy object { type }

                    Tool calls require user confirmation before execution.

              • mcp_server_name: string

              • type: "mcp_toolset"

                • "mcp_toolset"

            • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

              A custom tool as returned in API responses.

              • description: string

              • input_schema: BetaManagedAgentsCustomToolInputSchema

                JSON Schema for custom tool input parameters.

                • properties: optional map[unknown]

                  JSON Schema properties defining the tool's input parameters.

                • required: optional array of string

                  List of required property names.

                • type: optional "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 of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

        • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

          A resolved Anthropic-managed skill.

        • BetaManagedAgentsCustomSkill object { skill_id, type, version }

          A resolved user-created custom skill.

      • system: string

      • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

        • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

        • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

        • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

          A custom tool as returned in API responses.

      • type: "agent"

        • "agent"

      • version: number

    • archived_at: string

      A timestamp in RFC 3339 format

    • created_at: string

      A timestamp in RFC 3339 format

    • environment_id: string

    • metadata: map[string]

    • outcome_evaluations: array of BetaManagedAgentsOutcomeEvaluationResource

      Per-outcome evaluation state. One entry per define_outcome event sent to the session.

      • completed_at: string

        A timestamp in RFC 3339 format

      • description: string

        What the agent should produce.

      • explanation: string

        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 of BetaManagedAgentsSessionResource

      • BetaManagedAgentsGitHubRepositoryResource object { id, created_at, mount_path, 4 more }

        • 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: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout

          • BetaManagedAgentsBranchCheckout object { name, type }

            • name: string

              Branch name to check out.

            • type: "branch"

              • "branch"

          • BetaManagedAgentsCommitCheckout object { sha, type }

            • sha: string

              Full commit SHA to check out.

            • type: "commit"

              • "commit"

      • BetaManagedAgentsFileResource object { id, created_at, file_id, 3 more }

        • 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 object { memory_store_id, type, access, 4 more }

        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: optional "read_write" or "read_only"

          Access mode for an attached memory store.

          • "read_write"

          • "read_only"

        • description: optional 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: optional string

          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: optional string

          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: optional string

          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: optional number

        Cumulative time in seconds the session spent in running status. Excludes idle time.

      • duration_seconds: optional number

        Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update.

    • status: "rescheduling" or "running" or "idle" or "terminated"

      SessionStatus enum

      • "rescheduling"

      • "running"

      • "idle"

      • "terminated"

    • title: string

    • 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: optional BetaManagedAgentsCacheCreationUsage

        Prompt-cache creation token usage broken down by cache lifetime.

        • ephemeral_1h_input_tokens: optional number

          Tokens used to create 1-hour ephemeral cache entries.

        • ephemeral_5m_input_tokens: optional number

          Tokens used to create 5-minute ephemeral cache entries.

      • cache_read_input_tokens: optional number

        Total tokens read from prompt cache.

      • input_tokens: optional number

        Total input tokens consumed across all turns.

      • output_tokens: optional number

        Total output tokens generated across all turns.

    • vault_ids: array of string

      Vault IDs attached to the session at creation. Empty when no vaults were supplied.

Example

curl https://api.anthropic.com/v1/sessions \
    -H 'Content-Type: application/json' \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: managed-agents-2026-04-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY" \
    -d '{
          "agent": "agent_011CZkYpogX7uDKUyvBTophP",
          "environment_id": "env_011CZkZ9X2dpNyB7HsEFoRfW",
          "title": "Order #1234 inquiry"
        }'

Response

{
  "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

get /v1/sessions

List Sessions

Query Parameters

  • agent_id: optional string

    Filter sessions created with this agent ID.

  • agent_version: optional number

    Filter by agent version. Only applies when agent_id is also set.

  • "created_at[gt]": optional string

    Return sessions created after this time (exclusive).

  • "created_at[gte]": optional string

    Return sessions created at or after this time (inclusive).

  • "created_at[lt]": optional string

    Return sessions created before this time (exclusive).

  • "created_at[lte]": optional string

    Return sessions created at or before this time (inclusive).

  • include_archived: optional boolean

    When true, includes archived sessions. Default: false (exclude archived).

  • limit: optional number

    Maximum number of results to return.

  • memory_store_id: optional string

    Filter sessions whose resources contain a memory_store with this memory store ID.

  • order: optional "asc" or "desc"

    Sort direction for results, ordered by created_at. Defaults to desc (newest first).

    • "asc"

    • "desc"

  • page: optional string

    Opaque pagination cursor from a previous response's next_page.

  • statuses: optional array of "rescheduling" or "running" or "idle" or "terminated"

    Filter by session status. Repeat the parameter to match any of multiple statuses.

    • "rescheduling"

    • "running"

    • "idle"

    • "terminated"

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Returns

  • data: optional array of BetaManagedAgentsSession

    List of sessions.

    • id: string

    • agent: BetaManagedAgentsSessionAgent

      Resolved agent definition for a session. Snapshot of the agent at session creation time.

      • id: string

      • description: string

      • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

        • name: string

        • type: "url"

          • "url"

        • url: string

      • model: BetaManagedAgentsModelConfig

        Model identifier and configuration.

        • id: BetaManagedAgentsModel

          The model that will power your agent.

          See models for additional details and options.

          • "claude-opus-4-7" or "claude-opus-4-6" or "claude-sonnet-4-6" or 6 more

            The model that will power your agent.

            See models for additional details and options.

            • "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: optional "standard" or "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

        Resolved coordinator topology with full agent definitions for each roster member.

        • agents: array of BetaManagedAgentsSessionThreadAgent

          Full agent definitions the coordinator may spawn as session threads.

          • id: string

          • description: string

          • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

            • name: string

            • type: "url"

            • url: string

          • model: BetaManagedAgentsModelConfig

            Model identifier and configuration.

          • name: string

          • skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

            • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

              A resolved Anthropic-managed skill.

              • skill_id: string

              • type: "anthropic"

                • "anthropic"

              • version: string

            • BetaManagedAgentsCustomSkill object { skill_id, type, version }

              A resolved user-created custom skill.

              • skill_id: string

              • type: "custom"

                • "custom"

              • version: string

          • system: string

          • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

            • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

              • configs: array of BetaManagedAgentsAgentToolConfig

                • enabled: boolean

                • name: "bash" or "edit" or "read" or 5 more

                  Built-in agent tool identifier.

                  • "bash"

                  • "edit"

                  • "read"

                  • "write"

                  • "glob"

                  • "grep"

                  • "web_fetch"

                  • "web_search"

                • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                  Permission policy for tool execution.

                  • BetaManagedAgentsAlwaysAllowPolicy object { type }

                    Tool calls are automatically approved without user confirmation.

                    • type: "always_allow"

                      • "always_allow"

                  • BetaManagedAgentsAlwaysAskPolicy object { type }

                    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 or BetaManagedAgentsAlwaysAskPolicy

                  Permission policy for tool execution.

                  • BetaManagedAgentsAlwaysAllowPolicy object { type }

                    Tool calls are automatically approved without user confirmation.

                  • BetaManagedAgentsAlwaysAskPolicy object { type }

                    Tool calls require user confirmation before execution.

              • type: "agent_toolset_20260401"

                • "agent_toolset_20260401"

            • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

              • configs: array of BetaManagedAgentsMCPToolConfig

                • enabled: boolean

                • name: string

                • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                  Permission policy for tool execution.

                  • BetaManagedAgentsAlwaysAllowPolicy object { type }

                    Tool calls are automatically approved without user confirmation.

                  • BetaManagedAgentsAlwaysAskPolicy object { type }

                    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 or BetaManagedAgentsAlwaysAskPolicy

                  Permission policy for tool execution.

                  • BetaManagedAgentsAlwaysAllowPolicy object { type }

                    Tool calls are automatically approved without user confirmation.

                  • BetaManagedAgentsAlwaysAskPolicy object { type }

                    Tool calls require user confirmation before execution.

              • mcp_server_name: string

              • type: "mcp_toolset"

                • "mcp_toolset"

            • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

              A custom tool as returned in API responses.

              • description: string

              • input_schema: BetaManagedAgentsCustomToolInputSchema

                JSON Schema for custom tool input parameters.

                • properties: optional map[unknown]

                  JSON Schema properties defining the tool's input parameters.

                • required: optional array of string

                  List of required property names.

                • type: optional "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 of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

        • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

          A resolved Anthropic-managed skill.

        • BetaManagedAgentsCustomSkill object { skill_id, type, version }

          A resolved user-created custom skill.

      • system: string

      • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

        • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

        • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

        • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

          A custom tool as returned in API responses.

      • type: "agent"

        • "agent"

      • version: number

    • archived_at: string

      A timestamp in RFC 3339 format

    • created_at: string

      A timestamp in RFC 3339 format

    • environment_id: string

    • metadata: map[string]

    • outcome_evaluations: array of BetaManagedAgentsOutcomeEvaluationResource

      Per-outcome evaluation state. One entry per define_outcome event sent to the session.

      • completed_at: string

        A timestamp in RFC 3339 format

      • description: string

        What the agent should produce.

      • explanation: string

        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 of BetaManagedAgentsSessionResource

      • BetaManagedAgentsGitHubRepositoryResource object { id, created_at, mount_path, 4 more }

        • 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: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout

          • BetaManagedAgentsBranchCheckout object { name, type }

            • name: string

              Branch name to check out.

            • type: "branch"

              • "branch"

          • BetaManagedAgentsCommitCheckout object { sha, type }

            • sha: string

              Full commit SHA to check out.

            • type: "commit"

              • "commit"

      • BetaManagedAgentsFileResource object { id, created_at, file_id, 3 more }

        • 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 object { memory_store_id, type, access, 4 more }

        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: optional "read_write" or "read_only"

          Access mode for an attached memory store.

          • "read_write"

          • "read_only"

        • description: optional 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: optional string

          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: optional string

          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: optional string

          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: optional number

        Cumulative time in seconds the session spent in running status. Excludes idle time.

      • duration_seconds: optional number

        Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update.

    • status: "rescheduling" or "running" or "idle" or "terminated"

      SessionStatus enum

      • "rescheduling"

      • "running"

      • "idle"

      • "terminated"

    • title: string

    • 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: optional BetaManagedAgentsCacheCreationUsage

        Prompt-cache creation token usage broken down by cache lifetime.

        • ephemeral_1h_input_tokens: optional number

          Tokens used to create 1-hour ephemeral cache entries.

        • ephemeral_5m_input_tokens: optional number

          Tokens used to create 5-minute ephemeral cache entries.

      • cache_read_input_tokens: optional number

        Total tokens read from prompt cache.

      • input_tokens: optional number

        Total input tokens consumed across all turns.

      • output_tokens: optional number

        Total output tokens generated across all turns.

    • vault_ids: array of string

      Vault IDs attached to the session at creation. Empty when no vaults were supplied.

  • next_page: optional string

    Opaque cursor for the next page. Null when no more results.

Example

curl https://api.anthropic.com/v1/sessions \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: managed-agents-2026-04-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

Response

{
  "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

get /v1/sessions/{session_id}

Get Session

Path Parameters

  • session_id: string

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Returns

  • BetaManagedAgentsSession object { id, agent, archived_at, 12 more }

    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

      • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

        • name: string

        • type: "url"

          • "url"

        • url: string

      • model: BetaManagedAgentsModelConfig

        Model identifier and configuration.

        • id: BetaManagedAgentsModel

          The model that will power your agent.

          See models for additional details and options.

          • "claude-opus-4-7" or "claude-opus-4-6" or "claude-sonnet-4-6" or 6 more

            The model that will power your agent.

            See models for additional details and options.

            • "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: optional "standard" or "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

        Resolved coordinator topology with full agent definitions for each roster member.

        • agents: array of BetaManagedAgentsSessionThreadAgent

          Full agent definitions the coordinator may spawn as session threads.

          • id: string

          • description: string

          • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

            • name: string

            • type: "url"

            • url: string

          • model: BetaManagedAgentsModelConfig

            Model identifier and configuration.

          • name: string

          • skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

            • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

              A resolved Anthropic-managed skill.

              • skill_id: string

              • type: "anthropic"

                • "anthropic"

              • version: string

            • BetaManagedAgentsCustomSkill object { skill_id, type, version }

              A resolved user-created custom skill.

              • skill_id: string

              • type: "custom"

                • "custom"

              • version: string

          • system: string

          • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

            • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

              • configs: array of BetaManagedAgentsAgentToolConfig

                • enabled: boolean

                • name: "bash" or "edit" or "read" or 5 more

                  Built-in agent tool identifier.

                  • "bash"

                  • "edit"

                  • "read"

                  • "write"

                  • "glob"

                  • "grep"

                  • "web_fetch"

                  • "web_search"

                • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                  Permission policy for tool execution.

                  • BetaManagedAgentsAlwaysAllowPolicy object { type }

                    Tool calls are automatically approved without user confirmation.

                    • type: "always_allow"

                      • "always_allow"

                  • BetaManagedAgentsAlwaysAskPolicy object { type }

                    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 or BetaManagedAgentsAlwaysAskPolicy

                  Permission policy for tool execution.

                  • BetaManagedAgentsAlwaysAllowPolicy object { type }

                    Tool calls are automatically approved without user confirmation.

                  • BetaManagedAgentsAlwaysAskPolicy object { type }

                    Tool calls require user confirmation before execution.

              • type: "agent_toolset_20260401"

                • "agent_toolset_20260401"

            • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

              • configs: array of BetaManagedAgentsMCPToolConfig

                • enabled: boolean

                • name: string

                • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                  Permission policy for tool execution.

                  • BetaManagedAgentsAlwaysAllowPolicy object { type }

                    Tool calls are automatically approved without user confirmation.

                  • BetaManagedAgentsAlwaysAskPolicy object { type }

                    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 or BetaManagedAgentsAlwaysAskPolicy

                  Permission policy for tool execution.

                  • BetaManagedAgentsAlwaysAllowPolicy object { type }

                    Tool calls are automatically approved without user confirmation.

                  • BetaManagedAgentsAlwaysAskPolicy object { type }

                    Tool calls require user confirmation before execution.

              • mcp_server_name: string

              • type: "mcp_toolset"

                • "mcp_toolset"

            • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

              A custom tool as returned in API responses.

              • description: string

              • input_schema: BetaManagedAgentsCustomToolInputSchema

                JSON Schema for custom tool input parameters.

                • properties: optional map[unknown]

                  JSON Schema properties defining the tool's input parameters.

                • required: optional array of string

                  List of required property names.

                • type: optional "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 of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

        • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

          A resolved Anthropic-managed skill.

        • BetaManagedAgentsCustomSkill object { skill_id, type, version }

          A resolved user-created custom skill.

      • system: string

      • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

        • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

        • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

        • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

          A custom tool as returned in API responses.

      • type: "agent"

        • "agent"

      • version: number

    • archived_at: string

      A timestamp in RFC 3339 format

    • created_at: string

      A timestamp in RFC 3339 format

    • environment_id: string

    • metadata: map[string]

    • outcome_evaluations: array of BetaManagedAgentsOutcomeEvaluationResource

      Per-outcome evaluation state. One entry per define_outcome event sent to the session.

      • completed_at: string

        A timestamp in RFC 3339 format

      • description: string

        What the agent should produce.

      • explanation: string

        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 of BetaManagedAgentsSessionResource

      • BetaManagedAgentsGitHubRepositoryResource object { id, created_at, mount_path, 4 more }

        • 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: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout

          • BetaManagedAgentsBranchCheckout object { name, type }

            • name: string

              Branch name to check out.

            • type: "branch"

              • "branch"

          • BetaManagedAgentsCommitCheckout object { sha, type }

            • sha: string

              Full commit SHA to check out.

            • type: "commit"

              • "commit"

      • BetaManagedAgentsFileResource object { id, created_at, file_id, 3 more }

        • 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 object { memory_store_id, type, access, 4 more }

        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: optional "read_write" or "read_only"

          Access mode for an attached memory store.

          • "read_write"

          • "read_only"

        • description: optional 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: optional string

          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: optional string

          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: optional string

          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: optional number

        Cumulative time in seconds the session spent in running status. Excludes idle time.

      • duration_seconds: optional number

        Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update.

    • status: "rescheduling" or "running" or "idle" or "terminated"

      SessionStatus enum

      • "rescheduling"

      • "running"

      • "idle"

      • "terminated"

    • title: string

    • 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: optional BetaManagedAgentsCacheCreationUsage

        Prompt-cache creation token usage broken down by cache lifetime.

        • ephemeral_1h_input_tokens: optional number

          Tokens used to create 1-hour ephemeral cache entries.

        • ephemeral_5m_input_tokens: optional number

          Tokens used to create 5-minute ephemeral cache entries.

      • cache_read_input_tokens: optional number

        Total tokens read from prompt cache.

      • input_tokens: optional number

        Total input tokens consumed across all turns.

      • output_tokens: optional number

        Total output tokens generated across all turns.

    • vault_ids: array of string

      Vault IDs attached to the session at creation. Empty when no vaults were supplied.

Example

curl https://api.anthropic.com/v1/sessions/$SESSION_ID \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: managed-agents-2026-04-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

Response

{
  "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

post /v1/sessions/{session_id}

Update Session

Path Parameters

  • session_id: string

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Body Parameters

  • agent: optional 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: optional array of BetaManagedAgentsURLMCPServerParams

      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: optional array of BetaManagedAgentsAgentToolset20260401Params or BetaManagedAgentsMCPToolsetParams or BetaManagedAgentsCustomToolParams

      Replacement tool list. Full replacement: the provided array becomes the new value. Send an empty array to clear; omit to preserve.

      • BetaManagedAgentsAgentToolset20260401Params object { type, configs, default_config }

        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: optional array of BetaManagedAgentsAgentToolConfigParams

          Per-tool configuration overrides.

          • name: "bash" or "edit" or "read" or 5 more

            Built-in agent tool identifier.

            • "bash"

            • "edit"

            • "read"

            • "write"

            • "glob"

            • "grep"

            • "web_fetch"

            • "web_search"

          • enabled: optional boolean

            Whether this tool is enabled and available to Claude. Overrides the default_config setting.

          • permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

            Permission policy for tool execution.

            • BetaManagedAgentsAlwaysAllowPolicy object { type }

              Tool calls are automatically approved without user confirmation.

              • type: "always_allow"

                • "always_allow"

            • BetaManagedAgentsAlwaysAskPolicy object { type }

              Tool calls require user confirmation before execution.

              • type: "always_ask"

                • "always_ask"

        • default_config: optional BetaManagedAgentsAgentToolsetDefaultConfigParams

          Default configuration for all tools in a toolset.

          • enabled: optional boolean

            Whether tools are enabled and available to Claude by default. Defaults to true if not specified.

          • permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

            Permission policy for tool execution.

            • BetaManagedAgentsAlwaysAllowPolicy object { type }

              Tool calls are automatically approved without user confirmation.

            • BetaManagedAgentsAlwaysAskPolicy object { type }

              Tool calls require user confirmation before execution.

      • BetaManagedAgentsMCPToolsetParams object { mcp_server_name, type, configs, default_config }

        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: optional array of BetaManagedAgentsMCPToolConfigParams

          Per-tool configuration overrides.

          • name: string

            Name of the MCP tool to configure. 1-128 characters.

          • enabled: optional boolean

            Whether this tool is enabled. Overrides the default_config setting.

          • permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

            Permission policy for tool execution.

            • BetaManagedAgentsAlwaysAllowPolicy object { type }

              Tool calls are automatically approved without user confirmation.

            • BetaManagedAgentsAlwaysAskPolicy object { type }

              Tool calls require user confirmation before execution.

        • default_config: optional BetaManagedAgentsMCPToolsetDefaultConfigParams

          Default configuration for all tools from an MCP server.

          • enabled: optional boolean

            Whether tools are enabled by default. Defaults to true if not specified.

          • permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

            Permission policy for tool execution.

            • BetaManagedAgentsAlwaysAllowPolicy object { type }

              Tool calls are automatically approved without user confirmation.

            • BetaManagedAgentsAlwaysAskPolicy object { type }

              Tool calls require user confirmation before execution.

      • BetaManagedAgentsCustomToolParams object { description, input_schema, name, type }

        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: optional map[unknown]

            JSON Schema properties defining the tool's input parameters.

          • required: optional array of string

            List of required property names.

          • type: optional "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: optional map[string]

    Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve.

  • title: optional string

    Human-readable session title.

  • vault_ids: optional array of string

    Vault IDs (vlt_*) to attach to the session. Not yet supported; requests setting this field are rejected. Reserved for future use.

Returns

  • BetaManagedAgentsSession object { id, agent, archived_at, 12 more }

    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

      • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

        • name: string

        • type: "url"

          • "url"

        • url: string

      • model: BetaManagedAgentsModelConfig

        Model identifier and configuration.

        • id: BetaManagedAgentsModel

          The model that will power your agent.

          See models for additional details and options.

          • "claude-opus-4-7" or "claude-opus-4-6" or "claude-sonnet-4-6" or 6 more

            The model that will power your agent.

            See models for additional details and options.

            • "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: optional "standard" or "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

        Resolved coordinator topology with full agent definitions for each roster member.

        • agents: array of BetaManagedAgentsSessionThreadAgent

          Full agent definitions the coordinator may spawn as session threads.

          • id: string

          • description: string

          • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

            • name: string

            • type: "url"

            • url: string

          • model: BetaManagedAgentsModelConfig

            Model identifier and configuration.

          • name: string

          • skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

            • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

              A resolved Anthropic-managed skill.

              • skill_id: string

              • type: "anthropic"

                • "anthropic"

              • version: string

            • BetaManagedAgentsCustomSkill object { skill_id, type, version }

              A resolved user-created custom skill.

              • skill_id: string

              • type: "custom"

                • "custom"

              • version: string

          • system: string

          • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

            • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

              • configs: array of BetaManagedAgentsAgentToolConfig

                • enabled: boolean

                • name: "bash" or "edit" or "read" or 5 more

                  Built-in agent tool identifier.

                  • "bash"

                  • "edit"

                  • "read"

                  • "write"

                  • "glob"

                  • "grep"

                  • "web_fetch"

                  • "web_search"

                • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                  Permission policy for tool execution.

                  • BetaManagedAgentsAlwaysAllowPolicy object { type }

                    Tool calls are automatically approved without user confirmation.

                    • type: "always_allow"

                      • "always_allow"

                  • BetaManagedAgentsAlwaysAskPolicy object { type }

                    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 or BetaManagedAgentsAlwaysAskPolicy

                  Permission policy for tool execution.

                  • BetaManagedAgentsAlwaysAllowPolicy object { type }

                    Tool calls are automatically approved without user confirmation.

                  • BetaManagedAgentsAlwaysAskPolicy object { type }

                    Tool calls require user confirmation before execution.

              • type: "agent_toolset_20260401"

                • "agent_toolset_20260401"

            • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

              • configs: array of BetaManagedAgentsMCPToolConfig

                • enabled: boolean

                • name: string

                • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                  Permission policy for tool execution.

                  • BetaManagedAgentsAlwaysAllowPolicy object { type }

                    Tool calls are automatically approved without user confirmation.

                  • BetaManagedAgentsAlwaysAskPolicy object { type }

                    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 or BetaManagedAgentsAlwaysAskPolicy

                  Permission policy for tool execution.

                  • BetaManagedAgentsAlwaysAllowPolicy object { type }

                    Tool calls are automatically approved without user confirmation.

                  • BetaManagedAgentsAlwaysAskPolicy object { type }

                    Tool calls require user confirmation before execution.

              • mcp_server_name: string

              • type: "mcp_toolset"

                • "mcp_toolset"

            • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

              A custom tool as returned in API responses.

              • description: string

              • input_schema: BetaManagedAgentsCustomToolInputSchema

                JSON Schema for custom tool input parameters.

                • properties: optional map[unknown]

                  JSON Schema properties defining the tool's input parameters.

                • required: optional array of string

                  List of required property names.

                • type: optional "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 of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

        • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

          A resolved Anthropic-managed skill.

        • BetaManagedAgentsCustomSkill object { skill_id, type, version }

          A resolved user-created custom skill.

      • system: string

      • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

        • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

        • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

        • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

          A custom tool as returned in API responses.

      • type: "agent"

        • "agent"

      • version: number

    • archived_at: string

      A timestamp in RFC 3339 format

    • created_at: string

      A timestamp in RFC 3339 format

    • environment_id: string

    • metadata: map[string]

    • outcome_evaluations: array of BetaManagedAgentsOutcomeEvaluationResource

      Per-outcome evaluation state. One entry per define_outcome event sent to the session.

      • completed_at: string

        A timestamp in RFC 3339 format

      • description: string

        What the agent should produce.

      • explanation: string

        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 of BetaManagedAgentsSessionResource

      • BetaManagedAgentsGitHubRepositoryResource object { id, created_at, mount_path, 4 more }

        • 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: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout

          • BetaManagedAgentsBranchCheckout object { name, type }

            • name: string

              Branch name to check out.

            • type: "branch"

              • "branch"

          • BetaManagedAgentsCommitCheckout object { sha, type }

            • sha: string

              Full commit SHA to check out.

            • type: "commit"

              • "commit"

      • BetaManagedAgentsFileResource object { id, created_at, file_id, 3 more }

        • 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 object { memory_store_id, type, access, 4 more }

        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: optional "read_write" or "read_only"

          Access mode for an attached memory store.

          • "read_write"

          • "read_only"

        • description: optional 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: optional string

          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: optional string

          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: optional string

          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: optional number

        Cumulative time in seconds the session spent in running status. Excludes idle time.

      • duration_seconds: optional number

        Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update.

    • status: "rescheduling" or "running" or "idle" or "terminated"

      SessionStatus enum

      • "rescheduling"

      • "running"

      • "idle"

      • "terminated"

    • title: string

    • 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: optional BetaManagedAgentsCacheCreationUsage

        Prompt-cache creation token usage broken down by cache lifetime.

        • ephemeral_1h_input_tokens: optional number

          Tokens used to create 1-hour ephemeral cache entries.

        • ephemeral_5m_input_tokens: optional number

          Tokens used to create 5-minute ephemeral cache entries.

      • cache_read_input_tokens: optional number

        Total tokens read from prompt cache.

      • input_tokens: optional number

        Total input tokens consumed across all turns.

      • output_tokens: optional number

        Total output tokens generated across all turns.

    • vault_ids: array of string

      Vault IDs attached to the session at creation. Empty when no vaults were supplied.

Example

curl https://api.anthropic.com/v1/sessions/$SESSION_ID \
    -H 'Content-Type: application/json' \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: managed-agents-2026-04-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY" \
    -d '{
          "title": "Order #1234 inquiry"
        }'

Response

{
  "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

delete /v1/sessions/{session_id}

Delete Session

Path Parameters

  • session_id: string

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Returns

  • BetaManagedAgentsDeletedSession object { id, type }

    Confirmation that a session has been permanently deleted.

    • id: string

    • type: "session_deleted"

      • "session_deleted"

Example

curl https://api.anthropic.com/v1/sessions/$SESSION_ID \
    -X DELETE \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: managed-agents-2026-04-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

Response

{
  "id": "sesn_011CZkZAtmR3yMPDzynEDxu7",
  "type": "session_deleted"
}

Archive Session

post /v1/sessions/{session_id}/archive

Archive Session

Path Parameters

  • session_id: string

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Returns

  • BetaManagedAgentsSession object { id, agent, archived_at, 12 more }

    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

      • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

        • name: string

        • type: "url"

          • "url"

        • url: string

      • model: BetaManagedAgentsModelConfig

        Model identifier and configuration.

        • id: BetaManagedAgentsModel

          The model that will power your agent.

          See models for additional details and options.

          • "claude-opus-4-7" or "claude-opus-4-6" or "claude-sonnet-4-6" or 6 more

            The model that will power your agent.

            See models for additional details and options.

            • "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: optional "standard" or "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

        Resolved coordinator topology with full agent definitions for each roster member.

        • agents: array of BetaManagedAgentsSessionThreadAgent

          Full agent definitions the coordinator may spawn as session threads.

          • id: string

          • description: string

          • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

            • name: string

            • type: "url"

            • url: string

          • model: BetaManagedAgentsModelConfig

            Model identifier and configuration.

          • name: string

          • skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

            • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

              A resolved Anthropic-managed skill.

              • skill_id: string

              • type: "anthropic"

                • "anthropic"

              • version: string

            • BetaManagedAgentsCustomSkill object { skill_id, type, version }

              A resolved user-created custom skill.

              • skill_id: string

              • type: "custom"

                • "custom"

              • version: string

          • system: string

          • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

            • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

              • configs: array of BetaManagedAgentsAgentToolConfig

                • enabled: boolean

                • name: "bash" or "edit" or "read" or 5 more

                  Built-in agent tool identifier.

                  • "bash"

                  • "edit"

                  • "read"

                  • "write"

                  • "glob"

                  • "grep"

                  • "web_fetch"

                  • "web_search"

                • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                  Permission policy for tool execution.

                  • BetaManagedAgentsAlwaysAllowPolicy object { type }

                    Tool calls are automatically approved without user confirmation.

                    • type: "always_allow"

                      • "always_allow"

                  • BetaManagedAgentsAlwaysAskPolicy object { type }

                    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 or BetaManagedAgentsAlwaysAskPolicy

                  Permission policy for tool execution.

                  • BetaManagedAgentsAlwaysAllowPolicy object { type }

                    Tool calls are automatically approved without user confirmation.

                  • BetaManagedAgentsAlwaysAskPolicy object { type }

                    Tool calls require user confirmation before execution.

              • type: "agent_toolset_20260401"

                • "agent_toolset_20260401"

            • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

              • configs: array of BetaManagedAgentsMCPToolConfig

                • enabled: boolean

                • name: string

                • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                  Permission policy for tool execution.

                  • BetaManagedAgentsAlwaysAllowPolicy object { type }

                    Tool calls are automatically approved without user confirmation.

                  • BetaManagedAgentsAlwaysAskPolicy object { type }

                    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 or BetaManagedAgentsAlwaysAskPolicy

                  Permission policy for tool execution.

                  • BetaManagedAgentsAlwaysAllowPolicy object { type }

                    Tool calls are automatically approved without user confirmation.

                  • BetaManagedAgentsAlwaysAskPolicy object { type }

                    Tool calls require user confirmation before execution.

              • mcp_server_name: string

              • type: "mcp_toolset"

                • "mcp_toolset"

            • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

              A custom tool as returned in API responses.

              • description: string

              • input_schema: BetaManagedAgentsCustomToolInputSchema

                JSON Schema for custom tool input parameters.

                • properties: optional map[unknown]

                  JSON Schema properties defining the tool's input parameters.

                • required: optional array of string

                  List of required property names.

                • type: optional "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 of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

        • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

          A resolved Anthropic-managed skill.

        • BetaManagedAgentsCustomSkill object { skill_id, type, version }

          A resolved user-created custom skill.

      • system: string

      • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

        • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

        • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

        • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

          A custom tool as returned in API responses.

      • type: "agent"

        • "agent"

      • version: number

    • archived_at: string

      A timestamp in RFC 3339 format

    • created_at: string

      A timestamp in RFC 3339 format

    • environment_id: string

    • metadata: map[string]

    • outcome_evaluations: array of BetaManagedAgentsOutcomeEvaluationResource

      Per-outcome evaluation state. One entry per define_outcome event sent to the session.

      • completed_at: string

        A timestamp in RFC 3339 format

      • description: string

        What the agent should produce.

      • explanation: string

        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 of BetaManagedAgentsSessionResource

      • BetaManagedAgentsGitHubRepositoryResource object { id, created_at, mount_path, 4 more }

        • 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: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout

          • BetaManagedAgentsBranchCheckout object { name, type }

            • name: string

              Branch name to check out.

            • type: "branch"

              • "branch"

          • BetaManagedAgentsCommitCheckout object { sha, type }

            • sha: string

              Full commit SHA to check out.

            • type: "commit"

              • "commit"

      • BetaManagedAgentsFileResource object { id, created_at, file_id, 3 more }

        • 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 object { memory_store_id, type, access, 4 more }

        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: optional "read_write" or "read_only"

          Access mode for an attached memory store.

          • "read_write"

          • "read_only"

        • description: optional 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: optional string

          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: optional string

          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: optional string

          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: optional number

        Cumulative time in seconds the session spent in running status. Excludes idle time.

      • duration_seconds: optional number

        Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update.

    • status: "rescheduling" or "running" or "idle" or "terminated"

      SessionStatus enum

      • "rescheduling"

      • "running"

      • "idle"

      • "terminated"

    • title: string

    • 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: optional BetaManagedAgentsCacheCreationUsage

        Prompt-cache creation token usage broken down by cache lifetime.

        • ephemeral_1h_input_tokens: optional number

          Tokens used to create 1-hour ephemeral cache entries.

        • ephemeral_5m_input_tokens: optional number

          Tokens used to create 5-minute ephemeral cache entries.

      • cache_read_input_tokens: optional number

        Total tokens read from prompt cache.

      • input_tokens: optional number

        Total input tokens consumed across all turns.

      • output_tokens: optional number

        Total output tokens generated across all turns.

    • vault_ids: array of string

      Vault IDs attached to the session at creation. Empty when no vaults were supplied.

Example

curl https://api.anthropic.com/v1/sessions/$SESSION_ID/archive \
    -X POST \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: managed-agents-2026-04-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

Response

{
  "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 object { id, type, version }

    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: optional 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 object { name, type }

    • name: string

      Branch name to check out.

    • type: "branch"

      • "branch"

Beta Managed Agents Cache Creation Usage

  • BetaManagedAgentsCacheCreationUsage object { ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }

    Prompt-cache creation token usage broken down by cache lifetime.

    • ephemeral_1h_input_tokens: optional number

      Tokens used to create 1-hour ephemeral cache entries.

    • ephemeral_5m_input_tokens: optional number

      Tokens used to create 5-minute ephemeral cache entries.

Beta Managed Agents Commit Checkout

  • BetaManagedAgentsCommitCheckout object { sha, type }

    • sha: string

      Full commit SHA to check out.

    • type: "commit"

      • "commit"

Beta Managed Agents Deleted Session

  • BetaManagedAgentsDeletedSession object { id, type }

    Confirmation that a session has been permanently deleted.

    • id: string

    • type: "session_deleted"

      • "session_deleted"

Beta Managed Agents File Resource Params

  • BetaManagedAgentsFileResourceParams object { file_id, type, mount_path }

    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: optional string

      Mount path in the container. Defaults to /mnt/session/uploads/<file_id>.

Beta Managed Agents GitHub Repository Resource Params

  • BetaManagedAgentsGitHubRepositoryResourceParams object { authorization_token, type, url, 2 more }

    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: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout

      Branch or commit to check out. Defaults to the repository's default branch.

      • BetaManagedAgentsBranchCheckout object { name, type }

        • name: string

          Branch name to check out.

        • type: "branch"

          • "branch"

      • BetaManagedAgentsCommitCheckout object { sha, type }

        • sha: string

          Full commit SHA to check out.

        • type: "commit"

          • "commit"

    • mount_path: optional string

      Mount path in the container. Defaults to /workspace/<repo-name>.

Beta Managed Agents Memory Store Resource Param

  • BetaManagedAgentsMemoryStoreResourceParam object { memory_store_id, type, access, instructions }

    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: optional "read_write" or "read_only"

      Access mode for an attached memory store.

      • "read_write"

      • "read_only"

    • instructions: optional string

      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 object { agents, type }

    Resolved coordinator topology with a concrete agent roster.

    • agents: array of BetaManagedAgentsAgentReference

      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 object { agents, type }

    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 of BetaManagedAgentsMultiagentRosterEntryParams

      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 object { id, type, version }

        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: optional number

          The specific agent version to use. Omit to use the latest version. Must be at least 1 if specified.

      • BetaManagedAgentsMultiagentSelfParams object { type }

        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 or BetaManagedAgentsAgentParams or BetaManagedAgentsMultiagentSelfParams

    An entry in a multiagent roster: an agent ID string, a versioned agent reference, or self.

    • string

    • BetaManagedAgentsAgentParams object { id, type, version }

      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: optional number

        The specific agent version to use. Omit to use the latest version. Must be at least 1 if specified.

    • BetaManagedAgentsMultiagentSelfParams object { type }

      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 object { completed_at, description, explanation, 4 more }

    Evaluation state for a single outcome defined via a define_outcome event.

    • completed_at: string

      A timestamp in RFC 3339 format

    • description: string

      What the agent should produce.

    • explanation: string

      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 object { id, agent, archived_at, 12 more }

    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

      • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

        • name: string

        • type: "url"

          • "url"

        • url: string

      • model: BetaManagedAgentsModelConfig

        Model identifier and configuration.

        • id: BetaManagedAgentsModel

          The model that will power your agent.

          See models for additional details and options.

          • "claude-opus-4-7" or "claude-opus-4-6" or "claude-sonnet-4-6" or 6 more

            The model that will power your agent.

            See models for additional details and options.

            • "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: optional "standard" or "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

        Resolved coordinator topology with full agent definitions for each roster member.

        • agents: array of BetaManagedAgentsSessionThreadAgent

          Full agent definitions the coordinator may spawn as session threads.

          • id: string

          • description: string

          • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

            • name: string

            • type: "url"

            • url: string

          • model: BetaManagedAgentsModelConfig

            Model identifier and configuration.

          • name: string

          • skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

            • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

              A resolved Anthropic-managed skill.

              • skill_id: string

              • type: "anthropic"

                • "anthropic"

              • version: string

            • BetaManagedAgentsCustomSkill object { skill_id, type, version }

              A resolved user-created custom skill.

              • skill_id: string

              • type: "custom"

                • "custom"

              • version: string

          • system: string

          • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

            • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

              • configs: array of BetaManagedAgentsAgentToolConfig

                • enabled: boolean

                • name: "bash" or "edit" or "read" or 5 more

                  Built-in agent tool identifier.

                  • "bash"

                  • "edit"

                  • "read"

                  • "write"

                  • "glob"

                  • "grep"

                  • "web_fetch"

                  • "web_search"

                • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                  Permission policy for tool execution.

                  • BetaManagedAgentsAlwaysAllowPolicy object { type }

                    Tool calls are automatically approved without user confirmation.

                    • type: "always_allow"

                      • "always_allow"

                  • BetaManagedAgentsAlwaysAskPolicy object { type }

                    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 or BetaManagedAgentsAlwaysAskPolicy

                  Permission policy for tool execution.

                  • BetaManagedAgentsAlwaysAllowPolicy object { type }

                    Tool calls are automatically approved without user confirmation.

                  • BetaManagedAgentsAlwaysAskPolicy object { type }

                    Tool calls require user confirmation before execution.

              • type: "agent_toolset_20260401"

                • "agent_toolset_20260401"

            • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

              • configs: array of BetaManagedAgentsMCPToolConfig

                • enabled: boolean

                • name: string

                • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                  Permission policy for tool execution.

                  • BetaManagedAgentsAlwaysAllowPolicy object { type }

                    Tool calls are automatically approved without user confirmation.

                  • BetaManagedAgentsAlwaysAskPolicy object { type }

                    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 or BetaManagedAgentsAlwaysAskPolicy

                  Permission policy for tool execution.

                  • BetaManagedAgentsAlwaysAllowPolicy object { type }

                    Tool calls are automatically approved without user confirmation.

                  • BetaManagedAgentsAlwaysAskPolicy object { type }

                    Tool calls require user confirmation before execution.

              • mcp_server_name: string

              • type: "mcp_toolset"

                • "mcp_toolset"

            • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

              A custom tool as returned in API responses.

              • description: string

              • input_schema: BetaManagedAgentsCustomToolInputSchema

                JSON Schema for custom tool input parameters.

                • properties: optional map[unknown]

                  JSON Schema properties defining the tool's input parameters.

                • required: optional array of string

                  List of required property names.

                • type: optional "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 of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

        • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

          A resolved Anthropic-managed skill.

        • BetaManagedAgentsCustomSkill object { skill_id, type, version }

          A resolved user-created custom skill.

      • system: string

      • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

        • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

        • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

        • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

          A custom tool as returned in API responses.

      • type: "agent"

        • "agent"

      • version: number

    • archived_at: string

      A timestamp in RFC 3339 format

    • created_at: string

      A timestamp in RFC 3339 format

    • environment_id: string

    • metadata: map[string]

    • outcome_evaluations: array of BetaManagedAgentsOutcomeEvaluationResource

      Per-outcome evaluation state. One entry per define_outcome event sent to the session.

      • completed_at: string

        A timestamp in RFC 3339 format

      • description: string

        What the agent should produce.

      • explanation: string

        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 of BetaManagedAgentsSessionResource

      • BetaManagedAgentsGitHubRepositoryResource object { id, created_at, mount_path, 4 more }

        • 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: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout

          • BetaManagedAgentsBranchCheckout object { name, type }

            • name: string

              Branch name to check out.

            • type: "branch"

              • "branch"

          • BetaManagedAgentsCommitCheckout object { sha, type }

            • sha: string

              Full commit SHA to check out.

            • type: "commit"

              • "commit"

      • BetaManagedAgentsFileResource object { id, created_at, file_id, 3 more }

        • 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 object { memory_store_id, type, access, 4 more }

        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: optional "read_write" or "read_only"

          Access mode for an attached memory store.

          • "read_write"

          • "read_only"

        • description: optional 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: optional string

          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: optional string

          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: optional string

          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: optional number

        Cumulative time in seconds the session spent in running status. Excludes idle time.

      • duration_seconds: optional number

        Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update.

    • status: "rescheduling" or "running" or "idle" or "terminated"

      SessionStatus enum

      • "rescheduling"

      • "running"

      • "idle"

      • "terminated"

    • title: string

    • 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: optional BetaManagedAgentsCacheCreationUsage

        Prompt-cache creation token usage broken down by cache lifetime.

        • ephemeral_1h_input_tokens: optional number

          Tokens used to create 1-hour ephemeral cache entries.

        • ephemeral_5m_input_tokens: optional number

          Tokens used to create 5-minute ephemeral cache entries.

      • cache_read_input_tokens: optional number

        Total tokens read from prompt cache.

      • input_tokens: optional number

        Total input tokens consumed across all turns.

      • output_tokens: optional number

        Total output tokens generated across all turns.

    • vault_ids: array of string

      Vault IDs attached to the session at creation. Empty when no vaults were supplied.

Beta Managed Agents Session Agent

  • BetaManagedAgentsSessionAgent object { id, description, mcp_servers, 8 more }

    Resolved agent definition for a session. Snapshot of the agent at session creation time.

    • id: string

    • description: string

    • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

      • name: string

      • type: "url"

        • "url"

      • url: string

    • model: BetaManagedAgentsModelConfig

      Model identifier and configuration.

      • id: BetaManagedAgentsModel

        The model that will power your agent.

        See models for additional details and options.

        • "claude-opus-4-7" or "claude-opus-4-6" or "claude-sonnet-4-6" or 6 more

          The model that will power your agent.

          See models for additional details and options.

          • "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: optional "standard" or "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

      Resolved coordinator topology with full agent definitions for each roster member.

      • agents: array of BetaManagedAgentsSessionThreadAgent

        Full agent definitions the coordinator may spawn as session threads.

        • id: string

        • description: string

        • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

          • name: string

          • type: "url"

          • url: string

        • model: BetaManagedAgentsModelConfig

          Model identifier and configuration.

        • name: string

        • skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

          • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

            A resolved Anthropic-managed skill.

            • skill_id: string

            • type: "anthropic"

              • "anthropic"

            • version: string

          • BetaManagedAgentsCustomSkill object { skill_id, type, version }

            A resolved user-created custom skill.

            • skill_id: string

            • type: "custom"

              • "custom"

            • version: string

        • system: string

        • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

          • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

            • configs: array of BetaManagedAgentsAgentToolConfig

              • enabled: boolean

              • name: "bash" or "edit" or "read" or 5 more

                Built-in agent tool identifier.

                • "bash"

                • "edit"

                • "read"

                • "write"

                • "glob"

                • "grep"

                • "web_fetch"

                • "web_search"

              • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                Permission policy for tool execution.

                • BetaManagedAgentsAlwaysAllowPolicy object { type }

                  Tool calls are automatically approved without user confirmation.

                  • type: "always_allow"

                    • "always_allow"

                • BetaManagedAgentsAlwaysAskPolicy object { type }

                  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 or BetaManagedAgentsAlwaysAskPolicy

                Permission policy for tool execution.

                • BetaManagedAgentsAlwaysAllowPolicy object { type }

                  Tool calls are automatically approved without user confirmation.

                • BetaManagedAgentsAlwaysAskPolicy object { type }

                  Tool calls require user confirmation before execution.

            • type: "agent_toolset_20260401"

              • "agent_toolset_20260401"

          • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

            • configs: array of BetaManagedAgentsMCPToolConfig

              • enabled: boolean

              • name: string

              • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                Permission policy for tool execution.

                • BetaManagedAgentsAlwaysAllowPolicy object { type }

                  Tool calls are automatically approved without user confirmation.

                • BetaManagedAgentsAlwaysAskPolicy object { type }

                  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 or BetaManagedAgentsAlwaysAskPolicy

                Permission policy for tool execution.

                • BetaManagedAgentsAlwaysAllowPolicy object { type }

                  Tool calls are automatically approved without user confirmation.

                • BetaManagedAgentsAlwaysAskPolicy object { type }

                  Tool calls require user confirmation before execution.

            • mcp_server_name: string

            • type: "mcp_toolset"

              • "mcp_toolset"

          • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

            A custom tool as returned in API responses.

            • description: string

            • input_schema: BetaManagedAgentsCustomToolInputSchema

              JSON Schema for custom tool input parameters.

              • properties: optional map[unknown]

                JSON Schema properties defining the tool's input parameters.

              • required: optional array of string

                List of required property names.

              • type: optional "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 of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

      • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

        A resolved Anthropic-managed skill.

      • BetaManagedAgentsCustomSkill object { skill_id, type, version }

        A resolved user-created custom skill.

    • system: string

    • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

      • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

      • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

      • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

        A custom tool as returned in API responses.

    • type: "agent"

      • "agent"

    • version: number

Beta Managed Agents Session Agent Update

  • BetaManagedAgentsSessionAgentUpdate object { mcp_servers, tools }

    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: optional array of BetaManagedAgentsURLMCPServerParams

      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: optional array of BetaManagedAgentsAgentToolset20260401Params or BetaManagedAgentsMCPToolsetParams or BetaManagedAgentsCustomToolParams

      Replacement tool list. Full replacement: the provided array becomes the new value. Send an empty array to clear; omit to preserve.

      • BetaManagedAgentsAgentToolset20260401Params object { type, configs, default_config }

        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: optional array of BetaManagedAgentsAgentToolConfigParams

          Per-tool configuration overrides.

          • name: "bash" or "edit" or "read" or 5 more

            Built-in agent tool identifier.

            • "bash"

            • "edit"

            • "read"

            • "write"

            • "glob"

            • "grep"

            • "web_fetch"

            • "web_search"

          • enabled: optional boolean

            Whether this tool is enabled and available to Claude. Overrides the default_config setting.

          • permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

            Permission policy for tool execution.

            • BetaManagedAgentsAlwaysAllowPolicy object { type }

              Tool calls are automatically approved without user confirmation.

              • type: "always_allow"

                • "always_allow"

            • BetaManagedAgentsAlwaysAskPolicy object { type }

              Tool calls require user confirmation before execution.

              • type: "always_ask"

                • "always_ask"

        • default_config: optional BetaManagedAgentsAgentToolsetDefaultConfigParams

          Default configuration for all tools in a toolset.

          • enabled: optional boolean

            Whether tools are enabled and available to Claude by default. Defaults to true if not specified.

          • permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

            Permission policy for tool execution.

            • BetaManagedAgentsAlwaysAllowPolicy object { type }

              Tool calls are automatically approved without user confirmation.

            • BetaManagedAgentsAlwaysAskPolicy object { type }

              Tool calls require user confirmation before execution.

      • BetaManagedAgentsMCPToolsetParams object { mcp_server_name, type, configs, default_config }

        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: optional array of BetaManagedAgentsMCPToolConfigParams

          Per-tool configuration overrides.

          • name: string

            Name of the MCP tool to configure. 1-128 characters.

          • enabled: optional boolean

            Whether this tool is enabled. Overrides the default_config setting.

          • permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

            Permission policy for tool execution.

            • BetaManagedAgentsAlwaysAllowPolicy object { type }

              Tool calls are automatically approved without user confirmation.

            • BetaManagedAgentsAlwaysAskPolicy object { type }

              Tool calls require user confirmation before execution.

        • default_config: optional BetaManagedAgentsMCPToolsetDefaultConfigParams

          Default configuration for all tools from an MCP server.

          • enabled: optional boolean

            Whether tools are enabled by default. Defaults to true if not specified.

          • permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

            Permission policy for tool execution.

            • BetaManagedAgentsAlwaysAllowPolicy object { type }

              Tool calls are automatically approved without user confirmation.

            • BetaManagedAgentsAlwaysAskPolicy object { type }

              Tool calls require user confirmation before execution.

      • BetaManagedAgentsCustomToolParams object { description, input_schema, name, type }

        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: optional map[unknown]

            JSON Schema properties defining the tool's input parameters.

          • required: optional array of string

            List of required property names.

          • type: optional "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 object { agents, type }

    Resolved coordinator topology with full agent definitions for each roster member.

    • agents: array of BetaManagedAgentsSessionThreadAgent

      Full agent definitions the coordinator may spawn as session threads.

      • id: string

      • description: string

      • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

        • name: string

        • type: "url"

          • "url"

        • url: string

      • model: BetaManagedAgentsModelConfig

        Model identifier and configuration.

        • id: BetaManagedAgentsModel

          The model that will power your agent.

          See models for additional details and options.

          • "claude-opus-4-7" or "claude-opus-4-6" or "claude-sonnet-4-6" or 6 more

            The model that will power your agent.

            See models for additional details and options.

            • "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: optional "standard" or "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 of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

        • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

          A resolved Anthropic-managed skill.

          • skill_id: string

          • type: "anthropic"

            • "anthropic"

          • version: string

        • BetaManagedAgentsCustomSkill object { skill_id, type, version }

          A resolved user-created custom skill.

          • skill_id: string

          • type: "custom"

            • "custom"

          • version: string

      • system: string

      • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

        • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

          • configs: array of BetaManagedAgentsAgentToolConfig

            • enabled: boolean

            • name: "bash" or "edit" or "read" or 5 more

              Built-in agent tool identifier.

              • "bash"

              • "edit"

              • "read"

              • "write"

              • "glob"

              • "grep"

              • "web_fetch"

              • "web_search"

            • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

              Permission policy for tool execution.

              • BetaManagedAgentsAlwaysAllowPolicy object { type }

                Tool calls are automatically approved without user confirmation.

                • type: "always_allow"

                  • "always_allow"

              • BetaManagedAgentsAlwaysAskPolicy object { type }

                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 or BetaManagedAgentsAlwaysAskPolicy

              Permission policy for tool execution.

              • BetaManagedAgentsAlwaysAllowPolicy object { type }

                Tool calls are automatically approved without user confirmation.

              • BetaManagedAgentsAlwaysAskPolicy object { type }

                Tool calls require user confirmation before execution.

          • type: "agent_toolset_20260401"

            • "agent_toolset_20260401"

        • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

          • configs: array of BetaManagedAgentsMCPToolConfig

            • enabled: boolean

            • name: string

            • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

              Permission policy for tool execution.

              • BetaManagedAgentsAlwaysAllowPolicy object { type }

                Tool calls are automatically approved without user confirmation.

              • BetaManagedAgentsAlwaysAskPolicy object { type }

                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 or BetaManagedAgentsAlwaysAskPolicy

              Permission policy for tool execution.

              • BetaManagedAgentsAlwaysAllowPolicy object { type }

                Tool calls are automatically approved without user confirmation.

              • BetaManagedAgentsAlwaysAskPolicy object { type }

                Tool calls require user confirmation before execution.

          • mcp_server_name: string

          • type: "mcp_toolset"

            • "mcp_toolset"

        • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

          A custom tool as returned in API responses.

          • description: string

          • input_schema: BetaManagedAgentsCustomToolInputSchema

            JSON Schema for custom tool input parameters.

            • properties: optional map[unknown]

              JSON Schema properties defining the tool's input parameters.

            • required: optional array of string

              List of required property names.

            • type: optional "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 object { active_seconds, duration_seconds }

    Timing statistics for a session.

    • active_seconds: optional number

      Cumulative time in seconds the session spent in running status. Excludes idle time.

    • duration_seconds: optional number

      Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update.

Beta Managed Agents Session Updated Event

  • BetaManagedAgentsSessionUpdatedEvent object { id, processed_at, type, 3 more }

    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: optional BetaManagedAgentsSessionAgent

      Resolved agent definition for a session. Snapshot of the agent at session creation time.

      • id: string

      • description: string

      • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

        • name: string

        • type: "url"

          • "url"

        • url: string

      • model: BetaManagedAgentsModelConfig

        Model identifier and configuration.

        • id: BetaManagedAgentsModel

          The model that will power your agent.

          See models for additional details and options.

          • "claude-opus-4-7" or "claude-opus-4-6" or "claude-sonnet-4-6" or 6 more

            The model that will power your agent.

            See models for additional details and options.

            • "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: optional "standard" or "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

        Resolved coordinator topology with full agent definitions for each roster member.

        • agents: array of BetaManagedAgentsSessionThreadAgent

          Full agent definitions the coordinator may spawn as session threads.

          • id: string

          • description: string

          • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

            • name: string

            • type: "url"

            • url: string

          • model: BetaManagedAgentsModelConfig

            Model identifier and configuration.

          • name: string

          • skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

            • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

              A resolved Anthropic-managed skill.

              • skill_id: string

              • type: "anthropic"

                • "anthropic"

              • version: string

            • BetaManagedAgentsCustomSkill object { skill_id, type, version }

              A resolved user-created custom skill.

              • skill_id: string

              • type: "custom"

                • "custom"

              • version: string

          • system: string

          • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

            • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

              • configs: array of BetaManagedAgentsAgentToolConfig

                • enabled: boolean

                • name: "bash" or "edit" or "read" or 5 more

                  Built-in agent tool identifier.

                  • "bash"

                  • "edit"

                  • "read"

                  • "write"

                  • "glob"

                  • "grep"

                  • "web_fetch"

                  • "web_search"

                • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                  Permission policy for tool execution.

                  • BetaManagedAgentsAlwaysAllowPolicy object { type }

                    Tool calls are automatically approved without user confirmation.

                    • type: "always_allow"

                      • "always_allow"

                  • BetaManagedAgentsAlwaysAskPolicy object { type }

                    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 or BetaManagedAgentsAlwaysAskPolicy

                  Permission policy for tool execution.

                  • BetaManagedAgentsAlwaysAllowPolicy object { type }

                    Tool calls are automatically approved without user confirmation.

                  • BetaManagedAgentsAlwaysAskPolicy object { type }

                    Tool calls require user confirmation before execution.

              • type: "agent_toolset_20260401"

                • "agent_toolset_20260401"

            • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

              • configs: array of BetaManagedAgentsMCPToolConfig

                • enabled: boolean

                • name: string

                • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                  Permission policy for tool execution.

                  • BetaManagedAgentsAlwaysAllowPolicy object { type }

                    Tool calls are automatically approved without user confirmation.

                  • BetaManagedAgentsAlwaysAskPolicy object { type }

                    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 or BetaManagedAgentsAlwaysAskPolicy

                  Permission policy for tool execution.

                  • BetaManagedAgentsAlwaysAllowPolicy object { type }

                    Tool calls are automatically approved without user confirmation.

                  • BetaManagedAgentsAlwaysAskPolicy object { type }

                    Tool calls require user confirmation before execution.

              • mcp_server_name: string

              • type: "mcp_toolset"

                • "mcp_toolset"

            • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

              A custom tool as returned in API responses.

              • description: string

              • input_schema: BetaManagedAgentsCustomToolInputSchema

                JSON Schema for custom tool input parameters.

                • properties: optional map[unknown]

                  JSON Schema properties defining the tool's input parameters.

                • required: optional array of string

                  List of required property names.

                • type: optional "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 of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

        • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

          A resolved Anthropic-managed skill.

        • BetaManagedAgentsCustomSkill object { skill_id, type, version }

          A resolved user-created custom skill.

      • system: string

      • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

        • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

        • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

        • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

          A custom tool as returned in API responses.

      • type: "agent"

        • "agent"

      • version: number

    • metadata: optional map[string]

      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: optional string

      The session's new title. Present only when the update changed it.

Beta Managed Agents Session Usage

  • BetaManagedAgentsSessionUsage object { cache_creation, cache_read_input_tokens, input_tokens, output_tokens }

    Cumulative token usage for a session across all turns.

    • cache_creation: optional BetaManagedAgentsCacheCreationUsage

      Prompt-cache creation token usage broken down by cache lifetime.

      • ephemeral_1h_input_tokens: optional number

        Tokens used to create 1-hour ephemeral cache entries.

      • ephemeral_5m_input_tokens: optional number

        Tokens used to create 5-minute ephemeral cache entries.

    • cache_read_input_tokens: optional number

      Total tokens read from prompt cache.

    • input_tokens: optional number

      Total input tokens consumed across all turns.

    • output_tokens: optional number

      Total output tokens generated across all turns.

Beta Managed Agents User Tool Result Event

  • BetaManagedAgentsUserToolResultEvent object { id, tool_use_id, type, 4 more }

    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 stop_reason.event_ids field.

    • type: "user.tool_result"

      • "user.tool_result"

    • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

      The result content returned by the tool.

      • BetaManagedAgentsTextBlock object { text, type }

        Regular text content.

        • text: string

          The text content.

        • type: "text"

          • "text"

      • BetaManagedAgentsImageBlock object { source, type }

        Image content specified directly as base64 data or as a reference via a URL.

        • source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource

          Union type for image source variants.

          • BetaManagedAgentsBase64ImageSource object { data, media_type, type }

            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 object { type, url }

            Image referenced by URL.

            • type: "url"

              • "url"

            • url: string

              URL of the image to fetch.

          • BetaManagedAgentsFileImageSource object { file_id, type }

            Image referenced by file ID.

            • file_id: string

              ID of a previously uploaded file.

            • type: "file"

              • "file"

        • type: "image"

          • "image"

      • BetaManagedAgentsDocumentBlock object { source, type, context, title }

        Document content, either specified directly as base64 data, as text, or as a reference via a URL.

        • source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource

          Union type for document source variants.

          • BetaManagedAgentsBase64DocumentSource object { data, media_type, type }

            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 object { data, media_type, type }

            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 object { type, url }

            Document referenced by URL.

            • type: "url"

              • "url"

            • url: string

              URL of the document to fetch.

          • BetaManagedAgentsFileDocumentSource object { file_id, type }

            Document referenced by file ID.

            • file_id: string

              ID of a previously uploaded file.

            • type: "file"

              • "file"

        • type: "document"

          • "document"

        • context: optional string

          Additional context about the document for the model.

        • title: optional string

          The title of the document.

      • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

        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 of BetaManagedAgentsSearchResultContent

          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: optional boolean

      Whether the tool execution resulted in an error.

    • processed_at: optional string

      A timestamp in RFC 3339 format

    • session_thread_id: optional string

      Routes this result to a subagent thread. Copy from the agent.tool_use event's session_thread_id.

Events

List Events

get /v1/sessions/{session_id}/events

List Events

Path Parameters

  • session_id: string

Query Parameters

  • "created_at[gt]": optional string

    Return events created after this time (exclusive).

  • "created_at[gte]": optional string

    Return events created at or after this time (inclusive).

  • "created_at[lt]": optional string

    Return events created before this time (exclusive).

  • "created_at[lte]": optional string

    Return events created at or before this time (inclusive).

  • limit: optional number

    Query parameter for limit

  • order: optional "asc" or "desc"

    Sort direction for results, ordered by created_at. Defaults to asc (chronological).

    • "asc"

    • "desc"

  • page: optional string

    Opaque pagination cursor from a previous response's next_page.

  • types: optional array of string

    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.

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Returns

  • data: optional array of BetaManagedAgentsSessionEvent

    Events for the session, ordered by created_at.

    • BetaManagedAgentsUserMessageEvent object { id, content, type, processed_at }

      A user message event in the session conversation.

      • id: string

        Unique identifier for this event.

      • content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock

        Array of content blocks comprising the user message.

        • BetaManagedAgentsTextBlock object { text, type }

          Regular text content.

          • text: string

            The text content.

          • type: "text"

            • "text"

        • BetaManagedAgentsImageBlock object { source, type }

          Image content specified directly as base64 data or as a reference via a URL.

          • source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource

            Union type for image source variants.

            • BetaManagedAgentsBase64ImageSource object { data, media_type, type }

              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 object { type, url }

              Image referenced by URL.

              • type: "url"

                • "url"

              • url: string

                URL of the image to fetch.

            • BetaManagedAgentsFileImageSource object { file_id, type }

              Image referenced by file ID.

              • file_id: string

                ID of a previously uploaded file.

              • type: "file"

                • "file"

          • type: "image"

            • "image"

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          Document content, either specified directly as base64 data, as text, or as a reference via a URL.

          • source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource

            Union type for document source variants.

            • BetaManagedAgentsBase64DocumentSource object { data, media_type, type }

              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 object { data, media_type, type }

              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 object { type, url }

              Document referenced by URL.

              • type: "url"

                • "url"

              • url: string

                URL of the document to fetch.

            • BetaManagedAgentsFileDocumentSource object { file_id, type }

              Document referenced by file ID.

              • file_id: string

                ID of a previously uploaded file.

              • type: "file"

                • "file"

          • type: "document"

            • "document"

          • context: optional string

            Additional context about the document for the model.

          • title: optional string

            The title of the document.

      • type: "user.message"

        • "user.message"

      • processed_at: optional string

        A timestamp in RFC 3339 format

    • BetaManagedAgentsUserInterruptEvent object { id, type, processed_at, session_thread_id }

      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: optional string

        A timestamp in RFC 3339 format

      • session_thread_id: optional string

        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 object { id, result, tool_use_id, 4 more }

      A tool confirmation event that approves or denies a pending tool execution.

      • id: string

        Unique identifier for this event.

      • result: "allow" or "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 stop_reason.event_ids field.

      • type: "user.tool_confirmation"

        • "user.tool_confirmation"

      • deny_message: optional string

        Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.

      • processed_at: optional string

        A timestamp in RFC 3339 format

      • session_thread_id: optional string

        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 object { id, custom_tool_use_id, type, 4 more }

      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 stop_reason.event_ids field.

      • type: "user.custom_tool_result"

        • "user.custom_tool_result"

      • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

        The result content returned by the tool.

        • BetaManagedAgentsTextBlock object { text, type }

          Regular text content.

        • BetaManagedAgentsImageBlock object { source, type }

          Image content specified directly as base64 data or as a reference via a URL.

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          Document content, either specified directly as base64 data, as text, or as a reference via a URL.

        • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

          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 of BetaManagedAgentsSearchResultContent

            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: optional boolean

        Whether the tool execution resulted in an error.

      • processed_at: optional string

        A timestamp in RFC 3339 format

      • session_thread_id: optional string

        Routes this result to a subagent thread. Copy from the agent.custom_tool_use event's session_thread_id.

    • BetaManagedAgentsAgentCustomToolUseEvent object { id, input, name, 3 more }

      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: map[unknown]

        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: optional string

        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 object { id, content, processed_at, type }

      An agent response event in the session conversation.

      • id: string

        Unique identifier for this event.

      • content: array of BetaManagedAgentsTextBlock

        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 object { id, processed_at, type }

      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 object { id, input, mcp_server_name, 5 more }

      Event emitted when the agent invokes a tool provided by an MCP server.

      • id: string

        Unique identifier for this event.

      • input: map[unknown]

        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: optional "allow" or "ask" or "deny"

        AgentEvaluatedPermission enum

        • "allow"

        • "ask"

        • "deny"

      • session_thread_id: optional string

        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 object { id, mcp_tool_use_id, processed_at, 3 more }

      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: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

        The result content returned by the tool.

        • BetaManagedAgentsTextBlock object { text, type }

          Regular text content.

        • BetaManagedAgentsImageBlock object { source, type }

          Image content specified directly as base64 data or as a reference via a URL.

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          Document content, either specified directly as base64 data, as text, or as a reference via a URL.

        • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

          A block containing a web search result.

      • is_error: optional boolean

        Whether the tool execution resulted in an error.

    • BetaManagedAgentsAgentToolUseEvent object { id, input, name, 4 more }

      Event emitted when the agent invokes a built-in agent tool.

      • id: string

        Unique identifier for this event.

      • input: map[unknown]

        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: optional "allow" or "ask" or "deny"

        AgentEvaluatedPermission enum

        • "allow"

        • "ask"

        • "deny"

      • session_thread_id: optional string

        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 object { id, processed_at, tool_use_id, 3 more }

      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: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

        The result content returned by the tool.

        • BetaManagedAgentsTextBlock object { text, type }

          Regular text content.

        • BetaManagedAgentsImageBlock object { source, type }

          Image content specified directly as base64 data or as a reference via a URL.

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          Document content, either specified directly as base64 data, as text, or as a reference via a URL.

        • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

          A block containing a web search result.

      • is_error: optional boolean

        Whether the tool execution resulted in an error.

    • BetaManagedAgentsAgentThreadMessageReceivedEvent object { id, content, from_session_thread_id, 3 more }

      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 of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock

        Message content blocks.

        • BetaManagedAgentsTextBlock object { text, type }

          Regular text content.

        • BetaManagedAgentsImageBlock object { source, type }

          Image content specified directly as base64 data or as a reference via a URL.

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          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: optional string

        Name of the callable agent this message came from. Absent when received from the primary agent.

    • BetaManagedAgentsAgentThreadMessageSentEvent object { id, content, processed_at, 3 more }

      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 of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock

        Message content blocks.

        • BetaManagedAgentsTextBlock object { text, type }

          Regular text content.

        • BetaManagedAgentsImageBlock object { source, type }

          Image content specified directly as base64 data or as a reference via a URL.

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          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: optional string

        Name of the callable agent this message was sent to. Absent when sent to the primary agent.

    • BetaManagedAgentsAgentThreadContextCompactedEvent object { id, processed_at, type }

      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 object { id, error, processed_at, type }

      An error event indicating a problem occurred during session execution.

      • id: string

        Unique identifier for this event.

      • error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 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 object { message, retry_status, type }

          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 or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            What the client should do next in response to this error.

            • BetaManagedAgentsRetryStatusRetrying object { type }

              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 object { type }

              This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

              • type: "exhausted"

                • "exhausted"

            • BetaManagedAgentsRetryStatusTerminal object { type }

              The session encountered a terminal error and will transition to terminated state.

              • type: "terminal"

                • "terminal"

          • type: "unknown_error"

            • "unknown_error"

        • BetaManagedAgentsModelOverloadedError object { message, retry_status, type }

          The model is currently overloaded. Emitted after automatic retries are exhausted.

          • message: string

            Human-readable error description.

          • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            What the client should do next in response to this error.

            • BetaManagedAgentsRetryStatusRetrying object { type }

              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 object { type }

              This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

            • BetaManagedAgentsRetryStatusTerminal object { type }

              The session encountered a terminal error and will transition to terminated state.

          • type: "model_overloaded_error"

            • "model_overloaded_error"

        • BetaManagedAgentsModelRateLimitedError object { message, retry_status, type }

          The model request was rate-limited.

          • message: string

            Human-readable error description.

          • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            What the client should do next in response to this error.

            • BetaManagedAgentsRetryStatusRetrying object { type }

              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 object { type }

              This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

            • BetaManagedAgentsRetryStatusTerminal object { type }

              The session encountered a terminal error and will transition to terminated state.

          • type: "model_rate_limited_error"

            • "model_rate_limited_error"

        • BetaManagedAgentsModelRequestFailedError object { message, retry_status, type }

          A model request failed for a reason other than overload or rate-limiting.

          • message: string

            Human-readable error description.

          • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            What the client should do next in response to this error.

            • BetaManagedAgentsRetryStatusRetrying object { type }

              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 object { type }

              This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

            • BetaManagedAgentsRetryStatusTerminal object { type }

              The session encountered a terminal error and will transition to terminated state.

          • type: "model_request_failed_error"

            • "model_request_failed_error"

        • BetaManagedAgentsMCPConnectionFailedError object { mcp_server_name, message, retry_status, type }

          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 or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            What the client should do next in response to this error.

            • BetaManagedAgentsRetryStatusRetrying object { type }

              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 object { type }

              This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

            • BetaManagedAgentsRetryStatusTerminal object { type }

              The session encountered a terminal error and will transition to terminated state.

          • type: "mcp_connection_failed_error"

            • "mcp_connection_failed_error"

        • BetaManagedAgentsMCPAuthenticationFailedError object { mcp_server_name, message, retry_status, type }

          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 or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            What the client should do next in response to this error.

            • BetaManagedAgentsRetryStatusRetrying object { type }

              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 object { type }

              This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

            • BetaManagedAgentsRetryStatusTerminal object { type }

              The session encountered a terminal error and will transition to terminated state.

          • type: "mcp_authentication_failed_error"

            • "mcp_authentication_failed_error"

        • BetaManagedAgentsBillingError object { message, retry_status, type }

          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 or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            What the client should do next in response to this error.

            • BetaManagedAgentsRetryStatusRetrying object { type }

              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 object { type }

              This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

            • BetaManagedAgentsRetryStatusTerminal object { type }

              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 object { id, processed_at, type }

      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 object { id, processed_at, type }

      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 object { id, processed_at, stop_reason, type }

      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 or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted

        The agent completed its turn naturally and is ready for the next user message.

        • BetaManagedAgentsSessionEndTurn object { type }

          The agent completed its turn naturally and is ready for the next user message.

          • type: "end_turn"

            • "end_turn"

        • BetaManagedAgentsSessionRequiresAction object { event_ids, type }

          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 of string

            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 object { type }

          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 object { id, processed_at, type }

      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 object { id, agent_name, processed_at, 2 more }

      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 object { id, iteration, outcome_id, 2 more }

      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 object { id, explanation, iteration, 6 more }

      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: optional "standard" or "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"

    • BetaManagedAgentsSpanModelRequestStartEvent object { id, processed_at, type }

      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 object { id, is_error, model_request_start_id, 3 more }

      Emitted when a model request completes.

      • id: string

        Unique identifier for this event.

      • is_error: boolean

        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 object { id, iteration, outcome_id, 2 more }

      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 object { id, description, max_iterations, 4 more }

      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

        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 or BetaManagedAgentsTextRubric

        Rubric for grading the quality of an outcome.

        • BetaManagedAgentsFileRubric object { file_id, type }

          Rubric referenced by a file uploaded via the Files API.

          • file_id: string

            ID of the rubric file.

          • type: "file"

            • "file"

        • BetaManagedAgentsTextRubric object { content, type }

          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 object { id, processed_at, type }

      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 object { id, agent_name, processed_at, 2 more }

      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 object { id, agent_name, processed_at, 3 more }

      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 or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted

        The agent completed its turn naturally and is ready for the next user message.

        • BetaManagedAgentsSessionEndTurn object { type }

          The agent completed its turn naturally and is ready for the next user message.

        • BetaManagedAgentsSessionRequiresAction object { event_ids, type }

          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 object { type }

          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 object { id, agent_name, processed_at, 2 more }

      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 object { id, tool_use_id, type, 4 more }

      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 stop_reason.event_ids field.

      • type: "user.tool_result"

        • "user.tool_result"

      • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

        The result content returned by the tool.

        • BetaManagedAgentsTextBlock object { text, type }

          Regular text content.

        • BetaManagedAgentsImageBlock object { source, type }

          Image content specified directly as base64 data or as a reference via a URL.

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          Document content, either specified directly as base64 data, as text, or as a reference via a URL.

        • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

          A block containing a web search result.

      • is_error: optional boolean

        Whether the tool execution resulted in an error.

      • processed_at: optional string

        A timestamp in RFC 3339 format

      • session_thread_id: optional string

        Routes this result to a subagent thread. Copy from the agent.tool_use event's session_thread_id.

    • BetaManagedAgentsSessionThreadStatusRescheduledEvent object { id, agent_name, processed_at, 2 more }

      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 object { id, processed_at, type, 3 more }

      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: optional BetaManagedAgentsSessionAgent

        Resolved agent definition for a session. Snapshot of the agent at session creation time.

        • id: string

        • description: string

        • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

          • name: string

          • type: "url"

            • "url"

          • url: string

        • model: BetaManagedAgentsModelConfig

          Model identifier and configuration.

          • id: BetaManagedAgentsModel

            The model that will power your agent.

            See models for additional details and options.

            • "claude-opus-4-7" or "claude-opus-4-6" or "claude-sonnet-4-6" or 6 more

              The model that will power your agent.

              See models for additional details and options.

              • "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: optional "standard" or "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

          Resolved coordinator topology with full agent definitions for each roster member.

          • agents: array of BetaManagedAgentsSessionThreadAgent

            Full agent definitions the coordinator may spawn as session threads.

            • id: string

            • description: string

            • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

              • name: string

              • type: "url"

              • url: string

            • model: BetaManagedAgentsModelConfig

              Model identifier and configuration.

            • name: string

            • skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

              • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

                A resolved Anthropic-managed skill.

                • skill_id: string

                • type: "anthropic"

                  • "anthropic"

                • version: string

              • BetaManagedAgentsCustomSkill object { skill_id, type, version }

                A resolved user-created custom skill.

                • skill_id: string

                • type: "custom"

                  • "custom"

                • version: string

            • system: string

            • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

              • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

                • configs: array of BetaManagedAgentsAgentToolConfig

                  • enabled: boolean

                  • name: "bash" or "edit" or "read" or 5 more

                    Built-in agent tool identifier.

                    • "bash"

                    • "edit"

                    • "read"

                    • "write"

                    • "glob"

                    • "grep"

                    • "web_fetch"

                    • "web_search"

                  • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                    Permission policy for tool execution.

                    • BetaManagedAgentsAlwaysAllowPolicy object { type }

                      Tool calls are automatically approved without user confirmation.

                      • type: "always_allow"

                        • "always_allow"

                    • BetaManagedAgentsAlwaysAskPolicy object { type }

                      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 or BetaManagedAgentsAlwaysAskPolicy

                    Permission policy for tool execution.

                    • BetaManagedAgentsAlwaysAllowPolicy object { type }

                      Tool calls are automatically approved without user confirmation.

                    • BetaManagedAgentsAlwaysAskPolicy object { type }

                      Tool calls require user confirmation before execution.

                • type: "agent_toolset_20260401"

                  • "agent_toolset_20260401"

              • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

                • configs: array of BetaManagedAgentsMCPToolConfig

                  • enabled: boolean

                  • name: string

                  • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                    Permission policy for tool execution.

                    • BetaManagedAgentsAlwaysAllowPolicy object { type }

                      Tool calls are automatically approved without user confirmation.

                    • BetaManagedAgentsAlwaysAskPolicy object { type }

                      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 or BetaManagedAgentsAlwaysAskPolicy

                    Permission policy for tool execution.

                    • BetaManagedAgentsAlwaysAllowPolicy object { type }

                      Tool calls are automatically approved without user confirmation.

                    • BetaManagedAgentsAlwaysAskPolicy object { type }

                      Tool calls require user confirmation before execution.

                • mcp_server_name: string

                • type: "mcp_toolset"

                  • "mcp_toolset"

              • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

                A custom tool as returned in API responses.

                • description: string

                • input_schema: BetaManagedAgentsCustomToolInputSchema

                  JSON Schema for custom tool input parameters.

                  • properties: optional map[unknown]

                    JSON Schema properties defining the tool's input parameters.

                  • required: optional array of string

                    List of required property names.

                  • type: optional "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 of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

          • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

            A resolved Anthropic-managed skill.

          • BetaManagedAgentsCustomSkill object { skill_id, type, version }

            A resolved user-created custom skill.

        • system: string

        • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

          • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

          • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

          • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

            A custom tool as returned in API responses.

        • type: "agent"

          • "agent"

        • version: number

      • metadata: optional map[string]

        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: optional string

        The session's new title. Present only when the update changed it.

  • next_page: optional string

    Opaque cursor for the next page. Null when no more results.

Example

curl https://api.anthropic.com/v1/sessions/$SESSION_ID/events \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: managed-agents-2026-04-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

Response

{
  "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

post /v1/sessions/{session_id}/events

Send Events

Path Parameters

  • session_id: string

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Body Parameters

  • events: array of BetaManagedAgentsEventParams

    Events to send to the session.

    • BetaManagedAgentsUserMessageEventParams object { content, type }

      Parameters for sending a user message to the session.

      • content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock

        Array of content blocks for the user message.

        • BetaManagedAgentsTextBlock object { text, type }

          Regular text content.

          • text: string

            The text content.

          • type: "text"

            • "text"

        • BetaManagedAgentsImageBlock object { source, type }

          Image content specified directly as base64 data or as a reference via a URL.

          • source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource

            Union type for image source variants.

            • BetaManagedAgentsBase64ImageSource object { data, media_type, type }

              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 object { type, url }

              Image referenced by URL.

              • type: "url"

                • "url"

              • url: string

                URL of the image to fetch.

            • BetaManagedAgentsFileImageSource object { file_id, type }

              Image referenced by file ID.

              • file_id: string

                ID of a previously uploaded file.

              • type: "file"

                • "file"

          • type: "image"

            • "image"

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          Document content, either specified directly as base64 data, as text, or as a reference via a URL.

          • source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource

            Union type for document source variants.

            • BetaManagedAgentsBase64DocumentSource object { data, media_type, type }

              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 object { data, media_type, type }

              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 object { type, url }

              Document referenced by URL.

              • type: "url"

                • "url"

              • url: string

                URL of the document to fetch.

            • BetaManagedAgentsFileDocumentSource object { file_id, type }

              Document referenced by file ID.

              • file_id: string

                ID of a previously uploaded file.

              • type: "file"

                • "file"

          • type: "document"

            • "document"

          • context: optional string

            Additional context about the document for the model.

          • title: optional string

            The title of the document.

      • type: "user.message"

        • "user.message"

    • BetaManagedAgentsUserInterruptEventParams object { type, session_thread_id }

      Parameters for sending an interrupt to pause the agent.

      • type: "user.interrupt"

        • "user.interrupt"

      • session_thread_id: optional string

        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 object { result, tool_use_id, type, deny_message }

      Parameters for confirming or denying a tool execution request.

      • result: "allow" or "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 stop_reason.event_ids field.

      • type: "user.tool_confirmation"

        • "user.tool_confirmation"

      • deny_message: optional string

        Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.

    • BetaManagedAgentsUserCustomToolResultEventParams object { custom_tool_use_id, type, content, is_error }

      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 stop_reason.event_ids field.

      • type: "user.custom_tool_result"

        • "user.custom_tool_result"

      • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

        The result content returned by the tool.

        • BetaManagedAgentsTextBlock object { text, type }

          Regular text content.

        • BetaManagedAgentsImageBlock object { source, type }

          Image content specified directly as base64 data or as a reference via a URL.

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          Document content, either specified directly as base64 data, as text, or as a reference via a URL.

        • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

          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 of BetaManagedAgentsSearchResultContent

            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: optional boolean

        Whether the tool execution resulted in an error.

    • BetaManagedAgentsUserDefineOutcomeEventParams object { description, rubric, type, max_iterations }

      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 or BetaManagedAgentsTextRubricParams

        Rubric for grading the quality of an outcome.

        • BetaManagedAgentsFileRubricParams object { file_id, type }

          Rubric referenced by a file uploaded via the Files API.

          • file_id: string

            ID of the rubric file.

          • type: "file"

            • "file"

        • BetaManagedAgentsTextRubricParams object { content, type }

          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: optional number

        Eval→revision cycles before giving up. Default 3, max 20.

    • BetaManagedAgentsUserToolResultEventParams object { tool_use_id, type, content, is_error }

      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 stop_reason.event_ids field.

      • type: "user.tool_result"

        • "user.tool_result"

      • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

        The result content returned by the tool.

        • BetaManagedAgentsTextBlock object { text, type }

          Regular text content.

        • BetaManagedAgentsImageBlock object { source, type }

          Image content specified directly as base64 data or as a reference via a URL.

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          Document content, either specified directly as base64 data, as text, or as a reference via a URL.

        • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

          A block containing a web search result.

      • is_error: optional boolean

        Whether the tool execution resulted in an error.

Returns

  • BetaManagedAgentsSendSessionEvents object { data }

    Events that were successfully sent to the session.

    • data: optional array of BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or 3 more

      Sent events

      • BetaManagedAgentsUserMessageEvent object { id, content, type, processed_at }

        A user message event in the session conversation.

        • id: string

          Unique identifier for this event.

        • content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock

          Array of content blocks comprising the user message.

          • BetaManagedAgentsTextBlock object { text, type }

            Regular text content.

            • text: string

              The text content.

            • type: "text"

              • "text"

          • BetaManagedAgentsImageBlock object { source, type }

            Image content specified directly as base64 data or as a reference via a URL.

            • source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource

              Union type for image source variants.

              • BetaManagedAgentsBase64ImageSource object { data, media_type, type }

                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 object { type, url }

                Image referenced by URL.

                • type: "url"

                  • "url"

                • url: string

                  URL of the image to fetch.

              • BetaManagedAgentsFileImageSource object { file_id, type }

                Image referenced by file ID.

                • file_id: string

                  ID of a previously uploaded file.

                • type: "file"

                  • "file"

            • type: "image"

              • "image"

          • BetaManagedAgentsDocumentBlock object { source, type, context, title }

            Document content, either specified directly as base64 data, as text, or as a reference via a URL.

            • source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource

              Union type for document source variants.

              • BetaManagedAgentsBase64DocumentSource object { data, media_type, type }

                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 object { data, media_type, type }

                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 object { type, url }

                Document referenced by URL.

                • type: "url"

                  • "url"

                • url: string

                  URL of the document to fetch.

              • BetaManagedAgentsFileDocumentSource object { file_id, type }

                Document referenced by file ID.

                • file_id: string

                  ID of a previously uploaded file.

                • type: "file"

                  • "file"

            • type: "document"

              • "document"

            • context: optional string

              Additional context about the document for the model.

            • title: optional string

              The title of the document.

        • type: "user.message"

          • "user.message"

        • processed_at: optional string

          A timestamp in RFC 3339 format

      • BetaManagedAgentsUserInterruptEvent object { id, type, processed_at, session_thread_id }

        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: optional string

          A timestamp in RFC 3339 format

        • session_thread_id: optional string

          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 object { id, result, tool_use_id, 4 more }

        A tool confirmation event that approves or denies a pending tool execution.

        • id: string

          Unique identifier for this event.

        • result: "allow" or "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 stop_reason.event_ids field.

        • type: "user.tool_confirmation"

          • "user.tool_confirmation"

        • deny_message: optional string

          Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.

        • processed_at: optional string

          A timestamp in RFC 3339 format

        • session_thread_id: optional string

          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 object { id, custom_tool_use_id, type, 4 more }

        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 stop_reason.event_ids field.

        • type: "user.custom_tool_result"

          • "user.custom_tool_result"

        • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

          The result content returned by the tool.

          • BetaManagedAgentsTextBlock object { text, type }

            Regular text content.

          • BetaManagedAgentsImageBlock object { source, type }

            Image content specified directly as base64 data or as a reference via a URL.

          • BetaManagedAgentsDocumentBlock object { source, type, context, title }

            Document content, either specified directly as base64 data, as text, or as a reference via a URL.

          • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

            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 of BetaManagedAgentsSearchResultContent

              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: optional boolean

          Whether the tool execution resulted in an error.

        • processed_at: optional string

          A timestamp in RFC 3339 format

        • session_thread_id: optional string

          Routes this result to a subagent thread. Copy from the agent.custom_tool_use event's session_thread_id.

      • BetaManagedAgentsUserDefineOutcomeEvent object { id, description, max_iterations, 4 more }

        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

          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 or BetaManagedAgentsTextRubric

          Rubric for grading the quality of an outcome.

          • BetaManagedAgentsFileRubric object { file_id, type }

            Rubric referenced by a file uploaded via the Files API.

            • file_id: string

              ID of the rubric file.

            • type: "file"

              • "file"

          • BetaManagedAgentsTextRubric object { content, type }

            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 object { id, tool_use_id, type, 4 more }

        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 stop_reason.event_ids field.

        • type: "user.tool_result"

          • "user.tool_result"

        • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

          The result content returned by the tool.

          • BetaManagedAgentsTextBlock object { text, type }

            Regular text content.

          • BetaManagedAgentsImageBlock object { source, type }

            Image content specified directly as base64 data or as a reference via a URL.

          • BetaManagedAgentsDocumentBlock object { source, type, context, title }

            Document content, either specified directly as base64 data, as text, or as a reference via a URL.

          • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

            A block containing a web search result.

        • is_error: optional boolean

          Whether the tool execution resulted in an error.

        • processed_at: optional string

          A timestamp in RFC 3339 format

        • session_thread_id: optional string

          Routes this result to a subagent thread. Copy from the agent.tool_use event's session_thread_id.

Example

curl https://api.anthropic.com/v1/sessions/$SESSION_ID/events \
    -H 'Content-Type: application/json' \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: managed-agents-2026-04-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY" \
    -d '{
          "events": [
            {
              "content": [
                {
                  "text": "Where is my order #1234?",
                  "type": "text"
                }
              ],
              "type": "user.message"
            }
          ]
        }'

Response

{
  "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

get /v1/sessions/{session_id}/events/stream

Stream Events

Path Parameters

  • session_id: string

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Returns

  • BetaManagedAgentsStreamSessionEvents = BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or 30 more

    Server-sent event in the session stream.

    • BetaManagedAgentsUserMessageEvent object { id, content, type, processed_at }

      A user message event in the session conversation.

      • id: string

        Unique identifier for this event.

      • content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock

        Array of content blocks comprising the user message.

        • BetaManagedAgentsTextBlock object { text, type }

          Regular text content.

          • text: string

            The text content.

          • type: "text"

            • "text"

        • BetaManagedAgentsImageBlock object { source, type }

          Image content specified directly as base64 data or as a reference via a URL.

          • source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource

            Union type for image source variants.

            • BetaManagedAgentsBase64ImageSource object { data, media_type, type }

              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 object { type, url }

              Image referenced by URL.

              • type: "url"

                • "url"

              • url: string

                URL of the image to fetch.

            • BetaManagedAgentsFileImageSource object { file_id, type }

              Image referenced by file ID.

              • file_id: string

                ID of a previously uploaded file.

              • type: "file"

                • "file"

          • type: "image"

            • "image"

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          Document content, either specified directly as base64 data, as text, or as a reference via a URL.

          • source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource

            Union type for document source variants.

            • BetaManagedAgentsBase64DocumentSource object { data, media_type, type }

              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 object { data, media_type, type }

              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 object { type, url }

              Document referenced by URL.

              • type: "url"

                • "url"

              • url: string

                URL of the document to fetch.

            • BetaManagedAgentsFileDocumentSource object { file_id, type }

              Document referenced by file ID.

              • file_id: string

                ID of a previously uploaded file.

              • type: "file"

                • "file"

          • type: "document"

            • "document"

          • context: optional string

            Additional context about the document for the model.

          • title: optional string

            The title of the document.

      • type: "user.message"

        • "user.message"

      • processed_at: optional string

        A timestamp in RFC 3339 format

    • BetaManagedAgentsUserInterruptEvent object { id, type, processed_at, session_thread_id }

      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: optional string

        A timestamp in RFC 3339 format

      • session_thread_id: optional string

        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 object { id, result, tool_use_id, 4 more }

      A tool confirmation event that approves or denies a pending tool execution.

      • id: string

        Unique identifier for this event.

      • result: "allow" or "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 stop_reason.event_ids field.

      • type: "user.tool_confirmation"

        • "user.tool_confirmation"

      • deny_message: optional string

        Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.

      • processed_at: optional string

        A timestamp in RFC 3339 format

      • session_thread_id: optional string

        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 object { id, custom_tool_use_id, type, 4 more }

      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 stop_reason.event_ids field.

      • type: "user.custom_tool_result"

        • "user.custom_tool_result"

      • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

        The result content returned by the tool.

        • BetaManagedAgentsTextBlock object { text, type }

          Regular text content.

        • BetaManagedAgentsImageBlock object { source, type }

          Image content specified directly as base64 data or as a reference via a URL.

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          Document content, either specified directly as base64 data, as text, or as a reference via a URL.

        • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

          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 of BetaManagedAgentsSearchResultContent

            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: optional boolean

        Whether the tool execution resulted in an error.

      • processed_at: optional string

        A timestamp in RFC 3339 format

      • session_thread_id: optional string

        Routes this result to a subagent thread. Copy from the agent.custom_tool_use event's session_thread_id.

    • BetaManagedAgentsAgentCustomToolUseEvent object { id, input, name, 3 more }

      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: map[unknown]

        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: optional string

        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 object { id, content, processed_at, type }

      An agent response event in the session conversation.

      • id: string

        Unique identifier for this event.

      • content: array of BetaManagedAgentsTextBlock

        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 object { id, processed_at, type }

      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 object { id, input, mcp_server_name, 5 more }

      Event emitted when the agent invokes a tool provided by an MCP server.

      • id: string

        Unique identifier for this event.

      • input: map[unknown]

        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: optional "allow" or "ask" or "deny"

        AgentEvaluatedPermission enum

        • "allow"

        • "ask"

        • "deny"

      • session_thread_id: optional string

        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 object { id, mcp_tool_use_id, processed_at, 3 more }

      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: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

        The result content returned by the tool.

        • BetaManagedAgentsTextBlock object { text, type }

          Regular text content.

        • BetaManagedAgentsImageBlock object { source, type }

          Image content specified directly as base64 data or as a reference via a URL.

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          Document content, either specified directly as base64 data, as text, or as a reference via a URL.

        • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

          A block containing a web search result.

      • is_error: optional boolean

        Whether the tool execution resulted in an error.

    • BetaManagedAgentsAgentToolUseEvent object { id, input, name, 4 more }

      Event emitted when the agent invokes a built-in agent tool.

      • id: string

        Unique identifier for this event.

      • input: map[unknown]

        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: optional "allow" or "ask" or "deny"

        AgentEvaluatedPermission enum

        • "allow"

        • "ask"

        • "deny"

      • session_thread_id: optional string

        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 object { id, processed_at, tool_use_id, 3 more }

      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: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

        The result content returned by the tool.

        • BetaManagedAgentsTextBlock object { text, type }

          Regular text content.

        • BetaManagedAgentsImageBlock object { source, type }

          Image content specified directly as base64 data or as a reference via a URL.

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          Document content, either specified directly as base64 data, as text, or as a reference via a URL.

        • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

          A block containing a web search result.

      • is_error: optional boolean

        Whether the tool execution resulted in an error.

    • BetaManagedAgentsAgentThreadMessageReceivedEvent object { id, content, from_session_thread_id, 3 more }

      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 of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock

        Message content blocks.

        • BetaManagedAgentsTextBlock object { text, type }

          Regular text content.

        • BetaManagedAgentsImageBlock object { source, type }

          Image content specified directly as base64 data or as a reference via a URL.

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          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: optional string

        Name of the callable agent this message came from. Absent when received from the primary agent.

    • BetaManagedAgentsAgentThreadMessageSentEvent object { id, content, processed_at, 3 more }

      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 of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock

        Message content blocks.

        • BetaManagedAgentsTextBlock object { text, type }

          Regular text content.

        • BetaManagedAgentsImageBlock object { source, type }

          Image content specified directly as base64 data or as a reference via a URL.

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          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: optional string

        Name of the callable agent this message was sent to. Absent when sent to the primary agent.

    • BetaManagedAgentsAgentThreadContextCompactedEvent object { id, processed_at, type }

      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 object { id, error, processed_at, type }

      An error event indicating a problem occurred during session execution.

      • id: string

        Unique identifier for this event.

      • error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 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 object { message, retry_status, type }

          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 or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            What the client should do next in response to this error.

            • BetaManagedAgentsRetryStatusRetrying object { type }

              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 object { type }

              This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

              • type: "exhausted"

                • "exhausted"

            • BetaManagedAgentsRetryStatusTerminal object { type }

              The session encountered a terminal error and will transition to terminated state.

              • type: "terminal"

                • "terminal"

          • type: "unknown_error"

            • "unknown_error"

        • BetaManagedAgentsModelOverloadedError object { message, retry_status, type }

          The model is currently overloaded. Emitted after automatic retries are exhausted.

          • message: string

            Human-readable error description.

          • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            What the client should do next in response to this error.

            • BetaManagedAgentsRetryStatusRetrying object { type }

              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 object { type }

              This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

            • BetaManagedAgentsRetryStatusTerminal object { type }

              The session encountered a terminal error and will transition to terminated state.

          • type: "model_overloaded_error"

            • "model_overloaded_error"

        • BetaManagedAgentsModelRateLimitedError object { message, retry_status, type }

          The model request was rate-limited.

          • message: string

            Human-readable error description.

          • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            What the client should do next in response to this error.

            • BetaManagedAgentsRetryStatusRetrying object { type }

              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 object { type }

              This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

            • BetaManagedAgentsRetryStatusTerminal object { type }

              The session encountered a terminal error and will transition to terminated state.

          • type: "model_rate_limited_error"

            • "model_rate_limited_error"

        • BetaManagedAgentsModelRequestFailedError object { message, retry_status, type }

          A model request failed for a reason other than overload or rate-limiting.

          • message: string

            Human-readable error description.

          • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            What the client should do next in response to this error.

            • BetaManagedAgentsRetryStatusRetrying object { type }

              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 object { type }

              This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

            • BetaManagedAgentsRetryStatusTerminal object { type }

              The session encountered a terminal error and will transition to terminated state.

          • type: "model_request_failed_error"

            • "model_request_failed_error"

        • BetaManagedAgentsMCPConnectionFailedError object { mcp_server_name, message, retry_status, type }

          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 or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            What the client should do next in response to this error.

            • BetaManagedAgentsRetryStatusRetrying object { type }

              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 object { type }

              This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

            • BetaManagedAgentsRetryStatusTerminal object { type }

              The session encountered a terminal error and will transition to terminated state.

          • type: "mcp_connection_failed_error"

            • "mcp_connection_failed_error"

        • BetaManagedAgentsMCPAuthenticationFailedError object { mcp_server_name, message, retry_status, type }

          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 or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            What the client should do next in response to this error.

            • BetaManagedAgentsRetryStatusRetrying object { type }

              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 object { type }

              This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

            • BetaManagedAgentsRetryStatusTerminal object { type }

              The session encountered a terminal error and will transition to terminated state.

          • type: "mcp_authentication_failed_error"

            • "mcp_authentication_failed_error"

        • BetaManagedAgentsBillingError object { message, retry_status, type }

          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 or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            What the client should do next in response to this error.

            • BetaManagedAgentsRetryStatusRetrying object { type }

              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 object { type }

              This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

            • BetaManagedAgentsRetryStatusTerminal object { type }

              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 object { id, processed_at, type }

      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 object { id, processed_at, type }

      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 object { id, processed_at, stop_reason, type }

      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 or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted

        The agent completed its turn naturally and is ready for the next user message.

        • BetaManagedAgentsSessionEndTurn object { type }

          The agent completed its turn naturally and is ready for the next user message.

          • type: "end_turn"

            • "end_turn"

        • BetaManagedAgentsSessionRequiresAction object { event_ids, type }

          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 of string

            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 object { type }

          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 object { id, processed_at, type }

      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 object { id, agent_name, processed_at, 2 more }

      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 object { id, iteration, outcome_id, 2 more }

      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 object { id, explanation, iteration, 6 more }

      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: optional "standard" or "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"

    • BetaManagedAgentsSpanModelRequestStartEvent object { id, processed_at, type }

      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 object { id, is_error, model_request_start_id, 3 more }

      Emitted when a model request completes.

      • id: string

        Unique identifier for this event.

      • is_error: boolean

        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 object { id, iteration, outcome_id, 2 more }

      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 object { id, description, max_iterations, 4 more }

      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

        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 or BetaManagedAgentsTextRubric

        Rubric for grading the quality of an outcome.

        • BetaManagedAgentsFileRubric object { file_id, type }

          Rubric referenced by a file uploaded via the Files API.

          • file_id: string

            ID of the rubric file.

          • type: "file"

            • "file"

        • BetaManagedAgentsTextRubric object { content, type }

          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 object { id, processed_at, type }

      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 object { id, agent_name, processed_at, 2 more }

      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 object { id, agent_name, processed_at, 3 more }

      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 or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted

        The agent completed its turn naturally and is ready for the next user message.

        • BetaManagedAgentsSessionEndTurn object { type }

          The agent completed its turn naturally and is ready for the next user message.

        • BetaManagedAgentsSessionRequiresAction object { event_ids, type }

          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 object { type }

          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 object { id, agent_name, processed_at, 2 more }

      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 object { id, tool_use_id, type, 4 more }

      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 stop_reason.event_ids field.

      • type: "user.tool_result"

        • "user.tool_result"

      • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

        The result content returned by the tool.

        • BetaManagedAgentsTextBlock object { text, type }

          Regular text content.

        • BetaManagedAgentsImageBlock object { source, type }

          Image content specified directly as base64 data or as a reference via a URL.

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          Document content, either specified directly as base64 data, as text, or as a reference via a URL.

        • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

          A block containing a web search result.

      • is_error: optional boolean

        Whether the tool execution resulted in an error.

      • processed_at: optional string

        A timestamp in RFC 3339 format

      • session_thread_id: optional string

        Routes this result to a subagent thread. Copy from the agent.tool_use event's session_thread_id.

    • BetaManagedAgentsSessionThreadStatusRescheduledEvent object { id, agent_name, processed_at, 2 more }

      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 object { id, processed_at, type, 3 more }

      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: optional BetaManagedAgentsSessionAgent

        Resolved agent definition for a session. Snapshot of the agent at session creation time.

        • id: string

        • description: string

        • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

          • name: string

          • type: "url"

            • "url"

          • url: string

        • model: BetaManagedAgentsModelConfig

          Model identifier and configuration.

          • id: BetaManagedAgentsModel

            The model that will power your agent.

            See models for additional details and options.

            • "claude-opus-4-7" or "claude-opus-4-6" or "claude-sonnet-4-6" or 6 more

              The model that will power your agent.

              See models for additional details and options.

              • "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: optional "standard" or "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

          Resolved coordinator topology with full agent definitions for each roster member.

          • agents: array of BetaManagedAgentsSessionThreadAgent

            Full agent definitions the coordinator may spawn as session threads.

            • id: string

            • description: string

            • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

              • name: string

              • type: "url"

              • url: string

            • model: BetaManagedAgentsModelConfig

              Model identifier and configuration.

            • name: string

            • skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

              • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

                A resolved Anthropic-managed skill.

                • skill_id: string

                • type: "anthropic"

                  • "anthropic"

                • version: string

              • BetaManagedAgentsCustomSkill object { skill_id, type, version }

                A resolved user-created custom skill.

                • skill_id: string

                • type: "custom"

                  • "custom"

                • version: string

            • system: string

            • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

              • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

                • configs: array of BetaManagedAgentsAgentToolConfig

                  • enabled: boolean

                  • name: "bash" or "edit" or "read" or 5 more

                    Built-in agent tool identifier.

                    • "bash"

                    • "edit"

                    • "read"

                    • "write"

                    • "glob"

                    • "grep"

                    • "web_fetch"

                    • "web_search"

                  • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                    Permission policy for tool execution.

                    • BetaManagedAgentsAlwaysAllowPolicy object { type }

                      Tool calls are automatically approved without user confirmation.

                      • type: "always_allow"

                        • "always_allow"

                    • BetaManagedAgentsAlwaysAskPolicy object { type }

                      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 or BetaManagedAgentsAlwaysAskPolicy

                    Permission policy for tool execution.

                    • BetaManagedAgentsAlwaysAllowPolicy object { type }

                      Tool calls are automatically approved without user confirmation.

                    • BetaManagedAgentsAlwaysAskPolicy object { type }

                      Tool calls require user confirmation before execution.

                • type: "agent_toolset_20260401"

                  • "agent_toolset_20260401"

              • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

                • configs: array of BetaManagedAgentsMCPToolConfig

                  • enabled: boolean

                  • name: string

                  • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                    Permission policy for tool execution.

                    • BetaManagedAgentsAlwaysAllowPolicy object { type }

                      Tool calls are automatically approved without user confirmation.

                    • BetaManagedAgentsAlwaysAskPolicy object { type }

                      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 or BetaManagedAgentsAlwaysAskPolicy

                    Permission policy for tool execution.

                    • BetaManagedAgentsAlwaysAllowPolicy object { type }

                      Tool calls are automatically approved without user confirmation.

                    • BetaManagedAgentsAlwaysAskPolicy object { type }

                      Tool calls require user confirmation before execution.

                • mcp_server_name: string

                • type: "mcp_toolset"

                  • "mcp_toolset"

              • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

                A custom tool as returned in API responses.

                • description: string

                • input_schema: BetaManagedAgentsCustomToolInputSchema

                  JSON Schema for custom tool input parameters.

                  • properties: optional map[unknown]

                    JSON Schema properties defining the tool's input parameters.

                  • required: optional array of string

                    List of required property names.

                  • type: optional "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 of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

          • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

            A resolved Anthropic-managed skill.

          • BetaManagedAgentsCustomSkill object { skill_id, type, version }

            A resolved user-created custom skill.

        • system: string

        • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

          • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

          • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

          • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

            A custom tool as returned in API responses.

        • type: "agent"

          • "agent"

        • version: number

      • metadata: optional map[string]

        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: optional string

        The session's new title. Present only when the update changed it.

Example

curl https://api.anthropic.com/v1/sessions/$SESSION_ID/events/stream \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: managed-agents-2026-04-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

Response

{
  "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 object { id, input, name, 3 more }

    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: map[unknown]

      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: optional string

      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 object { id, mcp_tool_use_id, processed_at, 3 more }

    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: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

      The result content returned by the tool.

      • BetaManagedAgentsTextBlock object { text, type }

        Regular text content.

        • text: string

          The text content.

        • type: "text"

          • "text"

      • BetaManagedAgentsImageBlock object { source, type }

        Image content specified directly as base64 data or as a reference via a URL.

        • source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource

          Union type for image source variants.

          • BetaManagedAgentsBase64ImageSource object { data, media_type, type }

            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 object { type, url }

            Image referenced by URL.

            • type: "url"

              • "url"

            • url: string

              URL of the image to fetch.

          • BetaManagedAgentsFileImageSource object { file_id, type }

            Image referenced by file ID.

            • file_id: string

              ID of a previously uploaded file.

            • type: "file"

              • "file"

        • type: "image"

          • "image"

      • BetaManagedAgentsDocumentBlock object { source, type, context, title }

        Document content, either specified directly as base64 data, as text, or as a reference via a URL.

        • source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource

          Union type for document source variants.

          • BetaManagedAgentsBase64DocumentSource object { data, media_type, type }

            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 object { data, media_type, type }

            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 object { type, url }

            Document referenced by URL.

            • type: "url"

              • "url"

            • url: string

              URL of the document to fetch.

          • BetaManagedAgentsFileDocumentSource object { file_id, type }

            Document referenced by file ID.

            • file_id: string

              ID of a previously uploaded file.

            • type: "file"

              • "file"

        • type: "document"

          • "document"

        • context: optional string

          Additional context about the document for the model.

        • title: optional string

          The title of the document.

      • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

        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 of BetaManagedAgentsSearchResultContent

          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: optional boolean

      Whether the tool execution resulted in an error.

Beta Managed Agents Agent MCP Tool Use Event

  • BetaManagedAgentsAgentMCPToolUseEvent object { id, input, mcp_server_name, 5 more }

    Event emitted when the agent invokes a tool provided by an MCP server.

    • id: string

      Unique identifier for this event.

    • input: map[unknown]

      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: optional "allow" or "ask" or "deny"

      AgentEvaluatedPermission enum

      • "allow"

      • "ask"

      • "deny"

    • session_thread_id: optional string

      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 object { id, content, processed_at, type }

    An agent response event in the session conversation.

    • id: string

      Unique identifier for this event.

    • content: array of BetaManagedAgentsTextBlock

      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 object { id, processed_at, type }

    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 object { id, processed_at, type }

    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 object { id, content, from_session_thread_id, 3 more }

    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 of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock

      Message content blocks.

      • BetaManagedAgentsTextBlock object { text, type }

        Regular text content.

        • text: string

          The text content.

        • type: "text"

          • "text"

      • BetaManagedAgentsImageBlock object { source, type }

        Image content specified directly as base64 data or as a reference via a URL.

        • source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource

          Union type for image source variants.

          • BetaManagedAgentsBase64ImageSource object { data, media_type, type }

            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 object { type, url }

            Image referenced by URL.

            • type: "url"

              • "url"

            • url: string

              URL of the image to fetch.

          • BetaManagedAgentsFileImageSource object { file_id, type }

            Image referenced by file ID.

            • file_id: string

              ID of a previously uploaded file.

            • type: "file"

              • "file"

        • type: "image"

          • "image"

      • BetaManagedAgentsDocumentBlock object { source, type, context, title }

        Document content, either specified directly as base64 data, as text, or as a reference via a URL.

        • source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource

          Union type for document source variants.

          • BetaManagedAgentsBase64DocumentSource object { data, media_type, type }

            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 object { data, media_type, type }

            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 object { type, url }

            Document referenced by URL.

            • type: "url"

              • "url"

            • url: string

              URL of the document to fetch.

          • BetaManagedAgentsFileDocumentSource object { file_id, type }

            Document referenced by file ID.

            • file_id: string

              ID of a previously uploaded file.

            • type: "file"

              • "file"

        • type: "document"

          • "document"

        • context: optional string

          Additional context about the document for the model.

        • title: optional string

          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: optional string

      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 object { id, content, processed_at, 3 more }

    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 of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock

      Message content blocks.

      • BetaManagedAgentsTextBlock object { text, type }

        Regular text content.

        • text: string

          The text content.

        • type: "text"

          • "text"

      • BetaManagedAgentsImageBlock object { source, type }

        Image content specified directly as base64 data or as a reference via a URL.

        • source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource

          Union type for image source variants.

          • BetaManagedAgentsBase64ImageSource object { data, media_type, type }

            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 object { type, url }

            Image referenced by URL.

            • type: "url"

              • "url"

            • url: string

              URL of the image to fetch.

          • BetaManagedAgentsFileImageSource object { file_id, type }

            Image referenced by file ID.

            • file_id: string

              ID of a previously uploaded file.

            • type: "file"

              • "file"

        • type: "image"

          • "image"

      • BetaManagedAgentsDocumentBlock object { source, type, context, title }

        Document content, either specified directly as base64 data, as text, or as a reference via a URL.

        • source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource

          Union type for document source variants.

          • BetaManagedAgentsBase64DocumentSource object { data, media_type, type }

            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 object { data, media_type, type }

            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 object { type, url }

            Document referenced by URL.

            • type: "url"

              • "url"

            • url: string

              URL of the document to fetch.

          • BetaManagedAgentsFileDocumentSource object { file_id, type }

            Document referenced by file ID.

            • file_id: string

              ID of a previously uploaded file.

            • type: "file"

              • "file"

        • type: "document"

          • "document"

        • context: optional string

          Additional context about the document for the model.

        • title: optional string

          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: optional string

      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 object { id, processed_at, tool_use_id, 3 more }

    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: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

      The result content returned by the tool.

      • BetaManagedAgentsTextBlock object { text, type }

        Regular text content.

        • text: string

          The text content.

        • type: "text"

          • "text"

      • BetaManagedAgentsImageBlock object { source, type }

        Image content specified directly as base64 data or as a reference via a URL.

        • source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource

          Union type for image source variants.

          • BetaManagedAgentsBase64ImageSource object { data, media_type, type }

            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 object { type, url }

            Image referenced by URL.

            • type: "url"

              • "url"

            • url: string

              URL of the image to fetch.

          • BetaManagedAgentsFileImageSource object { file_id, type }

            Image referenced by file ID.

            • file_id: string

              ID of a previously uploaded file.

            • type: "file"

              • "file"

        • type: "image"

          • "image"

      • BetaManagedAgentsDocumentBlock object { source, type, context, title }

        Document content, either specified directly as base64 data, as text, or as a reference via a URL.

        • source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource

          Union type for document source variants.

          • BetaManagedAgentsBase64DocumentSource object { data, media_type, type }

            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 object { data, media_type, type }

            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 object { type, url }

            Document referenced by URL.

            • type: "url"

              • "url"

            • url: string

              URL of the document to fetch.

          • BetaManagedAgentsFileDocumentSource object { file_id, type }

            Document referenced by file ID.

            • file_id: string

              ID of a previously uploaded file.

            • type: "file"

              • "file"

        • type: "document"

          • "document"

        • context: optional string

          Additional context about the document for the model.

        • title: optional string

          The title of the document.

      • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

        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 of BetaManagedAgentsSearchResultContent

          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: optional boolean

      Whether the tool execution resulted in an error.

Beta Managed Agents Agent Tool Use Event

  • BetaManagedAgentsAgentToolUseEvent object { id, input, name, 4 more }

    Event emitted when the agent invokes a built-in agent tool.

    • id: string

      Unique identifier for this event.

    • input: map[unknown]

      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: optional "allow" or "ask" or "deny"

      AgentEvaluatedPermission enum

      • "allow"

      • "ask"

      • "deny"

    • session_thread_id: optional string

      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 object { data, media_type, type }

    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 object { data, media_type, type }

    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 object { message, retry_status, type }

    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 or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

      What the client should do next in response to this error.

      • BetaManagedAgentsRetryStatusRetrying object { type }

        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 object { type }

        This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

        • type: "exhausted"

          • "exhausted"

      • BetaManagedAgentsRetryStatusTerminal object { type }

        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 object { source, type, context, title }

    Document content, either specified directly as base64 data, as text, or as a reference via a URL.

    • source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource

      Union type for document source variants.

      • BetaManagedAgentsBase64DocumentSource object { data, media_type, type }

        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 object { data, media_type, type }

        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 object { type, url }

        Document referenced by URL.

        • type: "url"

          • "url"

        • url: string

          URL of the document to fetch.

      • BetaManagedAgentsFileDocumentSource object { file_id, type }

        Document referenced by file ID.

        • file_id: string

          ID of a previously uploaded file.

        • type: "file"

          • "file"

    • type: "document"

      • "document"

    • context: optional string

      Additional context about the document for the model.

    • title: optional string

      The title of the document.

Beta Managed Agents Event Params

  • BetaManagedAgentsEventParams = BetaManagedAgentsUserMessageEventParams or BetaManagedAgentsUserInterruptEventParams or BetaManagedAgentsUserToolConfirmationEventParams or 3 more

    Union type for event parameters that can be sent to a session.

    • BetaManagedAgentsUserMessageEventParams object { content, type }

      Parameters for sending a user message to the session.

      • content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock

        Array of content blocks for the user message.

        • BetaManagedAgentsTextBlock object { text, type }

          Regular text content.

          • text: string

            The text content.

          • type: "text"

            • "text"

        • BetaManagedAgentsImageBlock object { source, type }

          Image content specified directly as base64 data or as a reference via a URL.

          • source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource

            Union type for image source variants.

            • BetaManagedAgentsBase64ImageSource object { data, media_type, type }

              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 object { type, url }

              Image referenced by URL.

              • type: "url"

                • "url"

              • url: string

                URL of the image to fetch.

            • BetaManagedAgentsFileImageSource object { file_id, type }

              Image referenced by file ID.

              • file_id: string

                ID of a previously uploaded file.

              • type: "file"

                • "file"

          • type: "image"

            • "image"

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          Document content, either specified directly as base64 data, as text, or as a reference via a URL.

          • source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource

            Union type for document source variants.

            • BetaManagedAgentsBase64DocumentSource object { data, media_type, type }

              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 object { data, media_type, type }

              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 object { type, url }

              Document referenced by URL.

              • type: "url"

                • "url"

              • url: string

                URL of the document to fetch.

            • BetaManagedAgentsFileDocumentSource object { file_id, type }

              Document referenced by file ID.

              • file_id: string

                ID of a previously uploaded file.

              • type: "file"

                • "file"

          • type: "document"

            • "document"

          • context: optional string

            Additional context about the document for the model.

          • title: optional string

            The title of the document.

      • type: "user.message"

        • "user.message"

    • BetaManagedAgentsUserInterruptEventParams object { type, session_thread_id }

      Parameters for sending an interrupt to pause the agent.

      • type: "user.interrupt"

        • "user.interrupt"

      • session_thread_id: optional string

        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 object { result, tool_use_id, type, deny_message }

      Parameters for confirming or denying a tool execution request.

      • result: "allow" or "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 stop_reason.event_ids field.

      • type: "user.tool_confirmation"

        • "user.tool_confirmation"

      • deny_message: optional string

        Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.

    • BetaManagedAgentsUserCustomToolResultEventParams object { custom_tool_use_id, type, content, is_error }

      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 stop_reason.event_ids field.

      • type: "user.custom_tool_result"

        • "user.custom_tool_result"

      • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

        The result content returned by the tool.

        • BetaManagedAgentsTextBlock object { text, type }

          Regular text content.

        • BetaManagedAgentsImageBlock object { source, type }

          Image content specified directly as base64 data or as a reference via a URL.

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          Document content, either specified directly as base64 data, as text, or as a reference via a URL.

        • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

          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 of BetaManagedAgentsSearchResultContent

            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: optional boolean

        Whether the tool execution resulted in an error.

    • BetaManagedAgentsUserDefineOutcomeEventParams object { description, rubric, type, max_iterations }

      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 or BetaManagedAgentsTextRubricParams

        Rubric for grading the quality of an outcome.

        • BetaManagedAgentsFileRubricParams object { file_id, type }

          Rubric referenced by a file uploaded via the Files API.

          • file_id: string

            ID of the rubric file.

          • type: "file"

            • "file"

        • BetaManagedAgentsTextRubricParams object { content, type }

          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: optional number

        Eval→revision cycles before giving up. Default 3, max 20.

    • BetaManagedAgentsUserToolResultEventParams object { tool_use_id, type, content, is_error }

      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 stop_reason.event_ids field.

      • type: "user.tool_result"

        • "user.tool_result"

      • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

        The result content returned by the tool.

        • BetaManagedAgentsTextBlock object { text, type }

          Regular text content.

        • BetaManagedAgentsImageBlock object { source, type }

          Image content specified directly as base64 data or as a reference via a URL.

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          Document content, either specified directly as base64 data, as text, or as a reference via a URL.

        • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

          A block containing a web search result.

      • is_error: optional boolean

        Whether the tool execution resulted in an error.

Beta Managed Agents File Document Source

  • BetaManagedAgentsFileDocumentSource object { file_id, type }

    Document referenced by file ID.

    • file_id: string

      ID of a previously uploaded file.

    • type: "file"

      • "file"

Beta Managed Agents File Image Source

  • BetaManagedAgentsFileImageSource object { file_id, type }

    Image referenced by file ID.

    • file_id: string

      ID of a previously uploaded file.

    • type: "file"

      • "file"

Beta Managed Agents File Rubric

  • BetaManagedAgentsFileRubric object { file_id, type }

    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 object { file_id, type }

    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 object { source, type }

    Image content specified directly as base64 data or as a reference via a URL.

    • source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource

      Union type for image source variants.

      • BetaManagedAgentsBase64ImageSource object { data, media_type, type }

        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 object { type, url }

        Image referenced by URL.

        • type: "url"

          • "url"

        • url: string

          URL of the image to fetch.

      • BetaManagedAgentsFileImageSource object { file_id, type }

        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 object { mcp_server_name, message, retry_status, type }

    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 or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

      What the client should do next in response to this error.

      • BetaManagedAgentsRetryStatusRetrying object { type }

        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 object { type }

        This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

        • type: "exhausted"

          • "exhausted"

      • BetaManagedAgentsRetryStatusTerminal object { type }

        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 object { mcp_server_name, message, retry_status, type }

    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 or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

      What the client should do next in response to this error.

      • BetaManagedAgentsRetryStatusRetrying object { type }

        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 object { type }

        This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

        • type: "exhausted"

          • "exhausted"

      • BetaManagedAgentsRetryStatusTerminal object { type }

        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 object { message, retry_status, type }

    The model is currently overloaded. Emitted after automatic retries are exhausted.

    • message: string

      Human-readable error description.

    • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

      What the client should do next in response to this error.

      • BetaManagedAgentsRetryStatusRetrying object { type }

        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 object { type }

        This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

        • type: "exhausted"

          • "exhausted"

      • BetaManagedAgentsRetryStatusTerminal object { type }

        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 object { message, retry_status, type }

    The model request was rate-limited.

    • message: string

      Human-readable error description.

    • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

      What the client should do next in response to this error.

      • BetaManagedAgentsRetryStatusRetrying object { type }

        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 object { type }

        This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

        • type: "exhausted"

          • "exhausted"

      • BetaManagedAgentsRetryStatusTerminal object { type }

        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 object { message, retry_status, type }

    A model request failed for a reason other than overload or rate-limiting.

    • message: string

      Human-readable error description.

    • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

      What the client should do next in response to this error.

      • BetaManagedAgentsRetryStatusRetrying object { type }

        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 object { type }

        This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

        • type: "exhausted"

          • "exhausted"

      • BetaManagedAgentsRetryStatusTerminal object { type }

        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 object { data, media_type, type }

    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 object { type }

    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 object { type }

    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 object { type }

    The session encountered a terminal error and will transition to terminated state.

    • type: "terminal"

      • "terminal"

Beta Managed Agents Search Result Block

  • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

    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 of BetaManagedAgentsSearchResultContent

      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 object { enabled }

    Citation settings for a search result.

    • enabled: boolean

      Whether citations are enabled for this search result.

Beta Managed Agents Search Result Content

  • BetaManagedAgentsSearchResultContent object { text, type }

    Text content within a search result.

    • text: string

      The text content.

    • type: "text"

      • "text"

Beta Managed Agents Send Session Events

  • BetaManagedAgentsSendSessionEvents object { data }

    Events that were successfully sent to the session.

    • data: optional array of BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or 3 more

      Sent events

      • BetaManagedAgentsUserMessageEvent object { id, content, type, processed_at }

        A user message event in the session conversation.

        • id: string

          Unique identifier for this event.

        • content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock

          Array of content blocks comprising the user message.

          • BetaManagedAgentsTextBlock object { text, type }

            Regular text content.

            • text: string

              The text content.

            • type: "text"

              • "text"

          • BetaManagedAgentsImageBlock object { source, type }

            Image content specified directly as base64 data or as a reference via a URL.

            • source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource

              Union type for image source variants.

              • BetaManagedAgentsBase64ImageSource object { data, media_type, type }

                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 object { type, url }

                Image referenced by URL.

                • type: "url"

                  • "url"

                • url: string

                  URL of the image to fetch.

              • BetaManagedAgentsFileImageSource object { file_id, type }

                Image referenced by file ID.

                • file_id: string

                  ID of a previously uploaded file.

                • type: "file"

                  • "file"

            • type: "image"

              • "image"

          • BetaManagedAgentsDocumentBlock object { source, type, context, title }

            Document content, either specified directly as base64 data, as text, or as a reference via a URL.

            • source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource

              Union type for document source variants.

              • BetaManagedAgentsBase64DocumentSource object { data, media_type, type }

                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 object { data, media_type, type }

                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 object { type, url }

                Document referenced by URL.

                • type: "url"

                  • "url"

                • url: string

                  URL of the document to fetch.

              • BetaManagedAgentsFileDocumentSource object { file_id, type }

                Document referenced by file ID.

                • file_id: string

                  ID of a previously uploaded file.

                • type: "file"

                  • "file"

            • type: "document"

              • "document"

            • context: optional string

              Additional context about the document for the model.

            • title: optional string

              The title of the document.

        • type: "user.message"

          • "user.message"

        • processed_at: optional string

          A timestamp in RFC 3339 format

      • BetaManagedAgentsUserInterruptEvent object { id, type, processed_at, session_thread_id }

        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: optional string

          A timestamp in RFC 3339 format

        • session_thread_id: optional string

          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 object { id, result, tool_use_id, 4 more }

        A tool confirmation event that approves or denies a pending tool execution.

        • id: string

          Unique identifier for this event.

        • result: "allow" or "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 stop_reason.event_ids field.

        • type: "user.tool_confirmation"

          • "user.tool_confirmation"

        • deny_message: optional string

          Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.

        • processed_at: optional string

          A timestamp in RFC 3339 format

        • session_thread_id: optional string

          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 object { id, custom_tool_use_id, type, 4 more }

        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 stop_reason.event_ids field.

        • type: "user.custom_tool_result"

          • "user.custom_tool_result"

        • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

          The result content returned by the tool.

          • BetaManagedAgentsTextBlock object { text, type }

            Regular text content.

          • BetaManagedAgentsImageBlock object { source, type }

            Image content specified directly as base64 data or as a reference via a URL.

          • BetaManagedAgentsDocumentBlock object { source, type, context, title }

            Document content, either specified directly as base64 data, as text, or as a reference via a URL.

          • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

            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 of BetaManagedAgentsSearchResultContent

              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: optional boolean

          Whether the tool execution resulted in an error.

        • processed_at: optional string

          A timestamp in RFC 3339 format

        • session_thread_id: optional string

          Routes this result to a subagent thread. Copy from the agent.custom_tool_use event's session_thread_id.

      • BetaManagedAgentsUserDefineOutcomeEvent object { id, description, max_iterations, 4 more }

        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

          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 or BetaManagedAgentsTextRubric

          Rubric for grading the quality of an outcome.

          • BetaManagedAgentsFileRubric object { file_id, type }

            Rubric referenced by a file uploaded via the Files API.

            • file_id: string

              ID of the rubric file.

            • type: "file"

              • "file"

          • BetaManagedAgentsTextRubric object { content, type }

            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 object { id, tool_use_id, type, 4 more }

        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 stop_reason.event_ids field.

        • type: "user.tool_result"

          • "user.tool_result"

        • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

          The result content returned by the tool.

          • BetaManagedAgentsTextBlock object { text, type }

            Regular text content.

          • BetaManagedAgentsImageBlock object { source, type }

            Image content specified directly as base64 data or as a reference via a URL.

          • BetaManagedAgentsDocumentBlock object { source, type, context, title }

            Document content, either specified directly as base64 data, as text, or as a reference via a URL.

          • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

            A block containing a web search result.

        • is_error: optional boolean

          Whether the tool execution resulted in an error.

        • processed_at: optional string

          A timestamp in RFC 3339 format

        • session_thread_id: optional string

          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 object { id, processed_at, type }

    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 object { type }

    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 object { id, error, processed_at, type }

    An error event indicating a problem occurred during session execution.

    • id: string

      Unique identifier for this event.

    • error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 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 object { message, retry_status, type }

        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 or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

          What the client should do next in response to this error.

          • BetaManagedAgentsRetryStatusRetrying object { type }

            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 object { type }

            This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

            • type: "exhausted"

              • "exhausted"

          • BetaManagedAgentsRetryStatusTerminal object { type }

            The session encountered a terminal error and will transition to terminated state.

            • type: "terminal"

              • "terminal"

        • type: "unknown_error"

          • "unknown_error"

      • BetaManagedAgentsModelOverloadedError object { message, retry_status, type }

        The model is currently overloaded. Emitted after automatic retries are exhausted.

        • message: string

          Human-readable error description.

        • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

          What the client should do next in response to this error.

          • BetaManagedAgentsRetryStatusRetrying object { type }

            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 object { type }

            This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

          • BetaManagedAgentsRetryStatusTerminal object { type }

            The session encountered a terminal error and will transition to terminated state.

        • type: "model_overloaded_error"

          • "model_overloaded_error"

      • BetaManagedAgentsModelRateLimitedError object { message, retry_status, type }

        The model request was rate-limited.

        • message: string

          Human-readable error description.

        • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

          What the client should do next in response to this error.

          • BetaManagedAgentsRetryStatusRetrying object { type }

            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 object { type }

            This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

          • BetaManagedAgentsRetryStatusTerminal object { type }

            The session encountered a terminal error and will transition to terminated state.

        • type: "model_rate_limited_error"

          • "model_rate_limited_error"

      • BetaManagedAgentsModelRequestFailedError object { message, retry_status, type }

        A model request failed for a reason other than overload or rate-limiting.

        • message: string

          Human-readable error description.

        • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

          What the client should do next in response to this error.

          • BetaManagedAgentsRetryStatusRetrying object { type }

            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 object { type }

            This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

          • BetaManagedAgentsRetryStatusTerminal object { type }

            The session encountered a terminal error and will transition to terminated state.

        • type: "model_request_failed_error"

          • "model_request_failed_error"

      • BetaManagedAgentsMCPConnectionFailedError object { mcp_server_name, message, retry_status, type }

        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 or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

          What the client should do next in response to this error.

          • BetaManagedAgentsRetryStatusRetrying object { type }

            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 object { type }

            This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

          • BetaManagedAgentsRetryStatusTerminal object { type }

            The session encountered a terminal error and will transition to terminated state.

        • type: "mcp_connection_failed_error"

          • "mcp_connection_failed_error"

      • BetaManagedAgentsMCPAuthenticationFailedError object { mcp_server_name, message, retry_status, type }

        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 or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

          What the client should do next in response to this error.

          • BetaManagedAgentsRetryStatusRetrying object { type }

            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 object { type }

            This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

          • BetaManagedAgentsRetryStatusTerminal object { type }

            The session encountered a terminal error and will transition to terminated state.

        • type: "mcp_authentication_failed_error"

          • "mcp_authentication_failed_error"

      • BetaManagedAgentsBillingError object { message, retry_status, type }

        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 or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

          What the client should do next in response to this error.

          • BetaManagedAgentsRetryStatusRetrying object { type }

            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 object { type }

            This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

          • BetaManagedAgentsRetryStatusTerminal object { type }

            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 or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or 30 more

    Union type for all event types in a session.

    • BetaManagedAgentsUserMessageEvent object { id, content, type, processed_at }

      A user message event in the session conversation.

      • id: string

        Unique identifier for this event.

      • content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock

        Array of content blocks comprising the user message.

        • BetaManagedAgentsTextBlock object { text, type }

          Regular text content.

          • text: string

            The text content.

          • type: "text"

            • "text"

        • BetaManagedAgentsImageBlock object { source, type }

          Image content specified directly as base64 data or as a reference via a URL.

          • source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource

            Union type for image source variants.

            • BetaManagedAgentsBase64ImageSource object { data, media_type, type }

              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 object { type, url }

              Image referenced by URL.

              • type: "url"

                • "url"

              • url: string

                URL of the image to fetch.

            • BetaManagedAgentsFileImageSource object { file_id, type }

              Image referenced by file ID.

              • file_id: string

                ID of a previously uploaded file.

              • type: "file"

                • "file"

          • type: "image"

            • "image"

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          Document content, either specified directly as base64 data, as text, or as a reference via a URL.

          • source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource

            Union type for document source variants.

            • BetaManagedAgentsBase64DocumentSource object { data, media_type, type }

              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 object { data, media_type, type }

              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 object { type, url }

              Document referenced by URL.

              • type: "url"

                • "url"

              • url: string

                URL of the document to fetch.

            • BetaManagedAgentsFileDocumentSource object { file_id, type }

              Document referenced by file ID.

              • file_id: string

                ID of a previously uploaded file.

              • type: "file"

                • "file"

          • type: "document"

            • "document"

          • context: optional string

            Additional context about the document for the model.

          • title: optional string

            The title of the document.

      • type: "user.message"

        • "user.message"

      • processed_at: optional string

        A timestamp in RFC 3339 format

    • BetaManagedAgentsUserInterruptEvent object { id, type, processed_at, session_thread_id }

      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: optional string

        A timestamp in RFC 3339 format

      • session_thread_id: optional string

        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 object { id, result, tool_use_id, 4 more }

      A tool confirmation event that approves or denies a pending tool execution.

      • id: string

        Unique identifier for this event.

      • result: "allow" or "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 stop_reason.event_ids field.

      • type: "user.tool_confirmation"

        • "user.tool_confirmation"

      • deny_message: optional string

        Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.

      • processed_at: optional string

        A timestamp in RFC 3339 format

      • session_thread_id: optional string

        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 object { id, custom_tool_use_id, type, 4 more }

      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 stop_reason.event_ids field.

      • type: "user.custom_tool_result"

        • "user.custom_tool_result"

      • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

        The result content returned by the tool.

        • BetaManagedAgentsTextBlock object { text, type }

          Regular text content.

        • BetaManagedAgentsImageBlock object { source, type }

          Image content specified directly as base64 data or as a reference via a URL.

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          Document content, either specified directly as base64 data, as text, or as a reference via a URL.

        • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

          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 of BetaManagedAgentsSearchResultContent

            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: optional boolean

        Whether the tool execution resulted in an error.

      • processed_at: optional string

        A timestamp in RFC 3339 format

      • session_thread_id: optional string

        Routes this result to a subagent thread. Copy from the agent.custom_tool_use event's session_thread_id.

    • BetaManagedAgentsAgentCustomToolUseEvent object { id, input, name, 3 more }

      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: map[unknown]

        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: optional string

        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 object { id, content, processed_at, type }

      An agent response event in the session conversation.

      • id: string

        Unique identifier for this event.

      • content: array of BetaManagedAgentsTextBlock

        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 object { id, processed_at, type }

      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 object { id, input, mcp_server_name, 5 more }

      Event emitted when the agent invokes a tool provided by an MCP server.

      • id: string

        Unique identifier for this event.

      • input: map[unknown]

        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: optional "allow" or "ask" or "deny"

        AgentEvaluatedPermission enum

        • "allow"

        • "ask"

        • "deny"

      • session_thread_id: optional string

        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 object { id, mcp_tool_use_id, processed_at, 3 more }

      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: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

        The result content returned by the tool.

        • BetaManagedAgentsTextBlock object { text, type }

          Regular text content.

        • BetaManagedAgentsImageBlock object { source, type }

          Image content specified directly as base64 data or as a reference via a URL.

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          Document content, either specified directly as base64 data, as text, or as a reference via a URL.

        • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

          A block containing a web search result.

      • is_error: optional boolean

        Whether the tool execution resulted in an error.

    • BetaManagedAgentsAgentToolUseEvent object { id, input, name, 4 more }

      Event emitted when the agent invokes a built-in agent tool.

      • id: string

        Unique identifier for this event.

      • input: map[unknown]

        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: optional "allow" or "ask" or "deny"

        AgentEvaluatedPermission enum

        • "allow"

        • "ask"

        • "deny"

      • session_thread_id: optional string

        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 object { id, processed_at, tool_use_id, 3 more }

      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: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

        The result content returned by the tool.

        • BetaManagedAgentsTextBlock object { text, type }

          Regular text content.

        • BetaManagedAgentsImageBlock object { source, type }

          Image content specified directly as base64 data or as a reference via a URL.

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          Document content, either specified directly as base64 data, as text, or as a reference via a URL.

        • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

          A block containing a web search result.

      • is_error: optional boolean

        Whether the tool execution resulted in an error.

    • BetaManagedAgentsAgentThreadMessageReceivedEvent object { id, content, from_session_thread_id, 3 more }

      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 of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock

        Message content blocks.

        • BetaManagedAgentsTextBlock object { text, type }

          Regular text content.

        • BetaManagedAgentsImageBlock object { source, type }

          Image content specified directly as base64 data or as a reference via a URL.

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          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: optional string

        Name of the callable agent this message came from. Absent when received from the primary agent.

    • BetaManagedAgentsAgentThreadMessageSentEvent object { id, content, processed_at, 3 more }

      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 of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock

        Message content blocks.

        • BetaManagedAgentsTextBlock object { text, type }

          Regular text content.

        • BetaManagedAgentsImageBlock object { source, type }

          Image content specified directly as base64 data or as a reference via a URL.

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          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: optional string

        Name of the callable agent this message was sent to. Absent when sent to the primary agent.

    • BetaManagedAgentsAgentThreadContextCompactedEvent object { id, processed_at, type }

      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 object { id, error, processed_at, type }

      An error event indicating a problem occurred during session execution.

      • id: string

        Unique identifier for this event.

      • error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 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 object { message, retry_status, type }

          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 or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            What the client should do next in response to this error.

            • BetaManagedAgentsRetryStatusRetrying object { type }

              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 object { type }

              This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

              • type: "exhausted"

                • "exhausted"

            • BetaManagedAgentsRetryStatusTerminal object { type }

              The session encountered a terminal error and will transition to terminated state.

              • type: "terminal"

                • "terminal"

          • type: "unknown_error"

            • "unknown_error"

        • BetaManagedAgentsModelOverloadedError object { message, retry_status, type }

          The model is currently overloaded. Emitted after automatic retries are exhausted.

          • message: string

            Human-readable error description.

          • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            What the client should do next in response to this error.

            • BetaManagedAgentsRetryStatusRetrying object { type }

              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 object { type }

              This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

            • BetaManagedAgentsRetryStatusTerminal object { type }

              The session encountered a terminal error and will transition to terminated state.

          • type: "model_overloaded_error"

            • "model_overloaded_error"

        • BetaManagedAgentsModelRateLimitedError object { message, retry_status, type }

          The model request was rate-limited.

          • message: string

            Human-readable error description.

          • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            What the client should do next in response to this error.

            • BetaManagedAgentsRetryStatusRetrying object { type }

              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 object { type }

              This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

            • BetaManagedAgentsRetryStatusTerminal object { type }

              The session encountered a terminal error and will transition to terminated state.

          • type: "model_rate_limited_error"

            • "model_rate_limited_error"

        • BetaManagedAgentsModelRequestFailedError object { message, retry_status, type }

          A model request failed for a reason other than overload or rate-limiting.

          • message: string

            Human-readable error description.

          • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            What the client should do next in response to this error.

            • BetaManagedAgentsRetryStatusRetrying object { type }

              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 object { type }

              This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

            • BetaManagedAgentsRetryStatusTerminal object { type }

              The session encountered a terminal error and will transition to terminated state.

          • type: "model_request_failed_error"

            • "model_request_failed_error"

        • BetaManagedAgentsMCPConnectionFailedError object { mcp_server_name, message, retry_status, type }

          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 or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            What the client should do next in response to this error.

            • BetaManagedAgentsRetryStatusRetrying object { type }

              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 object { type }

              This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

            • BetaManagedAgentsRetryStatusTerminal object { type }

              The session encountered a terminal error and will transition to terminated state.

          • type: "mcp_connection_failed_error"

            • "mcp_connection_failed_error"

        • BetaManagedAgentsMCPAuthenticationFailedError object { mcp_server_name, message, retry_status, type }

          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 or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            What the client should do next in response to this error.

            • BetaManagedAgentsRetryStatusRetrying object { type }

              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 object { type }

              This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

            • BetaManagedAgentsRetryStatusTerminal object { type }

              The session encountered a terminal error and will transition to terminated state.

          • type: "mcp_authentication_failed_error"

            • "mcp_authentication_failed_error"

        • BetaManagedAgentsBillingError object { message, retry_status, type }

          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 or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            What the client should do next in response to this error.

            • BetaManagedAgentsRetryStatusRetrying object { type }

              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 object { type }

              This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

            • BetaManagedAgentsRetryStatusTerminal object { type }

              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 object { id, processed_at, type }

      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 object { id, processed_at, type }

      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 object { id, processed_at, stop_reason, type }

      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 or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted

        The agent completed its turn naturally and is ready for the next user message.

        • BetaManagedAgentsSessionEndTurn object { type }

          The agent completed its turn naturally and is ready for the next user message.

          • type: "end_turn"

            • "end_turn"

        • BetaManagedAgentsSessionRequiresAction object { event_ids, type }

          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 of string

            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 object { type }

          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 object { id, processed_at, type }

      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 object { id, agent_name, processed_at, 2 more }

      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 object { id, iteration, outcome_id, 2 more }

      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 object { id, explanation, iteration, 6 more }

      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: optional "standard" or "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"

    • BetaManagedAgentsSpanModelRequestStartEvent object { id, processed_at, type }

      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 object { id, is_error, model_request_start_id, 3 more }

      Emitted when a model request completes.

      • id: string

        Unique identifier for this event.

      • is_error: boolean

        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 object { id, iteration, outcome_id, 2 more }

      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 object { id, description, max_iterations, 4 more }

      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

        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 or BetaManagedAgentsTextRubric

        Rubric for grading the quality of an outcome.

        • BetaManagedAgentsFileRubric object { file_id, type }

          Rubric referenced by a file uploaded via the Files API.

          • file_id: string

            ID of the rubric file.

          • type: "file"

            • "file"

        • BetaManagedAgentsTextRubric object { content, type }

          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 object { id, processed_at, type }

      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 object { id, agent_name, processed_at, 2 more }

      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 object { id, agent_name, processed_at, 3 more }

      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 or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted

        The agent completed its turn naturally and is ready for the next user message.

        • BetaManagedAgentsSessionEndTurn object { type }

          The agent completed its turn naturally and is ready for the next user message.

        • BetaManagedAgentsSessionRequiresAction object { event_ids, type }

          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 object { type }

          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 object { id, agent_name, processed_at, 2 more }

      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 object { id, tool_use_id, type, 4 more }

      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 stop_reason.event_ids field.

      • type: "user.tool_result"

        • "user.tool_result"

      • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

        The result content returned by the tool.

        • BetaManagedAgentsTextBlock object { text, type }

          Regular text content.

        • BetaManagedAgentsImageBlock object { source, type }

          Image content specified directly as base64 data or as a reference via a URL.

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          Document content, either specified directly as base64 data, as text, or as a reference via a URL.

        • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

          A block containing a web search result.

      • is_error: optional boolean

        Whether the tool execution resulted in an error.

      • processed_at: optional string

        A timestamp in RFC 3339 format

      • session_thread_id: optional string

        Routes this result to a subagent thread. Copy from the agent.tool_use event's session_thread_id.

    • BetaManagedAgentsSessionThreadStatusRescheduledEvent object { id, agent_name, processed_at, 2 more }

      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 object { id, processed_at, type, 3 more }

      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: optional BetaManagedAgentsSessionAgent

        Resolved agent definition for a session. Snapshot of the agent at session creation time.

        • id: string

        • description: string

        • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

          • name: string

          • type: "url"

            • "url"

          • url: string

        • model: BetaManagedAgentsModelConfig

          Model identifier and configuration.

          • id: BetaManagedAgentsModel

            The model that will power your agent.

            See models for additional details and options.

            • "claude-opus-4-7" or "claude-opus-4-6" or "claude-sonnet-4-6" or 6 more

              The model that will power your agent.

              See models for additional details and options.

              • "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: optional "standard" or "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

          Resolved coordinator topology with full agent definitions for each roster member.

          • agents: array of BetaManagedAgentsSessionThreadAgent

            Full agent definitions the coordinator may spawn as session threads.

            • id: string

            • description: string

            • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

              • name: string

              • type: "url"

              • url: string

            • model: BetaManagedAgentsModelConfig

              Model identifier and configuration.

            • name: string

            • skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

              • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

                A resolved Anthropic-managed skill.

                • skill_id: string

                • type: "anthropic"

                  • "anthropic"

                • version: string

              • BetaManagedAgentsCustomSkill object { skill_id, type, version }

                A resolved user-created custom skill.

                • skill_id: string

                • type: "custom"

                  • "custom"

                • version: string

            • system: string

            • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

              • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

                • configs: array of BetaManagedAgentsAgentToolConfig

                  • enabled: boolean

                  • name: "bash" or "edit" or "read" or 5 more

                    Built-in agent tool identifier.

                    • "bash"

                    • "edit"

                    • "read"

                    • "write"

                    • "glob"

                    • "grep"

                    • "web_fetch"

                    • "web_search"

                  • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                    Permission policy for tool execution.

                    • BetaManagedAgentsAlwaysAllowPolicy object { type }

                      Tool calls are automatically approved without user confirmation.

                      • type: "always_allow"

                        • "always_allow"

                    • BetaManagedAgentsAlwaysAskPolicy object { type }

                      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 or BetaManagedAgentsAlwaysAskPolicy

                    Permission policy for tool execution.

                    • BetaManagedAgentsAlwaysAllowPolicy object { type }

                      Tool calls are automatically approved without user confirmation.

                    • BetaManagedAgentsAlwaysAskPolicy object { type }

                      Tool calls require user confirmation before execution.

                • type: "agent_toolset_20260401"

                  • "agent_toolset_20260401"

              • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

                • configs: array of BetaManagedAgentsMCPToolConfig

                  • enabled: boolean

                  • name: string

                  • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                    Permission policy for tool execution.

                    • BetaManagedAgentsAlwaysAllowPolicy object { type }

                      Tool calls are automatically approved without user confirmation.

                    • BetaManagedAgentsAlwaysAskPolicy object { type }

                      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 or BetaManagedAgentsAlwaysAskPolicy

                    Permission policy for tool execution.

                    • BetaManagedAgentsAlwaysAllowPolicy object { type }

                      Tool calls are automatically approved without user confirmation.

                    • BetaManagedAgentsAlwaysAskPolicy object { type }

                      Tool calls require user confirmation before execution.

                • mcp_server_name: string

                • type: "mcp_toolset"

                  • "mcp_toolset"

              • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

                A custom tool as returned in API responses.

                • description: string

                • input_schema: BetaManagedAgentsCustomToolInputSchema

                  JSON Schema for custom tool input parameters.

                  • properties: optional map[unknown]

                    JSON Schema properties defining the tool's input parameters.

                  • required: optional array of string

                    List of required property names.

                  • type: optional "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 of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

          • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

            A resolved Anthropic-managed skill.

          • BetaManagedAgentsCustomSkill object { skill_id, type, version }

            A resolved user-created custom skill.

        • system: string

        • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

          • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

          • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

          • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

            A custom tool as returned in API responses.

        • type: "agent"

          • "agent"

        • version: number

      • metadata: optional map[string]

        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: optional string

        The session's new title. Present only when the update changed it.

Beta Managed Agents Session Requires Action

  • BetaManagedAgentsSessionRequiresAction object { event_ids, type }

    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 of string

      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 object { type }

    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 object { id, processed_at, stop_reason, type }

    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 or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted

      The agent completed its turn naturally and is ready for the next user message.

      • BetaManagedAgentsSessionEndTurn object { type }

        The agent completed its turn naturally and is ready for the next user message.

        • type: "end_turn"

          • "end_turn"

      • BetaManagedAgentsSessionRequiresAction object { event_ids, type }

        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 of string

          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 object { type }

        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 object { id, processed_at, type }

    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 object { id, processed_at, type }

    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 object { id, processed_at, type }

    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 object { id, agent_name, processed_at, 2 more }

    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 object { id, agent_name, processed_at, 3 more }

    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 or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted

      The agent completed its turn naturally and is ready for the next user message.

      • BetaManagedAgentsSessionEndTurn object { type }

        The agent completed its turn naturally and is ready for the next user message.

        • type: "end_turn"

          • "end_turn"

      • BetaManagedAgentsSessionRequiresAction object { event_ids, type }

        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 of string

          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 object { type }

        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 object { id, agent_name, processed_at, 2 more }

    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 object { id, agent_name, processed_at, 2 more }

    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 object { id, agent_name, processed_at, 2 more }

    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 object { id, is_error, model_request_start_id, 3 more }

    Emitted when a model request completes.

    • id: string

      Unique identifier for this event.

    • is_error: boolean

      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: optional "standard" or "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"

    • 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 object { id, processed_at, type }

    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 object { cache_creation_input_tokens, cache_read_input_tokens, input_tokens, 2 more }

    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: optional "standard" or "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 Span Outcome Evaluation End Event

  • BetaManagedAgentsSpanOutcomeEvaluationEndEvent object { id, explanation, iteration, 6 more }

    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: optional "standard" or "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 Span Outcome Evaluation Ongoing Event

  • BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent object { id, iteration, outcome_id, 2 more }

    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 object { id, iteration, outcome_id, 2 more }

    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 or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or 30 more

    Server-sent event in the session stream.

    • BetaManagedAgentsUserMessageEvent object { id, content, type, processed_at }

      A user message event in the session conversation.

      • id: string

        Unique identifier for this event.

      • content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock

        Array of content blocks comprising the user message.

        • BetaManagedAgentsTextBlock object { text, type }

          Regular text content.

          • text: string

            The text content.

          • type: "text"

            • "text"

        • BetaManagedAgentsImageBlock object { source, type }

          Image content specified directly as base64 data or as a reference via a URL.

          • source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource

            Union type for image source variants.

            • BetaManagedAgentsBase64ImageSource object { data, media_type, type }

              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 object { type, url }

              Image referenced by URL.

              • type: "url"

                • "url"

              • url: string

                URL of the image to fetch.

            • BetaManagedAgentsFileImageSource object { file_id, type }

              Image referenced by file ID.

              • file_id: string

                ID of a previously uploaded file.

              • type: "file"

                • "file"

          • type: "image"

            • "image"

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          Document content, either specified directly as base64 data, as text, or as a reference via a URL.

          • source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource

            Union type for document source variants.

            • BetaManagedAgentsBase64DocumentSource object { data, media_type, type }

              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 object { data, media_type, type }

              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 object { type, url }

              Document referenced by URL.

              • type: "url"

                • "url"

              • url: string

                URL of the document to fetch.

            • BetaManagedAgentsFileDocumentSource object { file_id, type }

              Document referenced by file ID.

              • file_id: string

                ID of a previously uploaded file.

              • type: "file"

                • "file"

          • type: "document"

            • "document"

          • context: optional string

            Additional context about the document for the model.

          • title: optional string

            The title of the document.

      • type: "user.message"

        • "user.message"

      • processed_at: optional string

        A timestamp in RFC 3339 format

    • BetaManagedAgentsUserInterruptEvent object { id, type, processed_at, session_thread_id }

      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: optional string

        A timestamp in RFC 3339 format

      • session_thread_id: optional string

        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 object { id, result, tool_use_id, 4 more }

      A tool confirmation event that approves or denies a pending tool execution.

      • id: string

        Unique identifier for this event.

      • result: "allow" or "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 stop_reason.event_ids field.

      • type: "user.tool_confirmation"

        • "user.tool_confirmation"

      • deny_message: optional string

        Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.

      • processed_at: optional string

        A timestamp in RFC 3339 format

      • session_thread_id: optional string

        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 object { id, custom_tool_use_id, type, 4 more }

      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 stop_reason.event_ids field.

      • type: "user.custom_tool_result"

        • "user.custom_tool_result"

      • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

        The result content returned by the tool.

        • BetaManagedAgentsTextBlock object { text, type }

          Regular text content.

        • BetaManagedAgentsImageBlock object { source, type }

          Image content specified directly as base64 data or as a reference via a URL.

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          Document content, either specified directly as base64 data, as text, or as a reference via a URL.

        • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

          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 of BetaManagedAgentsSearchResultContent

            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: optional boolean

        Whether the tool execution resulted in an error.

      • processed_at: optional string

        A timestamp in RFC 3339 format

      • session_thread_id: optional string

        Routes this result to a subagent thread. Copy from the agent.custom_tool_use event's session_thread_id.

    • BetaManagedAgentsAgentCustomToolUseEvent object { id, input, name, 3 more }

      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: map[unknown]

        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: optional string

        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 object { id, content, processed_at, type }

      An agent response event in the session conversation.

      • id: string

        Unique identifier for this event.

      • content: array of BetaManagedAgentsTextBlock

        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 object { id, processed_at, type }

      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 object { id, input, mcp_server_name, 5 more }

      Event emitted when the agent invokes a tool provided by an MCP server.

      • id: string

        Unique identifier for this event.

      • input: map[unknown]

        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: optional "allow" or "ask" or "deny"

        AgentEvaluatedPermission enum

        • "allow"

        • "ask"

        • "deny"

      • session_thread_id: optional string

        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 object { id, mcp_tool_use_id, processed_at, 3 more }

      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: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

        The result content returned by the tool.

        • BetaManagedAgentsTextBlock object { text, type }

          Regular text content.

        • BetaManagedAgentsImageBlock object { source, type }

          Image content specified directly as base64 data or as a reference via a URL.

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          Document content, either specified directly as base64 data, as text, or as a reference via a URL.

        • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

          A block containing a web search result.

      • is_error: optional boolean

        Whether the tool execution resulted in an error.

    • BetaManagedAgentsAgentToolUseEvent object { id, input, name, 4 more }

      Event emitted when the agent invokes a built-in agent tool.

      • id: string

        Unique identifier for this event.

      • input: map[unknown]

        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: optional "allow" or "ask" or "deny"

        AgentEvaluatedPermission enum

        • "allow"

        • "ask"

        • "deny"

      • session_thread_id: optional string

        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 object { id, processed_at, tool_use_id, 3 more }

      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: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

        The result content returned by the tool.

        • BetaManagedAgentsTextBlock object { text, type }

          Regular text content.

        • BetaManagedAgentsImageBlock object { source, type }

          Image content specified directly as base64 data or as a reference via a URL.

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          Document content, either specified directly as base64 data, as text, or as a reference via a URL.

        • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

          A block containing a web search result.

      • is_error: optional boolean

        Whether the tool execution resulted in an error.

    • BetaManagedAgentsAgentThreadMessageReceivedEvent object { id, content, from_session_thread_id, 3 more }

      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 of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock

        Message content blocks.

        • BetaManagedAgentsTextBlock object { text, type }

          Regular text content.

        • BetaManagedAgentsImageBlock object { source, type }

          Image content specified directly as base64 data or as a reference via a URL.

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          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: optional string

        Name of the callable agent this message came from. Absent when received from the primary agent.

    • BetaManagedAgentsAgentThreadMessageSentEvent object { id, content, processed_at, 3 more }

      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 of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock

        Message content blocks.

        • BetaManagedAgentsTextBlock object { text, type }

          Regular text content.

        • BetaManagedAgentsImageBlock object { source, type }

          Image content specified directly as base64 data or as a reference via a URL.

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          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: optional string

        Name of the callable agent this message was sent to. Absent when sent to the primary agent.

    • BetaManagedAgentsAgentThreadContextCompactedEvent object { id, processed_at, type }

      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 object { id, error, processed_at, type }

      An error event indicating a problem occurred during session execution.

      • id: string

        Unique identifier for this event.

      • error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 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 object { message, retry_status, type }

          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 or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            What the client should do next in response to this error.

            • BetaManagedAgentsRetryStatusRetrying object { type }

              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 object { type }

              This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

              • type: "exhausted"

                • "exhausted"

            • BetaManagedAgentsRetryStatusTerminal object { type }

              The session encountered a terminal error and will transition to terminated state.

              • type: "terminal"

                • "terminal"

          • type: "unknown_error"

            • "unknown_error"

        • BetaManagedAgentsModelOverloadedError object { message, retry_status, type }

          The model is currently overloaded. Emitted after automatic retries are exhausted.

          • message: string

            Human-readable error description.

          • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            What the client should do next in response to this error.

            • BetaManagedAgentsRetryStatusRetrying object { type }

              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 object { type }

              This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

            • BetaManagedAgentsRetryStatusTerminal object { type }

              The session encountered a terminal error and will transition to terminated state.

          • type: "model_overloaded_error"

            • "model_overloaded_error"

        • BetaManagedAgentsModelRateLimitedError object { message, retry_status, type }

          The model request was rate-limited.

          • message: string

            Human-readable error description.

          • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            What the client should do next in response to this error.

            • BetaManagedAgentsRetryStatusRetrying object { type }

              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 object { type }

              This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

            • BetaManagedAgentsRetryStatusTerminal object { type }

              The session encountered a terminal error and will transition to terminated state.

          • type: "model_rate_limited_error"

            • "model_rate_limited_error"

        • BetaManagedAgentsModelRequestFailedError object { message, retry_status, type }

          A model request failed for a reason other than overload or rate-limiting.

          • message: string

            Human-readable error description.

          • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            What the client should do next in response to this error.

            • BetaManagedAgentsRetryStatusRetrying object { type }

              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 object { type }

              This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

            • BetaManagedAgentsRetryStatusTerminal object { type }

              The session encountered a terminal error and will transition to terminated state.

          • type: "model_request_failed_error"

            • "model_request_failed_error"

        • BetaManagedAgentsMCPConnectionFailedError object { mcp_server_name, message, retry_status, type }

          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 or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            What the client should do next in response to this error.

            • BetaManagedAgentsRetryStatusRetrying object { type }

              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 object { type }

              This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

            • BetaManagedAgentsRetryStatusTerminal object { type }

              The session encountered a terminal error and will transition to terminated state.

          • type: "mcp_connection_failed_error"

            • "mcp_connection_failed_error"

        • BetaManagedAgentsMCPAuthenticationFailedError object { mcp_server_name, message, retry_status, type }

          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 or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            What the client should do next in response to this error.

            • BetaManagedAgentsRetryStatusRetrying object { type }

              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 object { type }

              This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

            • BetaManagedAgentsRetryStatusTerminal object { type }

              The session encountered a terminal error and will transition to terminated state.

          • type: "mcp_authentication_failed_error"

            • "mcp_authentication_failed_error"

        • BetaManagedAgentsBillingError object { message, retry_status, type }

          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 or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            What the client should do next in response to this error.

            • BetaManagedAgentsRetryStatusRetrying object { type }

              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 object { type }

              This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

            • BetaManagedAgentsRetryStatusTerminal object { type }

              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 object { id, processed_at, type }

      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 object { id, processed_at, type }

      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 object { id, processed_at, stop_reason, type }

      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 or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted

        The agent completed its turn naturally and is ready for the next user message.

        • BetaManagedAgentsSessionEndTurn object { type }

          The agent completed its turn naturally and is ready for the next user message.

          • type: "end_turn"

            • "end_turn"

        • BetaManagedAgentsSessionRequiresAction object { event_ids, type }

          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 of string

            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 object { type }

          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 object { id, processed_at, type }

      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 object { id, agent_name, processed_at, 2 more }

      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 object { id, iteration, outcome_id, 2 more }

      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 object { id, explanation, iteration, 6 more }

      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: optional "standard" or "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"

    • BetaManagedAgentsSpanModelRequestStartEvent object { id, processed_at, type }

      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 object { id, is_error, model_request_start_id, 3 more }

      Emitted when a model request completes.

      • id: string

        Unique identifier for this event.

      • is_error: boolean

        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 object { id, iteration, outcome_id, 2 more }

      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 object { id, description, max_iterations, 4 more }

      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

        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 or BetaManagedAgentsTextRubric

        Rubric for grading the quality of an outcome.

        • BetaManagedAgentsFileRubric object { file_id, type }

          Rubric referenced by a file uploaded via the Files API.

          • file_id: string

            ID of the rubric file.

          • type: "file"

            • "file"

        • BetaManagedAgentsTextRubric object { content, type }

          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 object { id, processed_at, type }

      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 object { id, agent_name, processed_at, 2 more }

      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 object { id, agent_name, processed_at, 3 more }

      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 or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted

        The agent completed its turn naturally and is ready for the next user message.

        • BetaManagedAgentsSessionEndTurn object { type }

          The agent completed its turn naturally and is ready for the next user message.

        • BetaManagedAgentsSessionRequiresAction object { event_ids, type }

          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 object { type }

          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 object { id, agent_name, processed_at, 2 more }

      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 object { id, tool_use_id, type, 4 more }

      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 stop_reason.event_ids field.

      • type: "user.tool_result"

        • "user.tool_result"

      • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

        The result content returned by the tool.

        • BetaManagedAgentsTextBlock object { text, type }

          Regular text content.

        • BetaManagedAgentsImageBlock object { source, type }

          Image content specified directly as base64 data or as a reference via a URL.

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          Document content, either specified directly as base64 data, as text, or as a reference via a URL.

        • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

          A block containing a web search result.

      • is_error: optional boolean

        Whether the tool execution resulted in an error.

      • processed_at: optional string

        A timestamp in RFC 3339 format

      • session_thread_id: optional string

        Routes this result to a subagent thread. Copy from the agent.tool_use event's session_thread_id.

    • BetaManagedAgentsSessionThreadStatusRescheduledEvent object { id, agent_name, processed_at, 2 more }

      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 object { id, processed_at, type, 3 more }

      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: optional BetaManagedAgentsSessionAgent

        Resolved agent definition for a session. Snapshot of the agent at session creation time.

        • id: string

        • description: string

        • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

          • name: string

          • type: "url"

            • "url"

          • url: string

        • model: BetaManagedAgentsModelConfig

          Model identifier and configuration.

          • id: BetaManagedAgentsModel

            The model that will power your agent.

            See models for additional details and options.

            • "claude-opus-4-7" or "claude-opus-4-6" or "claude-sonnet-4-6" or 6 more

              The model that will power your agent.

              See models for additional details and options.

              • "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: optional "standard" or "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

          Resolved coordinator topology with full agent definitions for each roster member.

          • agents: array of BetaManagedAgentsSessionThreadAgent

            Full agent definitions the coordinator may spawn as session threads.

            • id: string

            • description: string

            • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

              • name: string

              • type: "url"

              • url: string

            • model: BetaManagedAgentsModelConfig

              Model identifier and configuration.

            • name: string

            • skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

              • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

                A resolved Anthropic-managed skill.

                • skill_id: string

                • type: "anthropic"

                  • "anthropic"

                • version: string

              • BetaManagedAgentsCustomSkill object { skill_id, type, version }

                A resolved user-created custom skill.

                • skill_id: string

                • type: "custom"

                  • "custom"

                • version: string

            • system: string

            • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

              • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

                • configs: array of BetaManagedAgentsAgentToolConfig

                  • enabled: boolean

                  • name: "bash" or "edit" or "read" or 5 more

                    Built-in agent tool identifier.

                    • "bash"

                    • "edit"

                    • "read"

                    • "write"

                    • "glob"

                    • "grep"

                    • "web_fetch"

                    • "web_search"

                  • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                    Permission policy for tool execution.

                    • BetaManagedAgentsAlwaysAllowPolicy object { type }

                      Tool calls are automatically approved without user confirmation.

                      • type: "always_allow"

                        • "always_allow"

                    • BetaManagedAgentsAlwaysAskPolicy object { type }

                      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 or BetaManagedAgentsAlwaysAskPolicy

                    Permission policy for tool execution.

                    • BetaManagedAgentsAlwaysAllowPolicy object { type }

                      Tool calls are automatically approved without user confirmation.

                    • BetaManagedAgentsAlwaysAskPolicy object { type }

                      Tool calls require user confirmation before execution.

                • type: "agent_toolset_20260401"

                  • "agent_toolset_20260401"

              • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

                • configs: array of BetaManagedAgentsMCPToolConfig

                  • enabled: boolean

                  • name: string

                  • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                    Permission policy for tool execution.

                    • BetaManagedAgentsAlwaysAllowPolicy object { type }

                      Tool calls are automatically approved without user confirmation.

                    • BetaManagedAgentsAlwaysAskPolicy object { type }

                      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 or BetaManagedAgentsAlwaysAskPolicy

                    Permission policy for tool execution.

                    • BetaManagedAgentsAlwaysAllowPolicy object { type }

                      Tool calls are automatically approved without user confirmation.

                    • BetaManagedAgentsAlwaysAskPolicy object { type }

                      Tool calls require user confirmation before execution.

                • mcp_server_name: string

                • type: "mcp_toolset"

                  • "mcp_toolset"

              • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

                A custom tool as returned in API responses.

                • description: string

                • input_schema: BetaManagedAgentsCustomToolInputSchema

                  JSON Schema for custom tool input parameters.

                  • properties: optional map[unknown]

                    JSON Schema properties defining the tool's input parameters.

                  • required: optional array of string

                    List of required property names.

                  • type: optional "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 of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

          • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

            A resolved Anthropic-managed skill.

          • BetaManagedAgentsCustomSkill object { skill_id, type, version }

            A resolved user-created custom skill.

        • system: string

        • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

          • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

          • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

          • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

            A custom tool as returned in API responses.

        • type: "agent"

          • "agent"

        • version: number

      • metadata: optional map[string]

        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: optional string

        The session's new title. Present only when the update changed it.

Beta Managed Agents Text Block

  • BetaManagedAgentsTextBlock object { text, type }

    Regular text content.

    • text: string

      The text content.

    • type: "text"

      • "text"

Beta Managed Agents Text Rubric

  • BetaManagedAgentsTextRubric object { content, type }

    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 object { content, type }

    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 object { message, retry_status, type }

    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 or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

      What the client should do next in response to this error.

      • BetaManagedAgentsRetryStatusRetrying object { type }

        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 object { type }

        This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

        • type: "exhausted"

          • "exhausted"

      • BetaManagedAgentsRetryStatusTerminal object { type }

        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 object { type, url }

    Document referenced by URL.

    • type: "url"

      • "url"

    • url: string

      URL of the document to fetch.

Beta Managed Agents URL Image Source

  • BetaManagedAgentsURLImageSource object { type, url }

    Image referenced by URL.

    • type: "url"

      • "url"

    • url: string

      URL of the image to fetch.

Beta Managed Agents User Custom Tool Result Event

  • BetaManagedAgentsUserCustomToolResultEvent object { id, custom_tool_use_id, type, 4 more }

    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 stop_reason.event_ids field.

    • type: "user.custom_tool_result"

      • "user.custom_tool_result"

    • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

      The result content returned by the tool.

      • BetaManagedAgentsTextBlock object { text, type }

        Regular text content.

        • text: string

          The text content.

        • type: "text"

          • "text"

      • BetaManagedAgentsImageBlock object { source, type }

        Image content specified directly as base64 data or as a reference via a URL.

        • source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource

          Union type for image source variants.

          • BetaManagedAgentsBase64ImageSource object { data, media_type, type }

            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 object { type, url }

            Image referenced by URL.

            • type: "url"

              • "url"

            • url: string

              URL of the image to fetch.

          • BetaManagedAgentsFileImageSource object { file_id, type }

            Image referenced by file ID.

            • file_id: string

              ID of a previously uploaded file.

            • type: "file"

              • "file"

        • type: "image"

          • "image"

      • BetaManagedAgentsDocumentBlock object { source, type, context, title }

        Document content, either specified directly as base64 data, as text, or as a reference via a URL.

        • source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource

          Union type for document source variants.

          • BetaManagedAgentsBase64DocumentSource object { data, media_type, type }

            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 object { data, media_type, type }

            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 object { type, url }

            Document referenced by URL.

            • type: "url"

              • "url"

            • url: string

              URL of the document to fetch.

          • BetaManagedAgentsFileDocumentSource object { file_id, type }

            Document referenced by file ID.

            • file_id: string

              ID of a previously uploaded file.

            • type: "file"

              • "file"

        • type: "document"

          • "document"

        • context: optional string

          Additional context about the document for the model.

        • title: optional string

          The title of the document.

      • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

        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 of BetaManagedAgentsSearchResultContent

          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: optional boolean

      Whether the tool execution resulted in an error.

    • processed_at: optional string

      A timestamp in RFC 3339 format

    • session_thread_id: optional string

      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 object { custom_tool_use_id, type, content, is_error }

    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 stop_reason.event_ids field.

    • type: "user.custom_tool_result"

      • "user.custom_tool_result"

    • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

      The result content returned by the tool.

      • BetaManagedAgentsTextBlock object { text, type }

        Regular text content.

        • text: string

          The text content.

        • type: "text"

          • "text"

      • BetaManagedAgentsImageBlock object { source, type }

        Image content specified directly as base64 data or as a reference via a URL.

        • source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource

          Union type for image source variants.

          • BetaManagedAgentsBase64ImageSource object { data, media_type, type }

            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 object { type, url }

            Image referenced by URL.

            • type: "url"

              • "url"

            • url: string

              URL of the image to fetch.

          • BetaManagedAgentsFileImageSource object { file_id, type }

            Image referenced by file ID.

            • file_id: string

              ID of a previously uploaded file.

            • type: "file"

              • "file"

        • type: "image"

          • "image"

      • BetaManagedAgentsDocumentBlock object { source, type, context, title }

        Document content, either specified directly as base64 data, as text, or as a reference via a URL.

        • source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource

          Union type for document source variants.

          • BetaManagedAgentsBase64DocumentSource object { data, media_type, type }

            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 object { data, media_type, type }

            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 object { type, url }

            Document referenced by URL.

            • type: "url"

              • "url"

            • url: string

              URL of the document to fetch.

          • BetaManagedAgentsFileDocumentSource object { file_id, type }

            Document referenced by file ID.

            • file_id: string

              ID of a previously uploaded file.

            • type: "file"

              • "file"

        • type: "document"

          • "document"

        • context: optional string

          Additional context about the document for the model.

        • title: optional string

          The title of the document.

      • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

        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 of BetaManagedAgentsSearchResultContent

          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: optional boolean

      Whether the tool execution resulted in an error.

Beta Managed Agents User Define Outcome Event

  • BetaManagedAgentsUserDefineOutcomeEvent object { id, description, max_iterations, 4 more }

    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

      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 or BetaManagedAgentsTextRubric

      Rubric for grading the quality of an outcome.

      • BetaManagedAgentsFileRubric object { file_id, type }

        Rubric referenced by a file uploaded via the Files API.

        • file_id: string

          ID of the rubric file.

        • type: "file"

          • "file"

      • BetaManagedAgentsTextRubric object { content, type }

        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 object { description, rubric, type, max_iterations }

    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 or BetaManagedAgentsTextRubricParams

      Rubric for grading the quality of an outcome.

      • BetaManagedAgentsFileRubricParams object { file_id, type }

        Rubric referenced by a file uploaded via the Files API.

        • file_id: string

          ID of the rubric file.

        • type: "file"

          • "file"

      • BetaManagedAgentsTextRubricParams object { content, type }

        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: optional number

      Eval→revision cycles before giving up. Default 3, max 20.

Beta Managed Agents User Interrupt Event

  • BetaManagedAgentsUserInterruptEvent object { id, type, processed_at, session_thread_id }

    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: optional string

      A timestamp in RFC 3339 format

    • session_thread_id: optional string

      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 object { type, session_thread_id }

    Parameters for sending an interrupt to pause the agent.

    • type: "user.interrupt"

      • "user.interrupt"

    • session_thread_id: optional string

      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 object { id, content, type, processed_at }

    A user message event in the session conversation.

    • id: string

      Unique identifier for this event.

    • content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock

      Array of content blocks comprising the user message.

      • BetaManagedAgentsTextBlock object { text, type }

        Regular text content.

        • text: string

          The text content.

        • type: "text"

          • "text"

      • BetaManagedAgentsImageBlock object { source, type }

        Image content specified directly as base64 data or as a reference via a URL.

        • source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource

          Union type for image source variants.

          • BetaManagedAgentsBase64ImageSource object { data, media_type, type }

            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 object { type, url }

            Image referenced by URL.

            • type: "url"

              • "url"

            • url: string

              URL of the image to fetch.

          • BetaManagedAgentsFileImageSource object { file_id, type }

            Image referenced by file ID.

            • file_id: string

              ID of a previously uploaded file.

            • type: "file"

              • "file"

        • type: "image"

          • "image"

      • BetaManagedAgentsDocumentBlock object { source, type, context, title }

        Document content, either specified directly as base64 data, as text, or as a reference via a URL.

        • source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource

          Union type for document source variants.

          • BetaManagedAgentsBase64DocumentSource object { data, media_type, type }

            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 object { data, media_type, type }

            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 object { type, url }

            Document referenced by URL.

            • type: "url"

              • "url"

            • url: string

              URL of the document to fetch.

          • BetaManagedAgentsFileDocumentSource object { file_id, type }

            Document referenced by file ID.

            • file_id: string

              ID of a previously uploaded file.

            • type: "file"

              • "file"

        • type: "document"

          • "document"

        • context: optional string

          Additional context about the document for the model.

        • title: optional string

          The title of the document.

    • type: "user.message"

      • "user.message"

    • processed_at: optional string

      A timestamp in RFC 3339 format

Beta Managed Agents User Message Event Params

  • BetaManagedAgentsUserMessageEventParams object { content, type }

    Parameters for sending a user message to the session.

    • content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock

      Array of content blocks for the user message.

      • BetaManagedAgentsTextBlock object { text, type }

        Regular text content.

        • text: string

          The text content.

        • type: "text"

          • "text"

      • BetaManagedAgentsImageBlock object { source, type }

        Image content specified directly as base64 data or as a reference via a URL.

        • source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource

          Union type for image source variants.

          • BetaManagedAgentsBase64ImageSource object { data, media_type, type }

            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 object { type, url }

            Image referenced by URL.

            • type: "url"

              • "url"

            • url: string

              URL of the image to fetch.

          • BetaManagedAgentsFileImageSource object { file_id, type }

            Image referenced by file ID.

            • file_id: string

              ID of a previously uploaded file.

            • type: "file"

              • "file"

        • type: "image"

          • "image"

      • BetaManagedAgentsDocumentBlock object { source, type, context, title }

        Document content, either specified directly as base64 data, as text, or as a reference via a URL.

        • source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource

          Union type for document source variants.

          • BetaManagedAgentsBase64DocumentSource object { data, media_type, type }

            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 object { data, media_type, type }

            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 object { type, url }

            Document referenced by URL.

            • type: "url"

              • "url"

            • url: string

              URL of the document to fetch.

          • BetaManagedAgentsFileDocumentSource object { file_id, type }

            Document referenced by file ID.

            • file_id: string

              ID of a previously uploaded file.

            • type: "file"

              • "file"

        • type: "document"

          • "document"

        • context: optional string

          Additional context about the document for the model.

        • title: optional string

          The title of the document.

    • type: "user.message"

      • "user.message"

Beta Managed Agents User Tool Confirmation Event

  • BetaManagedAgentsUserToolConfirmationEvent object { id, result, tool_use_id, 4 more }

    A tool confirmation event that approves or denies a pending tool execution.

    • id: string

      Unique identifier for this event.

    • result: "allow" or "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 stop_reason.event_ids field.

    • type: "user.tool_confirmation"

      • "user.tool_confirmation"

    • deny_message: optional string

      Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.

    • processed_at: optional string

      A timestamp in RFC 3339 format

    • session_thread_id: optional string

      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 object { result, tool_use_id, type, deny_message }

    Parameters for confirming or denying a tool execution request.

    • result: "allow" or "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 stop_reason.event_ids field.

    • type: "user.tool_confirmation"

      • "user.tool_confirmation"

    • deny_message: optional string

      Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.

Beta Managed Agents User Tool Result Event Params

  • BetaManagedAgentsUserToolResultEventParams object { tool_use_id, type, content, is_error }

    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 stop_reason.event_ids field.

    • type: "user.tool_result"

      • "user.tool_result"

    • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

      The result content returned by the tool.

      • BetaManagedAgentsTextBlock object { text, type }

        Regular text content.

        • text: string

          The text content.

        • type: "text"

          • "text"

      • BetaManagedAgentsImageBlock object { source, type }

        Image content specified directly as base64 data or as a reference via a URL.

        • source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource

          Union type for image source variants.

          • BetaManagedAgentsBase64ImageSource object { data, media_type, type }

            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 object { type, url }

            Image referenced by URL.

            • type: "url"

              • "url"

            • url: string

              URL of the image to fetch.

          • BetaManagedAgentsFileImageSource object { file_id, type }

            Image referenced by file ID.

            • file_id: string

              ID of a previously uploaded file.

            • type: "file"

              • "file"

        • type: "image"

          • "image"

      • BetaManagedAgentsDocumentBlock object { source, type, context, title }

        Document content, either specified directly as base64 data, as text, or as a reference via a URL.

        • source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource

          Union type for document source variants.

          • BetaManagedAgentsBase64DocumentSource object { data, media_type, type }

            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 object { data, media_type, type }

            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 object { type, url }

            Document referenced by URL.

            • type: "url"

              • "url"

            • url: string

              URL of the document to fetch.

          • BetaManagedAgentsFileDocumentSource object { file_id, type }

            Document referenced by file ID.

            • file_id: string

              ID of a previously uploaded file.

            • type: "file"

              • "file"

        • type: "document"

          • "document"

        • context: optional string

          Additional context about the document for the model.

        • title: optional string

          The title of the document.

      • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

        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 of BetaManagedAgentsSearchResultContent

          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: optional boolean

      Whether the tool execution resulted in an error.

Resources

Add Session Resource

post /v1/sessions/{session_id}/resources

Add Session Resource

Path Parameters

  • session_id: string

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Body Parameters

  • file_id: string

    ID of a previously uploaded file.

  • type: "file"

    • "file"

  • mount_path: optional string

    Mount path in the container. Defaults to /mnt/session/uploads/<file_id>.

Returns

  • BetaManagedAgentsFileResource object { id, created_at, file_id, 3 more }

    • 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

curl https://api.anthropic.com/v1/sessions/$SESSION_ID/resources \
    -H 'Content-Type: application/json' \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: managed-agents-2026-04-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY" \
    -d '{
          "file_id": "file_011CNha8iCJcU1wXNR6q4V8w",
          "type": "file",
          "mount_path": "/uploads/receipt.pdf"
        }'

Response

{
  "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

get /v1/sessions/{session_id}/resources

List Session Resources

Path Parameters

  • session_id: string

Query Parameters

  • limit: optional number

    Maximum number of resources to return per page (max 1000). If omitted, returns all resources.

  • page: optional string

    Opaque cursor from a previous response's next_page field.

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Returns

  • data: array of BetaManagedAgentsSessionResource

    Resources for the session, ordered by created_at.

    • BetaManagedAgentsGitHubRepositoryResource object { id, created_at, mount_path, 4 more }

      • 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: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout

        • BetaManagedAgentsBranchCheckout object { name, type }

          • name: string

            Branch name to check out.

          • type: "branch"

            • "branch"

        • BetaManagedAgentsCommitCheckout object { sha, type }

          • sha: string

            Full commit SHA to check out.

          • type: "commit"

            • "commit"

    • BetaManagedAgentsFileResource object { id, created_at, file_id, 3 more }

      • 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 object { memory_store_id, type, access, 4 more }

      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: optional "read_write" or "read_only"

        Access mode for an attached memory store.

        • "read_write"

        • "read_only"

      • description: optional 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: optional string

        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: optional string

        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: optional string

        Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource.

  • next_page: optional string

    Opaque cursor for the next page. Null when no more results.

Example

curl https://api.anthropic.com/v1/sessions/$SESSION_ID/resources \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: managed-agents-2026-04-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

Response

{
  "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

get /v1/sessions/{session_id}/resources/{resource_id}

Get Session Resource

Path Parameters

  • session_id: string

  • resource_id: string

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Returns

  • BetaManagedAgentsGitHubRepositoryResource object { id, created_at, mount_path, 4 more }

    • 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: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout

      • BetaManagedAgentsBranchCheckout object { name, type }

        • name: string

          Branch name to check out.

        • type: "branch"

          • "branch"

      • BetaManagedAgentsCommitCheckout object { sha, type }

        • sha: string

          Full commit SHA to check out.

        • type: "commit"

          • "commit"

  • BetaManagedAgentsFileResource object { id, created_at, file_id, 3 more }

    • 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 object { memory_store_id, type, access, 4 more }

    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: optional "read_write" or "read_only"

      Access mode for an attached memory store.

      • "read_write"

      • "read_only"

    • description: optional 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: optional string

      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: optional string

      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: optional string

      Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource.

Example

curl https://api.anthropic.com/v1/sessions/$SESSION_ID/resources/$RESOURCE_ID \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: managed-agents-2026-04-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

Response

{
  "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

post /v1/sessions/{session_id}/resources/{resource_id}

Update Session Resource

Path Parameters

  • session_id: string

  • resource_id: string

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Body Parameters

  • authorization_token: string

    New authorization token for the resource. Currently only github_repository resources support token rotation.

Returns

  • BetaManagedAgentsGitHubRepositoryResource object { id, created_at, mount_path, 4 more }

    • 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: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout

      • BetaManagedAgentsBranchCheckout object { name, type }

        • name: string

          Branch name to check out.

        • type: "branch"

          • "branch"

      • BetaManagedAgentsCommitCheckout object { sha, type }

        • sha: string

          Full commit SHA to check out.

        • type: "commit"

          • "commit"

  • BetaManagedAgentsFileResource object { id, created_at, file_id, 3 more }

    • 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 object { memory_store_id, type, access, 4 more }

    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: optional "read_write" or "read_only"

      Access mode for an attached memory store.

      • "read_write"

      • "read_only"

    • description: optional 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: optional string

      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: optional string

      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: optional string

      Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource.

Example

curl https://api.anthropic.com/v1/sessions/$SESSION_ID/resources/$RESOURCE_ID \
    -H 'Content-Type: application/json' \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: managed-agents-2026-04-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY" \
    -d '{
          "authorization_token": "ghp_exampletoken"
        }'

Response

{
  "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

delete /v1/sessions/{session_id}/resources/{resource_id}

Delete Session Resource

Path Parameters

  • session_id: string

  • resource_id: string

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Returns

  • BetaManagedAgentsDeleteSessionResource object { id, type }

    Confirmation of resource deletion.

    • id: string

    • type: "session_resource_deleted"

      • "session_resource_deleted"

Example

curl https://api.anthropic.com/v1/sessions/$SESSION_ID/resources/$RESOURCE_ID \
    -X DELETE \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: managed-agents-2026-04-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

Response

{
  "id": "sesrsc_011CZkZBJq5dWxk9fVLNcPht",
  "type": "session_resource_deleted"
}

Domain Types

Beta Managed Agents Delete Session Resource

  • BetaManagedAgentsDeleteSessionResource object { id, type }

    Confirmation of resource deletion.

    • id: string

    • type: "session_resource_deleted"

      • "session_resource_deleted"

Beta Managed Agents File Resource

  • BetaManagedAgentsFileResource object { id, created_at, file_id, 3 more }

    • 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 object { id, created_at, mount_path, 4 more }

    • 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: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout

      • BetaManagedAgentsBranchCheckout object { name, type }

        • name: string

          Branch name to check out.

        • type: "branch"

          • "branch"

      • BetaManagedAgentsCommitCheckout object { sha, type }

        • sha: string

          Full commit SHA to check out.

        • type: "commit"

          • "commit"

Beta Managed Agents Memory Store Resource

  • BetaManagedAgentsMemoryStoreResource object { memory_store_id, type, access, 4 more }

    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: optional "read_write" or "read_only"

      Access mode for an attached memory store.

      • "read_write"

      • "read_only"

    • description: optional 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: optional string

      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: optional string

      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: optional string

      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 or BetaManagedAgentsFileResource or BetaManagedAgentsMemoryStoreResource

    A memory store attached to an agent session.

    • BetaManagedAgentsGitHubRepositoryResource object { id, created_at, mount_path, 4 more }

      • 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: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout

        • BetaManagedAgentsBranchCheckout object { name, type }

          • name: string

            Branch name to check out.

          • type: "branch"

            • "branch"

        • BetaManagedAgentsCommitCheckout object { sha, type }

          • sha: string

            Full commit SHA to check out.

          • type: "commit"

            • "commit"

    • BetaManagedAgentsFileResource object { id, created_at, file_id, 3 more }

      • 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 object { memory_store_id, type, access, 4 more }

      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: optional "read_write" or "read_only"

        Access mode for an attached memory store.

        • "read_write"

        • "read_only"

      • description: optional 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: optional string

        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: optional string

        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: optional string

        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 or BetaManagedAgentsFileResource or BetaManagedAgentsMemoryStoreResource

    The requested session resource.

    • BetaManagedAgentsGitHubRepositoryResource object { id, created_at, mount_path, 4 more }

      • 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: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout

        • BetaManagedAgentsBranchCheckout object { name, type }

          • name: string

            Branch name to check out.

          • type: "branch"

            • "branch"

        • BetaManagedAgentsCommitCheckout object { sha, type }

          • sha: string

            Full commit SHA to check out.

          • type: "commit"

            • "commit"

    • BetaManagedAgentsFileResource object { id, created_at, file_id, 3 more }

      • 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 object { memory_store_id, type, access, 4 more }

      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: optional "read_write" or "read_only"

        Access mode for an attached memory store.

        • "read_write"

        • "read_only"

      • description: optional 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: optional string

        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: optional string

        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: optional string

        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 or BetaManagedAgentsFileResource or BetaManagedAgentsMemoryStoreResource

    The updated session resource.

    • BetaManagedAgentsGitHubRepositoryResource object { id, created_at, mount_path, 4 more }

      • 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: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout

        • BetaManagedAgentsBranchCheckout object { name, type }

          • name: string

            Branch name to check out.

          • type: "branch"

            • "branch"

        • BetaManagedAgentsCommitCheckout object { sha, type }

          • sha: string

            Full commit SHA to check out.

          • type: "commit"

            • "commit"

    • BetaManagedAgentsFileResource object { id, created_at, file_id, 3 more }

      • 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 object { memory_store_id, type, access, 4 more }

      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: optional "read_write" or "read_only"

        Access mode for an attached memory store.

        • "read_write"

        • "read_only"

      • description: optional 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: optional string

        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: optional string

        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: optional string

        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

get /v1/sessions/{session_id}/threads

List Session Threads

Path Parameters

  • session_id: string

Query Parameters

  • limit: optional number

    Maximum results per page. Defaults to 1000.

  • page: optional string

    Opaque pagination cursor from a previous response's next_page. Forward-only.

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Returns

  • data: optional array of BetaManagedAgentsSessionThread

    Threads in the session, primary first then children in spawn order.

    • 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

      • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

        • name: string

        • type: "url"

          • "url"

        • url: string

      • model: BetaManagedAgentsModelConfig

        Model identifier and configuration.

        • id: BetaManagedAgentsModel

          The model that will power your agent.

          See models for additional details and options.

          • "claude-opus-4-7" or "claude-opus-4-6" or "claude-sonnet-4-6" or 6 more

            The model that will power your agent.

            See models for additional details and options.

            • "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: optional "standard" or "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 of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

        • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

          A resolved Anthropic-managed skill.

          • skill_id: string

          • type: "anthropic"

            • "anthropic"

          • version: string

        • BetaManagedAgentsCustomSkill object { skill_id, type, version }

          A resolved user-created custom skill.

          • skill_id: string

          • type: "custom"

            • "custom"

          • version: string

      • system: string

      • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

        • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

          • configs: array of BetaManagedAgentsAgentToolConfig

            • enabled: boolean

            • name: "bash" or "edit" or "read" or 5 more

              Built-in agent tool identifier.

              • "bash"

              • "edit"

              • "read"

              • "write"

              • "glob"

              • "grep"

              • "web_fetch"

              • "web_search"

            • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

              Permission policy for tool execution.

              • BetaManagedAgentsAlwaysAllowPolicy object { type }

                Tool calls are automatically approved without user confirmation.

                • type: "always_allow"

                  • "always_allow"

              • BetaManagedAgentsAlwaysAskPolicy object { type }

                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 or BetaManagedAgentsAlwaysAskPolicy

              Permission policy for tool execution.

              • BetaManagedAgentsAlwaysAllowPolicy object { type }

                Tool calls are automatically approved without user confirmation.

              • BetaManagedAgentsAlwaysAskPolicy object { type }

                Tool calls require user confirmation before execution.

          • type: "agent_toolset_20260401"

            • "agent_toolset_20260401"

        • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

          • configs: array of BetaManagedAgentsMCPToolConfig

            • enabled: boolean

            • name: string

            • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

              Permission policy for tool execution.

              • BetaManagedAgentsAlwaysAllowPolicy object { type }

                Tool calls are automatically approved without user confirmation.

              • BetaManagedAgentsAlwaysAskPolicy object { type }

                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 or BetaManagedAgentsAlwaysAskPolicy

              Permission policy for tool execution.

              • BetaManagedAgentsAlwaysAllowPolicy object { type }

                Tool calls are automatically approved without user confirmation.

              • BetaManagedAgentsAlwaysAskPolicy object { type }

                Tool calls require user confirmation before execution.

          • mcp_server_name: string

          • type: "mcp_toolset"

            • "mcp_toolset"

        • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

          A custom tool as returned in API responses.

          • description: string

          • input_schema: BetaManagedAgentsCustomToolInputSchema

            JSON Schema for custom tool input parameters.

            • properties: optional map[unknown]

              JSON Schema properties defining the tool's input parameters.

            • required: optional array of string

              List of required property names.

            • type: optional "object"

              Must be 'object' for tool input schemas.

              • "object"

          • name: string

          • type: "custom"

            • "custom"

      • type: "agent"

        • "agent"

      • version: number

    • archived_at: string

      A timestamp in RFC 3339 format

    • created_at: string

      A timestamp in RFC 3339 format

    • parent_thread_id: string

      Parent thread that spawned this thread. Null for the primary thread.

    • session_id: string

      The session this thread belongs to.

    • stats: BetaManagedAgentsSessionThreadStats

      Timing statistics for a session thread.

      • active_seconds: optional number

        Cumulative time in seconds the thread spent actively running. Excludes idle time.

      • duration_seconds: optional number

        Elapsed time since thread creation in seconds. For archived threads, frozen at the final update.

      • startup_seconds: optional 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

      Cumulative token usage for a session thread across all turns.

      • cache_creation: optional BetaManagedAgentsCacheCreationUsage

        Prompt-cache creation token usage broken down by cache lifetime.

        • ephemeral_1h_input_tokens: optional number

          Tokens used to create 1-hour ephemeral cache entries.

        • ephemeral_5m_input_tokens: optional number

          Tokens used to create 5-minute ephemeral cache entries.

      • cache_read_input_tokens: optional number

        Total tokens read from prompt cache.

      • input_tokens: optional number

        Total input tokens consumed across all turns.

      • output_tokens: optional number

        Total output tokens generated across all turns.

  • next_page: optional string

    Opaque cursor for the next page. Null when no more results.

Example

curl https://api.anthropic.com/v1/sessions/$SESSION_ID/threads \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: managed-agents-2026-04-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

Response

{
  "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

get /v1/sessions/{session_id}/threads/{thread_id}

Get Session Thread

Path Parameters

  • session_id: string

  • thread_id: string

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Returns

  • BetaManagedAgentsSessionThread object { id, agent, archived_at, 8 more }

    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

      • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

        • name: string

        • type: "url"

          • "url"

        • url: string

      • model: BetaManagedAgentsModelConfig

        Model identifier and configuration.

        • id: BetaManagedAgentsModel

          The model that will power your agent.

          See models for additional details and options.

          • "claude-opus-4-7" or "claude-opus-4-6" or "claude-sonnet-4-6" or 6 more

            The model that will power your agent.

            See models for additional details and options.

            • "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: optional "standard" or "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 of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

        • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

          A resolved Anthropic-managed skill.

          • skill_id: string

          • type: "anthropic"

            • "anthropic"

          • version: string

        • BetaManagedAgentsCustomSkill object { skill_id, type, version }

          A resolved user-created custom skill.

          • skill_id: string

          • type: "custom"

            • "custom"

          • version: string

      • system: string

      • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

        • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

          • configs: array of BetaManagedAgentsAgentToolConfig

            • enabled: boolean

            • name: "bash" or "edit" or "read" or 5 more

              Built-in agent tool identifier.

              • "bash"

              • "edit"

              • "read"

              • "write"

              • "glob"

              • "grep"

              • "web_fetch"

              • "web_search"

            • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

              Permission policy for tool execution.

              • BetaManagedAgentsAlwaysAllowPolicy object { type }

                Tool calls are automatically approved without user confirmation.

                • type: "always_allow"

                  • "always_allow"

              • BetaManagedAgentsAlwaysAskPolicy object { type }

                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 or BetaManagedAgentsAlwaysAskPolicy

              Permission policy for tool execution.

              • BetaManagedAgentsAlwaysAllowPolicy object { type }

                Tool calls are automatically approved without user confirmation.

              • BetaManagedAgentsAlwaysAskPolicy object { type }

                Tool calls require user confirmation before execution.

          • type: "agent_toolset_20260401"

            • "agent_toolset_20260401"

        • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

          • configs: array of BetaManagedAgentsMCPToolConfig

            • enabled: boolean

            • name: string

            • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

              Permission policy for tool execution.

              • BetaManagedAgentsAlwaysAllowPolicy object { type }

                Tool calls are automatically approved without user confirmation.

              • BetaManagedAgentsAlwaysAskPolicy object { type }

                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 or BetaManagedAgentsAlwaysAskPolicy

              Permission policy for tool execution.

              • BetaManagedAgentsAlwaysAllowPolicy object { type }

                Tool calls are automatically approved without user confirmation.

              • BetaManagedAgentsAlwaysAskPolicy object { type }

                Tool calls require user confirmation before execution.

          • mcp_server_name: string

          • type: "mcp_toolset"

            • "mcp_toolset"

        • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

          A custom tool as returned in API responses.

          • description: string

          • input_schema: BetaManagedAgentsCustomToolInputSchema

            JSON Schema for custom tool input parameters.

            • properties: optional map[unknown]

              JSON Schema properties defining the tool's input parameters.

            • required: optional array of string

              List of required property names.

            • type: optional "object"

              Must be 'object' for tool input schemas.

              • "object"

          • name: string

          • type: "custom"

            • "custom"

      • type: "agent"

        • "agent"

      • version: number

    • archived_at: string

      A timestamp in RFC 3339 format

    • created_at: string

      A timestamp in RFC 3339 format

    • parent_thread_id: string

      Parent thread that spawned this thread. Null for the primary thread.

    • session_id: string

      The session this thread belongs to.

    • stats: BetaManagedAgentsSessionThreadStats

      Timing statistics for a session thread.

      • active_seconds: optional number

        Cumulative time in seconds the thread spent actively running. Excludes idle time.

      • duration_seconds: optional number

        Elapsed time since thread creation in seconds. For archived threads, frozen at the final update.

      • startup_seconds: optional 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

      Cumulative token usage for a session thread across all turns.

      • cache_creation: optional BetaManagedAgentsCacheCreationUsage

        Prompt-cache creation token usage broken down by cache lifetime.

        • ephemeral_1h_input_tokens: optional number

          Tokens used to create 1-hour ephemeral cache entries.

        • ephemeral_5m_input_tokens: optional number

          Tokens used to create 5-minute ephemeral cache entries.

      • cache_read_input_tokens: optional number

        Total tokens read from prompt cache.

      • input_tokens: optional number

        Total input tokens consumed across all turns.

      • output_tokens: optional number

        Total output tokens generated across all turns.

Example

curl https://api.anthropic.com/v1/sessions/$SESSION_ID/threads/$THREAD_ID \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: managed-agents-2026-04-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

Response

{
  "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

post /v1/sessions/{session_id}/threads/{thread_id}/archive

Archive Session Thread

Path Parameters

  • session_id: string

  • thread_id: string

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Returns

  • BetaManagedAgentsSessionThread object { id, agent, archived_at, 8 more }

    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

      • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

        • name: string

        • type: "url"

          • "url"

        • url: string

      • model: BetaManagedAgentsModelConfig

        Model identifier and configuration.

        • id: BetaManagedAgentsModel

          The model that will power your agent.

          See models for additional details and options.

          • "claude-opus-4-7" or "claude-opus-4-6" or "claude-sonnet-4-6" or 6 more

            The model that will power your agent.

            See models for additional details and options.

            • "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: optional "standard" or "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 of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

        • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

          A resolved Anthropic-managed skill.

          • skill_id: string

          • type: "anthropic"

            • "anthropic"

          • version: string

        • BetaManagedAgentsCustomSkill object { skill_id, type, version }

          A resolved user-created custom skill.

          • skill_id: string

          • type: "custom"

            • "custom"

          • version: string

      • system: string

      • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

        • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

          • configs: array of BetaManagedAgentsAgentToolConfig

            • enabled: boolean

            • name: "bash" or "edit" or "read" or 5 more

              Built-in agent tool identifier.

              • "bash"

              • "edit"

              • "read"

              • "write"

              • "glob"

              • "grep"

              • "web_fetch"

              • "web_search"

            • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

              Permission policy for tool execution.

              • BetaManagedAgentsAlwaysAllowPolicy object { type }

                Tool calls are automatically approved without user confirmation.

                • type: "always_allow"

                  • "always_allow"

              • BetaManagedAgentsAlwaysAskPolicy object { type }

                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 or BetaManagedAgentsAlwaysAskPolicy

              Permission policy for tool execution.

              • BetaManagedAgentsAlwaysAllowPolicy object { type }

                Tool calls are automatically approved without user confirmation.

              • BetaManagedAgentsAlwaysAskPolicy object { type }

                Tool calls require user confirmation before execution.

          • type: "agent_toolset_20260401"

            • "agent_toolset_20260401"

        • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

          • configs: array of BetaManagedAgentsMCPToolConfig

            • enabled: boolean

            • name: string

            • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

              Permission policy for tool execution.

              • BetaManagedAgentsAlwaysAllowPolicy object { type }

                Tool calls are automatically approved without user confirmation.

              • BetaManagedAgentsAlwaysAskPolicy object { type }

                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 or BetaManagedAgentsAlwaysAskPolicy

              Permission policy for tool execution.

              • BetaManagedAgentsAlwaysAllowPolicy object { type }

                Tool calls are automatically approved without user confirmation.

              • BetaManagedAgentsAlwaysAskPolicy object { type }

                Tool calls require user confirmation before execution.

          • mcp_server_name: string

          • type: "mcp_toolset"

            • "mcp_toolset"

        • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

          A custom tool as returned in API responses.

          • description: string

          • input_schema: BetaManagedAgentsCustomToolInputSchema

            JSON Schema for custom tool input parameters.

            • properties: optional map[unknown]

              JSON Schema properties defining the tool's input parameters.

            • required: optional array of string

              List of required property names.

            • type: optional "object"

              Must be 'object' for tool input schemas.

              • "object"

          • name: string

          • type: "custom"

            • "custom"

      • type: "agent"

        • "agent"

      • version: number

    • archived_at: string

      A timestamp in RFC 3339 format

    • created_at: string

      A timestamp in RFC 3339 format

    • parent_thread_id: string

      Parent thread that spawned this thread. Null for the primary thread.

    • session_id: string

      The session this thread belongs to.

    • stats: BetaManagedAgentsSessionThreadStats

      Timing statistics for a session thread.

      • active_seconds: optional number

        Cumulative time in seconds the thread spent actively running. Excludes idle time.

      • duration_seconds: optional number

        Elapsed time since thread creation in seconds. For archived threads, frozen at the final update.

      • startup_seconds: optional 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

      Cumulative token usage for a session thread across all turns.

      • cache_creation: optional BetaManagedAgentsCacheCreationUsage

        Prompt-cache creation token usage broken down by cache lifetime.

        • ephemeral_1h_input_tokens: optional number

          Tokens used to create 1-hour ephemeral cache entries.

        • ephemeral_5m_input_tokens: optional number

          Tokens used to create 5-minute ephemeral cache entries.

      • cache_read_input_tokens: optional number

        Total tokens read from prompt cache.

      • input_tokens: optional number

        Total input tokens consumed across all turns.

      • output_tokens: optional number

        Total output tokens generated across all turns.

Example

curl https://api.anthropic.com/v1/sessions/$SESSION_ID/threads/$THREAD_ID/archive \
    -X POST \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: managed-agents-2026-04-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

Response

{
  "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 object { id, agent, archived_at, 8 more }

    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

      • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

        • name: string

        • type: "url"

          • "url"

        • url: string

      • model: BetaManagedAgentsModelConfig

        Model identifier and configuration.

        • id: BetaManagedAgentsModel

          The model that will power your agent.

          See models for additional details and options.

          • "claude-opus-4-7" or "claude-opus-4-6" or "claude-sonnet-4-6" or 6 more

            The model that will power your agent.

            See models for additional details and options.

            • "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: optional "standard" or "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 of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

        • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

          A resolved Anthropic-managed skill.

          • skill_id: string

          • type: "anthropic"

            • "anthropic"

          • version: string

        • BetaManagedAgentsCustomSkill object { skill_id, type, version }

          A resolved user-created custom skill.

          • skill_id: string

          • type: "custom"

            • "custom"

          • version: string

      • system: string

      • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

        • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

          • configs: array of BetaManagedAgentsAgentToolConfig

            • enabled: boolean

            • name: "bash" or "edit" or "read" or 5 more

              Built-in agent tool identifier.

              • "bash"

              • "edit"

              • "read"

              • "write"

              • "glob"

              • "grep"

              • "web_fetch"

              • "web_search"

            • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

              Permission policy for tool execution.

              • BetaManagedAgentsAlwaysAllowPolicy object { type }

                Tool calls are automatically approved without user confirmation.

                • type: "always_allow"

                  • "always_allow"

              • BetaManagedAgentsAlwaysAskPolicy object { type }

                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 or BetaManagedAgentsAlwaysAskPolicy

              Permission policy for tool execution.

              • BetaManagedAgentsAlwaysAllowPolicy object { type }

                Tool calls are automatically approved without user confirmation.

              • BetaManagedAgentsAlwaysAskPolicy object { type }

                Tool calls require user confirmation before execution.

          • type: "agent_toolset_20260401"

            • "agent_toolset_20260401"

        • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

          • configs: array of BetaManagedAgentsMCPToolConfig

            • enabled: boolean

            • name: string

            • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

              Permission policy for tool execution.

              • BetaManagedAgentsAlwaysAllowPolicy object { type }

                Tool calls are automatically approved without user confirmation.

              • BetaManagedAgentsAlwaysAskPolicy object { type }

                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 or BetaManagedAgentsAlwaysAskPolicy

              Permission policy for tool execution.

              • BetaManagedAgentsAlwaysAllowPolicy object { type }

                Tool calls are automatically approved without user confirmation.

              • BetaManagedAgentsAlwaysAskPolicy object { type }

                Tool calls require user confirmation before execution.

          • mcp_server_name: string

          • type: "mcp_toolset"

            • "mcp_toolset"

        • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

          A custom tool as returned in API responses.

          • description: string

          • input_schema: BetaManagedAgentsCustomToolInputSchema

            JSON Schema for custom tool input parameters.

            • properties: optional map[unknown]

              JSON Schema properties defining the tool's input parameters.

            • required: optional array of string

              List of required property names.

            • type: optional "object"

              Must be 'object' for tool input schemas.

              • "object"

          • name: string

          • type: "custom"

            • "custom"

      • type: "agent"

        • "agent"

      • version: number

    • archived_at: string

      A timestamp in RFC 3339 format

    • created_at: string

      A timestamp in RFC 3339 format

    • parent_thread_id: string

      Parent thread that spawned this thread. Null for the primary thread.

    • session_id: string

      The session this thread belongs to.

    • stats: BetaManagedAgentsSessionThreadStats

      Timing statistics for a session thread.

      • active_seconds: optional number

        Cumulative time in seconds the thread spent actively running. Excludes idle time.

      • duration_seconds: optional number

        Elapsed time since thread creation in seconds. For archived threads, frozen at the final update.

      • startup_seconds: optional 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

      Cumulative token usage for a session thread across all turns.

      • cache_creation: optional BetaManagedAgentsCacheCreationUsage

        Prompt-cache creation token usage broken down by cache lifetime.

        • ephemeral_1h_input_tokens: optional number

          Tokens used to create 1-hour ephemeral cache entries.

        • ephemeral_5m_input_tokens: optional number

          Tokens used to create 5-minute ephemeral cache entries.

      • cache_read_input_tokens: optional number

        Total tokens read from prompt cache.

      • input_tokens: optional number

        Total input tokens consumed across all turns.

      • output_tokens: optional number

        Total output tokens generated across all turns.

Beta Managed Agents Session Thread Stats

  • BetaManagedAgentsSessionThreadStats object { active_seconds, duration_seconds, startup_seconds }

    Timing statistics for a session thread.

    • active_seconds: optional number

      Cumulative time in seconds the thread spent actively running. Excludes idle time.

    • duration_seconds: optional number

      Elapsed time since thread creation in seconds. For archived threads, frozen at the final update.

    • startup_seconds: optional 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" or "idle" or "rescheduling" or "terminated"

    SessionThreadStatus enum

    • "running"

    • "idle"

    • "rescheduling"

    • "terminated"

Beta Managed Agents Session Thread Usage

  • BetaManagedAgentsSessionThreadUsage object { cache_creation, cache_read_input_tokens, input_tokens, output_tokens }

    Cumulative token usage for a session thread across all turns.

    • cache_creation: optional BetaManagedAgentsCacheCreationUsage

      Prompt-cache creation token usage broken down by cache lifetime.

      • ephemeral_1h_input_tokens: optional number

        Tokens used to create 1-hour ephemeral cache entries.

      • ephemeral_5m_input_tokens: optional number

        Tokens used to create 5-minute ephemeral cache entries.

    • cache_read_input_tokens: optional number

      Total tokens read from prompt cache.

    • input_tokens: optional number

      Total input tokens consumed across all turns.

    • output_tokens: optional number

      Total output tokens generated across all turns.

Beta Managed Agents Stream Session Thread Events

  • BetaManagedAgentsStreamSessionThreadEvents = BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or 30 more

    Server-sent event in a single thread's stream.

    • BetaManagedAgentsUserMessageEvent object { id, content, type, processed_at }

      A user message event in the session conversation.

      • id: string

        Unique identifier for this event.

      • content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock

        Array of content blocks comprising the user message.

        • BetaManagedAgentsTextBlock object { text, type }

          Regular text content.

          • text: string

            The text content.

          • type: "text"

            • "text"

        • BetaManagedAgentsImageBlock object { source, type }

          Image content specified directly as base64 data or as a reference via a URL.

          • source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource

            Union type for image source variants.

            • BetaManagedAgentsBase64ImageSource object { data, media_type, type }

              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 object { type, url }

              Image referenced by URL.

              • type: "url"

                • "url"

              • url: string

                URL of the image to fetch.

            • BetaManagedAgentsFileImageSource object { file_id, type }

              Image referenced by file ID.

              • file_id: string

                ID of a previously uploaded file.

              • type: "file"

                • "file"

          • type: "image"

            • "image"

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          Document content, either specified directly as base64 data, as text, or as a reference via a URL.

          • source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource

            Union type for document source variants.

            • BetaManagedAgentsBase64DocumentSource object { data, media_type, type }

              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 object { data, media_type, type }

              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 object { type, url }

              Document referenced by URL.

              • type: "url"

                • "url"

              • url: string

                URL of the document to fetch.

            • BetaManagedAgentsFileDocumentSource object { file_id, type }

              Document referenced by file ID.

              • file_id: string

                ID of a previously uploaded file.

              • type: "file"

                • "file"

          • type: "document"

            • "document"

          • context: optional string

            Additional context about the document for the model.

          • title: optional string

            The title of the document.

      • type: "user.message"

        • "user.message"

      • processed_at: optional string

        A timestamp in RFC 3339 format

    • BetaManagedAgentsUserInterruptEvent object { id, type, processed_at, session_thread_id }

      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: optional string

        A timestamp in RFC 3339 format

      • session_thread_id: optional string

        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 object { id, result, tool_use_id, 4 more }

      A tool confirmation event that approves or denies a pending tool execution.

      • id: string

        Unique identifier for this event.

      • result: "allow" or "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 stop_reason.event_ids field.

      • type: "user.tool_confirmation"

        • "user.tool_confirmation"

      • deny_message: optional string

        Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.

      • processed_at: optional string

        A timestamp in RFC 3339 format

      • session_thread_id: optional string

        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 object { id, custom_tool_use_id, type, 4 more }

      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 stop_reason.event_ids field.

      • type: "user.custom_tool_result"

        • "user.custom_tool_result"

      • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

        The result content returned by the tool.

        • BetaManagedAgentsTextBlock object { text, type }

          Regular text content.

        • BetaManagedAgentsImageBlock object { source, type }

          Image content specified directly as base64 data or as a reference via a URL.

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          Document content, either specified directly as base64 data, as text, or as a reference via a URL.

        • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

          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 of BetaManagedAgentsSearchResultContent

            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: optional boolean

        Whether the tool execution resulted in an error.

      • processed_at: optional string

        A timestamp in RFC 3339 format

      • session_thread_id: optional string

        Routes this result to a subagent thread. Copy from the agent.custom_tool_use event's session_thread_id.

    • BetaManagedAgentsAgentCustomToolUseEvent object { id, input, name, 3 more }

      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: map[unknown]

        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: optional string

        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 object { id, content, processed_at, type }

      An agent response event in the session conversation.

      • id: string

        Unique identifier for this event.

      • content: array of BetaManagedAgentsTextBlock

        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 object { id, processed_at, type }

      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 object { id, input, mcp_server_name, 5 more }

      Event emitted when the agent invokes a tool provided by an MCP server.

      • id: string

        Unique identifier for this event.

      • input: map[unknown]

        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: optional "allow" or "ask" or "deny"

        AgentEvaluatedPermission enum

        • "allow"

        • "ask"

        • "deny"

      • session_thread_id: optional string

        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 object { id, mcp_tool_use_id, processed_at, 3 more }

      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: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

        The result content returned by the tool.

        • BetaManagedAgentsTextBlock object { text, type }

          Regular text content.

        • BetaManagedAgentsImageBlock object { source, type }

          Image content specified directly as base64 data or as a reference via a URL.

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          Document content, either specified directly as base64 data, as text, or as a reference via a URL.

        • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

          A block containing a web search result.

      • is_error: optional boolean

        Whether the tool execution resulted in an error.

    • BetaManagedAgentsAgentToolUseEvent object { id, input, name, 4 more }

      Event emitted when the agent invokes a built-in agent tool.

      • id: string

        Unique identifier for this event.

      • input: map[unknown]

        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: optional "allow" or "ask" or "deny"

        AgentEvaluatedPermission enum

        • "allow"

        • "ask"

        • "deny"

      • session_thread_id: optional string

        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 object { id, processed_at, tool_use_id, 3 more }

      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: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

        The result content returned by the tool.

        • BetaManagedAgentsTextBlock object { text, type }

          Regular text content.

        • BetaManagedAgentsImageBlock object { source, type }

          Image content specified directly as base64 data or as a reference via a URL.

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          Document content, either specified directly as base64 data, as text, or as a reference via a URL.

        • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

          A block containing a web search result.

      • is_error: optional boolean

        Whether the tool execution resulted in an error.

    • BetaManagedAgentsAgentThreadMessageReceivedEvent object { id, content, from_session_thread_id, 3 more }

      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 of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock

        Message content blocks.

        • BetaManagedAgentsTextBlock object { text, type }

          Regular text content.

        • BetaManagedAgentsImageBlock object { source, type }

          Image content specified directly as base64 data or as a reference via a URL.

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          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: optional string

        Name of the callable agent this message came from. Absent when received from the primary agent.

    • BetaManagedAgentsAgentThreadMessageSentEvent object { id, content, processed_at, 3 more }

      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 of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock

        Message content blocks.

        • BetaManagedAgentsTextBlock object { text, type }

          Regular text content.

        • BetaManagedAgentsImageBlock object { source, type }

          Image content specified directly as base64 data or as a reference via a URL.

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          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: optional string

        Name of the callable agent this message was sent to. Absent when sent to the primary agent.

    • BetaManagedAgentsAgentThreadContextCompactedEvent object { id, processed_at, type }

      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 object { id, error, processed_at, type }

      An error event indicating a problem occurred during session execution.

      • id: string

        Unique identifier for this event.

      • error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 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 object { message, retry_status, type }

          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 or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            What the client should do next in response to this error.

            • BetaManagedAgentsRetryStatusRetrying object { type }

              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 object { type }

              This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

              • type: "exhausted"

                • "exhausted"

            • BetaManagedAgentsRetryStatusTerminal object { type }

              The session encountered a terminal error and will transition to terminated state.

              • type: "terminal"

                • "terminal"

          • type: "unknown_error"

            • "unknown_error"

        • BetaManagedAgentsModelOverloadedError object { message, retry_status, type }

          The model is currently overloaded. Emitted after automatic retries are exhausted.

          • message: string

            Human-readable error description.

          • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            What the client should do next in response to this error.

            • BetaManagedAgentsRetryStatusRetrying object { type }

              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 object { type }

              This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

            • BetaManagedAgentsRetryStatusTerminal object { type }

              The session encountered a terminal error and will transition to terminated state.

          • type: "model_overloaded_error"

            • "model_overloaded_error"

        • BetaManagedAgentsModelRateLimitedError object { message, retry_status, type }

          The model request was rate-limited.

          • message: string

            Human-readable error description.

          • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            What the client should do next in response to this error.

            • BetaManagedAgentsRetryStatusRetrying object { type }

              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 object { type }

              This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

            • BetaManagedAgentsRetryStatusTerminal object { type }

              The session encountered a terminal error and will transition to terminated state.

          • type: "model_rate_limited_error"

            • "model_rate_limited_error"

        • BetaManagedAgentsModelRequestFailedError object { message, retry_status, type }

          A model request failed for a reason other than overload or rate-limiting.

          • message: string

            Human-readable error description.

          • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            What the client should do next in response to this error.

            • BetaManagedAgentsRetryStatusRetrying object { type }

              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 object { type }

              This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

            • BetaManagedAgentsRetryStatusTerminal object { type }

              The session encountered a terminal error and will transition to terminated state.

          • type: "model_request_failed_error"

            • "model_request_failed_error"

        • BetaManagedAgentsMCPConnectionFailedError object { mcp_server_name, message, retry_status, type }

          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 or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            What the client should do next in response to this error.

            • BetaManagedAgentsRetryStatusRetrying object { type }

              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 object { type }

              This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

            • BetaManagedAgentsRetryStatusTerminal object { type }

              The session encountered a terminal error and will transition to terminated state.

          • type: "mcp_connection_failed_error"

            • "mcp_connection_failed_error"

        • BetaManagedAgentsMCPAuthenticationFailedError object { mcp_server_name, message, retry_status, type }

          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 or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            What the client should do next in response to this error.

            • BetaManagedAgentsRetryStatusRetrying object { type }

              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 object { type }

              This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

            • BetaManagedAgentsRetryStatusTerminal object { type }

              The session encountered a terminal error and will transition to terminated state.

          • type: "mcp_authentication_failed_error"

            • "mcp_authentication_failed_error"

        • BetaManagedAgentsBillingError object { message, retry_status, type }

          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 or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            What the client should do next in response to this error.

            • BetaManagedAgentsRetryStatusRetrying object { type }

              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 object { type }

              This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

            • BetaManagedAgentsRetryStatusTerminal object { type }

              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 object { id, processed_at, type }

      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 object { id, processed_at, type }

      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 object { id, processed_at, stop_reason, type }

      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 or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted

        The agent completed its turn naturally and is ready for the next user message.

        • BetaManagedAgentsSessionEndTurn object { type }

          The agent completed its turn naturally and is ready for the next user message.

          • type: "end_turn"

            • "end_turn"

        • BetaManagedAgentsSessionRequiresAction object { event_ids, type }

          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 of string

            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 object { type }

          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 object { id, processed_at, type }

      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 object { id, agent_name, processed_at, 2 more }

      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 object { id, iteration, outcome_id, 2 more }

      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 object { id, explanation, iteration, 6 more }

      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: optional "standard" or "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"

    • BetaManagedAgentsSpanModelRequestStartEvent object { id, processed_at, type }

      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 object { id, is_error, model_request_start_id, 3 more }

      Emitted when a model request completes.

      • id: string

        Unique identifier for this event.

      • is_error: boolean

        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 object { id, iteration, outcome_id, 2 more }

      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 object { id, description, max_iterations, 4 more }

      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

        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 or BetaManagedAgentsTextRubric

        Rubric for grading the quality of an outcome.

        • BetaManagedAgentsFileRubric object { file_id, type }

          Rubric referenced by a file uploaded via the Files API.

          • file_id: string

            ID of the rubric file.

          • type: "file"

            • "file"

        • BetaManagedAgentsTextRubric object { content, type }

          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 object { id, processed_at, type }

      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 object { id, agent_name, processed_at, 2 more }

      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 object { id, agent_name, processed_at, 3 more }

      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 or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted

        The agent completed its turn naturally and is ready for the next user message.

        • BetaManagedAgentsSessionEndTurn object { type }

          The agent completed its turn naturally and is ready for the next user message.

        • BetaManagedAgentsSessionRequiresAction object { event_ids, type }

          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 object { type }

          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 object { id, agent_name, processed_at, 2 more }

      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 object { id, tool_use_id, type, 4 more }

      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 stop_reason.event_ids field.

      • type: "user.tool_result"

        • "user.tool_result"

      • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

        The result content returned by the tool.

        • BetaManagedAgentsTextBlock object { text, type }

          Regular text content.

        • BetaManagedAgentsImageBlock object { source, type }

          Image content specified directly as base64 data or as a reference via a URL.

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          Document content, either specified directly as base64 data, as text, or as a reference via a URL.

        • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

          A block containing a web search result.

      • is_error: optional boolean

        Whether the tool execution resulted in an error.

      • processed_at: optional string

        A timestamp in RFC 3339 format

      • session_thread_id: optional string

        Routes this result to a subagent thread. Copy from the agent.tool_use event's session_thread_id.

    • BetaManagedAgentsSessionThreadStatusRescheduledEvent object { id, agent_name, processed_at, 2 more }

      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 object { id, processed_at, type, 3 more }

      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: optional BetaManagedAgentsSessionAgent

        Resolved agent definition for a session. Snapshot of the agent at session creation time.

        • id: string

        • description: string

        • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

          • name: string

          • type: "url"

            • "url"

          • url: string

        • model: BetaManagedAgentsModelConfig

          Model identifier and configuration.

          • id: BetaManagedAgentsModel

            The model that will power your agent.

            See models for additional details and options.

            • "claude-opus-4-7" or "claude-opus-4-6" or "claude-sonnet-4-6" or 6 more

              The model that will power your agent.

              See models for additional details and options.

              • "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: optional "standard" or "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

          Resolved coordinator topology with full agent definitions for each roster member.

          • agents: array of BetaManagedAgentsSessionThreadAgent

            Full agent definitions the coordinator may spawn as session threads.

            • id: string

            • description: string

            • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

              • name: string

              • type: "url"

              • url: string

            • model: BetaManagedAgentsModelConfig

              Model identifier and configuration.

            • name: string

            • skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

              • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

                A resolved Anthropic-managed skill.

                • skill_id: string

                • type: "anthropic"

                  • "anthropic"

                • version: string

              • BetaManagedAgentsCustomSkill object { skill_id, type, version }

                A resolved user-created custom skill.

                • skill_id: string

                • type: "custom"

                  • "custom"

                • version: string

            • system: string

            • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

              • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

                • configs: array of BetaManagedAgentsAgentToolConfig

                  • enabled: boolean

                  • name: "bash" or "edit" or "read" or 5 more

                    Built-in agent tool identifier.

                    • "bash"

                    • "edit"

                    • "read"

                    • "write"

                    • "glob"

                    • "grep"

                    • "web_fetch"

                    • "web_search"

                  • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                    Permission policy for tool execution.

                    • BetaManagedAgentsAlwaysAllowPolicy object { type }

                      Tool calls are automatically approved without user confirmation.

                      • type: "always_allow"

                        • "always_allow"

                    • BetaManagedAgentsAlwaysAskPolicy object { type }

                      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 or BetaManagedAgentsAlwaysAskPolicy

                    Permission policy for tool execution.

                    • BetaManagedAgentsAlwaysAllowPolicy object { type }

                      Tool calls are automatically approved without user confirmation.

                    • BetaManagedAgentsAlwaysAskPolicy object { type }

                      Tool calls require user confirmation before execution.

                • type: "agent_toolset_20260401"

                  • "agent_toolset_20260401"

              • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

                • configs: array of BetaManagedAgentsMCPToolConfig

                  • enabled: boolean

                  • name: string

                  • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                    Permission policy for tool execution.

                    • BetaManagedAgentsAlwaysAllowPolicy object { type }

                      Tool calls are automatically approved without user confirmation.

                    • BetaManagedAgentsAlwaysAskPolicy object { type }

                      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 or BetaManagedAgentsAlwaysAskPolicy

                    Permission policy for tool execution.

                    • BetaManagedAgentsAlwaysAllowPolicy object { type }

                      Tool calls are automatically approved without user confirmation.

                    • BetaManagedAgentsAlwaysAskPolicy object { type }

                      Tool calls require user confirmation before execution.

                • mcp_server_name: string

                • type: "mcp_toolset"

                  • "mcp_toolset"

              • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

                A custom tool as returned in API responses.

                • description: string

                • input_schema: BetaManagedAgentsCustomToolInputSchema

                  JSON Schema for custom tool input parameters.

                  • properties: optional map[unknown]

                    JSON Schema properties defining the tool's input parameters.

                  • required: optional array of string

                    List of required property names.

                  • type: optional "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 of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

          • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

            A resolved Anthropic-managed skill.

          • BetaManagedAgentsCustomSkill object { skill_id, type, version }

            A resolved user-created custom skill.

        • system: string

        • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

          • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

          • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

          • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

            A custom tool as returned in API responses.

        • type: "agent"

          • "agent"

        • version: number

      • metadata: optional map[string]

        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: optional string

        The session's new title. Present only when the update changed it.

Events

List Session Thread Events

get /v1/sessions/{session_id}/threads/{thread_id}/events

List Session Thread Events

Path Parameters

  • session_id: string

  • thread_id: string

Query Parameters

  • limit: optional number

    Query parameter for limit

  • page: optional string

    Query parameter for page

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Returns

  • data: optional array of BetaManagedAgentsSessionEvent

    Events for the thread, ordered by created_at.

    • BetaManagedAgentsUserMessageEvent object { id, content, type, processed_at }

      A user message event in the session conversation.

      • id: string

        Unique identifier for this event.

      • content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock

        Array of content blocks comprising the user message.

        • BetaManagedAgentsTextBlock object { text, type }

          Regular text content.

          • text: string

            The text content.

          • type: "text"

            • "text"

        • BetaManagedAgentsImageBlock object { source, type }

          Image content specified directly as base64 data or as a reference via a URL.

          • source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource

            Union type for image source variants.

            • BetaManagedAgentsBase64ImageSource object { data, media_type, type }

              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 object { type, url }

              Image referenced by URL.

              • type: "url"

                • "url"

              • url: string

                URL of the image to fetch.

            • BetaManagedAgentsFileImageSource object { file_id, type }

              Image referenced by file ID.

              • file_id: string

                ID of a previously uploaded file.

              • type: "file"

                • "file"

          • type: "image"

            • "image"

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          Document content, either specified directly as base64 data, as text, or as a reference via a URL.

          • source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource

            Union type for document source variants.

            • BetaManagedAgentsBase64DocumentSource object { data, media_type, type }

              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 object { data, media_type, type }

              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 object { type, url }

              Document referenced by URL.

              • type: "url"

                • "url"

              • url: string

                URL of the document to fetch.

            • BetaManagedAgentsFileDocumentSource object { file_id, type }

              Document referenced by file ID.

              • file_id: string

                ID of a previously uploaded file.

              • type: "file"

                • "file"

          • type: "document"

            • "document"

          • context: optional string

            Additional context about the document for the model.

          • title: optional string

            The title of the document.

      • type: "user.message"

        • "user.message"

      • processed_at: optional string

        A timestamp in RFC 3339 format

    • BetaManagedAgentsUserInterruptEvent object { id, type, processed_at, session_thread_id }

      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: optional string

        A timestamp in RFC 3339 format

      • session_thread_id: optional string

        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 object { id, result, tool_use_id, 4 more }

      A tool confirmation event that approves or denies a pending tool execution.

      • id: string

        Unique identifier for this event.

      • result: "allow" or "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 stop_reason.event_ids field.

      • type: "user.tool_confirmation"

        • "user.tool_confirmation"

      • deny_message: optional string

        Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.

      • processed_at: optional string

        A timestamp in RFC 3339 format

      • session_thread_id: optional string

        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 object { id, custom_tool_use_id, type, 4 more }

      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 stop_reason.event_ids field.

      • type: "user.custom_tool_result"

        • "user.custom_tool_result"

      • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

        The result content returned by the tool.

        • BetaManagedAgentsTextBlock object { text, type }

          Regular text content.

        • BetaManagedAgentsImageBlock object { source, type }

          Image content specified directly as base64 data or as a reference via a URL.

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          Document content, either specified directly as base64 data, as text, or as a reference via a URL.

        • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

          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 of BetaManagedAgentsSearchResultContent

            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: optional boolean

        Whether the tool execution resulted in an error.

      • processed_at: optional string

        A timestamp in RFC 3339 format

      • session_thread_id: optional string

        Routes this result to a subagent thread. Copy from the agent.custom_tool_use event's session_thread_id.

    • BetaManagedAgentsAgentCustomToolUseEvent object { id, input, name, 3 more }

      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: map[unknown]

        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: optional string

        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 object { id, content, processed_at, type }

      An agent response event in the session conversation.

      • id: string

        Unique identifier for this event.

      • content: array of BetaManagedAgentsTextBlock

        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 object { id, processed_at, type }

      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 object { id, input, mcp_server_name, 5 more }

      Event emitted when the agent invokes a tool provided by an MCP server.

      • id: string

        Unique identifier for this event.

      • input: map[unknown]

        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: optional "allow" or "ask" or "deny"

        AgentEvaluatedPermission enum

        • "allow"

        • "ask"

        • "deny"

      • session_thread_id: optional string

        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 object { id, mcp_tool_use_id, processed_at, 3 more }

      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: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

        The result content returned by the tool.

        • BetaManagedAgentsTextBlock object { text, type }

          Regular text content.

        • BetaManagedAgentsImageBlock object { source, type }

          Image content specified directly as base64 data or as a reference via a URL.

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          Document content, either specified directly as base64 data, as text, or as a reference via a URL.

        • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

          A block containing a web search result.

      • is_error: optional boolean

        Whether the tool execution resulted in an error.

    • BetaManagedAgentsAgentToolUseEvent object { id, input, name, 4 more }

      Event emitted when the agent invokes a built-in agent tool.

      • id: string

        Unique identifier for this event.

      • input: map[unknown]

        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: optional "allow" or "ask" or "deny"

        AgentEvaluatedPermission enum

        • "allow"

        • "ask"

        • "deny"

      • session_thread_id: optional string

        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 object { id, processed_at, tool_use_id, 3 more }

      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: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

        The result content returned by the tool.

        • BetaManagedAgentsTextBlock object { text, type }

          Regular text content.

        • BetaManagedAgentsImageBlock object { source, type }

          Image content specified directly as base64 data or as a reference via a URL.

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          Document content, either specified directly as base64 data, as text, or as a reference via a URL.

        • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

          A block containing a web search result.

      • is_error: optional boolean

        Whether the tool execution resulted in an error.

    • BetaManagedAgentsAgentThreadMessageReceivedEvent object { id, content, from_session_thread_id, 3 more }

      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 of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock

        Message content blocks.

        • BetaManagedAgentsTextBlock object { text, type }

          Regular text content.

        • BetaManagedAgentsImageBlock object { source, type }

          Image content specified directly as base64 data or as a reference via a URL.

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          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: optional string

        Name of the callable agent this message came from. Absent when received from the primary agent.

    • BetaManagedAgentsAgentThreadMessageSentEvent object { id, content, processed_at, 3 more }

      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 of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock

        Message content blocks.

        • BetaManagedAgentsTextBlock object { text, type }

          Regular text content.

        • BetaManagedAgentsImageBlock object { source, type }

          Image content specified directly as base64 data or as a reference via a URL.

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          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: optional string

        Name of the callable agent this message was sent to. Absent when sent to the primary agent.

    • BetaManagedAgentsAgentThreadContextCompactedEvent object { id, processed_at, type }

      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 object { id, error, processed_at, type }

      An error event indicating a problem occurred during session execution.

      • id: string

        Unique identifier for this event.

      • error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 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 object { message, retry_status, type }

          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 or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            What the client should do next in response to this error.

            • BetaManagedAgentsRetryStatusRetrying object { type }

              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 object { type }

              This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

              • type: "exhausted"

                • "exhausted"

            • BetaManagedAgentsRetryStatusTerminal object { type }

              The session encountered a terminal error and will transition to terminated state.

              • type: "terminal"

                • "terminal"

          • type: "unknown_error"

            • "unknown_error"

        • BetaManagedAgentsModelOverloadedError object { message, retry_status, type }

          The model is currently overloaded. Emitted after automatic retries are exhausted.

          • message: string

            Human-readable error description.

          • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            What the client should do next in response to this error.

            • BetaManagedAgentsRetryStatusRetrying object { type }

              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 object { type }

              This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

            • BetaManagedAgentsRetryStatusTerminal object { type }

              The session encountered a terminal error and will transition to terminated state.

          • type: "model_overloaded_error"

            • "model_overloaded_error"

        • BetaManagedAgentsModelRateLimitedError object { message, retry_status, type }

          The model request was rate-limited.

          • message: string

            Human-readable error description.

          • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            What the client should do next in response to this error.

            • BetaManagedAgentsRetryStatusRetrying object { type }

              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 object { type }

              This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

            • BetaManagedAgentsRetryStatusTerminal object { type }

              The session encountered a terminal error and will transition to terminated state.

          • type: "model_rate_limited_error"

            • "model_rate_limited_error"

        • BetaManagedAgentsModelRequestFailedError object { message, retry_status, type }

          A model request failed for a reason other than overload or rate-limiting.

          • message: string

            Human-readable error description.

          • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            What the client should do next in response to this error.

            • BetaManagedAgentsRetryStatusRetrying object { type }

              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 object { type }

              This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

            • BetaManagedAgentsRetryStatusTerminal object { type }

              The session encountered a terminal error and will transition to terminated state.

          • type: "model_request_failed_error"

            • "model_request_failed_error"

        • BetaManagedAgentsMCPConnectionFailedError object { mcp_server_name, message, retry_status, type }

          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 or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            What the client should do next in response to this error.

            • BetaManagedAgentsRetryStatusRetrying object { type }

              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 object { type }

              This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

            • BetaManagedAgentsRetryStatusTerminal object { type }

              The session encountered a terminal error and will transition to terminated state.

          • type: "mcp_connection_failed_error"

            • "mcp_connection_failed_error"

        • BetaManagedAgentsMCPAuthenticationFailedError object { mcp_server_name, message, retry_status, type }

          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 or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            What the client should do next in response to this error.

            • BetaManagedAgentsRetryStatusRetrying object { type }

              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 object { type }

              This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

            • BetaManagedAgentsRetryStatusTerminal object { type }

              The session encountered a terminal error and will transition to terminated state.

          • type: "mcp_authentication_failed_error"

            • "mcp_authentication_failed_error"

        • BetaManagedAgentsBillingError object { message, retry_status, type }

          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 or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            What the client should do next in response to this error.

            • BetaManagedAgentsRetryStatusRetrying object { type }

              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 object { type }

              This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

            • BetaManagedAgentsRetryStatusTerminal object { type }

              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 object { id, processed_at, type }

      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 object { id, processed_at, type }

      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 object { id, processed_at, stop_reason, type }

      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 or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted

        The agent completed its turn naturally and is ready for the next user message.

        • BetaManagedAgentsSessionEndTurn object { type }

          The agent completed its turn naturally and is ready for the next user message.

          • type: "end_turn"

            • "end_turn"

        • BetaManagedAgentsSessionRequiresAction object { event_ids, type }

          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 of string

            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 object { type }

          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 object { id, processed_at, type }

      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 object { id, agent_name, processed_at, 2 more }

      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 object { id, iteration, outcome_id, 2 more }

      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 object { id, explanation, iteration, 6 more }

      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: optional "standard" or "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"

    • BetaManagedAgentsSpanModelRequestStartEvent object { id, processed_at, type }

      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 object { id, is_error, model_request_start_id, 3 more }

      Emitted when a model request completes.

      • id: string

        Unique identifier for this event.

      • is_error: boolean

        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 object { id, iteration, outcome_id, 2 more }

      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 object { id, description, max_iterations, 4 more }

      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

        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 or BetaManagedAgentsTextRubric

        Rubric for grading the quality of an outcome.

        • BetaManagedAgentsFileRubric object { file_id, type }

          Rubric referenced by a file uploaded via the Files API.

          • file_id: string

            ID of the rubric file.

          • type: "file"

            • "file"

        • BetaManagedAgentsTextRubric object { content, type }

          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 object { id, processed_at, type }

      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 object { id, agent_name, processed_at, 2 more }

      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 object { id, agent_name, processed_at, 3 more }

      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 or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted

        The agent completed its turn naturally and is ready for the next user message.

        • BetaManagedAgentsSessionEndTurn object { type }

          The agent completed its turn naturally and is ready for the next user message.

        • BetaManagedAgentsSessionRequiresAction object { event_ids, type }

          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 object { type }

          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 object { id, agent_name, processed_at, 2 more }

      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 object { id, tool_use_id, type, 4 more }

      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 stop_reason.event_ids field.

      • type: "user.tool_result"

        • "user.tool_result"

      • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

        The result content returned by the tool.

        • BetaManagedAgentsTextBlock object { text, type }

          Regular text content.

        • BetaManagedAgentsImageBlock object { source, type }

          Image content specified directly as base64 data or as a reference via a URL.

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          Document content, either specified directly as base64 data, as text, or as a reference via a URL.

        • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

          A block containing a web search result.

      • is_error: optional boolean

        Whether the tool execution resulted in an error.

      • processed_at: optional string

        A timestamp in RFC 3339 format

      • session_thread_id: optional string

        Routes this result to a subagent thread. Copy from the agent.tool_use event's session_thread_id.

    • BetaManagedAgentsSessionThreadStatusRescheduledEvent object { id, agent_name, processed_at, 2 more }

      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 object { id, processed_at, type, 3 more }

      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: optional BetaManagedAgentsSessionAgent

        Resolved agent definition for a session. Snapshot of the agent at session creation time.

        • id: string

        • description: string

        • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

          • name: string

          • type: "url"

            • "url"

          • url: string

        • model: BetaManagedAgentsModelConfig

          Model identifier and configuration.

          • id: BetaManagedAgentsModel

            The model that will power your agent.

            See models for additional details and options.

            • "claude-opus-4-7" or "claude-opus-4-6" or "claude-sonnet-4-6" or 6 more

              The model that will power your agent.

              See models for additional details and options.

              • "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: optional "standard" or "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

          Resolved coordinator topology with full agent definitions for each roster member.

          • agents: array of BetaManagedAgentsSessionThreadAgent

            Full agent definitions the coordinator may spawn as session threads.

            • id: string

            • description: string

            • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

              • name: string

              • type: "url"

              • url: string

            • model: BetaManagedAgentsModelConfig

              Model identifier and configuration.

            • name: string

            • skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

              • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

                A resolved Anthropic-managed skill.

                • skill_id: string

                • type: "anthropic"

                  • "anthropic"

                • version: string

              • BetaManagedAgentsCustomSkill object { skill_id, type, version }

                A resolved user-created custom skill.

                • skill_id: string

                • type: "custom"

                  • "custom"

                • version: string

            • system: string

            • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

              • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

                • configs: array of BetaManagedAgentsAgentToolConfig

                  • enabled: boolean

                  • name: "bash" or "edit" or "read" or 5 more

                    Built-in agent tool identifier.

                    • "bash"

                    • "edit"

                    • "read"

                    • "write"

                    • "glob"

                    • "grep"

                    • "web_fetch"

                    • "web_search"

                  • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                    Permission policy for tool execution.

                    • BetaManagedAgentsAlwaysAllowPolicy object { type }

                      Tool calls are automatically approved without user confirmation.

                      • type: "always_allow"

                        • "always_allow"

                    • BetaManagedAgentsAlwaysAskPolicy object { type }

                      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 or BetaManagedAgentsAlwaysAskPolicy

                    Permission policy for tool execution.

                    • BetaManagedAgentsAlwaysAllowPolicy object { type }

                      Tool calls are automatically approved without user confirmation.

                    • BetaManagedAgentsAlwaysAskPolicy object { type }

                      Tool calls require user confirmation before execution.

                • type: "agent_toolset_20260401"

                  • "agent_toolset_20260401"

              • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

                • configs: array of BetaManagedAgentsMCPToolConfig

                  • enabled: boolean

                  • name: string

                  • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                    Permission policy for tool execution.

                    • BetaManagedAgentsAlwaysAllowPolicy object { type }

                      Tool calls are automatically approved without user confirmation.

                    • BetaManagedAgentsAlwaysAskPolicy object { type }

                      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 or BetaManagedAgentsAlwaysAskPolicy

                    Permission policy for tool execution.

                    • BetaManagedAgentsAlwaysAllowPolicy object { type }

                      Tool calls are automatically approved without user confirmation.

                    • BetaManagedAgentsAlwaysAskPolicy object { type }

                      Tool calls require user confirmation before execution.

                • mcp_server_name: string

                • type: "mcp_toolset"

                  • "mcp_toolset"

              • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

                A custom tool as returned in API responses.

                • description: string

                • input_schema: BetaManagedAgentsCustomToolInputSchema

                  JSON Schema for custom tool input parameters.

                  • properties: optional map[unknown]

                    JSON Schema properties defining the tool's input parameters.

                  • required: optional array of string

                    List of required property names.

                  • type: optional "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 of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

          • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

            A resolved Anthropic-managed skill.

          • BetaManagedAgentsCustomSkill object { skill_id, type, version }

            A resolved user-created custom skill.

        • system: string

        • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

          • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

          • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

          • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

            A custom tool as returned in API responses.

        • type: "agent"

          • "agent"

        • version: number

      • metadata: optional map[string]

        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: optional string

        The session's new title. Present only when the update changed it.

  • next_page: optional string

    Opaque cursor for the next page. Null when no more results.

Example

curl https://api.anthropic.com/v1/sessions/$SESSION_ID/threads/$THREAD_ID/events \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: managed-agents-2026-04-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

Response

{
  "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

get /v1/sessions/{session_id}/threads/{thread_id}/stream

Stream Session Thread Events

Path Parameters

  • session_id: string

  • thread_id: string

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Returns

  • BetaManagedAgentsStreamSessionThreadEvents = BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or 30 more

    Server-sent event in a single thread's stream.

    • BetaManagedAgentsUserMessageEvent object { id, content, type, processed_at }

      A user message event in the session conversation.

      • id: string

        Unique identifier for this event.

      • content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock

        Array of content blocks comprising the user message.

        • BetaManagedAgentsTextBlock object { text, type }

          Regular text content.

          • text: string

            The text content.

          • type: "text"

            • "text"

        • BetaManagedAgentsImageBlock object { source, type }

          Image content specified directly as base64 data or as a reference via a URL.

          • source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource

            Union type for image source variants.

            • BetaManagedAgentsBase64ImageSource object { data, media_type, type }

              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 object { type, url }

              Image referenced by URL.

              • type: "url"

                • "url"

              • url: string

                URL of the image to fetch.

            • BetaManagedAgentsFileImageSource object { file_id, type }

              Image referenced by file ID.

              • file_id: string

                ID of a previously uploaded file.

              • type: "file"

                • "file"

          • type: "image"

            • "image"

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          Document content, either specified directly as base64 data, as text, or as a reference via a URL.

          • source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource

            Union type for document source variants.

            • BetaManagedAgentsBase64DocumentSource object { data, media_type, type }

              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 object { data, media_type, type }

              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 object { type, url }

              Document referenced by URL.

              • type: "url"

                • "url"

              • url: string

                URL of the document to fetch.

            • BetaManagedAgentsFileDocumentSource object { file_id, type }

              Document referenced by file ID.

              • file_id: string

                ID of a previously uploaded file.

              • type: "file"

                • "file"

          • type: "document"

            • "document"

          • context: optional string

            Additional context about the document for the model.

          • title: optional string

            The title of the document.

      • type: "user.message"

        • "user.message"

      • processed_at: optional string

        A timestamp in RFC 3339 format

    • BetaManagedAgentsUserInterruptEvent object { id, type, processed_at, session_thread_id }

      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: optional string

        A timestamp in RFC 3339 format

      • session_thread_id: optional string

        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 object { id, result, tool_use_id, 4 more }

      A tool confirmation event that approves or denies a pending tool execution.

      • id: string

        Unique identifier for this event.

      • result: "allow" or "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 stop_reason.event_ids field.

      • type: "user.tool_confirmation"

        • "user.tool_confirmation"

      • deny_message: optional string

        Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.

      • processed_at: optional string

        A timestamp in RFC 3339 format

      • session_thread_id: optional string

        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 object { id, custom_tool_use_id, type, 4 more }

      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 stop_reason.event_ids field.

      • type: "user.custom_tool_result"

        • "user.custom_tool_result"

      • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

        The result content returned by the tool.

        • BetaManagedAgentsTextBlock object { text, type }

          Regular text content.

        • BetaManagedAgentsImageBlock object { source, type }

          Image content specified directly as base64 data or as a reference via a URL.

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          Document content, either specified directly as base64 data, as text, or as a reference via a URL.

        • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

          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 of BetaManagedAgentsSearchResultContent

            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: optional boolean

        Whether the tool execution resulted in an error.

      • processed_at: optional string

        A timestamp in RFC 3339 format

      • session_thread_id: optional string

        Routes this result to a subagent thread. Copy from the agent.custom_tool_use event's session_thread_id.

    • BetaManagedAgentsAgentCustomToolUseEvent object { id, input, name, 3 more }

      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: map[unknown]

        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: optional string

        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 object { id, content, processed_at, type }

      An agent response event in the session conversation.

      • id: string

        Unique identifier for this event.

      • content: array of BetaManagedAgentsTextBlock

        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 object { id, processed_at, type }

      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 object { id, input, mcp_server_name, 5 more }

      Event emitted when the agent invokes a tool provided by an MCP server.

      • id: string

        Unique identifier for this event.

      • input: map[unknown]

        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: optional "allow" or "ask" or "deny"

        AgentEvaluatedPermission enum

        • "allow"

        • "ask"

        • "deny"

      • session_thread_id: optional string

        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 object { id, mcp_tool_use_id, processed_at, 3 more }

      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: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

        The result content returned by the tool.

        • BetaManagedAgentsTextBlock object { text, type }

          Regular text content.

        • BetaManagedAgentsImageBlock object { source, type }

          Image content specified directly as base64 data or as a reference via a URL.

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          Document content, either specified directly as base64 data, as text, or as a reference via a URL.

        • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

          A block containing a web search result.

      • is_error: optional boolean

        Whether the tool execution resulted in an error.

    • BetaManagedAgentsAgentToolUseEvent object { id, input, name, 4 more }

      Event emitted when the agent invokes a built-in agent tool.

      • id: string

        Unique identifier for this event.

      • input: map[unknown]

        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: optional "allow" or "ask" or "deny"

        AgentEvaluatedPermission enum

        • "allow"

        • "ask"

        • "deny"

      • session_thread_id: optional string

        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 object { id, processed_at, tool_use_id, 3 more }

      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: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

        The result content returned by the tool.

        • BetaManagedAgentsTextBlock object { text, type }

          Regular text content.

        • BetaManagedAgentsImageBlock object { source, type }

          Image content specified directly as base64 data or as a reference via a URL.

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          Document content, either specified directly as base64 data, as text, or as a reference via a URL.

        • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

          A block containing a web search result.

      • is_error: optional boolean

        Whether the tool execution resulted in an error.

    • BetaManagedAgentsAgentThreadMessageReceivedEvent object { id, content, from_session_thread_id, 3 more }

      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 of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock

        Message content blocks.

        • BetaManagedAgentsTextBlock object { text, type }

          Regular text content.

        • BetaManagedAgentsImageBlock object { source, type }

          Image content specified directly as base64 data or as a reference via a URL.

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          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: optional string

        Name of the callable agent this message came from. Absent when received from the primary agent.

    • BetaManagedAgentsAgentThreadMessageSentEvent object { id, content, processed_at, 3 more }

      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 of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock

        Message content blocks.

        • BetaManagedAgentsTextBlock object { text, type }

          Regular text content.

        • BetaManagedAgentsImageBlock object { source, type }

          Image content specified directly as base64 data or as a reference via a URL.

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          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: optional string

        Name of the callable agent this message was sent to. Absent when sent to the primary agent.

    • BetaManagedAgentsAgentThreadContextCompactedEvent object { id, processed_at, type }

      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 object { id, error, processed_at, type }

      An error event indicating a problem occurred during session execution.

      • id: string

        Unique identifier for this event.

      • error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 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 object { message, retry_status, type }

          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 or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            What the client should do next in response to this error.

            • BetaManagedAgentsRetryStatusRetrying object { type }

              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 object { type }

              This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

              • type: "exhausted"

                • "exhausted"

            • BetaManagedAgentsRetryStatusTerminal object { type }

              The session encountered a terminal error and will transition to terminated state.

              • type: "terminal"

                • "terminal"

          • type: "unknown_error"

            • "unknown_error"

        • BetaManagedAgentsModelOverloadedError object { message, retry_status, type }

          The model is currently overloaded. Emitted after automatic retries are exhausted.

          • message: string

            Human-readable error description.

          • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            What the client should do next in response to this error.

            • BetaManagedAgentsRetryStatusRetrying object { type }

              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 object { type }

              This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

            • BetaManagedAgentsRetryStatusTerminal object { type }

              The session encountered a terminal error and will transition to terminated state.

          • type: "model_overloaded_error"

            • "model_overloaded_error"

        • BetaManagedAgentsModelRateLimitedError object { message, retry_status, type }

          The model request was rate-limited.

          • message: string

            Human-readable error description.

          • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            What the client should do next in response to this error.

            • BetaManagedAgentsRetryStatusRetrying object { type }

              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 object { type }

              This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

            • BetaManagedAgentsRetryStatusTerminal object { type }

              The session encountered a terminal error and will transition to terminated state.

          • type: "model_rate_limited_error"

            • "model_rate_limited_error"

        • BetaManagedAgentsModelRequestFailedError object { message, retry_status, type }

          A model request failed for a reason other than overload or rate-limiting.

          • message: string

            Human-readable error description.

          • retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            What the client should do next in response to this error.

            • BetaManagedAgentsRetryStatusRetrying object { type }

              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 object { type }

              This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

            • BetaManagedAgentsRetryStatusTerminal object { type }

              The session encountered a terminal error and will transition to terminated state.

          • type: "model_request_failed_error"

            • "model_request_failed_error"

        • BetaManagedAgentsMCPConnectionFailedError object { mcp_server_name, message, retry_status, type }

          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 or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            What the client should do next in response to this error.

            • BetaManagedAgentsRetryStatusRetrying object { type }

              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 object { type }

              This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

            • BetaManagedAgentsRetryStatusTerminal object { type }

              The session encountered a terminal error and will transition to terminated state.

          • type: "mcp_connection_failed_error"

            • "mcp_connection_failed_error"

        • BetaManagedAgentsMCPAuthenticationFailedError object { mcp_server_name, message, retry_status, type }

          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 or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            What the client should do next in response to this error.

            • BetaManagedAgentsRetryStatusRetrying object { type }

              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 object { type }

              This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

            • BetaManagedAgentsRetryStatusTerminal object { type }

              The session encountered a terminal error and will transition to terminated state.

          • type: "mcp_authentication_failed_error"

            • "mcp_authentication_failed_error"

        • BetaManagedAgentsBillingError object { message, retry_status, type }

          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 or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal

            What the client should do next in response to this error.

            • BetaManagedAgentsRetryStatusRetrying object { type }

              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 object { type }

              This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

            • BetaManagedAgentsRetryStatusTerminal object { type }

              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 object { id, processed_at, type }

      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 object { id, processed_at, type }

      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 object { id, processed_at, stop_reason, type }

      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 or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted

        The agent completed its turn naturally and is ready for the next user message.

        • BetaManagedAgentsSessionEndTurn object { type }

          The agent completed its turn naturally and is ready for the next user message.

          • type: "end_turn"

            • "end_turn"

        • BetaManagedAgentsSessionRequiresAction object { event_ids, type }

          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 of string

            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 object { type }

          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 object { id, processed_at, type }

      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 object { id, agent_name, processed_at, 2 more }

      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 object { id, iteration, outcome_id, 2 more }

      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 object { id, explanation, iteration, 6 more }

      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: optional "standard" or "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"

    • BetaManagedAgentsSpanModelRequestStartEvent object { id, processed_at, type }

      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 object { id, is_error, model_request_start_id, 3 more }

      Emitted when a model request completes.

      • id: string

        Unique identifier for this event.

      • is_error: boolean

        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 object { id, iteration, outcome_id, 2 more }

      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 object { id, description, max_iterations, 4 more }

      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

        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 or BetaManagedAgentsTextRubric

        Rubric for grading the quality of an outcome.

        • BetaManagedAgentsFileRubric object { file_id, type }

          Rubric referenced by a file uploaded via the Files API.

          • file_id: string

            ID of the rubric file.

          • type: "file"

            • "file"

        • BetaManagedAgentsTextRubric object { content, type }

          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 object { id, processed_at, type }

      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 object { id, agent_name, processed_at, 2 more }

      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 object { id, agent_name, processed_at, 3 more }

      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 or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted

        The agent completed its turn naturally and is ready for the next user message.

        • BetaManagedAgentsSessionEndTurn object { type }

          The agent completed its turn naturally and is ready for the next user message.

        • BetaManagedAgentsSessionRequiresAction object { event_ids, type }

          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 object { type }

          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 object { id, agent_name, processed_at, 2 more }

      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 object { id, tool_use_id, type, 4 more }

      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 stop_reason.event_ids field.

      • type: "user.tool_result"

        • "user.tool_result"

      • content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

        The result content returned by the tool.

        • BetaManagedAgentsTextBlock object { text, type }

          Regular text content.

        • BetaManagedAgentsImageBlock object { source, type }

          Image content specified directly as base64 data or as a reference via a URL.

        • BetaManagedAgentsDocumentBlock object { source, type, context, title }

          Document content, either specified directly as base64 data, as text, or as a reference via a URL.

        • BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }

          A block containing a web search result.

      • is_error: optional boolean

        Whether the tool execution resulted in an error.

      • processed_at: optional string

        A timestamp in RFC 3339 format

      • session_thread_id: optional string

        Routes this result to a subagent thread. Copy from the agent.tool_use event's session_thread_id.

    • BetaManagedAgentsSessionThreadStatusRescheduledEvent object { id, agent_name, processed_at, 2 more }

      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 object { id, processed_at, type, 3 more }

      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: optional BetaManagedAgentsSessionAgent

        Resolved agent definition for a session. Snapshot of the agent at session creation time.

        • id: string

        • description: string

        • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

          • name: string

          • type: "url"

            • "url"

          • url: string

        • model: BetaManagedAgentsModelConfig

          Model identifier and configuration.

          • id: BetaManagedAgentsModel

            The model that will power your agent.

            See models for additional details and options.

            • "claude-opus-4-7" or "claude-opus-4-6" or "claude-sonnet-4-6" or 6 more

              The model that will power your agent.

              See models for additional details and options.

              • "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: optional "standard" or "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

          Resolved coordinator topology with full agent definitions for each roster member.

          • agents: array of BetaManagedAgentsSessionThreadAgent

            Full agent definitions the coordinator may spawn as session threads.

            • id: string

            • description: string

            • mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition

              • name: string

              • type: "url"

              • url: string

            • model: BetaManagedAgentsModelConfig

              Model identifier and configuration.

            • name: string

            • skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

              • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

                A resolved Anthropic-managed skill.

                • skill_id: string

                • type: "anthropic"

                  • "anthropic"

                • version: string

              • BetaManagedAgentsCustomSkill object { skill_id, type, version }

                A resolved user-created custom skill.

                • skill_id: string

                • type: "custom"

                  • "custom"

                • version: string

            • system: string

            • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

              • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

                • configs: array of BetaManagedAgentsAgentToolConfig

                  • enabled: boolean

                  • name: "bash" or "edit" or "read" or 5 more

                    Built-in agent tool identifier.

                    • "bash"

                    • "edit"

                    • "read"

                    • "write"

                    • "glob"

                    • "grep"

                    • "web_fetch"

                    • "web_search"

                  • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                    Permission policy for tool execution.

                    • BetaManagedAgentsAlwaysAllowPolicy object { type }

                      Tool calls are automatically approved without user confirmation.

                      • type: "always_allow"

                        • "always_allow"

                    • BetaManagedAgentsAlwaysAskPolicy object { type }

                      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 or BetaManagedAgentsAlwaysAskPolicy

                    Permission policy for tool execution.

                    • BetaManagedAgentsAlwaysAllowPolicy object { type }

                      Tool calls are automatically approved without user confirmation.

                    • BetaManagedAgentsAlwaysAskPolicy object { type }

                      Tool calls require user confirmation before execution.

                • type: "agent_toolset_20260401"

                  • "agent_toolset_20260401"

              • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

                • configs: array of BetaManagedAgentsMCPToolConfig

                  • enabled: boolean

                  • name: string

                  • permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy

                    Permission policy for tool execution.

                    • BetaManagedAgentsAlwaysAllowPolicy object { type }

                      Tool calls are automatically approved without user confirmation.

                    • BetaManagedAgentsAlwaysAskPolicy object { type }

                      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 or BetaManagedAgentsAlwaysAskPolicy

                    Permission policy for tool execution.

                    • BetaManagedAgentsAlwaysAllowPolicy object { type }

                      Tool calls are automatically approved without user confirmation.

                    • BetaManagedAgentsAlwaysAskPolicy object { type }

                      Tool calls require user confirmation before execution.

                • mcp_server_name: string

                • type: "mcp_toolset"

                  • "mcp_toolset"

              • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

                A custom tool as returned in API responses.

                • description: string

                • input_schema: BetaManagedAgentsCustomToolInputSchema

                  JSON Schema for custom tool input parameters.

                  • properties: optional map[unknown]

                    JSON Schema properties defining the tool's input parameters.

                  • required: optional array of string

                    List of required property names.

                  • type: optional "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 of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

          • BetaManagedAgentsAnthropicSkill object { skill_id, type, version }

            A resolved Anthropic-managed skill.

          • BetaManagedAgentsCustomSkill object { skill_id, type, version }

            A resolved user-created custom skill.

        • system: string

        • tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

          • BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }

          • BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }

          • BetaManagedAgentsCustomTool object { description, input_schema, name, type }

            A custom tool as returned in API responses.

        • type: "agent"

          • "agent"

        • version: number

      • metadata: optional map[string]

        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: optional string

        The session's new title. Present only when the update changed it.

Example

curl https://api.anthropic.com/v1/sessions/$SESSION_ID/threads/$THREAD_ID/stream \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: managed-agents-2026-04-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

Response

{
  "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

post /v1/vaults

Create Vault

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Body Parameters

  • display_name: string

    Human-readable name for the vault. 1-255 characters.

  • metadata: optional map[string]

    Arbitrary key-value metadata to attach to the vault. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars.

Returns

  • BetaManagedAgentsVault object { id, archived_at, created_at, 4 more }

    A vault that stores credentials for use by agents during sessions.

    • id: string

      Unique identifier for the vault.

    • archived_at: string

      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: map[string]

      Arbitrary key-value metadata attached to the vault.

    • type: "vault"

      • "vault"

    • updated_at: string

      A timestamp in RFC 3339 format

Example

curl https://api.anthropic.com/v1/vaults \
    -H 'Content-Type: application/json' \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: managed-agents-2026-04-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY" \
    -d '{
          "display_name": "Example vault",
          "metadata": {
            "environment": "production"
          }
        }'

Response

{
  "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

get /v1/vaults

List Vaults

Query Parameters

  • include_archived: optional boolean

    Whether to include archived vaults in the results.

  • limit: optional number

    Maximum number of vaults to return per page. Defaults to 20, maximum 100.

  • page: optional string

    Opaque pagination token from a previous list_vaults response.

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Returns

  • data: optional array of BetaManagedAgentsVault

    List of vaults.

    • id: string

      Unique identifier for the vault.

    • archived_at: string

      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: map[string]

      Arbitrary key-value metadata attached to the vault.

    • type: "vault"

      • "vault"

    • updated_at: string

      A timestamp in RFC 3339 format

  • next_page: optional string

    Pagination token for the next page, or null if no more results.

Example

curl https://api.anthropic.com/v1/vaults \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: managed-agents-2026-04-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

Response

{
  "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

get /v1/vaults/{vault_id}

Get Vault

Path Parameters

  • vault_id: string

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Returns

  • BetaManagedAgentsVault object { id, archived_at, created_at, 4 more }

    A vault that stores credentials for use by agents during sessions.

    • id: string

      Unique identifier for the vault.

    • archived_at: string

      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: map[string]

      Arbitrary key-value metadata attached to the vault.

    • type: "vault"

      • "vault"

    • updated_at: string

      A timestamp in RFC 3339 format

Example

curl https://api.anthropic.com/v1/vaults/$VAULT_ID \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: managed-agents-2026-04-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

Response

{
  "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

post /v1/vaults/{vault_id}

Update Vault

Path Parameters

  • vault_id: string

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Body Parameters

  • display_name: optional string

    Updated human-readable name for the vault. 1-255 characters.

  • metadata: optional map[string]

    Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omitted keys are preserved.

Returns

  • BetaManagedAgentsVault object { id, archived_at, created_at, 4 more }

    A vault that stores credentials for use by agents during sessions.

    • id: string

      Unique identifier for the vault.

    • archived_at: string

      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: map[string]

      Arbitrary key-value metadata attached to the vault.

    • type: "vault"

      • "vault"

    • updated_at: string

      A timestamp in RFC 3339 format

Example

curl https://api.anthropic.com/v1/vaults/$VAULT_ID \
    -H 'Content-Type: application/json' \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: managed-agents-2026-04-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY" \
    -d '{
          "display_name": "Example vault",
          "metadata": {
            "environment": "production"
          }
        }'

Response

{
  "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

delete /v1/vaults/{vault_id}

Delete Vault

Path Parameters

  • vault_id: string

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Returns

  • BetaManagedAgentsDeletedVault object { id, type }

    Confirmation of a deleted vault.

    • id: string

      Unique identifier of the deleted vault.

    • type: "vault_deleted"

      • "vault_deleted"

Example

curl https://api.anthropic.com/v1/vaults/$VAULT_ID \
    -X DELETE \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: managed-agents-2026-04-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

Response

{
  "id": "vlt_011CZkZDLs7fYzm1hXNPeRjv",
  "type": "vault_deleted"
}

Archive Vault

post /v1/vaults/{vault_id}/archive

Archive Vault

Path Parameters

  • vault_id: string

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Returns

  • BetaManagedAgentsVault object { id, archived_at, created_at, 4 more }

    A vault that stores credentials for use by agents during sessions.

    • id: string

      Unique identifier for the vault.

    • archived_at: string

      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: map[string]

      Arbitrary key-value metadata attached to the vault.

    • type: "vault"

      • "vault"

    • updated_at: string

      A timestamp in RFC 3339 format

Example

curl https://api.anthropic.com/v1/vaults/$VAULT_ID/archive \
    -X POST \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: managed-agents-2026-04-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

Response

{
  "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 object { id, type }

    Confirmation of a deleted vault.

    • id: string

      Unique identifier of the deleted vault.

    • type: "vault_deleted"

      • "vault_deleted"

Beta Managed Agents Vault

  • BetaManagedAgentsVault object { id, archived_at, created_at, 4 more }

    A vault that stores credentials for use by agents during sessions.

    • id: string

      Unique identifier for the vault.

    • archived_at: string

      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: map[string]

      Arbitrary key-value metadata attached to the vault.

    • type: "vault"

      • "vault"

    • updated_at: string

      A timestamp in RFC 3339 format

Credentials

Create Credential

post /v1/vaults/{vault_id}/credentials

Create Credential

Path Parameters

  • vault_id: string

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Body Parameters

  • auth: BetaManagedAgentsMCPOAuthCreateParams or BetaManagedAgentsStaticBearerCreateParams

    Authentication details for creating a credential.

    • BetaManagedAgentsMCPOAuthCreateParams object { access_token, mcp_server_url, type, 2 more }

      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: optional string

        A timestamp in RFC 3339 format

      • refresh: optional 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 or BetaManagedAgentsTokenEndpointAuthBasicParam or BetaManagedAgentsTokenEndpointAuthPostParam

          Token endpoint requires no client authentication.

          • BetaManagedAgentsTokenEndpointAuthNoneParam object { type }

            Token endpoint requires no client authentication.

            • type: "none"

              • "none"

          • BetaManagedAgentsTokenEndpointAuthBasicParam object { client_secret, type }

            Token endpoint uses HTTP Basic authentication with client credentials.

            • client_secret: string

              OAuth client secret.

            • type: "client_secret_basic"

              • "client_secret_basic"

          • BetaManagedAgentsTokenEndpointAuthPostParam object { client_secret, type }

            Token endpoint uses POST body authentication with client credentials.

            • client_secret: string

              OAuth client secret.

            • type: "client_secret_post"

              • "client_secret_post"

        • resource: optional string

          OAuth resource indicator.

        • scope: optional string

          OAuth scope for the refresh request.

    • BetaManagedAgentsStaticBearerCreateParams object { token, mcp_server_url, type }

      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: optional string

    Human-readable name for the credential. Up to 255 characters.

  • metadata: optional map[string]

    Arbitrary key-value metadata to attach to the credential. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars.

Returns

  • BetaManagedAgentsCredential object { id, archived_at, auth, 6 more }

    A credential stored in a vault. Sensitive fields are never returned in responses.

    • id: string

      Unique identifier for the credential.

    • archived_at: string

      A timestamp in RFC 3339 format

    • auth: BetaManagedAgentsMCPOAuthAuthResponse or BetaManagedAgentsStaticBearerAuthResponse

      Authentication details for a credential.

      • BetaManagedAgentsMCPOAuthAuthResponse object { mcp_server_url, type, expires_at, refresh }

        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: optional string

          A timestamp in RFC 3339 format

        • refresh: optional 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 or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse

            Token endpoint requires no client authentication.

            • BetaManagedAgentsTokenEndpointAuthNoneResponse object { type }

              Token endpoint requires no client authentication.

              • type: "none"

                • "none"

            • BetaManagedAgentsTokenEndpointAuthBasicResponse object { type }

              Token endpoint uses HTTP Basic authentication with client credentials.

              • type: "client_secret_basic"

                • "client_secret_basic"

            • BetaManagedAgentsTokenEndpointAuthPostResponse object { type }

              Token endpoint uses POST body authentication with client credentials.

              • type: "client_secret_post"

                • "client_secret_post"

          • resource: optional string

            OAuth resource indicator.

          • scope: optional string

            OAuth scope for the refresh request.

      • BetaManagedAgentsStaticBearerAuthResponse object { mcp_server_url, type }

        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: map[string]

      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: optional string

      Human-readable name for the credential.

Example

curl https://api.anthropic.com/v1/vaults/$VAULT_ID/credentials \
    -H 'Content-Type: application/json' \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: managed-agents-2026-04-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY" \
    -d '{
          "auth": {
            "token": "bearer_exampletoken",
            "mcp_server_url": "https://example-server.modelcontextprotocol.io/sse",
            "type": "static_bearer"
          },
          "display_name": "Example credential",
          "metadata": {
            "environment": "production"
          }
        }'

Response

{
  "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

get /v1/vaults/{vault_id}/credentials

List Credentials

Path Parameters

  • vault_id: string

Query Parameters

  • include_archived: optional boolean

    Whether to include archived credentials in the results.

  • limit: optional number

    Maximum number of credentials to return per page. Defaults to 20, maximum 100.

  • page: optional string

    Opaque pagination token from a previous list_credentials response.

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Returns

  • data: optional array of BetaManagedAgentsCredential

    List of credentials.

    • id: string

      Unique identifier for the credential.

    • archived_at: string

      A timestamp in RFC 3339 format

    • auth: BetaManagedAgentsMCPOAuthAuthResponse or BetaManagedAgentsStaticBearerAuthResponse

      Authentication details for a credential.

      • BetaManagedAgentsMCPOAuthAuthResponse object { mcp_server_url, type, expires_at, refresh }

        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: optional string

          A timestamp in RFC 3339 format

        • refresh: optional 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 or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse

            Token endpoint requires no client authentication.

            • BetaManagedAgentsTokenEndpointAuthNoneResponse object { type }

              Token endpoint requires no client authentication.

              • type: "none"

                • "none"

            • BetaManagedAgentsTokenEndpointAuthBasicResponse object { type }

              Token endpoint uses HTTP Basic authentication with client credentials.

              • type: "client_secret_basic"

                • "client_secret_basic"

            • BetaManagedAgentsTokenEndpointAuthPostResponse object { type }

              Token endpoint uses POST body authentication with client credentials.

              • type: "client_secret_post"

                • "client_secret_post"

          • resource: optional string

            OAuth resource indicator.

          • scope: optional string

            OAuth scope for the refresh request.

      • BetaManagedAgentsStaticBearerAuthResponse object { mcp_server_url, type }

        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: map[string]

      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: optional string

      Human-readable name for the credential.

  • next_page: optional string

    Pagination token for the next page, or null if no more results.

Example

curl https://api.anthropic.com/v1/vaults/$VAULT_ID/credentials \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: managed-agents-2026-04-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

Response

{
  "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

get /v1/vaults/{vault_id}/credentials/{credential_id}

Get Credential

Path Parameters

  • vault_id: string

  • credential_id: string

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Returns

  • BetaManagedAgentsCredential object { id, archived_at, auth, 6 more }

    A credential stored in a vault. Sensitive fields are never returned in responses.

    • id: string

      Unique identifier for the credential.

    • archived_at: string

      A timestamp in RFC 3339 format

    • auth: BetaManagedAgentsMCPOAuthAuthResponse or BetaManagedAgentsStaticBearerAuthResponse

      Authentication details for a credential.

      • BetaManagedAgentsMCPOAuthAuthResponse object { mcp_server_url, type, expires_at, refresh }

        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: optional string

          A timestamp in RFC 3339 format

        • refresh: optional 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 or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse

            Token endpoint requires no client authentication.

            • BetaManagedAgentsTokenEndpointAuthNoneResponse object { type }

              Token endpoint requires no client authentication.

              • type: "none"

                • "none"

            • BetaManagedAgentsTokenEndpointAuthBasicResponse object { type }

              Token endpoint uses HTTP Basic authentication with client credentials.

              • type: "client_secret_basic"

                • "client_secret_basic"

            • BetaManagedAgentsTokenEndpointAuthPostResponse object { type }

              Token endpoint uses POST body authentication with client credentials.

              • type: "client_secret_post"

                • "client_secret_post"

          • resource: optional string

            OAuth resource indicator.

          • scope: optional string

            OAuth scope for the refresh request.

      • BetaManagedAgentsStaticBearerAuthResponse object { mcp_server_url, type }

        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: map[string]

      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: optional string

      Human-readable name for the credential.

Example

curl https://api.anthropic.com/v1/vaults/$VAULT_ID/credentials/$CREDENTIAL_ID \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: managed-agents-2026-04-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

Response

{
  "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

post /v1/vaults/{vault_id}/credentials/{credential_id}

Update Credential

Path Parameters

  • vault_id: string

  • credential_id: string

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Body Parameters

  • auth: optional BetaManagedAgentsMCPOAuthUpdateParams or BetaManagedAgentsStaticBearerUpdateParams

    Updated authentication details for a credential.

    • BetaManagedAgentsMCPOAuthUpdateParams object { type, access_token, expires_at, refresh }

      Parameters for updating an MCP OAuth credential. The mcp_server_url is immutable.

      • type: "mcp_oauth"

        • "mcp_oauth"

      • access_token: optional string

        Updated OAuth access token.

      • expires_at: optional string

        A timestamp in RFC 3339 format

      • refresh: optional BetaManagedAgentsMCPOAuthRefreshUpdateParams

        Parameters for updating OAuth refresh token configuration.

        • refresh_token: optional string

          Updated OAuth refresh token.

        • scope: optional string

          Updated OAuth scope for the refresh request.

        • token_endpoint_auth: optional BetaManagedAgentsTokenEndpointAuthBasicUpdateParam or BetaManagedAgentsTokenEndpointAuthPostUpdateParam

          Updated HTTP Basic authentication parameters for the token endpoint.

          • BetaManagedAgentsTokenEndpointAuthBasicUpdateParam object { type, client_secret }

            Updated HTTP Basic authentication parameters for the token endpoint.

            • type: "client_secret_basic"

              • "client_secret_basic"

            • client_secret: optional string

              Updated OAuth client secret.

          • BetaManagedAgentsTokenEndpointAuthPostUpdateParam object { type, client_secret }

            Updated POST body authentication parameters for the token endpoint.

            • type: "client_secret_post"

              • "client_secret_post"

            • client_secret: optional string

              Updated OAuth client secret.

    • BetaManagedAgentsStaticBearerUpdateParams object { type, token }

      Parameters for updating a static bearer token credential. The mcp_server_url is immutable.

      • type: "static_bearer"

        • "static_bearer"

      • token: optional string

        Updated static bearer token value.

  • display_name: optional string

    Updated human-readable name for the credential. 1-255 characters.

  • metadata: optional map[string]

    Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omitted keys are preserved.

Returns

  • BetaManagedAgentsCredential object { id, archived_at, auth, 6 more }

    A credential stored in a vault. Sensitive fields are never returned in responses.

    • id: string

      Unique identifier for the credential.

    • archived_at: string

      A timestamp in RFC 3339 format

    • auth: BetaManagedAgentsMCPOAuthAuthResponse or BetaManagedAgentsStaticBearerAuthResponse

      Authentication details for a credential.

      • BetaManagedAgentsMCPOAuthAuthResponse object { mcp_server_url, type, expires_at, refresh }

        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: optional string

          A timestamp in RFC 3339 format

        • refresh: optional 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 or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse

            Token endpoint requires no client authentication.

            • BetaManagedAgentsTokenEndpointAuthNoneResponse object { type }

              Token endpoint requires no client authentication.

              • type: "none"

                • "none"

            • BetaManagedAgentsTokenEndpointAuthBasicResponse object { type }

              Token endpoint uses HTTP Basic authentication with client credentials.

              • type: "client_secret_basic"

                • "client_secret_basic"

            • BetaManagedAgentsTokenEndpointAuthPostResponse object { type }

              Token endpoint uses POST body authentication with client credentials.

              • type: "client_secret_post"

                • "client_secret_post"

          • resource: optional string

            OAuth resource indicator.

          • scope: optional string

            OAuth scope for the refresh request.

      • BetaManagedAgentsStaticBearerAuthResponse object { mcp_server_url, type }

        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: map[string]

      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: optional string

      Human-readable name for the credential.

Example

curl https://api.anthropic.com/v1/vaults/$VAULT_ID/credentials/$CREDENTIAL_ID \
    -H 'Content-Type: application/json' \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: managed-agents-2026-04-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY" \
    -d '{
          "display_name": "Example credential",
          "metadata": {
            "environment": "production"
          }
        }'

Response

{
  "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

delete /v1/vaults/{vault_id}/credentials/{credential_id}

Delete Credential

Path Parameters

  • vault_id: string

  • credential_id: string

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Returns

  • BetaManagedAgentsDeletedCredential object { id, type }

    Confirmation of a deleted credential.

    • id: string

      Unique identifier of the deleted credential.

    • type: "vault_credential_deleted"

      • "vault_credential_deleted"

Example

curl https://api.anthropic.com/v1/vaults/$VAULT_ID/credentials/$CREDENTIAL_ID \
    -X DELETE \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: managed-agents-2026-04-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

Response

{
  "id": "vcrd_011CZkZEMt8gZan2iYOQfSkw",
  "type": "vault_credential_deleted"
}

Archive Credential

post /v1/vaults/{vault_id}/credentials/{credential_id}/archive

Archive Credential

Path Parameters

  • vault_id: string

  • credential_id: string

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Returns

  • BetaManagedAgentsCredential object { id, archived_at, auth, 6 more }

    A credential stored in a vault. Sensitive fields are never returned in responses.

    • id: string

      Unique identifier for the credential.

    • archived_at: string

      A timestamp in RFC 3339 format

    • auth: BetaManagedAgentsMCPOAuthAuthResponse or BetaManagedAgentsStaticBearerAuthResponse

      Authentication details for a credential.

      • BetaManagedAgentsMCPOAuthAuthResponse object { mcp_server_url, type, expires_at, refresh }

        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: optional string

          A timestamp in RFC 3339 format

        • refresh: optional 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 or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse

            Token endpoint requires no client authentication.

            • BetaManagedAgentsTokenEndpointAuthNoneResponse object { type }

              Token endpoint requires no client authentication.

              • type: "none"

                • "none"

            • BetaManagedAgentsTokenEndpointAuthBasicResponse object { type }

              Token endpoint uses HTTP Basic authentication with client credentials.

              • type: "client_secret_basic"

                • "client_secret_basic"

            • BetaManagedAgentsTokenEndpointAuthPostResponse object { type }

              Token endpoint uses POST body authentication with client credentials.

              • type: "client_secret_post"

                • "client_secret_post"

          • resource: optional string

            OAuth resource indicator.

          • scope: optional string

            OAuth scope for the refresh request.

      • BetaManagedAgentsStaticBearerAuthResponse object { mcp_server_url, type }

        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: map[string]

      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: optional string

      Human-readable name for the credential.

Example

curl https://api.anthropic.com/v1/vaults/$VAULT_ID/credentials/$CREDENTIAL_ID/archive \
    -X POST \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: managed-agents-2026-04-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

Response

{
  "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

post /v1/vaults/{vault_id}/credentials/{credential_id}/mcp_oauth_validate

Validate Credential

Path Parameters

  • vault_id: string

  • credential_id: string

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Returns

  • BetaManagedAgentsCredentialValidation object { credential_id, has_refresh_token, mcp_probe, 5 more }

    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

      The failing step of an MCP validation probe.

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

      • method: string

        The MCP method that failed (for example initialize or tools/list).

    • refresh: BetaManagedAgentsRefreshObject

      Outcome of a refresh-token exchange attempted during credential validation.

      • http_response: BetaManagedAgentsRefreshHTTPResponse

        An HTTP response captured during a credential validation probe.

      • status: "succeeded" or "failed" or "connect_error" or "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

curl https://api.anthropic.com/v1/vaults/$VAULT_ID/credentials/$CREDENTIAL_ID/mcp_oauth_validate \
    -X POST \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: managed-agents-2026-04-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

Response

{
  "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 object { id, archived_at, auth, 6 more }

    A credential stored in a vault. Sensitive fields are never returned in responses.

    • id: string

      Unique identifier for the credential.

    • archived_at: string

      A timestamp in RFC 3339 format

    • auth: BetaManagedAgentsMCPOAuthAuthResponse or BetaManagedAgentsStaticBearerAuthResponse

      Authentication details for a credential.

      • BetaManagedAgentsMCPOAuthAuthResponse object { mcp_server_url, type, expires_at, refresh }

        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: optional string

          A timestamp in RFC 3339 format

        • refresh: optional 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 or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse

            Token endpoint requires no client authentication.

            • BetaManagedAgentsTokenEndpointAuthNoneResponse object { type }

              Token endpoint requires no client authentication.

              • type: "none"

                • "none"

            • BetaManagedAgentsTokenEndpointAuthBasicResponse object { type }

              Token endpoint uses HTTP Basic authentication with client credentials.

              • type: "client_secret_basic"

                • "client_secret_basic"

            • BetaManagedAgentsTokenEndpointAuthPostResponse object { type }

              Token endpoint uses POST body authentication with client credentials.

              • type: "client_secret_post"

                • "client_secret_post"

          • resource: optional string

            OAuth resource indicator.

          • scope: optional string

            OAuth scope for the refresh request.

      • BetaManagedAgentsStaticBearerAuthResponse object { mcp_server_url, type }

        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: map[string]

      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: optional string

      Human-readable name for the credential.

Beta Managed Agents Credential Validation

  • BetaManagedAgentsCredentialValidation object { credential_id, has_refresh_token, mcp_probe, 5 more }

    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

      The failing step of an MCP validation probe.

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

      • method: string

        The MCP method that failed (for example initialize or tools/list).

    • refresh: BetaManagedAgentsRefreshObject

      Outcome of a refresh-token exchange attempted during credential validation.

      • http_response: BetaManagedAgentsRefreshHTTPResponse

        An HTTP response captured during a credential validation probe.

      • status: "succeeded" or "failed" or "connect_error" or "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" or "invalid" or "unknown"

    Overall verdict of a credential validation probe.

    • "valid"

    • "invalid"

    • "unknown"

Beta Managed Agents Deleted Credential

  • BetaManagedAgentsDeletedCredential object { id, type }

    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 object { mcp_server_url, type, expires_at, refresh }

    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: optional string

      A timestamp in RFC 3339 format

    • refresh: optional 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 or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse

        Token endpoint requires no client authentication.

        • BetaManagedAgentsTokenEndpointAuthNoneResponse object { type }

          Token endpoint requires no client authentication.

          • type: "none"

            • "none"

        • BetaManagedAgentsTokenEndpointAuthBasicResponse object { type }

          Token endpoint uses HTTP Basic authentication with client credentials.

          • type: "client_secret_basic"

            • "client_secret_basic"

        • BetaManagedAgentsTokenEndpointAuthPostResponse object { type }

          Token endpoint uses POST body authentication with client credentials.

          • type: "client_secret_post"

            • "client_secret_post"

      • resource: optional string

        OAuth resource indicator.

      • scope: optional string

        OAuth scope for the refresh request.

Beta Managed Agents MCP OAuth Create Params

  • BetaManagedAgentsMCPOAuthCreateParams object { access_token, mcp_server_url, type, 2 more }

    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: optional string

      A timestamp in RFC 3339 format

    • refresh: optional 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 or BetaManagedAgentsTokenEndpointAuthBasicParam or BetaManagedAgentsTokenEndpointAuthPostParam

        Token endpoint requires no client authentication.

        • BetaManagedAgentsTokenEndpointAuthNoneParam object { type }

          Token endpoint requires no client authentication.

          • type: "none"

            • "none"

        • BetaManagedAgentsTokenEndpointAuthBasicParam object { client_secret, type }

          Token endpoint uses HTTP Basic authentication with client credentials.

          • client_secret: string

            OAuth client secret.

          • type: "client_secret_basic"

            • "client_secret_basic"

        • BetaManagedAgentsTokenEndpointAuthPostParam object { client_secret, type }

          Token endpoint uses POST body authentication with client credentials.

          • client_secret: string

            OAuth client secret.

          • type: "client_secret_post"

            • "client_secret_post"

      • resource: optional string

        OAuth resource indicator.

      • scope: optional string

        OAuth scope for the refresh request.

Beta Managed Agents MCP OAuth Refresh Params

  • BetaManagedAgentsMCPOAuthRefreshParams object { client_id, refresh_token, token_endpoint, 3 more }

    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 or BetaManagedAgentsTokenEndpointAuthBasicParam or BetaManagedAgentsTokenEndpointAuthPostParam

      Token endpoint requires no client authentication.

      • BetaManagedAgentsTokenEndpointAuthNoneParam object { type }

        Token endpoint requires no client authentication.

        • type: "none"

          • "none"

      • BetaManagedAgentsTokenEndpointAuthBasicParam object { client_secret, type }

        Token endpoint uses HTTP Basic authentication with client credentials.

        • client_secret: string

          OAuth client secret.

        • type: "client_secret_basic"

          • "client_secret_basic"

      • BetaManagedAgentsTokenEndpointAuthPostParam object { client_secret, type }

        Token endpoint uses POST body authentication with client credentials.

        • client_secret: string

          OAuth client secret.

        • type: "client_secret_post"

          • "client_secret_post"

    • resource: optional string

      OAuth resource indicator.

    • scope: optional string

      OAuth scope for the refresh request.

Beta Managed Agents MCP OAuth Refresh Response

  • BetaManagedAgentsMCPOAuthRefreshResponse object { client_id, token_endpoint, token_endpoint_auth, 2 more }

    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 or BetaManagedAgentsTokenEndpointAuthBasicResponse or BetaManagedAgentsTokenEndpointAuthPostResponse

      Token endpoint requires no client authentication.

      • BetaManagedAgentsTokenEndpointAuthNoneResponse object { type }

        Token endpoint requires no client authentication.

        • type: "none"

          • "none"

      • BetaManagedAgentsTokenEndpointAuthBasicResponse object { type }

        Token endpoint uses HTTP Basic authentication with client credentials.

        • type: "client_secret_basic"

          • "client_secret_basic"

      • BetaManagedAgentsTokenEndpointAuthPostResponse object { type }

        Token endpoint uses POST body authentication with client credentials.

        • type: "client_secret_post"

          • "client_secret_post"

    • resource: optional string

      OAuth resource indicator.

    • scope: optional string

      OAuth scope for the refresh request.

Beta Managed Agents MCP OAuth Refresh Update Params

  • BetaManagedAgentsMCPOAuthRefreshUpdateParams object { refresh_token, scope, token_endpoint_auth }

    Parameters for updating OAuth refresh token configuration.

    • refresh_token: optional string

      Updated OAuth refresh token.

    • scope: optional string

      Updated OAuth scope for the refresh request.

    • token_endpoint_auth: optional BetaManagedAgentsTokenEndpointAuthBasicUpdateParam or BetaManagedAgentsTokenEndpointAuthPostUpdateParam

      Updated HTTP Basic authentication parameters for the token endpoint.

      • BetaManagedAgentsTokenEndpointAuthBasicUpdateParam object { type, client_secret }

        Updated HTTP Basic authentication parameters for the token endpoint.

        • type: "client_secret_basic"

          • "client_secret_basic"

        • client_secret: optional string

          Updated OAuth client secret.

      • BetaManagedAgentsTokenEndpointAuthPostUpdateParam object { type, client_secret }

        Updated POST body authentication parameters for the token endpoint.

        • type: "client_secret_post"

          • "client_secret_post"

        • client_secret: optional string

          Updated OAuth client secret.

Beta Managed Agents MCP OAuth Update Params

  • BetaManagedAgentsMCPOAuthUpdateParams object { type, access_token, expires_at, refresh }

    Parameters for updating an MCP OAuth credential. The mcp_server_url is immutable.

    • type: "mcp_oauth"

      • "mcp_oauth"

    • access_token: optional string

      Updated OAuth access token.

    • expires_at: optional string

      A timestamp in RFC 3339 format

    • refresh: optional BetaManagedAgentsMCPOAuthRefreshUpdateParams

      Parameters for updating OAuth refresh token configuration.

      • refresh_token: optional string

        Updated OAuth refresh token.

      • scope: optional string

        Updated OAuth scope for the refresh request.

      • token_endpoint_auth: optional BetaManagedAgentsTokenEndpointAuthBasicUpdateParam or BetaManagedAgentsTokenEndpointAuthPostUpdateParam

        Updated HTTP Basic authentication parameters for the token endpoint.

        • BetaManagedAgentsTokenEndpointAuthBasicUpdateParam object { type, client_secret }

          Updated HTTP Basic authentication parameters for the token endpoint.

          • type: "client_secret_basic"

            • "client_secret_basic"

          • client_secret: optional string

            Updated OAuth client secret.

        • BetaManagedAgentsTokenEndpointAuthPostUpdateParam object { type, client_secret }

          Updated POST body authentication parameters for the token endpoint.

          • type: "client_secret_post"

            • "client_secret_post"

          • client_secret: optional string

            Updated OAuth client secret.

Beta Managed Agents MCP Probe

  • BetaManagedAgentsMCPProbe object { http_response, method }

    The failing step of an MCP validation probe.

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

    • method: string

      The MCP method that failed (for example initialize or tools/list).

Beta Managed Agents Refresh HTTP Response

  • BetaManagedAgentsRefreshHTTPResponse object { body, body_truncated, content_type, status_code }

    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 object { http_response, status }

    Outcome of a refresh-token exchange attempted during credential validation.

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

    • status: "succeeded" or "failed" or "connect_error" or "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 object { mcp_server_url, type }

    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 object { token, mcp_server_url, type }

    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 object { type, token }

    Parameters for updating a static bearer token credential. The mcp_server_url is immutable.

    • type: "static_bearer"

      • "static_bearer"

    • token: optional string

      Updated static bearer token value.

Beta Managed Agents Token Endpoint Auth Basic Param

  • BetaManagedAgentsTokenEndpointAuthBasicParam object { client_secret, type }

    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 object { type }

    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 object { type, client_secret }

    Updated HTTP Basic authentication parameters for the token endpoint.

    • type: "client_secret_basic"

      • "client_secret_basic"

    • client_secret: optional string

      Updated OAuth client secret.

Beta Managed Agents Token Endpoint Auth None Param

  • BetaManagedAgentsTokenEndpointAuthNoneParam object { type }

    Token endpoint requires no client authentication.

    • type: "none"

      • "none"

Beta Managed Agents Token Endpoint Auth None Response

  • BetaManagedAgentsTokenEndpointAuthNoneResponse object { type }

    Token endpoint requires no client authentication.

    • type: "none"

      • "none"

Beta Managed Agents Token Endpoint Auth Post Param

  • BetaManagedAgentsTokenEndpointAuthPostParam object { client_secret, type }

    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 object { type }

    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 object { type, client_secret }

    Updated POST body authentication parameters for the token endpoint.

    • type: "client_secret_post"

      • "client_secret_post"

    • client_secret: optional string

      Updated OAuth client secret.

Memory Stores

Create a memory store

post /v1/memory_stores

Create a memory store

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Body Parameters

  • name: string

    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: optional 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.

  • metadata: optional map[string]

    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.

Returns

  • BetaManagedAgentsMemoryStore object { id, created_at, name, 5 more }

    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: optional string

      A timestamp in RFC 3339 format

    • description: optional 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: optional map[string]

      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

curl https://api.anthropic.com/v1/memory_stores \
    -H 'Content-Type: application/json' \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: managed-agents-2026-04-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY" \
    -d '{
          "name": "x"
        }'

Response

{
  "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

get /v1/memory_stores

List memory stores

Query Parameters

  • "created_at[gte]": optional string

    Return only stores whose created_at is at or after this time (inclusive). Sent on the wire as created_at[gte].

  • "created_at[lte]": optional string

    Return only stores whose created_at is at or before this time (inclusive). Sent on the wire as created_at[lte].

  • include_archived: optional boolean

    When true, archived stores are included in the results. Defaults to false (archived stores are excluded).

  • limit: optional number

    Maximum number of stores to return per page. Must be between 1 and 100. Defaults to 20 when omitted.

  • page: optional string

    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.

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Returns

  • data: optional array of BetaManagedAgentsMemoryStore

    Memory stores on this page, newest first. Empty when there are no stores matching the filters.

    • 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: optional string

      A timestamp in RFC 3339 format

    • description: optional 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: optional map[string]

      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.

  • next_page: optional string

    Opaque cursor for the next page (a page_... value). Pass as page on the next request. null when there are no more results.

Example

curl https://api.anthropic.com/v1/memory_stores \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: managed-agents-2026-04-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

Response

{
  "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

get /v1/memory_stores/{memory_store_id}

Retrieve a memory store

Path Parameters

  • memory_store_id: string

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Returns

  • BetaManagedAgentsMemoryStore object { id, created_at, name, 5 more }

    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: optional string

      A timestamp in RFC 3339 format

    • description: optional 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: optional map[string]

      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

curl https://api.anthropic.com/v1/memory_stores/$MEMORY_STORE_ID \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: managed-agents-2026-04-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

Response

{
  "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

post /v1/memory_stores/{memory_store_id}

Update a memory store

Path Parameters

  • memory_store_id: string

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Body Parameters

  • description: optional string

    New description for the store, up to 1024 characters. Pass an empty string to clear it.

  • metadata: optional map[string]

    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: optional string

    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.

Returns

  • BetaManagedAgentsMemoryStore object { id, created_at, name, 5 more }

    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: optional string

      A timestamp in RFC 3339 format

    • description: optional 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: optional map[string]

      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

curl https://api.anthropic.com/v1/memory_stores/$MEMORY_STORE_ID \
    -H 'Content-Type: application/json' \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: managed-agents-2026-04-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY" \
    -d '{}'

Response

{
  "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

delete /v1/memory_stores/{memory_store_id}

Delete a memory store

Path Parameters

  • memory_store_id: string

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Returns

  • BetaManagedAgentsDeletedMemoryStore object { id, type }

    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

curl https://api.anthropic.com/v1/memory_stores/$MEMORY_STORE_ID \
    -X DELETE \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: managed-agents-2026-04-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

Response

{
  "id": "id",
  "type": "memory_store_deleted"
}

Archive a memory store

post /v1/memory_stores/{memory_store_id}/archive

Archive a memory store

Path Parameters

  • memory_store_id: string

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Returns

  • BetaManagedAgentsMemoryStore object { id, created_at, name, 5 more }

    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: optional string

      A timestamp in RFC 3339 format

    • description: optional 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: optional map[string]

      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

curl https://api.anthropic.com/v1/memory_stores/$MEMORY_STORE_ID/archive \
    -X POST \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: managed-agents-2026-04-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

Response

{
  "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 object { id, type }

    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 object { id, created_at, name, 5 more }

    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: optional string

      A timestamp in RFC 3339 format

    • description: optional 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: optional map[string]

      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

post /v1/memory_stores/{memory_store_id}/memories

Create a memory

Path Parameters

  • memory_store_id: string

Query Parameters

  • view: optional BetaManagedAgentsMemoryView

    Query parameter for view

    • "basic"

    • "full"

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Body Parameters

  • content: string

    UTF-8 text content for the new memory. Maximum 100 kB (102,400 bytes). Required; pass "" explicitly to create an empty memory.

  • path: string

    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.

Returns

  • BetaManagedAgentsMemory object { id, content_sha256, content_size_bytes, 7 more }

    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.

    • 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: optional string

      The memory's UTF-8 text content. Populated when view=full; null when view=basic. Maximum 100 kB (102,400 bytes).

Example

curl https://api.anthropic.com/v1/memory_stores/$MEMORY_STORE_ID/memories \
    -H 'Content-Type: application/json' \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: managed-agents-2026-04-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY" \
    -d '{
          "content": "content",
          "path": "xx"
        }'

Response

{
  "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

get /v1/memory_stores/{memory_store_id}/memories

List memories

Path Parameters

  • memory_store_id: string

Query Parameters

  • depth: optional number

    Query parameter for depth

  • limit: optional number

    Query parameter for limit

  • order: optional "asc" or "desc"

    Query parameter for order

    • "asc"

    • "desc"

  • order_by: optional string

    Query parameter for order_by

  • page: optional string

    Query parameter for page

  • path_prefix: optional string

    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: optional BetaManagedAgentsMemoryView

    Query parameter for view

    • "basic"

    • "full"

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Returns

  • data: optional array of BetaManagedAgentsMemoryListItem

    One page of results. Each item is either a memory object or, when depth was set, a memory_prefix rollup marker. Items appear in the requested order_by/order.

    • BetaManagedAgentsMemory object { id, content_sha256, content_size_bytes, 7 more }

      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.

      • 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: optional string

        The memory's UTF-8 text content. Populated when view=full; null when view=basic. Maximum 100 kB (102,400 bytes).

    • BetaManagedAgentsMemoryPrefix object { path, type }

      A rolled-up directory marker returned by List memories 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"

  • next_page: optional string

    Opaque cursor for the next page (a page_... value), or null if there are no more results. Pass as page on the next request.

Example

curl https://api.anthropic.com/v1/memory_stores/$MEMORY_STORE_ID/memories \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: managed-agents-2026-04-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

Response

{
  "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

get /v1/memory_stores/{memory_store_id}/memories/{memory_id}

Retrieve a memory

Path Parameters

  • memory_store_id: string

  • memory_id: string

Query Parameters

  • view: optional BetaManagedAgentsMemoryView

    Query parameter for view

    • "basic"

    • "full"

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Returns

  • BetaManagedAgentsMemory object { id, content_sha256, content_size_bytes, 7 more }

    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.

    • 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: optional string

      The memory's UTF-8 text content. Populated when view=full; null when view=basic. Maximum 100 kB (102,400 bytes).

Example

curl https://api.anthropic.com/v1/memory_stores/$MEMORY_STORE_ID/memories/$MEMORY_ID \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: managed-agents-2026-04-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

Response

{
  "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

post /v1/memory_stores/{memory_store_id}/memories/{memory_id}

Update a memory

Path Parameters

  • memory_store_id: string

  • memory_id: string

Query Parameters

  • view: optional BetaManagedAgentsMemoryView

    Query parameter for view

    • "basic"

    • "full"

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Body Parameters

  • content: optional string

    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: optional string

    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: optional 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: optional 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.

Returns

  • BetaManagedAgentsMemory object { id, content_sha256, content_size_bytes, 7 more }

    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.

    • 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: optional string

      The memory's UTF-8 text content. Populated when view=full; null when view=basic. Maximum 100 kB (102,400 bytes).

Example

curl https://api.anthropic.com/v1/memory_stores/$MEMORY_STORE_ID/memories/$MEMORY_ID \
    -H 'Content-Type: application/json' \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: managed-agents-2026-04-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY" \
    -d '{}'

Response

{
  "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

delete /v1/memory_stores/{memory_store_id}/memories/{memory_id}

Delete a memory

Path Parameters

  • memory_store_id: string

  • memory_id: string

Query Parameters

  • expected_content_sha256: optional string

    Query parameter for expected_content_sha256

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Returns

  • BetaManagedAgentsDeletedMemory object { id, type }

    Tombstone returned by Delete a memory. The memory's version history persists and remains listable via List memory versions until the store itself is deleted.

    • id: string

      ID of the deleted memory (a mem_... value).

    • type: "memory_deleted"

      • "memory_deleted"

Example

curl https://api.anthropic.com/v1/memory_stores/$MEMORY_STORE_ID/memories/$MEMORY_ID \
    -X DELETE \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: managed-agents-2026-04-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

Response

{
  "id": "id",
  "type": "memory_deleted"
}

Domain Types

Beta Managed Agents Conflict Error

  • BetaManagedAgentsConflictError object { type, message }

    • type: "conflict_error"

      • "conflict_error"

    • message: optional string

Beta Managed Agents Content Sha256 Precondition

  • BetaManagedAgentsContentSha256Precondition object { type, content_sha256 }

    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: optional 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 object { id, type }

    Tombstone returned by Delete a memory. The memory's version history persists and remains listable via List memory versions 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 or BetaAuthenticationError or BetaBillingError or 9 more

    • BetaInvalidRequestError object { message, type }

      • message: string

      • type: "invalid_request_error"

        • "invalid_request_error"

    • BetaAuthenticationError object { message, type }

      • message: string

      • type: "authentication_error"

        • "authentication_error"

    • BetaBillingError object { message, type }

      • message: string

      • type: "billing_error"

        • "billing_error"

    • BetaPermissionError object { message, type }

      • message: string

      • type: "permission_error"

        • "permission_error"

    • BetaNotFoundError object { message, type }

      • message: string

      • type: "not_found_error"

        • "not_found_error"

    • BetaRateLimitError object { message, type }

      • message: string

      • type: "rate_limit_error"

        • "rate_limit_error"

    • BetaGatewayTimeoutError object { message, type }

      • message: string

      • type: "timeout_error"

        • "timeout_error"

    • BetaAPIError object { message, type }

      • message: string

      • type: "api_error"

        • "api_error"

    • BetaOverloadedError object { message, type }

      • message: string

      • type: "overloaded_error"

        • "overloaded_error"

    • BetaManagedAgentsMemoryPreconditionFailedError object { type, message }

      • type: "memory_precondition_failed_error"

        • "memory_precondition_failed_error"

      • message: optional string

    • BetaManagedAgentsMemoryPathConflictError object { type, conflicting_memory_id, conflicting_path, message }

      • type: "memory_path_conflict_error"

        • "memory_path_conflict_error"

      • conflicting_memory_id: optional string

      • conflicting_path: optional string

      • message: optional string

    • BetaManagedAgentsConflictError object { type, message }

      • type: "conflict_error"

        • "conflict_error"

      • message: optional string

Beta Managed Agents Memory

  • BetaManagedAgentsMemory object { id, content_sha256, content_size_bytes, 7 more }

    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.

    • 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: optional string

      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 or BetaManagedAgentsMemoryPrefix

    One item in a List memories response: either a memory object or, when depth is set, a memory_prefix rollup marker.

    • BetaManagedAgentsMemory object { id, content_sha256, content_size_bytes, 7 more }

      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.

      • 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: optional string

        The memory's UTF-8 text content. Populated when view=full; null when view=basic. Maximum 100 kB (102,400 bytes).

    • BetaManagedAgentsMemoryPrefix object { path, type }

      A rolled-up directory marker returned by List memories 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 object { type, conflicting_memory_id, conflicting_path, message }

    • type: "memory_path_conflict_error"

      • "memory_path_conflict_error"

    • conflicting_memory_id: optional string

    • conflicting_path: optional string

    • message: optional string

Beta Managed Agents Memory Precondition Failed Error

  • BetaManagedAgentsMemoryPreconditionFailedError object { type, message }

    • type: "memory_precondition_failed_error"

      • "memory_precondition_failed_error"

    • message: optional string

Beta Managed Agents Memory Prefix

  • BetaManagedAgentsMemoryPrefix object { path, type }

    A rolled-up directory marker returned by List memories 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" or "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 object { type, content_sha256 }

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

get /v1/memory_stores/{memory_store_id}/memory_versions

List memory versions

Path Parameters

  • memory_store_id: string

Query Parameters

  • api_key_id: optional string

    Query parameter for api_key_id

  • "created_at[gte]": optional string

    Return versions created at or after this time (inclusive).

  • "created_at[lte]": optional string

    Return versions created at or before this time (inclusive).

  • limit: optional number

    Query parameter for limit

  • memory_id: optional string

    Query parameter for memory_id

  • operation: optional BetaManagedAgentsMemoryVersionOperation

    Query parameter for operation

    • "created"

    • "modified"

    • "deleted"

  • page: optional string

    Query parameter for page

  • session_id: optional string

    Query parameter for session_id

  • view: optional BetaManagedAgentsMemoryView

    Query parameter for view

    • "basic"

    • "full"

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Returns

  • data: optional array of BetaManagedAgentsMemoryVersion

    One page of memory_version objects, ordered by created_at descending (newest first), with id as tiebreak.

    • 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 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: optional string

      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: optional string

      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: optional number

      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: optional 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.

      • BetaManagedAgentsSessionActor object { session_id, type }

        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 for further provenance.

        • type: "session_actor"

          • "session_actor"

      • BetaManagedAgentsAPIActor object { api_key_id, type }

        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 object { type, user_id }

        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: optional string

      The memory's path at the time of this write. null if and only if redacted_at is set.

    • redacted_at: optional string

      A timestamp in RFC 3339 format

    • redacted_by: optional 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.

  • next_page: optional string

    Opaque cursor for the next page (a page_... value), or null if there are no more results. Pass as page on the next request.

Example

curl https://api.anthropic.com/v1/memory_stores/$MEMORY_STORE_ID/memory_versions \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: managed-agents-2026-04-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

Response

{
  "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

get /v1/memory_stores/{memory_store_id}/memory_versions/{memory_version_id}

Retrieve a memory version

Path Parameters

  • memory_store_id: string

  • memory_version_id: string

Query Parameters

  • view: optional BetaManagedAgentsMemoryView

    Query parameter for view

    • "basic"

    • "full"

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Returns

  • BetaManagedAgentsMemoryVersion object { id, created_at, memory_id, 10 more }

    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 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: optional string

      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: optional string

      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: optional number

      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: optional 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.

      • BetaManagedAgentsSessionActor object { session_id, type }

        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 for further provenance.

        • type: "session_actor"

          • "session_actor"

      • BetaManagedAgentsAPIActor object { api_key_id, type }

        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 object { type, user_id }

        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: optional string

      The memory's path at the time of this write. null if and only if redacted_at is set.

    • redacted_at: optional string

      A timestamp in RFC 3339 format

    • redacted_by: optional 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.

Example

curl https://api.anthropic.com/v1/memory_stores/$MEMORY_STORE_ID/memory_versions/$MEMORY_VERSION_ID \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: managed-agents-2026-04-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

Response

{
  "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

post /v1/memory_stores/{memory_store_id}/memory_versions/{memory_version_id}/redact

Redact a memory version

Path Parameters

  • memory_store_id: string

  • memory_version_id: string

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Returns

  • BetaManagedAgentsMemoryVersion object { id, created_at, memory_id, 10 more }

    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 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: optional string

      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: optional string

      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: optional number

      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: optional 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.

      • BetaManagedAgentsSessionActor object { session_id, type }

        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 for further provenance.

        • type: "session_actor"

          • "session_actor"

      • BetaManagedAgentsAPIActor object { api_key_id, type }

        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 object { type, user_id }

        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: optional string

      The memory's path at the time of this write. null if and only if redacted_at is set.

    • redacted_at: optional string

      A timestamp in RFC 3339 format

    • redacted_by: optional 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.

Example

curl https://api.anthropic.com/v1/memory_stores/$MEMORY_STORE_ID/memory_versions/$MEMORY_VERSION_ID/redact \
    -X POST \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: managed-agents-2026-04-01' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

Response

{
  "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 or BetaManagedAgentsAPIActor or 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.

    • BetaManagedAgentsSessionActor object { session_id, type }

      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 for further provenance.

      • type: "session_actor"

        • "session_actor"

    • BetaManagedAgentsAPIActor object { api_key_id, type }

      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 object { type, user_id }

      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 object { api_key_id, type }

    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 object { id, created_at, memory_id, 10 more }

    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 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: optional string

      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: optional string

      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: optional number

      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: optional 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.

      • BetaManagedAgentsSessionActor object { session_id, type }

        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 for further provenance.

        • type: "session_actor"

          • "session_actor"

      • BetaManagedAgentsAPIActor object { api_key_id, type }

        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 object { type, user_id }

        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: optional string

      The memory's path at the time of this write. null if and only if redacted_at is set.

    • redacted_at: optional string

      A timestamp in RFC 3339 format

    • redacted_by: optional 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.

Beta Managed Agents Memory Version Operation

  • BetaManagedAgentsMemoryVersionOperation = "created" or "modified" or "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 object { session_id, type }

    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 for further provenance.

    • type: "session_actor"

      • "session_actor"

Beta Managed Agents User Actor

  • BetaManagedAgentsUserActor object { type, user_id }

    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

post /v1/files

Upload File

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Returns

  • FileMetadata object { id, created_at, filename, 5 more }

    • 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: optional boolean

      Whether the file can be downloaded.

    • scope: optional BetaFileScope

      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

curl https://api.anthropic.com/v1/files \
    -H 'Content-Type: multipart/form-data' \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: files-api-2025-04-14' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY" \
    -F 'file=@/path/to/file'

Response

{
  "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

get /v1/files

List Files

Query Parameters

  • after_id: optional string

    ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object.

  • before_id: optional string

    ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object.

  • limit: optional number

    Number of items to return per page.

    Defaults to 20. Ranges from 1 to 1000.

  • scope_id: optional string

    Filter by scope ID. Only returns files associated with the specified scope (e.g., a session ID).

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Returns

  • data: array of FileMetadata

    List of file metadata objects.

    • 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: optional boolean

      Whether the file can be downloaded.

    • scope: optional BetaFileScope

      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"

  • first_id: optional string

    ID of the first file in this page of results.

  • has_more: optional boolean

    Whether there are more results available.

  • last_id: optional string

    ID of the last file in this page of results.

Example

curl https://api.anthropic.com/v1/files \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: files-api-2025-04-14' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

Response

{
  "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

get /v1/files/{file_id}/content

Download File

Path Parameters

  • file_id: string

    ID of the File.

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Example

curl https://api.anthropic.com/v1/files/$FILE_ID/content \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: files-api-2025-04-14' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

Get File Metadata

get /v1/files/{file_id}

Get File Metadata

Path Parameters

  • file_id: string

    ID of the File.

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Returns

  • FileMetadata object { id, created_at, filename, 5 more }

    • 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: optional boolean

      Whether the file can be downloaded.

    • scope: optional BetaFileScope

      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

curl https://api.anthropic.com/v1/files/$FILE_ID \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: files-api-2025-04-14' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

Response

{
  "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

delete /v1/files/{file_id}

Delete File

Path Parameters

  • file_id: string

    ID of the File.

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Returns

  • DeletedFile object { id, type }

    • id: string

      ID of the deleted file.

    • type: optional "file_deleted"

      Deleted object type.

      For file deletion, this is always "file_deleted".

      • "file_deleted"

Example

curl https://api.anthropic.com/v1/files/$FILE_ID \
    -X DELETE \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: files-api-2025-04-14' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

Response

{
  "id": "file_011CNha8iCJcU1wXNR6q4V8w",
  "type": "file_deleted"
}

Domain Types

Beta File Scope

  • BetaFileScope object { id, type }

    • 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 object { id, type }

    • id: string

      ID of the deleted file.

    • type: optional "file_deleted"

      Deleted object type.

      For file deletion, this is always "file_deleted".

      • "file_deleted"

File Metadata

  • FileMetadata object { id, created_at, filename, 5 more }

    • 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: optional boolean

      Whether the file can be downloaded.

    • scope: optional BetaFileScope

      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

post /v1/skills

Create Skill

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Returns

  • 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

    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

    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

curl https://api.anthropic.com/v1/skills \
    -X POST \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: skills-2025-10-02' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

Response

{
  "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

get /v1/skills

List Skills

Query Parameters

  • limit: optional number

    Number of results to return per page.

    Maximum value is 100. Defaults to 20.

  • page: optional string

    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: optional string

    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

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Returns

  • data: array of object { id, created_at, display_title, 4 more }

    List of skills.

    • 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

      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

      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.

  • has_more: boolean

    Whether there are more results available.

    If true, there are additional results that can be fetched using the next_page token.

  • next_page: string

    Token for fetching the next page of results.

    If null, there are no more results available. Pass this value to the page_token parameter in the next request to get the next page.

Example

curl https://api.anthropic.com/v1/skills \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: skills-2025-10-02' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

Response

{
  "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

get /v1/skills/{skill_id}

Get Skill

Path Parameters

  • skill_id: string

    Unique identifier for the skill.

    The format and length of IDs may change over time.

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Returns

  • 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

    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

    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

curl https://api.anthropic.com/v1/skills/$SKILL_ID \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: skills-2025-10-02' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

Response

{
  "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

delete /v1/skills/{skill_id}

Delete Skill

Path Parameters

  • skill_id: string

    Unique identifier for the skill.

    The format and length of IDs may change over time.

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Returns

  • 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

curl https://api.anthropic.com/v1/skills/$SKILL_ID \
    -X DELETE \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: skills-2025-10-02' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

Response

{
  "id": "skill_01JAbcdefghijklmnopqrstuvw",
  "type": "type"
}

Domain Types

Skill Create Response

  • SkillCreateResponse object { id, created_at, display_title, 4 more }

    • 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

      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

      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 object { id, created_at, display_title, 4 more }

    • 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

      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

      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 object { id, created_at, display_title, 4 more }

    • 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

      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

      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 object { id, type }

    • 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

post /v1/skills/{skill_id}/versions

Create Skill Version

Path Parameters

  • skill_id: string

    Unique identifier for the skill.

    The format and length of IDs may change over time.

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Returns

  • 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

curl https://api.anthropic.com/v1/skills/$SKILL_ID/versions \
    -X POST \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: skills-2025-10-02' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

Response

{
  "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

get /v1/skills/{skill_id}/versions

List Skill Versions

Path Parameters

  • skill_id: string

    Unique identifier for the skill.

    The format and length of IDs may change over time.

Query Parameters

  • limit: optional number

    Number of items to return per page.

    Defaults to 20. Ranges from 1 to 1000.

  • page: optional string

    Optionally set to the next_page token from the previous response.

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Returns

  • data: array of object { id, created_at, description, 5 more }

    List of skill versions.

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

  • has_more: boolean

    Indicates if there are more results in the requested page direction.

  • next_page: string

    Token to provide in as page in the subsequent request to retrieve the next page of data.

Example

curl https://api.anthropic.com/v1/skills/$SKILL_ID/versions \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: skills-2025-10-02' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

Response

{
  "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

get /v1/skills/{skill_id}/versions/{version}/content

Download a skill version's content as a zip archive.

Path Parameters

  • skill_id: string

    Unique identifier for the skill.

    The format and length of IDs may change over time.

  • version: string

    Version identifier for the skill.

    Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129").

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Example

curl https://api.anthropic.com/v1/skills/$SKILL_ID/versions/$VERSION/content \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: skills-2025-10-02' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

Get Skill Version

get /v1/skills/{skill_id}/versions/{version}

Get Skill Version

Path Parameters

  • skill_id: string

    Unique identifier for the skill.

    The format and length of IDs may change over time.

  • version: string

    Version identifier for the skill.

    Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129").

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Returns

  • 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

curl https://api.anthropic.com/v1/skills/$SKILL_ID/versions/$VERSION \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: skills-2025-10-02' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

Response

{
  "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

delete /v1/skills/{skill_id}/versions/{version}

Delete Skill Version

Path Parameters

  • skill_id: string

    Unique identifier for the skill.

    The format and length of IDs may change over time.

  • version: string

    Version identifier for the skill.

    Each version is identified by a Unix epoch timestamp (e.g., "1759178010641129").

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Returns

  • 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

curl https://api.anthropic.com/v1/skills/$SKILL_ID/versions/$VERSION \
    -X DELETE \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: skills-2025-10-02' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

Response

{
  "id": "1759178010641129",
  "type": "type"
}

Domain Types

Version Create Response

  • VersionCreateResponse object { id, created_at, description, 5 more }

    • 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 object { id, created_at, description, 5 more }

    • 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 object { id, created_at, description, 5 more }

    • 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 object { id, type }

    • 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

post /v1/user_profiles

Create User Profile

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Body Parameters

  • external_id: optional string

    Platform's own identifier for this user. Not enforced unique. Maximum 255 characters.

  • metadata: optional map[string]

    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: optional string

    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: optional "external" or "resold" or "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"

Returns

  • BetaUserProfile object { id, created_at, metadata, 6 more }

    • id: string

      Unique identifier for this user profile, prefixed uprof_.

    • created_at: string

      A timestamp in RFC 3339 format

    • metadata: map[string]

      Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars.

    • relationship: "external" or "resold" or "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: map[BetaUserProfileTrustGrant]

      Trust grants for this profile, keyed by grant name. Key omitted when no grant is active or in flight.

      • status: "active" or "pending" or "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: optional string

      Platform's own identifier for this user. Not enforced unique.

    • name: optional string

      Display name of the entity this profile represents. For resold this is the resold-to company's name.

Example

curl https://api.anthropic.com/v1/user_profiles \
    -H 'Content-Type: application/json' \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: user-profiles-2026-03-24' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY" \
    -d '{
          "external_id": "user_12345",
          "metadata": {}
        }'

Response

{
  "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

get /v1/user_profiles

List User Profiles

Query Parameters

  • limit: optional number

    Query parameter for limit

  • order: optional "asc" or "desc"

    Query parameter for order

    • "asc"

    • "desc"

  • page: optional string

    Query parameter for page

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Returns

  • data: array of BetaUserProfile

    User profiles on this page.

    • id: string

      Unique identifier for this user profile, prefixed uprof_.

    • created_at: string

      A timestamp in RFC 3339 format

    • metadata: map[string]

      Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars.

    • relationship: "external" or "resold" or "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: map[BetaUserProfileTrustGrant]

      Trust grants for this profile, keyed by grant name. Key omitted when no grant is active or in flight.

      • status: "active" or "pending" or "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: optional string

      Platform's own identifier for this user. Not enforced unique.

    • name: optional string

      Display name of the entity this profile represents. For resold this is the resold-to company's name.

  • next_page: string

    Cursor for the next page, or null when there are no more results.

Example

curl https://api.anthropic.com/v1/user_profiles \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: user-profiles-2026-03-24' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

Response

{
  "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

get /v1/user_profiles/{user_profile_id}

Get User Profile

Path Parameters

  • user_profile_id: string

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Returns

  • BetaUserProfile object { id, created_at, metadata, 6 more }

    • id: string

      Unique identifier for this user profile, prefixed uprof_.

    • created_at: string

      A timestamp in RFC 3339 format

    • metadata: map[string]

      Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars.

    • relationship: "external" or "resold" or "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: map[BetaUserProfileTrustGrant]

      Trust grants for this profile, keyed by grant name. Key omitted when no grant is active or in flight.

      • status: "active" or "pending" or "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: optional string

      Platform's own identifier for this user. Not enforced unique.

    • name: optional string

      Display name of the entity this profile represents. For resold this is the resold-to company's name.

Example

curl https://api.anthropic.com/v1/user_profiles/$USER_PROFILE_ID \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: user-profiles-2026-03-24' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

Response

{
  "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

post /v1/user_profiles/{user_profile_id}

Update User Profile

Path Parameters

  • user_profile_id: string

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Body Parameters

  • external_id: optional string

    If present, replaces the stored external_id. Omit to leave unchanged. Maximum 255 characters.

  • metadata: optional map[string]

    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: optional string

    If present, replaces the stored name. Omit to leave unchanged. Maximum 255 characters.

  • relationship: optional "external" or "resold" or "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"

Returns

  • BetaUserProfile object { id, created_at, metadata, 6 more }

    • id: string

      Unique identifier for this user profile, prefixed uprof_.

    • created_at: string

      A timestamp in RFC 3339 format

    • metadata: map[string]

      Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars.

    • relationship: "external" or "resold" or "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: map[BetaUserProfileTrustGrant]

      Trust grants for this profile, keyed by grant name. Key omitted when no grant is active or in flight.

      • status: "active" or "pending" or "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: optional string

      Platform's own identifier for this user. Not enforced unique.

    • name: optional string

      Display name of the entity this profile represents. For resold this is the resold-to company's name.

Example

curl https://api.anthropic.com/v1/user_profiles/$USER_PROFILE_ID \
    -H 'Content-Type: application/json' \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: user-profiles-2026-03-24' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY" \
    -d '{
          "external_id": "user_12345"
        }'

Response

{
  "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

post /v1/user_profiles/{user_profile_id}/enrollment_url

Create Enrollment URL

Path Parameters

  • user_profile_id: string

Header Parameters

  • "anthropic-beta": optional array of AnthropicBeta

    Optional header to specify the beta version(s) you want to use.

    • string

    • "message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 22 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"

Returns

  • BetaUserProfileEnrollmentURL object { expires_at, type, url }

    • 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

curl https://api.anthropic.com/v1/user_profiles/$USER_PROFILE_ID/enrollment_url \
    -X POST \
    -H 'anthropic-version: 2023-06-01' \
    -H 'anthropic-beta: user-profiles-2026-03-24' \
    -H "X-Api-Key: $ANTHROPIC_API_KEY"

Response

{
  "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 object { id, created_at, metadata, 6 more }

    • id: string

      Unique identifier for this user profile, prefixed uprof_.

    • created_at: string

      A timestamp in RFC 3339 format

    • metadata: map[string]

      Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars.

    • relationship: "external" or "resold" or "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: map[BetaUserProfileTrustGrant]

      Trust grants for this profile, keyed by grant name. Key omitted when no grant is active or in flight.

      • status: "active" or "pending" or "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: optional string

      Platform's own identifier for this user. Not enforced unique.

    • name: optional string

      Display name of the entity this profile represents. For resold this is the resold-to company's name.

Beta User Profile Enrollment URL

  • BetaUserProfileEnrollmentURL object { expires_at, type, url }

    • 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 object { status }

    • status: "active" or "pending" or "rejected"

      Status of the trust grant.

      • "active"

      • "pending"

      • "rejected"

Webhooks

Domain Types

Beta Webhook Event

  • BetaWebhookEvent object { id, created_at, data, type }

    • id: string

      Unique event identifier for idempotency.

    • created_at: string

      RFC 3339 timestamp when the event occurred.

    • data: BetaWebhookEventData

      • BetaWebhookSessionCreatedEventData object { id, organization_id, type, workspace_id }

        • id: string

          ID of the resource that triggered the event.

        • organization_id: string

        • type: "session.created"

          • "session.created"

        • workspace_id: string

      • BetaWebhookSessionPendingEventData object { id, organization_id, type, workspace_id }

        • id: string

          ID of the resource that triggered the event.

        • organization_id: string

        • type: "session.pending"

          • "session.pending"

        • workspace_id: string

      • BetaWebhookSessionRunningEventData object { id, organization_id, type, workspace_id }

        • id: string

          ID of the resource that triggered the event.

        • organization_id: string

        • type: "session.running"

          • "session.running"

        • workspace_id: string

      • BetaWebhookSessionIdledEventData object { id, organization_id, type, workspace_id }

        • id: string

          ID of the resource that triggered the event.

        • organization_id: string

        • type: "session.idled"

          • "session.idled"

        • workspace_id: string

      • BetaWebhookSessionRequiresActionEventData object { id, organization_id, type, workspace_id }

        • id: string

          ID of the resource that triggered the event.

        • organization_id: string

        • type: "session.requires_action"

          • "session.requires_action"

        • workspace_id: string

      • BetaWebhookSessionArchivedEventData object { id, organization_id, type, workspace_id }

        • id: string

          ID of the resource that triggered the event.

        • organization_id: string

        • type: "session.archived"

          • "session.archived"

        • workspace_id: string

      • BetaWebhookSessionDeletedEventData object { id, organization_id, type, workspace_id }

        • id: string

          ID of the resource that triggered the event.

        • organization_id: string

        • type: "session.deleted"

          • "session.deleted"

        • workspace_id: string

      • BetaWebhookSessionStatusRescheduledEventData object { id, organization_id, type, workspace_id }

        • id: string

          ID of the resource that triggered the event.

        • organization_id: string

        • type: "session.status_rescheduled"

          • "session.status_rescheduled"

        • workspace_id: string

      • BetaWebhookSessionStatusRunStartedEventData object { id, organization_id, type, workspace_id }

        • 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 object { id, organization_id, type, workspace_id }

        • id: string

          ID of the resource that triggered the event.

        • organization_id: string

        • type: "session.status_idled"

          • "session.status_idled"

        • workspace_id: string

      • BetaWebhookSessionStatusTerminatedEventData object { id, organization_id, type, workspace_id }

        • id: string

          ID of the resource that triggered the event.

        • organization_id: string

        • type: "session.status_terminated"

          • "session.status_terminated"

        • workspace_id: string

      • BetaWebhookSessionThreadCreatedEventData object { id, organization_id, type, workspace_id }

        • id: string

          ID of the resource that triggered the event.

        • organization_id: string

        • type: "session.thread_created"

          • "session.thread_created"

        • workspace_id: string

      • BetaWebhookSessionThreadIdledEventData object { id, organization_id, type, workspace_id }

        • id: string

          ID of the resource that triggered the event.

        • organization_id: string

        • type: "session.thread_idled"

          • "session.thread_idled"

        • workspace_id: string

      • BetaWebhookSessionThreadTerminatedEventData object { id, organization_id, type, workspace_id }

        • id: string

          ID of the resource that triggered the event.

        • organization_id: string

        • type: "session.thread_terminated"

          • "session.thread_terminated"

        • workspace_id: string

      • BetaWebhookSessionOutcomeEvaluationEndedEventData object { id, organization_id, type, workspace_id }

        • 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 object { id, organization_id, type, workspace_id }

        • id: string

          ID of the resource that triggered the event.

        • organization_id: string

        • type: "vault.created"

          • "vault.created"

        • workspace_id: string

      • BetaWebhookVaultArchivedEventData object { id, organization_id, type, workspace_id }

        • id: string

          ID of the resource that triggered the event.

        • organization_id: string

        • type: "vault.archived"

          • "vault.archived"

        • workspace_id: string

      • BetaWebhookVaultDeletedEventData object { id, organization_id, type, workspace_id }

        • id: string

          ID of the resource that triggered the event.

        • organization_id: string

        • type: "vault.deleted"

          • "vault.deleted"

        • workspace_id: string

      • BetaWebhookVaultCredentialCreatedEventData object { id, organization_id, type, 2 more }

        • 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 object { id, organization_id, type, 2 more }

        • 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 object { id, organization_id, type, 2 more }

        • 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 object { id, organization_id, type, 2 more }

        • 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 or BetaWebhookSessionPendingEventData or BetaWebhookSessionRunningEventData or 19 more

    • BetaWebhookSessionCreatedEventData object { id, organization_id, type, workspace_id }

      • id: string

        ID of the resource that triggered the event.

      • organization_id: string

      • type: "session.created"

        • "session.created"

      • workspace_id: string

    • BetaWebhookSessionPendingEventData object { id, organization_id, type, workspace_id }

      • id: string

        ID of the resource that triggered the event.

      • organization_id: string

      • type: "session.pending"

        • "session.pending"

      • workspace_id: string

    • BetaWebhookSessionRunningEventData object { id, organization_id, type, workspace_id }

      • id: string

        ID of the resource that triggered the event.

      • organization_id: string

      • type: "session.running"

        • "session.running"

      • workspace_id: string

    • BetaWebhookSessionIdledEventData object { id, organization_id, type, workspace_id }

      • id: string

        ID of the resource that triggered the event.

      • organization_id: string

      • type: "session.idled"

        • "session.idled"

      • workspace_id: string

    • BetaWebhookSessionRequiresActionEventData object { id, organization_id, type, workspace_id }

      • id: string

        ID of the resource that triggered the event.

      • organization_id: string

      • type: "session.requires_action"

        • "session.requires_action"

      • workspace_id: string

    • BetaWebhookSessionArchivedEventData object { id, organization_id, type, workspace_id }

      • id: string

        ID of the resource that triggered the event.

      • organization_id: string

      • type: "session.archived"

        • "session.archived"

      • workspace_id: string

    • BetaWebhookSessionDeletedEventData object { id, organization_id, type, workspace_id }

      • id: string

        ID of the resource that triggered the event.

      • organization_id: string

      • type: "session.deleted"

        • "session.deleted"

      • workspace_id: string

    • BetaWebhookSessionStatusRescheduledEventData object { id, organization_id, type, workspace_id }

      • id: string

        ID of the resource that triggered the event.

      • organization_id: string

      • type: "session.status_rescheduled"

        • "session.status_rescheduled"

      • workspace_id: string

    • BetaWebhookSessionStatusRunStartedEventData object { id, organization_id, type, workspace_id }

      • 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 object { id, organization_id, type, workspace_id }

      • id: string

        ID of the resource that triggered the event.

      • organization_id: string

      • type: "session.status_idled"

        • "session.status_idled"

      • workspace_id: string

    • BetaWebhookSessionStatusTerminatedEventData object { id, organization_id, type, workspace_id }

      • id: string

        ID of the resource that triggered the event.

      • organization_id: string

      • type: "session.status_terminated"

        • "session.status_terminated"

      • workspace_id: string

    • BetaWebhookSessionThreadCreatedEventData object { id, organization_id, type, workspace_id }

      • id: string

        ID of the resource that triggered the event.

      • organization_id: string

      • type: "session.thread_created"

        • "session.thread_created"

      • workspace_id: string

    • BetaWebhookSessionThreadIdledEventData object { id, organization_id, type, workspace_id }

      • id: string

        ID of the resource that triggered the event.

      • organization_id: string

      • type: "session.thread_idled"

        • "session.thread_idled"

      • workspace_id: string

    • BetaWebhookSessionThreadTerminatedEventData object { id, organization_id, type, workspace_id }

      • id: string

        ID of the resource that triggered the event.

      • organization_id: string

      • type: "session.thread_terminated"

        • "session.thread_terminated"

      • workspace_id: string

    • BetaWebhookSessionOutcomeEvaluationEndedEventData object { id, organization_id, type, workspace_id }

      • 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 object { id, organization_id, type, workspace_id }

      • id: string

        ID of the resource that triggered the event.

      • organization_id: string

      • type: "vault.created"

        • "vault.created"

      • workspace_id: string

    • BetaWebhookVaultArchivedEventData object { id, organization_id, type, workspace_id }

      • id: string

        ID of the resource that triggered the event.

      • organization_id: string

      • type: "vault.archived"

        • "vault.archived"

      • workspace_id: string

    • BetaWebhookVaultDeletedEventData object { id, organization_id, type, workspace_id }

      • id: string

        ID of the resource that triggered the event.

      • organization_id: string

      • type: "vault.deleted"

        • "vault.deleted"

      • workspace_id: string

    • BetaWebhookVaultCredentialCreatedEventData object { id, organization_id, type, 2 more }

      • 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 object { id, organization_id, type, 2 more }

      • 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 object { id, organization_id, type, 2 more }

      • 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 object { id, organization_id, type, 2 more }

      • 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 object { id, organization_id, type, workspace_id }

    • 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 object { id, organization_id, type, workspace_id }

    • 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 object { id, organization_id, type, workspace_id }

    • 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 object { id, organization_id, type, workspace_id }

    • 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 object { id, organization_id, type, workspace_id }

    • 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 object { id, organization_id, type, workspace_id }

    • 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 object { id, organization_id, type, workspace_id }

    • 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 object { id, organization_id, type, workspace_id }

    • 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 object { id, organization_id, type, workspace_id }

    • 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 object { id, organization_id, type, workspace_id }

    • 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 object { id, organization_id, type, workspace_id }

    • 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 object { id, organization_id, type, workspace_id }

    • 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 object { id, organization_id, type, workspace_id }

    • 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 object { id, organization_id, type, workspace_id }

    • 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 object { id, organization_id, type, workspace_id }

    • 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 object { id, organization_id, type, workspace_id }

    • 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 object { id, organization_id, type, workspace_id }

    • 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 object { id, organization_id, type, 2 more }

    • 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 object { id, organization_id, type, 2 more }

    • 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 object { id, organization_id, type, 2 more }

    • 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 object { id, organization_id, type, 2 more }

    • 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 object { id, organization_id, type, workspace_id }

    • 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 object { id, created_at, data, type }

    • id: string

      Unique event identifier for idempotency.

    • created_at: string

      RFC 3339 timestamp when the event occurred.

    • data: BetaWebhookEventData

      • BetaWebhookSessionCreatedEventData object { id, organization_id, type, workspace_id }

        • id: string

          ID of the resource that triggered the event.

        • organization_id: string

        • type: "session.created"

          • "session.created"

        • workspace_id: string

      • BetaWebhookSessionPendingEventData object { id, organization_id, type, workspace_id }

        • id: string

          ID of the resource that triggered the event.

        • organization_id: string

        • type: "session.pending"

          • "session.pending"

        • workspace_id: string

      • BetaWebhookSessionRunningEventData object { id, organization_id, type, workspace_id }

        • id: string

          ID of the resource that triggered the event.

        • organization_id: string

        • type: "session.running"

          • "session.running"

        • workspace_id: string

      • BetaWebhookSessionIdledEventData object { id, organization_id, type, workspace_id }

        • id: string

          ID of the resource that triggered the event.

        • organization_id: string

        • type: "session.idled"

          • "session.idled"

        • workspace_id: string

      • BetaWebhookSessionRequiresActionEventData object { id, organization_id, type, workspace_id }

        • id: string

          ID of the resource that triggered the event.

        • organization_id: string

        • type: "session.requires_action"

          • "session.requires_action"

        • workspace_id: string

      • BetaWebhookSessionArchivedEventData object { id, organization_id, type, workspace_id }

        • id: string

          ID of the resource that triggered the event.

        • organization_id: string

        • type: "session.archived"

          • "session.archived"

        • workspace_id: string

      • BetaWebhookSessionDeletedEventData object { id, organization_id, type, workspace_id }

        • id: string

          ID of the resource that triggered the event.

        • organization_id: string

        • type: "session.deleted"

          • "session.deleted"

        • workspace_id: string

      • BetaWebhookSessionStatusRescheduledEventData object { id, organization_id, type, workspace_id }

        • id: string

          ID of the resource that triggered the event.

        • organization_id: string

        • type: "session.status_rescheduled"

          • "session.status_rescheduled"

        • workspace_id: string

      • BetaWebhookSessionStatusRunStartedEventData object { id, organization_id, type, workspace_id }

        • 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 object { id, organization_id, type, workspace_id }

        • id: string

          ID of the resource that triggered the event.

        • organization_id: string

        • type: "session.status_idled"

          • "session.status_idled"

        • workspace_id: string

      • BetaWebhookSessionStatusTerminatedEventData object { id, organization_id, type, workspace_id }

        • id: string

          ID of the resource that triggered the event.

        • organization_id: string

        • type: "session.status_terminated"

          • "session.status_terminated"

        • workspace_id: string

      • BetaWebhookSessionThreadCreatedEventData object { id, organization_id, type, workspace_id }

        • id: string

          ID of the resource that triggered the event.

        • organization_id: string

        • type: "session.thread_created"

          • "session.thread_created"

        • workspace_id: string

      • BetaWebhookSessionThreadIdledEventData object { id, organization_id, type, workspace_id }

        • id: string

          ID of the resource that triggered the event.

        • organization_id: string

        • type: "session.thread_idled"

          • "session.thread_idled"

        • workspace_id: string

      • BetaWebhookSessionThreadTerminatedEventData object { id, organization_id, type, workspace_id }

        • id: string

          ID of the resource that triggered the event.

        • organization_id: string

        • type: "session.thread_terminated"

          • "session.thread_terminated"

        • workspace_id: string

      • BetaWebhookSessionOutcomeEvaluationEndedEventData object { id, organization_id, type, workspace_id }

        • 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 object { id, organization_id, type, workspace_id }

        • id: string

          ID of the resource that triggered the event.

        • organization_id: string

        • type: "vault.created"

          • "vault.created"

        • workspace_id: string

      • BetaWebhookVaultArchivedEventData object { id, organization_id, type, workspace_id }

        • id: string

          ID of the resource that triggered the event.

        • organization_id: string

        • type: "vault.archived"

          • "vault.archived"

        • workspace_id: string

      • BetaWebhookVaultDeletedEventData object { id, organization_id, type, workspace_id }

        • id: string

          ID of the resource that triggered the event.

        • organization_id: string

        • type: "vault.deleted"

          • "vault.deleted"

        • workspace_id: string

      • BetaWebhookVaultCredentialCreatedEventData object { id, organization_id, type, 2 more }

        • 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 object { id, organization_id, type, 2 more }

        • 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 object { id, organization_id, type, 2 more }

        • 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 object { id, organization_id, type, 2 more }

        • 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"