The oldest record in the whole dataset covers a period ending 26 April 2009, and that date is almost never the answer to the question you are asking. What you get for a given ticker on the Massive financials endpoints is later, sometimes years later, and it is set by that company rather than by us. Ask for the oldest record instead of assuming one.
Applies to
- Plans: Stocks Advanced, or any plan carrying the Financials and Ratios Expansion, both of which get all history. Basic, Starter, Developer and plain Business do not include financials at all.
- Endpoints: /stocks/financials/v1/income-statements, /stocks/financials/v1/balance-sheets, /stocks/financials/v1/cash-flow-statements.
- Asset classes: US stocks.
How to find the floor for a ticker
Ask for the oldest record rather than working it out:
curl -X GET "https://api.massive.com/stocks/financials/v1/income-statements?tickers=AAPL&timeframe=annual&sort=period_end.asc&limit=1&apiKey=YOUR_API_KEY"
Response
{
"status": "OK",
"results": [
{ "tickers": ["AAPL"], "period_end": "2010-09-25", "filing_date": "2012-10-31",
"fiscal_year": 2010, "fiscal_quarter": 4, "timeframe": "annual" }
]
}
Apple's oldest annual record covers the year ending 25 September 2010, and its oldest quarterly one the quarter ending 26 December 2009. Change timeframe to quarterly for the 10-Q series. Sorting ascending is what makes this one request rather than a paging exercise.
The filing_date of 2012-10-31 on a 2010 period is not a mistake. That field names the most recent filing that carried the period's data, and a later 10-K restates prior years as comparatives.
What affects how far back a company goes
How far back a company goes is affected by three things, in the order they usually bite:
| Cause | Effect |
|---|---|
| When the company listed | A company that IPO'd in 2021 has no filings before then, whatever the archive holds |
| When it began filing in the structured format | Older filings exist as documents but are not parsed into line items |
| Whether the plan carries financials at all | Financials are an Advanced or Expansion feature, not part of the reference data every plan gets |
The third is the one to rule out first, because it looks identical to the other two from the outside: a NOT_AUTHORIZED response is entitlement, while an empty results array with HTTP 200 means the record genuinely is not there.
Why the floor is not one date
The floor is not one date because financial statements are parsed from filings rather than captured from a feed. Market data has a single start, the day we began capturing the tape, but a filing's availability depends on the company: when it listed, when it started filing electronically in a structured form, and whether it has restated or amended anything since.
If you see an error
An empty results array with HTTP 200 means no record for that period, not a failure.
{"status":"NOT_AUTHORIZED"} means the plan does not carry financials at all, not that the period is too old.
A period that exists for one company and not another at the same date is expected: the floor is per company.
