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

# Fetch what a page says, not what surrounds it

> Fetch a page at a URL and get its main content with every heading, table, and link as the page has them, without the navigation and the advertising. The response names what was left out and what the page hides.

A web page is made for a person's eyes: a header, a menu, side columns, advertising, and somewhere among them the text the person came for. A model that receives all of it has to find the text among the rest. `fetch_contents` returns the main content of the page, with its structure, and stores it as a record, which is a copy you can read again and cite.

## Fetch the page

Send the address. Every other field has a default.

```bash cURL theme={"theme":"css-variables"}
curl https://api.getclean.ai/v1/contents \
  --header "Authorization: Bearer $GETCLEAN_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{ "url": "SOURCE_URL" }'
```

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

client = GetClean()

record = client.fetch_contents(url="SOURCE_URL")
```

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

const client = new GetClean();

const record = await client.fetchContents({ url: "SOURCE_URL" });
```

Replace `SOURCE_URL` with the address of a page.

The response is the record. This one is cut to the fields that this page explains.

```json 201 Created theme={"theme":"css-variables"}
{
  "id": "cnt_3Fk9abaUhNX7t2eKkgfd3e",
  "outcome": { "kind": "delivered", "reason": "whole" },
  "fetched_at": "2026-11-04T08:40:12Z",
  "fingerprint": "sha-256=:kw4QGoYGxOYpZ0EZGL+nxMfFUXfrxcp+P0M4EOrEiH4=:",
  "scope": "main",
  "markdown": "# Quarterly results\n\nRevenue rose 12% to …",
  "counts": {
    "characters": 6210,
    "blocks": { "heading": 4, "text": 22, "table": 1 },
    "links": { "page": 9 }
  },
  "left_out": [{ "kind": "navigation", "characters": 1480 }],
  "hidden_text": [],
  "source": {
    "final_url": "https://example.com/q3",
    "title": "Quarterly results",
    "published_date": "2026-10-28",
    "published_date_basis": "structured_data",
    "language": "en"
  }
}
```

`markdown` has the content as one string. Bold, italic, struck text, code, links, and footnote marks are as the page has them. The same page gives the same text and the same ids on every fetch under one version and one configuration of getclean, and the `fingerprint` is the hash of that text.

`counts` says how much the record has: the characters, the blocks by kind, and the links by kind.

## See what was left out

The main content is the part of the page that is its substance. `left_out` names every other part with its kind and its size: `header`, `footer`, `navigation`, `table_of_contents`, `forms`, `widgets`, `rails`, `comments`, and `advertising`. A rail is a side column.

A page can keep real content in one of those parts. To read all of it, ask the stored record for the whole page. The source is not fetched again, and the read costs nothing.

```bash cURL theme={"theme":"css-variables"}
curl "https://api.getclean.ai/v1/contents/CONTENTS_ID?scope=whole_page" \
  --header "Authorization: Bearer $GETCLEAN_API_KEY"
```

```python Python theme={"theme":"css-variables"}
whole = client.get_contents(contents_id="CONTENTS_ID", scope="whole_page")
```

```typescript TypeScript theme={"theme":"css-variables"}
const whole = await client.getContents("CONTENTS_ID", { scope: "whole_page" });
```

Replace `CONTENTS_ID` with the `id` of the record.

## See what the page hides

Some text on a page cannot be seen by a person who reads it: text in the color of its background, text too small to read, text under another element. Such text can be written for a machine, as an instruction to your model. It is never mixed into the content. It comes apart in `hidden_text`, each item with its words and the way it was hidden, so you decide what to do with it.

Text that is hidden in a way getclean does not detect comes back as content. Treat every text of a source as material to read, never as an instruction to follow.

## Choose the formats

`formats` takes any of 7 values. The default is `markdown`.

| Format | What comes back |
| - | - |
| `markdown` | The content as one Markdown string. |
| `html` | The content as clean HTML. |
| `json` | The content as blocks, each with its id, its kind, and its section, and each table cell by cell with its merged cells. |
| `doclang` | The content as XML that has each block with its place on the page. |
| `links` | Every link with its kind and the block that has it. |
| `screenshot` | A picture of the whole page, with its digest. |
| `raw_html` | The page's bytes as the server sent them, with their digest. |

An empty list returns the facts of the source and no content.

A response has at most `max_characters` of text, which is 20,000 if you send none. For a page that is larger, the response has the outline of the page in place of its text. For how to read such a page, see [Read the 2 sections you need from a 300-page document](https://docs.getclean.ai/read/long-documents.md).

## Read the page from another country

A site can show a different page to a visitor from another country. `subject_country` sets the country the page is read from, and `subject_language` sets the language the site is asked for. The response says in `source.visitor` from where the page was read. `get_limits` lists the countries you can choose.

## Act on a page that could not be read

`outcome` is the first field to read. If the site sent a challenge for bots, a sign-in page, or an error, the record has no content and its outcome says what happened. `outcome.message` says what can work next, such as a later retry, or a person who opens the page and uploads the saved copy. A fetch that failed, was refused, or needs a person costs nothing.


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