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

# Ask 20 questions in one call

> Send up to 20 questions in one call, each with its own wordings, country, and purpose. The questions share one set of filters and one spending limit, and the response opens with a tally of how they ended.

A comparison of the AI strategies of 60 countries is 60 searches that differ in 2 things: the country, and the language of the question. `search_batch` runs up to 20 searches in one call, so the comparison is 3 calls. Each search gets its own question, and the rules for ranking and filtering are written once.

## Send the questions

Put each question in `items`, and the fields that all of them share at the top. This request asks 3 countries the same question, each in 4 wordings, in English and in the country's own language.

```bash cURL theme={"theme":"css-variables"}
curl https://api.getclean.ai/v1/search:batch \
  --header "Authorization: Bearer $GETCLEAN_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: IDEMPOTENCY_KEY" \
  --data '{
    "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."
      },
      {
        "label": "japan",
        "query": "Japan national AI strategy public investment in compute",
        "alternate_queries": ["AI戦略 計算資源 投資", "国家AI戦略 計算基盤 予算", "統合イノベーション戦略 AI 計算資源の整備"],
        "subject_country": "JP",
        "purpose": "Find the official text of the national AI strategy of Japan 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.",
    "max_candidates": 5
  }'
```

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

client = GetClean()

batch = client.search_batch(
    items=[
        SearchBatchItem(
            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.",
        ),
        SearchBatchItem(
            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.",
        ),
        SearchBatchItem(
            label="japan",
            query="Japan national AI strategy public investment in compute",
            alternate_queries=["AI戦略 計算資源 投資", "国家AI戦略 計算基盤 予算", "統合イノベーション戦略 AI 計算資源の整備"],
            subject_country="JP",
            purpose="Find the official text of the national AI strategy of Japan 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.",
    max_candidates=5,
)
```

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

const client = new GetClean();

const batch = await client.searchBatch({
    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.",
        },
        {
            label: "japan",
            query: "Japan national AI strategy public investment in compute",
            alternate_queries: ["AI戦略 計算資源 投資", "国家AI戦略 計算基盤 予算", "統合イノベーション戦略 AI 計算資源の整備"],
            subject_country: "JP",
            purpose: "Find the official text of the national AI strategy of Japan 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.",
    max_candidates: 5,
});
```

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 run and charged twice. The SDKs make the key for you.

## Read the tally first

The response starts with `counts`, and then has one result for each item, in the order you sent them. This response is cut to the tally and to the outcome of each search.

```json 200 OK theme={"theme":"css-variables"}
{
  "counts": { "delivered": 3, "partial": 0, "failed": 0, "refused": 0, "needs_person": 0, "skipped": 0 },
  "results": [
    { "index": 0, "label": "brazil", "search": { "outcome": { "kind": "delivered", "reason": "candidates" } } },
    { "index": 1, "label": "germany", "search": { "outcome": { "kind": "delivered", "reason": "candidates" } } },
    { "index": 2, "label": "japan", "search": { "outcome": { "kind": "delivered", "reason": "candidates" } } }
  ]
}
```

Each result is a whole search, with its results, its receipt, and an `id` of its own, so `get_search` reads it again later. An item that could not run has a `problem` in place of a search and is counted as `skipped`. One item never stops the others.

## Know which fields belong to an item

An item has the question and what belongs to it.

| Field of an item | What it is |
| - | - |
| `query` | The question. |
| `alternate_queries` | Other wordings of it, in any language. |
| `subject_identifiers` | Exact codes of the subject, such as a registry number. |
| `subject_country` | The country the search is made from. |
| `purpose` | Why you search, in a sentence that every model step of that search reads. |
| `label` | Your own name for the item, returned with its result. |

Every other field of a search is set at the top and applies to all items: the datasources, the filters, the ranking, the sizes. A field in the wrong place is refused, and the problem says where it belongs.

## Read the first result of each search in the same call

`contents` at the top applies to every search of the batch. Set `top` to `1`, and put your questions in `highlights` and your fields in `json_schema`. One call then returns, for each of 20 countries, the first official source, the passages that bear on your questions, and a filled row. For those fields, see [Search and get the evidence in one call](https://docs.getclean.ai/find/search-and-read.md).

## Plan for the time a batch takes

Each search has its own `wait_seconds`, counted from its own start. 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.

## Check what a batch of searches costs

A batch costs the sum of its searches. `max_cost` is the spending limit of the whole call, 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.