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

> ## Agent Instructions
> getclean's own MCP server is at https://mcp.getclean.ai/mcp. The /mcp path of this docs site is Mintlify's search over these pages, not getclean.
> Every answer of the API opens with outcome. A page that could not be read is a record whose outcome says why, never an HTTP error; read outcome before anything else.
> The API's contract is the OpenAPI 3.1 file at https://docs.getclean.ai/openapi.yaml; the SDKs are generated from it.
> The product's name is written getclean, in lower case.

# Figures from filings, each traced to its cell

> Take revenue, margin, and debt from annual reports as figures that name their table, their row, and their column. Tell what a company reports about itself from what others estimate, and find a figure that was restated.

An analyst's note goes to clients before the market opens. A client traces one figure, finds that it came from a third party's estimate and not from the filing, and stops reading the notes. The figure was plausible. Its source was wrong, and nothing in the note showed that. This page builds a run in which every figure names the cell it came from, in the company's own document.

## The run in 5 steps

### Find the filing itself

Search with the company's identifier, so that a company with a similar name does not get into the results. `source_independence` set to `self` keeps only the company's own sources, and `ranking_priorities` puts the primary ones first.

```json Request body of search theme={"theme":"css-variables"}
{
  "query": "annual report 2025",
  "subject_identifiers": [{ "scheme": "lei", "value": "LEI_CODE" }],
  "source_independence": "self",
  "ranking_priorities": ["primary"]
}
```

Replace `LEI_CODE` with the company's identifier.

Each result says whether its publisher is the company itself and whether it is a primary source. An aggregator's page about the company is a secondary one, and its numbers are somebody's reading of the filing.

### Get the report as an outline

An annual report can run to 300 pages. Fetch it with `max_characters` set to `0`, and the response has its sections with their sizes and their pages. Your agent reads the income statement and the notes it needs, and not the photographs of the board.

### Read the statements as tables

Ask `list_blocks` for the blocks of kind `table` in one section. Each comes cell by cell, with its merged headings, so the figure for 2025 cannot be taken for the figure for 2024.

```json One table of the response, cut to its rows theme={"theme":"css-variables"}
{
  "table": {
    "caption": "Revenue by year",
    "rows": [["Year", "Revenue"], ["2024", "3.7 bn"], ["2025", "4.1 bn"]],
    "header_rows": [0]
  }
}
```

### Fill the fields of your financial model with their cells

Send the fields of your financial model as a schema. A model fills each field from the report, and each value comes back with the words it was taken from and with its place: the page as printed, and inside a table the row and the column.

```json Part of the response of fill_schema theme={"theme":"css-variables"}
{
  "schema_values": { "revenue_2025": "4.1 bn" },
  "schema_statuses": {
    "/revenue_2025": { "status": "found", "text": "4.1 bn", "page_label": "87", "row": 2, "column": 1 },
    "/net_debt_2025": { "status": "absent" }
  }
}
```

A field that the report does not state is `absent`, and it has no value. No plausible number is put in its place.

### Find a figure that was restated

A report often shows last year's figure beside this year's, and sometimes last year's figure has changed without a note that says so. Ask each report for the prior year's figure too, and compare it with the figure you took from last year's report. If the 2 differ, the figure was restated, and you have the cell of each.

## What a client can check

| The client asks | What your note has |
| - | - |
| Is this the reported figure? | The source is the company's own document, a primary source. |
| Which cell is it? | The table, the printed page, the row, and the column. |
| Why is there no figure here? | The report does not state one, and the field says `absent`. |
| Was last year's figure changed? | Both figures, each with its cell. |

## Know the limits

Cells come as the document displays them. The format of a number, such as a decimal comma, is not declared, so your code parses it. The arithmetic of a statement is not checked for you, and the cells are there for your code to check it.

Tables come as cells from a filing that is a web page, a spreadsheet, or a PDF with structure. The tables of a scan and of a PDF without structure come as text.

For the calls, see [Get every table, cell by cell](https://docs.getclean.ai/read/tables-and-blocks.md) and [Fill your fields, each with the words it came from](https://docs.getclean.ai/read/extract-fields-with-citations.md).


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