Claude Platform Docs

Events

List Events
$ ant beta:sessions:events list
GET/v1/sessions/{session_id}/events
Send Events
$ ant beta:sessions:events send
POST/v1/sessions/{session_id}/events
Stream Events
$ ant beta:sessions:events stream
GET/v1/sessions/{session_id}/events/stream
Models
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_mcp_tool_result_event: object{ id, mcp_tool_use_id, processed_at, 3 more }

Event representing the result of an MCP tool execution.

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.

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

An agent response event in the session conversation.

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

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.

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.

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_base64_document_source: object{ data, media_type, type }

Base64-encoded document data.

data: string

Base64-encoded document data.

minLength1
media_type: string

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

minLength1
type: "base64"
beta_managed_agents_base64_image_source: object{ data, media_type, type }

Base64-encoded image data.

data: string

Base64-encoded image data.

minLength1
media_type: string

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

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

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_event_params: BetaManagedAgentsUserMessageEventParams { content, type } or BetaManagedAgentsUserInterruptEventParams { type, session_thread_id } or BetaManagedAgentsUserToolConfirmationEventParams { result, tool_use_id, type, deny_message } or 4 more

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

beta_managed_agents_file_document_source: object{ file_id, type }

Document referenced by file ID.

file_id: string

ID of a previously uploaded file.

minLength1
type: "file"
beta_managed_agents_file_image_source: object{ file_id, type }

Image referenced by file ID.

file_id: string

ID of a previously uploaded file.

minLength1
type: "file"
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_file_rubric_params: 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_image_block: object{ source, type }

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

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

Authentication to an MCP server failed.

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_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_plain_text_document_source: object{ data, media_type, type }

Plain text document content.

data: string

The plain text content.

minLength1
media_type: "text/plain"

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

type: "text"
beta_managed_agents_redacted_block: object{ type }

Placeholder for content withheld by Anthropic model policy.

type: "redacted"
beta_managed_agents_retry_status_exhausted: object{ type }

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

type: "exhausted"
beta_managed_agents_retry_status_retrying: object{ type }

The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.

type: "retrying"
beta_managed_agents_retry_status_terminal: object{ type }

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

type: "terminal"
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"
beta_managed_agents_search_result_citations: object{ enabled }

Citation settings for a search result.

enabled: boolean

Whether citations are enabled for this search result.

beta_managed_agents_search_result_content: object{ text, type }

Text content within a search result.

text: string

The text content.

minLength1
type: "text"
beta_managed_agents_send_session_events: object{ data }

Events that were successfully sent to the session.

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"
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_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_error_event: object{ id, error, processed_at, type }

An error event indicating a problem occurred during session execution.

beta_managed_agents_session_event: 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 32 more

Union type for all event types in a session.

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_status_idle_event: object{ id, processed_at, stop_reason, type }

Indicates the agent has paused and is awaiting user input.

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

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_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_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_session_usage_snapshot: object{ active_seconds, cache_creation, cache_read_input_tokens, 4 more }

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

beta_managed_agents_span_model_request_end_event: object{ id, is_error, model_request_start_id, 3 more }

Emitted when a model request completes.

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

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

beta_managed_agents_system_message_event_params: object{ content, type }

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

content: array of BetaManagedAgentsSystemContentBlock { text, type }

System content blocks to append. Text-only.

text: string

The text content.

minLength1
type: "text"
type: "system.message"
beta_managed_agents_text_block: object{ text, type }

Regular text content.

text: string

The text content.

minLength1
type: "text"
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"
beta_managed_agents_text_rubric_params: object{ content, type }

Rubric content provided inline as text.

content: string

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

maxLength262144
type: "text"
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_url_document_source: object{ type, url }

Document referenced by URL.

type: "url"
url: string

URL of the document to fetch.

minLength1
beta_managed_agents_url_image_source: object{ type, url }

Image referenced by URL.

type: "url"
url: string

URL of the image to fetch.

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

beta_managed_agents_user_custom_tool_result_event_params: object{ custom_tool_use_id, type, content, is_error }

Parameters for providing the result of a custom tool execution.

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.

beta_managed_agents_user_define_outcome_event_params: object{ description, rubric, type, max_iterations }

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

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_interrupt_event_params: object{ type, session_thread_id }

Parameters for sending an interrupt to pause the agent.

type: "user.interrupt"
session_thread_id: optional string

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

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

A user message event in the session conversation.

beta_managed_agents_user_message_event_params: object{ content, type }

Parameters for sending a user message to the session.

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_tool_confirmation_event_params: object{ result, tool_use_id, type, deny_message }

Parameters for confirming or denying a tool execution request.

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.

minLength1
maxLength128
type: "user.tool_confirmation"
deny_message: optional string

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

maxLength10000
beta_managed_agents_user_tool_result_event_params: object{ tool_use_id, type, content, is_error }

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