/api/v1/xbrl/segmentsDimensional breakdown time-series — one metric or concept split by a chosen axis (segment / geography / product / class).
Dimensional breakdown time-series — one metric or concept split by a chosen axis (segment / geography / product / class).
10 tokensSince v3.88.0
Why use this
Return a per-member series for a `concept` (or canonical `metric`) along an `axis` — business segments by default, or geographic / product-or-service / share-class / any axis qname — with members exactly as filed (including filer extension members).
Common use case
Charting revenue by business segment or by geography over time; comparing product-line contribution; any as-filed dimensional breakdown the flat standardized surface cannot express.
A dimensional breakdown time-series: one concept (or canonical metric) split by a chosen axis — business segments (us-gaap:StatementBusinessSegmentsAxis, default), geography (srt:StatementGeographicalAxis), product/service (srt:ProductOrServiceAxis), share class (us-gaap:StatementClassOfStockAxis), or any axis qname. Members are returned exactly as filed, including filer extension members (e.g. aapl:GreaterChinaSegmentMember); v1 does NOT canonicalize members across companies. This exposes the dimensional structure a flat standardized metrics bag cannot represent. Selector is ticker | cik; period is A | Q (no TTM); by default the member series spans ALL available periods (omit years, or pass years=all), and an explicit years=N narrows to the last N fiscal years (<= 25). Coverage is wide — every US filer is served presence-based — while historical depth loads incrementally; a ticker that matches no US filer returns 404 UNKNOWN_TICKER.
Parameters
| Name | In | Required | Default | Allowed | Description | Example |
|---|---|---|---|---|---|---|
| ticker | query | optional | — | — | Selector — provide exactly ONE of `ticker` | `cik`. Canonical hyphen form, case-insensitive. A ticker that matches no US filer -> 404 `UNKNOWN_TICKER`. | MSFT |
| cik | query | optional | — | — | Selector: issuer CIK, zero-padded or bare (both match — compared with leading zeros stripped). Must be numeric (else 400 INVALID_PARAM). | 789019 |
| axis | query | optional | us-gaap:StatementBusinessSegmentsAxis | — | The dimension to break down along, as an axis qname. Default `us-gaap:StatementBusinessSegmentsAxis`; also accepts `srt:StatementGeographicalAxis`, `srt:ProductOrServiceAxis`, `us-gaap:StatementClassOfStockAxis`, or any axis qname the filer used. | srt:StatementGeographicalAxis |
| concept | query | optional | — | — | The concept to break down, as a qname (`us-gaap:Revenues`) or local name. Provide exactly ONE of `concept` | `metric`. | us-gaap:Revenues |
| metric | query | optional | — | — | Alternatively, a canonical metric key (e.g. `revenue`) — resolved to its underlying concept(s) via the concept map. Provide exactly ONE of `concept` | `metric`. | revenue |
| period | query | optional | A | — | `A` (annual, default) or `Q` (quarterly). `TTM` is not offered for segment breakdowns (dimensional facts are not rolled into a trailing-twelve-month figure). | Q |
| years | query | optional | all available periods | — | Years of history. DEFAULT = all available periods (omit, or pass `years=all`, for the member series' full history — no fiscal-year floor; `meta.years` echoes `"all"`); pass an integer to narrow to the last N fiscal years, clamped to [1, 25]. With `period=Q` an integer `years` returns up to `years x 4` points per member. | 25 |
| as_of | query | optional | — | — | Point-in-time: return the dimensional facts as-known at this date — only filings filed on or before `as_of` are eligible, and the winning filing per period is elected among them. `YYYY-MM-DD`; malformed -> 400 INVALID_PARAM. Omit for the current (latest) filings. | 2024-06-30 |
| basis | query | optional | latest | — | `latest` (default) elects the most recently filed version of each period (restated view); `original` elects the earliest-filed version (as-known-then). Composes with `as_of` (both bound the eligible filings, `basis` breaks the tie). Any other value -> 400 INVALID_PARAM. | original |
Response schema
| Field | Type | Nullable | Description |
|---|---|---|---|
| data.company_name | string | yes | The company's display name, embedded beside `data.ticker`/`data.cik` so a client can label the breakdown without a second lookup (mirrors the SEC companyfacts `entityName`). Resolved from the always-updated company catalog by the resolved CIK; present with `null` when the catalog has no name for the company (never a fabricated value). Additive — every existing field is unchanged. |
| data.series[] | array | no | One entry per as-filed member on the chosen `axis`. Each: `member` (the member qname, INCLUDING filer extensions like `msft:IntelligentCloudMember`) and `points[]`. Members are returned AS FILED — there is no cross-company member canonicalization in v1 (two issuers' `...GreaterChinaSegmentMember` are not reconciled). |
| data.series[].points[] | array | no | The member's time-series for the chosen concept / metric — one point per reporting period: `{fiscal_year, fiscal_period, period_end, start_date, end_date, value, decimals, unit, concept, is_extension, accession_no}`. `fiscal_year`/`fiscal_period` are the company's own fiscal-year naming, reconciled per company across its filings (a quarter carries the year of the fiscal year it sits in); `start_date`/`end_date` are the dates to key on. |
| data.series[].points[].is_extension | boolean | no | True when the point's underlying source concept is a filer-defined extension (from `xbrl.concepts.is_extension`); false for a standard us-gaap / ifrs / dei concept. |
Sample response
·
- "status": "success"
- "data":
- "ticker": "MSFT"
- "cik": "0000789019"
- "company_name": "MICROSOFT CORP"
- "covered": true
- "phase": "wide"
- "axis": "us-gaap:StatementBusinessSegmentsAxis"
- "concept_or_metric": "us-gaap:Revenues"
- "period": "A"
- "series":
- "meta":
- "member_count": 2
- "concepts_resolved":
- "years": "all"
- "note": "As-filed members; no cross-company member canonicalization. Current-period facts only (context end_date = period_of_report)."
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/xbrl/segments?api_Token=YOUR_API_KEY&ticker=MSFT&cik=789019&axis=srt%3AStatementGeographicalAxis&concept=us-gaap%3ARevenues&metric=revenue&period=Q&years=25&as_of=2024-06-30&basis=original" \
-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).