Events

List Events

beta.sessions.events.list(session_id, **kwargs) -> PageCursor<BetaManagedAgentsSessionEvent>

GET/v1/sessions/{session_id}/events

Send Events

beta.sessions.events.send_(session_id, **kwargs) -> BetaManagedAgentsSendSessionEvents

POST/v1/sessions/{session_id}/events

Stream Events

beta.sessions.events.stream(session_id, **kwargs) -> BetaManagedAgentsStreamSessionEvents

GET/v1/sessions/{session_id}/events/stream

Models

class BetaManagedAgentsAgentCustomToolUseEvent { 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: Hash[Symbol, untyped]

Input parameters for the tool call.

name: String

Name of the custom tool being called.

processed_at: Time

A timestamp in RFC 3339 format

formatdate-time

type: :"agent.custom_tool_use"

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

class BetaManagedAgentsAgentMCPToolResultEvent { id, mcp_tool_use_id, processed_at, 3 more }

Event representing the result of an MCP tool execution.

class BetaManagedAgentsAgentMCPToolUseEvent { id, input, mcp_server_name, 5 more }

Event emitted when the agent invokes a tool provided by an MCP server.

class BetaManagedAgentsAgentMessageEvent { id, content, processed_at, type }

An agent response event in the session conversation.

class BetaManagedAgentsAgentThinkingEvent { 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: Time

A timestamp in RFC 3339 format

formatdate-time

type: :"agent.thinking"

class BetaManagedAgentsAgentThreadContextCompactedEvent { id, processed_at, type }

Indicates that context compaction (summarization) occurred during the session.

id: String

Unique identifier for this event.

processed_at: Time

A timestamp in RFC 3339 format

formatdate-time

type: :"agent.thread_context_compacted"

class BetaManagedAgentsAgentThreadMessageReceivedEvent { 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.

class BetaManagedAgentsAgentThreadMessageSentEvent { id, content, processed_at, 3 more }

Observability event emitted to the sender's output stream when an agent-to-agent message is sent.

class BetaManagedAgentsAgentToolResultEvent { id, processed_at, tool_use_id, 3 more }

Event representing the result of an agent tool execution.

class BetaManagedAgentsAgentToolUseEvent { id, input, name, 4 more }

Event emitted when the agent invokes a built-in agent tool.

id: String

Unique identifier for this event.

input: Hash[Symbol, untyped]

Input parameters for the tool call.

name: String

Name of the agent tool being used.

processed_at: Time

A timestamp in RFC 3339 format

formatdate-time

type: :"agent.tool_use"

evaluated_permission: :allow | :ask | :deny

AgentEvaluatedPermission enum

One of the following:

:allow

:ask

:deny

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

class BetaManagedAgentsBase64DocumentSource { data, media_type, type }

Base64-encoded document data.

data: String

Base64-encoded document data.

minLength1

media_type: String

MIME type of the document (e.g., "application/pdf").

minLength1

type: :base64

class BetaManagedAgentsBase64ImageSource { data, media_type, type }

Base64-encoded image data.

data: String

Base64-encoded image data.

minLength1

media_type: String

MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").

minLength1

type: :base64

class BetaManagedAgentsBillingError { 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.

class BetaManagedAgentsCredentialHostUnreachableError { credential_id, message, retry_status, 2 more }

An environment_variable credential's auth.networking.allowed_hosts includes a host the environment's network policy does not permit.

class BetaManagedAgentsDocumentBlock { source, type, context, title }

Document content, either specified directly as base64 data, as text, or as a reference via a URL.

BetaManagedAgentsEventParams = BetaManagedAgentsUserMessageEventParams { content, type } | BetaManagedAgentsUserInterruptEventParams { type, session_thread_id } | BetaManagedAgentsUserToolConfirmationEventParams { result, tool_use_id, type, deny_message } | 4 more

Union type for event parameters that can be sent to a session.

One of the following:

class BetaManagedAgentsFileDocumentSource { file_id, type }

Document referenced by file ID.

file_id: String

ID of a previously uploaded file.

minLength1

type: :file

class BetaManagedAgentsFileImageSource { file_id, type }

Image referenced by file ID.

file_id: String

ID of a previously uploaded file.

minLength1

type: :file

class BetaManagedAgentsFileRubric { file_id, type }

Rubric referenced by a file uploaded via the Files API.

file_id: String

ID of the rubric file.

type: :file

class BetaManagedAgentsFileRubricParams { file_id, type }

Rubric referenced by a file uploaded via the Files API.

file_id: String

ID of the rubric file.

type: :file

class BetaManagedAgentsImageBlock { source, type }

Image content specified directly as base64 data or as a reference via a URL.

class BetaManagedAgentsMCPAuthenticationFailedError { mcp_server_name, message, retry_status, type }

Authentication to an MCP server failed.

class BetaManagedAgentsMCPConnectionFailedError { mcp_server_name, message, retry_status, type }

Failed to connect to an MCP server.

class BetaManagedAgentsModelOverloadedError { message, retry_status, type }

The model is currently overloaded. Emitted after automatic retries are exhausted.

class BetaManagedAgentsModelRateLimitedError { message, retry_status, type }

The model request was rate-limited.

class BetaManagedAgentsModelRequestFailedError { message, retry_status, type }

A model request failed for a reason other than overload or rate-limiting.

class BetaManagedAgentsPlainTextDocumentSource { data, media_type, type }

Plain text document content.

data: String

The plain text content.

minLength1

media_type: :"text/plain"

MIME type of the text content. Must be "text/plain".

type: :text

class BetaManagedAgentsRedactedBlock { type }

Placeholder for content withheld by Anthropic model policy.

type: :redacted

class BetaManagedAgentsRetryStatusExhausted { type }

This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.

type: :exhausted

class BetaManagedAgentsRetryStatusRetrying { 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

class BetaManagedAgentsRetryStatusTerminal { type }

The session encountered a terminal error and will transition to terminated state.

type: :terminal

class BetaManagedAgentsSearchResultBlock { citations, content, source, 2 more }

A block containing a web search result.

citations: BetaManagedAgentsSearchResultCitations { enabled }

Citation settings for a search result.

enabled: bool

Whether citations are enabled for this search result.

content: Array[BetaManagedAgentsSearchResultContent { text, type }]

Array of text content blocks from the search result.

text: String

The text content.

minLength1

type: :text

source: String

The URL source of the search result.

minLength1

title: String

The title of the search result.

minLength1

type: :search_result

class BetaManagedAgentsSearchResultCitations { enabled }

Citation settings for a search result.

enabled: bool

Whether citations are enabled for this search result.

class BetaManagedAgentsSearchResultContent { text, type }

Text content within a search result.

text: String

The text content.

minLength1

type: :text

class BetaManagedAgentsSendSessionEvents { data }

Events that were successfully sent to the session.

class BetaManagedAgentsSessionBudgetReached { type }

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

class BetaManagedAgentsSessionDeletedEvent { 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: Time

A timestamp in RFC 3339 format

formatdate-time

type: :"session.deleted"

class BetaManagedAgentsSessionEndTurn { type }

The agent completed its turn naturally and is ready for the next user message.

type: :end_turn

class BetaManagedAgentsSessionErrorEvent { id, error, processed_at, type }

An error event indicating a problem occurred during session execution.

BetaManagedAgentsSessionEvent = BetaManagedAgentsUserMessageEvent { id, content, type, processed_at } | BetaManagedAgentsUserInterruptEvent { id, type, processed_at, session_thread_id } | BetaManagedAgentsUserToolConfirmationEvent { id, result, tool_use_id, 4 more } | 32 more

Union type for all event types in a session.

One of the following:

class BetaManagedAgentsSessionRequiresAction { 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[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

class BetaManagedAgentsSessionRetriesExhausted { type }

The turn ended because repeated errors exhausted the retry budget or an error escalated to retry_status: 'exhausted'.

type: :retries_exhausted

class BetaManagedAgentsSessionStatusIdleEvent { id, processed_at, stop_reason, type }

Indicates the agent has paused and is awaiting user input.

class BetaManagedAgentsSessionStatusRescheduledEvent { 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: Time

A timestamp in RFC 3339 format

formatdate-time

type: :"session.status_rescheduled"

class BetaManagedAgentsSessionStatusRunningEvent { id, processed_at, type }

Indicates the session is actively running and the agent is working.

id: String

Unique identifier for this event.

processed_at: Time

A timestamp in RFC 3339 format

formatdate-time

type: :"session.status_running"

class BetaManagedAgentsSessionStatusTerminatedEvent { 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: Time

A timestamp in RFC 3339 format

formatdate-time

type: :"session.status_terminated"

class BetaManagedAgentsSessionThreadCreatedEvent { 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: Time

A timestamp in RFC 3339 format

formatdate-time

session_thread_id: String

Public sthr_ ID of the newly created thread.

type: :"session.thread_created"

class BetaManagedAgentsSessionThreadStatusIdleEvent { 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.

class BetaManagedAgentsSessionThreadStatusRescheduledEvent { 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: Time

A timestamp in RFC 3339 format

formatdate-time

session_thread_id: String

Public sthr_ ID of the thread that is retrying.

type: :"session.thread_status_rescheduled"

class BetaManagedAgentsSessionThreadStatusRunningEvent { 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: Time

A timestamp in RFC 3339 format

formatdate-time

session_thread_id: String

Public sthr_ ID of the thread that started running.

type: :"session.thread_status_running"

class BetaManagedAgentsSessionThreadStatusTerminatedEvent { 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: Time

A timestamp in RFC 3339 format

formatdate-time

session_thread_id: String

Public sthr_ ID of the thread that terminated.

type: :"session.thread_status_terminated"

class BetaManagedAgentsSessionUsageSnapshot { active_seconds, cache_creation, cache_read_input_tokens, 4 more }

Point-in-time snapshot of a session's cumulative usage.

class BetaManagedAgentsSpanModelRequestEndEvent { id, is_error, model_request_start_id, 3 more }

Emitted when a model request completes.

class BetaManagedAgentsSpanModelRequestStartEvent { id, processed_at, type }

Emitted when a model request is initiated by the agent.

id: String

Unique identifier for this event.

processed_at: Time

A timestamp in RFC 3339 format

formatdate-time

type: :"span.model_request_start"

class BetaManagedAgentsSpanModelUsage { cache_creation_input_tokens, cache_read_input_tokens, input_tokens, 2 more }

Token usage for a single model request.

cache_creation_input_tokens: Integer

Tokens used to create prompt cache in this request.

formatint32

cache_read_input_tokens: Integer

Tokens read from prompt cache in this request.

formatint32

input_tokens: Integer

Input tokens consumed by this request.

formatint32

output_tokens: Integer

Output tokens generated by this request.

formatint32

speed: :standard | :fast

Inference speed mode. fast provides significantly faster output token generation at premium pricing. Not all models support fast; invalid combinations are rejected at create time.

One of the following:

:standard

:fast

class BetaManagedAgentsSpanOutcomeEvaluationEndEvent { 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.

class BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent { 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: Integer

0-indexed revision cycle, matching the corresponding span.outcome_evaluation_start.

formatint32

outcome_id: String

The outc_ ID of the outcome being evaluated.

processed_at: Time

A timestamp in RFC 3339 format

formatdate-time

type: :"span.outcome_evaluation_ongoing"

class BetaManagedAgentsSpanOutcomeEvaluationStartEvent { id, iteration, outcome_id, 2 more }

Emitted when an outcome evaluation cycle begins.

id: String

Unique identifier for this event.

iteration: Integer

0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc.

formatint32

outcome_id: String

The outc_ ID of the outcome being evaluated.

processed_at: Time

A timestamp in RFC 3339 format

formatdate-time

type: :"span.outcome_evaluation_start"

BetaManagedAgentsStreamSessionEvents = BetaManagedAgentsUserMessageEvent { id, content, type, processed_at } | BetaManagedAgentsUserInterruptEvent { id, type, processed_at, session_thread_id } | BetaManagedAgentsUserToolConfirmationEvent { id, result, tool_use_id, 4 more } | 34 more

Server-sent event in the session stream.

One of the following:

class BetaManagedAgentsSystemMessageEventParams { content, type }

Privileged context for the accompanying turn and all subsequent turns, appended to the session's system context as a role: "system" turn rather than replacing the top-level system prompt. At most one per request: it must be the final event and immediately follow the user.message, user.tool_result, or user.custom_tool_result it accompanies. Only supported on models that accept mid-conversation system messages.

content: Array[BetaManagedAgentsSystemContentBlock { text, type }]

System content blocks to append. Text-only.

text: String

The text content.

minLength1

type: :text

type: :"system.message"

class BetaManagedAgentsTextBlock { text, type }

Regular text content.

text: String

The text content.

minLength1

type: :text

class BetaManagedAgentsTextRubric { 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

class BetaManagedAgentsTextRubricParams { 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.

maxLength262144

type: :text

class BetaManagedAgentsUnknownError { 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.

class BetaManagedAgentsURLDocumentSource { type, url }

Document referenced by URL.

type: :url

url: String

URL of the document to fetch.

minLength1

class BetaManagedAgentsURLImageSource { type, url }

Image referenced by URL.

type: :url

url: String

URL of the image to fetch.

minLength1

class BetaManagedAgentsUserCustomToolResultEvent { id, custom_tool_use_id, type, 4 more }

Event sent by the client providing the result of a custom tool execution.

class BetaManagedAgentsUserCustomToolResultEventParams { custom_tool_use_id, type, content, is_error }

Parameters for providing the result of a custom tool execution.

class BetaManagedAgentsUserDefineOutcomeEvent { 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.

class BetaManagedAgentsUserDefineOutcomeEventParams { description, rubric, type, max_iterations }

Parameters for defining an outcome the agent should work toward. The agent begins work on receipt.

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

processed_at: Time

A timestamp in RFC 3339 format

formatdate-time

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

class BetaManagedAgentsUserInterruptEventParams { type, session_thread_id }

Parameters for sending an interrupt to pause the agent.

type: :"user.interrupt"

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

class BetaManagedAgentsUserMessageEvent { id, content, type, processed_at }

A user message event in the session conversation.

class BetaManagedAgentsUserMessageEventParams { content, type }

Parameters for sending a user message to the session.

class BetaManagedAgentsUserToolConfirmationEvent { 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 | :deny

UserToolConfirmationResult enum

One of the following:

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

deny_message: String

Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.

maxLength10000

processed_at: Time

A timestamp in RFC 3339 format

formatdate-time

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

class BetaManagedAgentsUserToolConfirmationEventParams { result, tool_use_id, type, deny_message }

Parameters for confirming or denying a tool execution request.

result: :allow | :deny

UserToolConfirmationResult enum

One of the following:

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

minLength1

maxLength128

type: :"user.tool_confirmation"

deny_message: String

Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.

maxLength10000

class BetaManagedAgentsUserToolResultEventParams { 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.