Skip to main content

thread_events

Creates, updates, deletes, gets or lists a thread_events resource.

Overview​

Namethread_events
TypeResource
Idanthropic.sessions.thread_events

Fields​

The following fields are returned by SELECT queries:

Successful response (OK)

NameDatatypeDescription
idstringUnique identifier for this event.
namestringName of the custom tool being called.
custom_tool_use_idstringThe 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_idstringPublic `sthr_` ID of the thread that sent the message.
mcp_tool_use_idstringThe id of the `agent.mcp_tool_use` event this result corresponds to.
model_request_start_idstringThe id of the corresponding `span.model_request_start` event.
outcome_evaluation_start_idstringThe id of the corresponding `span.outcome_evaluation_start` event.
outcome_idstringThe `outc_` ID of the outcome being evaluated.
session_thread_idstringIf 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_idstringPublic `sthr_` ID of the thread the message was sent to.
tool_use_idstringThe 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_namestringName of the callable agent the thread runs.
from_agent_namestringName of the callable agent this message came from. Absent when received from the primary agent.
mcp_server_namestringName of the MCP server providing the tool.
to_agent_namestringName of the callable agent this message was sent to. Absent when sent to the primary agent.
â–¶agentobjectThe 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.
â–¶budgetobjectThe 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.
â–¶contentarrayArray of content blocks comprising the user message.
deny_messagestringOptional message providing context for a 'deny' decision. Only allowed when result is 'deny'.
descriptionstringWhat the agent should produce. Copied from the input event.
â–¶errorobjectAn 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_permissionstringThe evaluated permission policy for this tool invocation. (allow, ask, deny)
â–¶evaluationobjectWhich 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).
explanationstringHuman-readable explanation of the verdict. For `needs_revision`, describes which criteria failed and why.
inputobjectInput parameters for the tool call.
is_errorbooleanWhether the tool execution resulted in an error.
iterationinteger (int32)0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc.
max_iterationsinteger (int32)Evaluate-then-revise cycles before giving up. Default 3, max 20.
metadataobjectThe 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_usageobjectToken usage for this model request.
processed_atstring (date-time)Timestamp when the agent finished processing this message.
resultstringThe confirmation result: 'allow' or 'deny'. (allow, deny)
â–¶rubricobjectHow to grade the outcome. File rubrics are currently resolved to their text content; clients should handle both variants.
â–¶stop_detailsobjectStructured information about why the session stopped. `null` when there is nothing more to report.
â–¶stop_reasonobjectThe agent completed its turn naturally and is ready for the next user message.
titlestringThe session's new title. Present only when the update changed it.
typestring (user.message)
â–¶usageobjectAggregate token usage for this evaluation cycle. Sums across all grader model requests within the cycle.

Methods​

The following methods are available for this resource:

NameAccessible byRequired ParamsOptional ParamsDescription
listselectsession_id, thread_idanthropic-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.

NameDatatypeDescription
session_idstring (example: sesn_011CZkZAtmR3yMPDzynEDxu7)
thread_idstring (example: sthr_011CZkZVWa6oIjw0rgXZpnBt)
anthropic-workspace-idstringOptional 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)

SELECT examples​

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_details,
stop_reason,
title,
type,
usage
FROM anthropic.sessions.thread_events
WHERE session_id = '{{ session_id }}' -- required
AND thread_id = '{{ thread_id }}' -- required
AND "anthropic-workspace-id" = '{{ anthropic-workspace-id }}'
;