List Events

GET/v1/sessions/{session_id}/events

List the persisted event history of a session, in chronological order (oldest first).

Path Parameters

Parameter	Type	Required	Description
session_id	string	✅	The session ID (sess_...)

Request Examples

Python

from anthropic import Anthropic

client = Anthropic(
    api_key="sk-sb-YOUR_KEY",
    base_url="https://api.sandbase.ai"
)

page = client.beta.sessions.events.list(session_id="sess_01abc...")
for event in page.data:
    print(f"{event.type}: {event.id}")

cURL

curl "https://api.sandbase.ai/v1/sessions/sess_01abc.../events" \
  -H "Authorization: Bearer sk-sb-YOUR_KEY"

Response

Each event shares a common envelope. Fields not relevant to a given event type are null or zero.

{
  "data": [
    {
      "id": "sevt_01abc...",
      "type": "user.message",
      "content": [{ "type": "text", "text": "Where is my order #1234?" }],
      "stop_reason": null,
      "model_used": null,
      "tokens_in": 0,
      "tokens_out": 0,
      "duration_ms": null,
      "processed_at": "2026-05-29T10:00:00Z",
      "created_at": "2026-05-29T10:00:00Z"
    },
    {
      "id": "sevt_02def...",
      "type": "agent.message",
      "content": [{ "type": "text", "text": "Let me look up order #1234 for you." }],
      "stop_reason": null,
      "model_used": "claude-sonnet-4",
      "tokens_in": 1200,
      "tokens_out": 80,
      "duration_ms": 1840,
      "processed_at": "2026-05-29T10:00:02Z",
      "created_at": "2026-05-29T10:00:02Z"
    }
  ]
}

Event Envelope

Field	Type	Description
id	string	Event ID (sevt_...)
type	string	Event type (see below)
content	array | object | null	Type-specific payload (e.g. message content blocks)
stop_reason	object | null	Present on session.status_idle
model_used	string | null	Model that produced the event, when applicable
tokens_in	integer	Input tokens for this event (0 when N/A)
tokens_out	integer	Output tokens for this event (0 when N/A)
duration_ms	integer | null	Processing time, when applicable
processed_at	string | null	RFC 3339 timestamp when processed
created_at	string	RFC 3339 timestamp

Event Types

Supported today

User events

Type	Description
user.message	A user message
user.interrupt	Interrupt that pauses the agent

Agent events

Type	Description
agent.message	Agent's text response
agent.tool_use	Agent invokes a built-in tool
agent.tool_result	Result of a built-in tool execution
agent.mcp_tool_use	Agent invokes an MCP tool
agent.custom_tool_use	Agent calls a custom tool

Session status events

Type	Description
session.status_running	Session is actively running
session.status_idle	Agent paused, awaiting input (carries stop_reason)
session.error	An error occurred during execution

Stop Reasons (session.status_idle)

stop_reason.type	Meaning
end_turn	Agent completed its turn naturally, ready for the next message
requires_action	Agent is blocked on user input
user_interrupt	The turn was interrupted by the user

Roadmap

The following event types and fields exist in the Claude API and are reserved for compatibility, but are not yet emitted by SandBase:

• user.tool_confirmation, user.custom_tool_result (tool permission + custom tool flows)
• agent.thinking, agent.tool_result enrichments, agent.mcp_tool_result
• session.status_rescheduled, session.status_terminated, session.updated, session.deleted
• Multiagent / outcome events: session.thread_*, agent.thread_*, user.define_outcome, span.*
• Cursor pagination (limit, order, page, next_page) and the types / created_at_* filters

Clients should ignore unrecognized event types and tolerate missing fields.

Errors

Status	Type	Description
401	authentication_error	Invalid or missing API key
404	not_found	Session not found