/api/v1/xbrl/dictionaryThe 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
Common use case
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
| Name | In | Required | Default | Allowed | Description | Example |
|---|---|---|---|---|---|---|
| kind | query | optional | — | primitive, derived, ratio, template_slot | Restrict 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 |
| statement | query | optional | — | income_statement, balance_sheet, cash_flow_statement, comprehensive_income, analytic, derived, other | Restrict to one statement group. `analytic` covers the ratios and money intermediates; `derived` the legacy-derived metrics. Any other value -> 400 INVALID_PARAM. | income_statement |
| metric | query | optional | — | — | Case-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
| Field | Type | Nullable | Description |
|---|---|---|---|
| data | array | no | A 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[].aggregation | string | no | How 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[].formula | string | yes | For 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.count | number | no | Number 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
| Status | Label | Description |
|---|---|---|
| 200 | OK | Request succeeded. |
| 400 | Bad Request | Invalid query, body, or path parameter. |
| 401 | Unauthorized | Missing or invalid Authorization header / api_Token. |
| 402 | Payment Required | Insufficient token balance for this call. Top up |
| 429 | Too Many Requests | Rate limit exceeded for your tier (see /pricing for tier limits). Tier limits |
| 500 | Server Error | Unexpected 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).