> ## Documentation Index > Fetch the complete documentation index at: https://docs.numi.sh/llms.txt > Use this file to discover all available pages before exploring further. # History > The comparative periods of each filing, the vintage of each figure, the four views of a history and the filing-date snapshot. The history endpoints, `GET /v1/companies/{ref}/segments/history` and `GET /v1/companies/{ref}/fundamentals/history`, return the figures of one company across its filings, each entry with the filing that reported it and its `vintage`. ## Vintages An annual report carries up to three fiscal years of figures: its own year and two comparative years. A quarterly report carries its own quarter and the same quarter of the year before. Each of these periods is read, and the `vintage` of a row says which one it is: | `vintage` | The period | | - | - | | `0` | The filing's own period | | `1` | The comparative period one fiscal year earlier | | `2` | The comparative period two fiscal years earlier (annual reports only) | Some annual reports carry fewer than three years, so a company can have fewer than three years. The earliest years of a company exist only as comparatives: they have a row of vintage 1 or 2 and no row of vintage 0. The data covers the filings in numi's store only and does not go back beyond them. So `first` below means the earliest filing in that data, not the filing that first reported the figure anywhere. The comparative periods come from the facts of the filing. A period counts when the filing states revenue or net income for it on no dimension, and its end falls about one or two years before the end of the filing's own period. A response that names one filing, such as `GET /v1/companies/{ref}/segments`, returns the filing's own period only. Add `periods=all` for the comparative periods in a `comparatives` list. ## The four views The `view` parameter chooses which entries a history returns. Without it, the view is `own`. | `view` | Returns | | - | - | | `own` | One entry per filing: the filing's own period (vintage 0). A filing and its amendment for one period are two entries. | | `first` | One entry per fiscal period, from the earliest filing in numi's data that carries the period, in any vintage. | | `latest` | One entry per fiscal period, from the newest filing that carries the period, in any vintage. This is the latest recast series. | | `all` | Every period of every filing, vintages included. | A fiscal period is identified by its start and its end together, with the period type. A year-to-date cash flow in a 10-Q and the revenue of its quarter end on the same day and are two different periods. A company that changes its fiscal year gets periods with different ends, and they stay separate. Filings are ordered by filing date, then by id. For `first` and `latest`, the filing is chosen for each period and each axis, or for each period and each metric, and never for the period alone. A 10-K/A that restates only revenue wins `latest` for revenue, and the original 10-K keeps net income. So two entries of one response can come from different filings, and every entry names the filing it came from. ### An example Microsoft's 10-K for the year ending 2025-06-30 (filed 2025-07-30) and its 10-K for the year ending 2026-06-30 (filed 2026-07-29) both carry the revenue of fiscal year 2025. When both filings are in numi's data, this request returns the revenue of Microsoft in the `latest` view: ```bash theme={null} curl "https://api.numi.sh/v1/companies/MSFT/fundamentals/history?metric=revenue&view=latest" \ -H "X-API-Key: $NUMI_API_KEY" ``` Each cell below is the entry of that view for a fiscal year, with the filing it came from and its vintage in that filing: | Fiscal year | `own` | `first` | `latest` | `all` | | - | - | - | - | - | | 2023 | | 2025 10-K, vintage 2 | 2025 10-K, vintage 2 | 2025 10-K, vintage 2 | | 2024 | | 2025 10-K, vintage 1 | 2026 10-K, vintage 2 | both filings | | 2025 | 2025 10-K, vintage 0 | 2025 10-K, vintage 0 | 2026 10-K, vintage 1 | both filings | | 2026 | 2026 10-K, vintage 0 | 2026 10-K, vintage 0 | 2026 10-K, vintage 0 | 2026 10-K, vintage 0 | The revenue of fiscal year 2025 is 281,724,000,000 US dollars in the 2025 10-K as its own period, and 281,724,000,000 in the 2026 10-K as its first comparative period. Microsoft did not restate it, so the two entries agree. When a company restates a figure, the two entries differ, and `first` returns the figure as the earliest filing in the data reports it while `latest` returns the restated figure. The 2023 and 2024 years of the table exist only as comparatives of the 2025 10-K, so `own` has no entry for them. A restated figure stays with the filing that restated it; numi does not pick a winner, the `view` does. ## Snapshots with `as_of` `as_of` takes a date as `YYYY-MM-DD` and keeps only the filings with a filing date on or before it. It applies to every view, and before `first` and `latest` choose a filing, so a filing after the date never leaks into an earlier snapshot. With `view=latest&as_of=2026-01-01`, the request above returns the figures as the filings of 2025 and earlier gave them. `as_of` is a snapshot by filing date, at day granularity. A filing filed on the date is in. It does not cut by the hour, and it is not an intraday point-in-time cut. A date that is not on the calendar, such as `2026-02-30`, is a 400 `bad_request`. ## An empty history A history with no entries still answers with status 200. `filings_checked` is the number of extracted filings of the period type that numi holds for the company, and `reason` says why `entries` is empty: `no_extracted_data` when numi read no such data from those filings, `not_extracted` when the filings are in the data and not read yet, `no_filings` when numi holds no filing of the company yet, and `none_before_as_of` when every filing is later than `as_of`. When `entries` is not empty, `reason` is null. ## In the MCP server The tools `get_segment_history` and `get_fundamentals_history` take the same `view` and `as_of`. `get_segments` and `get_fundamentals` take `periods`. See [the MCP server](https://docs.numi.sh/mcp-server.md). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.