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

# Get one ranked list from the web and from specialist datasources

> A search runs on the web and on up to 10 datasources at once and returns one ranked list. Name the datasources, or let the search choose the ones that fit the question. The catalog says what each one covers.

Much of what research needs is in places that a web search reaches poorly, such as a register of court decisions. Each such place is a datasource: a place that getclean can search, with its own coverage and its own rules. One search runs on the web and on up to 10 datasources, and the results of all of them come back as one list.

## Let the search choose the datasources

A search that names no datasource runs on the web and on the groups of datasources that fit the question. A model makes that choice, and the response lists every datasource that ran with the reason it ran.

## Name the datasources yourself

To decide where a search runs, send `datasources`. It takes up to 10 names, each the id of a datasource, the name of a group, or a published set written as `set:NAME`. This search runs on the web and on the legal datasources of the United States.

```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": "fair use of copyrighted works to train a model",
    "datasources": ["web", "legal"],
    "subject_country": "US"
  }'
```

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

client = GetClean()

search = client.search(
    query="fair use of copyrighted works to train a model",
    datasources=["web", "legal"],
    subject_country="US",
)
```

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

const client = new GetClean();

const search = await client.search({
    query: "fair use of copyrighted works to train a model",
    datasources: ["web", "legal"],
    subject_country: "US",
});
```

`subject_country` is the country the search is made from, and a group means its datasources of that country. A search that names its datasources needs no model to choose them, so that model step does not run.

## Look in the catalog first

`list_datasources` returns the catalog, which can be narrowed by `group`, `country`, `language`, and `access`. This request lists the datasources that cover the United States.

```bash cURL theme={"theme":"css-variables"}
curl "https://api.getclean.ai/v1/datasources?country=US" \
  --header "Authorization: Bearer $GETCLEAN_API_KEY"
```

```python Python theme={"theme":"css-variables"}
for datasource in client.list_datasources(country="US"):
    print(datasource.id, datasource.group)
```

```typescript TypeScript theme={"theme":"css-variables"}
for await (const datasource of await client.listDatasources({ country: "US" })) {
    console.log(datasource.id, datasource.group);
}
```

An entry says what the datasource covers and what it can do, before any search.

| Field | What it says |
| - | - |
| `id` and `group` | The names that `datasources` takes. |
| `countries` and `languages` | What the datasource covers, where an empty list means all of them. |
| `access` | How the datasource is reached: `open`, `registered`, or `paid`. |
| `filters` | For each of the 12 filters of a search, whether the datasource applies it. |
| `operators` | For each of the 10 query operators, whether the datasource applies it. |
| `identifier_schemes` | The kinds of code it can look up, such as a docket number. |
| `history` | Whether it can be searched as it was on a past day. |

An entry of the group `legal`, for example, can cover one country and one language, apply a date filter itself, and look up a case by its docket number.

## See how a datasource treats a filter

A filter has one of 3 states on a datasource. `native` means the datasource applies it. `emulated` means getclean applies it to the results after the datasource returned them. `not_applicable` means the datasource does not take it.

A datasource that cannot apply a filter you sent, and whose results cannot be filtered afterwards, is left out of that search. The response names it and the filter, so a narrow search does not pass for a complete one. For that part of the response, see [See what a search covered and what it missed](https://docs.getclean.ai/find/search-receipt.md).

## Reach a datasource that needs a login or a fee

A `registered` datasource needs a login that the owner of the account registers. If a search names one whose login is not registered, that datasource is left out, the response says so, and the others run. If every datasource it names needs such a login, the search is refused.

A `paid` datasource charges a fee for each query, and its entry in the catalog has the fee. `max_source_price` sets the most you allow for one query. A datasource that asks more is not searched, and the response says so.

## Check what several datasources cost

A search is charged one unit for each wording on each datasource it ran on. The choice of datasources is one model step, and it does not run if you name them. `list_datasources` and `get_datasource` cost nothing.


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