Get search
Read a search you already have, free: the first page as it was answered, and behind it the full list the search stored, including the results it dropped and why. Nothing is searched again and nothing is charged; only the record’s expires_at moves.
page_size: its members and the notices kept with it. A notice of the original answer that was not kept does not come back, and dropped_reason is absent on every candidate. A later page is the stored list in rank order, and every item on it carries dropped_reason. Every other member comes as stored; request_id is this call’s, and expires_at is the record’s new one. next_page_token comes while more remain. fetch_contents reads a candidate by its URL.
What it costs
The key needssearch:read. The call is free. The answer is 200 with Search; the call moves the record’s expires_at 48 hours ahead.
Refused before any work
A value outside its set or range,page_size above its maximum excepted, which is lowered with the notice page_size_lowered: 400 invalid-request, not_allowed or bound, each with where it is. An id of the wrong kind: 400 invalid-request, before any lookup. A token of another search or another query: 400 page-token-invalid. An unknown query parameter: 400 invalid-request, unknown_field.
Notices this operation makes
The search’s own notices first, thenpage_size_lowered and version_retiring.
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: an unknown or another account’s search. - 410
search-expired, The search has expired: for 30 days after it expired, to the owning account only, withexpired_atandchangenamingsearch; 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
How much of the record comes back: full, every member, or compact, the smaller form the Search schema lists. Default full; the MCP server always asks for compact.
How much of a search record comes back: full, every member, or compact, the smaller form the Search schema lists. A closed set.
full, compact Response
The search record as stored: the first page as it was answered, or a later page of the stored list with dropped_reason on every item; next_page_token while more remain.
One search record, srch_, kept 48 hours after its last call and at most 30 days from its making. It keeps the results and the receipt as they were, and get_search pages the list the search stored and never searches again or charges. It reads in one order: the outcome; the notices and the coverage gaps, read before the list; the leads in rank order with the facts of each; the counts, which describe the search and never a page; how the question was read and the request as it ran; the receipt per source; what ordered the list; how it ran; the money.
Under view compact only these members come, each whole: id, outcome, notices, coverage_gaps, counts, end_reason, cost, searched_at, run_id, expires_at, request_id, next_page_token on a paged get_search, and candidates, each with id, url, title, published_date, access, relevance_score, source_profile, fetch_cost, dropped_reason on a paged item, excerpts holding the first excerpt only, and contents when fetched. Every member outside that list is optional in this schema and always present in the full view.
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 search-expired for 30 days, then 404.
"2026-11-07T09:00:03Z"
Why the list ended: relevance, the next candidate fell under the ranking model's cut-off; max_candidates, the cap on leads was reached; ceiling, the money ran out; exhausted, every source gave all it had; source_cap, every source reached max_per_datasource. A closed set. Present on delivered and partial, absent on the other kinds.
relevance, max_candidates, ceiling, exhausted, source_cap