FocusAlphaDocs
Get key
API Reference

Segmented Financials

As-reported segment breakdowns — how a company splits its revenue and operating income across product lines, geographies, and business segments — parsed directly from the dimensioned facts in its SEC 10-K and 10-Q XBRL filings. Pass a ticker and get the segment tables exactly as the company disclosed them, newest period first.

GET/v1/financials/income-statements/segments?ticker={ticker}

Provide a ticker (or cik) and get that issuer’s income-statement segment breakdowns under an income_statement_segments array, newest reporting period first. Each row is one filing period; its metrics (e.g. revenue, operating_income) are broken out by the axes the company reports along — product, geography, and business segment.

This is the segmented family
Four routes make up the segmented-financials family. The income-statement route documented here is the one that carries data — segments are disclosed on the income statement. The balance-sheet and cash-flow segment routes exist for parity and always return an empty array, and the combined route returns all three nested in one row. All four share the query parameters and error contract below.

Coverage & data source#

Segment tables are parsed straight from the dimensioned XBRL facts in each company’s SEC filing instance — not from a companyfacts summary, which drops segment dimensions — and kept fresh automatically as new 10-Ks and 10-Qs land. We cover roughly 1,300 US-listed companies that actually disclose segment breakdowns; the rest of our ~2,000-company universe reports as a single segment (or files inline XBRL without a standalone label linkbase) and returns an empty array. Values are passed through as reported — we do not re-derive, reconcile, or fill segments the company didn’t break out.

Query parameters#

tickerstringoptional
US ticker, e.g. AAPL. One of ticker or cik is required.
cikstringoptional
SEC Central Index Key, in any zero-padding, e.g. 320193 or 0000320193. Use in place of ticker.
periodstringoptional
Reporting grain: annual or quarterly. Optional — defaults to annual. Segments have no ttm grain; any other value returns 400.
limitnumberoptional
Maximum number of periods to return, newest first. Defaults to 4; minimum 1. A value below 1 returns 400.
report_periodstringoptional
Return only the period whose report date equals this exact YYYY-MM-DD value.
report_period_gte / _lte / _gt / _ltstringoptional
Bound the report date with YYYY-MM-DD comparisons — gte/lte are inclusive, gt/lt exclusive. Combine to select a range.
At least one issuer is required
You must pass ticker or cik. A request with neither returns 400.

Example request#

curlbash
curl "https://api.focusalpha.ai/v1/financials/income-statements/segments?ticker=AAPL&period=annual&limit=1" \
  -H "Authorization: Bearer $FOCUSALPHA_API_KEY"

Response#

Returns an income_statement_segments array, one element per reporting period, newest first. Each row carries seven identifying scalar fields followed by the segment metrics.

Row scalars#

tickerstring | nulloptional
The issuer's ticker (echoes the requested symbol; null when queried by CIK alone).
report_periodstringrequired
The period’s report date (YYYY-MM-DD) — the fiscal period end. Rows sort by this, newest first.
fiscal_periodstring | nulloptional
The fiscal-period label, e.g. FY2025 or Q2 2026.
periodstringrequired
The grain of this row: annual or quarterly.
currencystring | nulloptional
ISO-4217 reporting currency, e.g. USD.
accession_numberstring | nulloptional
The SEC accession number of the source filing, e.g. 0000320193-25-000079.
filing_urlstring | nulloptional
Link to the source filing's EDGAR index page.

Segment metrics#

Beyond the scalars, each row carries one key per metric the company breaks out — most commonly revenue and operating_income. A metric value is itself an object keyed by axis (the dimension the company split along), and each axis holds an array of { label, value } members:

product{ label, value }[]optional
Breakdown by product line or service, e.g. iPhone, Mac, Services.
geography{ label, value }[]optional
Breakdown by geographic area of sale, e.g. U.S., China.
segment{ label, value }[]optional
Breakdown by reportable business segment, e.g. Americas, Europe.
labelstringrequired
The member name exactly as the company labeled it in the filing.
valuenumberrequired
The reported amount for that member, in the row’s currency (whole units, not thousands).
Axes are as-reported and vary by company
Which axes appear — and how members are labeled — depends entirely on what each company discloses. Apple splits revenue by product, geography, and reportable segment; another filer may report only a single segment axis. Treat the metric and axis keys as an open map: iterate what’s present rather than assuming a fixed set. Members within an axis are not guaranteed to sum to the consolidated total (some companies disclose a partial breakdown or a separate reconciliation).

Example response#

income-statement-segments.jsonjson
{
  "income_statement_segments": [
    {
      "ticker": "AAPL",
      "report_period": "2025-09-27",
      "fiscal_period": "FY2025",
      "period": "annual",
      "currency": "USD",
      "accession_number": "0000320193-25-000079",
      "filing_url": "https://www.sec.gov/Archives/edgar/data/320193/000032019325000079/0000320193-25-000079-index.htm",
      "revenue": {
        "product": [
          { "label": "iPhone", "value": 209586000000 },
          { "label": "Mac", "value": 33708000000 },
          { "label": "iPad", "value": 28023000000 },
          { "label": "Wearables, Home and Accessories", "value": 35686000000 }
        ],
        "geography": [
          { "label": "U.S.", "value": 151790000000 },
          { "label": "China", "value": 64377000000 },
          { "label": "Other countries", "value": 199994000000 }
        ],
        "segment": [
          { "label": "Americas", "value": 178353000000 },
          { "label": "Europe", "value": 111032000000 },
          { "label": "Greater China", "value": 64377000000 },
          { "label": "Japan", "value": 28703000000 },
          { "label": "Rest of Asia Pacific", "value": 33696000000 }
        ]
      },
      "operating_income": {
        "segment": [
          { "label": "Americas", "value": 72480000000 },
          { "label": "Europe", "value": 47739000000 }
        ]
      }
    }
  ]
}

Errors#

Statuses: 400 (neither ticker nor cik, an out-of-range limit, a bad period, or a malformed report-period date), 401 (bad or missing API key), 402 (per-minute rate limit or monthly quota exceeded — upgrade your plan), 404 (unknown issuer), and 503 (data temporarily unavailable; includes a Retry-After header — retry shortly). A known issuer that discloses no segments is a successful 200 with an empty income_statement_segments array. Errors use the bare { error, message } envelope — see Errors.