Skip to main content
useSessionStream subscribes to one channel of a session and updates a records array as new records arrive. It reads the out channel by default (the agent’s output) or in (the input channel). It is read-only; useSession is reserved for two-way (read and write) communication.
Requires a Public Access Token with the read:sessions:{id} scope. See Realtime auth for generating one.

Basic usage

Pass the session id (or external id) and an accessToken. The hook returns the records received so far, the last control record, the cursor of the last record seen, and any error:

Options

The return value:
  • records: every data record received so far, in arrival order. Control records are delivered to onControl instead.
  • lastEventId: the cursor of the last record seen. Persist it and pass it back as the lastEventId option to resume.
  • lastControl: the last control record (for example turn-complete).
  • stop: abort the subscription, keeping the records received so far.

Start from the latest record

By default the hook replays the channel history, then live-tails. Pass from: "latest" to start at the current tail (the latest record, then live updates) instead of replaying, and maxRecords to bound memory:
from: "latest" requires a server that supports it. Against an older server a client that passes it degrades safely to a full replay.

Resume from a cursor

The hook resumes automatically across a component remount. A full page reload clears in-memory state, so to resume there, persist the returned lastEventId and pass it back on the next load. The channel then continues after that record with no replay and no gap:

React to control records

Control records (such as turn-complete) never enter records. Handle them with onControl, or read the latest from lastControl:
For an expiring token on a long-lived subscription, pass refreshAccessToken (see Realtime auth). To read a session channel outside React, use session.out.read().