Broadcast Research API
Broadcast operations expose normalized news, clustered stories, scheduled
company events, and an economic calendar. Every operation requires research
and completes synchronously.
Operations
| Method | Path | Required scope | Purpose |
|---|---|---|---|
GET | /v1/research/broadcast/feed | research | Read the recent materialized feed across optional categories, newest first |
GET | /v1/research/broadcast/headlines | research | Read headlines for one category |
GET | /v1/research/broadcast/ticker-news | research | Read news for a canonical ticker and aliases |
GET | /v1/research/broadcast/search | research | Search normalized headlines |
GET | /v1/research/broadcast/breaking | research | Read headlines meeting breaking-news criteria |
GET | /v1/research/broadcast/story/{cluster_id} | research | Read one clustered story and source context |
GET | /v1/research/broadcast/events | research | Read source-wide or ticker-filtered scheduled company events |
GET | /v1/research/broadcast/economic-calendar | research | Read country-level economic events |
Query and identity rules
Use the categories, event types, languages, time ranges, importance bounds, and list limits defined in OpenAPI. Comma-separated ticker/category parameters are parsed as lists. Preserve each returned source, publication timestamp, language, and cluster ID; similar titles are not proof that two rows are the same story. The breaking-news recency window accepts one minute through seven days and defaults to the three-hour materialization cadence.
Company events default to the complete source-wide Finnhub earnings batch for
the requested window. Supplying tickers narrows that batch and enables the
per-ticker Yahoo calendar fallback for earnings, dividend, and ex-dividend
dates. Event-type filters remain optional for command callers.
The unified feed uses the same bounded window and orders publication time first,
then stored AI importance for equal timestamps. Only AI-evaluated candidates
that pass the server-owned financial-domain publication gate are visible. It
never collects feeds or evaluates news during a request. Rejected candidates are
retained briefly for internal audit and are unavailable to feed, search, ticker,
story, and Breaking reads. The current materialized feed is English-only and
reports lang: "en"; it does not accept a language override.
ticker-news is a research-news lookup, not symbol validation. Resolve any
trading instrument through Exchanges and Accounts before constructing an
order. Economic-calendar importance is provider-normalized and should not be
treated as a probability or guaranteed market impact.
Freshness and failures
Feed status and data-source fields explain which inputs were available. A successful empty headline/event list means no matching rows were established; it is distinct from an upstream error.
The routes synchronously call the research infrastructure. A timeout returns
504 UPSTREAM_TIMEOUT, unavailable transport returns
503 UPSTREAM_UNAVAILABLE, and an upstream or malformed response returns a
502 error. Do not convert those failures into an empty successful feed.