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

# Search and get the evidence in one call

> Let a search fetch its first results in the same call. Each comes back as a record with its outline, the passages that bear on your questions, or your own fields filled, before an agent has read one page.

A search and 5 fetches are 6 calls and 6 turns of an agent. Most of those turns bring back what the agent could have asked for at the start: the outline of each page, or the passages that bear on its question. With `contents` in a search, the first results are fetched inside the call, and each is read the way you say.

## Fetch the first results with the search

Set `contents.top` to the number of results to fetch, from 1 to 10. This search returns 3 results and fetches the first one, with at most 8,000 characters of its text.

```bash cURL theme={"theme":"css-variables"}
curl https://api.getclean.ai/v1/search \
  --header "Authorization: Bearer $GETCLEAN_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "query": "EU AI Act article 50 marking obligations",
    "max_candidates": 3,
    "contents": { "top": 1, "max_characters": 8000 }
  }'
```

```python Python theme={"theme":"css-variables"}
from getclean import GetClean, SearchContentsOptions

client = GetClean()

search = client.search(
    query="EU AI Act article 50 marking obligations",
    max_candidates=3,
    contents=SearchContentsOptions(top=1, max_characters=8000),
)
```

```typescript TypeScript theme={"theme":"css-variables"}
import { GetClean } from "getclean";

const client = new GetClean();

const search = await client.search({
    query: "EU AI Act article 50 marking obligations",
    max_candidates: 3,
    contents: { top: 1, max_characters: 8000 },
});
```

A fetched result has a record in `contents`. This response is cut to the first result and to its record.

```json 201 Created theme={"theme":"css-variables"}
{
  "candidates": [
    {
      "title": "Regulation (EU) 2024/1689",
      "url": "https://eur-lex.example/ai-act",
      "contents": {
        "id": "cnt_8Lq5XFriyaJ0jEc2oPNx6E",
        "outcome": { "kind": "delivered", "reason": "sections_only" },
        "truncated": true,
        "sections": [
          { "id": "s0", "title": null, "level": 0, "characters": 400 },
          { "id": "s4", "title": "Article 50", "level": 2, "characters": 9100 }
        ]
      }
    }
  ]
}
```

The page has more than 8,000 characters, so its outline came in place of a text cut at an arbitrary point. The section "Article 50" has 9,100 characters, and one more call reads it by its id. For that call, see [Read the 2 sections you need from a 300-page document](https://docs.getclean.ai/read/long-documents.md).

## Choose how each result is read

`contents` takes the fields of a fetch.

| Field | What it asks of each fetched result |
| - | - |
| `top` | How many of the first results to fetch. |
| `max_characters` | The most text of one page, where `0` returns the outline and no text. |
| `highlights` | Up to 5 phrases or questions to find in the page. |
| `json_schema` | Your own fields, filled from the page. |
| `summary` | A summary of the page. |
| `scope` | The main content, or the whole page. |
| `block_kinds` | Only blocks of these kinds, such as `table`. |

The record of a fetched result has its text as Markdown, or its outline. Any other format is a read of the stored record by its id, at no charge.

## Get the evidence without the pages

The fields combine. This request searches in 4 wordings, puts official sources first, asks 4 questions of the first of them, fills a template of 5 fields from it, and returns no page text at all.

```json Request body theme={"theme":"css-variables"}
{
  "query": "Brazil national AI strategy compute investment",
  "alternate_queries": [
    "Plano Brasileiro de Inteligência Artificial investimento em infraestrutura computacional",
    "estratégia brasileira de inteligência artificial supercomputador financiamento",
    "Brazil AI plan 2024-2028 budget for computing capacity"
  ],
  "ranking_priorities": ["official", "primary"],
  "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
}
```

The response has, for the first result, its outline, the place of each passage that bears on a question, and the 5 fields, each with the words it was filled from. The agent has spent one call and has the evidence and the way back to it. It reads a section in full only where the evidence is thin.

## Bound the text of the response

`max_total_characters` limits the text of the whole response, 40,000 characters unless you set it. The excerpts of the results come first. The fetched pages follow in rank order as long as they fit. A page that would pass the limit comes as its outline with the notice `total_characters_cut`, and its text stays in the record.

## Give the fetches enough time

The fetches run inside the time of the search, which is `wait_seconds`. A search has 10 seconds by default, where a fetch on its own has 30. A search that fetches several pages or asks for model steps should set `wait_seconds` higher, up to 60, because the fetches share that time.

A fetch that was not started by the end of that time makes no record. The outcome of the search is then `partial` with the reason `fetches_missing`, and the notice `fetch_not_finished` names the results. Fetch each of them with `fetch_contents`.

## Read a fetched result again

The record of a fetched result is a stored record like any other. Its `id` works with `get_section`, `list_blocks`, `highlight_contents`, and the other calls on a record. After the fetch, each excerpt of the result also has the place where its words are in the record.

## Check what the call costs

The call costs the search, and each fetch is charged as a fetch. A filled schema and a summary each cost one model step for each page, and so do highlights if a model has to judge one. Each record has its own `cost`.

A result that was not fetched has `fetch_cost`: the most a fetch of it can cost with the fields of this request. An agent can read the price of going further before it pays it. The field is missing for a document whose number of pages is not known.


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