Financial Data API — Documentation

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:

string

The named publisher the value came from (for example, a central bank or statistics office).

string

A URL pointing at the originating release or dataset.

string

The required attribution string for the value.

string

The freshness label: fresh, stale, or unknown.

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.

object

Rights and exposure metadata governing how the value may be used.

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.

The provenance endpoint

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

GET /provenance/observations/{observationId}

string

required

The identifier of the observation you want to trace. You get this from any observation response.

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.

curl -G "https://api.financialdatapi.com/provenance/observations/obs_01HZX9K2P7QF3M4N5R6S7T8U9V" \
  -H "x-api-key: $FINANCIALDATA_API_KEY"

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"])

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);

Example response

{
  "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"
}

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.

The auditable chain

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

Named source

Who published this? Identifies the official issuer, for example a central bank or a national statistics office.

Source URL

Where can a human verify it? Points at the originating release or dataset so a reviewer can cross-check by hand.

Raw payload reference

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.

Ingestion run

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.

Pair provenance with the 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.

A typical audit flow

Find the observation

Query any observation route and read the inline provider, sourceUrl, and rawAvailable. For many audits this is already enough.

Pull the full chain

Call GET /provenance/observations/{observationId} to retrieve the named source, source URL, raw payload reference metadata, and ingestion run together.

Verify against the release

Open the sourceUrl and confirm the published figure matches. The raw payload reference and ingestion run document the path in between.

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

Freshness and liveness

How Financial Data API flags stale and silently-frozen feeds.

Get started

Data products

Data infrastructure

Agent access

Resources

Legal

Provenance

What every observation already carries

The provenance endpoint

Example response

The auditable chain

A typical audit flow

Freshness and liveness

​What every observation already carries

​The provenance endpoint

​Example response

​The auditable chain

​A typical audit flow

​Related

Freshness and liveness

What every observation already carries

The provenance endpoint

Example response

The auditable chain

A typical audit flow

Related