events

Creates, updates, deletes, gets or lists an events resource.

Overview

Name	events
Type	Resource
Id	anthropic.sessions.events

Fields

The following fields are returned by SELECT queries:

list

Successful response (OK)

Name	Datatype	Description
id	string	Unique identifier for this event.
name	string	Name of the custom tool being called.
custom_tool_use_id	string	The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.
from_session_thread_id	string	Public `sthr_` ID of the thread that sent the message.
mcp_tool_use_id	string	The id of the `agent.mcp_tool_use` event this result corresponds to.
model_request_start_id	string	The id of the corresponding `span.model_request_start` event.
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.
session_thread_id	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.
to_session_thread_id	string	Public `sthr_` ID of the thread the message was sent to.
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](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.
agent_name	string	Name of the callable agent the thread runs.
from_agent_name	string	Name of the callable agent this message came from. Absent when received from the primary agent.
mcp_server_name	string	Name of the MCP server providing the tool.
to_agent_name	string	Name of the callable agent this message was sent to. Absent when sent to the primary agent.
▶agent	object	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.
▶budget	object	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.
▶content	array	Array of content blocks comprising the user message.
deny_message	string	Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.
description	string	What the agent should produce. Copied from the input event.
▶error	object	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.
evaluated_permission	string	The evaluated permission policy for this tool invocation. (allow, ask, deny)
▶evaluation	object	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).
explanation	string	Human-readable explanation of the verdict. For `needs_revision`, describes which criteria failed and why.
input	object	Input parameters for the tool call.
is_error	boolean	Whether the tool execution resulted in an error.
iteration	integer (int32)	0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc.
max_iterations	integer (int32)	Evaluate-then-revise cycles before giving up. Default 3, max 20.
metadata	object	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.
▶model_usage	object	Token usage for this model request.
processed_at	string (date-time)	Timestamp when the agent finished processing this message.
result	string	The confirmation result: 'allow' or 'deny'. (allow, deny)
▶rubric	object	How to grade the outcome. File rubrics are currently resolved to their text content; clients should handle both variants.
▶stop_reason	object	The agent completed its turn naturally and is ready for the next user message.
title	string	The session's new title. Present only when the update changed it.
type	string	(user.message)
▶usage	object	Aggregate token usage for this evaluation cycle. Sums across all grader model requests within the cycle.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
list	select	session_id	order, types[], created_at[gte], created_at[gt], created_at[lte], created_at[lt], anthropic-workspace-id
send	exec	session_id, events	anthropic-workspace-id

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
session_id	string	Path parameter session_id (example: sesn_011CZkZAtmR3yMPDzynEDxu7)
anthropic-workspace-id	string	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. (example: wrkspc_011CZkZaBF1tNoB5wlCeusgy)
created_at[gt]	string (date-time)	Return events created after this time (exclusive). Compared against the event's processed_at value.
created_at[gte]	string (date-time)	Return events created at or after this time (inclusive). Compared against the event's processed_at value.
created_at[lt]	string (date-time)	Return events created before this time (exclusive). Compared against the event's processed_at value.
created_at[lte]	string (date-time)	Return events created at or before this time (inclusive). Compared against the event's processed_at value.
order	string	Sort direction for results, ordered by the event's processed_at. Defaults to asc (chronological).
types[]	array	Filter by event type. Values match the type field on returned events (for example, user.message or agent.tool_use). Omit to return all event types.

SELECT examples

list

Successful response (OK)

SELECT
id,
name,
custom_tool_use_id,
from_session_thread_id,
mcp_tool_use_id,
model_request_start_id,
outcome_evaluation_start_id,
outcome_id,
session_thread_id,
to_session_thread_id,
tool_use_id,
agent_name,
from_agent_name,
mcp_server_name,
to_agent_name,
agent,
budget,
content,
deny_message,
description,
error,
evaluated_permission,
evaluation,
explanation,
input,
is_error,
iteration,
max_iterations,
metadata,
model_usage,
processed_at,
result,
rubric,
stop_reason,
title,
type,
usage
FROM anthropic.sessions.events
WHERE session_id = '{{ session_id }}' -- required
AND order = '{{ order }}'
AND "types[]" = '{{ types[] }}'
AND "created_at[gte]" = '{{ created_at[gte] }}'
AND "created_at[gt]" = '{{ created_at[gt] }}'
AND "created_at[lte]" = '{{ created_at[lte] }}'
AND "created_at[lt]" = '{{ created_at[lt] }}'
AND "anthropic-workspace-id" = '{{ anthropic-workspace-id }}'
;

Lifecycle Methods

send

Successful response (OK)

EXEC anthropic.sessions.events.send 
@session_id='{{ session_id }}' --required, 
@anthropic-workspace-id='{{ anthropic-workspace-id }}'
@@json=
'{
"events": "{{ events }}"
}'
;