Stream Events

GET/v1/sessions/{session_id}/events/stream

Stream session events as Server-Sent Events (SSE). Each event is delivered as a data: frame using the same shapes as List Events, followed by a terminal data: [DONE] frame.

Path Parameters

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

How It Works

The endpoint returns a text/event-stream. Each line prefixed with data: carries one JSON-encoded event. A turn typically produces this sequence:

session.status_running
  -> agent.tool_use -> agent.tool_result   (zero or more)
  -> agent.message                         (zero or more)
session.status_idle (stop_reason: end_turn)

Current behavior

SandBase currently replays the session's persisted events in order and then emits data: [DONE]. Live incremental push (holding the connection open and streaming new events as they are produced) is on the roadmap. For near-real-time updates today, reconnect or poll List Events after sending a message.

Request Examples

Python

from anthropic import Anthropic

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

for event in client.beta.sessions.events.stream(session_id="sess_01abc..."):
    if event.type == "agent.message":
        for block in event.content:
            print(block.text, end="")
    elif event.type == "session.status_idle":
        print(f"\n[done: {event.stop_reason.type}]")
        break

Raw SSE

import json, httpx

with httpx.stream("GET",
    "https://api.sandbase.ai/v1/sessions/sess_01abc.../events/stream",
    headers={"Authorization": "Bearer sk-sb-YOUR_KEY"}
) as response:
    for line in response.iter_lines():
        if line.startswith("data: ") and line != "data: [DONE]":
            event = json.loads(line[6:])
            print(event["type"])

cURL

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

Response

Each SSE frame contains one event; the stream ends with data: [DONE].

data: {"id":"sevt_01...","type":"session.status_running","processed_at":"2026-05-29T10:00:00Z"}

data: {"id":"sevt_02...","type":"agent.tool_use","content":{"name":"web_search","input":{"query":"order 1234"}},"processed_at":"2026-05-29T10:00:01Z"}

data: {"id":"sevt_03...","type":"agent.message","content":[{"type":"text","text":"Your order #1234 shipped yesterday."}],"processed_at":"2026-05-29T10:00:03Z"}

data: {"id":"sevt_04...","type":"session.status_idle","stop_reason":{"type":"end_turn"},"processed_at":"2026-05-29T10:00:03Z"}

data: [DONE]

See List Events - Event Types for the full field reference of each event type.

Reconnection

If the connection drops, reconnect to the same endpoint. To backfill events you may have missed, use List Events and ignore events you have already processed (dedupe by event id).

Errors

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