List blocks
List the blocks of a record, free: by kind, by section, by document page or by id, in document order, one page of results at a time.
cnt_ id and the filters you want; every filter you send must match. Each block is the record’s own Block: its id, kind, section, size and text, a table as its rows and spans, an image as its address and size. block_ids reads the blocks a highlight names by block_id, so you can read the whole block around a match. Use get_section for a section’s text in one piece; use get_contents for the whole record.
What it costs
The key needscontents:read. The call is free.
What comes back
200 with BlockPage: the record’s id and facts, the record’s new expires_at, the blocks, and next_page_token while more remain.
- A page of results ends before the block that would pass
max_characters, or atpage_sizeblocks, whichever comes first. - One block alone larger than
max_characterscomes whole, alone on its page, with the noticeblock_over_limit. highlight_idsis empty on every block here; the fetch’s highlights stand on the record.- No block matching:
200with[]. page_sizeis from 1, default 50, maximum 200; a larger value is lowered with the noticepage_size_lowered, never refused.page_tokenis bound to its query and its record and is alive as long as the record;next_page_tokenis absent on the last page, and a page that carries it has at least one block.
Refused before any work
- A value outside its set or range, a duplicate or an empty list:
400 invalid-request,not_allowed,boundorduplicate, each with where it is;page_sizeabove its maximum is lowered instead. page_numberon a record withoutpages:400 invalid-request,dependent; abovepages.count:400 invalid-request,bound.block_idswithstart_block_id:400 invalid-request,exclusive.- An id of the wrong kind:
400 invalid-request, before any lookup. - A token of another record or another query:
400 page-token-invalid. - A
section_id, ablock_idsvalue or astart_block_idthe record does not hold:404 not-found,change.fieldnaming it. - A record that failed, was refused or needs a person:
409 record-without-content. - An unknown query parameter:
400 invalid-request,unknown_field.
Notices this operation makes
block_over_limit, page_size_lowered, field_not_applicable, version_retiring, after the record’s own notices.
Problem types
- 400
invalid-request, The request is invalid;page-token-invalid, The page token 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,change.fieldsayingcontents_id,section_id,block_idsorstart_block_id. - 409
record-without-content, The record has no content. - 410
contents-expired, The record has expired. - 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.
Query Parameters
Keep only blocks of these kinds: 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
One page of the record's blocks in document order, BlockPage, with the record's id and facts and the record's new expires_at; next_page_token while more remain.
One page of a record's blocks in document order, the answer of list_blocks. First the record's id and facts, and the record's new expires_at; then the blocks; then next_page_token while more remain.