How should an AI agent read segment revenue?

An agent should present a segment breakdown as complete only when its axis is reconciled, give the ratio and quote the warnings when the axis is over or under, and keep each axis apart. When a tool returns the reason not_covered or no_extracted_data, the agent should tell the user that numi has no such data, and not that the company has no segments. With each figure, it should cite the filing it came from. Your agent reads numi through the MCP server at https://api.numi.sh/mcp, or through the REST API from your own tool code. Both return the same objects, so everything below applies to both.

The status of each axis

Each axis has three fields for the check: revenue_total (the revenue the filing reports), coverage_ratio (the rows divided by that total) and reconciliation (the status):

`reconciliation`	The rows, with any reconciling rows	What the agent should say
`reconciled`	Come to 95 to 105 percent of `revenue_total`	The rows as the breakdown of revenue, each with its `revenue_share`
`over`	Come to more than 105 percent	The rows and the ratio, that the rows exceed the reported total, and the axis warnings
`under`	Come to less than 95 percent	The rows and the ratio, and that part of revenue is in no row
`unknown`	Can’t be checked: the filing reports no revenue total, no row states revenue, or the total is only part of a bank’s revenue. The segments page lists each case	The rows, that numi could not check them against a total, and the warning that says why

reconciled is an arithmetic check on the rows numi kept. It does not prove that the filing has no other breakdown, so an agent that needs the filing’s own words can read the segment note with get_segment_note.

The warnings

warnings lists, in the extractor’s own words, what it chose or left out for the axis: a row it removed as a subtotal, the reading it kept, or a total it took from another revenue concept. When an axis is not reconciled, the agent should quote its warnings instead of guessing a cause, and read the segment note when the user asks why. On a reconciled axis, it should quote a warning that removed a row the user may look for, such as a country the filing also reports on its own. An empty array means the extractor raised no warning. null means the axis was extracted before numi recorded warnings.

When there is no answer

Over MCP, a tool error is text that starts with Error (<code>), or with Error (<code>, <reason>) when it has a reason, such as Error (not_found, no_extracted_data). Over REST, the same code is error.code and the same reason is error.reason in the JSON body. A not_found error can have one of these reasons:

not_covered: no company in numi matches. The agent should say that numi does not cover the company. When it is unsure of a ticker, it should call search_companies first.
no_extracted_data: numi holds the company’s filings and read no such breakdown from them. The filing may still describe the breakdown in its segment note, so the agent can offer to read it.
not_extracted: numi holds the filings and has no data from them yet. The message says which case applies: when the filings are waiting, the data comes after the next daily run; when numi could not extract them, the message gives the address to write to. The agent should relay that, and not say that the data is missing.
no_filings: numi knows the company and holds no filing of it yet.
no_such_filing: the company has no extracted filing with that filing_id. The agent should call get_company for the filing ids.
no_note: the filing has no segment note on file.

An empty history is not an error: its reason field says why it is empty, such as none_before_as_of when every filing came after as_of. One error has a code and no reason: sandbox_restricted, with status 403, when the key is on the sandbox plan and the company is not one of the 10 sandbox companies. Its message lists the companies the key can read.

Keep each axis apart

A filing often reports the same revenue on more than one axis. Microsoft’s business, product and geography axes each add up to 100 percent of its revenue, so one list with the rows of all three comes to 300 percent. The agent should answer from one axis at a time: business for operating segments, product for products and services, geography for regions.

An example

A user asks how Meta’s revenue splits by region. get_segments for META with axis set to geography returns reconciliation reconciled and a coverage_ratio of 1, with four rows: “US Canada”, “Asia Pacific”, “Europe” and “Rest of World”. The axis has one warning:

Removed country:US from the geography axis as an alternative partition: the rows kept are a finer breakdown of the same revenue.

Meta also tags its US revenue on the same axis, and the extractor took that row out so that US revenue doesn’t count twice. The axis is reconciled, so the agent can give the rows as shares of revenue, and it quotes the warning because the user may look for a US figure. An answer that follows the rules on this page:

In its 10-K for the year ended December 31, 2025, Meta reported revenue of $201.0 billion. By region: US Canada $78.9 billion (39.2%), Asia Pacific $53.8 billion (26.8%), Europe $46.6 billion (23.2%) and Rest of World $21.7 billion (10.8%). The four regions add up to that revenue, so numi marks them reconciled. There is no separate row for the United States, and the warning on the axis says why: “Removed country:US from the geography axis as an alternative partition: the rows kept are a finer breakdown of the same revenue.” Source: Meta’s 10-K for the year ended December 31, 2025, accession 0001628280-26-003942, https://www.sec.gov/Archives/edgar/data/1326801/000162828026003942/0001628280-26-003942-index.htm

Cite the filing

The filing of each response has its form_type, period_end, accession_number and source_url, the filing’s index page on EDGAR, where numi has matched the filing to an EDGAR submission. An agent that cites the form, the period and the link with each figure gives the user a way to check it.

Instructions you can give your agent

When you use numi segment data:
- Present an axis as a complete breakdown only when its reconciliation is "reconciled".
- When it is "over" or "under", give coverage_ratio and quote the axis warnings. Do not guess a cause.
- Quote a warning that removed a row the user may look for, such as a country.
- Never add up rows from two axes (business, product, geography).
- If a tool error has the reason not_covered, say that numi does not cover the company.
- If it has the reason no_extracted_data, say that numi read no such breakdown, and offer to read the segment note.
- If it has the reason not_extracted, say that numi has no data from the filings yet, and pass on what the message says to do next.
- With each figure, cite the form, the period end and the source_url of its filing.

Prompts to try

Each of these names only sandbox companies, so it works with a free sandbox key from numi.sh/account:

Break down Microsoft’s revenue by product line for its last fiscal year, and say whether the lines add up to total revenue.
Compare how Apple and NVIDIA split their revenue by region in their latest annual reports.
How has Amazon’s revenue by business segment changed across its recent annual filings?

Getting started

Data

Guides

API reference

Changelog

How should an AI agent read segment revenue?

The status of each axis

The warnings

When there is no answer

Keep each axis apart

An example

Cite the filing

Instructions you can give your agent

Prompts to try

​The status of each axis

​The warnings

​When there is no answer

​Keep each axis apart

​An example

​Cite the filing

​Instructions you can give your agent

​Prompts to try

The status of each axis

The warnings

When there is no answer

Keep each axis apart

An example

Cite the filing

Instructions you can give your agent

Prompts to try