> ## Documentation Index
> Fetch the complete documentation index at: https://docs.focusalpha.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# News & themes

> Scored, source-attributed news for a company — per event or per article — and macro theme streams that name no company at all.

The news layer answers two different questions against two different keys: *what has been happening to a company* (the per-company routes) and *what has happened on a macro theme* — rates, trade, geopolitics — most of which names no company and is therefore unreachable by ticker. In the [dashboard](https://app.focusalpha.ai)'s dataset list these appear as **Real-time company events**, **Real-time company news**, and **Real-time macro news** (`get_company_events` / `get_company_news` / `get_macro_news` [via MCP](/mcp-setup)). Sources span press and wire coverage (roughly 160 feeds across two dozen regions), earnings-call transcripts, SEC 8-K filings, Asian exchange filings, company IR pages, and a semiconductor supply-chain lane; `channel` on every row says which.

All endpoints on this page require the **Fund** plan, except the vocabulary endpoint `GET /v1/news/themes`, which is free on every plan. Every metered call costs 1 credit.

The `company_id` path segment accepts a ticker, CIK, ISIN, or `cmp_…` id, and resolves to every symbol the company is known by.

Responses use the `{ data, next_cursor, coverage }` envelope with cursor pagination — pass `next_cursor` back unchanged as `cursor`; see [Pagination](/concepts/pagination). Errors use the standard error envelope; see [Errors](/concepts/errors).

<Warning>
  **Coverage starts 2026-07-26 — there is no history before that date.** An empty result for an earlier date means the feed did not exist, not that nothing happened. The stream itself is polled continuously (roughly every two minutes).
</Warning>

<Note>
  An empty result usually means nothing cleared the scoring bar, not that nothing was published: only items scoring 40+ on the rule pass are read by the model, roughly a fifth of the stream. A large share of the volume is Japanese, Korean or Chinese and is **not translated** — an English keyword search finds nothing in it.
</Note>

## GET /v1/companies/\{company\_id}/news/events

One row per **(event, company)** — the monitoring grain. An event is one event, not one article: ten write-ups of the same print collapse to one row, with the headline and reason taken from the strongest article. The per-article route below answers "what was written"; this one answers "what happened".

**Plan:** Fund · **Credits:** 1 per call

<ParamField query="direction" type="string">
  `bullish`, `bearish`, or `neutral` — the event's overall direction, the most common read across its articles.
</ParamField>

<ParamField query="min_impact" type="integer">
  0–100. Peak impact across the event's articles.
</ParamField>

<ParamField query="relation" type="string" default="direct">
  Which kind of connection to this company. `direct` (default) — the article names it. `knock_on` — the article does **not** name it; the row is reached through a filed relationship in the entity graph and is an inference. `both` — both kinds, each row carrying its own `relation`.
</ParamField>

<ParamField query="min_magnitude" type="integer">
  0–100, knock-on rows only: how far the inference says this name was repriced. Not the same scale as `min_impact`, and never applied to direct rows.
</ParamField>

<ParamField query="since" type="string">
  ISO-8601 timestamp lower bound.
</ParamField>

<ParamField query="include_scheduled" type="boolean" default="false">
  Include future-dated calendar rows (IR feeds publish the earnings calendar, so some rows are dated months ahead). Excluded by default.
</ParamField>

<ParamField query="cursor" type="string">
  `next_cursor` from the previous page, passed back unchanged.
</ParamField>

<ParamField query="limit" type="integer">
  1–200, default 50.
</ParamField>

```bash theme={null}
curl "https://api.focusalpha.ai/v1/companies/MU/news/events?direction=bullish&min_impact=60" \
  -H "Authorization: Bearer $FOCUSALPHA_API_KEY"
```

```json theme={null}
{
  "data": [
    {
      "event_id": "story_01j5xk2v9r",
      "relation": "direct",
      "ticker": "MU",
      "n_articles": 4,
      "first_at": "2026-08-26T08:12:00Z",
      "last_at": "2026-08-26T14:40:00Z",
      "peak_impact": 78,
      "peak_magnitude": null,
      "via": null,
      "direction": "bullish",
      "human_reviewed": false,
      "headline": "Micron raises Q4 guidance on memory pricing",
      "why": "Raised revenue guidance implies stronger DRAM pricing than the street modelled.",
      "event_type": "guidance",
      "link": "https://…",
      "publishers": ["Reuters", "Nikkei Asia"],
      "weakest_time_basis": "publisher_stated",
      "occurred_on": "2026-08-26",
      "reaches": []
    }
  ],
  "next_cursor": null,
  "coverage": {
    "available_from": "2026-07-26",
    "available_to": null,
    "update_frequency": "continuous",
    "history_status": "starts_2026_07_26"
  }
}
```

<Note>
  An event can merge several kinds of source — a wire write-up, the company's own 8-K, and the earnings call that followed — and `publishers` then lists all of them. The event's `headline` and `why` come from its strongest article, not from all of them. Timestamps come from different clocks: `weakest_time_basis` carries the least precise one in the event, so times are only comparable within the same basis.
</Note>

## GET /v1/companies/\{company\_id}/news

One row per **(article, company)**. Same filters as the events route, plus `event_type` and `until`.

**Plan:** Fund · **Credits:** 1 per call

<ParamField query="direction" type="string">
  `bullish`, `bearish`, or `neutral` — the model's read of what this article means **for this name**.
</ParamField>

<ParamField query="event_type" type="string">
  One of the 20 coarse event types (`earnings`, `guidance`, `m&a`, `fda`, …).
</ParamField>

<ParamField query="min_impact" type="integer">
  0–100. The model's per-name impact — not a price move.
</ParamField>

<ParamField query="relation" type="string" default="direct">
  `direct` (default), `knock_on`, or `both` — see the events route above.
</ParamField>

<ParamField query="min_magnitude" type="integer">
  0–100, knock-on rows only.
</ParamField>

<ParamField query="since" type="string">
  ISO-8601 timestamp lower bound.
</ParamField>

<ParamField query="until" type="string">
  ISO-8601 timestamp upper bound.
</ParamField>

<ParamField query="include_scheduled" type="boolean" default="false">
  Include future-dated calendar rows. Excluded by default.
</ParamField>

<ParamField query="cursor" type="string">
  `next_cursor` from the previous page, passed back unchanged.
</ParamField>

<ParamField query="limit" type="integer">
  1–200, default 50.
</ParamField>

```bash theme={null}
curl "https://api.focusalpha.ai/v1/companies/MU/news?event_type=guidance&since=2026-08-01T00:00:00Z" \
  -H "Authorization: Bearer $FOCUSALPHA_API_KEY"
```

```json theme={null}
{
  "data": [
    {
      "news_id": "n_88214",
      "event_id": "story_01j5xk2v9r",
      "relation": "direct",
      "ticker": "MU",
      "direction": "bullish",
      "impact_score": 78,
      "magnitude": null,
      "via": null,
      "confidence": null,
      "horizon": null,
      "primary_tickers": null,
      "ticker_confirmed": true,
      "title": "Micron raises Q4 guidance on memory pricing",
      "event_type": "guidance",
      "event_subtype": "raise",
      "subject": "Micron Technology",
      "why": "Raised revenue guidance implies stronger DRAM pricing than the street modelled.",
      "human_reviewed": false,
      "link": "https://…",
      "region": "us",
      "channel": "wire",
      "publisher": "Reuters",
      "summary": "…",
      "summary_withheld": false,
      "event_at": "2026-08-26T08:12:00Z",
      "time_basis": "publisher_stated",
      "time_precision": "minute",
      "is_scheduled": false,
      "occurred_on": "2026-08-26",
      "announced_lag_days": 0,
      "reaches": []
    }
  ],
  "next_cursor": null,
  "coverage": {
    "available_from": "2026-07-26",
    "available_to": null,
    "update_frequency": "continuous",
    "history_status": "starts_2026_07_26"
  }
}
```

<Warning>
  `direction` and `impact_score` are the **model's read** of an article. They are not price moves, not forecasts, and not a recommendation. `human_reviewed` marks the rows a person checked. The `ticker` on a row is what the model wrote, not a resolved identifier — roughly 20% are unconfirmed by the entity layer, and a few are private companies with no symbol. Check `ticker_confirmed` before treating one as tradable.
</Warning>

<Note>
  Knock-on rows (`relation=knock_on`, and the `reaches` list) are **inferences** from the entity graph's filed relationships, not reporting — never restate one as something the article said. The full article text is neither served nor stored: a row carries the title, the publisher's own blurb, a one-line `why`, and a `link` — follow the link to read the article.
</Note>

## GET /v1/news/themes

The macro theme vocabulary. Call this before querying a theme stream — a guessed theme name returns an empty page, not an error.

**Plan:** Free and above · **Credits:** free

```bash theme={null}
curl "https://api.focusalpha.ai/v1/news/themes" \
  -H "Authorization: Bearer $FOCUSALPHA_API_KEY"
```

```json theme={null}
{
  "themes": [
    { "theme": "rates", "signals": 487 },
    { "theme": "trade", "signals": 368 },
    { "theme": "geopolitics", "signals": 594 }
  ]
}
```

<Note>
  Themes are not equally full — `market` and `commodity` hold thousands of rows while recently split-out themes hold almost nothing yet. The counts in this response are the honest guide.
</Note>

## GET /v1/news/themes/\{theme}

Everything on one macro theme, company or no company. This is the only route that reaches the \~89% of macro items that carry no ticker impact at all.

**Plan:** Fund · **Credits:** 1 per call

<ParamField path="theme" type="string" required>
  A theme name from `GET /v1/news/themes`, e.g. `rates`.
</ParamField>

<ParamField query="track" type="string">
  `macro` — items read as macro events, usually naming no company. `company` — the same policy events landing **on** named companies, which is the half a ticker query can never reach.
</ParamField>

<ParamField query="stance" type="string">
  `decided` — somebody **did** it. `talked` — somebody only said it. The Fed holding rates and a governor talking about holding rates are different events; this is how to ask for only the first.
</ParamField>

<ParamField query="min_score" type="integer">
  0–100 rule score. 40 and above is the subset the model has read.
</ParamField>

<ParamField query="region" type="string">
  One of `us`, `jp`, `kr`, `tw`, `cn`, `eu`, `in`, `global`. Note `region` is null on more than half of all rows — unlabelled, not global.
</ParamField>

<ParamField query="since" type="string">
  ISO-8601 timestamp lower bound.
</ParamField>

<ParamField query="until" type="string">
  ISO-8601 timestamp upper bound.
</ParamField>

<ParamField query="include_scheduled" type="boolean" default="false">
  Include future-dated calendar rows. Excluded by default.
</ParamField>

<ParamField query="cursor" type="string">
  `next_cursor` from the previous page, passed back unchanged.
</ParamField>

<ParamField query="limit" type="integer">
  1–200, default 50.
</ParamField>

```bash theme={null}
curl "https://api.focusalpha.ai/v1/news/themes/rates?stance=decided&region=us&min_score=40" \
  -H "Authorization: Bearer $FOCUSALPHA_API_KEY"
```

<Note>
  A theme is a routing label, not a verdict: `rates` collects everything the rule pass read as rate-related, including general market commentary that merely discusses rate expectations. Read the title before treating a row as a policy event.
</Note>