stream_events
Read-only
Listen for realtime events as they publish — a bounded read of the backend's
ad-hoc SSE stream (GET /events), filter passed inline, nothing saved server-side.
DEFAULT DELIVERY — BUILD A DASHBOARD: when the user asks to stream / watch / keep
listening for live events, build a live dashboard (in Claude, an Artifact) whose
page calls this tool in its own loop, carrying `cursor` from read to read, and
renders each event as it lands. One prompt then keeps the stream open with no agent
turn per read. If the page cannot reach this server, run the loop yourself and write
each event into the dashboard's shared store. Stream into chat only when the user
asks for that, or the client cannot render a dashboard.
Returns {"events": [...], "cursor": "<last id seen>", "closed": null | reason,
"elapsed_seconds": n}. Each item in `events` is the same object `list_realtime_events` returns for that
type ({event_type, symbol, payload, published_at, id}) — summary, thesis impact,
significant changes, citations — the moment it publishes, no polling of the 12h
cache. There is NO PDF link on an event: the event's report lands a few minutes
later, announced on the `report_plan` topic, and get_latest_report([symbol]) then
returns it (stale or missing with no report on the way -> generate_report_for_stock,
ticker only).
THE LOOP: a call returns after `max_events` matched events or `max_wait_seconds`
(cap 55 s), whichever comes first — call it again to keep listening, and ALWAYS
pass the returned `cursor` back in: this stream keeps no state, so without it
the next call starts at "now" and drops whatever published in between. The
cursor advances on heartbeats too (events the filter dropped), so an empty
`events` list with a moved cursor is normal on a quiet tape. Omit `cursor` on
the first call to start at now. For a subscription that resumes by itself, use
register_event_subscription + stream_event_subscription instead.
`topics` (optional, any mix; case-insensitive):
- an event type from list_options("event_types") — eps_update, 8k_release,
transcript_update, ir_publication, biggest_mover, 13f_new, strategy_update, ...
- a family from the same listing — earnings, news, market_movement,
institutional_ownership, analyst_activity, strategy, prediction — which
matches every type in it, including types added later;
- `report_plan` (stream-only): a frame each time a symbol's new report is
PUBLISHED — its document is already written ({symbol, event_type, planned_at,
queued_at, plan_key, report_key}); the next step is get_latest_report([symbol]),
which returns it (`stale: false`). Subscribe to it to stream research as it is
written.
`symbols` (optional): tickers; 13f_* filer events carry the filer's CIK in the
symbol slot. No topics and no symbols = everything. Unknown topic -> 422 with the
allowed lists in `detail`.
`closed` set means the server ended the stream — do not reconnect with that id.
Requires auth (your MCP client attaches the OAuth bearer automatically).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cursor | No | The `cursor` returned by the previous read; resume after it. Omit to start at now. | |
| topics | No | Event types or families from list_options("event_types") (e.g. "eps_update", "earnings"), plus the stream-only "report_plan"; case-insensitive. Omit for every topic. | |
| symbols | No | Tickers to listen for (13f_* filer events carry the filer's CIK in the symbol slot). Omit for every symbol. | |
| max_events | No | Return after this many matched events (clamped to 1-200). | |
| max_wait_seconds | No | Return after this many seconds even if fewer events arrived (clamped to 1-55). |
Output 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. |