Skip to content
/api/v1/xbrl/facts

Query as-filed XBRL facts — dimension-, concept-, and amendment-aware.

Query as-filed XBRL facts — dimension-, concept-, and amendment-aware.

10 tokensSince v3.86.0

Why use this

Return individual as-filed facts (numeric, text, and nil) with concept, unit, decimals, period, and dimensions, filtered by filing or issuer, concept tag, and dimension, newest-filing-first.

Common use case

Pulling a concept's fact series across a filing or issuer; extracting one segment/geography/share-class breakdown via `dim.<axis>`; isolating the consolidated value with `consolidated_only`.

As-filed fact query over the parsed XBRL — every fact including dimensioned duplicates, nil, and text (no flattening). Provide at least one selector (accession | cik); narrow with tag (local or prefix:local), repeatable dim.<axis>=<member> filters, or consolidated_only=true to drop all breakouts. amendments=current|all controls whether superseded rows are included. Ordered newest-filing-first, paginated (limit <= 500, offset); meta.pagination.total is null by design (has_more comes from a limit+1 probe). This is the pre-parsed, dimensioned companion to the legacy on-demand GET /api/v1/facts (same 10-token tier; the legacy route is untouched). Unlike the statements endpoints, /facts is NOT coverage-gated — a selector with nothing parsed yet returns an empty array, not 404 NOT_COVERED.

Parameters

NameInRequiredDefaultAllowedDescriptionExample
accessionqueryoptional——Selector — provide at least ONE of `accession` | `cik`. Restrict to a single filing's facts (dashed or 18-digit form). Malformed -> 400 INVALID_PARAM.0000950170-25-100235
cikqueryoptional——Selector: issuer CIK, zero-padded or bare (both match — compared with leading zeros stripped). Must be numeric (else 400 INVALID_PARAM). With `cik`, `amendments=current` (default) returns only current filings.789019
as_ofqueryoptional——Point-in-time: return only facts whose filing was FILED on or before this date (`filed_at <= as_of`) — the facts as-known at that date. `YYYY-MM-DD`; malformed -> 400 INVALID_PARAM. This is the filed-date cut; the restated-vs-original axis is the existing `amendments=current|all` (the facts-layer basis). Omit for no date cut.2024-06-30
tagqueryoptional——Concept filter — a local name (`Revenues`) or a prefixed qname (`us-gaap:Revenues`). The prefixed form matches taxonomy + local name exactly; the bare form matches local name across taxonomies.Revenues
dimsqueryoptional——Dimension filter(s) as `axis=member` pairs, comma-separated for multiple. Pairs are AND-combined (a jsonb containment match), returning only facts carrying every axis=member pair. Equivalent REST shorthand: repeatable `dim.<axisQName>=<memberQName>` query keys (that raw-key family cannot be a named tool parameter — qname keys carry `:` — so agents use `dims`; on the same axis the `dim.*` key wins). Ignored when `consolidated_only=true`.us-gaap:StatementBusinessSegmentsAxis=msft:IntelligentCloudMember
consolidated_onlyqueryoptionalfalse—`true`/`1`/`yes` returns only dimensionless (consolidated / all-defaults) contexts — the entity-wide value, excluding every dimensioned breakout. Takes precedence over `dim.<axis>` filters.true
amendmentsqueryoptionalcurrent—`current` (default) returns facts from current filings only (`is_current`; meaningful with the `cik` selector); `all` includes superseded originals/amendments. Any other value -> 400 INVALID_PARAM.all
limitqueryoptional100—Page size, clamped to [1, 500] (junk -> 100). Paginated via `offset`; the response reports `has_more` (a limit+1 probe) rather than an exact total.100
offsetqueryoptional0—Zero-based row offset for pagination (negative/junk -> 0).0

Response schema

FieldTypeNullableDescription
data[]arraynoArray of as-filed fact rows matching the filters, ordered newest-filing-first. Empty `[]` when the selector resolves but nothing matches (facts is NOT coverage-gated — a selector with nothing parsed yet simply yields no rows rather than 404 NOT_COVERED).
data[].conceptstringnoThe concept as `prefix:local` (e.g. `us-gaap:Revenues`), or the bare local name for a filer extension with no prefix. `is_extension` flags filer-defined concepts.
data[].valuenumberyesFact value as a JSON number (numeric facts). Null for nil-tagged facts; a STRING for text facts (e.g. `Large accelerated filer`). `decimals` is the SEC decimals attribute; `unit` is the resolved unit key (`USD`, `shares`, `USD/shares`, ...).
data[].dimensionsarraynoALWAYS an array; `[]` = consolidated/dimensionless. Each `{axis, member}` (qnames) — what `dim.<axis>=` filters on.
meta.paginationobjectno`{total, limit, offset, has_more}`. `total` is null by design (the query skips an exact COUNT and derives `has_more` from a limit+1 probe — cheaper for wide fact scans).

Sample response

·
  • "status": "success"
  • "data":
    ]
  • "meta":
    • "pagination":
    }
}

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/facts?api_Token=YOUR_API_KEY&accession=0000950170-25-100235&cik=789019&as_of=2024-06-30&tag=Revenues&dims=us-gaap%3AStatementBusinessSegmentsAxis%3Dmsft%3AIntelligentCloudMember&consolidated_only=true&amendments=all&limit=100&offset=0" \
  -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).