The gap between filing_date and the first filing decides whether a point-in-time backtest on the Massive financials endpoints works. A filing_date.lte filter on income statements, balance sheets or cash flow statements adds no look-ahead, but it hides years that were already public. The dollar figures on each record come from the most recent filing that included the period, so a restatement replaces the numbers first published, and share counts and earnings per share on the income statements are restated for later stock splits as well.
Applies to
- Plans: Stocks Advanced, or any plan carrying the Financials and Ratios Expansion, for the three statement endpoints. The SEC EDGAR Index endpoint is included in all Stocks plans.
- Endpoints: /stocks/financials/v1/income-statements, /stocks/financials/v1/balance-sheets, /stocks/financials/v1/cash-flow-statements and /stocks/filings/vX/index.
- Asset classes: US stocks.
What a filing_date filter returns for a past date
A filing_date.lte filter on the financials endpoints returns only the periods whose most recent filing is on or before that date. Here is Apple's latest annual income statement as a backtest dated 31 December 2024 would select it:
curl -X GET "https://api.massive.com/stocks/financials/v1/income-statements?tickers=AAPL&timeframe=annual&filing_date.lte=2024-12-31&sort=period_end.desc&limit=2&apiKey=YOUR_API_KEY"
Response
{
"status": "OK",
"results": [
{ "tickers": ["AAPL"], "period_end": "2022-09-24", "filing_date": "2024-11-01",
"fiscal_quarter": 4, "fiscal_year": 2022, "timeframe": "annual" },
{ "tickers": ["AAPL"], "period_end": "2021-09-25", "filing_date": "2023-11-03",
"fiscal_quarter": 4, "fiscal_year": 2021, "timeframe": "annual" }
]
}
The newest year the filter returns is fiscal 2022. Apple's fiscal 2023 and fiscal 2024 annual income statements were both public by 31 December 2024, but both records carry the filing_date of a later 10-K that repeated them as comparatives, so neither passes the filter. Every record the filter returns was public on the filter date, so there is no look-ahead; the cost is the periods it drops.
How to find the date a period was first filed
The original filing date of a 10-K or 10-Q is on the SEC EDGAR Index endpoint, which lists each filing with the date it was submitted to the SEC. The financials documentation points to it for exactly this:
curl -X GET "https://api.massive.com/stocks/filings/vX/index?ticker=AAPL&form_type=10-K&filing_date.lte=2024-12-31&limit=3&apiKey=YOUR_API_KEY"
Response
{
"status": "OK",
"results": [
{ "form_type": "10-K", "filing_date": "2024-11-01",
"filing_url": "https://www.sec.gov/Archives/edgar/data/320193/0000320193-24-000123.txt" },
{ "form_type": "10-K", "filing_date": "2023-11-03",
"filing_url": "https://www.sec.gov/Archives/edgar/data/320193/0000320193-23-000106.txt" },
{ "form_type": "10-K", "filing_date": "2022-10-28",
"filing_url": "https://www.sec.gov/Archives/edgar/data/320193/0000320193-22-000108.txt" }
]
}
The 10-K filed on 2024-11-01 is the one that first reported fiscal 2024, which ended on 2024-09-28. To build a point-in-time view from the SEC EDGAR Index:
- List the company's 10-K and 10-Q filings with /stocks/filings/vX/index.
- Match each filing to a period_end. Each filing's filing_url opens the filing on SEC.gov, and its header states the period of report (CONFORMED PERIOD OF REPORT: 20240928 for the filing above).
- Treat each period as known from its first filing date, not from period_end and not from the filing_date on the financials record.
The dollar figures on a record come from the latest filing
The dollar figures on a Massive financials record come from the latest filing that included the period: the financials endpoints keep one record per period and timeframe, not one per filing. When a later filing restates a prior year, the record changes to the restated figures:
curl -X GET "https://api.massive.com/stocks/financials/v1/income-statements?tickers=GE&timeframe=annual&period_end=2022-12-31&apiKey=YOUR_API_KEY"
Response
{
"status": "OK",
"results": [
{ "period_end": "2022-12-31", "filing_date": "2025-02-03", "fiscal_quarter": 4,
"fiscal_year": 2022, "timeframe": "annual", "revenue": 29139000000.0 }
]
}
GE's 10-K filed on 10 February 2023 reported 2022 total revenues of $76,555 million. The record carries $29,139 million and the filing_date of the 10-K filed on 3 February 2025, which restated that year. The financials endpoints have no parameter that returns an earlier version of a record, so figures as first reported have to come from the original filing itself.
Share counts and earnings per share on a Massive income statement do not follow the latest-filing rule. They are restated to the company's current share basis, including stock splits made after the filing named in filing_date, so they can differ from every filing. NVIDIA's quarter ending 25 October 2020 shows 40 times the diluted share count its original 10-Q reported, although its filing_date is in 2021, before the 2024 split. Are Massive's fundamentals adjusted for stock splits? shows that record and how to recover the share count as first filed.
Which dates mean what
The dates on a record are not interchangeable, so read what each one marks before you key anything on it:
| Field | What it marks |
|---|---|
| period_end | The last day of the period the numbers cover |
| filing_date | The day of the most recent SEC filing that included this period's data |
| fiscal_year and fiscal_quarter | The company's own fiscal labeling, which need not follow the calendar |
The filing_date rule is the same on quarterly and trailing-twelve-month records as on annual ones. Apple's quarter ending 2025-06-28 was first filed in a 10-Q on 2025-08-01, and its quarterly and trailing-twelve-month records both carry filing_date 2026-07-31, the date of the following year's third-quarter 10-Q, which repeated it as a comparative.
Why period_end is the tempting wrong answer
period_end is tempting because it is the date the numbers describe, and a spreadsheet reads naturally when a quarter sits on the quarter. It is the wrong key for anything that simulates decisions, because the gap between a period ending and its filing is weeks and varies by company and by filing type.
You cannot sort on filing_date, only filter: sort accepts cik, period_end, fiscal_year, fiscal_quarter and timeframe, and anything else is a 400 that names the list.
If you see an error
A filing_date later than you expect on an old period means a later filing, such as a 10-K, a 10-Q or an amended 10-K/A, included the period. The field names the most recent filing carrying the data, not the first.
The older /vX/reference/financials endpoint no longer returns data: the changelog lists it as sunset on 22 June 2026, and its Sunset response header gives 9 October 2026. An HTTP 410 with this body comes from that endpoint:
{"status":"GONE","error":"This endpoint has been deprecated and is undergoing a brownout. Please check the Sunset and Link response headers for migration details."}
Move to the /stocks/financials/v1/ endpoints above, which carry filing_date on every record.
A NOT_AUTHORIZED response means the plan does not carry financials. It is an Advanced or Expansion feature, not part of the reference data every plan gets.
