Summarize contents
Have a model write a summary of a record you already have, at most 1,500 characters in the content’s language, from the copy getclean keeps. It is the same step as fetch_contents’s summary. Use highlight_contents to find words and fill_schema to fill fields.
What it costs
The key needscontents:model. The price is 1 model_steps. The answer is 200 with ContentsSummary; the call moves the record’s expires_at 48 hours ahead.
The idempotency key
Idempotency-Key is optional here. The 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; the same key in flight is 409 idempotency-key-in-flight; the same key with another body 422 idempotency-key-reused.
The summary
At most 1,500 characters, in the content’s language; no link and no image markup, any the model writes removed with the noticemodel_link_removed. The step is the whole call: a step that gave a bad answer is 502 gateway-error, a step that passed bounds.contents.model_step_seconds is 504 gateway-timeout, each retryable true and 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 read the summary is an empty string and the step is not billed.
Refused before any work
A value outside its set:invalid-field, not_allowed; a bound passed: bound; an unknown field: unknown_field. A key whose policy forbids model work, or whose cap is below a model step: 403 policy-limit-exceeded. A record that failed, was refused or needs a person: 409 record-without-content. Every violation of the body is reported at once in violations.
Notices this operation makes
The record’s own notices first, thenmodel_link_removed, field_not_applicable, version_retiring.
Problem types
The same asfill_schema.
- 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;credit-exhausted, The credit is exhausted;run-budget-exhausted, The run’s budget is exhausted;key-budget-exhausted, The key’s budget is exhausted. - 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. - 502
gateway-error, A step behind the service failed: the model step gave a bad answer; nothing was billed, and a retry may work. - 503
overloaded, The service is overloaded. - 504
gateway-timeout, A step behind the service timed out: the model step passed its time bound; nothing was billed, and a retry may work.
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 summarize_contents; every field optional, so {} summarizes the whole record. An explicit null equals an absent field and gets the default. The object is closed; an unknown field is refused invalid-field, unknown_field.
Summarize 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 and an empty summary.
1 - 10 elementsOne of the block kinds the field lists.
1Response
The summary, the execution and the cost.
The answer of summarize_contents: the record's id and facts, its new expires_at, the summary, the execution and the cost.