> ## 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 one question in 20 wordings

> Send one question with other wordings of it, in any language. The search runs them all on the web and on specialist datasources and returns one ranked list. Each result says which wording found it, and where.

A person types one query in one language and reads the first page of results. A research question has more than one form: the term a lawyer uses, the words of a news story, the same question in German and in French. `search` takes all of them in one call, runs each where it can be understood, and returns one list.

## Send a question with its other wordings

Put the question in `query` and the other wordings in `alternate_queries`. This search asks one question in 9 wordings and 5 languages: the legal reference, the plain words of a news story, and the terms that lawyers use in German, French, Spanish, and Italian.

```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",
    "alternate_queries": [
      "duty to label AI-generated content under the EU AI Act",
      "deepfake disclosure rules Regulation (EU) 2024/1689",
      "KI-Verordnung Artikel 50 Kennzeichnungspflicht",
      "Transparenzpflichten für KI-generierte Inhalte",
      "règlement IA article 50 obligation de marquage",
      "obligations de transparence pour les contenus générés par IA",
      "Reglamento de IA artículo 50 obligaciones de transparencia",
      "regolamento IA articolo 50 obblighi di trasparenza"
    ]
  }'
```

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

client = GetClean()

search = client.search(
    query="EU AI Act article 50 marking obligations",
    alternate_queries=[
        "duty to label AI-generated content under the EU AI Act",
        "deepfake disclosure rules Regulation (EU) 2024/1689",
        "KI-Verordnung Artikel 50 Kennzeichnungspflicht",
        "Transparenzpflichten für KI-generierte Inhalte",
        "règlement IA article 50 obligation de marquage",
        "obligations de transparence pour les contenus générés par IA",
        "Reglamento de IA artículo 50 obligaciones de transparencia",
        "regolamento IA articolo 50 obblighi di trasparenza",
    ],
)
```

```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",
    alternate_queries: [
        "duty to label AI-generated content under the EU AI Act",
        "deepfake disclosure rules Regulation (EU) 2024/1689",
        "KI-Verordnung Artikel 50 Kennzeichnungspflicht",
        "Transparenzpflichten für KI-generierte Inhalte",
        "règlement IA article 50 obligation de marquage",
        "obligations de transparence pour les contenus générés par IA",
        "Reglamento de IA artículo 50 obligaciones de transparencia",
        "regolamento IA articolo 50 obblighi di trasparenza",
    ],
});
```

A search takes up to 10 other wordings. A wording with `OR` in it counts once for each side, and a search runs at most 20 in all.

Nothing is translated. A wording runs on the datasources that cover its language, so the German wordings reach German sources that the English ones do not. The web takes every wording. You write the wordings, or the model behind the agent does, in the languages of the place you research.

## Read the list

The results come as `candidates`, in rank order. This response is cut to the first result and to the fields that say what it is.

```json 201 Created theme={"theme":"css-variables"}
{
  "candidates": [
    {
      "title": "Regulation (EU) 2024/1689",
      "url": "https://eur-lex.example/ai-act",
      "language": "en",
      "published_date": "2024-07-12",
      "source_profile": { "kind": "state", "role": "primary" },
      "copy_count": 2,
      "excerpts": [
        { "text": "Providers of AI systems … shall ensure …", "wording_index": 0 }
      ],
      "matches": [
        { "wording_index": 0, "datasource_id": "web", "rank": 1 }
      ]
    }
  ]
}
```

A result is one page for a group of copies. `copy_count` says on how many other sites the same text was found, so the copies of one story count as one source. `source_profile` says who publishes the page and whether it is a primary source. For how to rank by these facts, see [Put primary sources first](https://docs.getclean.ai/find/rank-by-source.md).

`matches` says which wording found the result, on which datasource, and at which rank there. A result that 3 wordings found on 2 datasources is one row with 6 matches.

## See what each wording found

The response says how each wording did, so the next search can be better than this one. `interpretation.wordings` has one row for each wording, with its language and the number of results it found on each datasource. This response is cut to 4 of the 9 rows.

```json Part of the response theme={"theme":"css-variables"}
{
  "interpretation": {
    "wordings": [
      { "index": 0, "text": "EU AI Act article 50 marking obligations", "language": "en", "origin": "caller", "result_counts": { "web": 41 } },
      { "index": 3, "text": "KI-Verordnung Artikel 50 Kennzeichnungspflicht", "language": "de", "origin": "alternate", "result_counts": { "web": 27 } },
      { "index": 5, "text": "règlement IA article 50 obligation de marquage", "language": "fr", "origin": "alternate", "result_counts": { "web": 19 } },
      { "index": 8, "text": "regolamento IA articolo 50 obblighi di trasparenza", "language": "it", "origin": "alternate", "result_counts": { "web": 0 } }
    ]
  }
}
```

The Italian wording found nothing, so the next search can try other Italian words or leave the language out. A wording that no datasource covers is not dropped in silence. It comes back in `coverage_gaps` with the reason, so you know what was asked and not searched.

## Use the operators you know

A wording can have a phrase in quotation marks, a word to exclude with a minus sign, `OR`, `site:`, `filetype:`, `intitle:`, `inurl:`, `before:`, `after:`, and `*`. Each datasource applies the operators it supports. The response says for each datasource what it did with each operator, so you can see whether an operator was applied.

## Narrow the results

These fields remove results. Each is applied by the datasource where it can be, and by getclean after the search where it cannot. A datasource that can do neither is left out of the search, and the response says so.

| Field | Which results stay |
| - | - |
| `published_within_days` | Pages published in the last days, counted from the day of the search. |
| `published_from`, `published_until` | Pages published between 2 dates. |
| `languages` | Pages written in these languages, whatever the language of the wording. |
| `allowed_domains`, `blocked_domains` | Results on these sites only, or no results on these sites. |
| `media_types` | Results of these file types, such as `application/pdf`. |

`max_candidates` sets how many results come back, from 1 to 50. The default is 10. The results after those are stored with the search, and `get_search` returns them at no charge.

## Check what a search costs

A search costs one search unit and one unit for each wording on each datasource it ran on. By default a model ranks the results and chooses datasources that fit the question, and each of those 2 steps is charged as a model step. To run a search without a model, send `deterministic_only` as `true`. The search then runs on the web alone unless you name the datasources, and the results come in the order the datasources gave them, merged.


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