HTTP API
Session events
Durable events, live previews, and the events used by application UIs.
The durable session log is available through sessions.events. The SSE route
publishes a client-safe projection of that log plus ephemeral previews; it
is not the raw log. System messages and internal model request data are not
browser transcript events. See streaming protocol for
formats, tokens, and cursors, and sessions for lifecycle.
Event catalogue
This table covers commonly used events. Some are visible only through authorized server reads. Use each schema for exact fields and streaming protocol for browser events.
| Event | When |
|---|---|
user.message | A message you sent. Carries the delivery mode, any attachments and any message metadata. |
agent.message | What the model said. Durable; this is the one to render and to store. |
agent.text_delta | Ephemeral typing preview. Never persisted: a client that reconnects sees the agent.message instead. |
agent.reasoning_delta, tool.call.input_delta | The same, for reasoning and for tool arguments being composed. |
tool.call.started / .completed | Every tool call, whoever runs it, with its input and its result. |
tool.call.pending / .decision | A call waiting on a person, and the answer. |
model.request.started / .completed / .failed / .retried | One per model call, per fallback rung. Tokens, cache counters and cost land on .completed. |
session.status | Every transition, with a stopReason on an idle. |
session.usage | The turn's meter, written immediately before the terminal status. |
session.error | Something degraded and the turn continued: an unreachable connection, a failed summariser. |
session.metadata, message.metadata | A change to session metadata, or an annotation of one message. |
subagent.spawned / .status / .message / .completed | The four things a child session reports to its parent. |
connection.authorization_required / .authorized | A tool needs an OAuth grant this identity does not have yet. |
sandbox.attached / .released / .idle / .snapshotted / .resumed | The lifecycle of the machine. |
session.artifact | Something the agent published, such as a preview URL. |
compaction, cache.prefix | The transcript was compacted; the cached prefix was pinned or re-pinned. |
hook.dead_letter | A hook delivery gave up. |