Company Guidance — Future Outlook (SEC)

Overview

Management forecasts for future periods — not financial results already reported. Forward revenue, EPS, margin, cash-flow, capex and other guidance is extracted from official SEC-filed earnings releases. Every row keeps an exact source quote, accession and exhibit link. `latestByComparisonKey` preserves every parallel metric, future period, unit, currency and accounting-basis combination; the older `latestByMetric` remains as a compact convenience view. `summary.periodSignals` separates quarterly, annual and other horizons so opposing revisions are not hidden inside one aggregate signal. Revision direction and breadth use only the latest unambiguous statement per comparable key, before the response limit, so repeated history does not inflate the signal. If the newest filing date contains incompatible extracted states for one key, the history is retained but that key is excluded from `latestByComparisonKey` and the aggregate signal; `ambiguousComparisonKeys` and `ambiguousLatestStatements` disclose it instead of selecting a row by array order. Those counters are measured on the whole stored profile, while the returned `guidance` list obeys `limit` (default 100); if the evidence for an older ambiguous key falls outside the current window, raise `limit` to read it. Coverage is lazy and existing data is served stale-while-revalidate. It does not claim to include analyst consensus or statements made only during an earnings call.

Use it toTrack exactly what management guided and whether that guidance improved or deteriorated.

`summary.freshness` says how old the newest filed guidance is (`latestGuidanceAgeDays`), how many later exhibits carried none (`filingsWithoutGuidanceSince`) and a `status`: `current`, `aging`, `no_recent_guidance` or `none`. It is measured on the whole stored profile, so a filter cannot make the data look stale, and an issuer that stopped publishing guidance is reported as such instead of serving a years-old statement as if it were the latest (Visa on 2026-09-20: newest guidance 1,062 days old with later exhibits carrying none). Each statement carries an `extraction` block with the extractor and prompt versions that produced it and when, which is what makes two extractions comparable; the model's commercial name is deliberately not published, because it answers no question those versions do not and would make our supplier part of your integration. Every statement carries the sentence it was extracted from in `evidence`, so the extraction can be checked rather than trusted — at both levels: the aggregate `summary.signal` and each individual statement. Audited on 2026-09-20 against the original SEC documents: 25 of 25 sampled `evidence` sentences appear verbatim in the filing they claim to come from. When an analysed exhibit says the outlook is in the earnings presentation — Visa does this every quarter — the filing is marked `guidance_in_unread_exhibit` and the freshness note says so plainly: we do not have it, which is not the same as the company not guiding. Guidance is voluntary and can legitimately be empty — Apple often reports complete financial results without filing formal forward guidance. For results already announced, use `/api/v1/financials/{ticker}` instead. A first uncached request can return HTTP 202 with dataStatus `preparing` and `Retry-After: 15`. Successful responses expose profile freshness in `Last-Modified` and cache state in `X-Raspberry-Guidance-Cache`; authenticated results are never marked for a shared public cache. SEC access is free; the first successful extraction can use the AI extraction model, while later requests use the compact cache. `metric`, `period` and `change` may repeat as lists; repeated scalar `limit` or `since` parameters return HTTP 400. A ticker the SEC company map does not hold returns HTTP 404 with a body that says why — ETFs and funds (SMH, XLK), index or futures symbols (NQ, MNQ) and foreign shares listed only abroad (RMS, ADYEN) never file company reports — plus `suggestions`, the mapped tickers one typo away (APPL → AAPL) or an empty list when none is close. `latestByMetric` and `latestByComparisonKey` are maps keyed by what the filing itself said: the metric name as the company words it, and the full comparison key (period, metric, unit, currency, basis), so two figures are only ever compared when they describe the same thing. `summary` counts what the reading rests on: statements matched before the limit, statements analysed, metrics and periods covered, how many were comparable, explicit, numeric or qualitative, and the direction counts behind `revisionBreadth` and `signal`. Every field of this response is declared, field by field, in the machine-readable contract at `/api/v1/schema` (JSON Schema 2020-12); the test suite validates each response against it.

Coverage

Call it

Send your ra_live_… key in the x-api-key header. Pick your language:

curl "https://raspberrytrades.com/api/v1/guidance/NVDA?change=lowered&limit=1" \
  -H "x-api-key: ra_live_your_key_here"