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

# Fetch 20 sources at once and know what came back before you read a word

> Send up to 20 addresses in one call and get one record for each. The response opens with a tally of how the fetches ended, so your code knows the state of the whole batch before it reads one record.

A watch list has 20 official pages, a tender page links to 9 PDFs, and a diligence needs 12 filings. Fetched one by one, each costs an agent a turn, and a fetch that failed in the middle of the run can go unseen. `fetch_contents_batch` takes up to 20 addresses, fetches them side by side, and returns a tally and then one result for each address, in the order you sent them.

## Send the addresses

Put each address in `items`. Fields at the top of the request apply to every item. This request reads the 5 documents of one company for a diligence: each comes back as its outline with a summary, and 3 of them with the passages for their own questions.

```bash cURL theme={"theme":"css-variables"}
curl https://api.getclean.ai/v1/contents:batch \
  --header "Authorization: Bearer $GETCLEAN_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: IDEMPOTENCY_KEY" \
  --data '{
    "items": [
      {
        "url": "ANNUAL_REPORT_URL",
        "label": "annual-report",
        "highlights": ["What drove the change in operating margin?", "going concern"]
      },
      {
        "url": "HALF_YEAR_REPORT_URL",
        "label": "half-year-report",
        "highlights": ["What drove the change in operating margin?"]
      },
      { "url": "SUSTAINABILITY_REPORT_URL", "label": "sustainability-report" },
      {
        "url": "BOND_PROSPECTUS_URL",
        "label": "bond-prospectus",
        "highlights": ["Change of Control", "What are the financial covenants?"]
      },
      { "url": "COMPANY_REGISTER_URL", "label": "company-register" }
    ],
    "max_characters": 0,
    "summary": true
  }'
```

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

client = GetClean()

batch = client.fetch_contents_batch(
    items=[
        ContentsBatchItem(
            url="ANNUAL_REPORT_URL",
            label="annual-report",
            highlights=["What drove the change in operating margin?", "going concern"],
        ),
        ContentsBatchItem(
            url="HALF_YEAR_REPORT_URL",
            label="half-year-report",
            highlights=["What drove the change in operating margin?"],
        ),
        ContentsBatchItem(url="SUSTAINABILITY_REPORT_URL", label="sustainability-report"),
        ContentsBatchItem(
            url="BOND_PROSPECTUS_URL",
            label="bond-prospectus",
            highlights=["Change of Control", "What are the financial covenants?"],
        ),
        ContentsBatchItem(url="COMPANY_REGISTER_URL", label="company-register"),
    ],
    max_characters=0,
    summary=True,
)
```

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

const client = new GetClean();

const batch = await client.fetchContentsBatch({
    items: [
        {
            url: "ANNUAL_REPORT_URL",
            label: "annual-report",
            highlights: ["What drove the change in operating margin?", "going concern"],
        },
        {
            url: "HALF_YEAR_REPORT_URL",
            label: "half-year-report",
            highlights: ["What drove the change in operating margin?"],
        },
        { url: "SUSTAINABILITY_REPORT_URL", label: "sustainability-report" },
        {
            url: "BOND_PROSPECTUS_URL",
            label: "bond-prospectus",
            highlights: ["Change of Control", "What are the financial covenants?"],
        },
        { url: "COMPANY_REGISTER_URL", label: "company-register" },
    ],
    max_characters: 0,
    summary: true,
});
```

Replace the 5 placeholders that end in `_URL` with the addresses of the documents. Replace `IDEMPOTENCY_KEY` with a value of your own that is new for each batch. A batch must have this key, so that a batch sent twice is not fetched and charged twice. The SDKs make the key for you.

With `max_characters` set to `0`, each record comes as its outline, and its text stays in the record for a later read.

## Read the tally first

The response starts with `counts`, which says how the items ended. This response is cut to the tally and to the outcome of each record.

```json 200 OK theme={"theme":"css-variables"}
{
  "counts": { "delivered": 4, "partial": 0, "failed": 0, "refused": 0, "needs_person": 1, "skipped": 0 },
  "results": [
    { "index": 0, "label": "annual-report",         "contents": { "outcome": { "kind": "delivered", "reason": "whole" } } },
    { "index": 1, "label": "half-year-report",      "contents": { "outcome": { "kind": "delivered", "reason": "whole" } } },
    { "index": 2, "label": "sustainability-report", "contents": { "outcome": { "kind": "delivered", "reason": "whole" } } },
    { "index": 3, "label": "bond-prospectus",       "contents": { "outcome": { "kind": "delivered", "reason": "whole" } } },
    { "index": 4, "label": "company-register",      "contents": { "outcome": { "kind": "needs_person", "reason": "sign_in_needed" } } }
  ]
}
```

The 6 numbers of the tally add up to the number of items. Here 4 documents were delivered and the company register needs a person, because a sign-in page was where the page should be. Your code can decide on the tally alone whether the batch is good enough to go on.

Each result has the `index` of its item and the `label` you gave it, and then a record. One item never stops the others. An item that could not be started at all, for example because its address is a private one, is counted as `skipped` and has a `problem` in place of a record.

## Give an item its own fields

An item can have these fields of its own.

| Field | What it does for that address |
| - | - |
| `label` | Your own name for the item, returned with its result. |
| `highlights` | Up to 5 phrases or questions to find in this source. |
| `baseline_fingerprint` | The fingerprint of an earlier record, so that a source that still has that text comes back as `unchanged`, without text. |
| `as_of_date` | The past day on which to read this page from an archive. |
| `subject_country` | The country this page is read from. |
| `subject_language` | The language the site is asked for. |

Every other field of a fetch is set once at the top. With `json_schema` at the top, the same fields are filled from each of the 20 sources, so one call returns 20 rows of one template.

## Bound the text of the whole response

`max_characters` limits the text of each record. `max_total_characters` limits the text of the whole response, so that 20 long sources cannot overflow the context of the agent that reads them. The default is 200,000 characters.

Records get their text in the order you sent them, as long as it fits in what remains. A record that would pass the limit comes as its outline with the notice `total_characters_cut`. Its text is in the stored record, and `get_contents` returns it at no charge.

## Plan for the time a batch takes

Each item has its own `wait_seconds`, counted from its own start. Items run side by side, up to the number of calls your key can have in flight, and the others wait inside the call. A batch has a time limit of its own, which `get_limits` returns. An item that was not started by then is `skipped`, and its problem says after how many seconds to send it again.

A batch takes addresses and no files. For a file you have, see [Turn PDFs, Office files, and scans into evidence you can cite by page](https://docs.getclean.ai/read/pdfs-scans-and-documents.md).

## Check what a batch costs

A batch costs the sum of its records, each charged as one fetch. A skipped item costs nothing, and so does a record that failed, was refused, or needs a person.

`max_cost` is the spending limit of the whole call. It is divided among the items in the order you sent them. An item that the rest of the limit cannot cover is skipped, and its problem names the limit that stopped it.


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