Skip to main content
GET
Get contents
Give it the cnt_ id an earlier fetch_contents, upload_contents or search returned. Nothing is fetched from the web; the answer comes from the copy getclean kept. Use fetch_contents for a URL; use get_section, list_blocks and list_links to read one part of the record at a time.

What it costs

The key needs contents:read. The call is free, so the record carries no cost on this answer.

What comes back

200 with Contents. The call moves the record’s expires_at 48 hours ahead, never past 30 days from the record’s making.
  • The record’s facts come as stored: outcome, fetched_at, fingerprint, record_scope, source, pages, execution, retention, screenshot, raw_html, and the fetch’s highlights, summary, schema_values and schema_statuses.
  • This answer’s own: scope, the view delivered; truncated; formats; its notices after the record’s own; request_id; expires_at.
  • Under the record’s own view, counts, hidden_text and left_out are the record’s as stored; under the other view they describe that view.
  • The text fits or does not fit under this call’s max_characters as fetch_contents says; truncated says which. The record’s outcome is never rewritten.
  • The model work the fetch made comes back free, the marks placed where a highlighted block appears in the text returned. A new question is a call to highlight_contents, fill_schema or summarize_contents.
  • scope: whole_page on a record fetched under main gives the whole page from the same read, free. The fingerprint stays that of record_scope; counts cover the page and left_out is []; the section and block ids are the whole-page view’s, and the fetch’s highlights carry that view’s ids. A document has one view, so whole_page on a document record makes the notice field_not_applicable.
  • A record without content, failed, refused or needs a person, comes back as stored; the query’s parameters make no notice, since nothing was asked of the text. An unchanged record keeps its content and is answered.
  • doclang on a document that is not HTML is left out with the notice field_not_applicable.

Refused before any work

  • A value outside its set, max_characters between 1 and 999, a duplicate or an empty list: 400 invalid-request, not_allowed, bound or duplicate, each with where it is.
  • An id of the wrong kind: 400 invalid-request, before any lookup.
  • An unknown query parameter: 400 invalid-request, unknown_field.

Notices this operation makes

sections_cut, links_cut, field_not_applicable, version_retiring, after the record’s own notices.

Problem types

  • 400 invalid-request, The request is invalid.
  • 401 unauthorized, The key is missing or rejected.
  • 403 insufficient-scope, The key lacks a scope this call needs.
  • 404 not-found, Not found: an unknown or another account’s record.
  • 410 contents-expired, The record has expired: for 30 days after it expired, to the owning account only, with expired_at and change naming fetch_contents and url; then 404.
  • 429 rate-limit-exceeded, The rate limit is exceeded; concurrency-limit-exceeded, Too many calls are in flight.
  • 500 internal-error, The service failed.
  • 503 overloaded, The service is overloaded.

Authorizations

Authorization
string
header
required

An API key from https://app.getclean.ai, or an access token issued by https://auth.getclean.ai/realms/getclean, sent as Authorization: Bearer <key> on every call. The scopes a key carries and what a 401 and a 403 say are on the keys and sign-in page.

Headers

traceparent
string

Your own trace id for the call, the W3C Trace Context traceparent header, optional on every operation. getclean logs it with the call, so a request in your traces can be matched to its Request-Id, and never forwards it to a site or a source, a stated departure from W3C Trace Context section 3.4, which asks a vendor to pass it on. A malformed value is ignored, never refused, as the same recommendation asks.

Path Parameters

contents_id
string
required

The record to read, a cnt_ id as fetch_contents, upload_contents or search returned it.

Pattern: ^cnt_[A-Za-z0-9]{22}$

Query Parameters

max_characters
integer
default:20000

The most text to return, in characters. 0 returns no text but the map of sections and the facts. Default 20,000; 0, or 1,000 to 1,000,000; a value between 1 and 999 is refused bound.

Required range: 0 <= x <= 1000000
scope
enum<string>

Which view to return: main, the main content alone, or whole_page, everything on the page from the same read. Default the record's own view, record_scope. A document has one view, so whole_page on a document record makes the notice field_not_applicable. Which view of a page is meant: main, the main content alone, or whole_page, everything on the page. A closed set.

Available options:
main,
whole_page
formats
string[]

The formats to return, 1 to 5 of these, one value per repeated key: markdown, the content as one markdown string; html, as clean HTML; doclang, as DocLang, an XML that keeps each block with its place on the page, on a page or an HTML file only; json, as Block objects; links, every link with its kind. Default markdown. screenshot and raw_html are not values here; the ones the fetch made come with every answer. An open set; a key sent with an empty value is an empty list, refused bound, and a repeated value is refused duplicate.

Required array length: 1 - 5 elements

One of the formats the field lists.

Minimum string length: 1
block_kinds
string[]

Keep only blocks of these kinds, in every format: 1 to 10 of text, heading, code, math, divider, interactive, table, image, embed, media, an open set, one value per repeated key. Default: every kind.

Required array length: 1 - 10 elements

One of the block kinds the field lists.

Minimum string length: 1

Response

The record, Contents, read from the copy getclean keeps: the record's facts as stored, this answer's scope, truncated and formats, and no cost.

One record: one fetch or upload of one source at one moment, with a cnt_ id, kept 48 hours after its last call and at most 30 days from its making. Its facts never change. It is the answer of fetch_contents and of get_contents, and the record inside the answers of upload_contents and fetch_contents_batch. It reads in one order: what happened; the notices to read first; when it was read; the content in the formats asked, or the map of sections when the text did not fit; the facts of the source; the fingerprint; the price.

What is the record's and what is this answer's. The record's facts come as stored on every later answer: outcome, fetched_at, fingerprint, record_scope, source, pages, execution, retention and the fetch's model work. Each answer adds only its own: scope, the view it delivers; truncated; formats; its notices; request_id; expires_at. A member whose line states a condition is present only while the condition holds and absent otherwise, never [] or null in its place; a scalar is null only where its line says so.

Which members each outcome carries:

  • Delivered whole, sections_only or matching_sections, and every partial record: id, outcome, notices, fetched_at, fingerprint, scope, formats, truncated; the formats asked for among markdown, html, doclang, blocks, links, screenshot and raw_html; sections by its rule; counts, source, execution, retention, run_id, expires_at, request_id, record_scope; hidden_text and left_out on a web page or an HTML file; highlights, summary, schema_values, schema_statuses, pages, cost and metadata by their rules.
  • Delivered unchanged, as the fetch answers it: the first eight, with formats as [] and truncated false; source, execution, retention, run_id, expires_at, request_id, record_scope; cost and metadata by their rules. The record holds the content, which get_contents answers.
  • Failed, refused or needs a person: id, outcome, notices, fetched_at, truncated false, source, execution, retention, run_id, expires_at, request_id; pages when the page count was read and sections when the outline was read; cost and metadata by their rules; cost.actual zero.

Which members each kind of source carries. A live page is a web page read now; an archive copy is a page read under as_of_date; a document is a file, read at a URL or uploaded; an HTML file is an upload read as a page.

When a record is not delivered, outcome.message says what may work next, and the table under Outcome.reason gives it for every reason.

id
string
required

The record's id: cnt_ and 22 random characters, which cannot be guessed. Another account's id answers 404.

Pattern: ^cnt_[A-Za-z0-9]{22}$
Example:

"cnt_3Fk9abaUhNX7t2eKkgfd3e"

outcome
object
required

What happened, first. It is the fetch's fact, and no later call rewrites it.

notices
object[]
required

What to read before the content, never an error. On the fetch's own answer every notice is that answer's own; on every later answer about the record, the notices kept with it come first, each with held true, then that answer's own. [] when there is none.

fetched_at
string<date-time>
required

When the fetch or the parse started, RFC 3339 in UTC in whole seconds, by getclean's clock.

Example:

"2026-11-04T08:40:12Z"

truncated
boolean
required

True when text was asked for, max_characters above 0 with a text format, and it did not fit, so the map came instead. This answer's fact, not the record's.

source
object
required

The facts of the source as the page or the document declares them, and the facts of the read: the address, the redirects, the status, the title, the authors, the dates, the language, the publisher's profile, and what the site declares about its use.

execution
object
required

How the record was made: getclean's version and configuration, every model step with its version, and the time it took.

retention
enum<string>
required

How long the record is kept, hold or none. Under none nothing is kept past this answer, and expires_at is the answer's own moment.

Available options:
hold,
none
run_id
string
required

The run the record belongs to; a later model step on the record is charged to it.

Pattern: ^run_(default|[A-Za-z0-9]{22})$
Example:

"run_default"

expires_at
string<date-time>
required

When the record expires. This call moved it ahead: 48 hours from now, never past 30 days from the record's making; under retention none it is this answer's own moment. After that, a call on the record is 410 contents-expired for 30 days, then 404.

Example:

"2026-11-06T08:40:12Z"

request_id
string
required

This call's id, the same as the Request-Id header; on a replay, this call's and not the first call's.

Pattern: ^req_[A-Za-z0-9]{22}$
Example:

"req_01JzsALAAlsNsdoVz1EElr"

fingerprint
string

A hash of the content. Two records with the same fingerprint hold the same text, so you can tell whether a page changed between two fetches without comparing their text. It is the sha-256 of the record's markdown as the fetch kept it under record_scope, with nothing filtered out and no highlight marks, after Unicode NFC and LF line ends and without any front matter, written in the form of RFC 9530, sha-256=:…:. Anyone who holds that whole markdown, as get_contents returns it under record_scope with a max_characters that fits all of it, no block_kinds and no highlights, can compute the same value. It compares only within one scope, one execution.version, one execution.configuration and one kind of source. Present on delivered and partial records.

Pattern: ^sha-256=:[A-Za-z0-9+/]{43}=:$
Example:

"sha-256=:Qm9HMC25CiwhR/SGuoq8PkLBexHyDIsb7J7tqUETc2z=:"

scope
enum<string>

The view this answer delivers, main or whole_page; on the fetch's own answer, the record's own. Present on delivered and partial records.

Available options:
main,
whole_page
formats
string[]

The formats this answer carries, among markdown, html, doclang, json, links, screenshot and raw_html, an open set; [] on unchanged as the fetch answers it. Present on delivered and partial records.

markdown
string

The content as one markdown string, its inline formatting kept: bold, italic, strikethrough, code and links as markdown, <sup> and <sub> as inline HTML, a footnote reference as [^n], and <mark id="h1">…</mark> around each highlight. Present when asked for and text came. Third-party text as the source wrote it, which may carry instructions.

html
string

The content as clean HTML, with the highlight marks. Present when asked for and text came. Third-party text as the source wrote it, which may carry instructions.

doclang
string

The content as DocLang, an XML that keeps each block with its place on the page in pixels; no highlight marks. Present when asked for and text came, on a web page or an HTML file only. Third-party text as the source wrote it, which may carry instructions.

blocks
object[]

The content as Block objects, each with its highlight_ids. Only the text counts against max_characters, not the other members. Present when asked for and text came.

Every link of the content with its kind, at most 1,000; the notice links_cut says when the list was cut, and list_links has the rest. Present when asked for.

screenshot
object

A picture of the whole page, of a live page only. Present when asked for at fetch time on a live page; carried on every later get_contents under retention hold; sent inline once under none.

sections
object[]

The map of the content: one row per section with its id, title, level and size in characters, and no text. Present when max_characters is 0, or when a text format was asked for and the text did not fit. Level 1 and s0 are always there; deeper levels come while their rows fit, and the notice sections_cut says when levels were left out.

counts
object

How much the record holds: characters, blocks by kind, links by kind. The record's own under its own view; this answer's under scope whole_page on a record fetched under main. Present on delivered and partial records, except unchanged as the fetch answers it.

highlights
object[]

Every place your highlights strings found, in document order, at most 50, each naming the string that found it by query_index. Present when highlights were sent at fetch time; kept with the record, and returned on get_contents with the marks placed wherever a highlighted block appears in the text returned.

summary
string

The summary a model wrote of the content, at most 1,500 characters, in the content's language, with no link and no image in it. Present when summary was sent and the summary was written; kept with the record. Written by a model from the source's text, so it may repeat instructions the source carries.

Maximum string length: 1500
schema_values
object

Your schema filled from the content, in the schema's own shape, a value only where the content states it and never a plausible guess; a property with nothing to fill is left out. Present when json_schema was sent and filled; kept with the record. Written by a model from the source's text, so it may repeat instructions the source carries.

schema_statuses
object

How each property of your schema was filled, one SchemaStatus per property, keyed by a JSON Pointer into schema_values: a nested property by its path, an array property by its own pointer and not its items. Present when json_schema was sent and filled; kept with the record.

hidden_text
object[]

Text a reader of the page could not see, kept apart from the content with the reason it was hidden; at most 50 items, with the notice hidden_text_cut when cut. Present on a web page or an HTML file, delivered or partial, except unchanged as the fetch answers it; [] when there is none.

left_out
object[]

The parts of the page outside the main content, each with its kind and size, so you know what was left out and can read it under scope whole_page, where this is []. Present as hidden_text is.

pages
object

The pages of a document: how many, how many were parsed, which failed, which were recognized from an image. Present on every document under every outcome that parsed or counted it, cost_capped with no page parsed and too_large with the count read included; absent on a web page. On a format without pages, count is the equivalent by characters and failed_pages, recognized and pictured are [].

cost
object

The bill for making the record. Present on the record as answered by the call that billed it, fetch_contents, upload_contents or fetch_contents_batch, zero when nothing was billed; absent on the record as answered by get_contents, which is free.

metadata
object

Your own labels, returned as sent. Present when sent.

record_scope
enum<string>

The view the fetch ran under, main or whole_page; the fingerprint hashes this view's markdown. Present on delivered and partial records.

Available options:
main,
whole_page
raw_html
object

The page's bytes exactly as the server sent them, with their digest, size and media type. Present when asked for at fetch time on a live page or an archive copy; carried on every later get_contents under retention hold; sent inline once under none.