Claude Platform Docs

Stream Events

$ ant beta:sessions:events stream
GET/v1/sessions/{session_id}/events/stream

Stream Events

Parameters
--session-id: string

Path param: Path parameter session_id

--event-delta: optional array of BetaManagedAgentsDeltaType

Query param: When set, this connection also receives streaming deltas (event_start, event_delta) while an event is being produced, before the event itself arrives. Deltas are best-effort; when the final event is produced it carries the complete content. A model request that ends early (an error or interrupt) produces no final event — its terminal span.model_request_end closes the preview. Accepts one or more event types to preview and may be repeated: agent.message streams content_delta fragments; agent.thinking is start-only — a signal that the agent has begun extended thinking, concluded by the agent.thinking event itself. Only previews of the requested event types are sent.

--beta: optional array of AnthropicBeta

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

Returns
beta_managed_agents_stream_session_events: BetaManagedAgentsUserMessageEvent { id, content, type, processed_at } or BetaManagedAgentsUserInterruptEvent { id, type, processed_at, session_thread_id } or BetaManagedAgentsUserToolConfirmationEvent { id, result, tool_use_id, 4 more } or 34 more

Server-sent event in the session stream.

One of the following:
beta_managed_agents_user_message_event: 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 { text, type } or BetaManagedAgentsImageBlock { source, type } or BetaManagedAgentsDocumentBlock { source, type, context, title } or BetaManagedAgentsRedactedBlock { type }

Array of content blocks comprising the user message.

One of the following:
beta_managed_agents_text_block: object{ text, type }

Regular text content.

text: string

The text content.

minLength1
type: "text"
beta_managed_agents_image_block: object{ source, type }

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

beta_managed_agents_document_block: object{ source, type, context, title }

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

beta_managed_agents_redacted_block: object{ type }

Placeholder for content withheld by Anthropic model policy.

type: "redacted"
type: "user.message"
processed_at: optional string

A timestamp in RFC 3339 format

formatdate-time
beta_managed_agents_user_interrupt_event: object{ id, type, processed_at, session_thread_id }

An interrupt event that pauses agent execution and returns control to the user.

id: string

Unique identifier for this event.

type: "user.interrupt"
processed_at: optional string

A timestamp in RFC 3339 format

formatdate-time
session_thread_id: optional string

If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread.

beta_managed_agents_user_tool_confirmation_event: object{ id, result, tool_use_id, 4 more }

A tool confirmation event that approves or denies a pending tool execution.

id: string

Unique identifier for this event.

result: "allow" or "deny"

UserToolConfirmationResult enum

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

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

maxLength10000
processed_at: optional string

A timestamp in RFC 3339 format

formatdate-time
session_thread_id: optional string

When set, the confirmation routes to this subagent's thread rather than the primary. Echo this from the session_thread_id on the agent.tool_use or agent.mcp_tool_use event that prompted the approval.

beta_managed_agents_user_custom_tool_result_event: object{ id, custom_tool_use_id, type, 4 more }

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

id: string

Unique identifier for this event.

custom_tool_use_id: string

The id of the agent.custom_tool_use event this result corresponds to, which can be found in the last session.status_idle event's stop_reason.event_ids field.

type: "user.custom_tool_result"
content: optional array of BetaManagedAgentsTextBlock { text, type } or BetaManagedAgentsImageBlock { source, type } or BetaManagedAgentsDocumentBlock { source, type, context, title } or BetaManagedAgentsSearchResultBlock { citations, content, source, 2 more }

The result content returned by the tool.

One of the following:
beta_managed_agents_text_block: object{ text, type }

Regular text content.

text: string

The text content.

minLength1
type: "text"
beta_managed_agents_image_block: object{ source, type }

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

beta_managed_agents_document_block: object{ source, type, context, title }

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

beta_managed_agents_search_result_block: object{ citations, content, source, 2 more }

A block containing a web search result.

citations: object{ enabled }

Citation settings for a search result.

enabled: boolean

Whether citations are enabled for this search result.

content: array of 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"
is_error: optional boolean

Whether the tool execution resulted in an error.

processed_at: optional string

A timestamp in RFC 3339 format

formatdate-time
session_thread_id: optional string

Routes this result to a subagent thread. Copy from the agent.custom_tool_use event's session_thread_id.

beta_managed_agents_agent_custom_tool_use_event: object{ id, input, name, 3 more }

Event emitted when the agent calls a custom tool. The session goes idle until the client sends a user.custom_tool_result event with the result.

id: string

Unique identifier for this event.

input: map[unknown]

Input parameters for the tool call.

name: string

Name of the custom tool being called.

processed_at: string

A timestamp in RFC 3339 format

formatdate-time
type: "agent.custom_tool_use"
session_thread_id: optional string

When set, this event was cross-posted from a subagent's thread to surface its custom tool use on the primary thread's stream. Empty on the thread's own events. Echo this on a user.custom_tool_result event to route the result back.

beta_managed_agents_agent_message_event: object{ id, content, processed_at, type }

An agent response event in the session conversation.

id: string

Unique identifier for this event.

content: array of BetaManagedAgentsTextBlock { text, type } or BetaManagedAgentsRedactedBlock { type }

Array of text blocks comprising the agent response.

One of the following:
beta_managed_agents_text_block: object{ text, type }

Regular text content.

text: string

The text content.

minLength1
type: "text"
beta_managed_agents_redacted_block: object{ type }

Placeholder for content withheld by Anthropic model policy.

type: "redacted"
processed_at: string

A timestamp in RFC 3339 format

formatdate-time
type: "agent.message"
beta_managed_agents_agent_thinking_event: object{ id, processed_at, type }

Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier.

id: string

Unique identifier for this event.

processed_at: string

A timestamp in RFC 3339 format

formatdate-time
type: "agent.thinking"
beta_managed_agents_agent_mcp_tool_use_event: object{ id, input, mcp_server_name, 5 more }

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

id: string

Unique identifier for this event.

input: map[unknown]

Input parameters for the tool call.

mcp_server_name: string

Name of the MCP server providing the tool.

name: string

Name of the MCP tool being used.

processed_at: string

A timestamp in RFC 3339 format

formatdate-time
type: "agent.mcp_tool_use"
evaluated_permission: optional "allow" or "ask" or "deny"

AgentEvaluatedPermission enum

One of the following:
"allow"
"ask"
"deny"
session_thread_id: optional string

When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Echo this on a user.tool_confirmation event to route the approval back.

beta_managed_agents_agent_mcp_tool_result_event: object{ id, mcp_tool_use_id, processed_at, 3 more }

Event representing the result of an MCP tool execution.

id: string

Unique identifier for this event.

mcp_tool_use_id: string

The id of the agent.mcp_tool_use event this result corresponds to.

processed_at: string

A timestamp in RFC 3339 format

formatdate-time
type: "agent.mcp_tool_result"
content: optional array of BetaManagedAgentsTextBlock { text, type } or BetaManagedAgentsImageBlock { source, type } or BetaManagedAgentsDocumentBlock { source, type, context, title } or BetaManagedAgentsSearchResultBlock { citations, content, source, 2 more }

The result content returned by the tool.

One of the following:
beta_managed_agents_text_block: object{ text, type }

Regular text content.

text: string

The text content.

minLength1
type: "text"
beta_managed_agents_image_block: object{ source, type }

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

beta_managed_agents_document_block: object{ source, type, context, title }

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

beta_managed_agents_search_result_block: object{ citations, content, source, 2 more }

A block containing a web search result.

citations: object{ enabled }

Citation settings for a search result.

enabled: boolean

Whether citations are enabled for this search result.

content: array of 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"
is_error: optional boolean

Whether the tool execution resulted in an error.

beta_managed_agents_agent_tool_use_event: object{ id, input, name, 4 more }

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

id: string

Unique identifier for this event.

input: map[unknown]

Input parameters for the tool call.

name: string

Name of the agent tool being used.

processed_at: string

A timestamp in RFC 3339 format

formatdate-time
type: "agent.tool_use"
evaluated_permission: optional "allow" or "ask" or "deny"

AgentEvaluatedPermission enum

One of the following:
"allow"
"ask"
"deny"
session_thread_id: optional string

When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Echo this on a user.tool_confirmation event to route the approval back.

beta_managed_agents_agent_tool_result_event: object{ id, processed_at, tool_use_id, 3 more }

Event representing the result of an agent tool execution.

id: string

Unique identifier for this event.

processed_at: string

A timestamp in RFC 3339 format

formatdate-time
tool_use_id: string

The id of the agent.tool_use event this result corresponds to.

type: "agent.tool_result"
content: optional array of BetaManagedAgentsTextBlock { text, type } or BetaManagedAgentsImageBlock { source, type } or BetaManagedAgentsDocumentBlock { source, type, context, title } or BetaManagedAgentsSearchResultBlock { citations, content, source, 2 more }

The result content returned by the tool.

One of the following:
beta_managed_agents_text_block: object{ text, type }

Regular text content.

text: string

The text content.

minLength1
type: "text"
beta_managed_agents_image_block: object{ source, type }

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

beta_managed_agents_document_block: object{ source, type, context, title }

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

beta_managed_agents_search_result_block: object{ citations, content, source, 2 more }

A block containing a web search result.

citations: object{ enabled }

Citation settings for a search result.

enabled: boolean

Whether citations are enabled for this search result.

content: array of 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"
is_error: optional boolean

Whether the tool execution resulted in an error.

beta_managed_agents_agent_thread_message_received_event: object{ id, content, from_session_thread_id, 3 more }

Delivery event written to the target thread's input stream when an agent-to-agent message arrives.

id: string

Unique identifier for this event.

content: array of BetaManagedAgentsTextBlock { text, type } or BetaManagedAgentsImageBlock { source, type } or BetaManagedAgentsDocumentBlock { source, type, context, title } or BetaManagedAgentsRedactedBlock { type }

Message content blocks.

One of the following:
beta_managed_agents_text_block: object{ text, type }

Regular text content.

text: string

The text content.

minLength1
type: "text"
beta_managed_agents_image_block: object{ source, type }

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

beta_managed_agents_document_block: object{ source, type, context, title }

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

beta_managed_agents_redacted_block: object{ type }

Placeholder for content withheld by Anthropic model policy.

type: "redacted"
from_session_thread_id: string

Public sthr_ ID of the thread that sent the message.

processed_at: string

A timestamp in RFC 3339 format

formatdate-time
type: "agent.thread_message_received"
from_agent_name: optional string

Name of the callable agent this message came from. Absent when received from the primary agent.

beta_managed_agents_agent_thread_message_sent_event: object{ id, content, processed_at, 3 more }

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

id: string

Unique identifier for this event.

content: array of BetaManagedAgentsTextBlock { text, type } or BetaManagedAgentsImageBlock { source, type } or BetaManagedAgentsDocumentBlock { source, type, context, title } or BetaManagedAgentsRedactedBlock { type }

Message content blocks.

One of the following:
beta_managed_agents_text_block: object{ text, type }

Regular text content.

text: string

The text content.

minLength1
type: "text"
beta_managed_agents_image_block: object{ source, type }

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

beta_managed_agents_document_block: object{ source, type, context, title }

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

beta_managed_agents_redacted_block: object{ type }

Placeholder for content withheld by Anthropic model policy.

type: "redacted"
processed_at: string

A timestamp in RFC 3339 format

formatdate-time
to_session_thread_id: string

Public sthr_ ID of the thread the message was sent to.

type: "agent.thread_message_sent"
to_agent_name: optional string

Name of the callable agent this message was sent to. Absent when sent to the primary agent.

beta_managed_agents_agent_thread_context_compacted_event: object{ id, processed_at, type }

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

id: string

Unique identifier for this event.

processed_at: string

A timestamp in RFC 3339 format

formatdate-time
type: "agent.thread_context_compacted"
beta_managed_agents_session_error_event: object{ id, error, processed_at, type }

An error event indicating a problem occurred during session execution.

id: string

Unique identifier for this event.

error: BetaManagedAgentsUnknownError { message, retry_status, type } or BetaManagedAgentsModelOverloadedError { message, retry_status, type } or BetaManagedAgentsModelRateLimitedError { message, retry_status, type } or 5 more

An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on retry_status and message alone.

One of the following:
beta_managed_agents_unknown_error: object{ message, retry_status, type }

An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on retry_status and message alone.

beta_managed_agents_model_overloaded_error: object{ message, retry_status, type }

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

beta_managed_agents_model_rate_limited_error: object{ message, retry_status, type }

The model request was rate-limited.

beta_managed_agents_model_request_failed_error: object{ message, retry_status, type }

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

beta_managed_agents_mcp_connection_failed_error: object{ mcp_server_name, message, retry_status, type }

Failed to connect to an MCP server.

beta_managed_agents_mcp_authentication_failed_error: object{ mcp_server_name, message, retry_status, type }

Authentication to an MCP server failed.

beta_managed_agents_billing_error: object{ message, retry_status, type }

The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state.

beta_managed_agents_credential_host_unreachable_error: object{ 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.

processed_at: string

A timestamp in RFC 3339 format

formatdate-time
type: "session.error"
beta_managed_agents_session_status_rescheduled_event: object{ id, processed_at, type }

Indicates the session is recovering from an error state and is rescheduled for execution.

id: string

Unique identifier for this event.

processed_at: string

A timestamp in RFC 3339 format

formatdate-time
type: "session.status_rescheduled"
beta_managed_agents_session_status_running_event: object{ id, processed_at, type }

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

id: string

Unique identifier for this event.

processed_at: string

A timestamp in RFC 3339 format

formatdate-time
type: "session.status_running"
beta_managed_agents_session_status_idle_event: object{ id, processed_at, stop_reason, type }

Indicates the agent has paused and is awaiting user input.

id: string

Unique identifier for this event.

processed_at: string

A timestamp in RFC 3339 format

formatdate-time
stop_reason: BetaManagedAgentsSessionEndTurn { type } or BetaManagedAgentsSessionRequiresAction { event_ids, type } or BetaManagedAgentsSessionRetriesExhausted { type } or BetaManagedAgentsSessionBudgetReached { type }

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

One of the following:
beta_managed_agents_session_end_turn: object{ type }

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

type: "end_turn"
beta_managed_agents_session_requires_action: object{ event_ids, type }

The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running.

event_ids: array of string

The ids of events the agent is blocked on. Resolving fewer than all re-emits session.status_idle with the remainder.

type: "requires_action"
beta_managed_agents_session_retries_exhausted: object{ type }

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

type: "retries_exhausted"
beta_managed_agents_session_budget_reached: object{ 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"
type: "session.status_idle"
beta_managed_agents_session_status_terminated_event: object{ id, processed_at, type }

Indicates the session has terminated, either due to an error or completion.

id: string

Unique identifier for this event.

processed_at: string

A timestamp in RFC 3339 format

formatdate-time
type: "session.status_terminated"
beta_managed_agents_session_thread_created_event: object{ id, agent_name, processed_at, 2 more }

Emitted when a subagent is spawned as a new thread. Written to the parent thread's output stream so clients observing the session see child creation.

id: string

Unique identifier for this event.

agent_name: string

Name of the callable agent the thread runs.

processed_at: string

A timestamp in RFC 3339 format

formatdate-time
session_thread_id: string

Public sthr_ ID of the newly created thread.

type: "session.thread_created"
beta_managed_agents_span_outcome_evaluation_start_event: object{ id, iteration, outcome_id, 2 more }

Emitted when an outcome evaluation cycle begins.

id: string

Unique identifier for this event.

iteration: number

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

formatint32
outcome_id: string

The outc_ ID of the outcome being evaluated.

processed_at: string

A timestamp in RFC 3339 format

formatdate-time
type: "span.outcome_evaluation_start"
beta_managed_agents_span_outcome_evaluation_end_event: object{ id, explanation, iteration, 6 more }

Emitted when an outcome evaluation cycle completes. Carries the verdict and aggregate token usage. A verdict of needs_revision means another evaluation cycle follows; satisfied, max_iterations_reached, failed, or interrupted are terminal — no further evaluation cycles follow.

id: string

Unique identifier for this event.

explanation: string

Human-readable explanation of the verdict. For needs_revision, describes which criteria failed and why.

iteration: number

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

formatint32
outcome_evaluation_start_id: string

The id of the corresponding span.outcome_evaluation_start event.

outcome_id: string

The outc_ ID of the outcome being evaluated.

processed_at: string

A timestamp in RFC 3339 format

formatdate-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"
usage: object{ cache_creation_input_tokens, cache_read_input_tokens, input_tokens, 2 more }

Token usage for a single model request.

cache_creation_input_tokens: number

Tokens used to create prompt cache in this request.

formatint32
cache_read_input_tokens: number

Tokens read from prompt cache in this request.

formatint32
input_tokens: number

Input tokens consumed by this request.

formatint32
output_tokens: number

Output tokens generated by this request.

formatint32
speed: optional "standard" or "fast"

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

One of the following:
"standard"
"fast"
beta_managed_agents_span_model_request_start_event: object{ id, processed_at, type }

Emitted when a model request is initiated by the agent.

id: string

Unique identifier for this event.

processed_at: string

A timestamp in RFC 3339 format

formatdate-time
type: "span.model_request_start"
beta_managed_agents_span_model_request_end_event: object{ id, is_error, model_request_start_id, 3 more }

Emitted when a model request completes.

id: string

Unique identifier for this event.

is_error: boolean

Whether the model request resulted in an error.

model_request_start_id: string

The id of the corresponding span.model_request_start event.

model_usage: object{ cache_creation_input_tokens, cache_read_input_tokens, input_tokens, 2 more }

Token usage for a single model request.

cache_creation_input_tokens: number

Tokens used to create prompt cache in this request.

formatint32
cache_read_input_tokens: number

Tokens read from prompt cache in this request.

formatint32
input_tokens: number

Input tokens consumed by this request.

formatint32
output_tokens: number

Output tokens generated by this request.

formatint32
speed: optional "standard" or "fast"

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

One of the following:
"standard"
"fast"
processed_at: string

A timestamp in RFC 3339 format

formatdate-time
type: "span.model_request_end"
beta_managed_agents_span_outcome_evaluation_ongoing_event: object{ id, iteration, outcome_id, 2 more }

Periodic heartbeat emitted while an outcome evaluation cycle is in progress. Distinguishes 'evaluation is actively running' from 'evaluation is stuck' between the corresponding span.outcome_evaluation_start and span.outcome_evaluation_end events.

id: string

Unique identifier for this event.

iteration: number

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

formatint32
outcome_id: string

The outc_ ID of the outcome being evaluated.

processed_at: string

A timestamp in RFC 3339 format

formatdate-time
type: "span.outcome_evaluation_ongoing"
beta_managed_agents_user_define_outcome_event: object{ id, description, max_iterations, 4 more }

Echo of a user.define_outcome input event. Carries the server-generated outcome_id that subsequent span.outcome_evaluation_* events reference.

id: string

Unique identifier for this event.

description: string

What the agent should produce. Copied from the input event.

max_iterations: number

Evaluate-then-revise cycles before giving up. Default 3, max 20.

formatint32
outcome_id: string

Server-generated outc_ ID for this outcome. Referenced by span.outcome_evaluation_* events and the session's outcome_evaluations list.

processed_at: string

A timestamp in RFC 3339 format

formatdate-time
rubric: BetaManagedAgentsFileRubric { file_id, type } or BetaManagedAgentsTextRubric { content, type }

Rubric for grading the quality of an outcome.

One of the following:
beta_managed_agents_file_rubric: object{ file_id, type }

Rubric referenced by a file uploaded via the Files API.

file_id: string

ID of the rubric file.

type: "file"
beta_managed_agents_text_rubric: object{ content, type }

Rubric content provided inline as text.

content: string

Rubric content. Plain text or markdown — the grader treats it as freeform text.

type: "text"
type: "user.define_outcome"
beta_managed_agents_session_deleted_event: object{ id, processed_at, type }

Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session.

id: string

Unique identifier for this event.

processed_at: string

A timestamp in RFC 3339 format

formatdate-time
type: "session.deleted"
beta_managed_agents_session_thread_status_running_event: object{ id, agent_name, processed_at, 2 more }

A session thread has begun executing. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.

id: string

Unique identifier for this event.

agent_name: string

Name of the agent the thread runs.

processed_at: string

A timestamp in RFC 3339 format

formatdate-time
session_thread_id: string

Public sthr_ ID of the thread that started running.

type: "session.thread_status_running"
beta_managed_agents_session_thread_status_idle_event: object{ id, agent_name, processed_at, 3 more }

A session thread has yielded and is awaiting input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.

id: string

Unique identifier for this event.

agent_name: string

Name of the agent the thread runs.

processed_at: string

A timestamp in RFC 3339 format

formatdate-time
session_thread_id: string

Public sthr_ ID of the thread that went idle.

stop_reason: BetaManagedAgentsSessionEndTurn { type } or BetaManagedAgentsSessionRequiresAction { event_ids, type } or BetaManagedAgentsSessionRetriesExhausted { type } or BetaManagedAgentsSessionBudgetReached { type }

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

One of the following:
beta_managed_agents_session_end_turn: object{ type }

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

type: "end_turn"
beta_managed_agents_session_requires_action: object{ event_ids, type }

The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running.

event_ids: array of string

The ids of events the agent is blocked on. Resolving fewer than all re-emits session.status_idle with the remainder.

type: "requires_action"
beta_managed_agents_session_retries_exhausted: object{ type }

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

type: "retries_exhausted"
beta_managed_agents_session_budget_reached: object{ 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"
type: "session.thread_status_idle"
beta_managed_agents_session_thread_status_terminated_event: object{ id, agent_name, processed_at, 2 more }

A session thread has terminated and will accept no further input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.

id: string

Unique identifier for this event.

agent_name: string

Name of the agent the thread runs.

processed_at: string

A timestamp in RFC 3339 format

formatdate-time
session_thread_id: string

Public sthr_ ID of the thread that terminated.

type: "session.thread_status_terminated"
beta_managed_agents_user_tool_result_event: object{ id, tool_use_id, type, 4 more }

Event sent by the client providing the result of an agent-toolset tool execution. Only valid on self_hosted environments, where sandbox-routed tools are executed by the client rather than the server.

id: string

Unique identifier for this event.

tool_use_id: string

The id of the agent.tool_use event this result corresponds to, which can be found in the last session.status_idle event's stop_reason.event_ids field.

type: "user.tool_result"
content: optional array of BetaManagedAgentsTextBlock { text, type } or BetaManagedAgentsImageBlock { source, type } or BetaManagedAgentsDocumentBlock { source, type, context, title } or BetaManagedAgentsSearchResultBlock { citations, content, source, 2 more }

The result content returned by the tool.

One of the following:
beta_managed_agents_text_block: object{ text, type }

Regular text content.

text: string

The text content.

minLength1
type: "text"
beta_managed_agents_image_block: object{ source, type }

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

beta_managed_agents_document_block: object{ source, type, context, title }

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

beta_managed_agents_search_result_block: object{ citations, content, source, 2 more }

A block containing a web search result.

citations: object{ enabled }

Citation settings for a search result.

enabled: boolean

Whether citations are enabled for this search result.

content: array of 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"
is_error: optional boolean

Whether the tool execution resulted in an error.

processed_at: optional string

A timestamp in RFC 3339 format

formatdate-time
session_thread_id: optional string

Routes this result to a subagent thread. Copy from the agent.tool_use event's session_thread_id.

beta_managed_agents_session_thread_status_rescheduled_event: object{ id, agent_name, processed_at, 2 more }

A session thread hit a transient error and is retrying automatically. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.

id: string

Unique identifier for this event.

agent_name: string

Name of the agent the thread runs.

processed_at: string

A timestamp in RFC 3339 format

formatdate-time
session_thread_id: string

Public sthr_ ID of the thread that is retrying.

type: "session.thread_status_rescheduled"
beta_managed_agents_session_updated_event: object{ id, processed_at, type, 4 more }

Emitted when an UpdateSession request changed at least one field. Carries only the fields that changed; absent fields were not part of the update. The new configuration applies from the next turn.

id: string

Unique identifier for this event.

processed_at: string

A timestamp in RFC 3339 format

formatdate-time
type: "session.updated"
agent: optional object{ id, description, mcp_servers, 8 more }

Resolved agent definition for a session. Snapshot of the agent at session creation time.

id: string
description: string
mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition { name, type, url }
name: string
type: "url"
url: string
model: object{ id, effort, inference_geo, speed }

Model identifier and configuration.

id: "claude-sonnet-5" or "claude-fable-5" or "claude-opus-5" or 10 more or string

The model that will power your agent.

See models for additional details and options.

One of the following:
"claude-sonnet-5"

High-performance model for coding and agents

"claude-fable-5"

Next generation of intelligence for the hardest knowledge work and coding problems

"claude-opus-5"

Powerful intelligence for long-running agents and coding

"claude-opus-4-8"

Powerful intelligence for long-running agents and coding

"claude-opus-4-7"

Powerful intelligence for long-running agents and coding

"claude-opus-4-6"

Powerful intelligence for long-running agents and coding

"claude-sonnet-4-6"

Best combination of speed and intelligence

"claude-haiku-4-5"

Fastest model with near-frontier intelligence

"claude-haiku-4-5-20251001"

Fastest model with near-frontier intelligence

"claude-opus-4-5"

Powerful intelligence for long-running agents and coding

"claude-opus-4-5-20251101"

Powerful intelligence for long-running agents and coding

"claude-sonnet-4-5"

High-performance model for agents and coding

"claude-sonnet-4-5-20250929"

High-performance model for agents and coding

effort: optional BetaManagedAgentsEffortLow { type } or BetaManagedAgentsEffortMedium { type } or BetaManagedAgentsEffortHigh { type } or 2 more

How hard Claude works on each turn. Sets output_config.effort on every Messages call the session makes.

One of the following:
beta_managed_agents_effort_low: object{ type }

Low effort. Favors latency over reasoning depth.

type: "low"
beta_managed_agents_effort_medium: object{ type }

Medium effort. Balances latency and reasoning depth.

type: "medium"
beta_managed_agents_effort_high: object{ type }

High effort. Favors reasoning depth.

type: "high"
beta_managed_agents_effort_xhigh: object{ type }

Extra-high effort. Not all models accept this level.

type: "xhigh"
beta_managed_agents_effort_max: object{ type }

Maximum effort. Favors reasoning depth over latency.

type: "max"
inference_geo: optional string

Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.

speed: optional "standard" or "fast"

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

One of the following:
"standard"
"fast"
multiagent: object{ agents, type }

Resolved coordinator topology with full agent definitions for each roster member.

agents: array of BetaManagedAgentsSessionThreadAgent { id, description, mcp_servers, 7 more } or BetaManagedAgentsAdvisor { model, type }

Full agent definitions the coordinator may spawn as session threads.

One of the following:
beta_managed_agents_session_thread_agent: object{ id, description, mcp_servers, 7 more }

Resolved agent definition for a single session_thread. Snapshot of the agent at thread creation time. The multiagent roster is not repeated here; read it from Session.agent.

beta_managed_agents_advisor: object{ model, type }

Platform advisor roster entry: a model the session's primary thread may consult mid-turn.

model: string

The advisor model id.

type: "advisor"
type: "coordinator"
name: string
skills: array of BetaManagedAgentsAnthropicSkill { skill_id, type, version } or BetaManagedAgentsCustomSkill { skill_id, type, version }
One of the following:
beta_managed_agents_anthropic_skill: object{ skill_id, type, version }

A resolved Anthropic-managed skill.

skill_id: string
type: "anthropic"
version: string
beta_managed_agents_custom_skill: object{ skill_id, type, version }

A resolved user-created custom skill.

skill_id: string
type: "custom"
version: string
system: string
tools: array of BetaManagedAgentsAgentToolset20260401 { configs, default_config, type } or BetaManagedAgentsMCPToolset { configs, default_config, mcp_server_name, type } or BetaManagedAgentsCustomTool { description, input_schema, name, type }
One of the following:
beta_managed_agents_agent_toolset20260401: object{ configs, default_config, type }
beta_managed_agents_mcp_toolset: object{ configs, default_config, mcp_server_name, type }
beta_managed_agents_custom_tool: object{ description, input_schema, name, type }

A custom tool as returned in API responses.

description: string
input_schema: object{ type, properties, required }

JSON Schema for custom tool input parameters.

type: "object"
properties: optional map[unknown]
required: optional array of string
name: string
type: "custom"
type: "agent"
version: number
formatint32
budget: optional object{ max_list_cost, type }

A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches max_list_cost.

max_list_cost: object{ amount, currency }

A monetary amount in a specific currency.

amount: string

Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied.

currency: "USD"

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.

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

title: optional string

The session's new title. Present only when the update changed it.

beta_managed_agents_start_event: object{ event, type }

Opens a preview of a buffered event. Carries the previewed event's type and id only. Followed by zero or more event_delta events with the same event id, normally concluded by the buffered event carrying that id. If the producing model request ends without that event (an error or interrupt mid-stream), its terminal span.model_request_end closes the preview. Only sent on stream connections that opt in via event_deltas; never appears in event history.

event: BetaManagedAgentsAgentMessagePreview { id, type } or BetaManagedAgentsAgentThinkingPreview { id, type }

The previewed event's type and id. The event type determines which delta types the preview's event_delta events carry: agent.message events stream content_delta fragments; agent.thinking previews are start-only — no deltas follow, and the buffered agent.thinking with the same id concludes them.

One of the following:
beta_managed_agents_agent_message_preview: object{ id, type }
id: string

The id the buffered agent.message will carry if it is emitted. Matches the event_id on this preview's event_delta events.

type: "agent.message"
beta_managed_agents_agent_thinking_preview: object{ id, type }
id: string

The id the buffered agent.thinking will carry if it is emitted. Start-only — no event_delta events follow.

type: "agent.thinking"
type: "event_start"
beta_managed_agents_delta_event: object{ delta, event_id, type }

An incremental update to an event that is still being streamed. Deltas are best-effort and may stop early; when the buffered event with id == event_id is produced it carries the complete content. A model request that ends early (an error or interrupt) produces no buffered event — its terminal span.model_request_end closes the preview. Only sent on stream connections that opt in via event_deltas; never appears in event history.

delta: object{ content, type, index }

One fragment of the previewed event. The delta type is named for the previewed event's field it streams into: agent.message events stream content_delta fragments, each a partial element of the content array.

content: object{ text, type }

Regular text content.

text: string

The text content.

minLength1
type: "text"
type: "content_delta"
index: optional number

Which entry in the previewed event's content array this fragment lands in. Insert content as that entry when the index is new; append to the existing entry otherwise.

formatuint32
event_id: string

The id of the event being previewed. Matches event.id on the corresponding event_start and the buffered event that reconciles the preview.

type: "event_delta"
beta_managed_agents_system_message_event: object{ id, content, type, processed_at }

A mid-conversation system message event. Carries system-role content that is appended to the session as a role: "system" turn.

id: string

Unique identifier for this event.

content: array of BetaManagedAgentsSystemContentBlock { text, type }

System content blocks. Text-only.

text: string

The text content.

minLength1
type: "text"
type: "system.message"
processed_at: optional string

A timestamp in RFC 3339 format

formatdate-time
beta_managed_agents_session_usage_event: object{ id, processed_at, type, 2 more }

Periodic snapshot of the session's cumulative usage and tracked list cost.

id: string

Unique identifier for this event.

processed_at: string

A timestamp in RFC 3339 format

formatdate-time
type: "session.usage"
usage: object{ active_seconds, cache_creation, cache_read_input_tokens, 4 more }

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

active_seconds: optional number

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.

formatdouble
cache_creation: optional object{ ephemeral_1h_input_tokens, ephemeral_5m_input_tokens }

Prompt-cache creation token usage broken down by cache lifetime.

ephemeral_1h_input_tokens: optional number

Tokens used to create 1-hour ephemeral cache entries.

formatint32
ephemeral_5m_input_tokens: optional number

Tokens used to create 5-minute ephemeral cache entries.

formatint32
cache_read_input_tokens: optional number

Total tokens read from prompt cache.

formatint32
input_tokens: optional number

Total input tokens consumed across all turns.

formatint32
list_cost: optional object{ amount, currency }

A monetary amount in a specific currency.

amount: string

Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied.

currency: "USD"

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.

output_tokens: optional number

Total output tokens generated across all turns.

formatint32
server_tool_use: optional object{ web_fetch_requests, web_search_requests }

Cumulative count of server-executed tool invocations, broken down by tool.

web_fetch_requests: optional number

Number of server-executed web fetch requests.

formatint32
web_search_requests: optional number

Number of server-executed web search requests.

formatint32
budget: optional object{ max_list_cost, type }

A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches max_list_cost.

max_list_cost: object{ amount, currency }

A monetary amount in a specific currency.

amount: string

Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied.

currency: "USD"

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.

type: "limit"
beta_managed_agents_stream_session_events: BetaManagedAgentsUserMessageEvent { id, content, type, processed_at } or BetaManagedAgentsUserInterruptEvent { id, type, processed_at, session_thread_id } or BetaManagedAgentsUserToolConfirmationEvent { id, result, tool_use_id, 4 more } or 34 more

Server-sent event in the session stream.

Stream Events

ant beta:sessions:events stream \
  --api-key my-anthropic-api-key \
  --session-id sesn_011CZkZAtmR3yMPDzynEDxu7
{
  "id": "sevt_011CZkZGOp0iBcp4kaQSihUmy",
  "content": [
    {
      "text": "Where is my order #1234?",
      "type": "text"
    }
  ],
  "type": "user.message",
  "processed_at": "2026-03-15T10:00:00Z"
}
Returns Examples
{
  "id": "sevt_011CZkZGOp0iBcp4kaQSihUmy",
  "content": [
    {
      "text": "Where is my order #1234?",
      "type": "text"
    }
  ],
  "type": "user.message",
  "processed_at": "2026-03-15T10:00:00Z"
}