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

# See what a search covered and what it missed

> Every search returns a receipt: which datasources ran, with which wordings and filters, how many results each found, what was dropped and why, and what was asked but not searched.

A list of 10 results does not say whether 10 pages were found or 400, whether the German wording ran anywhere, or whether the date filter was applied. An agent that cannot see this repeats a weak search, and a reviewer cannot tell a careful search from a careless one. Every search here returns an account of itself with its results. An agent reads it to make its next search better, and a reviewer reads it to check the method.

## Read why the list ended

`counts` says how many pages were found and why the others are not in the list. This response is cut to the reasons that are not 0.

```json Part of the response theme={"theme":"css-variables"}
{
  "counts": {
    "returned": 3,
    "found": 41,
    "dropped": { "not_relevant": 30, "folded_copy": 8 }
  },
  "end_reason": "relevance"
}
```

Of 41 pages found, 3 came back. The ranking put 30 under its cut-off for relevance, and 8 were copies of a page already in the list. The numbers add up: `found` is `returned` plus every number in `dropped`.

`end_reason` says why the list stopped where it did.

| `end_reason` | Why the list ended |
| - | - |
| `relevance` | The next result was under the ranking's cut-off for relevance. |
| `max_candidates` | The number of results you asked for was reached, and more are stored. |
| `exhausted` | Every datasource returned all it had. |
| `source_cap` | Every datasource reached `max_per_datasource`. |
| `ceiling` | The spending limit was reached. |

## See what each datasource did

`datasources_searched` has one entry for each datasource that ran. This response is cut to one entry and to the fields that this section explains.

```json Part of the response theme={"theme":"css-variables"}
{
  "datasources_searched": [
    {
      "id": "web",
      "reason": "default",
      "outcome": { "kind": "delivered", "reason": "candidates" },
      "wordings": [0],
      "returned_count": 41,
      "result_count": 41,
      "result_count_kind": "exact",
      "filters_applied": {
        "published_within_days": { "state": "native" },
        "undated": { "state": "emulated", "how": "pages without a detectable date kept, as asked" }
      }
    }
  ]
}
```

An entry says why the datasource ran, how its part of the search ended, and which of your wordings it ran. `result_count` is the number of results the datasource says it has, and `result_count_kind` says whether that number is `exact`, an `estimate`, or a `lower_bound`.

`filters_applied` says for each filter whether the datasource applied it itself, `native`, or getclean applied it afterwards, `emulated`, with a line on how. Query operators such as a phrase in quotation marks are reported the same way in `operators_applied`.

## Find what was not searched

A part of the request that could not be searched at all is a coverage gap. `coverage_gaps` names each one: a datasource, a wording, a site, or a language, with the reason.

| `reason` | What happened |
| - | - |
| `not_covered` | No datasource covers the language of the wording, or the site. |
| `access_needed` | The datasource needs a login that is not registered. |
| `over_price` | The datasource's fee is above `max_source_price`. |
| `no_history` | The datasource cannot be searched as of a past day. |
| `filter_unsupported` | The datasource cannot apply a filter you sent. |
| `not_accepted` | The datasource did not accept the question as written. |
| `wording_too_long` | The wording is longer than the datasource takes. |
| `unreachable` or `deadline` | The datasource could not be reached, or did not respond in time. |
| `blocked` or `withheld_by_law` | The datasource refused the search, or a legal demand stops it. |
| `over_cap` | A limit of the search was passed. |

A gap is a fact to put in a report. "No German source was searched" is another finding than "no German source says so".

## Read the results that were dropped

The whole list is stored with the search, and `get_search` returns it at no charge. Its later pages have the results that were dropped, each with its `dropped_reason`.

```bash cURL theme={"theme":"css-variables"}
curl "https://api.getclean.ai/v1/search/SEARCH_ID?page_token=PAGE_TOKEN" \
  --header "Authorization: Bearer $GETCLEAN_API_KEY"
```

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

client = GetClean()

for candidate in client.get_search(search_id="SEARCH_ID"):
    print(candidate.url, candidate.dropped_reason)
```

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

const client = new GetClean();

for await (const candidate of await client.getSearch("SEARCH_ID")) {
    console.log(candidate.url, candidate.dropped_reason);
}
```

Replace `SEARCH_ID` with the `id` of the search, and `PAGE_TOKEN` with the `next_page_token` of the page before. The SDKs ask for the next page as you loop.

## See how the question was read

`interpretation` says how the question was understood: the phrases in quotation marks, the excluded words, the operators, and every wording that ran with the number of results it found on each datasource. If a spelling was corrected, the corrected wording ran beside yours, and the notice `query_corrected` says so.

`applied_request` has the request as it ran, with every default written out.

## Hand the method to a reviewer

A systematic review has to report each search as it was run, with its date and its counts. Send `record_form`, and the response has the search written up in `record`. `plain` writes it in plain words. `prisma` writes it in the PRISMA form, which is the form such reviews report in.

A search is stored for 48 hours after its last use and for at most 30 days, so store the write-up with your own files.

## Check what a receipt costs

The receipt is part of every search and adds nothing to its cost. `get_search` costs nothing, and the key needs the scope `search:read`. A search that sends `view` as `compact` returns a smaller response without the receipt.


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