Session events and recovery
Submit commands with POST on the Session’s events path. A reliably accepted command returns a JSON receipt, and execution continues independently of that response. How you follow the execution depends on your integration:
- An Application Server holding the Organization API Key receives the Session’s persisted events over its Backend Connection.
- A client without a Backend Connection, such as one holding a User API Key, reads the receipt, the Turn and the timeline.
- An audio Turn’s own response streams that Turn as Server-Sent Events (SSE).
There is no per-Session event subscription.
Follow events over a Backend Connection
Section titled “Follow events over a Backend Connection”A Backend Connection is one WebSocket from your Application Server process to /api/v1/org/backend/ws, with the tidb-link.backend.v1 subprotocol and the Organization API Key in its Authorization header; the API reference describes its messages. Attach a Session with session.attach, passing its End User’s userId, the sessionId and, after a reconnect, the cursor of the last event you processed. The core replays the events after that cursor, then sends each new event as session.event with its own cursor. Events of one Session arrive in order, without gaps or repeats.
Read draft snapshots
Section titled “Read draft snapshots”Each session.event carries a JSON envelope with type, sessionId, turnId, createdAt and data. For agent.session.turn.* types the nested data is the saved Turn event. agent.session.realtime.* types carry a Realtime fact of the Session timeline instead, and their turnId may be null; the API reference describes their fields. Use the envelope type to distinguish an answer draft from a progress message:
const drafts = new Map();function receive(envelope) { if (envelope.type === 'agent.session.turn.output_text.snapshot') { drafts.set(envelope.turnId, envelope.data.payload.text); }}A snapshot contains the complete provisional draft for that Turn. Replace the displayed draft; appending would repeat text. A later snapshot can revise earlier text or reset it to an empty string. Keep drafts separate by turnId. The first snapshot after re-attaching is usable without earlier draft frames. agent.session.turn.progress carries a separate progress message in data.payload.text and does not update the answer. There is no output_text.delta alias.
The final saved assistant message arrives as agent.session.turn.item.added with data.event: "assistant_message", data.payload.messageId and data.payload.text. Use the terminal Turn event to determine success, failure or cancellation. The multipart POST /turns/audio entry directly returns SSE frames with a Turn event name and its JSON event in data; closing that audio response while execution is active requests interruption.
Read results without a Backend Connection
Section titled “Read results without a Backend Connection”Read the receipt with /interactions/{receiptId}, then read the Turn its turnId names with /turns/{turnId} until that Turn’s status is no longer running. A running Turn read is a snapshot of its progress so far. /timeline lists Turns and Realtime facts in one order.
Wait for the idle event
Section titled “Wait for the idle event”A Turn’s terminal event and its command result are saved a moment before the Session releases the Turn. Until then the next message would join or be refused by the finished Turn, and an audio Turn or Template switch returns 409. agent.session.idle reports that the release happened. Wait for it before sending the next message, audio Turn or Template switch. Its data is { id, turnId, createdAt }, where turnId names the released Turn or is null when that Turn was never saved. Recovery that interrupts a Turn whose lease expired also saves its terminal event first. The idle event says nothing about the Turn’s outcome, can follow one Turn more than once, and a live Realtime Connection still makes a Template switch return 409. Without a Backend Connection, or when a wait must be bounded, read the Session and check that activeTurnId is null. For the audio entry, the end of its response is the idle point.
Connection lifetime
Section titled “Connection lifetime”Closing a Backend Connection or a POST /events command response does not cancel accepted execution; closing an audio Turn’s response while it runs requests interruption. Cancellation is an explicit command submitted through POST events. Execution budgets, timeouts and explicit stopping remain execution limits.
Following is observation: no attached connection, a slow reader or a disconnect does not cancel the Turn. Retain the last event cursor so you can re-attach and continue after reconnecting. Revoking or rotating the connection’s Organization API Key, or disabling its Organization, closes its Backend Connections without cancelling the Turn.
Recover commands separately
Section titled “Recover commands separately”Use GET /api/v1/user/sessions/{id}/interactions to find the original command receipt and /interactions/{receiptId} to read its original result. Use /turns and /turns/{turnId} for conversation history including Realtime Turns, and /timeline for Turns and Realtime facts in one order. Reading a receipt does not run work again.
Keep the original command identity and content, match the receipt to its execution, and distinguish progress from the original terminal result. An EOF, an agent.session.idle event or an accepted command does not establish success. Partial drafts remain provisional until the execution succeeds.
See Sessions and Turns for the command and history endpoints.
See reading Realtime conversation history for transcript metadata, narration and pagination behavior.