Corporate events & guidance

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’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). 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. Errors use the standard error envelope; see Errors.

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.

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

curl "https://api.focusalpha.ai/v1/8k-events/families" \
  -H "Authorization: Bearer $FOCUSALPHA_API_KEY"

{
  "data": [
    {
      "family": "officer_director_change",
      "attr_values": {
        "role_group": { "ceo": 412, "cfo": 388, "director": 1290 }
      }
    }
  ]
}

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

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

string

Event family, e.g. officer_director_change. Use the names served by GET /v1/8k-events/families.

string

An 8-K item code, e.g. 5.02. Same events, alternative key.

string

One filing, e.g. 0001234567-26-000123.

string

Lower bound on announced_at — the SEC acceptance timestamp. YYYY-MM-DD or an ISO instant like 2026-08-12T21:30:00Z.

string

Upper bound on announced_at, same formats.

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.

string

The value for attr_key. Values are the controlled vocabulary from GET /v1/8k-events/families.

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.

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.

string

next_cursor from the previous page, passed back unchanged.

integer

1–1000, default 100.

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"

{
  "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" }
}

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.

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.

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.

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

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

string

Inclusive lower bound on the filing date, YYYY-MM-DD.

string

Inclusive upper bound on the filing date, YYYY-MM-DD.

string

One filing, e.g. 0001437749-26-024904.

string

An 8-K item code the filing reported, e.g. 2.02.

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.

string

next_cursor from the previous page, passed back unchanged.

integer

1–1000, default 50. A smaller cap applies when include_body=true.

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

{
  "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

string

Normalised metric key, e.g. revenue, ebitda, core_eps.

string

One of new, raise, cut, maintain.

integer

Fiscal year, 2000–2100.

integer

1–4.

string

next_cursor from the previous page, passed back unchanged.

integer

1–1000, default 100.

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

{
  "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" }
}

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.

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.

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

string

Normalised metric key, e.g. revenue.

string

The period the figure is for, as the release labelled it — Q2 2026, FY26.

integer

2000–2100.

integer

1–4.

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.

string

next_cursor from the previous page, passed back unchanged.

integer

1–1000, default 100.

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

{
  "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" }
}

These are not the financial statements — those come from the filing’s own XBRL via /v1/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.

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

string

kpi_ladder, call_keyword, or earnings_beat.

string

open or settled.

string

next_cursor from the previous page, passed back unchanged.

integer

1–1000, default 100.

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

{
  "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" }
}

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.

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.

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

string

gaap or nongaap.

string

Inclusive lower bound on the estimated report date, YYYY-MM-DD.

string

Inclusive upper bound, YYYY-MM-DD.

string

next_cursor from the previous page, passed back unchanged.

integer

1–1000, default 100.

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

{
  "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" }
}

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.

Overview

Search & documents

SEC filings & financials

Companies & screening

Markets & ownership

Events & news

International

Service

Corporate events & guidance

GET /v1/8k-events/families

GET /v1/8k-events

GET /v1/companies/{company_id}/8k-events

GET /v1/companies/{company_id}/8k-exhibits

GET /v1/companies/{company_id}/guidance

Guidance variants

GET /v1/companies/{company_id}/earnings-results

GET /v1/companies/{company_id}/prediction-markets

GET /v1/companies/{company_id}/earnings-markets

​GET /v1/8k-events/families

​GET /v1/8k-events

​GET /v1/companies/{company_id}/8k-events

​GET /v1/companies/{company_id}/8k-exhibits

​GET /v1/companies/{company_id}/guidance

​Guidance variants

​GET /v1/companies/{company_id}/earnings-results

​GET /v1/companies/{company_id}/prediction-markets

​GET /v1/companies/{company_id}/earnings-markets

GET /v1/8k-events/families

GET /v1/8k-events

GET /v1/companies/{company_id}/8k-events

GET /v1/companies/{company_id}/8k-exhibits

GET /v1/companies/{company_id}/guidance

Guidance variants

GET /v1/companies/{company_id}/earnings-results

GET /v1/companies/{company_id}/prediction-markets

GET /v1/companies/{company_id}/earnings-markets