Get contents
Read a record you already have, free: the same copy in any format, at any size, under either view, with the model work the fetch made.
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 needscontents: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’shighlights,summary,schema_valuesandschema_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_textandleft_outare 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_charactersasfetch_contentssays;truncatedsays which. The record’soutcomeis 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_schemaorsummarize_contents. scope: whole_pageon a record fetched undermaingives the whole page from the same read, free. Thefingerprintstays that ofrecord_scope;countscover the page andleft_outis[]; 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, sowhole_pageon a document record makes the noticefield_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
unchangedrecord keeps its content and is answered. doclangon a document that is not HTML is left out with the noticefield_not_applicable.
Refused before any work
- A value outside its set,
max_charactersbetween 1 and 999, a duplicate or an empty list:400 invalid-request,not_allowed,boundorduplicate, 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, withexpired_atandchangenamingfetch_contentsandurl; then404. - 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
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
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
Query Parameters
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.
main, whole_page 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.
1 - 5 elementsOne of the formats the field lists.
1Keep 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.
1 - 10 elementsOne of the block kinds the field lists.
1Response
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_onlyormatching_sections, and every partial record:id,outcome,notices,fetched_at,fingerprint,scope,formats,truncated; the formats asked for amongmarkdown,html,doclang,blocks,links,screenshotandraw_html;sectionsby its rule;counts,source,execution,retention,run_id,expires_at,request_id,record_scope;hidden_textandleft_outon a web page or an HTML file;highlights,summary,schema_values,schema_statuses,pages,costandmetadataby their rules. - Delivered
unchanged, as the fetch answers it: the first eight, withformatsas[]andtruncatedfalse;source,execution,retention,run_id,expires_at,request_id,record_scope;costandmetadataby their rules. The record holds the content, whichget_contentsanswers. - Failed, refused or needs a person:
id,outcome,notices,fetched_at,truncatedfalse,source,execution,retention,run_id,expires_at,request_id;pageswhen the page count was read andsectionswhen the outline was read;costandmetadataby their rules;cost.actualzero.
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.
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.
"2026-11-06T08:40:12Z"
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.
^sha-256=:[A-Za-z0-9+/]{43}=:$"sha-256=:Qm9HMC25CiwhR/SGuoq8PkLBexHyDIsb7J7tqUETc2z=:"
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.
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.
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.
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.
1500Your 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.
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.
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 [].