Highlight contents
Find words or questions in a record you already have and mark where they stand, without fetching again. You get each place with its section and block ids, and, when you ask for text, the sections that hold them, marked. A string found verbatim is free; one a model has to judge costs one model step, once per call however many strings needed it.
What it costs
The key needscontents:read, and contents:model unless deterministic_only is true, since a string may need a model. Free when every string was found verbatim; 1 model_steps when any string had to be judged, once per call. The answer is 200 with ContentsHighlights; the call moves the record’s expires_at 48 hours ahead.
The idempotency key
Idempotency-Key is optional here. A billed answer is stored 24 hours and replayed under the same key and body with this call’s request_id and replayed true on cost; a free answer is not stored; the same key in flight is 409 idempotency-key-in-flight; the same key with another body 422 idempotency-key-reused.
Each string
Foundexact when its words stand in one block, after Unicode normalization and whitespace collapse, case kept; near when they stand there after case folding, with ellipses and the punctuation at the ends of words removed, pieces in order, the dotted and dotless i of Turkic scripts folded to one; judged when not found verbatim and a model picked the blocks that bear on it; not found, and nothing bears on it, or deterministic_only: the notice highlight_not_found, one per string. Every occurrence is a highlight, in document order, at most 50, past which the notice highlights_cut comes.
What comes back
max_characters: 0: the highlights list with ids and places, no text, formats echoed []. Above 0: the sections holding highlights, in document order while they fit; a section larger than what remains comes cut at a block edge with its highlighted blocks inside; truncated true when the text returned is not the whole content, false when the holding sections are the whole and fit or when nothing was found; the rest through get_section or list_blocks with block_ids. The marks are <mark id="h1">…</mark> in markdown and html and highlight_ids on blocks; the record’s own text never changes.
Verbatim only
Underdeterministic_only, a key whose policy forbids model work, or a ceiling below a model step, the strings are matched verbatim only; this operation is never refused for the key’s policy or the ceiling, an explicit deterministic_only: false under such a key excepted, policy-limit-exceeded as on the fetch; under a ceiling below the step the miss carries the notice cost_cut or budget_cut naming highlights. A model step that fails or passes its bound, bounds.contents.model_step_seconds, answers 200 with the verbatim results and the notice step_failed, not billed. scope: whole_page on a document record, or block_kinds that match no block, is the notice field_not_applicable; with no block to search nothing is found, nothing is judged, nothing billed.
Refused before any work
doclang, links, screenshot or raw_html in formats, or a value outside its set: invalid-field, not_allowed. highlights missing: required; an empty list: bound; a duplicate: duplicate. max_characters between 1 and 999, or any other bound passed: bound. An unknown field: unknown_field. A record that failed, was refused or needs a person: 409 record-without-content, change naming fetch_contents. Every violation of the body is reported at once in violations.
Notices this operation makes
The record’s own notices first, thenhighlight_not_found, highlights_cut, step_failed, cost_cut, budget_cut, default_set_by_policy, field_not_applicable, version_retiring.
Problem types
Never a money problem: when the money does not cover the model step, the strings are matched verbatim instead.- 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;policy-limit-exceeded, The key’s policy forbids this. - 404
not-found, Not found. - 409
record-without-content, The record has no content;idempotency-key-in-flight, The same request is still running. - 410
contents-expired, The record has expired. - 413
body-too-large, The body is too large. - 415
unsupported-media-type, The media type is not supported. - 422
invalid-field, A field is invalid;idempotency-key-reused, The idempotency key was reused with another body. - 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
One key per logical call, so a retry is never billed twice.
Optional on this operation; required on upload_contents, fetch_contents_batch and search_batch, where a duplicate would cost the most. The SDKs fill a fresh key when you give none and send the same key on every retry of that call; the command line and the MCP server do the same. Give your own key when your program retries across processes, so the second run finds the first answer.
The form: 1 to 255 visible ASCII characters, used exactly as sent, so a value written as a quoted Structured Field String keeps its quotes as part of the key. That is a stated departure from the IETF draft draft-ietf-httpapi-idempotency-key-header, revision 08, which is not yet a standard; this parameter documents the form in full.
What a repeated key does:
- The same key with the same body returns the first answer again, with this call's
request_id,expires_atas it stands andreplayedtrue on everycost. Nothing is billed again. - The same key while the first call still runs:
409 idempotency-key-in-flight, withRetry-After. - The same key with another body:
422 idempotency-key-reused.
Answers are stored for 24 hours, per account, for billed answers and running jobs only; a free answer is not stored. A call that may bill is kept in the store from its start, so a second call with its key meets the 409 while it runs.
1 - 255^[!-~]{1,255}$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.
Body
The request of highlight_contents. Every field is at the top level; an explicit null equals an absent field and gets the default. The object is closed; an unknown field is refused invalid-field, unknown_field.
Words or questions to find and mark; each string is one query, numbered by query_index in the answer. 1 to 5 strings, each 1 to 4,000 characters; an empty list is refused bound, a duplicate duplicate. Required.
1 - 5 elements1 - 4000Search and return only these blocks, 1 to 10 of text, heading, code, math, divider, interactive, table, image, embed, media; an open set. Default: every kind. When none matches, the notice field_not_applicable.
1 - 10 elementsOne of the block kinds the field lists.
1Response
The highlights found with their places, the holding sections marked when text was asked, the execution and the cost; a string not found is a notice, never an error.
The answer of highlight_contents: the record's id and facts, its new expires_at, the highlights found, the holding sections marked when text was asked, the execution and the cost.