/api/v1/facts/by-conceptXBRL facts queried by concept — against the small LEGACY dev-era index (~55,000 facts, no automated feed, heaviest 2016-2019).
XBRL facts queried by concept — against the small LEGACY dev-era index (~55,000 facts, no automated feed, heaviest 2016-2019). Returns every value of the concept stored in that index. For the full-market equivalent use GET /api/v1/xbrl/timeseries (per-company series) or GET /api/v1/xbrl/facts (per-filing).
10 tokensSince v3.4.0
Why use this
Concept-level fact lookup over the legacy dev-era index — pass a concept name (e.g. `us-gaap:Revenues`) and receive every value that index holds, optionally filtered by ticker or date range. Raw values only: no standardization across filings or fiscal calendars. HONEST SCOPE: the index is ~55,000 facts captured before the As-Filed engine existed; it is NOT the full market and does not grow. An empty `facts` array is the expected answer for most recent-period queries. For real coverage use [GET /api/v1/xbrl/facts](/docs/company-data/company-financials-xbrl-as-filed/get-xbrl-facts) (every fact of any parsed filing), [GET /api/v1/xbrl/timeseries](/docs/company-data/company-financials-xbrl-as-filed/get-api-v1-xbrl-timeseries) (per-company concept series, full history), or `/financials/metrics` (standardized, ~7,000 companies).
Returns facts from the LEGACY dev-era index filtered by concept and optional ticker/date range. This index predates the As-Filed engine: ~55,000 facts captured ad hoc (heaviest 2016-2019), no automated feed, so most recent-period queries legitimately return an empty facts array — that is the corpus, not an error. The endpoint is retained for backward compatibility with early integrations. New work should use the As-Filed surface, which parses every US 10-K/10-Q on arrival: GET /api/v1/xbrl/facts for per-filing facts, GET /api/v1/xbrl/timeseries for full-history per-company concept series.
Parameters
| Name | In | Required | Default | Allowed | Description | Example |
|---|---|---|---|---|---|---|
| concept | query | required | — | — | XBRL concept name in `prefix:LocalName` format. Standard concepts use `us-gaap:` prefix (e.g. `us-gaap:Revenues`, `us-gaap:NetIncomeLoss`, `us-gaap:Assets`); company-specific extensions use the company's own prefix. Case-sensitive. Returns 400 for unknown concepts; use the SEC EDGAR taxonomy browser to verify concept names before query. | us-gaap:Revenues |
| ticker | query | optional | — | — | Restrict to one issuer ticker (case-insensitive, canonical hyphen normalization). Default: every issuer present in the legacy index. NOTE: for a complete per-ticker concept time-series use GET /api/v1/xbrl/timeseries — this legacy index holds only what was hand-captured during development. | AAPL |
| date_from | query | optional | — | — | Inclusive lower bound on `period_end` (ISO `YYYY-MM-DD`). Useful for limiting to recent fiscal periods on high-cardinality concepts. | 2024-01-01 |
| date_to | query | optional | — | — | Inclusive upper bound on `period_end` (ISO `YYYY-MM-DD`). Combine with `date_from` for closed ranges. | 2025-12-31 |
| limit | query | optional | 100 | — | Maximum fact rows returned, capped at 1000 server-side. For bulk concept exports use date-range chunking + `limit=1000`. | 100 |
Response schema
| Field | Type | Nullable | Description |
|---|---|---|---|
| concept | string | no | Concept name echoed back, case-preserved (e.g. `us-gaap:Revenues`). Useful for asserting your client passed the concept you intended. |
| facts | array | no | Array of matching fact rows, sorted by `(ticker ASC, period_end DESC)` so per-ticker time-series are grouped. One row per `(ticker, period, dimension)` tuple — same ticker can appear multiple times if reported across multiple periods or dimensional members. |
| facts[].ticker | string | yes | Resolved issuer ticker (canonical hyphen form). Null when the issuer has no public-equity ticker. Use as primary grouping key when rendering cross-company comparisons. |
| facts[].cik | string | no | Filer CIK in 10-char zero-padded form. Stable identifier even when ticker is null. |
| facts[].value | number | yes | Numeric fact value in the unit specified by `unit`. Null for textual or non-numeric facts (rare on the standard us-gaap concepts since they're almost all numeric). NOT scale-adjusted — reconcile against `unit` to interpret (e.g. value=391035 + unit=USD-thousands means $391.035M). |
| facts[].unit | string | yes | XBRL unit. Common values: `USD`, `shares`, `pure` (dimensionless), `USD-per-share`, `iso4217:JPY`/`iso4217:EUR` (foreign currencies). Null only when `value` is null. Always check unit before arithmetic — companies routinely mix `USD` and `USD-thousands` within the same filing. |
| facts[].period_start | string | yes | ISO `YYYY-MM-DD` start date for duration concepts (income-statement and cash-flow facts). Null for instant concepts (balance-sheet facts that are point-in-time at `period_end`). |
| facts[].period_end | string | no | ISO `YYYY-MM-DD` end date — for instant concepts the as-of date; for duration concepts the period end. Always present. Use for time-series x-axis and for range-filtering. |
| facts[].accession_number | string | no | SEC accession of the source filing in canonical `XXXXXXXXXX-YY-NNNNNN` format. Pass to `GET /api/v1/sec/filings/{accession_number}` to drill into the source filing's metadata. |
| facts[].form_type | string | no | Source filing form type AS STORED in the legacy index — the full SEC label (e.g. `Form 10-K - Annual report [Section 13 and 15(d), not S-K Item 405]`), not the short `10-K` code. Substring-match (`10-K` in value) when filtering client-side. |
| meta | object | no | Pagination + filter echo block: `{ total: integer, limit: integer, applied_filters: object }`. `total` is the cap-aware match count for the concept × filter set. |
Sample response
·
- "concept": "us-gaap:Revenues"
- "facts":
- "meta":
- "total": 1
- "limit": 100
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/facts/by-concept?api_Token=YOUR_API_KEY&concept=us-gaap%3ARevenues&ticker=AAPL&date_from=2024-01-01&date_to=2025-12-31&limit=100" \
-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).