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

# Provenance

> Every observation traces back to its named source, source URL, raw payload reference, and ingestion run. One endpoint gives you an auditable chain from official release to API response.

When a number drives a decision, you need to be able to defend where it came from. Financial Data API attaches provenance to every observation and exposes a dedicated endpoint that returns the full chain: the **named source**, the **source URL**, a **raw payload reference**, and the **ingestion run** that recorded it. Together these let you walk backward from any value in an API response to the official release it originated from.

## What every observation already carries

You do not have to make a second call to get basic attribution. Observation responses include, inline:

<ResponseField name="provider" type="string">
  The named publisher the value came from (for example, a central bank or statistics office).
</ResponseField>

<ResponseField name="sourceUrl" type="string">
  A URL pointing at the originating release or dataset.
</ResponseField>

<ResponseField name="attribution" type="string">
  The required attribution string for the value.
</ResponseField>

<ResponseField name="freshnessStatus" type="string">
  The freshness label: `fresh`, `stale`, or `unknown`.
</ResponseField>

<ResponseField name="rawAvailable" type="boolean">
  Whether a captured upstream payload is on record for this value. The raw body itself is never returned; this flag proves the value was derived from a specific captured response, retrievable through the provenance endpoint as a reference.
</ResponseField>

<ResponseField name="rights" type="object">
  Rights and exposure metadata governing how the value may be used.
</ResponseField>

<Note>
  The raw payload reference is an identifier, not the payload. Financial Data API never re-serves upstream provider bodies; the reference exists only to prove a value was derived from a specific captured response.
</Note>

## The provenance endpoint

For the complete auditable chain on a single observation, call:

```
GET /provenance/observations/{observationId}
```

<ParamField path="observationId" type="string" required>
  The identifier of the observation you want to trace. You get this from any observation response.
</ParamField>

It returns the named source, the source URL, raw payload reference metadata, and the ingestion run that produced the value: an auditable chain from the official release all the way to the API response you received.

<CodeGroup>
  ```bash cURL theme={"theme":"css-variables"}
  curl -G "https://api.financialdatapi.com/provenance/observations/obs_01HZX9K2P7QF3M4N5R6S7T8U9V" \
    -H "x-api-key: $FINANCIALDATA_API_KEY"
  ```

  ```python Python theme={"theme":"css-variables"}
  import os, requests

  observation_id = "obs_01HZX9K2P7QF3M4N5R6S7T8U9V"
  resp = requests.get(
      f"https://api.financialdatapi.com/provenance/observations/{observation_id}",
      headers={"x-api-key": os.environ["FINANCIALDATA_API_KEY"]},
  )
  resp.raise_for_status()
  print(resp.json()["data"])
  ```

  ```typescript TypeScript theme={"theme":"css-variables"}
  import { FinancialDataApiClient } from "@financialdatapi/client";

  const client = new FinancialDataApiClient({ apiKey: process.env.FINANCIALDATA_API_KEY });

  const { data } = await client.getProvenance(
    "obs_01HZX9K2P7QF3M4N5R6S7T8U9V",
  );
  console.log(data);
  ```
</CodeGroup>

### Example response

```json theme={"theme":"css-variables"}
{
  "data": {
    "observation": {
      "observationId": "obs_01HZX9K2P7QF3M4N5R6S7T8U9V",
      "indicatorId": "cpi_inflation_yoy",
      "country": "USA",
      "actual": 3.2,
      "unit": "percent",
      "period": "May 2026",
      "periodEnd": "2026-05-31",
      "observedAt": "2026-06-11T12:30:00Z",
      "provider": "U.S. Bureau of Labor Statistics",
      "sourceUrl": "https://www.bls.gov/news.release/cpi.htm",
      "freshnessStatus": "fresh",
      "rawAvailable": true,
      "rights": { "exposureClass": "public" }
    },
    "rawPayload": {
      "rawPayloadId": "raw_01HZX8B0C1D2E3F4G5H6J7K8M9",
      "sourceId": "src_bls_cpi",
      "providerId": "prv_bls",
      "ingestionRunId": "run_01HZX7A0YBQ2C3D4E5F6G7H8J9",
      "contentHash": "sha256:9f2c…",
      "retrievedAt": "2026-06-11T12:30:04Z",
      "rawAvailable": true
    },
    "source": { "id": "src_bls_cpi", "name": "U.S. Bureau of Labor Statistics" },
    "provider": { "id": "prv_bls", "name": "U.S. Bureau of Labor Statistics" },
    "ingestionRun": {
      "id": "run_01HZX7A0YBQ2C3D4E5F6G7H8J9",
      "status": "completed",
      "startedAt": "2026-06-11T12:30:04Z",
      "completedAt": "2026-06-11T12:30:09Z"
    }
  },
  "meta": {
    "api_version": "v1",
    "request_id": "f2b1c4a0-7d3e-4a8b-9c10-2e5f6a7b8c9d"
  },
  "requestId": "f2b1c4a0-7d3e-4a8b-9c10-2e5f6a7b8c9d"
}
```

<Info>
  Field names and the exact shape are defined by the OpenAPI spec at `GET /openapi.json`. Treat the spec as authoritative and read fields defensively.
</Info>

## The auditable chain

Provenance is not a single label. It is a chain of four linked facts, each answering a different audit question.

<Steps>
  <Step title="Named source" icon="building-columns">
    Who published this? Identifies the official issuer, for example a central bank or a national statistics office.
  </Step>

  <Step title="Source URL" icon="link">
    Where can a human verify it? Points at the originating release or dataset so a reviewer can cross-check by hand.
  </Step>

  <Step title="Raw payload reference" icon="file-shield">
    Exactly which upstream response produced this value? A reference to the captured payload, proving the value was not hand-edited, without re-serving the upstream body.
  </Step>

  <Step title="Ingestion run" icon="gears">
    When and by which run did Financial Data API record it? Ties the value to a specific, timestamped ingestion, which connects provenance to the [time model](/concepts/time-model).
  </Step>
</Steps>

<Tip>
  Pair provenance with the [time model](/concepts/time-model). The ingestion run timestamp is what `as_of` approximates today, so the provenance chain and a point-in-time query describe the same moment from two angles: one tells you *where* a value came from, the other *when* it became known.
</Tip>

## A typical audit flow

<Steps>
  <Step title="Find the observation" icon="magnifying-glass">
    Query any observation route and read the inline `provider`, `sourceUrl`, and `rawAvailable`. For many audits this is already enough.
  </Step>

  <Step title="Pull the full chain" icon="link">
    Call `GET /provenance/observations/{observationId}` to retrieve the named source, source URL, raw payload reference metadata, and ingestion run together.
  </Step>

  <Step title="Verify against the release" icon="circle-check">
    Open the `sourceUrl` and confirm the published figure matches. The raw payload reference and ingestion run document the path in between.
  </Step>
</Steps>

<Check>
  Every value Financial Data API returns is traceable to an official release. There are no orphan numbers.
</Check>

## Related

<Columns cols={2}>
  <Card title="Freshness and liveness" icon="signal" href="/concepts/freshness-and-liveness">
    How Financial Data API flags stale and silently-frozen feeds.
  </Card>
</Columns>