/api/v1/facts/by-conceptXBRL facts queried by concept.
XBRL facts queried by concept. Returns every reported value of a given XBRL concept (e.g. us-gaap:Revenues) across companies, periods, and filings.
10 tokensSince v3.4.0
Why use this
Cross-company concept-level XBRL fact lookup — pass a concept name (e.g. `us-gaap:Revenues`, `us-gaap:NetIncomeLoss`, `us-gaap:Assets`) and receive every reported value across the ~7,000-company XBRL universe, optionally filtered by date range, ticker list, or sector. The 'raw' lookup — does NOT standardize across filings, fiscal calendars, or restated numbers. Use this when you need the AS-FILED fact for audit trails, custom analytical workflows, or LLM-grounded research that needs the exact reported value (not FinRadar's standardized reconciliation). For standardized cross-company comparisons (e.g. 'compare TTM revenue across S&P 500') use `/financials/metrics` instead, which standardizes the messy as-filed facts into a clean canonical schema.
Returns parsed XBRL facts filtered by concept (e.g. us-gaap:Revenues) and optional date range, ticker list, or sector. The "raw" lookup — does NOT standardize across filings or fiscal calendars. Use this when you need the as-filed fact (e.g. for audit trails). For standardized cross-company comparisons use GET /api/v1/financials/metrics.
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: returns facts across all ~7,000 companies. Useful for per-ticker concept time-series ('show me every reported `us-gaap:Revenues` for AAPL across all quarters'). | 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 — typically `10-K`, `10-Q`, `8-K`, `20-F`, `40-F`. Useful for filtering to annual-only (`10-K`) for clean YoY analysis or quarterly-only (`10-Q`) for QoQ tracking. |
| 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" \
-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).