> ## Documentation Index
> Fetch the complete documentation index at: https://docs.numi.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Revenue by segment from XBRL

> How to read a company's revenue by business, product and region from its SEC filing, and check that each breakdown adds up.

Segment revenue is a dimensional fact, a revenue concept on an axis with a member, and it is not in the SEC's companyfacts, companyconcept or frames APIs, which hold only facts that apply to the whole entity. Each axis is read on its own and checked against the undimensioned revenue total.

## The method

1. **Get the filing's facts with their dimensions.** Read the XBRL instance of the filing, or the JSON of a converter or an open-source parser. The entity-wide APIs will not do, because they carry no dimension.
2. **Keep the facts on one target axis at a time.** `StatementBusinessSegmentsAxis` gives operating segments, `ProductOrServiceAxis` gives products and services, and `StatementGeographicalAxis` gives regions. The [segments](https://docs.numi.sh/segments.md#axes) page lists the other axis names that numi maps to these three. Never put the rows of two axes in one list.
3. **Separate segment rows from reconciling rows by the consolidation member.** A fact with `OperatingSegmentsMember`, or with no consolidation member, is a segment row. A fact with `IntersegmentEliminationMember`, `CorporateNonSegmentMember`, `UnallocatedAmountsMember` or another reconciling member is a reconciling row. [What are reconciling rows?](https://docs.numi.sh/segments.md#what-are-reconciling-rows) has the detail.
4. **Add the segment rows and the reconciling rows, and divide by the filing's revenue total.** The total is `Revenues` or `RevenueFromContractWithCustomerExcludingAssessedTax`, with no dimension, for the same period and in the same unit.
5. **Read the ratio.** From 95 to 105 percent, the axis reconciles. The ratio says how far the rows are from the total, not why. Above the band, the common causes are two breakdowns on one axis, and sales between segments with no elimination row. Below the band, the common cause is a row that the filing does not tag. With no total, there is nothing to check. The filing's segment note says which cause applies.
6. **Keep the prior periods that the filing carries, each with the filing that reported it.** An annual report carries up to three fiscal years, and a later filing can restate a figure. The [history](https://docs.numi.sh/history.md) page explains how numi keeps them.
7. **Know what you chose.** A filer often states a segment's revenue twice, once with the operating-segments member and once with none, and the two differ. A parser must pick one context for each axis and say which. Rows that are sums of other rows must be dropped before the check, and the check must say so. The extractor behind the API keeps the context whose rows come nearest the reported total and removes rows that sum others. Each axis lists the reading it kept and the warnings for it, and the segments page's section [What the extractor decides](https://docs.numi.sh/segments.md#what-the-extractor-decides) has the detail.

## Why do the segment rows add up to more than revenue?

Two causes are common. The first is two breakdowns on one axis: a filer can tag the same revenue once by `ProductMember` and `ServiceOtherMember` and once by its product lines, and a list with every member counts that revenue twice. The second is sales between segments. A segment's revenue can include sales to another segment, so the segment rows add up to more than revenue until the elimination row, which is negative, brings them back. Add the reconciling rows before you compare. If the sum is still above 105 percent, read the filing's segment note.

## Does the SEC's companyfacts API have segment data?

No. The companyfacts, companyconcept and frames APIs hold only facts that apply to the whole entity, and a segment fact has a dimension, so none of them appears. The consolidated revenue is there, and the revenue of each segment is not. A request for segment revenue needs the filing's own XBRL facts, or a service that reads them.

## The same in one call

For a filer in the sandbox, one request returns each axis with its rows, its revenue total, its ratio and its status:

```bash theme={null}
curl "https://api.numi.sh/v1/companies/MSFT/segments" \
  -H "X-API-Key: $NUMI_API_KEY"
```

The `filing` in the response carries the filing's accession number and a link to its page on EDGAR, where numi has matched the filing to an EDGAR submission, so you can compare every row with the source. The MCP tool `get_segments` returns the same object. See [segments](https://docs.numi.sh/segments.md) for the meaning of each field.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.