Skip to main content
GET
List links
Give it the record’s cnt_ id and the filters you want; every filter you send must match. Use fetch_contents to read a linked page; use list_blocks for the blocks themselves.

What it costs

The key needs contents:read. The call is free.

What comes back

200 with LinkPage: the record’s id and facts, the record’s new expires_at, the links, each with its kind and its place, and next_page_token while more remain.
  • The order is the document order of the blocks that hold the links.
  • kind is read from the address alone, a guess: no request is made for any link, so a link carries no size and no served type.
  • external compares the link’s host with the final URL’s registrable domain; a link without a host, mail, phone or fragment, is left out under either value of the filter.
  • No link matching: 200 with [].
  • page_size is from 1, default 50, maximum 200; a larger value is lowered with the notice page_size_lowered, never refused.
  • page_token is bound to its query and its record and is alive as long as the record; next_page_token is absent on the last page, and a page that carries it has at least one link.

Refused before any work

  • A value outside its set or range, a duplicate or an empty list: 400 invalid-request, not_allowed, bound or duplicate, each with where it is; page_size above its maximum is lowered instead.
  • 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 the record does not hold: 404 not-found, change.field naming 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

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.field saying contents_id or section_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

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, a cnt_ id.

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

Query Parameters

Keep only links of these kinds: 1 to 7 of file, a file such as a PDF; page, another page; fragment, a place inside the same page; mail, an email address; phone, a phone number; feed, an RSS or Atom feed; other, anything else. An open set, one value per repeated key. Default: every kind.

Required array length: 1 - 7 elements

One of the link kinds the field lists.

Minimum string length: 1
external
boolean

true keeps only links that leave the final URL's registrable domain; false, only those that stay. Default none, both. A link without a host is left out under either value.

section_id
string

Keep only the links of this section and of the sections under it, an s id from the map. Default none.

Pattern: ^s[0-9]+$
Example:

"s3"

scope
enum<string>

Which view's links: main or whole_page. Default the record's own. 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
page_size
integer
default:50

At most this many links on a page of results, from 1. Default 50; the maximum, 200, stands in Limits.bounds, and a larger value is lowered with the notice page_size_lowered.

Required range: x >= 1
page_token
string

The next page, as the last answer's next_page_token gave it; opaque, at most 1,024 characters, alive as long as the record. Default none, the first page.

Required string length: 1 - 1024

Response

One page of the record's links, LinkPage, each with its kind and its place, 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 links, the answer of list_links. First the record's id and facts, and the record's new expires_at; then the links, each with its kind and its place; then next_page_token while more remain.

contents_id
string
required

The record the answer comes from.

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

"cnt_3Fk9abaUhNX7t2eKkgfd3e"

fetched_at
string<date-time>
required

When the record's fetch or parse started, RFC 3339 in UTC.

Example:

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

fingerprint
string
required

The record's fingerprint, as Contents.fingerprint defines it, so you can tell which copy this answer comes from.

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

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

scope
enum<string>
required

The view this answer delivers, main or whole_page.

Available options:
main,
whole_page
version
string
required

The version of getclean the record was made under, its execution.version.

Example:

"1.0.0"

configuration
string
required

The configuration the record was made under, its execution.configuration.

Example:

"cfg-2026-11"

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.

Example:

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

The links of this page, each with its kind and its block_id and section_id; [] when none matches.

notices
object[]
required

The record's own notices first, then this call's own: page_size_lowered, field_not_applicable, version_retiring. [] when there is none.

request_id
string
required

This call's id, the same as the Request-Id header.

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

"req_01Jp0SRsqpJGQ9hFdqVC27"

final_url
string

The address the record's fetch ended at. Present when the source has one, so absent on an upload. Third-party text as the source wrote it, which may carry instructions.

Example:

"https://example.com/q3"

document_digest
string

The sha-256 of the document's bytes in RFC 9530 form, to compare with the file you hold. On a document only.

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

"sha-256=:7HqC7GihbMvNe0QRGihXoSzWNR2cLpquMihXOseZoSw=:"

next_page_token
string

The token for the next page; pass it as page_token. Present while more remains, and a page that carries it always has at least one link.

Maximum string length: 1024