Reported Financial Statements (SEC)

Overview

Historical financial results the company has already reported to the SEC — not forecasts. Returns normalized annual or quarterly statements plus locally derived `analytics`: growth, margins, liquidity, leverage, cash flow, diagnostics and metric availability. The canonical annual view returns the latest SEC disclosure for each metric, unit and reporting context, so comparative facts repeated or restated in later filings do not consume the period limit; the raw view preserves every accession and source tag. The canonical quarterly view never presents six- or nine-month YTD cash flow as one quarter: it keeps reported isolated quarters, derives Q2/Q3 from adjacent comparable YTD facts when possible, and omits cumulative facts with no valid baseline. When a directly reported duration quarter and a YTD-derived quarter target the same metric/unit/end date, only the latest SEC disclosure is returned; within the same filing the directly reported quarter wins. Instant balances remain a separate economic context and are never collapsed with duration facts. `periodBasis` and `periodDerivation.inputs` make every subtraction and selection auditable down to SEC accession, dates and source values. Every comparison requires consecutive periods and every ratio requires inputs reported for the same fiscal end date. Coverage is lazy: an uncached ticker returns HTTP 202 while one free SEC Company Facts JSON is processed in the background.

Use it toRetrieve revenue, earnings, balance-sheet and cash-flow figures the company has already filed.

This endpoint contains reported historical facts. It is the correct endpoint for Apple revenue or earnings already announced. A first uncached request can return HTTP 202 with `Retry-After: 5`; repeat it after that interval. Successful responses expose source freshness in `source.retrievedAt`, profile freshness in `Last-Modified` and cache state in `X-Raspberry-Financials-Cache`. Authenticated responses are private-cacheable and are never marked for a shared public cache. Company Facts access is free and does not use an LLM. Canonical normalization currently targets US-GAAP; foreign issuers using another taxonomy can expose fewer or no canonical metrics, and the API reports that honestly instead of fabricating values. Stored US-GAAP observations must match their registered SEC tag and tag priority. Raspberry-derived free cash flow is accepted only when it exactly reconciles to operating cash flow minus the absolute capital expenditure for the same filing context. `metric` and `statement` may repeat as lists; repeated scalar `limit`, `period` or `view` parameters return HTTP 400. `coverage` reports the annual and quarterly periods the stored facts actually hold — an annual period is a roughly yearly duration filed on an annual form (a 52/53-week year), while quarterly durations disclosed inside a 10-K and half-year stubs are not counted as annual; balance-sheet instants at the fiscal year end belong to it — the earliest and latest period end, and a `note` that explains an empty answer: an issuer that has only just started filing (after a reorganisation, for example) reports quarters before its first annual report, so `period=annual` can legitimately return nothing. `coverage.reportedTaxonomies` lists the XBRL taxonomies the SEC publishes for the issuer and `coverage.ifrsFiler` is true when the figures were read from a foreign private issuer's IFRS filings (Form 20-F) rather than US GAAP ones — TSM, Spotify, HSBC, NEXA, China Yuchai, ChipMOS, Betterware and Abivax among them. Those issuers report in their own currency, so `coverage.reportingCurrency` states it and every value in the response is expressed in it: TSM in TWD, Spotify in EUR, HSBC in USD. US GAAP is always preferred when the issuer files it, so nothing about a US filer changes. 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. Beyond the observations, `analytics.latestByMetric` gives the newest value of each metric, `analytics.changes` the period-over-period move (`previousValue`, `previousEnd`, `absoluteChange`, `percentChange` in percentage points — 6.43 means +6.43 % — and `comparison`), `analytics.ratios` the derived ratios with the `formula` each one used, `analytics.diagnostics` a plain reading of revenue trend, profitability, free cash flow and debt position, and `analytics.metricAvailability` which of the expected metrics the issuer actually reports. Each observation states `durationDays`, the source `tag` and its `tagPriority`, and the SEC `frame` when there is one. 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/financials/AAPL?period=annual&metric=revenue&limit=1" \
  -H "x-api-key: ra_live_your_key_here"