Stream Events

$ ant beta:sessions:events stream

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

Stream Events

Parameters

--session-id: string⁠Path

--event-delta: optional array of BetaManagedAgentsDeltaType⁠Query

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

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

--workspace-id: optional string⁠Header

Optional header to select the Workspace for this request. The value is a Workspace ID (for example, wrkspc_011CZkZaBF1tNoB5wlCeusgy).

Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace.

Returns

beta_managed_agents_stream_session_events: BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or 41 more

Server-sent event in the session stream.

One of the following:

beta_managed_agents_user_message_event: object{ type: "user.message", id, content, processed_at }

A user message event in the session conversation.

type: "user.message"

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.

One of the following:

beta_managed_agents_text_block: object{ type: "text", text }

Regular text content.

type: "text"

text: string

The text content.

minLength1

beta_managed_agents_image_block: object{ type: "image", source }

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

beta_managed_agents_document_block: object{ type: "document", source, 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: "redacted" }

Placeholder for content withheld by Anthropic model policy.

type: "redacted"

processed_at: optional string

Timestamp when the agent finished processing this message.

formatdate-time

beta_managed_agents_user_interrupt_event: object{ type: "user.interrupt", id, processed_at, session_thread_id }

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

type: "user.interrupt"

id: string

Unique identifier for this event.

processed_at: optional string

Timestamp when the interrupt was processed.

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{ type: "user.tool_confirmation", id, result, 4 more }

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

type: "user.tool_confirmation"

id: string

Unique identifier for this event.

result: "allow" or "deny"

The confirmation result: 'allow' or 'deny'.

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.

deny_message: optional string

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

maxLength10000

processed_at: optional string

Timestamp when the confirmation was processed.

formatdate-time

session_thread_id: optional string

Set by the server to the subagent thread this confirmation was routed to. Omitted when it was routed to the primary thread.

beta_managed_agents_user_custom_tool_result_event: object{ type: "user.custom_tool_result", id, custom_tool_use_id, 4 more }

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

type: "user.custom_tool_result"

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. It is also listed in the last session.status_idle event's stop_reason.event_ids field.

content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

The result content returned by the tool.

One of the following:

beta_managed_agents_text_block: object{ type: "text", text }

Regular text content.

type: "text"

text: string

The text content.

minLength1

beta_managed_agents_image_block: object{ type: "image", source }

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

beta_managed_agents_document_block: object{ type: "document", source, 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{ type: "search_result", citations, content, 2 more }

A block containing a web search result.

type: "search_result"

citations: object{ enabled }

Citation settings for this search result.

enabled: boolean

Whether citations are enabled for this search result.

content: array of BetaManagedAgentsSearchResultContent { type: "text", text }

Array of text content blocks from the search result.

type: "text"

text: string

The text content.

minLength1

source: string

The URL source of the search result.

minLength1

title: string

The title of the search result.

minLength1

is_error: optional boolean

Whether the tool execution resulted in an error.

processed_at: optional string

Timestamp when this result was processed.

formatdate-time

session_thread_id: optional string

Set by the server to the subagent thread this result was routed to. Omitted when it was routed to the primary thread.

beta_managed_agents_agent_custom_tool_use_event: object{ type: "agent.custom_tool_use", id, input, 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. The client can send it as soon as this event arrives, without waiting for session.status_idle.

type: "agent.custom_tool_use"

id: string

Unique identifier for this event.

input: map[unknown]

Input parameters for the tool call.

Name of the custom tool being called.

processed_at: string

Timestamp when this tool use was processed.

formatdate-time

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. Informational only: the server routes the matching user.custom_tool_result by custom_tool_use_id, so clients do not send it back.

beta_managed_agents_agent_message_event: object{ type: "agent.message", id, content, processed_at }

An agent response event in the session conversation.

type: "agent.message"

id: string

Unique identifier for this event.

content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsRedactedBlock

Array of text blocks comprising the agent response.

One of the following:

beta_managed_agents_text_block: object{ type: "text", text }

Regular text content.

type: "text"

text: string

The text content.

minLength1

beta_managed_agents_redacted_block: object{ type: "redacted" }

Placeholder for content withheld by Anthropic model policy.

type: "redacted"

processed_at: string

Timestamp when this response was generated.

formatdate-time

beta_managed_agents_agent_thinking_event: object{ type: "agent.thinking", id, processed_at }

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

type: "agent.thinking"

id: string

Unique identifier for this event.

processed_at: string

Timestamp when this thinking was produced.

formatdate-time

beta_managed_agents_agent_mcp_tool_use_event: object{ type: "agent.mcp_tool_use", id, input, 6 more }

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

type: "agent.mcp_tool_use"

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 of the MCP tool being used.

processed_at: string

Timestamp when this event was processed.

formatdate-time

evaluated_permission: optional "allow" or "ask" or "deny"

The evaluated permission policy for this tool invocation.

One of the following:

"allow"

"ask"

"deny"

evaluation: optional BetaManagedAgentsAgentToolEvaluationAlwaysAllow or BetaManagedAgentsAgentToolEvaluationAlwaysAsk or BetaManagedAgentsAgentToolEvaluationAuto

Which resolved permission_policy produced evaluated_permission: always_allow, always_ask, or auto (with the server's per-invocation judgement). Absent only when the server refused the call before any policy applied (for example, the named tool is not enabled in the session); such a refusal has evaluated_permission deny. An event recorded before this field existed reads as the arm its evaluated_permission implies (always_allow for allow, always_ask for ask).

One of the following:

beta_managed_agents_agent_tool_evaluation_always_allow: object{ type: "always_allow" }

The resolved permission_policy was always_allow; accompanies evaluated_permission "allow".

type: "always_allow"

beta_managed_agents_agent_tool_evaluation_always_ask: object{ type: "always_ask" }

The resolved permission_policy was always_ask; accompanies evaluated_permission "ask".

type: "always_ask"

beta_managed_agents_agent_tool_evaluation_auto: object{ type: "auto", evaluated_permission }

The resolved permission_policy was auto: the server judged this invocation individually.

type: "auto"

evaluated_permission: BetaManagedAgentsAgentAutoEvaluatedPermissionAllow or BetaManagedAgentsAgentAutoEvaluatedPermissionAsk or BetaManagedAgentsAgentAutoEvaluatedPermissionDeny

The server's judgement for this invocation.

One of the following:

beta_managed_agents_agent_auto_evaluated_permission_allow: object{ type: "allow" }

The server judged the invocation safe to execute without client approval.

type: "allow"

beta_managed_agents_agent_auto_evaluated_permission_ask: object{ type: "ask", reason_code }

The server reached no judgement; the invocation is held for client approval.

type: "ask"

reason_code: string

The judgement's grounds in registry-bound terms, for client branching and audit rather than end-user display. Open registry; currently "indeterminate" (no judgement was reached). Clients must tolerate values outside this set.

maxLength64

beta_managed_agents_agent_auto_evaluated_permission_deny: object{ type: "deny", reason_code }

The server judged the invocation high-risk; it does not execute and a synthetic error tool result is appended.

type: "deny"

reason_code: string

The judgement's grounds in registry-bound terms. Open registry; currently "high_risk" (judged high-risk; the call does not run). Clients must tolerate values outside this set.

maxLength64

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. Informational only: the server routes the matching user.tool_confirmation by tool_use_id, so clients do not send it back.

beta_managed_agents_agent_mcp_tool_result_event: object{ type: "agent.mcp_tool_result", id, mcp_tool_use_id, 3 more }

Event representing the result of an MCP tool execution.

type: "agent.mcp_tool_result"

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

Timestamp when this event was processed.

formatdate-time

content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

The result content returned by the tool.

One of the following:

beta_managed_agents_text_block: object{ type: "text", text }

Regular text content.

type: "text"

text: string

The text content.

minLength1

beta_managed_agents_image_block: object{ type: "image", source }

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

beta_managed_agents_document_block: object{ type: "document", source, 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{ type: "search_result", citations, content, 2 more }

A block containing a web search result.

type: "search_result"

citations: object{ enabled }

Citation settings for this search result.

enabled: boolean

Whether citations are enabled for this search result.

content: array of BetaManagedAgentsSearchResultContent { type: "text", text }

Array of text content blocks from the search result.

type: "text"

text: string

The text content.

minLength1

source: string

The URL source of the search result.

minLength1

title: string

The title of the search result.

minLength1

is_error: optional boolean

Whether the tool execution resulted in an error.

beta_managed_agents_agent_tool_use_event: object{ type: "agent.tool_use", id, input, 5 more }

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

type: "agent.tool_use"

id: string

Unique identifier for this event.

input: map[unknown]

Input parameters for the tool call.

Name of the agent tool being used.

processed_at: string

Timestamp when this event was processed.

formatdate-time

evaluated_permission: optional "allow" or "ask" or "deny"

The evaluated permission policy for this tool invocation.

One of the following:

"allow"

"ask"

"deny"

evaluation: optional BetaManagedAgentsAgentToolEvaluationAlwaysAllow or BetaManagedAgentsAgentToolEvaluationAlwaysAsk or BetaManagedAgentsAgentToolEvaluationAuto

One of the following:

beta_managed_agents_agent_tool_evaluation_always_allow: object{ type: "always_allow" }

The resolved permission_policy was always_allow; accompanies evaluated_permission "allow".

type: "always_allow"

beta_managed_agents_agent_tool_evaluation_always_ask: object{ type: "always_ask" }

The resolved permission_policy was always_ask; accompanies evaluated_permission "ask".

type: "always_ask"

beta_managed_agents_agent_tool_evaluation_auto: object{ type: "auto", evaluated_permission }

The resolved permission_policy was auto: the server judged this invocation individually.

type: "auto"

evaluated_permission: BetaManagedAgentsAgentAutoEvaluatedPermissionAllow or BetaManagedAgentsAgentAutoEvaluatedPermissionAsk or BetaManagedAgentsAgentAutoEvaluatedPermissionDeny

The server's judgement for this invocation.

One of the following:

beta_managed_agents_agent_auto_evaluated_permission_allow: object{ type: "allow" }

The server judged the invocation safe to execute without client approval.

type: "allow"

beta_managed_agents_agent_auto_evaluated_permission_ask: object{ type: "ask", reason_code }

The server reached no judgement; the invocation is held for client approval.

type: "ask"

reason_code: string

maxLength64

beta_managed_agents_agent_auto_evaluated_permission_deny: object{ type: "deny", reason_code }

The server judged the invocation high-risk; it does not execute and a synthetic error tool result is appended.

type: "deny"

reason_code: string

The judgement's grounds in registry-bound terms. Open registry; currently "high_risk" (judged high-risk; the call does not run). Clients must tolerate values outside this set.

maxLength64

session_thread_id: optional string

beta_managed_agents_agent_tool_result_event: object{ type: "agent.tool_result", id, processed_at, 3 more }

Event representing the result of an agent tool execution.

type: "agent.tool_result"

id: string

Unique identifier for this event.

processed_at: string

Timestamp when this event was processed.

formatdate-time

tool_use_id: string

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

content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

The result content returned by the tool.

One of the following:

beta_managed_agents_text_block: object{ type: "text", text }

Regular text content.

type: "text"

text: string

The text content.

minLength1

beta_managed_agents_image_block: object{ type: "image", source }

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

beta_managed_agents_document_block: object{ type: "document", source, 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{ type: "search_result", citations, content, 2 more }

A block containing a web search result.

type: "search_result"

citations: object{ enabled }

Citation settings for this search result.

enabled: boolean

Whether citations are enabled for this search result.

content: array of BetaManagedAgentsSearchResultContent { type: "text", text }

Array of text content blocks from the search result.

type: "text"

text: string

The text content.

minLength1

source: string

The URL source of the search result.

minLength1

title: string

The title of the search result.

minLength1

is_error: optional boolean

Whether the tool execution resulted in an error.

beta_managed_agents_agent_thread_message_received_event: object{ type: "agent.thread_message_received", id, content, 3 more }

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

type: "agent.thread_message_received"

id: string

Unique identifier for this event.

content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock

Message content blocks.

One of the following:

beta_managed_agents_text_block: object{ type: "text", text }

Regular text content.

type: "text"

text: string

The text content.

minLength1

beta_managed_agents_image_block: object{ type: "image", source }

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

beta_managed_agents_document_block: object{ type: "document", source, 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: "redacted" }

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

Timestamp when the message was received.

formatdate-time

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{ type: "agent.thread_message_sent", id, content, 3 more }

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

type: "agent.thread_message_sent"

id: string

Unique identifier for this event.

content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock

Message content blocks.

One of the following:

beta_managed_agents_text_block: object{ type: "text", text }

Regular text content.

type: "text"

text: string

The text content.

minLength1

beta_managed_agents_image_block: object{ type: "image", source }

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

beta_managed_agents_document_block: object{ type: "document", source, 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: "redacted" }

Placeholder for content withheld by Anthropic model policy.

type: "redacted"

processed_at: string

Timestamp when the message was sent.

formatdate-time

to_session_thread_id: string

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

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{ type: "agent.thread_context_compacted", id, processed_at }

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

type: "agent.thread_context_compacted"

id: string

Unique identifier for this event.

processed_at: string

Timestamp when compaction was processed.

formatdate-time

beta_managed_agents_session_error_event: object{ type: "session.error", id, error, processed_at }

An error event indicating a problem occurred during session execution.

type: "session.error"

id: string

Unique identifier for this event.

error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 10 more

One of the following:

beta_managed_agents_unknown_error: object{ type: "unknown_error", message, retry_status }

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{ type: "model_overloaded_error", message, retry_status }

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

beta_managed_agents_model_rate_limited_error: object{ type: "model_rate_limited_error", message, retry_status }

The model request was rate-limited.

beta_managed_agents_model_request_failed_error: object{ type: "model_request_failed_error", message, retry_status }

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

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

Failed to connect to an MCP server.

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

Authentication to an MCP server failed.

beta_managed_agents_billing_error: object{ type: "billing_error", message, retry_status }

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{ type: "credential_host_unreachable_error", credential_id, message, 2 more }

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

beta_managed_agents_repository_authentication_error: object{ type: "repository_authentication_error", message, repository_url, retry_status }

The repository host rejected the credentials, or required credentials and received none.

beta_managed_agents_repository_forbidden_error: object{ type: "repository_forbidden_error", message, repository_url, retry_status }

The repository host refused access to the repository.

beta_managed_agents_repository_not_found_error: object{ type: "repository_not_found_error", message, repository_url, retry_status }

The repository host reported the repository as not found.

beta_managed_agents_repository_checkout_error: object{ type: "repository_checkout_error", message, repository_url, retry_status }

The requested branch or commit does not exist in the repository.

beta_managed_agents_repository_clone_error: object{ type: "repository_clone_error", message, repository_url, retry_status }

The repository could not be cloned.

processed_at: string

Timestamp when the error occurred.

formatdate-time

beta_managed_agents_session_status_rescheduled_event: object{ type: "session.status_rescheduled", id, processed_at }

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

type: "session.status_rescheduled"

id: string

Unique identifier for this event.

processed_at: string

Timestamp of status change.

formatdate-time

beta_managed_agents_session_status_running_event: object{ type: "session.status_running", id, processed_at }

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

type: "session.status_running"

id: string

Unique identifier for this event.

processed_at: string

Timestamp of status change.

formatdate-time

beta_managed_agents_session_status_idle_event: object{ type: "session.status_idle", id, processed_at, 2 more }

Indicates the agent has paused and is awaiting user input.

type: "session.status_idle"

id: string

Unique identifier for this event.

processed_at: string

Timestamp of status change.

formatdate-time

stop_details: object{ type: "refusal", category, explanation }

Structured information about why the session stopped. null when there is nothing more to report.

type: "refusal"

category: "cyber" or "bio" or "frontier_llm" or 2 more

The policy category that triggered the refusal, or null when there is no named category. New values can be added over time.

One of the following:

"cyber"

"bio"

"frontier_llm"

"reasoning_extraction"

"general_harms"

explanation: string

Human-readable explanation of the refusal, or null when none is available. The wording can change, so do not parse it.

stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or 2 more

One of the following:

beta_managed_agents_session_end_turn: object{ type: "end_turn" }

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

type: "end_turn"

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

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.

type: "requires_action"

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.

beta_managed_agents_session_retries_exhausted: object{ type: "retries_exhausted" }

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

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"

beta_managed_agents_session_refusal: object{ type: "refusal" }

The turn ended because the model's response was refused, for example by a safety classifier.

type: "refusal"

beta_managed_agents_session_status_terminated_event: object{ type: "session.status_terminated", id, processed_at }

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

type: "session.status_terminated"

id: string

Unique identifier for this event.

processed_at: string

Timestamp of status change.

formatdate-time

beta_managed_agents_session_thread_created_event: object{ type: "session.thread_created", id, agent_name, 3 more }

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

type: "session.thread_created"

id: string

Unique identifier for this event.

agent_name: string

Name of the callable agent the thread runs.

processed_at: string

Timestamp when the thread was created.

formatdate-time

session_thread_id: string

Public sthr_ ID of the newly created thread.

workflow_run_id: string

Identifier of the workflow run that created the thread, or null for any other thread.

beta_managed_agents_span_outcome_evaluation_start_event: object{ type: "span.outcome_evaluation_start", id, iteration, 2 more }

Emitted when an outcome evaluation cycle begins.

type: "span.outcome_evaluation_start"

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

Timestamp when outcome evaluation started.

formatdate-time

beta_managed_agents_span_outcome_evaluation_end_event: object{ type: "span.outcome_evaluation_end", id, explanation, 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.

type: "span.outcome_evaluation_end"

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

Timestamp when outcome evaluation ended.

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.

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

Aggregate token usage for this evaluation cycle. Sums across all grader model requests within the cycle.

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 tier this request actually ran at. Mirrors usage.speed on /v1/messages. Only present when the fast-mode beta is active.

One of the following:

"standard"

"fast"

beta_managed_agents_span_model_request_start_event: object{ type: "span.model_request_start", id, processed_at }

Emitted when a model request is initiated by the agent.

type: "span.model_request_start"

id: string

Unique identifier for this event.

processed_at: string

Timestamp when the model request started.

formatdate-time

beta_managed_agents_span_model_request_end_event: object{ type: "span.model_request_end", id, is_error, 3 more }

Emitted when a model request completes.

type: "span.model_request_end"

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 this 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 tier this request actually ran at. Mirrors usage.speed on /v1/messages. Only present when the fast-mode beta is active.

One of the following:

"standard"

"fast"

processed_at: string

Timestamp when the model request completed.

formatdate-time

beta_managed_agents_span_outcome_evaluation_ongoing_event: object{ type: "span.outcome_evaluation_ongoing", id, iteration, 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.

type: "span.outcome_evaluation_ongoing"

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

Timestamp when this heartbeat was emitted.

formatdate-time

beta_managed_agents_user_define_outcome_event: object{ type: "user.define_outcome", id, description, 4 more }

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

type: "user.define_outcome"

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

Timestamp when the outcome was accepted.

formatdate-time

rubric: BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric

How to grade the outcome. File rubrics are currently resolved to their text content; clients should handle both variants.

One of the following:

beta_managed_agents_file_rubric: object{ type: "file", file_id }

Rubric referenced by a file uploaded via the Files API.

type: "file"

file_id: string

ID of the rubric file.

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

Rubric content provided inline as text.

type: "text"

content: string

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

beta_managed_agents_session_deleted_event: object{ type: "session.deleted", id, processed_at }

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

type: "session.deleted"

id: string

Unique identifier for this event.

processed_at: string

Timestamp when the session was deleted.

formatdate-time

beta_managed_agents_session_thread_status_running_event: object{ type: "session.thread_status_running", id, agent_name, 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.

type: "session.thread_status_running"

id: string

Unique identifier for this event.

agent_name: string

Name of the agent the thread runs.

processed_at: string

Timestamp of the status transition.

formatdate-time

session_thread_id: string

Public sthr_ ID of the thread that started running.

beta_managed_agents_session_thread_status_idle_event: object{ type: "session.thread_status_idle", id, agent_name, 4 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.

type: "session.thread_status_idle"

id: string

Unique identifier for this event.

agent_name: string

Name of the agent the thread runs.

processed_at: string

Timestamp of the status transition.

formatdate-time

session_thread_id: string

Public sthr_ ID of the thread that went idle.

stop_details: object{ type: "refusal", category, explanation }

Structured information about why the thread stopped. null when there is nothing more to report.

type: "refusal"

category: "cyber" or "bio" or "frontier_llm" or 2 more

The policy category that triggered the refusal, or null when there is no named category. New values can be added over time.

One of the following:

"cyber"

"bio"

"frontier_llm"

"reasoning_extraction"

"general_harms"

explanation: string

Human-readable explanation of the refusal, or null when none is available. The wording can change, so do not parse it.

stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or 2 more

One of the following:

beta_managed_agents_session_end_turn: object{ type: "end_turn" }

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

type: "end_turn"

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

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.

type: "requires_action"

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.

beta_managed_agents_session_retries_exhausted: object{ type: "retries_exhausted" }

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

type: "budget_reached"

beta_managed_agents_session_refusal: object{ type: "refusal" }

The turn ended because the model's response was refused, for example by a safety classifier.

type: "refusal"

beta_managed_agents_session_thread_status_terminated_event: object{ type: "session.thread_status_terminated", id, agent_name, 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.

type: "session.thread_status_terminated"

id: string

Unique identifier for this event.

agent_name: string

Name of the agent the thread runs.

processed_at: string

Timestamp of the status transition.

formatdate-time

session_thread_id: string

Public sthr_ ID of the thread that terminated.

beta_managed_agents_user_tool_result_event: object{ type: "user.tool_result", id, tool_use_id, 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.

type: "user.tool_result"

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.

content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock

The result content returned by the tool.

One of the following:

beta_managed_agents_text_block: object{ type: "text", text }

Regular text content.

type: "text"

text: string

The text content.

minLength1

beta_managed_agents_image_block: object{ type: "image", source }

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

beta_managed_agents_document_block: object{ type: "document", source, 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{ type: "search_result", citations, content, 2 more }

A block containing a web search result.

type: "search_result"

citations: object{ enabled }

Citation settings for this search result.

enabled: boolean

Whether citations are enabled for this search result.

content: array of BetaManagedAgentsSearchResultContent { type: "text", text }

Array of text content blocks from the search result.

type: "text"

text: string

The text content.

minLength1

source: string

The URL source of the search result.

minLength1

title: string

The title of the search result.

minLength1

is_error: optional boolean

Whether the tool execution resulted in an error.

processed_at: optional string

Timestamp when this result was processed.

formatdate-time

session_thread_id: optional string

Set by the server to the subagent thread this result was routed to. Omitted when it was routed to the primary thread.

beta_managed_agents_session_thread_status_rescheduled_event: object{ type: "session.thread_status_rescheduled", id, agent_name, 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.

type: "session.thread_status_rescheduled"

id: string

Unique identifier for this event.

agent_name: string

Name of the agent the thread runs.

processed_at: string

Timestamp of the status transition.

formatdate-time

session_thread_id: string

Public sthr_ ID of the thread that is retrying.

beta_managed_agents_session_updated_event: object{ type: "session.updated", id, processed_at, 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.

type: "session.updated"

id: string

Unique identifier for this event.

processed_at: string

Timestamp when the update was applied.

formatdate-time

agent: optional object{ type: "agent", id, description, 8 more }

The session's effective agent configuration after the update. Present only when the update changed agent (tools or mcp_servers); when present it is the full materialised snapshot, not a diff.

type: "agent"

id: string

description: string

mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition { type: "url", name, url }

type: "url"

url: string

model: object{ id, effort, inference_geo, speed }

Model identifier and configuration.

id: "claude-haiku-5-5" or "claude-sonnet-5-5" or "claude-opus-5-5" or 14 more or string

The model that will power your agent.

See models for additional details and options.

One of the following:

"claude-haiku-5-5"

Fastest model for high-volume, real-time tasks

"claude-sonnet-5-5"

Efficient model for coding and agents

"claude-opus-5-5"

Powerful intelligence for coding, knowledge work, and long-running agents

"claude-fable-5-1"

Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows

"claude-sonnet-5"

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

"claude-haiku-4-5-20251001"

"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"⁠Deprecated

High-performance model for agents and coding

Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information.

"claude-sonnet-4-5-20250929"⁠Deprecated

High-performance model for agents and coding

Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information.

effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more

How hard Claude works on each inference call. One of low, medium, high, xhigh, max. Always present; resolved to the per-model default at save time when not supplied.

One of the following:

beta_managed_agents_effort_low: object{ type: "low" }

Low effort. Favors latency over reasoning depth.

type: "low"

beta_managed_agents_effort_medium: object{ type: "medium" }

Medium effort. Balances latency and reasoning depth.

type: "medium"

beta_managed_agents_effort_high: object{ type: "high" }

High effort. Favors reasoning depth.

type: "high"

beta_managed_agents_effort_xhigh: object{ type: "xhigh" }

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

type: "xhigh"

beta_managed_agents_effort_max: object{ type: "max" }

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. Defaults to standard. Not all models support fast; invalid combinations are rejected at create time.

One of the following:

"standard"

"fast"

multiagent: BetaManagedAgentsSessionMultiagentCoordinator or BetaManagedAgentsSessionMultiagent20261001

Resolved multiagent orchestration configuration. Null when the agent is single-threaded.

One of the following:

beta_managed_agents_session_multiagent_coordinator: object{ type: "coordinator", agents }

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

type: "coordinator"

agents: array of BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor

Full agent definitions the coordinator may spawn as session threads.

One of the following:

beta_managed_agents_session_thread_agent: object{ type: "agent", id, description, 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{ type: "advisor", model }

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

type: "advisor"

model: string

The advisor model id.

beta_managed_agents_session_multiagent20261001: object{ type: "multiagent_20261001", advisor, subagents, workflows }

Resolved multiagent configuration with three members, as copied to the session at creation.

type: "multiagent_20261001"

advisor: BetaManagedAgentsMultiagentAdvisorEnabled or BetaManagedAgentsMultiagentAdvisorDisabled

Whether the session's primary thread can consult an advisor model.

One of the following:

beta_managed_agents_multiagent_advisor_enabled: object{ type: "enabled", model }

The session's primary thread can consult model mid-turn.

type: "enabled"

model: string

The advisor model id.

beta_managed_agents_multiagent_advisor_disabled: object{ type: "disabled" }

The agent has no advisor.

type: "disabled"

subagents: BetaManagedAgentsSessionMultiagentSubagentsEnabled or BetaManagedAgentsMultiagentSubagentsDisabled

Whether the agent can spawn session threads.

One of the following:

beta_managed_agents_session_multiagent_subagents_enabled: object{ type: "enabled", inline_agents, predefined_agents }

The agent can spawn session threads.

type: "enabled"

inline_agents: BetaManagedAgentsMultiagentInlineAgentsEnabled or BetaManagedAgentsMultiagentInlineAgentsDisabled

Whether the agent can define inline agents, which are not saved, when it spawns session threads.

One of the following:

beta_managed_agents_multiagent_inline_agents_enabled: object{ type: "enabled" }

The agent can define inline agents.

type: "enabled"

beta_managed_agents_multiagent_inline_agents_disabled: object{ type: "disabled" }

The agent cannot define inline agents.

type: "disabled"

predefined_agents: array of BetaManagedAgentsSessionThreadAgent { type: "agent", id, description, 7 more }

Full agent definitions of the predefined agents, which are saved agents that this agent can spawn as session threads.

type: "agent"

id: string

description: string

mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition { type: "url", name, url }

type: "url"

url: string

model: object{ id, effort, inference_geo, speed }

Model identifier and configuration.

id: "claude-haiku-5-5" or "claude-sonnet-5-5" or "claude-opus-5-5" or 14 more or string

The model that will power your agent.

See models for additional details and options.

One of the following:

"claude-haiku-5-5"

Fastest model for high-volume, real-time tasks

"claude-sonnet-5-5"

Efficient model for coding and agents

"claude-opus-5-5"

Powerful intelligence for coding, knowledge work, and long-running agents

"claude-fable-5-1"

Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows

"claude-sonnet-5"

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

"claude-haiku-4-5-20251001"

"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"⁠Deprecated

High-performance model for agents and coding

Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information.

"claude-sonnet-4-5-20250929"⁠Deprecated

High-performance model for agents and coding

Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information.

effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more

How hard Claude works on each inference call. One of low, medium, high, xhigh, max. Always present; resolved to the per-model default at save time when not supplied.

One of the following:

beta_managed_agents_effort_low: object{ type: "low" }

Low effort. Favors latency over reasoning depth.

type: "low"

beta_managed_agents_effort_medium: object{ type: "medium" }

Medium effort. Balances latency and reasoning depth.

type: "medium"

beta_managed_agents_effort_high: object{ type: "high" }

High effort. Favors reasoning depth.

type: "high"

beta_managed_agents_effort_xhigh: object{ type: "xhigh" }

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

type: "xhigh"

beta_managed_agents_effort_max: object{ type: "max" }

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"

One of the following:

"standard"

"fast"

skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

One of the following:

beta_managed_agents_anthropic_skill: object{ type: "anthropic", skill_id, version }

A resolved Anthropic-managed skill.

type: "anthropic"

skill_id: string

version: string

beta_managed_agents_custom_skill: object{ type: "custom", skill_id, version }

A resolved user-created custom skill.

type: "custom"

skill_id: string

version: string

system: string

tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

One of the following:

beta_managed_agents_agent_toolset20260401: object{ type: "agent_toolset_20260401", configs, default_config }

beta_managed_agents_mcp_toolset: object{ type: "mcp_toolset", configs, default_config, mcp_server_name }

beta_managed_agents_custom_tool: object{ type: "custom", description, input_schema, name }

A custom tool as returned in API responses.

type: "custom"

description: string

input_schema: object{ type: "object", properties, required }

JSON Schema for custom tool input parameters.

type: "object"

properties: optional map[unknown]

required: optional array of string

version: number

formatint32

beta_managed_agents_multiagent_subagents_disabled: object{ type: "disabled" }

The agent cannot spawn session threads.

type: "disabled"

workflows: BetaManagedAgentsSessionMultiagentWorkflowsEnabled or BetaManagedAgentsMultiagentWorkflowsDisabled

Whether the agent can start workflow runs.

One of the following:

beta_managed_agents_session_multiagent_workflows_enabled: object{ type: "enabled", inline_agents, predefined_agents }

The agent can start workflow runs.

type: "enabled"

inline_agents: BetaManagedAgentsMultiagentInlineAgentsEnabled or BetaManagedAgentsMultiagentInlineAgentsDisabled

Whether a run's plan can define inline agents, which are not saved.

One of the following:

beta_managed_agents_multiagent_inline_agents_enabled: object{ type: "enabled" }

The agent can define inline agents.

type: "enabled"

beta_managed_agents_multiagent_inline_agents_disabled: object{ type: "disabled" }

The agent cannot define inline agents.

type: "disabled"

predefined_agents: array of BetaManagedAgentsSessionThreadAgent { type: "agent", id, description, 7 more }

Full agent definitions of the predefined agents, which are saved agents that a run's plan can use.

type: "agent"

id: string

description: string

mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition { type: "url", name, url }

type: "url"

url: string

model: object{ id, effort, inference_geo, speed }

Model identifier and configuration.

id: "claude-haiku-5-5" or "claude-sonnet-5-5" or "claude-opus-5-5" or 14 more or string

The model that will power your agent.

See models for additional details and options.

One of the following:

"claude-haiku-5-5"

Fastest model for high-volume, real-time tasks

"claude-sonnet-5-5"

Efficient model for coding and agents

"claude-opus-5-5"

Powerful intelligence for coding, knowledge work, and long-running agents

"claude-fable-5-1"

Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows

"claude-sonnet-5"

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

"claude-haiku-4-5-20251001"

"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"⁠Deprecated

High-performance model for agents and coding

Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information.

"claude-sonnet-4-5-20250929"⁠Deprecated

High-performance model for agents and coding

Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information.

effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more

How hard Claude works on each inference call. One of low, medium, high, xhigh, max. Always present; resolved to the per-model default at save time when not supplied.

One of the following:

beta_managed_agents_effort_low: object{ type: "low" }

Low effort. Favors latency over reasoning depth.

type: "low"

beta_managed_agents_effort_medium: object{ type: "medium" }

Medium effort. Balances latency and reasoning depth.

type: "medium"

beta_managed_agents_effort_high: object{ type: "high" }

High effort. Favors reasoning depth.

type: "high"

beta_managed_agents_effort_xhigh: object{ type: "xhigh" }

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

type: "xhigh"

beta_managed_agents_effort_max: object{ type: "max" }

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"

One of the following:

"standard"

"fast"

skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

One of the following:

beta_managed_agents_anthropic_skill: object{ type: "anthropic", skill_id, version }

A resolved Anthropic-managed skill.

type: "anthropic"

skill_id: string

version: string

beta_managed_agents_custom_skill: object{ type: "custom", skill_id, version }

A resolved user-created custom skill.

type: "custom"

skill_id: string

version: string

system: string

tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

One of the following:

beta_managed_agents_agent_toolset20260401: object{ type: "agent_toolset_20260401", configs, default_config }

beta_managed_agents_mcp_toolset: object{ type: "mcp_toolset", configs, default_config, mcp_server_name }

beta_managed_agents_custom_tool: object{ type: "custom", description, input_schema, name }

A custom tool as returned in API responses.

type: "custom"

description: string

input_schema: object{ type: "object", properties, required }

JSON Schema for custom tool input parameters.

type: "object"

properties: optional map[unknown]

required: optional array of string

version: number

formatint32

beta_managed_agents_multiagent_workflows_disabled: object{ type: "disabled" }

The agent cannot start workflow runs.

type: "disabled"

skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill

One of the following:

beta_managed_agents_anthropic_skill: object{ type: "anthropic", skill_id, version }

A resolved Anthropic-managed skill.

type: "anthropic"

skill_id: string

version: string

beta_managed_agents_custom_skill: object{ type: "custom", skill_id, version }

A resolved user-created custom skill.

type: "custom"

skill_id: string

version: string

system: string

tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool

One of the following:

beta_managed_agents_agent_toolset20260401: object{ type: "agent_toolset_20260401", configs, default_config }

beta_managed_agents_mcp_toolset: object{ type: "mcp_toolset", configs, default_config, mcp_server_name }

beta_managed_agents_custom_tool: object{ type: "custom", description, input_schema, name }

A custom tool as returned in API responses.

type: "custom"

description: string

input_schema: object{ type: "object", properties, required }

JSON Schema for custom tool input parameters.

type: "object"

properties: optional map[unknown]

required: optional array of string

version: number

formatint32

budget: optional object{ type: "limit", max_list_cost }

The session's budget after the update: the new budget when set or replaced, or null when the update removed it. Present only when the update changed the budget.

type: "limit"

max_list_cost: object{ amount, currency }

Maximum list cost the session may accrue. List price is used regardless of any negotiated discount, so the cap fires at or before the actual charge.

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.

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{ type: "event_start", event }

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.

type: "event_start"

event: BetaManagedAgentsAgentMessagePreview or BetaManagedAgentsAgentThinkingPreview

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{ type: "agent.message", id }

type: "agent.message"

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.

beta_managed_agents_agent_thinking_preview: object{ type: "agent.thinking", id }

type: "agent.thinking"

id: string

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

beta_managed_agents_delta_event: object{ type: "event_delta", delta, event_id }

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.

type: "event_delta"

delta: object{ type: "content_delta", content, 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.

type: "content_delta"

content: object{ type: "text", text }

A partial element of the content array at index, typed like the element itself — the same shape the buffered agent.message carries in content.

type: "text"

text: string

The text content.

minLength1

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.

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.

beta_managed_agents_system_message_event: object{ type: "system.message", id, content, processed_at }

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

type: "system.message"

id: string

Unique identifier for this event.

content: array of BetaManagedAgentsSystemContentBlock { type: "text", text }

System content blocks. Text-only.

type: "text"

text: string

The text content.

minLength1

processed_at: optional string

Timestamp when this system message was processed.

formatdate-time

beta_managed_agents_session_usage_event: object{ type: "session.usage", id, processed_at, 2 more }

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

type: "session.usage"

id: string

Unique identifier for this event.

processed_at: string

Timestamp when the snapshot was taken.

formatdate-time

usage: object{ active_seconds, cache_creation, cache_read_input_tokens, 4 more }

The session's cumulative usage at the snapshot time.

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 }

Tokens used to create prompt cache entries, broken down by cache TTL.

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 }

Cumulative list cost of the session across all turns, priced at public list rates.

amount: string

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 server-executed tool usage across all turns.

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{ type: "limit", max_list_cost }

The session's configured budget at the snapshot time, or null when the session has no budget.

type: "limit"

max_list_cost: object{ amount, currency }

Maximum list cost the session may accrue. List price is used regardless of any negotiated discount, so the cap fires at or before the actual charge.

amount: string

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.

beta_managed_agents_workflow_run_created_event: object{ type: "workflow_run.created", id, description, 4 more }

A workflow run was created. A workflow run is background work that the session's agent starts. Emitted once per run, before the run's other workflow_run.* events.

type: "workflow_run.created"

id: string

Unique identifier for this event.

description: string

Description that the agent gave the run, passed on as written, or null if it gave none.

Name that the agent gave the run, passed on as written, or a name that the server assigned.

phases: array of BetaManagedAgentsWorkflowRunPhase { id, description, name }

The phases that the run's plan declares, in the plan's order. Can be empty.

id: string

Unique identifier for the phase.

description: string

Description that the agent gave the phase, passed on as written, or null if it gave none.

Name that the agent gave the phase, passed on as written.

processed_at: string

Timestamp when this event was processed.

formatdate-time

workflow_run_id: string

Identifier of the run. The same value is on all of the run's workflow_run.* events.

beta_managed_agents_workflow_run_status_ended_event: object{ type: "workflow_run.status_ended", id, processed_at, 2 more }

A workflow run ended. Emitted once per run, as the last of the run's workflow_run.* events.

type: "workflow_run.status_ended"

id: string

Unique identifier for this event.

processed_at: string

Timestamp when this event was processed.

formatdate-time

result: BetaManagedAgentsWorkflowRunResultCompleted or BetaManagedAgentsWorkflowRunResultError or BetaManagedAgentsWorkflowRunResultStopped

How the run ended.

One of the following:

beta_managed_agents_workflow_run_result_completed: object{ type: "completed" }

The run's plan, a program that the agent wrote, finished. This does not say whether the work succeeded.

type: "completed"

beta_managed_agents_workflow_run_result_error: object{ type: "error", error }

The run failed or reached its time limit.

type: "error"

error: BetaManagedAgentsTimeoutWorkflowRunError or BetaManagedAgentsProgramWorkflowRunError or BetaManagedAgentsUnknownWorkflowRunError or 2 more

Why the run did not finish.

One of the following:

beta_managed_agents_timeout_workflow_run_error: object{ type: "timeout_error", message }

The run reached its time limit.

type: "timeout_error"

message: string

Short explanation written by the server. It never contains content from the run or its agents.

beta_managed_agents_program_workflow_run_error: object{ type: "program_error", message }

The plan, a program that the agent wrote, failed, or the server refused it.

type: "program_error"

message: string

Short explanation written by the server. It never contains content from the run or its agents.

beta_managed_agents_unknown_workflow_run_error: object{ type: "unknown_error", message }

A failure that has no type of its own.

type: "unknown_error"

message: string

Short explanation written by the server. It never contains content from the run or its agents.

beta_managed_agents_thread_limit_workflow_run_error: object{ type: "thread_limit_error", message }

The run exceeded the limit on the number of threads that a run can create.

type: "thread_limit_error"

message: string

Short explanation written by the server. It never contains content from the run or its agents.

beta_managed_agents_max_workflow_runs_workflow_run_error: object{ type: "max_workflow_runs_error", message }

No run was created, because the session was at its limit of open workflow runs, which are runs that have not ended. Only workflow_run.error carries this type.

type: "max_workflow_runs_error"

message: string

Short explanation written by the server. It never contains content from the run or its agents.

beta_managed_agents_workflow_run_result_stopped: object{ type: "stopped" }

The agent stopped the run.

type: "stopped"

workflow_run_id: string

Identifier of the run. The same value is on all of the run's workflow_run.* events.

beta_managed_agents_workflow_run_phase_started_event: object{ type: "workflow_run.phase_started", id, processed_at, 2 more }

A workflow run's plan entered a phase.

type: "workflow_run.phase_started"

id: string

Unique identifier for this event.

processed_at: string

Timestamp when this event was processed.

formatdate-time

workflow_run_id: string

Identifier of the run. The same value is on all of the run's workflow_run.* events.

workflow_run_phase_id: string

Identifier of the phase, as in phases on the run's workflow_run.created event.

beta_managed_agents_workflow_run_phase_ended_event: object{ type: "workflow_run.phase_ended", id, phase_started_id, 3 more }

A workflow run's plan left a phase, or the run's end closed it. Emitted once for every workflow_run.phase_started event, before the run's workflow_run.status_ended event. The event does not say whether the plan finished the phase's work, or why it left.

type: "workflow_run.phase_ended"

id: string

Unique identifier for this event.

phase_started_id: string

Identifier of the workflow_run.phase_started event that opened the phase.

processed_at: string

Timestamp when this event was processed.

formatdate-time

workflow_run_id: string

Identifier of the run. The same value is on all of the run's workflow_run.* events.

workflow_run_phase_id: string

Identifier of the phase, as in phases on the run's workflow_run.created event.

beta_managed_agents_workflow_run_status_running_event: object{ type: "workflow_run.status_running", id, processed_at, workflow_run_id }

A workflow run is running. Emitted when the run starts to execute, and each time it resumes after being idle. A run that starts idle emits workflow_run.status_idle first.

type: "workflow_run.status_running"

id: string

Unique identifier for this event.

processed_at: string

Timestamp when this event was processed.

formatdate-time

workflow_run_id: string

Identifier of the run. The same value is on all of the run's workflow_run.* events.

beta_managed_agents_workflow_run_status_idle_event: object{ type: "workflow_run.status_idle", id, processed_at, workflow_run_id }

A workflow run is idle. Emitted each time the run goes idle, whatever the cause. If the run ends while idle, no workflow_run.status_running comes between this event and its workflow_run.status_ended.

type: "workflow_run.status_idle"

id: string

Unique identifier for this event.

processed_at: string

Timestamp when this event was processed.

formatdate-time

workflow_run_id: string

Identifier of the run. The same value is on all of the run's workflow_run.* events.

beta_managed_agents_workflow_run_error_event: object{ type: "workflow_run.error", id, error, 2 more }

A workflow run met an error, or an error kept a run from being created. A run that ends with a result.type of error emits this event before its workflow_run.status_ended, with the same error.

type: "workflow_run.error"

id: string

Unique identifier for this event.

error: BetaManagedAgentsTimeoutWorkflowRunError or BetaManagedAgentsProgramWorkflowRunError or BetaManagedAgentsUnknownWorkflowRunError or 2 more

Why the run did not finish, or was not created.

One of the following:

beta_managed_agents_timeout_workflow_run_error: object{ type: "timeout_error", message }

The run reached its time limit.

type: "timeout_error"

message: string

Short explanation written by the server. It never contains content from the run or its agents.

beta_managed_agents_program_workflow_run_error: object{ type: "program_error", message }

The plan, a program that the agent wrote, failed, or the server refused it.

type: "program_error"

message: string

Short explanation written by the server. It never contains content from the run or its agents.

beta_managed_agents_unknown_workflow_run_error: object{ type: "unknown_error", message }

A failure that has no type of its own.

type: "unknown_error"

message: string

Short explanation written by the server. It never contains content from the run or its agents.

beta_managed_agents_thread_limit_workflow_run_error: object{ type: "thread_limit_error", message }

The run exceeded the limit on the number of threads that a run can create.

type: "thread_limit_error"

message: string

Short explanation written by the server. It never contains content from the run or its agents.

beta_managed_agents_max_workflow_runs_workflow_run_error: object{ type: "max_workflow_runs_error", message }

No run was created, because the session was at its limit of open workflow runs, which are runs that have not ended. Only workflow_run.error carries this type.

type: "max_workflow_runs_error"

message: string

Short explanation written by the server. It never contains content from the run or its agents.

processed_at: string

Timestamp when this event was processed.

formatdate-time

workflow_run_id: string

Identifier of the run that met the error, or null when the error kept a run from being created.

Stream Events

ant beta:sessions:events stream \
  --api-key my-anthropic-api-key \
  --session-id sesn_011CZkZAtmR3yMPDzynEDxu7

Response 200

{
  "id": "sevt_011CZkZGPp1iBcp4kaQSihUm",
  "content": [
    {
      "text": "Where is my order #1234?",
      "type": "text"
    }
  ],
  "type": "user.message",
  "processed_at": "2026-03-15T10:00:00Z"
}

Returns Examples

Response 200

{
  "id": "sevt_011CZkZGPp1iBcp4kaQSihUm",
  "content": [
    {
      "text": "Where is my order #1234?",
      "type": "text"
    }
  ],
  "type": "user.message",
  "processed_at": "2026-03-15T10:00:00Z"
}