# Time series A time series route returns one metric across a company's whole reporting history in a single request. It resolves in a fixed number of queries no matter how many years it spans, so a wide request costs little more than a narrow one. Prefer one wide call to a year-by-year loop. ## One request, whole history ```bash curl -X GET "https://api.arche.fi/v1/edgar/companies/0000789019/metrics/REVENUE/time-series?page_size=50" \ -H "X-Api-Key: $ARCHE_API_KEY" \ -H "X-Request-ID: $(uuidgen)" \ -H "Accept: application/json" ``` Representative response: ```json { "page": 1, "page_size": 50, "total": 19, "items": [ { "cik": "0000789019", "metric": "REVENUE", "value": "60420000000.000000", "unit": "USD", "period_end": "2008-06-30" } ] } ``` Values are decimal strings. Keep them as strings or decimals through your pipeline — `"60420000000.000000"` parsed to a binary float is a figure that no longer reconciles against the filing. ## A single metric The useful narrowing parameters: - `period_type` (annual | quarterly): Which cadence to return. Without it you get both, and mixing annual and quarterly rows in one series is a common source of nonsense growth rates. - `fiscal_year_from / fiscal_year_to` (integer): Bound the series by fiscal year. - `fiscal_period` (FY | Q1 | Q2 | Q3): A single period across years — every Q3 in the company's history, say. - `statement_type` (string): Disambiguates a metric that appears on more than one statement. - `include_provenance` (boolean): Attaches the source concept and accession to each point. Use it when the series is going into anything auditable. The metric name must be canonical. A derived name such as `GROSS_MARGIN` belongs to [modeling](https://docs.arche.fi/modeling), not here — see [Metric catalog](https://docs.arche.fi/metrics). ## Point-in-time series `as_of_date` anchors the whole series to a historical boundary, so every point is the value that was knowable on that date rather than today's restated value: ```bash curl -X GET "https://api.arche.fi/v1/edgar/companies/0000789019/metrics/REVENUE/time-series?as_of_date=2024-03-31&period_type=annual&page_size=50" \ -H "X-Api-Key: $ARCHE_API_KEY" \ -H "X-Request-ID: $(uuidgen)" \ -H "Accept: application/json" ``` This is the route to build features from in a backtest. Without `as_of_date` the series reflects the current best understanding of history, which is the correct answer to a different question. ## As-reported vs restated `as_reported=true` returns each period as the filer originally stated it, rather than as later amended: ```bash curl -X GET "https://api.arche.fi/v1/edgar/companies/0000789019/metrics/REVENUE/time-series?as_reported=true&period_type=annual&page_size=50" \ -H "X-Api-Key: $ARCHE_API_KEY" \ -H "X-Request-ID: $(uuidgen)" \ -H "Accept: application/json" ``` The distinction from `as_of_date` matters: - `as_reported=true` asks **what did the filer say at the time**, across all periods. - `as_of_date=…` asks **what was knowable on this date**, which includes restatements that had already arrived by then. They answer different questions and can be combined. ## Whole financial state Every canonical metric per period, rather than one metric across periods: ```bash curl -X GET "https://api.arche.fi/v1/edgar/companies/0000789019/financial-state/time-series?page_size=50" \ -H "X-Api-Key: $ARCHE_API_KEY" \ -H "X-Request-ID: $(uuidgen)" \ -H "Accept: application/json" ``` Each row is a fiscal period with its full metric set. This is the efficient way to populate a model for one company — one request instead of one per metric. ## Bundles and derived series A curated [bundle](https://docs.arche.fi/metrics) across the reporting history, by bundle code: ```bash curl -X GET "https://api.arche.fi/v1/edgar/companies/0000789019/metric-bundles/core_balance_sheet/time-series?page_size=50" \ -H "X-Api-Key: $ARCHE_API_KEY" \ -H "X-Request-ID: $(uuidgen)" \ -H "Accept: application/json" ``` Derived metrics have their own series route, since they are computed rather than mapped. Its parameters differ from the routes above — it takes `ciks` and `metrics` (plural, repeatable) and requires `statement_type`: ```bash curl -X GET "https://api.arche.fi/v1/edgar/derived-metrics/time-series?ciks=0000789019&statement_type=CASH_FLOW_STATEMENT&metrics=FCF_CONVERSION&frequency=annual" \ -H "X-Api-Key: $ARCHE_API_KEY" \ -H "X-Request-ID: $(uuidgen)" \ -H "Accept: application/json" ``` It also answers in its own shape — a single object with the request echoed back and the series under `points`, rather than a paginated `items` list: ```json { "data": { "ciks": ["0000789019"], "statement_type": "CASH_FLOW_STATEMENT", "frequency": "annual", "from_date": "1994-01-01", "to_date": "2026-09-21", "points": [ { "cik": "0000789019", "statement_type": "CASH_FLOW_STATEMENT", "accounting_standard": "US_GAAP", "statement_date": "2008-06-30", "fiscal_year": 2008, "fiscal_period": "FY", "currency": "USD", "metrics": { "FCF_CONVERSION": "1.042362" } } ] } } ``` Because it accepts several CIKs at once, it is the efficient way to pull one derived metric across a peer group. A derived series can have gaps where a canonical input was absent for a period. That is the metric declining to invent a value, not a coverage gap — check `dependencies` in the [derived catalog](https://docs.arche.fi/metrics) to see what it needed. > **Note:** A parallel `'/v1/fundamentals/*'` namespace exposes several of > these same shapes. Prefer the `'/v1/edgar/*'` routes documented > here: they are the ones the guides, the > [Python SDK](https://docs.arche.fi/sdks/python) and the point-in-time surface are > built around. ## Next steps - [Company identity](https://docs.arche.fi/identity): Resolve tickers to full issuer records, search by name, and read mapping validity. - [Metric catalog](https://docs.arche.fi/metrics): Look up canonical and derived metric names, formulas, bundles and segments. - [Modeling](https://docs.arche.fi/modeling): Snapshot-anchored ratios, growth, TTM aggregates and normalized model periods.