Skip to main content
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.
FamilycategoryExample indicator IDsWhat it tells you
Surprise indicessurpriseinflation_surprise_index, growth_surprise_indexHow much recent data beat or missed expectations (standardized, in sigma).
COT positioning percentilepositioningcot_positioning_percentileA trader cohort’s net positioning as a historical percentile (0–100) — how stretched it is versus its own history.
Valuation multiplesvaluation_multiplestrailing_pe_ratio, earnings_yield, dividend_yield, price_to_book_ratio, ev_to_ebitda_ratio, ev_to_sales_ratio, peg_ratioEquity valuation derived from SEC fundamentals and price inputs, per company.
Rates analyticsratesreal_yield_10y, real_policy_rate, policy_cycle_state, yield_curve_spread_10y_2y, yield_10y_changeReal rates, curve measures, and policy-cycle state derived from policy rates and yields.
Risk-regime compositeriskrisk_regimeA 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"

​
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"
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.

​
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.
1

Read the derived observation

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

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

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.
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.
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.