Skip to content
/api/v1/xbrl/dictionary

The complete field dictionary — every standardized metric, ratio and statement line the financials engine serves, each with a plain-English definition, its statement, units, how it aggregates over periods, its formula (for ratios), the query parameters it honours, and a coverage note.

The complete field dictionary — every standardized metric, ratio and statement line the financials engine serves, each with a plain-English definition, its statement, units, how it aggregates over periods, its formula (for ratios), the query parameters it honours, and a coverage note. On every endpoint the dictionary describes, `fiscal_year` is the fiscal year as the company names it in its own filings, reconciled per company across its filings (each quarter carries the year of the fiscal year it sits in); period-end dates are the join key and `calendar=true` serves the calendar-aligned label.

Why use this

One cheap (1 token) call returns the whole served field catalog so you never guess a metric key or its meaning: for each field a `key` (the identifier you pass to `metrics=`/`ratios=` on the time-series endpoint), a `label`, a `kind` (primitive line item / derived metric / ratio / statement-template slot), the `statement` it belongs to, `units`, `aggregation` (how a trailing-twelve-month figure is formed — a flow amount is summed across quarters, a balance-sheet level takes the latest value), a vendor-free `definition`, a `formula` in terms of other field keys (for ratios and derived metrics), the legal `parameters`, and a `coverage` note. Filter with `kind=`, `statement=`, or `metric=`.

Common use case

Building a metric picker or column chooser in your own app; discovering exactly which ratios and line items exist and what each one means; looking up a ratio's formula and which primitives feed it; confirming whether a field is a point-in-time balance or a period flow before charting it.

The single reference for every field the financials engine serves — the equivalent of a data terminal's field-lookup screen. It is GENERATED from the engine's own metric and ratio registries, so it is always in step with what the API actually computes: as standardization expands (more line items, more ratios), the new fields appear here automatically, and a build-time parity check guarantees the catalog can never drift from the engine or ship a blank definition. Each entry tells you the field's identifier (key), a human label, its class (kind), which statement it belongs to, its units, how it aggregates over periods (aggregation — so you know whether a trailing-twelve figure is a sum of quarters or a point-in-time balance), a plain-English definition, the formula for ratios and derived metrics (expressed in other field keys, so you can trace a ratio back to the primitives that feed it), the query parameters the field honours on the time-series and statements endpoints, and a coverage note. Filter with kind=, statement=, or metric= (a substring match on key or label). No selector and no company data — it is static reference data, served at the cheapest tier and safe to cache. Errors: 400 INVALID_PARAM for an unknown kind/statement.

Parameters

NameInRequiredDefaultAllowedDescriptionExample
kindqueryoptionalprimitive, derived, ratio, template_slotRestrict to one field class: `primitive` (a standardized line item sourced from the filing), `derived` (a convenience metric the engine derives), `ratio` (a computed ratio or analytic), or `template_slot` (a professional statement line the template presents). Any other value -> 400 INVALID_PARAM.ratio
statementqueryoptionalincome_statement, balance_sheet, cash_flow_statement, comprehensive_income, analytic, derived, otherRestrict to one statement group. `analytic` covers the ratios and money intermediates; `derived` the legacy-derived metrics. Any other value -> 400 INVALID_PARAM.income_statement
metricqueryoptionalCase-insensitive substring match on a field's `key` OR `label` (e.g. `margin`, `debt`, `revenue`). Non-matching text simply returns an empty list, never an error.margin

Response schema

FieldTypeNullableDescription
dataarraynoA flat list of field entries (one per served field key). Each entry: `key`, `label`, `kind` (`primitive`|`derived`|`ratio`|`template_slot`), `statement`, `units`, `aggregation` (`flow_sum`|`stock_latest`|`ratio_recomputed`|`per_share_non_additive`|`not_applicable`), `definition` (always non-empty), `formula` (a string for ratios/derived metrics, `null` for a sourced primitive or a template slot), `parameters` (the query params this field honours), and `coverage`. Ratio entries also carry `category`.
data[].aggregationstringnoHow the field aggregates over periods: `flow_sum` (an income/cash-flow amount that accumulates — a trailing-twelve figure sums four quarters), `stock_latest` (a balance-sheet level — a trailing-twelve figure is the latest value), `per_share_non_additive` (a per-share amount that cannot be validly summed across periods, so a calculated quarter/trailing cell is withheld rather than fabricated), `ratio_recomputed` (recomputed each period, not aggregated), or `not_applicable`.
data[].formulastringyesFor a ratio or derived metric, the calculation in terms of other dictionary keys (e.g. `gross_profit / revenue`, `total_debt - cash`); `avg(x)` denotes a period average of a balance metric. `null` for a primitive (sourced, not computed) or a template slot.
meta.countnumbernoNumber of entries after any filter; `meta.total` is the full catalog size. `meta.kinds` and `meta.statements` list the legal filter vocabularies; `meta.generated_from` is `engine_registry` (the dictionary is generated from the engine's own registries, so it stays current as standardization expands).

Sample response

·
  • "status": "success"
  • "request_id": "example-dictionary-request"
  • "timestamp": "2026-09-14T16:00:00Z"
  • "data":
    ]
  • "meta":
    • "count": 2
    • "total": 157
    • "kinds":
    • "statements":
    • "generated_from": "engine_registry"
    }
}

Errors

StatusLabelDescription
200OKRequest succeeded.
400Bad RequestInvalid query, body, or path parameter.
401UnauthorizedMissing or invalid Authorization header / api_Token.
402Payment RequiredInsufficient token balance for this call. Top up
429Too Many RequestsRate limit exceeded for your tier (see /pricing for tier limits). Tier limits
500Server ErrorUnexpected server-side failure. Retry with backoff; report if persistent.

Code samples

curl "https://api.finradar.ai/api/v1/xbrl/dictionary?api_Token=YOUR_API_KEY&kind=ratio&statement=income_statement&metric=margin" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Generate an API key in /account/credentials to run live queries (literal YOUR_API_KEY placeholder shown until then).