Financial Data API — Documentation

Financial Data API computes a set of analytics on top of its official-source observations and SEC fundamentals, then stores the results and serves them as observations, in the same envelope, with the same provenance, as the official data underneath. You read precomputed values, not a live calculator, and each one traces back to the inputs it was built from. This page leads with the derived datasets you can get and the indicator slugs that identify them, then shows how to query them.

What data is available

Every derived dataset is a canonical indicator with its own indicatorId, queryable through the standard observation endpoints. Filter by the category to pull a whole family.

Family	`category`	Example indicator IDs	What it tells you
Surprise indices	`surprise`	`inflation_surprise_index`, `growth_surprise_index`	How much recent data beat or missed expectations (standardized, in sigma).
COT positioning percentiles	`positioning`	`cot_positioning_percentile`, `cot_tff_percentile`	A trader cohort’s net positioning as a 3-year historical percentile (0–100) — how stretched it is versus its own history. Full weekly panels: legacy COT since 1992 (972 CFTC contracts), TFF leveraged funds since 2006 (117 financial futures).
Valuation multiples	`valuation_multiples`	`trailing_pe_ratio`, `earnings_yield`, `dividend_yield`, `price_to_book_ratio`, `ev_to_ebitda_ratio`, `ev_to_sales_ratio`, `peg_ratio`	Equity valuation derived from SEC fundamentals and price inputs, per company. All 13 trailing multiples are daily series from 2007 to today for ~500 US companies, computed from raw as-traded prices and point-in-time TTM fundamentals.
Central-bank sentiment	`central_bank`	`cb_statement_sentiment`, `cb_statement_sentiment_llm`	Hawk/dove scores for policy statements. The deterministic lexicon feed covers 244 FOMC statements from 1994; the model-scored feed covers 831 statements across the Fed, ECB, Bank of England, Bank of Canada and RBA. See Central bank sentiment.
Rates analytics	`rates`	`real_yield_10y`, `real_policy_rate`, `policy_cycle_state`, `yield_curve_spread_10y_2y`, `yield_10y_change`	Real rates, curve measures, and policy-cycle state derived from policy rates and yields.
Risk-regime composite	`risk`	`risk_regime`	A composite signal summarizing the prevailing risk environment.

The catalog is live. Resolve the full set of derived slugs and their categories from GET /canonical-indicators (the same registry that lists macro indicators), and treat the examples above as a map rather than an exhaustive list.

The forecast baseline

Financial Data API also computes a statistical macro forecast baseline with prediction intervals — its own model output, never a vendor, sell-side, or street consensus. Where it is published, it populates the forecast field (and its interval bounds) on the relevant macro observation, gated by out-of-sample skill, so a series only carries a forecast where the baseline has earned it. The consensus and forecast numbers used to compute surprise indices are a separate, calendar-sourced input (see Economic calendar and events), not the baseline.

How derived analytics work

Financial Data API ingests official observations (CPI prints, yields, CFTC positioning) and SEC fundamentals, then a derivation step computes higher-level values and persists them as observations. Because the result is stored:

Reads are fast and stable. You retrieve a value; you do not trigger a computation on request.
Each value is auditable. It carries the same sourceUrl, provider, and provenance chain as any observation, and you can trace it to the official releases underneath via GET /provenance/observations/{observationId}.
The product is read-only. You cannot pass your own formula or change the methodology; you read what Financial Data API has computed.

Derived values are served through the same observation endpoints as official data — there is no separate calculator API. Query them by indicatorId or pull a whole family by category.

Querying derived analytics

Send your API key on every request (x-api-key header or Authorization: Bearer); derived routes require the data:read scope. All paths are relative to https://api.financialdatapi.com.

Latest value of a derived series

curl "https://api.financialdatapi.com/observations/latest?indicator_id=inflation_surprise_index&country=USA" \
  -H "x-api-key: $FINANCIALDATA_API_KEY"

import { FinancialDataApiClient } from "@financialdatapi/client";

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

const { data } = await client.getLatestObservations({
  indicator_id: "inflation_surprise_index",
  country: "USA",
});
console.log(data[0].actual, data[0].unit, data[0].periodEnd);

A derived time series

curl "https://api.financialdatapi.com/observations?indicator_id=cot_positioning_percentile&limit=20&order=desc" \
  -H "x-api-key: $FINANCIALDATA_API_KEY"

import { FinancialDataApiClient } from "@financialdatapi/client";

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

for await (const obs of client.paginate("/observations", {
  indicator_id: "trailing_pe_ratio",
  order: "desc",
})) {
  console.log(obs.periodEnd, obs.actual, obs.unit);
}

Response

{
  "data": [
    {
      "observationId": "obs_inflation_surprise_index_country_usa_2026-05-31",
      "indicatorId": "inflation_surprise_index",
      "indicatorName": "Inflation surprise index",
      "category": "surprise",
      "country": "USA",
      "actual": 0.628,
      "unit": "sigma",
      "periodEnd": "2026-05-31",
      "observedAt": "2026-06-12T06:00:00.000Z",
      "provider": "Financial Data API",
      "sourceUrl": "https://api.financialdatapi.com",
      "rawAvailable": true
    }
  ],
  "meta": {
    "request_id": "8f1c0e2a-6b3d-4f0a-9c11-1d2e3f4a5b6c",
    "requestId": "8f1c0e2a-6b3d-4f0a-9c11-1d2e3f4a5b6c",
    "api_version": "v1",
    "pagination": { "limit": 20, "cursor": null, "next_cursor": null, "has_more": false }
  },
  "requestId": "8f1c0e2a-6b3d-4f0a-9c11-1d2e3f4a5b6c"
}

Units vary by family: surprise indices are in sigma, COT percentiles in percentile, valuation multiples are a ratio (or percent for yields). Always branch on the unit field.

Worked example: gold positioning at the extremes

The COT percentile panel is deep enough to test against history. Gold in the week of its August 2011 all-time-high top:

cURL

curl "https://api.financialdatapi.com/observations?indicator_id=cot_positioning_percentile&entity=instrument_cftc_gold_commodity_exchange_inc&start_date=2011-08-01&end_date=2011-08-05" \
  -H "x-api-key: $FINANCIALDATA_API_KEY"

That week printed 93.3 (crowded_long). The same query over 2015-07-24 to 2015-07-31 returns 2.9 (crowded_short) for 2015-07-28 — the cycle bottom. Each row also carries net, weeklyChange, percentile1y, percentile3y, and zScore3y in metadata.

FOMC statement sentiment

cb_statement_sentiment scores every FOMC policy statement on a hawk/dove scale — 244 statements from February 1994 to today, keyed to country_usa with one event-frequency row per statement date. The score is deterministic, not model-generated: a versioned lexicon (fdapi_hawk_dove_v1) counts hawkish and dovish phrases in the statement text and nets them into a score in [−1, +1]. valueText labels the row hawkish (score above 0.2), dovish (below −0.2), or neutral. Metadata carries a full audit trail: lexiconVersion, the matched hawkish and dovish phrases, phrase counts, word count, and deltaVsPrior — the change versus the previous statement, which is usually the tradable number.

cURL

curl "https://api.financialdatapi.com/observations?indicator_id=cb_statement_sentiment&entity=country_usa&start_date=2022-06-01&end_date=2022-06-30" \
  -H "x-api-key: $FINANCIALDATA_API_KEY"

The series tracks the eras you would expect it to:

Statement	Score	Reading
December 2008 (ZIRP, “all available tools”)	−1.0	Maximally dovish
July 2019 (the “hawkish cut”)	+0.14	Eased policy, hawkish language
June 2022 (75bp, inflation fight)	+1.0	Maximally hawkish

Each row’s sourceUrl links to the Federal Reserve statement it was scored from, so every value is verifiable against the public-domain original.

Trace a derived value to its inputs

Because every derived value is an observation, it carries full provenance. You can walk from a derived value back to the official releases it was built on — this is what makes derived analytics auditable.

Read the derived observation

Pull the derived value from GET /observations (or /observations/latest) and capture its observationId.

Follow provenance to the source

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

Raw provider payload bodies are never exposed by the product API. Provenance returns reference metadata (source, URL, ingestion run, raw payload id), not the original payload contents.

Notes

Stored, not computed on request

Derived values are precomputed and persisted. The number you read was computed earlier; the request does not recompute it. You cannot pass your own formula or change the methodology through the API.

Forecast baseline is not consensus

The macro forecast baseline is Financial Data API’s own statistical baseline, published with prediction intervals and gated by out-of-sample skill. It is never a vendor, sell-side, or street consensus. Where consensus is available for surprise computation, it comes from the economic calendar and is a separate input.

Rights and exposure

Derived datasets follow the same rights model as the rest of the API, and trace to the same official provenance. Raw vendor and real-time market price-tick data is deliberately not part of the product and is never served on the public surface.

Positioning

The raw CFTC COT and TFF series behind the positioning percentile.

Economic calendar and events

Where the consensus and forecast inputs behind surprise indices come from.

Macro indicators

The official observations that feed derived values, and how to query them.

Financial statements

The SEC fundamentals behind valuation multiples.

Get started

Data products

Data infrastructure

Agent access

Resources

Legal

Derived analytics

What data is available

The forecast baseline

How derived analytics work

Querying derived analytics

Latest value of a derived series

A derived time series

Worked example: gold positioning at the extremes

FOMC statement sentiment

Trace a derived value to its inputs

Notes

Positioning

Economic calendar and events

Macro indicators

Financial statements

​What data is available

​The forecast baseline

​How derived analytics work

​Querying derived analytics

​Latest value of a derived series

​A derived time series

​Worked example: gold positioning at the extremes

​FOMC statement sentiment

​Trace a derived value to its inputs

​Notes

​Related

Positioning

Economic calendar and events

Macro indicators

Financial statements

What data is available

The forecast baseline

How derived analytics work

Querying derived analytics

Latest value of a derived series

A derived time series

Worked example: gold positioning at the extremes

FOMC statement sentiment

Trace a derived value to its inputs

Notes

Related