Connect
From this release, run_id is 32 hex characters in responses and stream events alike.
Set event_deltas to true for live text and reasoning deltas.
curl -N -sS \
"$PANTHEON_BASE_URL/v1/sessions/$SESSION_ID/events/stream?event_deltas=true" \
-H "Authorization: Bearer $PANTHEON_API_KEY" \
-H "Last-Event-ID: $LAST_EVENT_ID"The server sends a keep-alive comment every 15 seconds.
Durable events
Durable events have an SSE id and JSON sequence. Save the SSE id as your replay cursor.
event: tool.started
id: evt_101
data: {"id":"evt_101","sequence":7,"type":"tool.started","workspace_id":"workspace_123","session_id":"session_123","run_id":"0123456789abcdef0123456789abcdef","created_at":"2026-09-03T12:00:01Z","content":{"tool_call_id":"call_123","name":"echo_tool","input":{"message":"hello"}},"data":{"tool_call_id":"call_123","name":"echo_tool"}}Text event content is a list of blocks. Structured event content is a JSON object.
Ephemeral events
Ephemeral events have no SSE id.
event: message.delta
data: {"type":"message.delta","run_id":"0123456789abcdef0123456789abcdef","delta":{"text":"Hello"}}Pantheon does not persist or replay these events.
Event catalog
| Value | Meaning |
|---|---|
run.started | A worker started the run. |
run.completed | The run finished successfully. |
run.failed | The run stopped with an error. |
run.cancelled | A client cancelled the run. |
message.started | Assistant message generation started. |
message.delta | A live assistant text fragment arrived. |
message.completed | Pantheon stored the final assistant message. |
reasoning.delta | A live reasoning fragment arrived. |
reasoning.message | Pantheon stored a durable reasoning message. |
intermediate.delta | A live intermediate output fragment arrived. |
tool.policy | What the agent was granted and what was withheld, once per run. |
tool.started | The agent started a tool call. |
agent.custom_tool_use | Your application must execute an application tool. |
tool.completed | A tool call completed. |
tool.failed | A tool call failed. |
tool.refused | The agent called a tool its revision does not grant. |
session.status_idle | The session returned to idle. |
session.error | A session error occurred. |
sandbox.recreated | Pantheon replaced a missing sandbox. |
stream.resync | The client must replay and reconnect with backoff. |
The application tool lifecycle events share one tool_call_id.
Read Application tools for correlation and resume steps.
Every run opens with one tool.policy event naming the agent revision that governed it, the built-in tools it granted, and each tool it withheld with the reason. A call to a tool the revision does not grant is never executed and arrives as tool.refused, not tool.failed, so a policy decision is never mistaken for a broken tool.
Handle stream.resync
If live subscription or barrier startup fails, the connection stays open and delivers persisted events with ids. The response header X-Pantheon-Live-Events: unavailable identifies this mode; otherwise its value is live, including when deltas were not requested. Startup degradation sends no resync frame. A live delivery failure mid-stream sends one resync frame without an id, then closes the connection.
Save the cursor
Keep the last durable SSE id.
Reconnect with backoff
Send that id in Last-Event-ID. If a resync arrives again within seconds of connecting, wait before the next attempt (500 ms doubling to 30 s) and cap the attempts, so a server that keeps resyncing never sees a tight loop.
Read the replay
Pantheon replays persisted events before live output resumes.
Pitfalls
- Deltas repeat after reconnect: Use only the SSE id from durable events as the cursor.
- Live text is missing: Include event_deltas=true. Final durable message events still arrive.
- Two tool pills appear: Merge every tool lifecycle event by tool_call_id.