Page history
List Events
api/beta/sessions/events/list
History
api/beta/sessions/events/list Changed · +15 / -1 lines
from line 64
- `string` - - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 31 more` + - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 38 more` - `"message-batches-2024-09-24"`
from line 133
- `"agent-memory-2026-07-22"` - `"mid-conversation-tool-changes-2026-07-01"` + + - `"compact-2026-01-12"` + + - `"computer-use-2025-11-24"` + + - `"mcp-tunnels-2026-06-22"` + + - `"structured-outputs-2025-11-13"` + + - `"task-budgets-2026-03-13"` + + - `"thinking-display-updates-2026-08-18"` + + - `"ce-user-management-2026-07-13"` ## Returns
api/beta/sessions/events/list Changed · +328 / -387 lines
# List Events ## Path parameters ## Query parameters ## Headers ## Returns ## Example ### Response (200) ## List Events ### Path Parameters ### Query Parameters ### Header Parameters ### Returns ### Example #### Response
The two sides of this change are too far apart to line up, so this is the differ's own diff of it.
from line 1
---- -title: List Events -url: https://platform.claude.com/docs/en/api/beta/sessions/events/list ---- - -## List Events - -**get** `/v1/sessions/{session_id}/events` +# List Events + +**GET** `/v1/sessions/{session_id}/events` List Events -### Path Parameters +## Path parameters - `session_id: string` -### Query Parameters +## Query parameters - `"created_at[gt]": optional string` Return events created after this time (exclusive). Compared against the event's `processed_at` value. + format: date-time + - `"created_at[gte]": optional string` Return events created at or after this time (inclusive). Compared against the event's `processed_at` value. + format: date-time + - `"created_at[lt]": optional string` Return events created before this time (exclusive). Compared against the event's `processed_at` value. + format: date-time + - `"created_at[lte]": optional string` Return events created at or before this time (inclusive). Compared against the event's `processed_at` value. + format: date-time + - `limit: optional number` Query parameter for limit + format: int32 + - `order: optional "asc" or "desc"` Sort direction for results, ordered by the event's `processed_at`. Defaults to asc (chronological).
from line 56
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 +## Headers - `"anthropic-beta": optional array of AnthropicBeta`
from line 134
- `"mid-conversation-tool-changes-2026-07-01"` -### Returns +## Returns - `data: optional array of BetaManagedAgentsSessionEvent` Events for the session, ordered by `processed_at`. - - `BetaManagedAgentsUserMessageEvent object { id, content, type, processed_at }` + - `BetaManagedAgentsUserMessageEvent object` A user message event in the session conversation.
from line 152
Array of content blocks comprising the user message. - - `BetaManagedAgentsTextBlock object { text, type }` + - `BetaManagedAgentsTextBlock object` Regular text content.
from line 160
The text content. + minLength: 1 + - `type: "text"` - - `"text"` - - - `BetaManagedAgentsImageBlock object { source, type }` + - `BetaManagedAgentsImageBlock object` Image content specified directly as base64 data or as a reference via a URL.
from line 172
Union type for image source variants. - - `BetaManagedAgentsBase64ImageSource object { data, media_type, type }` + - `BetaManagedAgentsBase64ImageSource object` Base64-encoded image data.
from line 180
Base64-encoded image data. + minLength: 1 + - `media_type: string` MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp"). + minLength: 1 + - `type: "base64"` - - `"base64"` - - - `BetaManagedAgentsURLImageSource object { type, url }` + - `BetaManagedAgentsURLImageSource object` Image referenced by URL. - `type: "url"` - - `"url"` - - `url: string` URL of the image to fetch. - - `BetaManagedAgentsFileImageSource object { file_id, type }` + minLength: 1 + + - `BetaManagedAgentsFileImageSource object` Image referenced by file ID.
from line 210
ID of a previously uploaded file. + minLength: 1 + - `type: "file"` - - `"file"` - - `type: "image"` - - `"image"` - - - `BetaManagedAgentsDocumentBlock object { source, type, context, title }` + - `BetaManagedAgentsDocumentBlock object` Document content, either specified directly as base64 data, as text, or as a reference via a URL.
from line 224
Union type for document source variants. - - `BetaManagedAgentsBase64DocumentSource object { data, media_type, type }` + - `BetaManagedAgentsBase64DocumentSource object` Base64-encoded document data.
from line 232
Base64-encoded document data. + minLength: 1 + - `media_type: string` MIME type of the document (e.g., "application/pdf"). + minLength: 1 + - `type: "base64"` - - `"base64"` - - - `BetaManagedAgentsPlainTextDocumentSource object { data, media_type, type }` + - `BetaManagedAgentsPlainTextDocumentSource object` Plain text document content.
from line 250
The plain text content. + minLength: 1 + - `media_type: "text/plain"` MIME type of the text content. Must be "text/plain". - - `"text/plain"` - - `type: "text"` - - `"text"` - - - `BetaManagedAgentsURLDocumentSource object { type, url }` + - `BetaManagedAgentsURLDocumentSource object` Document referenced by URL. - `type: "url"` - - `"url"` - - `url: string` URL of the document to fetch. - - `BetaManagedAgentsFileDocumentSource object { file_id, type }` + minLength: 1 + + - `BetaManagedAgentsFileDocumentSource object` Document referenced by file ID.
from line 278
ID of a previously uploaded file. + minLength: 1 + - `type: "file"` - - `"file"` - - `type: "document"` - - `"document"` - - `context: optional string or null` Additional context about the document for the model.
from line 292
The title of the document. - - `BetaManagedAgentsRedactedBlock object { type }` + - `BetaManagedAgentsRedactedBlock object` Placeholder for content withheld by Anthropic model policy. - `type: "redacted"` - - `"redacted"` - - `type: "user.message"` - - `"user.message"` - - `processed_at: optional string or null` A timestamp in RFC 3339 format - - `BetaManagedAgentsUserInterruptEvent object { id, type, processed_at, session_thread_id }` + format: date-time + + - `BetaManagedAgentsUserInterruptEvent object` An interrupt event that pauses agent execution and returns control to the user.
from line 316
- `type: "user.interrupt"` - - `"user.interrupt"` - - `processed_at: optional string or null` A timestamp in RFC 3339 format + format: date-time + - `session_thread_id: optional string or null` If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread. - - `BetaManagedAgentsUserToolConfirmationEvent object { id, result, tool_use_id, 4 more }` + - `BetaManagedAgentsUserToolConfirmationEvent object` A tool confirmation event that approves or denies a pending tool execution.
from line 348
- `type: "user.tool_confirmation"` - - `"user.tool_confirmation"` - - `deny_message: optional string or null` Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'. + maxLength: 10000 + - `processed_at: optional string or null` A timestamp in RFC 3339 format + format: date-time + - `session_thread_id: optional string or null` When set, the confirmation routes to this subagent's thread rather than the primary. Echo this from the `session_thread_id` on the `agent.tool_use` or `agent.mcp_tool_use` event that prompted the approval. - - `BetaManagedAgentsUserCustomToolResultEvent object { id, custom_tool_use_id, type, 4 more }` + - `BetaManagedAgentsUserCustomToolResultEvent object` Event sent by the client providing the result of a custom tool execution.
from line 378
- `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 }` + - `BetaManagedAgentsTextBlock object` Regular text content. - - `BetaManagedAgentsImageBlock object { source, type }` + - `BetaManagedAgentsImageBlock object` Image content specified directly as base64 data or as a reference via a URL. - - `BetaManagedAgentsDocumentBlock object { source, type, context, title }` + - `BetaManagedAgentsDocumentBlock object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - - `BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }` + - `BetaManagedAgentsSearchResultBlock object` A block containing a web search result.
from line 414
The text content. + minLength: 1 + - `type: "text"` - - `"text"` - - `source: string` The URL source of the search result. + minLength: 1 + - `title: string` The title of the search result. + minLength: 1 + - `type: "search_result"` - - `"search_result"` - - `is_error: optional boolean or null` Whether the tool execution resulted in an error.
from line 440
A timestamp in RFC 3339 format + format: date-time + - `session_thread_id: optional string or null` 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 }` + - `BetaManagedAgentsAgentCustomToolUseEvent object` 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.
from line 466
A timestamp in RFC 3339 format + format: date-time + - `type: "agent.custom_tool_use"` - - `"agent.custom_tool_use"` - - `session_thread_id: optional string or null` When set, this event was cross-posted from a subagent's thread to surface its custom tool use on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.custom_tool_result` event to route the result back. - - `BetaManagedAgentsAgentMessageEvent object { id, content, processed_at, type }` + - `BetaManagedAgentsAgentMessageEvent object` An agent response event in the session conversation.
from line 486
Array of text blocks comprising the agent response. - - `BetaManagedAgentsTextBlock object { text, type }` + - `BetaManagedAgentsTextBlock object` Regular text content. - - `BetaManagedAgentsRedactedBlock object { type }` + - `BetaManagedAgentsRedactedBlock object` Placeholder for content withheld by Anthropic model policy.
from line 498
A timestamp in RFC 3339 format + format: date-time + - `type: "agent.message"` - - `"agent.message"` - - - `BetaManagedAgentsAgentThinkingEvent object { id, processed_at, type }` + - `BetaManagedAgentsAgentThinkingEvent object` Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier.
from line 514
A timestamp in RFC 3339 format + format: date-time + - `type: "agent.thinking"` - - `"agent.thinking"` - - - `BetaManagedAgentsAgentMCPToolUseEvent object { id, input, mcp_server_name, 5 more }` + - `BetaManagedAgentsAgentMCPToolUseEvent object` Event emitted when the agent invokes a tool provided by an MCP server.
from line 542
A timestamp in RFC 3339 format + format: date-time + - `type: "agent.mcp_tool_use"` - - `"agent.mcp_tool_use"` - - `evaluated_permission: optional "allow" or "ask" or "deny"` AgentEvaluatedPermission enum
from line 560
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 }` + - `BetaManagedAgentsAgentMCPToolResultEvent object` Event representing the result of an MCP tool execution.
from line 576
A timestamp in RFC 3339 format + format: date-time + - `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 }` + - `BetaManagedAgentsTextBlock object` Regular text content. - - `BetaManagedAgentsImageBlock object { source, type }` + - `BetaManagedAgentsImageBlock object` Image content specified directly as base64 data or as a reference via a URL. - - `BetaManagedAgentsDocumentBlock object { source, type, context, title }` + - `BetaManagedAgentsDocumentBlock object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - - `BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }` + - `BetaManagedAgentsSearchResultBlock object` A block containing a web search result.
from line 604
Whether the tool execution resulted in an error. - - `BetaManagedAgentsAgentToolUseEvent object { id, input, name, 4 more }` + - `BetaManagedAgentsAgentToolUseEvent object` Event emitted when the agent invokes a built-in agent tool.
from line 624
A timestamp in RFC 3339 format + format: date-time + - `type: "agent.tool_use"` - - `"agent.tool_use"` - - `evaluated_permission: optional "allow" or "ask" or "deny"` AgentEvaluatedPermission enum
from line 642
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 }` + - `BetaManagedAgentsAgentToolResultEvent object` Event representing the result of an agent tool execution.
from line 654
A timestamp in RFC 3339 format + format: date-time + - `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 }` + - `BetaManagedAgentsTextBlock object` Regular text content. - - `BetaManagedAgentsImageBlock object { source, type }` + - `BetaManagedAgentsImageBlock object` Image content specified directly as base64 data or as a reference via a URL. - - `BetaManagedAgentsDocumentBlock object { source, type, context, title }` + - `BetaManagedAgentsDocumentBlock object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - - `BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }` + - `BetaManagedAgentsSearchResultBlock object` A block containing a web search result.
from line 686
Whether the tool execution resulted in an error. - - `BetaManagedAgentsAgentThreadMessageReceivedEvent object { id, content, from_session_thread_id, 3 more }` + - `BetaManagedAgentsAgentThreadMessageReceivedEvent object` Delivery event written to the target thread's input stream when an agent-to-agent message arrives.
from line 698
Message content blocks. - - `BetaManagedAgentsTextBlock object { text, type }` + - `BetaManagedAgentsTextBlock object` Regular text content. - - `BetaManagedAgentsImageBlock object { source, type }` + - `BetaManagedAgentsImageBlock object` Image content specified directly as base64 data or as a reference via a URL. - - `BetaManagedAgentsDocumentBlock object { source, type, context, title }` + - `BetaManagedAgentsDocumentBlock object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - - `BetaManagedAgentsRedactedBlock object { type }` + - `BetaManagedAgentsRedactedBlock object` Placeholder for content withheld by Anthropic model policy.
from line 722
A timestamp in RFC 3339 format + format: date-time + - `type: "agent.thread_message_received"` - - `"agent.thread_message_received"` - - `from_agent_name: optional string or null` Name of the callable agent this message came from. Absent when received from the primary agent. - - `BetaManagedAgentsAgentThreadMessageSentEvent object { id, content, processed_at, 3 more }` + - `BetaManagedAgentsAgentThreadMessageSentEvent object` Observability event emitted to the sender's output stream when an agent-to-agent message is sent.
from line 742
Message content blocks. - - `BetaManagedAgentsTextBlock object { text, type }` + - `BetaManagedAgentsTextBlock object` Regular text content. - - `BetaManagedAgentsImageBlock object { source, type }` + - `BetaManagedAgentsImageBlock object` Image content specified directly as base64 data or as a reference via a URL. - - `BetaManagedAgentsDocumentBlock object { source, type, context, title }` + - `BetaManagedAgentsDocumentBlock object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - - `BetaManagedAgentsRedactedBlock object { type }` + - `BetaManagedAgentsRedactedBlock object` Placeholder for content withheld by Anthropic model policy.
from line 762
A timestamp in RFC 3339 format + format: date-time + - `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 or null` Name of the callable agent this message was sent to. Absent when sent to the primary agent. - - `BetaManagedAgentsAgentThreadContextCompactedEvent object { id, processed_at, type }` + - `BetaManagedAgentsAgentThreadContextCompactedEvent object` Indicates that context compaction (summarization) occurred during the session.
from line 786
A timestamp in RFC 3339 format + format: date-time + - `type: "agent.thread_context_compacted"` - - `"agent.thread_context_compacted"` - - - `BetaManagedAgentsSessionErrorEvent object { id, error, processed_at, type }` + - `BetaManagedAgentsSessionErrorEvent object` An error event indicating a problem occurred during session execution.
from line 802
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 }` + - `BetaManagedAgentsUnknownError object` 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.
from line 814
What the client should do next in response to this error. - - `BetaManagedAgentsRetryStatusRetrying object { type }` + - `BetaManagedAgentsRetryStatusRetrying object` 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 }` + - `BetaManagedAgentsRetryStatusExhausted object` 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 }` + - `BetaManagedAgentsRetryStatusTerminal object` 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 }` + - `BetaManagedAgentsModelOverloadedError object` The model is currently overloaded. Emitted after automatic retries are exhausted.
from line 846
What the client should do next in response to this error. - - `BetaManagedAgentsRetryStatusRetrying object { type }` + - `BetaManagedAgentsRetryStatusRetrying object` 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 }` + - `BetaManagedAgentsRetryStatusExhausted object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - - `BetaManagedAgentsRetryStatusTerminal object { type }` + - `BetaManagedAgentsRetryStatusTerminal object` 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 }` + - `BetaManagedAgentsModelRateLimitedError object` The model request was rate-limited.
from line 872
What the client should do next in response to this error. - - `BetaManagedAgentsRetryStatusRetrying object { type }` + - `BetaManagedAgentsRetryStatusRetrying object` 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 }` + - `BetaManagedAgentsRetryStatusExhausted object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - - `BetaManagedAgentsRetryStatusTerminal object { type }` + - `BetaManagedAgentsRetryStatusTerminal object` 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 }` + - `BetaManagedAgentsModelRequestFailedError object` A model request failed for a reason other than overload or rate-limiting.
from line 898
What the client should do next in response to this error. - - `BetaManagedAgentsRetryStatusRetrying object { type }` + - `BetaManagedAgentsRetryStatusRetrying object` 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 }` + - `BetaManagedAgentsRetryStatusExhausted object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - - `BetaManagedAgentsRetryStatusTerminal object { type }` + - `BetaManagedAgentsRetryStatusTerminal object` 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 }` + - `BetaManagedAgentsMCPConnectionFailedError object` Failed to connect to an MCP server.
from line 928
What the client should do next in response to this error. - - `BetaManagedAgentsRetryStatusRetrying object { type }` + - `BetaManagedAgentsRetryStatusRetrying object` 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 }` + - `BetaManagedAgentsRetryStatusExhausted object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - - `BetaManagedAgentsRetryStatusTerminal object { type }` + - `BetaManagedAgentsRetryStatusTerminal object` 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 }` + - `BetaManagedAgentsMCPAuthenticationFailedError object` Authentication to an MCP server failed.
from line 958
What the client should do next in response to this error. - - `BetaManagedAgentsRetryStatusRetrying object { type }` + - `BetaManagedAgentsRetryStatusRetrying object` 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 }` + - `BetaManagedAgentsRetryStatusExhausted object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - - `BetaManagedAgentsRetryStatusTerminal object { type }` + - `BetaManagedAgentsRetryStatusTerminal object` 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 }` + - `BetaManagedAgentsBillingError object` 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.
from line 984
What the client should do next in response to this error. - - `BetaManagedAgentsRetryStatusRetrying object { type }` + - `BetaManagedAgentsRetryStatusRetrying object` 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 }` + - `BetaManagedAgentsRetryStatusExhausted object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - - `BetaManagedAgentsRetryStatusTerminal object { type }` + - `BetaManagedAgentsRetryStatusTerminal object` The session encountered a terminal error and will transition to `terminated` state. - `type: "billing_error"` - - `"billing_error"` - - - `BetaManagedAgentsCredentialHostUnreachableError object { credential_id, message, retry_status, 2 more }` + - `BetaManagedAgentsCredentialHostUnreachableError object` An `environment_variable` credential's `auth.networking.allowed_hosts` includes a host the environment's network policy does not permit.
from line 1014
What the client should do next in response to this error. - - `BetaManagedAgentsRetryStatusRetrying object { type }` + - `BetaManagedAgentsRetryStatusRetrying object` 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 }` + - `BetaManagedAgentsRetryStatusExhausted object` This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt. - - `BetaManagedAgentsRetryStatusTerminal object { type }` + - `BetaManagedAgentsRetryStatusTerminal object` The session encountered a terminal error and will transition to `terminated` state. - `type: "credential_host_unreachable_error"` - - `"credential_host_unreachable_error"` - - `vault_id: string` ID of the vault containing the affected credential.
from line 1036
A timestamp in RFC 3339 format + format: date-time + - `type: "session.error"` - - `"session.error"` - - - `BetaManagedAgentsSessionStatusRescheduledEvent object { id, processed_at, type }` + - `BetaManagedAgentsSessionStatusRescheduledEvent object` Indicates the session is recovering from an error state and is rescheduled for execution.
from line 1052
A timestamp in RFC 3339 format + format: date-time + - `type: "session.status_rescheduled"` - - `"session.status_rescheduled"` - - - `BetaManagedAgentsSessionStatusRunningEvent object { id, processed_at, type }` + - `BetaManagedAgentsSessionStatusRunningEvent object` Indicates the session is actively running and the agent is working.
from line 1068
A timestamp in RFC 3339 format + format: date-time + - `type: "session.status_running"` - - `"session.status_running"` - - - `BetaManagedAgentsSessionStatusIdleEvent object { id, processed_at, stop_reason, type }` + - `BetaManagedAgentsSessionStatusIdleEvent object` Indicates the agent has paused and is awaiting user input.
from line 1084
A timestamp in RFC 3339 format + format: date-time + - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or BetaManagedAgentsSessionBudgetReached` The agent completed its turn naturally and is ready for the next user message. - - `BetaManagedAgentsSessionEndTurn object { type }` + - `BetaManagedAgentsSessionEndTurn object` The agent completed its turn naturally and is ready for the next user message. - `type: "end_turn"` - - `"end_turn"` - - - `BetaManagedAgentsSessionRequiresAction object { event_ids, type }` + - `BetaManagedAgentsSessionRequiresAction object` 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.
from line 1106
- `type: "requires_action"` - - `"requires_action"` - - - `BetaManagedAgentsSessionRetriesExhausted object { type }` + - `BetaManagedAgentsSessionRetriesExhausted object` The turn ended because repeated errors exhausted the retry budget or an error escalated to `retry_status: 'exhausted'`. - `type: "retries_exhausted"` - - `"retries_exhausted"` - - - `BetaManagedAgentsSessionBudgetReached object { type }` + - `BetaManagedAgentsSessionBudgetReached object` The agent stopped because the session's tracked list cost reached its budget, or because its usage includes a model with no list price (which the budget cannot measure). Raise the budget to continue — or, if raising is rejected because a model has no list price, remove the budget. - `type: "budget_reached"` - - `"budget_reached"` - - `type: "session.status_idle"` - - `"session.status_idle"` - - - `BetaManagedAgentsSessionStatusTerminatedEvent object { id, processed_at, type }` + - `BetaManagedAgentsSessionStatusTerminatedEvent object` Indicates the session has terminated, either due to an error or completion.
from line 1132
A timestamp in RFC 3339 format + format: date-time + - `type: "session.status_terminated"` - - `"session.status_terminated"` - - - `BetaManagedAgentsSessionThreadCreatedEvent object { id, agent_name, processed_at, 2 more }` + - `BetaManagedAgentsSessionThreadCreatedEvent object` 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.
from line 1152
A timestamp in RFC 3339 format + format: date-time + - `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 }` + - `BetaManagedAgentsSpanOutcomeEvaluationStartEvent object` Emitted when an outcome evaluation cycle begins.
from line 1172
0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc. + format: int32 + - `outcome_id: string` The `outc_` ID of the outcome being evaluated.
from line 1182
A timestamp in RFC 3339 format + format: date-time + - `type: "span.outcome_evaluation_start"` - - `"span.outcome_evaluation_start"` - - - `BetaManagedAgentsSpanOutcomeEvaluationEndEvent object { id, explanation, iteration, 6 more }` + - `BetaManagedAgentsSpanOutcomeEvaluationEndEvent object` 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.
from line 1202
0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`. + format: int32 + - `outcome_evaluation_start_id: string` The id of the corresponding `span.outcome_evaluation_start` event.
from line 1216
A timestamp in RFC 3339 format + format: date-time + - `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.
from line 1232
Tokens used to create prompt cache in this request. + format: int32 + - `cache_read_input_tokens: number` Tokens read from prompt cache in this request. + format: int32 + - `input_tokens: number` Input tokens consumed by this request. + format: int32 + - `output_tokens: number` Output tokens generated by this request. + format: int32 + - `speed: optional "standard" or "fast" or null` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time.
from line 1260
- `"fast"` - - `BetaManagedAgentsSpanModelRequestStartEvent object { id, processed_at, type }` + - `BetaManagedAgentsSpanModelRequestStartEvent object` Emitted when a model request is initiated by the agent.
from line 1272
A timestamp in RFC 3339 format + format: date-time + - `type: "span.model_request_start"` - - `"span.model_request_start"` - - - `BetaManagedAgentsSpanModelRequestEndEvent object { id, is_error, model_request_start_id, 3 more }` + - `BetaManagedAgentsSpanModelRequestEndEvent object` Emitted when a model request completes.
from line 1300
A timestamp in RFC 3339 format + format: date-time + - `type: "span.model_request_end"` - - `"span.model_request_end"` - - - `BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent object { id, iteration, outcome_id, 2 more }` + - `BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent object` 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.
from line 1316
0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`. + format: int32 + - `outcome_id: string` The `outc_` ID of the outcome being evaluated.
from line 1326
A timestamp in RFC 3339 format + format: date-time + - `type: "span.outcome_evaluation_ongoing"` - - `"span.outcome_evaluation_ongoing"` - - - `BetaManagedAgentsUserDefineOutcomeEvent object { id, description, max_iterations, 4 more }` + - `BetaManagedAgentsUserDefineOutcomeEvent object` Echo of a `user.define_outcome` input event. Carries the server-generated `outcome_id` that subsequent `span.outcome_evaluation_*` events reference.
from line 1346
Evaluate-then-revise cycles before giving up. Default 3, max 20. + format: int32 + - `outcome_id: string` Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list.
from line 1356
A timestamp in RFC 3339 format + format: date-time + - `rubric: BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric` Rubric for grading the quality of an outcome. - - `BetaManagedAgentsFileRubric object { file_id, type }` + - `BetaManagedAgentsFileRubric object` Rubric referenced by a file uploaded via the Files API.
from line 1372
- `type: "file"` - - `"file"` - - - `BetaManagedAgentsTextRubric object { content, type }` + - `BetaManagedAgentsTextRubric object` Rubric content provided inline as text.
from line 1382
- `type: "text"` - - `"text"` - - `type: "user.define_outcome"` - - `"user.define_outcome"` - - - `BetaManagedAgentsSessionDeletedEvent object { id, processed_at, type }` + - `BetaManagedAgentsSessionDeletedEvent object` Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session.
from line 1396
A timestamp in RFC 3339 format + format: date-time + - `type: "session.deleted"` - - `"session.deleted"` - - - `BetaManagedAgentsSessionThreadStatusRunningEvent object { id, agent_name, processed_at, 2 more }` + - `BetaManagedAgentsSessionThreadStatusRunningEvent object` A session thread has begun executing. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.
from line 1416
A timestamp in RFC 3339 format + format: date-time + - `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 }` + - `BetaManagedAgentsSessionThreadStatusIdleEvent object` 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.
from line 1440
A timestamp in RFC 3339 format + format: date-time + - `session_thread_id: string` Public sthr_ ID of the thread that went idle.
from line 1450
The agent completed its turn naturally and is ready for the next user message. - - `BetaManagedAgentsSessionEndTurn object { type }` + - `BetaManagedAgentsSessionEndTurn object` The agent completed its turn naturally and is ready for the next user message. - - `BetaManagedAgentsSessionRequiresAction object { event_ids, type }` + - `BetaManagedAgentsSessionRequiresAction object` 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 }` + - `BetaManagedAgentsSessionRetriesExhausted object` The turn ended because repeated errors exhausted the retry budget or an error escalated to `retry_status: 'exhausted'`. - - `BetaManagedAgentsSessionBudgetReached object { type }` + - `BetaManagedAgentsSessionBudgetReached object` The agent stopped because the session's tracked list cost reached its budget, or because its usage includes a model with no list price (which the budget cannot measure). Raise the budget to continue — or, if raising is rejected because a model has no list price, remove the budget. - `type: "session.thread_status_idle"` - - `"session.thread_status_idle"` - - - `BetaManagedAgentsSessionThreadStatusTerminatedEvent object { id, agent_name, processed_at, 2 more }` + - `BetaManagedAgentsSessionThreadStatusTerminatedEvent object` 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.
from line 1484
A timestamp in RFC 3339 format + format: date-time + - `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 }` + - `BetaManagedAgentsUserToolResultEvent object` 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.
from line 1506
- `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 }` + - `BetaManagedAgentsTextBlock object` Regular text content. - - `BetaManagedAgentsImageBlock object { source, type }` + - `BetaManagedAgentsImageBlock object` Image content specified directly as base64 data or as a reference via a URL. - - `BetaManagedAgentsDocumentBlock object { source, type, context, title }` + - `BetaManagedAgentsDocumentBlock object` Document content, either specified directly as base64 data, as text, or as a reference via a URL. - - `BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }` + - `BetaManagedAgentsSearchResultBlock object` A block containing a web search result.
from line 1534
A timestamp in RFC 3339 format + format: date-time + - `session_thread_id: optional string or null` 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 }` + - `BetaManagedAgentsSessionThreadStatusRescheduledEvent object` 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.
from line 1556
A timestamp in RFC 3339 format + format: date-time + - `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, 4 more }` + - `BetaManagedAgentsSessionUpdatedEvent object` 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.
from line 1576
A timestamp in RFC 3339 format + format: date-time + - `type: "session.updated"` - - `"session.updated"` - - `agent: optional BetaManagedAgentsSessionAgent or null` Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time.
from line 1594
- `type: "url"` - - `"url"` - - `url: string` - `model: BetaManagedAgentsModelConfig`
from line 1670
How hard Claude works on each turn. Sets `output_config.effort` on every Messages call the session makes. - - `BetaManagedAgentsEffortLow object { type }` + - `BetaManagedAgentsEffortLow object` Low effort. Favors latency over reasoning depth. - `type: "low"` - - `"low"` - - - `BetaManagedAgentsEffortMedium object { type }` + - `BetaManagedAgentsEffortMedium object` Medium effort. Balances latency and reasoning depth. - `type: "medium"` - - `"medium"` - - - `BetaManagedAgentsEffortHigh object { type }` + - `BetaManagedAgentsEffortHigh object` High effort. Favors reasoning depth. - `type: "high"` - - `"high"` - - - `BetaManagedAgentsEffortXhigh object { type }` + - `BetaManagedAgentsEffortXhigh object` Extra-high effort. Not all models accept this level. - `type: "xhigh"` - - `"xhigh"` - - - `BetaManagedAgentsEffortMax object { type }` + - `BetaManagedAgentsEffortMax object` Maximum effort. Favors reasoning depth over latency. - `type: "max"` - - `"max"` - - `inference_geo: optional string` Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.
from line 1720
Full `agent` definitions the coordinator may spawn as session threads. - - `BetaManagedAgentsSessionThreadAgent object { id, description, mcp_servers, 7 more }` + - `BetaManagedAgentsSessionThreadAgent object` 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`.
from line 1744
- `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - - `BetaManagedAgentsAnthropicSkill object { skill_id, type, version }` + - `BetaManagedAgentsAnthropicSkill object` A resolved Anthropic-managed skill.
from line 1752
- `type: "anthropic"` - - `"anthropic"` - - `version: string` - - `BetaManagedAgentsCustomSkill object { skill_id, type, version }` + - `BetaManagedAgentsCustomSkill object` A resolved user-created custom skill.
from line 1762
- `type: "custom"` - - `"custom"` - - `version: string` - `system: string or null` - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool` - - `BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }` + - `BetaManagedAgentsAgentToolset20260401 object` - `configs: array of BetaManagedAgentsAgentToolConfig` - - `BetaManagedAgentsBashToolConfig object { enabled, name, permission_policy, type }` + - `BetaManagedAgentsBashToolConfig object` Configuration for the bash tool.
from line 1780
- `name: "bash"` - - `"bash"` - - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - - `BetaManagedAgentsAlwaysAllowPolicy object { type }` + - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - `type: "always_allow"` - - `"always_allow"` - - - `BetaManagedAgentsAlwaysAskPolicy object { type }` + - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `type: "always_ask"` - - `"always_ask"` - - `type: "bash"` - - `"bash"` - - - `BetaManagedAgentsEditToolConfig object { enabled, name, permission_policy, type }` + - `BetaManagedAgentsEditToolConfig object` Configuration for the edit tool.
from line 1806
- `name: "edit"` - - `"edit"` - - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - - `BetaManagedAgentsAlwaysAllowPolicy object { type }` + - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - - `BetaManagedAgentsAlwaysAskPolicy object { type }` + - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `type: "edit"` - - `"edit"` - - - `BetaManagedAgentsReadToolConfig object { enabled, name, permission_policy, type }` + - `BetaManagedAgentsReadToolConfig object` Configuration for the read tool.
from line 1828
- `name: "read"` - - `"read"` - - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - - `BetaManagedAgentsAlwaysAllowPolicy object { type }` + - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - - `BetaManagedAgentsAlwaysAskPolicy object { type }` + - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `type: "read"` - - `"read"` - - - `BetaManagedAgentsWriteToolConfig object { enabled, name, permission_policy, type }` + - `BetaManagedAgentsWriteToolConfig object` Configuration for the write tool.
from line 1850
- `name: "write"` - - `"write"` - - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - - `BetaManagedAgentsAlwaysAllowPolicy object { type }` + - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - - `BetaManagedAgentsAlwaysAskPolicy object { type }` + - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `type: "write"` - - `"write"` - - - `BetaManagedAgentsGlobToolConfig object { enabled, name, permission_policy, type }` + - `BetaManagedAgentsGlobToolConfig object` Configuration for the glob tool.
from line 1872
- `name: "glob"` - - `"glob"` - - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - - `BetaManagedAgentsAlwaysAllowPolicy object { type }` + - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - - `BetaManagedAgentsAlwaysAskPolicy object { type }` + - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `type: "glob"` - - `"glob"` - - - `BetaManagedAgentsGrepToolConfig object { enabled, name, permission_policy, type }` + - `BetaManagedAgentsGrepToolConfig object` Configuration for the grep tool.
from line 1894
- `name: "grep"` - - `"grep"` - - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - - `BetaManagedAgentsAlwaysAllowPolicy object { type }` + - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - - `BetaManagedAgentsAlwaysAskPolicy object { type }` + - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `type: "grep"` - - `"grep"` - - - `BetaManagedAgentsWebFetchToolConfig object { enabled, name, permission_policy, 4 more }` + - `BetaManagedAgentsWebFetchToolConfig object` Configuration for the web_fetch tool.
from line 1916
- `name: "web_fetch"` - - `"web_fetch"` - - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - - `BetaManagedAgentsAlwaysAllowPolicy object { type }` + - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - - `BetaManagedAgentsAlwaysAskPolicy object { type }` + - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `type: "web_fetch"` - - `"web_fetch"` - - `allowed_domains: optional array of string` - `blocked_domains: optional array of string` - `max_content_tokens: optional number or null` - - `BetaManagedAgentsWebSearchToolConfig object { enabled, name, permission_policy, 4 more }` + format: int32 + + - `BetaManagedAgentsWebSearchToolConfig object` Configuration for the web_search tool.
from line 1946
- `name: "web_search"` - - `"web_search"` - - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` Permission policy for tool execution. - - `BetaManagedAgentsAlwaysAllowPolicy object { type }` + - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - - `BetaManagedAgentsAlwaysAskPolicy object { type }` + - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `type: "web_search"` - - `"web_search"` - - `allowed_domains: optional array of string` - `blocked_domains: optional array of string`
from line 1972
Location precision. Only "approximate" is supported. - - `"approximate"` - - `city: optional string or null` City name. + minLength: 1, maxLength: 255 + - `country: optional string or null` Two-letter ISO 3166-1 country code, uppercase.
from line 1986
Region or state name. + minLength: 1, maxLength: 255 + - `timezone: optional string or null` IANA timezone identifier, e.g. "America/Los_Angeles". + minLength: 1, maxLength: 255 + - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` Resolved default configuration for agent tools.
from line 2004
Permission policy for tool execution. - - `BetaManagedAgentsAlwaysAllowPolicy object { type }` + - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - - `BetaManagedAgentsAlwaysAskPolicy object { type }` + - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution. - `type: "agent_toolset_20260401"` - - `"agent_toolset_20260401"` - - - `BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }` + - `BetaManagedAgentsMCPToolset object` - `configs: array of BetaManagedAgentsMCPToolConfig`
from line 2026
Permission policy for tool execution. - - `BetaManagedAgentsAlwaysAllowPolicy object { type }` + - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - - `BetaManagedAgentsAlwaysAskPolicy object { type }` + - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution.
from line 2044
Permission policy for tool execution. - - `BetaManagedAgentsAlwaysAllowPolicy object { type }` + - `BetaManagedAgentsAlwaysAllowPolicy object` Tool calls are automatically approved without user confirmation. - - `BetaManagedAgentsAlwaysAskPolicy object { type }` + - `BetaManagedAgentsAlwaysAskPolicy object` Tool calls require user confirmation before execution.
from line 2056
- `type: "mcp_toolset"` - - `"mcp_toolset"` - - - `BetaManagedAgentsCustomTool object { description, input_schema, name, type }` + - `BetaManagedAgentsCustomTool object` A custom tool as returned in API responses.
from line 2068
- `type: "object"` - - `"object"` - - `properties: optional map[unknown] or null` - `required: optional array of string or null`
from line 2076
- `type: "custom"` - - `"custom"` - - `type: "agent"` - - `"agent"` - - `version: number` - - `BetaManagedAgentsAdvisor object { model, type }` + format: int32 + + - `BetaManagedAgentsAdvisor object` Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
from line 2092
- `type: "advisor"` - - `"advisor"` - - `type: "coordinator"` - - `"coordinator"` - - `name: string` - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill` - - `BetaManagedAgentsAnthropicSkill object { skill_id, type, version }` + - `BetaManagedAgentsAnthropicSkill object` A resolved Anthropic-managed skill. - - `BetaManagedAgentsCustomSkill object { skill_id, type, version }` + - `BetaManagedAgentsCustomSkill object` A resolved user-created custom skill.
from line 2110
- `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 }` + - `BetaManagedAgentsAgentToolset20260401 object` + + - `BetaManagedAgentsMCPToolset object` + + - `BetaManagedAgentsCustomTool object` A custom tool as returned in API responses. - `type: "agent"` - - `"agent"` - - `version: number` + format: int32 + - `budget: optional BetaManagedAgentsBudgetLimit or null` A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.
from line 2140
Uppercase ISO-4217 currency code. `USD` is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced. - - `"USD"` - - `type: "limit"` - - `"limit"` - - `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.
from line 2150
The session's new title. Present only when the update changed it. - - `BetaManagedAgentsSystemMessageEvent object { id, content, type, processed_at }` + - `BetaManagedAgentsSystemMessageEvent object` A mid-conversation system message event. Carries system-role content that is appended to the session as a `role: "system"` turn.
from line 2166
The text content. + minLength: 1 + - `type: "text"` - - `"text"` - - `type: "system.message"` - - `"system.message"` - - `processed_at: optional string or null` A timestamp in RFC 3339 format - - `BetaManagedAgentsSessionUsageEvent object { id, processed_at, type, 2 more }` + format: date-time + + - `BetaManagedAgentsSessionUsageEvent object` Periodic snapshot of the session's cumulative usage and tracked list cost.
from line 2190
A timestamp in RFC 3339 format + format: date-time + - `type: "session.usage"` - - `"session.usage"` - - `usage: BetaManagedAgentsSessionUsageSnapshot` Point-in-time snapshot of a session's cumulative usage.
from line 2202
Cumulative time in seconds during which the session had at least one thread in running status. Overlapping activity from concurrent threads is counted once. This is the duration the session's runtime cost is priced on. + format: double + - `cache_creation: optional BetaManagedAgentsCacheCreationUsage` Prompt-cache creation token usage broken down by cache lifetime.
from line 2212
Tokens used to create 1-hour ephemeral cache entries. + format: int32 + - `ephemeral_5m_input_tokens: optional number` Tokens used to create 5-minute ephemeral cache entries. + format: int32 + - `cache_read_input_tokens: optional number` Total tokens read from prompt cache. + format: int32 + - `input_tokens: optional number` Total input tokens consumed across all turns. + format: int32 + - `list_cost: optional BetaMonetaryAmount` A monetary amount in a specific currency.
from line 2240
Total output tokens generated across all turns. + format: int32 + - `server_tool_use: optional BetaManagedAgentsServerToolUsage` Cumulative count of server-executed tool invocations, broken down by tool.
from line 2250
Number of server-executed web fetch requests. + format: int32 + - `web_search_requests: optional number` Number of server-executed web search requests. + format: int32 + - `budget: optional BetaManagedAgentsBudgetLimit or null` A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.
from line 2266
Opaque cursor for the next page. Null when no more results. -### Example - -```http +## Example + +```bash 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 +### Response (200) ```json {
api/beta/sessions/events/list Changed · +251 / -41 lines
from line 1801
- `configs: array of BetaManagedAgentsAgentToolConfig` - - `enabled: boolean` + - `BetaManagedAgentsBashToolConfig object { enabled, name, permission_policy, type }` - - `name: "bash" or "edit" or "read" or 5 more` + Configuration for the bash tool. - Built-in agent tool identifier. + - `enabled: boolean` - - `"bash"` + - `name: "bash"` - - `"edit"` + - `"bash"` - - `"read"` + - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` - - `"write"` + Permission policy for tool execution. - - `"glob"` + - `BetaManagedAgentsAlwaysAllowPolicy object { type }` - - `"grep"` + Tool calls are automatically approved without user confirmation. - - `"web_fetch"` + - `type: "always_allow"` - - `"web_search"` + - `"always_allow"` - - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy` + - `BetaManagedAgentsAlwaysAskPolicy object { type }` - Permission policy for tool execution. + Tool calls require user confirmation before execution. - - `BetaManagedAgentsAlwaysAllowPolicy object { type }` + - `type: "always_ask"` - Tool calls are automatically approved without user confirmation. + - `"always_ask"` - - `type: "always_allow"` + - `type: "bash"` - - `"always_allow"` + - `"bash"` - - `BetaManagedAgentsAlwaysAskPolicy object { type }` + - `BetaManagedAgentsEditToolConfig object { enabled, name, permission_policy, type }` - Tool calls require user confirmation before execution. + Configuration for the edit tool. - - `type: "always_ask"` + - `enabled: boolean` - - `"always_ask"` + - `name: "edit"` + + - `"edit"` + + - `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: "edit"` + + - `"edit"` + + - `BetaManagedAgentsReadToolConfig object { enabled, name, permission_policy, type }` + + Configuration for the read tool. + + - `enabled: boolean` + + - `name: "read"` + + - `"read"` + + - `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: "read"` + + - `"read"` + + - `BetaManagedAgentsWriteToolConfig object { enabled, name, permission_policy, type }` + + Configuration for the write tool. + + - `enabled: boolean` + + - `name: "write"` + + - `"write"` + + - `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: "write"` + + - `"write"` + + - `BetaManagedAgentsGlobToolConfig object { enabled, name, permission_policy, type }` + + Configuration for the glob tool. + + - `enabled: boolean` + + - `name: "glob"` + + - `"glob"` + + - `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: "glob"` + + - `"glob"` + + - `BetaManagedAgentsGrepToolConfig object { enabled, name, permission_policy, type }` + + Configuration for the grep tool. + + - `enabled: boolean` + + - `name: "grep"` + + - `"grep"` + + - `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: "grep"` + + - `"grep"` + + - `BetaManagedAgentsWebFetchToolConfig object { enabled, name, permission_policy, 4 more }` + + Configuration for the web_fetch tool. + + - `enabled: boolean` + + - `name: "web_fetch"` + + - `"web_fetch"` + + - `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: "web_fetch"` + + - `"web_fetch"` + + - `allowed_domains: optional array of string` + + - `blocked_domains: optional array of string` + + - `max_content_tokens: optional number or null` + + - `BetaManagedAgentsWebSearchToolConfig object { enabled, name, permission_policy, 4 more }` + + Configuration for the web_search tool. + + - `enabled: boolean` + + - `name: "web_search"` + + - `"web_search"` + + - `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: "web_search"` + + - `"web_search"` + + - `allowed_domains: optional array of string` + + - `blocked_domains: optional array of string` + + - `user_location: optional BetaManagedAgentsUserLocation or null` + + Approximate user location for search result localization. + + - `type: "approximate"` + + Location precision. Only "approximate" is supported. + + - `"approximate"` + + - `city: optional string or null` + + City name. + + - `country: optional string or null` + + Two-letter ISO 3166-1 country code, uppercase. + + - `region: optional string or null` + + Region or state name. + + - `timezone: optional string or null` + + IANA timezone identifier, e.g. "America/Los_Angeles". - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig`
api/beta/sessions/events/list Changed · +3 / -1 lines
from line 59
- `string` - - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 30 more` + - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 31 more` - `"message-batches-2024-09-24"`
from line 104
- `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` + + - `"user-profiles-2026-08-18"` - `"advisor-tool-2026-03-01"`
api/beta/sessions/events/list First recorded · 2155 lines, first recorded
## List Events ### Path Parameters ### Query Parameters ### Header Parameters ### Returns ### Example #### Response
The first capture of this source. The page was already there, and this is what it said.
---
title: List Events
url: https://platform.claude.com/docs/en/api/beta/sessions/events/list
---
## 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). Compared against the event's `processed_at` value.
- `"created_at[gte]": optional string`
Return events created at or after this time (inclusive). Compared against the event's `processed_at` value.
- `"created_at[lt]": optional string`
Return events created before this time (exclusive). Compared against the event's `processed_at` value.
- `"created_at[lte]": optional string`
Return events created at or before this time (inclusive). Compared against the event's `processed_at` value.
- `limit: optional number`
Query parameter for limit
- `order: optional "asc" or "desc"`
Sort direction for results, ordered by the event's `processed_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 30 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"`
- `"dreaming-2026-04-21"`
- `"thinking-token-count-2026-05-13"`
- `"server-side-fallback-2026-06-01"`
- `"server-side-fallback-2026-07-01"`
- `"fallback-credit-2026-06-01"`
- `"fallback-credit-2026-07-01"`
- `"agent-memory-2026-07-22"`
- `"mid-conversation-tool-changes-2026-07-01"`
### Returns
- `data: optional array of BetaManagedAgentsSessionEvent`
Events for the session, ordered by `processed_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 or BetaManagedAgentsRedactedBlock`
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 or null`
Additional context about the document for the model.
- `title: optional string or null`
The title of the document.
- `BetaManagedAgentsRedactedBlock object { type }`
Placeholder for content withheld by Anthropic model policy.
- `type: "redacted"`
- `"redacted"`
- `type: "user.message"`
- `"user.message"`
Cut at 300 lines.