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

# Outcomes and notices

> Every record starts with its outcome: what happened at the source, and what can work next. A page that could not be read is still a record, and its reason says what happened.

A research agent can take a failed fetch for a success: the page of a bot challenge for the article, or an empty page for "nothing to report". So the first field of every record says what happened at the source, before any content. An agent reads `outcome` first and the text second.

## An outcome has 3 parts

`outcome.kind` is one of 5 values, and code can branch on it.

| `kind` | What happened |
| - | - |
| `delivered` | Everything asked for came, which for a long source can be its outline in place of its text. |
| `partial` | The work stopped in the middle, and what was done is stored. |
| `failed` | The source did not give a page. |
| `refused` | A rule stopped the fetch, such as the site's robots file or the size of a file. |
| `needs_person` | A person has to act before this can work, for example by signing in. |

`outcome.reason` says which case it is, and `outcome.message` says in one sentence what can work next, if there is a next step. A fetch that met a bot challenge has this outcome.

```json Part of a response theme={"theme":"css-variables"}
{
  "outcome": {
    "kind": "failed",
    "reason": "challenge_served",
    "message": "A bot challenge stood where the page should be; a retry later may work on sites that do not challenge every new visitor, or a person opens the URL and uploads the saved page with captured_url."
  }
}
```

The record of such a fetch has no content, so nothing in it can pass for the article.

## Each reason says what can work next

A fetch or an upload can end with these reasons, among others. `reason` is an open list: treat a value you do not know as a new one, and read `message`.

| `reason` | What happened | What can work next |
| - | - | - |
| `whole` | Everything asked for fit in the response. | Nothing is needed. |
| `sections_only` | The text is longer than `max_characters`, so the outline came. | Read a section by its id. |
| `matching_sections` | The text is too long, and the sections with your highlights came. | Read the other sections by id. |
| `unchanged` | The source still has the text of your `baseline_fingerprint`. | Nothing is needed. |
| `pages_failed` | Some pages of a document could not be read, and `pages.failed_pages` names them. | No next step is named, so a report says which pages were not read. |
| `time_capped` | A document at an address was not finished in time. | Send the address to `upload_contents`, which reads it as a job. |
| `cost_capped` | The fetch stopped at `max_cost`, at the key's limit for one call, or at the balance, and `message` says which. | Set a higher `max_cost`, or have the owner of the account add funds or raise the key's limit. |
| `challenge_served` | A bot challenge was where the page should be. | Try later, or have a person save the page and upload it. |
| `not_found` | The site says the page does not exist. | The same request will not work. |
| `region_restricted` | The page is not offered in the country it was read from. | Set another `subject_country`. |
| `no_history` | No archive has a copy on or before the day you asked for. | The same day will not work. |
| `robots_disallowed` | The site's robots file forbids the fetch. | The same request will not work. |
| `sign_in_needed` | A sign-in page was where the page should be. | A person signs in, saves the page, and uploads it. |
| `paywalled` | A purchase wall was where the page should be. | A person decides. |

## An outcome says what came, not whether it is the right page

`whole` means that everything you asked for fit. It does not mean that the page is what its address promises. A wall is recognized by its signs, so an error page that is sent as a normal page, or a wall with no known sign, comes back as content. A page that declares its content as not free has the notice `paywall_declared`, whatever came.

## A search has outcomes too

A search as a whole has an outcome, and so has each datasource in its receipt. Their reasons include these 5.

| `reason` | What happened in the search |
| - | - |
| `candidates` | One or more results came. |
| `none` | Nothing matched, and the receipt says what was searched. |
| `sources_missing` | One datasource or one wording gave no list, and the others did. |
| `rerank_missing` | The time ran out or a limit on cost was reached before the ranking, so the results are in the merged order of the datasources. |
| `fetches_missing` | Some of the fetches inside the search did not finish. |

## A fetch that did not work costs nothing

A fetch that failed, was refused, or needs a person is not charged. A partial fetch is charged for the part that came.

## Notices come before the content

A notice is a fact that changes how the response should be read. It is not an error, and the call succeeded. `notices` is a list, and these notices bear on how far to trust the text.

| Notice | What to know before you read the content |
| - | - |
| `conversion_mismatch` | A check of the text against the page did not pass, so read the content with care. |
| `not_settled` | The page was still changing when `wait_seconds` ran out, and was read as it was then. |
| `ad_blocker_failed` | The advertising filter did not run, so advertising can be among the content. |
| `unread_region` | A part of the main content could not be read as text. |
| `no_main_content` | No main content was found, so the whole page came. |
| `paywall_declared` | The page declares its content as not free, so what came can be a teaser. |
| `redirected` | The fetch ended at another address than the one you sent. |
| `recognition_uncertain` | Some scanned pages were read with low confidence, and the notice names them. |
| `tracked_changes` | The document has tracked changes, which are shown as accepted. |
| `marks_not_read` | The document has no structure for its formatting, so bold and struck text could not be read. |

Other notices say that something was cut to fit a size limit, such as `highlights_cut` or `total_characters_cut`, and each names the size limit.

A notice that belongs to a record is stored with it. It comes back first on every later read of that record, marked with `held` set to `true`, so a second agent that reads the record learns what the first one was told.


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