# Provenance

Every normalized figure Arche serves was mapped from a concept a filer tagged in
an XBRL document. These routes expose that mapping, one metric at a time, so a
number in your model can be answered for rather than trusted.

They all key off a `statement_version_id`, which you get from
[`/v1/edgar/companies/{cik}/statements`](https://docs.arche.fi/quickstart).

## Why trace a figure

Normalization is where a dataset either earns trust or quietly loses it. Two
filers tag revenue with different concepts; one restates; one reports a segment
breakdown the mapping has to choose among. When a figure looks wrong, the
question is never "is the API up" — it is "which tag did this come from, and was
a rule applied to it".

## Metric provenance

The fullest answer for one metric on one statement version:

```bash
curl -X GET "https://api.arche.fi/v1/edgar/statements/e460c540-4378-406c-8b8d-13903c332b86/metrics/REVENUE/provenance" \
  -H "X-Api-Key: $ARCHE_API_KEY" \
  -H "X-Request-ID: $(uuidgen)" \
  -H "Accept: application/json"
```

Representative response:

```json
{
  "data": {
    "statement_version_id": "e460c540-4378-406c-8b8d-13903c332b86",
    "cik": "0000320193",
    "metric": "REVENUE",
    "value": "109417000000.000000",
    "source_accession": "0000320193-26-000020",
    "filing_type": "10-Q",
    "filing_date": "2026-07-31",
    "accepted_at": "2026-07-31T10:01:02Z",
    "source_line_item": "us-gaap:RevenueFromContractWithCustomerExcludingAssessedTax",
    "source_xbrl_concept": null,
    "mapping_type": null,
    "override_applied": false,
    "override_reason": null,
    "calculation_steps": null,
    "source_context": null,
    "source_hash": null
  }
}
```

That answers the question end to end: this revenue figure is the
`us-gaap:RevenueFromContractWithCustomerExcludingAssessedTax` fact from accession
`0000320193-26-000020`, a 10-Q accepted on 2026-07-31.

`override_applied` is the field to check before relying on a figure in an audit
context. When it is `true`, `override_reason` names why, and the value you are
holding is not the one the filer tagged.

## Corrected values

A figure can come from a filed fact and still differ from the number in the
filing. Normalization corrects two known tagging errors:

- `COST_OF_REVENUE_CREDIT_SIGN` (correction_rule): The filer tagged a cost as a credit, so its sign was reversed.
- `REVENUE_RESIDUAL_TOP_LINE_REPLACED` (correction_rule): The top line was first selected from a residual concept, and was replaced by
  the revenue the filer reported alongside its own gross profit.

Both leave `value_origin` as `SOURCE`, because both values come from a filed
fact. To tell a corrected figure from an untouched one, read these fields on
each fact in a statement's `normalized_payload.facts`:

- `correction_rule` (string | null): The correction applied to this value. `null`, the usual case, means the
  value is exactly as tagged.
- `as_filed_value` (decimal string | null): The value as the filing tagged it, before the correction. `null` when the
  correction chose a different fact rather than changing the number.
- `as_filed_concept` (string | null): The XBRL concept of the value that was replaced, when the correction chose
  a different fact.

Statements normalized before corrections were recorded report `null` in all
three fields, so a `null` on an older statement does not prove that no
correction was applied.

## Audit chain

A condensed view of the same lineage, plus the overrides that touched it:

```bash
curl -X GET "https://api.arche.fi/v1/edgar/statements/e460c540-4378-406c-8b8d-13903c332b86/metrics/REVENUE/audit-chain" \
  -H "X-Api-Key: $ARCHE_API_KEY" \
  -H "X-Request-ID: $(uuidgen)" \
  -H "Accept: application/json"
```

Representative response:

```json
{
  "data": {
    "metric_name": "REVENUE",
    "statement_version_id": "e460c540-4378-406c-8b8d-13903c332b86",
    "filing_accession": "0000320193-26-000020",
    "xbrl_concept": "us-gaap:RevenueFromContractWithCustomerExcludingAssessedTax",
    "mapping_type": null,
    "overrides": []
  }
}
```

Use the audit chain when you want a compact record to store next to a figure,
and provenance when you are investigating one.

## Fact revisions

Which individual facts changed between versions of a statement:

```bash
curl -X GET "https://api.arche.fi/v1/edgar/statements/e460c540-4378-406c-8b8d-13903c332b86/fact-revisions?page_size=50" \
  -H "X-Api-Key: $ARCHE_API_KEY" \
  -H "X-Request-ID: $(uuidgen)" \
  -H "Accept: application/json"
```

`items` is empty for a version whose facts were never revised, which is the
ordinary case. An empty list here is the answer "nothing was revised", not
missing data — the same distinction the
[restatement timeline](https://docs.arche.fi/guides/restatement-drift) draws.

## Override trace

Which mapping rules were evaluated for a statement identity, and what they did:

```bash
curl -X GET "https://api.arche.fi/v1/edgar/companies/0000320193/statements/overrides/trace?statement_type=INCOME_STATEMENT&fiscal_year=2025&fiscal_period=FY&version_sequence=1" \
  -H "X-Api-Key: $ARCHE_API_KEY" \
  -H "X-Request-ID: $(uuidgen)" \
  -H "Accept: application/json"
```

Representative response:

```json
{
  "data": {
    "cik": "0000320193",
    "statement_type": "INCOME_STATEMENT",
    "fiscal_year": 2025,
    "fiscal_period": "FY",
    "version_sequence": 1,
    "total_facts_evaluated": 0,
    "total_facts_remapped": 0,
    "total_facts_suppressed": 0,
    "rules": []
  }
}
```

Zero counts with an empty `rules` mean no override rule fired for that identity,
which is what you want to see on a clean filing. Non-zero `total_facts_remapped`
or `total_facts_suppressed` tells you the served statement differs from a
literal reading of the filer's tags, and `rules` says which rules are
responsible.

## Reading null provenance

Several provenance fields are frequently `null`, and they mean different things:

- `source_line_item` (string | null): The XBRL concept the value was read from. This is the field that usually
  carries the answer.
- `source_xbrl_concept` (string | null): A second concept field that is often `null` even when
  `source_line_item` is populated. Read `source_line_item` first.
- `mapping_type` (string | null): `null` where the mapping was a direct concept match needing no rule.
- `calculation_steps` (array | null): Populated only for a derived figure. `null` on an as-reported value, which
  is the stronger provenance of the two.

A `null` here is not a gap in the audit trail as long as `source_accession` and
`source_line_item` are populated — together those identify the fact uniquely.

## 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.
- [Metric catalog](https://docs.arche.fi/metrics): Look up canonical and derived metric names, formulas, bundles and segments.