# Version analytics

The [restatement timeline](https://docs.arche.fi/guides/restatement-drift) tells you that a period was
revised and how severely. These routes tell you what the revision did to a
number you care about.

All of them identify a period the same way: `statement_type`, `fiscal_year` and
`fiscal_period`, with `cik` or `ticker` naming the company.

## Which route answers which question

- `how far has one metric moved` (/v1/analysis/metric-drift): Original against latest, for one metric, in one period.
- `what changed between two versions` (/v1/analysis/version-delta): Original against a comparison version, for one metric.
- `every metric that changed` (/v1/edgar/statements/restatements/delta): A per-metric diff between two versions you name, rather than one metric.
- `what it did to derived figures` (/v1/analysis/model-impact): Valuation and sensitivity across the ordered version lineage.

## Metric drift

```bash
curl -X GET "https://api.arche.fi/v1/analysis/metric-drift?ticker=AAPL&statement_type=INCOME_STATEMENT&fiscal_year=2024&fiscal_period=FY&metric=REVENUE" \
  -H "X-Api-Key: $ARCHE_API_KEY" \
  -H "Accept: application/json"
```

A period no filer revised answers `200` with nothing moved, which is an answer
rather than a gap. [`/v1/edgar/restatement-alerts`](https://docs.arche.fi/reference) lists the periods
that were revised, so start there when you want a period with drift in it.

`metric` must be a canonical statement metric. This route reads filed facts only,
so a market-dependent derived metric is refused rather than estimated. See the
[metric catalog](https://docs.arche.fi/metrics) for which names are which.

## Version delta

The same shape, comparing the original against a specific later version instead
of against the latest:

```bash
curl -X GET "https://api.arche.fi/v1/analysis/version-delta?ticker=AAPL&statement_type=BALANCE_SHEET&fiscal_year=2024&fiscal_period=FY&metric=TOTAL_ASSETS" \
  -H "X-Api-Key: $ARCHE_API_KEY" \
  -H "Accept: application/json"
```

Market-dependent metrics are refused here too, for the same reason.

## Delta between two named versions

When the question is "everything that changed", not one metric, name the two
versions and read the whole diff:

```bash
curl -X GET "https://api.arche.fi/v1/edgar/statements/restatements/delta?ticker=AAPL&statement_type=BALANCE_SHEET&fiscal_year=2024&fiscal_period=FY&from_accession={from_accession}&to_accession={to_accession}" \
  -H "X-Api-Key: $ARCHE_API_KEY" \
  -H "Accept: application/json"
```

Name the versions with exactly one selector pair, either `from_accession` and
`to_accession` or `from_statement_version_id` and `to_statement_version_id`.

> **Note:** `/v1/fundamentals/restatement-delta` is the same comparison under
> the [fundamentals](https://docs.arche.fi/fundamentals) namespace, and additionally
> takes `metrics` to narrow the diff. Either route answers; pick the
> namespace the rest of your integration already uses.

## Model impact

What the revision did to derived figures across the version lineage, rather than
to a filed fact:

```bash
curl -X GET "https://api.arche.fi/v1/analysis/model-impact?ticker=AAPL&statement_type=INCOME_STATEMENT&fiscal_year=2024&fiscal_period=FY" \
  -H "X-Api-Key: $ARCHE_API_KEY" \
  -H "Accept: application/json"
```

Unlike the two routes above, this one can depend on market inputs, because
persisted metrics such as `MARKET_CAP` and `ENTERPRISE_VALUE` may be present in
the lineage. When they are, the route requires you to acknowledge that with
`allow_market_inputs=true`, so a figure that depends on a price is never returned
to a caller who believed they were reading filings alone.

## Next steps

- [Company identity](https://docs.arche.fi/identity): Resolve tickers to full issuer records, search by name, and read mapping validity.
- [Time series](https://docs.arche.fi/time-series): Pull a metric across a whole reporting history, point-in-time or as-reported.
- [Fundamentals](https://docs.arche.fi/fundamentals): Read panels across many companies, name a statement by its identity, and pull the approved macro context.