list_realtime_events
Read-only
Pull live market events from the backend's Redis-backed cache (12h TTL).
===> Call `situate(...)` FIRST. With symbols, its web says which event types fired
for the company and when — a node older than the 12h cache returns [] here; its
payload lives in the card's `persisted_in` table instead. With no symbols, its
`order` says which types to read and its `cache.count` per type says which are
empty before you call (0 = cold cache, not "nothing happened").
`list_options("event_types")` enumerates the valid type strings. `event_type` is REQUIRED and
has no default on purpose: the type is the whole question, and a default
would answer a different one (eps_update is one slice of the earnings
family, not the family).
Then CONNECT THE DOTS: fetch the type asked about and follow the situation
across its related_events with follow-up calls narrowed by `tickers=[...]`
to the symbols just seen — e.g. eps_update -> check the intraday tape
(detect_intraday_outlier_jumps) -> 8k_release -> ir_publication. One hop
answers most questions; two covers a full earnings cycle. An unfiltered
follow-up call re-pulls the whole cache.
Returns `events`, a list of event objects (keys vary by type). An EMPTY list
means the cache is cold for that event type (12h TTL), not that nothing happened.
A material event here (eps_update, eps_release, 8k_release, financials_release,
ir_publication, transcript_update) means the symbol's report is being written from
it (within minutes; the `report_plan` topic announces each one):
`list_available_reports(event_types=[<this type>])` says which are already current,
and get_latest_report returns them in seconds.
Requires auth (your MCP client attaches the OAuth bearer automatically).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sector | No | Sector values from list_options("sectors"). | |
| tickers | No | Narrow to these tickers; always set on follow-up calls (an unfiltered call re-pulls the whole cache). | |
| industry | No | Industry values from list_sub_industries([...]). | |
| event_type | Yes | REQUIRED realtime event type from list_options("event_types"), e.g. "eps_update", "8k_release", "ir_publication". | |
| market_cap | No | Market-cap buckets, e.g. ["Large-cap", "Mega-cap"]. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| events | Yes | Cached events of the requested type. Empty means the 12h cache is cold for that type, not that nothing happened. |