Skip to main content
Session events provide real-time updates during AI conversations, including streaming text, tool calls, and status changes.

​
session.status

Emitted when the session status changes (thinking, processing, complete). 
{
  "type": "session.status",
  "timestamp": "2026-01-01T00:00:00.000Z",
  "payload": {
    "session_id": "ses_abc123",
    "pending": true,
    "status_label": "thinking..."
  }
}
​
payload.session_id
string
Unique session identifier
​
payload.pending
boolean
Whether the session is actively processing
​
payload.status_label
string
Human-readable status (e.g., “thinking…”, “running tool”, “complete”)

​
session.message.appended

Emitted when a new message is added to the conversation history. 
{
  "type": "session.message.appended",
  "timestamp": "2026-01-01T00:00:00.000Z",
  "payload": {
    "session_id": "ses_abc123",
    "message": {
      "role": "assistant",
      "content": "I'll help you with that."
    }
  }
}
​
payload.message.role
string
Message role: "user", "assistant", or "system"
​
payload.message.content
string
Message text content

​
session.stream.chunk

Emitted as the AI model streams text output. 
{
  "type": "session.stream.chunk",
  "timestamp": "2026-01-01T00:00:00.000Z",
  "payload": {
    "session_id": "ses_abc123",
    "text": "Hello",
    "done": false
  }
}
​
payload.text
string
Text chunk from the model. Append to build the full response.
​
payload.done
boolean
Whether this is the final chunk in the stream
Stream chunks arrive rapidly. Buffer them and update your UI incrementally.

​
session.tool.call.started

Emitted when the AI begins executing a tool. 
{
  "type": "session.tool.call.started",
  "timestamp": "2026-01-01T00:00:00.000Z",
  "payload": {
    "session_id": "ses_abc123",
    "tool_call_id": "call_xyz789",
    "tool_name": "bash",
    "tool_input": {
      "command": "ls -la"
    }
  }
}
​
payload.tool_call_id
string
Unique identifier for this tool execution
​
payload.tool_name
string
Name of the tool being executed (e.g., "bash", "read_file")
​
payload.tool_input
object
Input parameters passed to the tool

​
session.tool.call.completed

Emitted when a tool finishes executing. 
{
  "type": "session.tool.call.completed",
  "timestamp": "2026-01-01T00:00:00.000Z",
  "payload": {
    "session_id": "ses_abc123",
    "tool_call_id": "call_xyz789",
    "tool_name": "bash",
    "ok": true,
    "duration_ms": 150
  }
}
​
payload.ok
boolean
Whether the tool executed successfully
​
payload.duration_ms
number
Tool execution time in milliseconds

​
session.tool.results

Emitted with the full results from tool execution. 
{
  "type": "session.tool.results",
  "timestamp": "2026-01-01T00:00:00.000Z",
  "payload": {
    "session_id": "ses_abc123",
    "results": [
      {
        "tool_call_id": "call_xyz789",
        "tool_name": "bash",
        "ok": true,
        "output": {
          "stdout": "total 24\ndrwxr-xr-x 5 user",
          "exit_code": 0
        }
      }
    ]
  }
}
​
payload.results
array
Array of tool execution results. Each result includes:
  • tool_call_id - Matches the ID from tool.call.started
  • tool_name - Tool that was executed
  • ok - Success status
  • output - Tool-specific output object

​
session.completed

Emitted when the AI finishes its turn (all streaming and tool calls complete). 
{
  "type": "session.completed",
  "timestamp": "2026-01-01T00:00:00.000Z",
  "payload": {
    "session_id": "ses_abc123",
    "final_message": "I've listed the directory contents."
  }
}
​
payload.final_message
string
The complete final message from the AI
Use this event to know when to prompt the user for their next message.

​
session.interrupted

Emitted when the user cancels an in-progress turn. 
{
  "type": "session.interrupted",
  "timestamp": "2026-01-01T00:00:00.000Z",
  "payload": {
    "session_id": "ses_abc123",
    "reason": "user_requested"
  }
}

​
session.error

Emitted when an error occurs during AI processing. 
{
  "type": "session.error",
  "timestamp": "2026-01-01T00:00:00.000Z",
  "payload": {
    "session_id": "ses_abc123",
    "error": "Rate limit exceeded",
    "code": "rate_limit"
  }
}
​
payload.error
string
Human-readable error message
​
payload.code
string
Error code for programmatic handling

​
Typical event sequence

A normal conversation turn emits events in this order:
  1. session.status - Status changes to “thinking”
  2. session.stream.chunk - Multiple chunks as AI responds
  3. session.tool.call.started - If AI calls a tool
  4. session.tool.call.completed - Tool execution finishes
  5. session.tool.results - Tool results available
  6. session.stream.chunk - AI continues responding
  7. session.completed - Turn is complete
  8. session.status - Status changes to “idle”

Build docs developers (and LLMs) love

Get started for freeTalk to us