stream_event_subscription
Read-only
Read the next events on a saved subscription — a bounded read of
GET /event-subscription/{subscription_id} that resumes from the position saved
when the previous read closed, so repeated calls see every matching event exactly
once with no gap and no replay.
For a live-streaming ask, the default is a dashboard (in Claude, an Artifact) that
loops stream_events with its cursor — see stream_events; a page should prefer that
ad-hoc stream, since a subscription read can stall.
Returns {"events": [...], "cursor": "<last id seen>", "closed": null | reason,
"elapsed_seconds": n} — same shape and event objects as stream_events. A call returns after `max_events`
matched events or `max_wait_seconds` (cap 55 s); call again to keep listening. The
API saves the cursor when this read closes the connection, so the next call resumes
correctly WITHOUT passing `cursor`. Pass `cursor` only to override the saved
position for one connection (e.g. re-read from an earlier frame id); it is not
persisted.
An empty `events` list means nothing matched in the window, not that the
subscription is broken. `closed` = "subscription deleted" means it was removed
mid-stream — do not reconnect. 404 `unknown subscription_id` covers both a missing
id and another user's id (indistinguishable by design).
Acting on what arrives: an `event` item is the full realtime event (use it
directly); to hand over research, get_latest_report([symbol]) first (a fresh plan
renders in ~10-20 s; batch up to 50 symbols per call), and only if it comes back
stale/missing a generate_report_for_stock(ticker) rebuild. A `report_plan` item
means a plan was just saved: get_latest_report([symbol]) renders it fresh.
Requires auth (your MCP client attaches the OAuth bearer automatically).
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cursor | No | Override the saved position for this one connection (not persisted). Omit to resume where the last read stopped. | |
| max_events | No | Return after this many matched events (clamped to 1-200). | |
| subscription_id | Yes | The `subscription_id` returned by register_event_subscription. | |
| max_wait_seconds | No | Return after this many seconds even if fewer events arrived (clamped to 1-55). |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| closed | No | Set when the server ended the stream (e.g. "subscription deleted"); do not reconnect. | |
| cursor | No | Last stream id seen (advances on heartbeats too). Pass it back on the next call; null only when no frame carried an id and none was passed in. | |
| events | Yes | Matched events in publish order; empty on a quiet tape. A frame whose data was not JSON comes through as {"raw": <text>}. | |
| elapsed_seconds | Yes | Wall time this read held the stream open. |