> ## 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.

# Deep research with a source for every claim

> Build a research agent whose report can be checked. Every sentence names the passage it rests on, every empty cell says why it is empty, and every search is stored with its receipt. The example compares the AI strategies of 60 countries.

A client asks how 60 countries plan to pay for artificial intelligence (AI) compute. Your agent writes the report. The client's analyst then picks 5 sentences and looks for their sources, and the report is worth what those 5 checks find. This page builds the run so that each check is one call, and so that the report already says what it could not find.

## The run in 7 steps

### Search 20 countries in one call

Each country is one search: the question, 3 more wordings in the country's own language, the country itself, and a sentence on why you search. `search_batch` runs 20 of them at once, so 60 countries are 3 calls. The fields at the top apply to every search: official and primary sources first, and your own instructions for the ranking. `contents` fetches the first result of each search in the same call, finds the passages for 4 questions in it, and has a model fill a template of 5 fields, sent as a JSON Schema.

```json Request body of search_batch, cut to 2 of 20 items theme={"theme":"css-variables"}
{
  "items": [
    {
      "label": "brazil",
      "query": "Brazil national AI strategy public investment in compute",
      "alternate_queries": [
        "Plano Brasileiro de Inteligência Artificial investimento em infraestrutura computacional",
        "estratégia brasileira de inteligência artificial supercomputador financiamento",
        "PBIA 2024-2028 orçamento para capacidade computacional"
      ],
      "subject_country": "BR",
      "purpose": "Find the official text of the national AI strategy of Brazil and what it commits to compute."
    },
    {
      "label": "germany",
      "query": "Germany national AI strategy public investment in compute",
      "alternate_queries": [
        "KI-Strategie der Bundesregierung Investitionen in Rechenkapazität",
        "Nationale KI-Strategie Deutschland Förderung Recheninfrastruktur",
        "Fortschreibung der KI-Strategie Haushaltsmittel Hochleistungsrechnen"
      ],
      "subject_country": "DE",
      "purpose": "Find the official text of the national AI strategy of Germany and what it commits to compute."
    }
  ],
  "ranking_priorities": ["official", "primary"],
  "ranking_instructions": "Put the strategy document itself before news and commentary about it. Among versions, put the most recent first.",
  "contents": {
    "top": 1,
    "max_characters": 0,
    "highlights": [
      "How much public money is committed to compute?",
      "Which body is responsible for the strategy?",
      "Which years does the plan cover?",
      "What does the plan say about a national supercomputer?"
    ],
    "json_schema": {
      "type": "object",
      "properties": {
        "compute_budget": {
          "type": "string",
          "description": "Public money committed to computing capacity, with its currency"
        },
        "total_budget": {
          "type": "string",
          "description": "All public money of the plan, with its currency"
        },
        "responsible_body": {
          "type": "string",
          "description": "The ministry or agency in charge of the strategy"
        },
        "period": { "type": "string", "description": "The first and the last year the plan covers" },
        "supercomputer_planned": {
          "type": "boolean",
          "description": "Whether the plan commits to a national supercomputer"
        }
      }
    }
  },
  "wait_seconds": 40
}
```

For each country the response has the ranked results, each with the profile of its source. For the first result it has the outline, the place of each passage that bears on a question, and the 5 fields, each with the words it was filled from. No whole page has entered your agent's context yet, only excerpts, passages, and the words of each field.

### Read what each source is

Every result has a profile: the kind of its publisher, and whether it is a primary source. A ministry's own strategy comes before a consultancy's summary of it, and the summary stays in the list for context. A news story that 14 sites reprinted is one result, with the number of its copies.

### Read each cell for what it rests on

Each field of the template has a status. This part of the response is the row of one country, cut to the status and the printed page of each field.

```json Part of the response theme={"theme":"css-variables"}
{
  "schema_statuses": {
    "/responsible_body":      { "status": "found", "page_label": "12" },
    "/period":                { "status": "found", "page_label": "3" },
    "/total_budget":          { "status": "found", "page_label": "41" },
    "/compute_budget":        { "status": "absent" },
    "/supercomputer_planned": { "status": "unread" }
  }
}
```

These 3 statuses are 3 different sentences in your report. `found` is a figure with its page, and `absent` is a finding: this strategy names no budget for compute. `unread` says that a part of the document was not read, so the report can say nothing yet about a supercomputer. A field has one of 2 more statuses in other cases: `empty` if the source shows the field with no value, and `failed` if the model could not fill it.

### Finish the strategies that did not fit

Some strategies are 200-page PDFs, and some are scans. A document that was not finished inside the search comes back as `partial`. Send its address to `upload_contents`, which reads the whole of it as a job, and fill the template again from that record. A scanned page that was read with low confidence is named, so a person looks at those pages and not at all of them.

### Read only the sections that matter

Where the evidence is thin, your agent reads one section by its id with `get_section`, or the tables of one section with `list_blocks`. Each of these reads is from the stored record, so it costs nothing and returns the same text to every agent of the run.

### Check the draft before it goes out

A second agent takes the draft and sends each quoted figure to its record as a highlight, with `deterministic_only` set to `true`. A quote whose words are in one block of the source comes back as `exact`, or as `near` if only its case or the punctuation at the ends of its words differs. A quote that is found nowhere gets the notice `highlight_not_found`, and its sentence goes back to the writer. This check uses no model and costs nothing.

### Take the method section from the receipts

Each search is stored with its receipt: which datasources ran, with which wordings, what was dropped, and what could not be searched. With `record_form` set to `plain`, a search also returns that account written out, ready for the method section of the report. A gap is said and not hidden: if no datasource in a country's language was searched, the report can say so.

## What the reader of the report can check

| The reader asks | What your report has |
| - | - |
| Where does this figure come from? | The record, the block, the printed page, and the words. |
| Is that an official source? | The kind of its publisher, and whether it is primary. |
| Why is this cell empty? | `absent`, the source does not state it, or `unread`, a part was not read. |
| What did the search miss? | The coverage gaps of each search. |
| Is it still true? | A new fetch whose fingerprint is compared with the stored one, and a comparison block by block if the 2 differ. |

## Update the report next quarter

Store each source's Markdown with its fingerprint and the version of getclean that read it, because a record is stored for at most 30 days. Next quarter, fetch the sources again under that version, with `pinned_version`, and compare each new fingerprint with the stored one. For each source whose fingerprint differs, `compare_contents` takes the stored Markdown and its fingerprint as the baseline and returns the blocks and the table cells that changed, with the text before and after.

## Know the limits

A wording runs only on the datasources that cover its language, and nothing is translated. A language that no datasource covers is a coverage gap in the receipt.

A record is stored for 48 hours after its last use and for at most 30 days, so what the report must show later, you store yourself.

The tables of a scan and of a PDF without structure come as text, not cell by cell.

The passages for a question and the filled fields are a model's work. Each filled field comes with the words of the source, and the check of the draft uses no model.

For the guide to each step, see [From a question to a checked report](https://docs.getclean.ai/start/how-it-fits.md).


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