> ## Documentation Index
> Fetch the complete documentation index at: https://doc.astreus.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Data provenance

> Where every number comes from, and how to trace it back to the filing.

Astreus is built on one refusal: **no number without a source.** This page explains
the pipeline behind that promise — and the endpoint that lets you audit it yourself.

## The pipeline

<Steps>
  <Step title="Filings, at the source">
    SEC 10-K, 10-Q, 8-K, 20-F and 40-F filings are ingested directly from EDGAR, XBRL facts
    and all — including the presentation tree and calculation linkbase, not just the tagged
    values. Exchange-lane issuers (Tadawul, DFM, ADX, Boursa Kuwait, QSE, TSE, TWSE, KRX,
    European exchanges) are read from the statements, results announcements and reports they
    publish, as inline XBRL, HTML or PDF.
  </Step>

  <Step title="Standardization with receipts">
    Each filer's lines are mapped onto one canonical schema (`std:revenue`,
    `std:operating_income`, …) so companies are comparable across markets and rulebooks. The
    mapping is stored, not discarded: every standardized line keeps a pointer to the raw
    fact(s) — or the printed cell — it came from.
  </Step>

  <Step title="Validation gates">
    Before anything is served, per-company invariant batteries run: statements must tie,
    values are reconciled against the regulator's own data where one exists (the SEC
    `companyfacts` API), and share counts, splits and restatements are cross-checked. Segment
    blocks must reconcile to the consolidated figure; note tables must foot and tie to the
    statement anchor; derived quarters must foot. Data that fails a gate is withheld — you see
    a null or a `held` entry, never a guess.
  </Step>

  <Step title="Serving, still auditable">
    The `fact-source` endpoint closes the loop at read time: any line, any period, back to the
    fact or printed cell, the filing accession or document reference, and the arithmetic
    behind derived values.
  </Step>
</Steps>

## Trace a number

```bash theme={null}
curl "https://astreus.ai/api/v1/companies/NVDA/fact-source?statement=income_statement&key=std:revenue&end_date=2024-10-27&period_type=quarterly" \
  -H "X-API-KEY: pk_live_YOUR_KEY"
```

The response names the XBRL concept, the accession number of the filing the value was
taken from, the raw fact with its context, unit and decimals, and any later revisions of
the same fact. Put the accession next to the number when you quote it — that is the
citation. The full parameter and provenance vocabulary is on
[Financial statements](/financial-statements#citing-a-cell-fact-source).

## What the gates mean for you

* **A null is a withheld or never-reported value** — the gate refusing to serve
  something it could not verify. Treat it as unavailable, never as zero.
* **Restatements are first-class.** `/financials` serves the latest restated value and
  `fact-source` tells you which filing it came from; `/financials/as-filed` with
  `vintage=original` gives what was originally filed. See [Data semantics](/data-semantics).
* **Derived Q4 is marked.** Most US filers file no Q4 10-Q; the fourth quarter is derived
  from the annual total minus Q1–Q3 and returned with `provenance: "derived_q4"` and its
  arithmetic.
* **Held is visible.** Note tables and segment blocks that failed a hard gate are listed as
  held, with the reason, and never carry values.

## Every corpus, and its provenance property

| Data                       | Source                                                                  | Provenance property                                                                     |
| -------------------------- | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| Standardized statements    | EDGAR XBRL; exchange-published statements (iXBRL, HTML, PDF)            | Every cell → fact or printed cell → filing; `provenance` names the lane                 |
| As-filed statements        | The same documents                                                      | Every cell → `docRef` and `own` / `comparative` vintage                                 |
| Segments & KPIs            | Filing segment notes; results releases; investor decks                  | `source.accession`, `sourceTag`, `vintage`, `q4Provenance`; deck rows cite the slide    |
| Filing-note tables         | Notes to the statements (iXBRL, HTML, PDF)                              | Per-cell `source` (XBRL context, HTML row, or PDF page + x-range); gate verdicts listed |
| Filing sections            | The filing text                                                         | Section text served verbatim, scoped to the filing                                      |
| 8-K events                 | EDGAR                                                                   | Typed by item code; extracted text served verbatim                                      |
| Transcripts & observations | Licensed providers; issuer IR sites; platform transcription             | Observations are span-anchored into the exact passage                                   |
| Guidance                   | Transcripts                                                             | Each commitment cites its call; resolutions cite the reported figure                    |
| Ownership                  | Forms 3/4/5, 13F                                                        | Positions reconciled filing by filing                                                   |
| Macro series               | FRED / ALFRED                                                           | Full revision vintages — point-in-time reads never look ahead                           |
| News                       | SEC, issuer, exchange, regulator and central-bank feeds; licensed wires | Every item carries its source attribution and display policy                            |
| Prices                     | Market data feeds                                                       | Split-adjusted; used for reactions and charts, not tick trading                         |