> ## 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.

# Corporate events & guidance

> Structured 8-K events, raw exhibit text, management guidance, reported earnings figures, and prediction-market prices.

These endpoints cover what a company disclosed and what it said it expects: 8-K filings as structured facts and as raw text, forward guidance, the figures printed in earnings releases, and the prediction-market contracts written against those outcomes. In the [dashboard](https://app.focusalpha.ai)'s dataset list these appear as **Real-time US events and filings**, **Real-time guidance and changes**, **Real-time earnings result analysis**, and **Prediction-market consensus** (see the [MCP tool map](/mcp-setup)).

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

The `company_id` path segment accepts a ticker (`AAPL`), a CIK, an ISIN, or a canonical `cmp_…` id. Guidance and earnings-results routes resolve the identifier to every ticker the company is known by, so figures filed under a secondary symbol are not missed.

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).

<Note>
  Several of these datasets are backfilled backwards, so their history start dates move. Read `coverage.available_from` on each response rather than assuming a fixed start date.
</Note>

## GET /v1/8k-events/families

The vocabulary for the structured 8-K event layer: the event families, their attribute fields, and the values actually observed in the data. Call this before filtering `GET /v1/8k-events` — a guessed family or attribute value returns an empty page, not an error.

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

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

```json theme={null}
{
  "data": [
    {
      "family": "officer_director_change",
      "attr_values": {
        "role_group": { "ceo": 412, "cfo": 388, "director": 1290 }
      }
    }
  ]
}
```

<Note>
  A field the extractor defines but no filing has filled yet is absent from the vocabulary — filtering on it would return nothing anyway.
</Note>

## GET /v1/8k-events

Cross-market structured 8-K events: what a filing disclosed, as fields — who was appointed to what and when, how much was borrowed at which rate, which listing rule was breached. This is the route for screening questions no per-company dataset can answer: every CEO departure this week, every bankruptcy filing this month.

One row per concrete fact (a person's appointment, one note tranche, one deficiency notice), newest SEC acceptance first. Several rows per filing is normal; `event_id` (`accession:item_code`) groups them. Extraction runs minutes behind SEC acceptance — a filing accepted moments ago may have no rows yet.

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

<ParamField query="family" type="string">Event family, e.g. `officer_director_change`. Use the names served by `GET /v1/8k-events/families`.</ParamField>

<ParamField query="item" type="string">An 8-K item code, e.g. `5.02`. Same events, alternative key.</ParamField>

<ParamField query="accession" type="string">One filing, e.g. `0001234567-26-000123`.</ParamField>

<ParamField query="announced_gte" type="string">Lower bound on `announced_at` — the SEC acceptance timestamp. `YYYY-MM-DD` or an ISO instant like `2026-08-12T21:30:00Z`.</ParamField>

<ParamField query="announced_lte" type="string">Upper bound on `announced_at`, same formats.</ParamField>

<ParamField query="attr_key" type="string">One attribute equality filter, paired with `attr_value` — e.g. `attr_key=role_group&attr_value=ceo`. Providing one half without the other is a 400.</ParamField>

<ParamField query="attr_value" type="string">The value for `attr_key`. Values are the controlled vocabulary from `GET /v1/8k-events/families`.</ParamField>

<ParamField query="gate" type="string">`item` keeps only statutory rows (the company filed under that item code); `probe` keeps only rows found by content matching under a different item code, which carry lower certainty.</ParamField>

<ParamField query="verified_only" type="boolean">Keep only rows whose quote was found verbatim in the filing and whose numbers all matched the filing text. The strictest cut — for anything where a wrong number is worse than a missing row.</ParamField>

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

<ParamField query="limit" type="integer">1–1000, default 100.</ParamField>

```bash theme={null}
curl "https://api.focusalpha.ai/v1/8k-events?family=officer_director_change&attr_key=role_group&attr_value=ceo&announced_gte=2026-08-01" \
  -H "Authorization: Bearer $FOCUSALPHA_API_KEY"
```

```json theme={null}
{
  "data": [
    {
      "detail_id": "184223",
      "event_id": "0001234567-26-000123:5.02",
      "accession": "0001234567-26-000123",
      "company_id": "cmp_01hzy3v8x2",
      "cik": "0001234567",
      "ticker": "ACME",
      "company_name": "Acme Corp",
      "item_code": "5.02",
      "family": "officer_director_change",
      "seq": 1,
      "attrs": { "role_group": "ceo", "effective_date": "2026-08-17" },
      "quote": "…appointed Jane Roe as Chief Executive Officer, effective August 17, 2026…",
      "quote_check": "verified",
      "numbers_unverified": [],
      "derived_fields": [],
      "fully_verified": true,
      "gate": "item",
      "form": "8-K",
      "is_amendment": false,
      "announced_at": "2026-08-14T21:31:12Z",
      "occurred_on": "2026-08-12",
      "filing_date": "2026-08-14",
      "source_ref": "https://www.sec.gov/Archives/edgar/data/…"
    }
  ],
  "next_cursor": "…",
  "coverage": { "available_from": "2025-11-03", "available_to": null, "update_frequency": "minutes", "history_status": "starts_2025_11_03" }
}
```

<Warning>
  Attribute values are strings exactly as the filing printed them (`"$700 million"`, `"SOFR plus 1.75%"`). Nothing is converted or summed — parse deliberately before any arithmetic, and never add a row with `attrs.is_total="yes"` to its sibling tranches.
</Warning>

<Note>
  `announced_at` (when the market learned) and `occurred_on` (the event's own date) differ on 59% of rows, with a tail running to years. Time windows here run on `announced_at`; dating the event itself is what `occurred_on` is for.
</Note>

<Note>
  Counting events means filtering `is_amendment`: rows from an 8-K/A usually restate the whole event rather than just the correction. `quote_check="unverified"` means the supporting sentence could not be matched against the filing under the checker's rules — read it as "check this one". `numbers_unverified` lists numbers absent from the filing text and `derived_fields` names the affected fields.
</Note>

## GET /v1/companies/\{company\_id}/8k-events

One company's structured 8-K events. Same filters, row shape, and pagination as the cross-market route above.

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

```bash theme={null}
curl "https://api.focusalpha.ai/v1/companies/ACME/8k-events?family=debt_obligation" \
  -H "Authorization: Bearer $FOCUSALPHA_API_KEY"
```

## GET /v1/companies/\{company\_id}/8k-exhibits

The text a company actually published with an 8-K — the earnings release, the management change, the deal announcement. One row per exhibit, newest filing first.

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

<ParamField query="date_gte" type="string">Inclusive lower bound on the filing date, `YYYY-MM-DD`.</ParamField>

<ParamField query="date_lte" type="string">Inclusive upper bound on the filing date, `YYYY-MM-DD`.</ParamField>

<ParamField query="accession" type="string">One filing, e.g. `0001437749-26-024904`.</ParamField>

<ParamField query="item" type="string">An 8-K item code the filing reported, e.g. `2.02`.</ParamField>

<ParamField query="include_body" type="boolean" default="false">Include the full exhibit text. Off by default — bodies run to tens of thousands of characters, and the page size shrinks when you ask for them. `chars` is always returned so you can see the size first.</ParamField>

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

<ParamField query="limit" type="integer">1–1000, default 50. A smaller cap applies when `include_body=true`.</ParamField>

```bash theme={null}
curl "https://api.focusalpha.ai/v1/companies/ACME/8k-exhibits?item=2.02&date_gte=2026-07-01" \
  -H "Authorization: Bearer $FOCUSALPHA_API_KEY"
```

```json theme={null}
{
  "data": [
    {
      "company_id": "cmp_01hzy3v8x2",
      "cik": "0001234567",
      "ticker": "ACME",
      "company_name": "Acme Corp",
      "accession": "0001437749-26-024904",
      "form": "8-K",
      "filing_date": "2026-07-29",
      "acceptance_ts": "2026-07-29T20:05:41Z",
      "items": ["2.02", "9.01"],
      "exhibit_type": "EX-99.1",
      "description": "Press release dated July 29, 2026",
      "url": "https://www.sec.gov/Archives/edgar/data/…",
      "format": "html",
      "chars": 18422
    }
  ],
  "next_cursor": null,
  "coverage": { "available_from": "2026-04-02", "available_to": null, "update_frequency": "daily", "history_status": "starts_2026_04_02" }
}
```

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

What management said it expects — revenue, margins, capex and the rest. Every row carries the `quote` it came from; the parsed `value_low` / `value_high` / `value_unit` are a convenience over the company's own phrasing (`new_value`), not a replacement for it.

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

<ParamField query="metric_key" type="string">Normalised metric key, e.g. `revenue`, `ebitda`, `core_eps`.</ParamField>

<ParamField query="direction" type="string">One of `new`, `raise`, `cut`, `maintain`.</ParamField>

<ParamField query="year" type="integer">Fiscal year, 2000–2100.</ParamField>

<ParamField query="quarter" type="integer">1–4.</ParamField>

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

<ParamField query="limit" type="integer">1–1000, default 100.</ParamField>

```bash theme={null}
curl "https://api.focusalpha.ai/v1/companies/ACME/guidance?metric_key=revenue" \
  -H "Authorization: Bearer $FOCUSALPHA_API_KEY"
```

```json theme={null}
{
  "data": [
    {
      "ticker": "ACME",
      "year": 2026,
      "quarter": 2,
      "conference_date": "2026-07-29T21:00:00Z",
      "transcript_id": "…",
      "source_kind": "release",
      "metric_key": "revenue",
      "basis": "nongaap",
      "period": "FY26",
      "label": "Revenue",
      "direction": "raise",
      "claimed": true,
      "new_value": "$9.0 billion to $9.2 billion",
      "prior_value": "$8.8 billion to $9.0 billion",
      "value_low": 9.0,
      "value_high": 9.2,
      "value_unit": "billion_usd",
      "value_is_band": true,
      "value_bound": null,
      "quote": "We now expect full-year revenue of $9.0 to $9.2 billion…"
    }
  ],
  "next_cursor": null,
  "coverage": { "available_from": "2025-09-12", "available_to": null, "update_frequency": "daily", "history_status": "starts_2025_09_12" }
}
```

<Note>
  This is what management **said**, not a filed figure. `period` is the period being guided (e.g. `FY26`), not the quarter being reported. Where the filed release and the call state a figure differently, the filed one is kept — every disagreement traced so far has been the call transcription.
</Note>

## Guidance variants

Three sibling routes share the guidance filters and row conventions:

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

* `GET /v1/companies/{company_id}/guidance-changes` — only the metrics that **moved** since the previous earnings event. Filters: `metric_key`, `year`, `cursor`, `limit`. Rows carry `current_value`, `prior_value`, `prior_transcript_id`, and `change`.
* `GET /v1/companies/{company_id}/guidance-earnings-events` — guidance as of one earnings event, with the 8-K release and the call collapsed into a single row per metric.
* `GET /v1/companies/{company_id}/guidance-latest` — the company's current standing guidance, one row per metric. Not paginated: `next_cursor` is always `null`, because reading the current outlook across pages invites reading page one as the whole state.

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

## GET /v1/companies/\{company\_id}/earnings-results

What a quarter actually delivered, as the company printed it in the earnings release — including the non-GAAP lines the financial statements do not carry (adjusted EBITDA, organic growth, segment KPIs). One row per figure per release; a GAAP and a non-GAAP reading of one metric are two rows.

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

<ParamField query="metric_key" type="string">Normalised metric key, e.g. `revenue`.</ParamField>

<ParamField query="period" type="string">The period the figure is **for**, as the release labelled it — `Q2 2026`, `FY26`.</ParamField>

<ParamField query="year" type="integer">2000–2100.</ParamField>

<ParamField query="quarter" type="integer">1–4.</ParamField>

<ParamField query="level" type="string">`consolidated` or `segment`. No default — a release that breaks a line out by segment emits one row per segment **beside** the consolidated row, so summing an unfiltered page double-counts.</ParamField>

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

<ParamField query="limit" type="integer">1–1000, default 100.</ParamField>

```bash theme={null}
curl "https://api.focusalpha.ai/v1/companies/ACME/earnings-results?metric_key=revenue&level=consolidated" \
  -H "Authorization: Bearer $FOCUSALPHA_API_KEY"
```

```json theme={null}
{
  "data": [
    {
      "ticker": "ACME",
      "year": 2026,
      "quarter": 2,
      "observed_at": "2026-07-29T20:05:41Z",
      "occurred_on": "2026-07-29",
      "doc_id": "…",
      "source_ref": "https://www.sec.gov/Archives/edgar/data/…",
      "source_feed": "sec_8k",
      "metric_key": "revenue",
      "basis": "gaap",
      "period": "Q2 2026",
      "label": "Revenue",
      "segment": null,
      "value_text": "$2.31 billion",
      "value_low": 2.31,
      "value_high": 2.31,
      "value_unit": "billion_usd",
      "yoy": "up 12%",
      "value_is_band": false,
      "quote": "Revenue was $2.31 billion, up 12% year over year…"
    }
  ],
  "next_cursor": null,
  "coverage": { "available_from": "2026-01-08", "available_to": null, "update_frequency": "daily", "history_status": "starts_2026_01_08" }
}
```

<Note>
  These are not the financial statements — those come from the filing's own XBRL via [`/v1/financials`](/api-reference/financials) and are the audited, comparable record. `yoy` is the change the release printed, never one computed by us; it is `null` when the release printed none.
</Note>

## GET /v1/companies/\{company\_id}/prediction-markets

What money is betting on a company: whether an operating number clears a threshold (`kpi_ladder`), whether a topic comes up on the next earnings call (`call_keyword`), whether EPS clears a contract's level (`earnings_beat`). One row per contract per most recent observation.

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

<ParamField query="category" type="string">`kpi_ladder`, `call_keyword`, or `earnings_beat`.</ParamField>

<ParamField query="status" type="string">`open` or `settled`.</ParamField>

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

<ParamField query="limit" type="integer">1–1000, default 100.</ParamField>

```bash theme={null}
curl "https://api.focusalpha.ai/v1/companies/TSLA/prediction-markets?status=open" \
  -H "Authorization: Bearer $FOCUSALPHA_API_KEY"
```

```json theme={null}
{
  "data": [
    {
      "company_id": "cmp_01hzy3v8x2",
      "ticker": "TSLA",
      "market_id": "pmk_3f1a9c02b7d44e10",
      "category": "kpi_ladder",
      "question": "Tesla Q3 2026 vehicle deliveries",
      "outcome": "Above 495,000",
      "period": "Q3 2026",
      "closes_at": "2026-10-02T14:00:00Z",
      "settled": false,
      "settled_yes": null,
      "yes_bid": 0.41,
      "yes_ask": 0.47,
      "implied_probability": 0.44,
      "volume": 182050,
      "as_of": "2026-08-27T13:00:11Z",
      "as_of_age_minutes": 38
    }
  ],
  "next_cursor": null,
  "coverage": { "available_from": "2025-10-01", "available_to": null, "update_frequency": "hourly_snapshots", "history_status": "snapshots" }
}
```

<Warning>
  **Not a live feed.** Prices are snapshots taken roughly hourly between 12:00 and 24:00 UTC, with a nightly gap of about 12.5 hours. Read `as_of_age_minutes` before calling any probability current.
</Warning>

<Note>
  `implied_probability` is `null` whenever the book was one-sided or its spread wider than 0.25 — that null means nobody is really trading the contract. `yes_bid` and `yes_ask` are returned raw for anyone who wants their own rule. Sort by `volume` before saying "the market expects": plenty of contracts have traded a few hundred dollars, which is a listing rather than an opinion.
</Note>

## GET /v1/companies/\{company\_id}/earnings-markets

Earnings-beat contracts with settlement checks: one row per company per quarter per basis. GAAP and non-GAAP are separate contracts written against separate levels — pooling them compares an adjusted figure with a GAAP one. Observed twice daily since 2025-09.

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

<ParamField query="basis" type="string">`gaap` or `nongaap`.</ParamField>

<ParamField query="date_gte" type="string">Inclusive lower bound on the estimated report date, `YYYY-MM-DD`.</ParamField>

<ParamField query="date_lte" type="string">Inclusive upper bound, `YYYY-MM-DD`.</ParamField>

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

<ParamField query="limit" type="integer">1–1000, default 100.</ParamField>

```bash theme={null}
curl "https://api.focusalpha.ai/v1/companies/ACME/earnings-markets?basis=nongaap" \
  -H "Authorization: Bearer $FOCUSALPHA_API_KEY"
```

```json theme={null}
{
  "data": [
    {
      "market_id": "pmk_9b02d4a1c33f57e8",
      "ticker": "ACME",
      "company_id": "cmp_01hzy3v8x2",
      "basis": "nongaap",
      "estimated_report_date": "2026-07-29",
      "eps_threshold": 1.42,
      "settled": true,
      "cleared": true,
      "reported_eps": 1.51,
      "reported_period": "Q2 2026",
      "reported_source_url": "https://www.sec.gov/Archives/edgar/data/…",
      "cleared_confirmed": true,
      "check_status": "agrees"
    }
  ],
  "next_cursor": null,
  "coverage": { "available_from": "2025-09-02", "available_to": null, "update_frequency": "twice_daily", "history_status": "starts_2025_09_02" }
}
```

<Note>
  `eps_threshold` is fixed when the contract is written and never revised — it is a property of the contract, not a running estimate. `cleared` is the exchange's settlement of its own contract; `cleared_confirmed` is an independent reading against the EPS printed in the earnings release, and `check_status` says why when that check could not run. A `null` `cleared_confirmed` means **not checked**, never that `cleared` is wrong.
</Note>