> ## 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. # How should an AI agent read segment revenue? > What an agent should say for each reconciliation status, how it reads the warnings and the reasons not_covered and no_extracted_data, and prompts to try. 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](https://docs.numi.sh/mcp-server.md) 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](https://docs.numi.sh/segments.md#reconciliation) 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 ()`, or with `Error (, )` 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](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 ```text theme={null} 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](https://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? This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.