Claude Platform Docs

Events

List Events
client.Beta.Sessions.Events.List(ctx, sessionID, params) (*PageCursor[BetaManagedAgentsSessionEventUnion], error)
GET/v1/sessions/{session_id}/events
Send Events
client.Beta.Sessions.Events.Send(ctx, sessionID, params) (*BetaManagedAgentsSendSessionEvents, error)
POST/v1/sessions/{session_id}/events
Stream Events
client.Beta.Sessions.Events.StreamEvents(ctx, sessionID, params) *ssestream.Stream[BetaManagedAgentsStreamSessionEventsUnion]
GET/v1/sessions/{session_id}/events/stream
Models
type BetaManagedAgentsAgentAutoEvaluatedPermissionUnion interface{…}

The server's per-invocation judgement under the auto permission policy. Its type always equals the event's top-level evaluated_permission. Open union: clients must tolerate unknown variants.

One of the following:
type BetaManagedAgentsAgentAutoEvaluatedPermissionAllow struct { Type: "allow" }

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

Type Allow
type BetaManagedAgentsAgentAutoEvaluatedPermissionAsk struct { Type: "ask"; ReasonCode }

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

Type Ask
ReasonCode 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
type BetaManagedAgentsAgentAutoEvaluatedPermissionDeny struct { Type: "deny"; ReasonCode }

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

Type Deny
ReasonCode 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
type BetaManagedAgentsAgentAutoEvaluatedPermissionAllow struct { Type: "allow" }

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

Type Allow
type BetaManagedAgentsAgentAutoEvaluatedPermissionAsk struct { Type: "ask"; ReasonCode }

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

Type Ask
ReasonCode 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
type BetaManagedAgentsAgentAutoEvaluatedPermissionDeny struct { Type: "deny"; ReasonCode }

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

Type Deny
ReasonCode 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
type BetaManagedAgentsAgentCustomToolUseEvent struct { 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 BetaManagedAgentsAgentCustomToolUseEventType
ID string

Unique identifier for this event.

Input map[string, any]

Input parameters for the tool call.

Name string

Name of the custom tool being called.

ProcessedAt Time

Timestamp when this tool use was processed.

formatdate-time
SessionThreadID string Optional

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.

type BetaManagedAgentsAgentEvaluatedPermission string
One of the following:
const BetaManagedAgentsAgentEvaluatedPermissionAllow BetaManagedAgentsAgentEvaluatedPermission = "allow"
const BetaManagedAgentsAgentEvaluatedPermissionAsk BetaManagedAgentsAgentEvaluatedPermission = "ask"
const BetaManagedAgentsAgentEvaluatedPermissionDeny BetaManagedAgentsAgentEvaluatedPermission = "deny"
type BetaManagedAgentsAgentMCPToolResultEvent struct { Type: "agent.mcp_tool_result"; ID; MCPToolUseID; /* 3 more */ }

Event representing the result of an MCP tool execution.

type BetaManagedAgentsAgentMCPToolUseEvent struct { Type: "agent.mcp_tool_use"; ID; Input; /* 6 more */ }

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

type BetaManagedAgentsAgentMessageEvent struct { Type: "agent.message"; ID; Content; ProcessedAt }

An agent response event in the session conversation.

Type BetaManagedAgentsAgentMessageEventType
ID string

Unique identifier for this event.

Content []BetaManagedAgentsAgentMessageEventContentUnion

Array of text blocks comprising the agent response.

One of the following:
type BetaManagedAgentsTextBlock struct { Type: "text"; Text }

Regular text content.

Type BetaManagedAgentsTextBlockType
Text string

The text content.

minLength1
type BetaManagedAgentsRedactedBlock struct { Type: "redacted" }

Placeholder for content withheld by Anthropic model policy.

Type BetaManagedAgentsRedactedBlockType
ProcessedAt Time

Timestamp when this response was generated.

formatdate-time
type BetaManagedAgentsAgentThinkingEvent struct { Type: "agent.thinking"; ID; ProcessedAt }

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

Type BetaManagedAgentsAgentThinkingEventType
ID string

Unique identifier for this event.

ProcessedAt Time

Timestamp when this thinking was produced.

formatdate-time
type BetaManagedAgentsAgentThreadContextCompactedEvent struct { Type: "agent.thread_context_compacted"; ID; ProcessedAt }

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

Type BetaManagedAgentsAgentThreadContextCompactedEventType
ID string

Unique identifier for this event.

ProcessedAt Time

Timestamp when compaction was processed.

formatdate-time
type BetaManagedAgentsAgentThreadMessageReceivedEvent struct { 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 BetaManagedAgentsAgentThreadMessageSentEvent struct { 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 BetaManagedAgentsAgentToolEvaluationUnion interface{…}

Names the resolved permission_policy that produced evaluated_permission, and under auto carries the judgement. Open union: clients must tolerate unknown variants.

One of the following:
type BetaManagedAgentsAgentToolEvaluationAlwaysAllow struct { Type: "always_allow" }

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

Type AlwaysAllow
type BetaManagedAgentsAgentToolEvaluationAlwaysAsk struct { Type: "always_ask" }

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

Type AlwaysAsk
type BetaManagedAgentsAgentToolEvaluationAuto struct { Type: "auto"; EvaluatedPermission }

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

type BetaManagedAgentsAgentToolEvaluationAlwaysAllow struct { Type: "always_allow" }

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

Type AlwaysAllow
type BetaManagedAgentsAgentToolEvaluationAlwaysAsk struct { Type: "always_ask" }

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

Type AlwaysAsk
type BetaManagedAgentsAgentToolEvaluationAuto struct { Type: "auto"; EvaluatedPermission }

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

type BetaManagedAgentsAgentToolResultEvent struct { Type: "agent.tool_result"; ID; ProcessedAt; /* 3 more */ }

Event representing the result of an agent tool execution.

type BetaManagedAgentsAgentToolUseEvent struct { Type: "agent.tool_use"; ID; Input; /* 5 more */ }

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

type BetaManagedAgentsBase64DocumentSource struct { Type: "base64"; Data; MediaType }

Base64-encoded document data.

Type BetaManagedAgentsBase64DocumentSourceType
Data string

Base64-encoded document data.

minLength1
MediaType string

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

minLength1
type BetaManagedAgentsBase64ImageSource struct { Type: "base64"; Data; MediaType }

Base64-encoded image data.

Type BetaManagedAgentsBase64ImageSourceType
Data string

Base64-encoded image data.

minLength1
MediaType string

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

minLength1
type BetaManagedAgentsBillingError struct { Type: "billing_error"; Message; RetryStatus }

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.

Type BetaManagedAgentsBillingErrorType
Message string

Human-readable error description.

RetryStatus BetaManagedAgentsBillingErrorRetryStatusUnion

What the client should do next.

One of the following:
type BetaManagedAgentsRetryStatusRetrying struct { Type: "retrying" }

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 BetaManagedAgentsRetryStatusRetryingType
type BetaManagedAgentsRetryStatusExhausted struct { Type: "exhausted" }

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

Type BetaManagedAgentsRetryStatusExhaustedType
type BetaManagedAgentsRetryStatusTerminal struct { Type: "terminal" }

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

Type BetaManagedAgentsRetryStatusTerminalType
type BetaManagedAgentsCredentialHostUnreachableError struct { Type: "credential_host_unreachable_error"; CredentialID; Message; /* 2 more */ }

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

type BetaManagedAgentsDocumentBlock struct { Type: "document"; Source; Context; Title }

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

type BetaManagedAgentsEventParamsUnion interface{…}

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

One of the following:
type BetaManagedAgentsFileDocumentSource struct { Type: "file"; FileID }

Document referenced by file ID.

Type BetaManagedAgentsFileDocumentSourceType
FileID string

ID of a previously uploaded file.

minLength1
type BetaManagedAgentsFileImageSource struct { Type: "file"; FileID }

Image referenced by file ID.

Type BetaManagedAgentsFileImageSourceType
FileID string

ID of a previously uploaded file.

minLength1
type BetaManagedAgentsFileRubric struct { Type: "file"; FileID }

Rubric referenced by a file uploaded via the Files API.

Type BetaManagedAgentsFileRubricType
FileID string

ID of the rubric file.

type BetaManagedAgentsFileRubricParams struct { Type: "file"; FileID }

Rubric referenced by a file uploaded via the Files API.

Type BetaManagedAgentsFileRubricParamsType
FileID string

ID of the rubric file.

type BetaManagedAgentsImageBlock struct { Type: "image"; Source }

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

type BetaManagedAgentsMaxWorkflowRunsWorkflowRunError struct { 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 MaxWorkflowRunsError
Message string

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

type BetaManagedAgentsMCPAuthenticationFailedError struct { Type: "mcp_authentication_failed_error"; MCPServerName; Message; RetryStatus }

Authentication to an MCP server failed.

type BetaManagedAgentsMCPConnectionFailedError struct { Type: "mcp_connection_failed_error"; MCPServerName; Message; RetryStatus }

Failed to connect to an MCP server.

type BetaManagedAgentsModelOverloadedError struct { Type: "model_overloaded_error"; Message; RetryStatus }

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

Type BetaManagedAgentsModelOverloadedErrorType
Message string

Human-readable error description.

RetryStatus BetaManagedAgentsModelOverloadedErrorRetryStatusUnion

What the client should do next.

One of the following:
type BetaManagedAgentsRetryStatusRetrying struct { Type: "retrying" }

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 BetaManagedAgentsRetryStatusRetryingType
type BetaManagedAgentsRetryStatusExhausted struct { Type: "exhausted" }

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

Type BetaManagedAgentsRetryStatusExhaustedType
type BetaManagedAgentsRetryStatusTerminal struct { Type: "terminal" }

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

Type BetaManagedAgentsRetryStatusTerminalType
type BetaManagedAgentsModelRateLimitedError struct { Type: "model_rate_limited_error"; Message; RetryStatus }

The model request was rate-limited.

Type BetaManagedAgentsModelRateLimitedErrorType
Message string

Human-readable error description.

RetryStatus BetaManagedAgentsModelRateLimitedErrorRetryStatusUnion

What the client should do next.

One of the following:
type BetaManagedAgentsRetryStatusRetrying struct { Type: "retrying" }

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 BetaManagedAgentsRetryStatusRetryingType
type BetaManagedAgentsRetryStatusExhausted struct { Type: "exhausted" }

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

Type BetaManagedAgentsRetryStatusExhaustedType
type BetaManagedAgentsRetryStatusTerminal struct { Type: "terminal" }

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

Type BetaManagedAgentsRetryStatusTerminalType
type BetaManagedAgentsModelRequestFailedError struct { Type: "model_request_failed_error"; Message; RetryStatus }

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

Type BetaManagedAgentsModelRequestFailedErrorType
Message string

Human-readable error description.

RetryStatus BetaManagedAgentsModelRequestFailedErrorRetryStatusUnion

What the client should do next.

One of the following:
type BetaManagedAgentsRetryStatusRetrying struct { Type: "retrying" }

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 BetaManagedAgentsRetryStatusRetryingType
type BetaManagedAgentsRetryStatusExhausted struct { Type: "exhausted" }

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

Type BetaManagedAgentsRetryStatusExhaustedType
type BetaManagedAgentsRetryStatusTerminal struct { Type: "terminal" }

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

Type BetaManagedAgentsRetryStatusTerminalType
type BetaManagedAgentsPlainTextDocumentSource struct { Type: "text"; Data; MediaType }

Plain text document content.

Type BetaManagedAgentsPlainTextDocumentSourceType
Data string

The plain text content.

minLength1
MediaType BetaManagedAgentsPlainTextDocumentSourceMediaType

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

type BetaManagedAgentsProgramWorkflowRunError struct { Type: "program_error"; Message }

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

Type ProgramError
Message string

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

type BetaManagedAgentsRedactedBlock struct { Type: "redacted" }

Placeholder for content withheld by Anthropic model policy.

Type BetaManagedAgentsRedactedBlockType
type BetaManagedAgentsRepositoryAuthenticationError struct { Type: "repository_authentication_error"; Message; RepositoryURL; RetryStatus }

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

type BetaManagedAgentsRepositoryCheckoutError struct { Type: "repository_checkout_error"; Message; RepositoryURL; RetryStatus }

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

type BetaManagedAgentsRepositoryCloneError struct { Type: "repository_clone_error"; Message; RepositoryURL; RetryStatus }

The repository could not be cloned.

type BetaManagedAgentsRepositoryForbiddenError struct { Type: "repository_forbidden_error"; Message; RepositoryURL; RetryStatus }

The repository host refused access to the repository.

type BetaManagedAgentsRepositoryNotFoundError struct { Type: "repository_not_found_error"; Message; RepositoryURL; RetryStatus }

The repository host reported the repository as not found.

type BetaManagedAgentsRetryStatusExhausted struct { Type: "exhausted" }

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

Type BetaManagedAgentsRetryStatusExhaustedType
type BetaManagedAgentsRetryStatusRetrying struct { Type: "retrying" }

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 BetaManagedAgentsRetryStatusRetryingType
type BetaManagedAgentsRetryStatusTerminal struct { Type: "terminal" }

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

Type BetaManagedAgentsRetryStatusTerminalType
type BetaManagedAgentsSearchResultBlock struct { Type: "search_result"; Citations; Content; /* 2 more */ }

A block containing a web search result.

Type BetaManagedAgentsSearchResultBlockType
Citations BetaManagedAgentsSearchResultCitations

Citation settings for this search result.

Enabled bool

Whether citations are enabled for this search result.

Content []BetaManagedAgentsSearchResultContent

Array of text content blocks from the search result.

Type BetaManagedAgentsSearchResultContentType
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
type BetaManagedAgentsSearchResultCitations struct { Enabled }

Citation settings for a search result.

Enabled bool

Whether citations are enabled for this search result.

type BetaManagedAgentsSearchResultContent struct { Type: "text"; Text }

Text content within a search result.

Type BetaManagedAgentsSearchResultContentType
Text string

The text content.

minLength1
type BetaManagedAgentsSendSessionEvents struct { Data }

Events that were successfully sent to the session.

type BetaManagedAgentsSessionBudgetReached struct { 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 BetaManagedAgentsSessionBudgetReachedType
type BetaManagedAgentsSessionDeletedEvent struct { Type: "session.deleted"; ID; ProcessedAt }

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

Type BetaManagedAgentsSessionDeletedEventType
ID string

Unique identifier for this event.

ProcessedAt Time

Timestamp when the session was deleted.

formatdate-time
type BetaManagedAgentsSessionEndTurn struct { Type: "end_turn" }

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

Type BetaManagedAgentsSessionEndTurnType
type BetaManagedAgentsSessionErrorEvent struct { Type: "session.error"; ID; Error; ProcessedAt }

An error event indicating a problem occurred during session execution.

type BetaManagedAgentsSessionEventUnion interface{…}

Union type for all event types in a session.

One of the following:
type BetaManagedAgentsSessionEventType string

The type of a session event.

One of the following:
type BetaManagedAgentsSessionRefusal struct { Type: "refusal" }

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

Type Refusal
type BetaManagedAgentsSessionRefusalStopDetails struct { Type: "refusal"; Category; Explanation }

Structured information about a refusal.

Type Refusal
Category BetaManagedAgentsSessionRefusalStopDetailsCategory

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:
const BetaManagedAgentsSessionRefusalStopDetailsCategoryCyber BetaManagedAgentsSessionRefusalStopDetailsCategory = "cyber"
const BetaManagedAgentsSessionRefusalStopDetailsCategoryBio BetaManagedAgentsSessionRefusalStopDetailsCategory = "bio"
const BetaManagedAgentsSessionRefusalStopDetailsCategoryFrontierLLM BetaManagedAgentsSessionRefusalStopDetailsCategory = "frontier_llm"
const BetaManagedAgentsSessionRefusalStopDetailsCategoryReasoningExtraction BetaManagedAgentsSessionRefusalStopDetailsCategory = "reasoning_extraction"
const BetaManagedAgentsSessionRefusalStopDetailsCategoryGeneralHarms BetaManagedAgentsSessionRefusalStopDetailsCategory = "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.

type BetaManagedAgentsSessionRequiresAction struct { Type: "requires_action"; EventIDs }

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 BetaManagedAgentsSessionRequiresActionType
EventIDs []string

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

type BetaManagedAgentsSessionRetriesExhausted struct { Type: "retries_exhausted" }

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

Type BetaManagedAgentsSessionRetriesExhaustedType
type BetaManagedAgentsSessionStatusIdleEvent struct { Type: "session.status_idle"; ID; ProcessedAt; /* 2 more */ }

Indicates the agent has paused and is awaiting user input.

type BetaManagedAgentsSessionStatusRescheduledEvent struct { Type: "session.status_rescheduled"; ID; ProcessedAt }

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

Type BetaManagedAgentsSessionStatusRescheduledEventType
ID string

Unique identifier for this event.

ProcessedAt Time

Timestamp of status change.

formatdate-time
type BetaManagedAgentsSessionStatusRunningEvent struct { Type: "session.status_running"; ID; ProcessedAt }

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

Type BetaManagedAgentsSessionStatusRunningEventType
ID string

Unique identifier for this event.

ProcessedAt Time

Timestamp of status change.

formatdate-time
type BetaManagedAgentsSessionStatusTerminatedEvent struct { Type: "session.status_terminated"; ID; ProcessedAt }

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

Type BetaManagedAgentsSessionStatusTerminatedEventType
ID string

Unique identifier for this event.

ProcessedAt Time

Timestamp of status change.

formatdate-time
type BetaManagedAgentsSessionThreadCreatedEvent struct { Type: "session.thread_created"; ID; AgentName; /* 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 BetaManagedAgentsSessionThreadCreatedEventType
ID string

Unique identifier for this event.

AgentName string

Name of the callable agent the thread runs.

ProcessedAt Time

Timestamp when the thread was created.

formatdate-time
SessionThreadID string

Public sthr_ ID of the newly created thread.

WorkflowRunID string

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

type BetaManagedAgentsSessionThreadStatusIdleEvent struct { Type: "session.thread_status_idle"; ID; AgentName; /* 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 BetaManagedAgentsSessionThreadStatusRescheduledEvent struct { Type: "session.thread_status_rescheduled"; ID; AgentName; /* 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 BetaManagedAgentsSessionThreadStatusRescheduledEventType
ID string

Unique identifier for this event.

AgentName string

Name of the agent the thread runs.

ProcessedAt Time

Timestamp of the status transition.

formatdate-time
SessionThreadID string

Public sthr_ ID of the thread that is retrying.

type BetaManagedAgentsSessionThreadStatusRunningEvent struct { Type: "session.thread_status_running"; ID; AgentName; /* 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 BetaManagedAgentsSessionThreadStatusRunningEventType
ID string

Unique identifier for this event.

AgentName string

Name of the agent the thread runs.

ProcessedAt Time

Timestamp of the status transition.

formatdate-time
SessionThreadID string

Public sthr_ ID of the thread that started running.

type BetaManagedAgentsSessionThreadStatusTerminatedEvent struct { Type: "session.thread_status_terminated"; ID; AgentName; /* 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 BetaManagedAgentsSessionThreadStatusTerminatedEventType
ID string

Unique identifier for this event.

AgentName string

Name of the agent the thread runs.

ProcessedAt Time

Timestamp of the status transition.

formatdate-time
SessionThreadID string

Public sthr_ ID of the thread that terminated.

type BetaManagedAgentsSessionUsageSnapshot struct { ActiveSeconds; CacheCreation; CacheReadInputTokens; /* 4 more */ }

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

type BetaManagedAgentsSpanModelRequestEndEvent struct { Type: "span.model_request_end"; ID; IsError; /* 3 more */ }

Emitted when a model request completes.

type BetaManagedAgentsSpanModelRequestStartEvent struct { Type: "span.model_request_start"; ID; ProcessedAt }

Emitted when a model request is initiated by the agent.

Type BetaManagedAgentsSpanModelRequestStartEventType
ID string

Unique identifier for this event.

ProcessedAt Time

Timestamp when the model request started.

formatdate-time
type BetaManagedAgentsSpanModelUsage struct { CacheCreationInputTokens; CacheReadInputTokens; InputTokens; /* 2 more */ }

Token usage for a single model request.

CacheCreationInputTokens int64

Tokens used to create prompt cache in this request.

formatint32
CacheReadInputTokens int64

Tokens read from prompt cache in this request.

formatint32
InputTokens int64

Input tokens consumed by this request.

formatint32
OutputTokens int64

Output tokens generated by this request.

formatint32
Speed BetaManagedAgentsSpanModelUsageSpeed Optional

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:
const BetaManagedAgentsSpanModelUsageSpeedStandard BetaManagedAgentsSpanModelUsageSpeed = "standard"
const BetaManagedAgentsSpanModelUsageSpeedFast BetaManagedAgentsSpanModelUsageSpeed = "fast"
type BetaManagedAgentsSpanOutcomeEvaluationEndEvent struct { 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 BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent struct { 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 BetaManagedAgentsSpanOutcomeEvaluationOngoingEventType
ID string

Unique identifier for this event.

Iteration int64

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

formatint32
OutcomeID string

The outc_ ID of the outcome being evaluated.

ProcessedAt Time

Timestamp when this heartbeat was emitted.

formatdate-time
type BetaManagedAgentsSpanOutcomeEvaluationStartEvent struct { Type: "span.outcome_evaluation_start"; ID; Iteration; /* 2 more */ }

Emitted when an outcome evaluation cycle begins.

Type BetaManagedAgentsSpanOutcomeEvaluationStartEventType
ID string

Unique identifier for this event.

Iteration int64

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

formatint32
OutcomeID string

The outc_ ID of the outcome being evaluated.

ProcessedAt Time

Timestamp when outcome evaluation started.

formatdate-time
type BetaManagedAgentsStreamSessionEventsUnion interface{…}

Server-sent event in the session stream.

One of the following:
type BetaManagedAgentsSystemMessageEventParams struct { Type: "system.message"; Content }

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.

Type BetaManagedAgentsSystemMessageEventParamsType
Content []BetaManagedAgentsSystemContentBlockParam

System content blocks to append. Text-only.

Type BetaManagedAgentsSystemContentBlockType
Text string

The text content.

minLength1
type BetaManagedAgentsTextBlock struct { Type: "text"; Text }

Regular text content.

Type BetaManagedAgentsTextBlockType
Text string

The text content.

minLength1
type BetaManagedAgentsTextRubric struct { Type: "text"; Content }

Rubric content provided inline as text.

Type BetaManagedAgentsTextRubricType
Content string

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

type BetaManagedAgentsTextRubricParams struct { Type: "text"; Content }

Rubric content provided inline as text.

Type BetaManagedAgentsTextRubricParamsType
Content string

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

maxLength262144
type BetaManagedAgentsThreadLimitWorkflowRunError struct { Type: "thread_limit_error"; Message }

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

Type ThreadLimitError
Message string

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

type BetaManagedAgentsTimeoutWorkflowRunError struct { Type: "timeout_error"; Message }

The run reached its time limit.

Type TimeoutError
Message string

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

type BetaManagedAgentsUnknownError struct { Type: "unknown_error"; Message; RetryStatus }

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.

Type BetaManagedAgentsUnknownErrorType
Message string

Human-readable error description.

RetryStatus BetaManagedAgentsUnknownErrorRetryStatusUnion

What the client should do next.

One of the following:
type BetaManagedAgentsRetryStatusRetrying struct { Type: "retrying" }

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 BetaManagedAgentsRetryStatusRetryingType
type BetaManagedAgentsRetryStatusExhausted struct { Type: "exhausted" }

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

Type BetaManagedAgentsRetryStatusExhaustedType
type BetaManagedAgentsRetryStatusTerminal struct { Type: "terminal" }

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

Type BetaManagedAgentsRetryStatusTerminalType
type BetaManagedAgentsUnknownWorkflowRunError struct { Type: "unknown_error"; Message }

A failure that has no type of its own.

Type UnknownError
Message string

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

type BetaManagedAgentsURLDocumentSource struct { Type: "url"; URL }

Document referenced by URL.

Type BetaManagedAgentsURLDocumentSourceType
URL string

URL of the document to fetch.

minLength1
type BetaManagedAgentsURLImageSource struct { Type: "url"; URL }

Image referenced by URL.

Type BetaManagedAgentsURLImageSourceType
URL string

URL of the image to fetch.

minLength1
type BetaManagedAgentsUserCustomToolResultEvent struct { Type: "user.custom_tool_result"; ID; CustomToolUseID; /* 4 more */ }

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

type BetaManagedAgentsUserCustomToolResultEventParams struct { Type: "user.custom_tool_result"; CustomToolUseID; Content; IsError }

Parameters for providing the result of a custom tool execution.

type BetaManagedAgentsUserDefineOutcomeEvent struct { 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 BetaManagedAgentsUserDefineOutcomeEventParams struct { Type: "user.define_outcome"; Description; Rubric; MaxIterations }

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

type BetaManagedAgentsUserInterruptEvent struct { Type: "user.interrupt"; ID; ProcessedAt; SessionThreadID }

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

Type BetaManagedAgentsUserInterruptEventType
ID string

Unique identifier for this event.

ProcessedAt Time Optional

Timestamp when the interrupt was processed.

formatdate-time
SessionThreadID string Optional

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.

type BetaManagedAgentsUserInterruptEventParams struct { Type: "user.interrupt"; SessionThreadID }

Parameters for sending an interrupt to pause the agent.

Type BetaManagedAgentsUserInterruptEventParamsType
SessionThreadID string Optional

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.

type BetaManagedAgentsUserMessageEvent struct { Type: "user.message"; ID; Content; ProcessedAt }

A user message event in the session conversation.

type BetaManagedAgentsUserMessageEventParams struct { Type: "user.message"; Content }

Parameters for sending a user message to the session.

type BetaManagedAgentsUserToolConfirmationEvent struct { Type: "user.tool_confirmation"; ID; Result; /* 4 more */ }

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

Type BetaManagedAgentsUserToolConfirmationEventType
ID string

Unique identifier for this event.

Result BetaManagedAgentsUserToolConfirmationEventResult

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

One of the following:
const BetaManagedAgentsUserToolConfirmationEventResultAllow BetaManagedAgentsUserToolConfirmationEventResult = "allow"
const BetaManagedAgentsUserToolConfirmationEventResultDeny BetaManagedAgentsUserToolConfirmationEventResult = "deny"
ToolUseID 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.

DenyMessage string Optional

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

maxLength10000
ProcessedAt Time Optional

Timestamp when the confirmation was processed.

formatdate-time
SessionThreadID string Optional

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

type BetaManagedAgentsUserToolConfirmationEventParams struct { Type: "user.tool_confirmation"; Result; ToolUseID; DenyMessage }

Parameters for confirming or denying a tool execution request.

Type BetaManagedAgentsUserToolConfirmationEventParamsType
Result BetaManagedAgentsUserToolConfirmationEventParamsResult

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

One of the following:
const BetaManagedAgentsUserToolConfirmationEventParamsResultAllow BetaManagedAgentsUserToolConfirmationEventParamsResult = "allow"
const BetaManagedAgentsUserToolConfirmationEventParamsResultDeny BetaManagedAgentsUserToolConfirmationEventParamsResult = "deny"
ToolUseID 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
DenyMessage string Optional

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

maxLength10000
type BetaManagedAgentsUserToolResultEventParams struct { Type: "user.tool_result"; ToolUseID; Content; IsError }

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.

type BetaManagedAgentsWorkflowRunCreatedEvent struct { 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 WorkflowRunCreated
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 string

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

Phases []BetaManagedAgentsWorkflowRunPhase

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 string

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

ProcessedAt Time

Timestamp when this event was processed.

formatdate-time
WorkflowRunID string

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

type BetaManagedAgentsWorkflowRunErrorUnion interface{…}

Why a workflow run did not finish, or was not created. More types may be added. On workflow_run.status_ended, for a type you do not recognize, rely on the event's result.type.

One of the following:
type BetaManagedAgentsWorkflowRunErrorEvent struct { 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 WorkflowRunError
ID string

Unique identifier for this event.

Error BetaManagedAgentsWorkflowRunErrorUnion

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

One of the following:
ProcessedAt Time

Timestamp when this event was processed.

formatdate-time
WorkflowRunID string

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

type BetaManagedAgentsWorkflowRunPhase struct { ID; Description; Name }

A phase that a workflow run's plan declares.

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 string

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

type BetaManagedAgentsWorkflowRunPhaseEndedEvent struct { Type: "workflow_run.phase_ended"; ID; PhaseStartedID; /* 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 WorkflowRunPhaseEnded
ID string

Unique identifier for this event.

PhaseStartedID string

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

ProcessedAt Time

Timestamp when this event was processed.

formatdate-time
WorkflowRunID string

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

WorkflowRunPhaseID string

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

type BetaManagedAgentsWorkflowRunPhaseStartedEvent struct { Type: "workflow_run.phase_started"; ID; ProcessedAt; /* 2 more */ }

A workflow run's plan entered a phase.

Type WorkflowRunPhaseStarted
ID string

Unique identifier for this event.

ProcessedAt Time

Timestamp when this event was processed.

formatdate-time
WorkflowRunID string

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

WorkflowRunPhaseID string

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

type BetaManagedAgentsWorkflowRunResultUnion interface{…}

How a workflow run ended.

One of the following:
type BetaManagedAgentsWorkflowRunResultCompleted struct { Type: "completed" }

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

Type Completed
type BetaManagedAgentsWorkflowRunResultError struct { Type: "error"; Error }

The run failed or reached its time limit.

Type Error
Error BetaManagedAgentsWorkflowRunErrorUnion

Why the run did not finish.

One of the following:
type BetaManagedAgentsWorkflowRunResultStopped struct { Type: "stopped" }

The agent stopped the run.

Type Stopped
type BetaManagedAgentsWorkflowRunResultCompleted struct { Type: "completed" }

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

Type Completed
type BetaManagedAgentsWorkflowRunResultError struct { Type: "error"; Error }

The run failed or reached its time limit.

Type Error
Error BetaManagedAgentsWorkflowRunErrorUnion

Why the run did not finish.

One of the following:
type BetaManagedAgentsWorkflowRunResultStopped struct { Type: "stopped" }

The agent stopped the run.

Type Stopped
type BetaManagedAgentsWorkflowRunStatusEndedEvent struct { Type: "workflow_run.status_ended"; ID; ProcessedAt; /* 2 more */ }

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

type BetaManagedAgentsWorkflowRunStatusIdleEvent struct { Type: "workflow_run.status_idle"; ID; ProcessedAt; WorkflowRunID }

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 WorkflowRunStatusIdle
ID string

Unique identifier for this event.

ProcessedAt Time

Timestamp when this event was processed.

formatdate-time
WorkflowRunID string

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

type BetaManagedAgentsWorkflowRunStatusRunningEvent struct { Type: "workflow_run.status_running"; ID; ProcessedAt; WorkflowRunID }

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 WorkflowRunStatusRunning
ID string

Unique identifier for this event.

ProcessedAt Time

Timestamp when this event was processed.

formatdate-time
WorkflowRunID string

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