# Facts (XBRL Concept Index) — Finradar API
> Version: 3.61.0 | Generated: 2026-06-20 | Content Hash: 0822f9aa
> Fetch this file at: https://uat.finradarapi.com/llms/facts-xbrl-concept-index.txt

## Authentication
All endpoints require an API key. Pass it via query parameter `?apiKey=YOUR_KEY` or header `X-API-Key: YOUR_KEY`. WebSocket endpoints accept the key in the `token` auth payload or query parameter.

---

## Facts (XBRL Concept Index)

Concept-indexed XBRL facts. Where Company Financials (XBRL) returns standardized metrics + ratios, this section returns the raw concept-level facts (e.g. us-gaap:Revenues, us-gaap:NetIncomeLoss) so customers can build custom calculations against the underlying SEC filing data.

### GET /api/v1/facts/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.

**Token cost:** 10 tokens per call

**Response fields:**
- `concept` (string): Concept name echoed back, case-preserved (e.g. `us-gaap:Revenues`). Useful for asserting your client passed the concept you intended.
- `facts` (array): 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 (nullable)): 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): Filer CIK in 10-char zero-padded form. Stable identifier even when ticker is null.
- `facts[].value` (number (nullable)): 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 (nullable)): 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 (nullable)): 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): 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): 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): 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): Pagination + filter echo block: `{ total: integer, limit: integer, applied_filters: object }`. `total` is the cap-aware match count for the concept × filter set.

**Since:** v3.4.0

**Utility:** 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.

**Parameters:**
- `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.
- `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').
- `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.
- `date_to` (query, optional): Inclusive upper bound on `period_end` (ISO `YYYY-MM-DD`). Combine with `date_from` for closed ranges.
- `limit` (query, optional, default: 100): Maximum fact rows returned, capped at 1000 server-side. For bulk concept exports use date-range chunking + `limit=1000`.

**Sample response:**
```json
{
  "concept": "us-gaap:Revenues",
  "facts": [
    {
      "ticker": "AAPL",
      "cik": "0000320193",
      "value": 391035000000,
      "unit": "USD",
      "period_start": "2024-09-29",
      "period_end": "2025-09-28",
      "accession_number": "0000320193-25-000123",
      "form_type": "10-K"
    }
  ],
  "meta": {
    "total": 1,
    "limit": 100
  }
}
```

### POST /api/v1/facts/aggregate

Aggregate XBRL facts across companies. Reduces a concept across a filter set (sector, ticker list, period) and returns sum / avg / median / count statistics.

**Token cost:** 10 tokens per call

**Response fields:**
- `concept` (string): Concept name echoed back. Useful for asserting your client passed the concept correctly.
- `period` (string): Period filter echoed back as ISO date / quarter-string / year-string (whichever form was passed). Useful for chart annotations.
- `aggregates` (object): Computed aggregate statistics across all facts matching the filter set. All fields use the most-common unit across contributing facts (e.g. `USD` is preferred over `USD-thousands`); units are NOT auto-converted — when the contributing facts have mixed units, the aggregation falls back to filtering by majority-unit and excluding the minority. Use `count` to detect when this happened.
- `aggregates.sum` (number (nullable)): Sum across all matching fact values (in the dominant unit). Useful for total-revenue-style aggregates. Null when no facts match the filter set OR when all values are null.
- `aggregates.avg` (number (nullable)): Arithmetic mean across matching facts. Useful for sector-average analysis. Null when count=0. Note: not weighted — for revenue-weighted averages, run two queries (numerator-aggregated + denominator-aggregated) and divide.
- `aggregates.median` (number (nullable)): Median (50th percentile) across matching facts. Useful for distribution-center analysis on heavy-tailed concepts where mean is skewed by outliers (e.g. revenue distributions are typically log-normal — median is the better center metric than mean). Null when count=0.
- `aggregates.count` (integer): Number of facts contributing to the aggregation. Always non-negative. Use to detect filter-too-narrow cases (count=0 means no matches; count<10 means small sample warrants caution).
- `aggregates.min` (number (nullable)): Minimum value across matching facts. Useful for identifying outlier candidates (lowest reported revenue in sector, smallest cap-ex spend). Null when count=0.
- `aggregates.max` (number (nullable)): Maximum value across matching facts. Useful for identifying top-of-distribution outliers. Null when count=0.
- `meta` (object): Filter echo block: `{ sector: string, tickers: array, period: string, dominant_unit: string, excluded_count: integer }`. `excluded_count` flags facts that were skipped due to unit mismatch — when non-zero, suggests you should filter your input cohort to a single-unit subset for cleaner aggregation.

**Since:** v3.4.0

**Utility:** Cross-company aggregation of one XBRL concept across a filter set — pass `concept` + `period` + optional sector / ticker-list filters and receive `sum`, `avg`, `median`, `count`, `min`, `max` in one shot. The right endpoint for sector-wide research workflows like 'median capex / revenue across S&P 500 Industrials in 2025', 'total reported revenue across all reporting companies in Q4 2025', or 'distribution of book-value-per-share across Healthcare names'. Pair with `/facts/by-concept` when you need the underlying row-level data; pair with `/financials/screen` when you want filter-then-rank workflows on standardized ratios. The 10-token cost reflects the heavy multi-row reduction.

**Parameters:**
- `concept` (body, required): XBRL concept name in `prefix:LocalName` format (e.g. `us-gaap:Revenues`, `us-gaap:NetIncomeLoss`). Same concept syntax as `/facts/by-concept`. Returns 400 for unknown concepts.
- `period` (body, required): Period filter — accepts (a) exact ISO `YYYY-MM-DD` for a specific period-end date, or (b) `YYYY-Q1`/`YYYY-Q2`/`YYYY-Q3`/`YYYY-Q4` for fiscal-quarter rollup, or (c) `YYYY` for full-year (annual filings only). Calendar-year scope; for fiscal-year offsets (companies with non-calendar fiscal years) use `/facts/by-concept` and aggregate client-side.
- `sector` (body, optional): Sharadar sector filter (e.g. `Technology`, `Healthcare`, `Industrials`). Default: aggregate across all sectors. Excludes companies unmapped in Sharadar (~5% of universe).
- `tickers` (body, optional): Array of ticker strings to restrict the aggregation to (max 500 entries). Useful for index-defined cohort aggregations (e.g. 'aggregate over the S&P 500'). Mutually exclusive with `sector` — pass one or the other, not both.

**Sample response:**
```json
{
  "concept": "us-gaap:Revenues",
  "period": "2025-12-31",
  "aggregates": {
    "sum": 12400000000000,
    "avg": 24800000000,
    "median": 1820000000,
    "count": 500,
    "min": 50000000,
    "max": 391035000000
  },
  "meta": {
    "sector": "all",
    "period": "2025-12-31"
  }
}
```