/api/v1/xbrl/segments

Dimensional breakdown time-series — one metric or concept split by a chosen axis (segment / geography / product / class).

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). Each point is the member's own figure for one reporting period; `breakdowns=true` adds the filer's splits of that figure (for example a segment's revenue by product line), each labelled with its dimensions.

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. Geography and product splits are often tagged only together with another dimension (for example a business segment); they then appear under `breakdowns=true`, not as a member's own figure.

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. Each member's points are its own figure, at most one per reporting period, by the XBRL dimensional model (a fact tagged with the member alone is the member's total; a fact tagged with the member and another dimension is a split of it) and the FASB and IFRS 8 segment models (Consolidation Items = Operating Segments marks the reportable-segment amount, preferred on a segments axis). A period whose candidate figures disagree is withheld rather than guessed. Pass breakdowns=true to also receive every other fact of each member — a segment's revenue by product line or region, its reconciling items, the concepts and shapes not served — each labelled with its other dimensions and concept. 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 `ifrs-full:SegmentsAxis` (IFRS filers), `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`, that concept only) or a local name (`Revenues`, every concept spelled so; a period where they report different numbers is withheld). 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
breakdowns	query	optional	false	—	`true` adds, under each member, every other fact the request read for it: the member split by another dimension (product line, region, customer type), a reconciling item, the member's figure in the shape `points` does not serve, the concepts `points` does not serve, and each candidate of a withheld period, as `data.series[].breakdowns[]`, one entry per combination of `other_dimensions` and concept, one point per reporting period. Default `false`: `data.series[].breakdowns` is an empty array. `true`/`false`/`1`/`0`/`yes`/`no`; any other value -> 400 INVALID_PARAM.	true

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.reporting_currency	string	yes	The ISO-4217 currency of the response's monetary points: the company's reporting currency as `GET /api/v1/xbrl/timeseries` elects it (the currency covering the most reporting periods across the company's standardized figures). For a company with no standardized figures it is elected the same way from the members' own figures, so it can then be a convenience-translation currency the filer tags beside its reporting currency (a tie goes to the later code alphabetically, the `/timeseries` tie-break). A fact in any other currency is not served. Null when no served point is monetary, the `/timeseries` rule.
data.series[]	array	no	One entry per as-filed member on the chosen `axis` with at least one served point (with `breakdowns=true`: a point or any other fact). Each: `member` (the member qname, INCLUDING filer extensions like `msft:IntelligentCloudMember`), `points[]` and `breakdowns[]`. 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 OWN figure for the chosen concept / metric — at most one point per reporting period: `{fiscal_year, fiscal_period, period_end, start_date, end_date, value, decimals, unit, concept, is_extension, accession_no, other_dimensions}`. The own figure is the fact tagged with the member alone, or with the member plus Consolidation Items = Operating Segments (US GAAP `srt:`/`us-gaap:ConsolidationItemsAxis` = `us-gaap:OperatingSegmentsMember`, or IFRS `ifrs-full:SegmentConsolidationItemsAxis` = `ifrs-full:OperatingSegmentsMember`). On a segments axis (`us-gaap:StatementBusinessSegmentsAxis`, `ifrs-full:SegmentsAxis`) the Operating Segments figure, the reportable-segment amount of the FASB and IFRS 8 segment models, is served when a filing tags both under one concept; on any other axis the member alone is served (it is the member's total; Operating Segments excludes corporate items and eliminations), and the Operating Segments figure only when the member alone is not tagged under the same concept. A fact that also carries another dimension (a product, region or customer split, or a reconciling item) is a breakdown, never a point here. Only the company's own figures are served: in a report filed jointly by several registrants, a fact tagged with the filer's own `dei:LegalEntityAxis` member, as the engine's registrant resolution names it from the filing's `dei:EntityCentralIndexKey` facts, counts as the member alone, another registrant's member is a breakdown, and a context naming another company is served only as the filer's proved column of a combined report. For a `metric`, a period whose figures are tagged with several of its concepts serves the concept the company's standardized figure for that period came from (`GET /api/v1/xbrl/timeseries`); without one, the period is served only when every mapped concept reports the same number (named by the metric's highest-ranked concept) and is otherwise withheld. For one period filed twice, the latest-accepted filing; a fact it tags twice at two roundings serves the more precise, and two different values at the same precision are withheld. A withheld period has no point; `breakdowns=true` lists its candidates. `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[].other_dimensions	array	no	The fact's dimensions other than the requested `axis`, as `[{axis, member}]` (the `GET /api/v1/xbrl/facts` dimensions shape: an explicit member is its qname, a typed member an object `{t: text}`). Empty for a member figure tagged alone (the filer's own legal-entity member is not repeated); `[{axis: "srt:ConsolidationItemsAxis", member: "us-gaap:OperatingSegmentsMember"}]` for an Operating Segments figure.
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.
data.series[].breakdowns[]	array	no	With `breakdowns=true`: every other fact the request read for the member, one entry per combination of other dimensions and concept — `{other_dimensions, points}`, one point per reporting period (the latest filing; the same duplicate rule as the own figure; a filing's conflicting duplicates are withheld here too). They are the member's splits (by product line, region, customer type), its reconciling items (for example Consolidation Items = Intersegment Eliminations), the member's figure in the shape `points` does not serve (`other_dimensions: []` for the member alone), the concepts `points` does not serve, and each candidate of a period `points` withholds; each point names its `concept`. Sum the entries of one split (for example every product line) to reconcile to the figure it splits where the filer reports a complete split. A fact whose context the engine's retained record marks unusable (a typed, unresolved or defaulted dimension member, or an inconsistent context), or that names another company outside a proved combined-report column, is never read, here or in `points`. Empty without `breakdowns=true`.
meta.breakdowns	boolean	no	Echo of the `breakdowns` request parameter.
meta.truncated	boolean	no	True when the request's facts exceeded the 5,000-fact read cap. Facts are read newest period first (quarters newest first within a fiscal year); the oldest fiscal period read is then dropped whole, never served from part of its facts, and older periods are missing (a single period with more than 5,000 facts returns no point). Narrow with `years=N` (or omit `breakdowns=true`) to see them.

Sample response

"request_id": null
"timestamp": "2026-09-24T12:00:00Z"
"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"
- "reporting_currency": "USD"
- "series":
}
"meta":
- "basis": "latest"
- "as_of": null
- "member_count": 2
- "concepts_resolved":
- "years": "all"
- "breakdowns": false
- "truncated": false
- "note": "As-filed members; no cross-company member canonicalization. Each point is the member's own figure for one reporting period: the axis member alone, or with Consolidation Items = Operating Segments (preferred on a segments axis; elsewhere only when the member alone is not tagged under the same concept). A period whose concepts or duplicate facts disagree is withheld. breakdowns=true adds every other fact of the member. 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

Reveal credentials

curl "https://api.finradar.ai/api/v1/xbrl/segments?ticker=MSFT&cik=789019&axis=srt%3AStatementGeographicalAxis&concept=us-gaap%3ARevenues&metric=revenue&period=Q&years=25&as_of=2024-06-30&basis=original&breakdowns=true" \
  -H "X-API-Key: YOUR_API_KEY"

Generate an API key in /account/credentials to run live queries (literal YOUR_API_KEY placeholder shown until then).