Claude Platform Docs

Events

List Events
GET/v1/sessions/{session_id}/events
Send Events
POST/v1/sessions/{session_id}/events
Stream Events
GET/v1/sessions/{session_id}/events/stream
Models
BetaManagedAgentsAgentCustomToolUseEvent 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 or null

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

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

Event representing the result of an MCP tool execution.

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

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

BetaManagedAgentsAgentMessageEvent object{ id, content, processed_at, type }

An agent response event in the session conversation.

BetaManagedAgentsAgentThinkingEvent 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"
BetaManagedAgentsAgentThreadContextCompactedEvent 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"
BetaManagedAgentsAgentThreadMessageReceivedEvent 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.

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

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

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

Event representing the result of an agent tool execution.

BetaManagedAgentsAgentToolUseEvent 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 or null

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.

BetaManagedAgentsBase64DocumentSource 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"
BetaManagedAgentsBase64ImageSource 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"
BetaManagedAgentsBillingError 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.

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

BetaManagedAgentsDocumentBlock object{ source, type, context, title }

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

BetaManagedAgentsEventParams = BetaManagedAgentsUserMessageEventParams { content, type } 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.

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

Document referenced by file ID.

file_id: string

ID of a previously uploaded file.

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

Image referenced by file ID.

file_id: string

ID of a previously uploaded file.

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

Rubric referenced by a file uploaded via the Files API.

file_id: string

ID of the rubric file.

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

Rubric referenced by a file uploaded via the Files API.

file_id: string

ID of the rubric file.

type: "file"
BetaManagedAgentsImageBlock object{ source, type }

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

BetaManagedAgentsMCPAuthenticationFailedError object{ mcp_server_name, message, retry_status, type }

Authentication to an MCP server failed.

BetaManagedAgentsMCPConnectionFailedError object{ mcp_server_name, message, retry_status, type }

Failed to connect to an MCP server.

BetaManagedAgentsModelOverloadedError object{ message, retry_status, type }

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

BetaManagedAgentsModelRateLimitedError object{ message, retry_status, type }

The model request was rate-limited.

BetaManagedAgentsModelRequestFailedError object{ message, retry_status, type }

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

BetaManagedAgentsPlainTextDocumentSource 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"
BetaManagedAgentsRedactedBlock object{ type }

Placeholder for content withheld by Anthropic model policy.

type: "redacted"
BetaManagedAgentsRetryStatusExhausted object{ type }

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

type: "exhausted"
BetaManagedAgentsRetryStatusRetrying 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"
BetaManagedAgentsRetryStatusTerminal object{ type }

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

type: "terminal"
BetaManagedAgentsSearchResultBlock object{ citations, content, source, 2 more }

A block containing a web search result.

citations: BetaManagedAgentsSearchResultCitations { 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"
BetaManagedAgentsSearchResultCitations object{ enabled }

Citation settings for a search result.

enabled: boolean

Whether citations are enabled for this search result.

BetaManagedAgentsSearchResultContent object{ text, type }

Text content within a search result.

text: string

The text content.

minLength1
type: "text"
BetaManagedAgentsSendSessionEvents object{ data }

Events that were successfully sent to the session.

BetaManagedAgentsSessionBudgetReached 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"
BetaManagedAgentsSessionDeletedEvent 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"
BetaManagedAgentsSessionEndTurn object{ type }

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

type: "end_turn"
BetaManagedAgentsSessionErrorEvent object{ id, error, processed_at, type }

An error event indicating a problem occurred during session execution.

BetaManagedAgentsSessionEvent = 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.

One of the following:
BetaManagedAgentsSessionRequiresAction 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"
BetaManagedAgentsSessionRetriesExhausted object{ type }

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

type: "retries_exhausted"
BetaManagedAgentsSessionStatusIdleEvent object{ id, processed_at, stop_reason, type }

Indicates the agent has paused and is awaiting user input.

BetaManagedAgentsSessionStatusRescheduledEvent 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"
BetaManagedAgentsSessionStatusRunningEvent 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"
BetaManagedAgentsSessionStatusTerminatedEvent 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"
BetaManagedAgentsSessionThreadCreatedEvent 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"
BetaManagedAgentsSessionThreadStatusIdleEvent 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.

BetaManagedAgentsSessionThreadStatusRescheduledEvent 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"
BetaManagedAgentsSessionThreadStatusRunningEvent 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"
BetaManagedAgentsSessionThreadStatusTerminatedEvent 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"
BetaManagedAgentsSessionUsageSnapshot object{ active_seconds, cache_creation, cache_read_input_tokens, 4 more }

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

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

Emitted when a model request completes.

BetaManagedAgentsSpanModelRequestStartEvent 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"
BetaManagedAgentsSpanModelUsage 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" or null

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

One of the following:
"standard"
"fast"
BetaManagedAgentsSpanOutcomeEvaluationEndEvent 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.

BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent 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"
BetaManagedAgentsSpanOutcomeEvaluationStartEvent 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"
BetaManagedAgentsStreamSessionEvents = BetaManagedAgentsUserMessageEvent { id, content, type, processed_at } or BetaManagedAgentsUserInterruptEvent { id, type, processed_at, session_thread_id } or BetaManagedAgentsUserToolConfirmationEvent { id, result, tool_use_id, 4 more } or 34 more

Server-sent event in the session stream.

One of the following:
BetaManagedAgentsSystemMessageEventParams 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"
BetaManagedAgentsTextBlock object{ text, type }

Regular text content.

text: string

The text content.

minLength1
type: "text"
BetaManagedAgentsTextRubric 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"
BetaManagedAgentsTextRubricParams 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"
BetaManagedAgentsUnknownError 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.

BetaManagedAgentsURLDocumentSource object{ type, url }

Document referenced by URL.

type: "url"
url: string

URL of the document to fetch.

minLength1
BetaManagedAgentsURLImageSource object{ type, url }

Image referenced by URL.

type: "url"
url: string

URL of the image to fetch.

minLength1
BetaManagedAgentsUserCustomToolResultEvent object{ id, custom_tool_use_id, type, 4 more }

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

BetaManagedAgentsUserCustomToolResultEventParams object{ custom_tool_use_id, type, content, is_error }

Parameters for providing the result of a custom tool execution.

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

BetaManagedAgentsUserDefineOutcomeEventParams object{ description, rubric, type, max_iterations }

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

BetaManagedAgentsUserInterruptEvent 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 or null

A timestamp in RFC 3339 format

formatdate-time
session_thread_id: optional string or null

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

BetaManagedAgentsUserInterruptEventParams object{ type, session_thread_id }

Parameters for sending an interrupt to pause the agent.

type: "user.interrupt"
session_thread_id: optional string or null

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

BetaManagedAgentsUserMessageEvent object{ id, content, type, processed_at }

A user message event in the session conversation.

BetaManagedAgentsUserMessageEventParams object{ content, type }

Parameters for sending a user message to the session.

BetaManagedAgentsUserToolConfirmationEvent object{ id, result, tool_use_id, 4 more }

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

BetaManagedAgentsUserToolConfirmationEventParams 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 or null

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

maxLength10000
BetaManagedAgentsUserToolResultEventParams 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.