Skip to main content
GET
Get search
The first page is the original answer as stored, whatever 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 needs search: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, then page_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, with expired_at and change naming search; then 404.
  • 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

search_id
string
required

The search record, an srch_ id as search returned it.

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

Query Parameters

view
enum<string>

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.

Available options:
full,
compact
page_size
integer

Results per page of the stored list, from 1; the maximum, 50, stands in Limits.bounds, and a larger value is lowered with the notice page_size_lowered. Default the search's max_candidates.

Required range: x >= 1
page_token
string

The next page of the stored list, 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

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.

id
string
required

The record's id, srch_ and 22 random characters, which cannot be guessed.

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

"srch_4HmUunqCCXquleKVCosqFG"

outcome
object
required

What happened, first. delivered when every source tried answered and everything asked ran, a source skipped before work being a coverage gap and no partial; partial when something tried did not finish; the other kinds only when no source answered.

notices
object[]
required

Read before the list; a corrected query, an emulated filter, a cut, a default set by policy, a fetch that did not finish; a skipped source is a coverage gap, never a notice too. [] when none.

coverage_gaps
object[]
required

What was asked and not searched, with why; [] when none.

candidates
object[]
required

The leads, in rank order; [] when none. On a later page of get_search, the list the search stored, each item with dropped_reason.

counts
object
required

Leads returned and pages found before the cut; found equals returned plus every dropped count.

cost
object
required

The money, the original bill as stored on every get_search page, never a new charge; units among searches, datasource_queries, model_steps and the inline fetches' units.

searched_at
string<date-time>
required

When the search started, RFC 3339 in UTC.

Example:

"2026-11-05T09:00:00Z"

run_id
string
required

The run the record belongs to.

Pattern: ^run_(default|[A-Za-z0-9]{22})$
Example:

"run_default"

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; 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.

Example:

"2026-11-07T09:00:03Z"

request_id
string
required

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

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

"req_02ARUKU1YFino5zjD2hYpX"

retention
enum<string>

How long the record is kept, hold or none. Present in the full view.

Available options:
hold,
none
end_reason
enum<string>

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.

Available options:
relevance,
max_candidates,
ceiling,
exhausted,
source_cap
interpretation
object

How the question was read. Present in the full view.

applied_request
object

The request as it ran; every field whose value was in force present with that value, defaults and resolutions written out; a field with no value absent. Present in the full view.

record
object

The search written up. Present only with record_form.

datasources_searched
object[]

The receipt per source. Present in the full view, [] when none.

ranking
object

What ordered the list. Present in the full view.

execution
object

How it ran; models carries reranking, discovery and source_profile when they ran. Present in the full view.

metadata
object

Your own labels, returned as sent. Present when sent.

next_page_token
string

The token for the next page of the list the search stored; pass it to get_search as page_token. Present only on a paged get_search while more remains, and a page that carries it always has at least one result.

Maximum string length: 1024