/api/v1/facts/aggregateAggregate XBRL facts across companies — over the same LEGACY dev-era index as /facts/by-concept (~55,000 facts, heaviest 2016-2019, no automated feed).
Aggregate XBRL facts across companies — over the same LEGACY dev-era index as /facts/by-concept (~55,000 facts, heaviest 2016-2019, no automated feed). Reduces a concept across a filter set (sector, ticker list, period) and returns sum / avg / median / count / min / max. `count: 0` is the normal, honest answer for cohorts outside the index's footprint.
10 tokensSince v3.4.0
Why use this
One-shot statistics over the legacy index — pass `concept` + `period` (exact date, `YYYY-Qn` calendar quarter, or bare `YYYY` for annual filings) + optionally `sector` OR `tickers`, and receive `sum`/`avg`/`median`/`count`/`min`/`max` computed over the dominant-unit majority (mixed-currency facts are excluded and reported in `meta.excluded_count`, never converted). HONEST SCOPE: the underlying index is ~55,000 dev-era facts — sector-wide or recent-period aggregations mostly return `count: 0` because the data was never captured, not because nothing was filed. For cross-company research on the FULL market use [GET /api/v1/xbrl/screen](/docs/company-data/company-financials-xbrl-as-filed/get-api-v1-xbrl-screen) (standardized screen over every parsed filer) or [GET /api/v1/xbrl/timeseries](/docs/company-data/company-financials-xbrl-as-filed/get-api-v1-xbrl-timeseries) per company; pair with `/financials/screen` for ratio-based filter-then-rank.
Cross-company aggregation of XBRL facts — pass a concept + filter set (sector, ticker list, period) and receive sum / avg / median / count statistics. Useful for sector-wide research like "median capex / revenue across S&P 500 Industrials in 2025".
Parameters
| Name | In | Required | Default | Allowed | Description | Example |
|---|---|---|---|---|---|---|
| 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. | us-gaap:Revenues |
| 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. | 2025-12-31 |
| sector | body | optional | — | — | Sector filter (e.g. `Technology`, `Healthcare`, `Industrials`). Default: aggregate across all sectors. Excludes companies unmapped (~5% of universe). | Technology |
| tickers | body | optional | — | — | Optional JSON array of 1-500 nonblank ticker strings, or null, to restrict the aggregation. An empty array, a blank entry or more than 500 entries returns 400. A non-null tickers array is mutually exclusive with a non-null sector. Send an array, not JSON encoded inside a string. | ["AAPL","MSFT","GOOGL"] |
Response schema
| Field | Type | Nullable | Description |
|---|---|---|---|
| concept | string | no | — |
| period | string | no | — |
| aggregates | object | no | — |
| aggregates.sum | number | yes | — |
| aggregates.avg | number | yes | — |
| aggregates.median | number | yes | — |
| aggregates.min | number | yes | — |
| aggregates.max | number | yes | — |
| aggregates.count | integer | no | — |
| meta | object | no | — |
| meta.sector | string | no | — |
| meta.tickers | array | no | — |
| meta.tickers[] | string | no | — |
| meta.period | string | no | — |
| meta.dominant_unit | string | yes | — |
| meta.excluded_count | integer | no | — |
Sample response
·
- "concept": "us-gaap:Revenues"
- "period": "2018"
- "aggregates":
- "sum": 1239490000000
- "avg": 61974500000
- "median": 51942000000
- "count": 20
- "min": -214000000
- "max": 265595000000
- "meta":
- "sector": "all"
- "tickers": []
- "period": "2018"
- "dominant_unit": "iso4217:USD"
- "excluded_count": 0
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 -X POST "https://api.finradar.ai/api/v1/facts/aggregate" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"concept": "us-gaap:Revenues",
"period": "2025-12-31",
"sector": "Technology",
"tickers": "[\"AAPL\",\"MSFT\",\"GOOGL\"]"
}'Generate an API key in /account/credentials to run live queries (literal YOUR_API_KEY placeholder shown until then).