Skip to main content
POST
Search
Each result is a lead, the one page shown for a group of copies. The search is kept as a record, so its full list is read again free, and every cut, skip or change is named in the answer. Use contents to fetch the top leads in the same call, fetch_contents to read one by its URL, and list_datasources to see what can be searched.

What it costs

The key needs search:run, which covers everything a search does, the inline fetches and their model fields included, under the key’s policy. The price is 1 searches, plus 1 datasource_queries per source per wording that ran, plus 1 model_steps for the ranking and 1 for the choice of sources when they ran, plus the inline fetches priced as fetch_contents; a ranking cut by the deadline is not billed. The answer is 201 Created with Location naming the record, Search. The record is kept 48 hours after its last call and at most 30 days from its making; get_search pages the list the search stored and never searches again or charges. A search answers within wait_seconds; what did not finish is named in a partial outcome. There is no job, no stream and no webhook.

The idempotency key

Idempotency-Key is optional here. The same key with the same body returns the first answer again with this call’s request_id, the current expires_at and replayed true on every cost, no second charge; the same key in flight is 409 idempotency-key-in-flight; the same key with another body 422 idempotency-key-reused.

The default call

, {"query": "…"}: the web plus the groups a model picks; ten results from each source per wording; ranked by a model; ten leads with 600-character excerpts and their publisher profiles; moderate safe search; ten seconds; the full record; the key’s default run. Two model steps run by default, the ranking and the choice of sources when none are named, and a third identifies the publisher of a site getclean has not seen before; deterministic_only turns all three off.

Languages

A wording runs only on a source that covers its language. The web source takes every wording, each in its own language, searched from subject_country; a source in one language takes only wordings in that language; a source with one index per language takes each wording in its own index. A wording no source covers is a coverage gap, with the hint to add a wording in the source’s language. languages restricts the pages returned and is independent of this. Nothing is translated. With subject_identifiers and no query, each identifier’s value runs as a wording with origin identifier.

The inline fetch

contents.top of the leads are fetched in the same call, each as a contents record under fetch_contents’s rules.
  • It takes the search’s as_of_date, pinned_version, run_id, deterministic_only, retention and max_source_price, and its subject_country when that is a country getclean can read from, else the key’s default_exit with the notice field_not_applicable.
  • A lead found through a registered datasource is fetched under that datasource’s login, the one way to use a login on a fetch.
  • Its time comes out of the search’s wait_seconds, and it runs under what remains of the search’s ceiling at its turn. Each inline record carries its own cost.
  • At the deadline the record follows the contents’ rules. A fetch not started by the deadline makes no record, and the search ends partial, fetches_missing, with the notice fetch_not_finished.
  • contents.max_characters bounds one page. max_total_characters bounds the whole answer’s text, excerpts and fetched pages together: the excerpts first, cut from the last lead backwards when they alone pass it, then the fetched pages in rank order while they fit in what remains; a page that would pass it comes as sections_only; each cut makes the notice total_characters_cut.

Money

The ceiling is the lowest of the request’s max_cost, the key’s cap, the run’s budget, the key’s budget and the balance. When it cannot cover everything, the extras are cut in this order, each with the notice cost_cut: first each inline fetch’s own extras, in the order fetch_contents gives; then whole fetches, the search ending partial, fetches_missing; then the ranking, partial, rerank_missing; then the choice of sources; then the results taken per source. max_source_price is the most you allow for a datasource that charges per query, or for a site an inline fetch meets that asks a price; a source whose fee passes it is not searched, the coverage gap over_price. getclean pays no site for a page, so a page that asks a price ends payment_required.

Said, never refused

A hard filter a source cannot apply and cannot emulate: that source skipped, in coverage_gaps, the filter named. A wording in a language no source covers: coverage_gaps. source_independence, or independent in ranking_priorities, with no subject resolved: notice field_not_applicable. A window later than as_of_date, or a per-site cap on one allowed site: a notice. datasources absent under deterministic_only: the receipt shows web only. The inline fetch’s subject_country not in Limits.exits: notice field_not_applicable, the key’s default_exit used. max_source_price below a datasource’s fee: that source skipped, coverage gap over_price. An issuer sent with a scheme that takes none: notice field_not_applicable, the identifier runs by its scheme and value.

Fields that read alike

allowed_domains names sites that count, names with dots; datasources names places to search, names without. allowed_domains is hard, only these; ranking_preferred_domains is soft, these first and the rest still count. subject_country is where the search is made from; languages is what the pages are written in. published_from is the page’s own date; as_of_date the source’s state on a past day. pinned_version is getclean’s version; as_of_date the sources’ day. purpose is why, for the record and every model step; ranking_instructions is how to rank. ranking_priorities says which source facts go first; ranking_order how the rest is ordered. source_kinds is a filter that removes; ranking_priorities: official a preference that reorders. max_per_datasource is taken from each source before merging; ranking_max_per_domain is kept from each site in the answer. max_candidates is how many leads; contents.top how many of them to fetch. max_excerpt_characters is per lead, max_total_characters the whole answer, contents.max_characters one page fetched. Leaving the model fields out still runs the ranking and the choice of sources; deterministic_only turns every judging step off. view is how much of the record comes back; record_form the form the record is written in.

Refused before any work

, every violation of the body reported at once in violations:
  • Neither query nor subject_identifiers: invalid-field, required.
  • alternate_queries without query: dependent.
  • A scheme that needs an issuer, without one: dependent; an issuer no catalog entry lists for its scheme: not_allowed, with the listed codes in allowed_values.
  • published_within_days with published_from or published_until: exclusive; published_until before published_from: order; a date after today: bound.
  • A site in both allowed_domains and blocked_domains: exclusive; a ranking_preferred_domains value outside allowed_domains when that is set, or in blocked_domains: dependent.
  • A site name in datasources, or a datasource id in allowed_domains, blocked_domains or ranking_preferred_domains: misplaced, change.field naming the field it belongs in.
  • contents without top: required; top above 10: bound; top above max_candidates: order; contents with wait_seconds below 5, the least a fetch needs: order.
  • Under deterministic_only: ranking_instructions, and json_schema or summary inside contents: model-work-refused.
  • More than 20 wordings after OR splits: bound, with the count.
  • max_cost below the smallest call’s price, one searches and one datasource_queries: cost-exceeds-cap, with minimum_cap.
  • max_total_characters below max_excerpt_characters: order.
  • A source getclean cannot search: datasource-not-searchable. Every named source behind a login the key has not registered: 403 datasource-access-required; one such source among others is the coverage gap access_needed, and the rest run.
  • safe_search or deterministic_only looser than the key’s policy, or allowed_domains widening the key’s domain policy: 403 policy-limit-exceeded.
  • A value of source_kinds, source_independence, ranking_priorities or ranking_order outside its set: not_allowed.
  • Every source would be skipped before work: no-datasource-can-run.
  • An unknown datasource id: datasource-unknown; an unknown set:NAME: domain-set-unknown.
  • A bare pdf in media_types: not_allowed, with application/pdf suggested.
  • Any other bound passed: bound; an unknown field: unknown_field.
  • pinned_version not served, never or no longer: version-withdrawn.

Notices this operation makes

query_corrected, filter_emulated, default_set_by_policy, window_after_as_of_date, fetch_not_finished, cost_cut, budget_cut, time_cut, field_not_applicable, total_characters_cut on the search and on an inline record, version_retiring. A skipped source is a coverage gap, never a notice too.

Problem types

A source’s failure is never an API problem; it stands as that source’s outcome in the receipt.
  • 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; datasource-access-required, The datasource needs a registered login; credit-exhausted, The credit is exhausted; run-budget-exhausted, The run’s budget is exhausted; key-budget-exhausted, The key’s budget is exhausted.
  • 409 idempotency-key-in-flight, The same request is still running.
  • 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; model-work-refused, Model work is refused by the request; cost-exceeds-cap, The cost cap is below the smallest call; version-withdrawn, The version is no longer served; idempotency-key-reused, The idempotency key was reused with another body; no-datasource-can-run, No datasource can run this search; datasource-unknown, The datasource is unknown; datasource-not-searchable, The datasource has no search; domain-set-unknown, The domain set is unknown.
  • 429 rate-limit-exceeded, The rate limit is exceeded; concurrency-limit-exceeded, Too many calls are in flight.
  • 451 legal-block, Withheld under a legal demand.
  • 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

Idempotency-Key
string

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_at as it stands and replayed true on every cost. Nothing is billed again.
  • The same key while the first call still runs: 409 idempotency-key-in-flight, with Retry-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.

Required string length: 1 - 255
Pattern: ^[!-~]{1,255}$
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.

Body

application/json

The request of search; also the shape of Search.applied_request, the request as it ran with every field in force. Every field is at the top level but the named objects Money, SubjectIdentifier and SearchContentsOptions; an explicit null equals an absent field and gets the default. The object is closed; an unknown field is refused invalid-field, unknown_field.

query
string

The question, 1 to 2,000 characters; required unless subject_identifiers is sent. "phrase", -word, OR, one level of ( ), site:, filetype:, intitle:, inurl:, before:, after: and * are honored where a source supports them, and the receipt's operators_applied says what each source did with each.

Required string length: 1 - 2000
Example:

"EU AI Act article 50 marking obligations"

alternate_queries
string[]

Other wordings of the question, in any language, each 1 to 2,000 characters, up to 10; one merged list with query, 20 wordings at most after OR splits. Default none. A wording runs only on the sources that cover its language; nothing is translated, so a wording in another language reaches the sources in that language. Without query it is refused dependent.

Maximum array length: 10
Required string length: 1 - 2000
subject_identifiers
object[]

Exact codes of the subject, up to 10 SubjectIdentifier objects; with no query, each identifier's value runs as a wording with origin identifier. issuer is required for ticker, docket, tax_id and registry, as the catalog's codes; a duplicate is refused duplicate. Default none.

Maximum array length: 10
subject_country
string

The country the search is made from, ISO 3166-1 alpha-2; groups of sources expand by it; the inline fetch reads from it when it is a country getclean can read from, one of Limits.exits, else from the key's default_exit with the notice field_not_applicable. Default none.

Pattern: ^[A-Z]{2}$
Example:

"DE"

purpose
string

Your reason for the search, kept in the record and read by every model step; never sent to a source. At most 2,000 characters. Default none.

Required string length: 1 - 2000
datasources
string[]

Where to search: up to 10 of a datasource id, a group, or set:NAME, a published set, each 1 to 64 characters; these are names without dots, where allowed_domains takes site names with dots. When sent, the search runs on these plus the sources that resolve a scheme of your subject_identifiers, added without a model step, each in the receipt with reason identifier. When absent, it runs on web plus the groups a model chooses for the question, one model step, each named; under deterministic_only, on web only. An unknown id is datasource-unknown, an unknown set domain-set-unknown, a site name here misplaced.

Maximum array length: 10
Required string length: 1 - 64
allowed_domains
string[]

Only results on these sites count, site names with dots: up to 500 of a domain, a wildcard such as *.example.com, a URL prefix, a suffix such as .gov, or set:NAME, a published set, each 1 to 2,048 characters. What each form reaches: a domain, that host and every host under it; *.example.com, the hosts under the domain and not the domain itself; a URL prefix, every address that begins with it; a suffix with a leading dot, every domain that ends in it; set:NAME, the sites of that set. It may narrow the key's policy.allowed_domains and never widen it, which is policy-limit-exceeded. Default none. A site in both this and blocked_domains is refused exclusive; a datasource id here misplaced.

Maximum array length: 500
Required string length: 1 - 2048
blocked_domains
string[]

Never results on these sites; up to 500 of the same forms and bound as allowed_domains, each form reaching what it reaches there. Default none.

Maximum array length: 500
Required string length: 1 - 2048
published_from
string<date>

Pages published on or after this date, inclusive, by the page's own date. Default none. With published_within_days it is refused exclusive; after published_until the pair is refused order; a date after today bound; a window that begins after as_of_date makes the notice window_after_as_of_date.

Example:

"2026-01-01"

published_until
string<date>

Pages published on or before this date, inclusive. Default none.

Example:

"2026-11-01"

published_within_days
integer

Pages published within this many days counted back from today, or from as_of_date when it is sent; 1 to 3,650. Not with published_from or published_until, which is refused exclusive. Default none.

Required range: 1 <= x <= 3650
undated
enum<string>
default:shown

Whether pages with no detectable date are kept inside a date window: shown keeps them, hidden drops them. Default shown. Sent without a window it makes the notice field_not_applicable.

Available options:
shown,
hidden
languages
string[]

Only pages written in these languages, up to 10 BCP 47 tags, each 1 to 35 characters; what the pages are written in, independent of the wordings' languages. Default none.

Maximum array length: 10
Required string length: 1 - 35
media_types
string[]

Only these file types, up to 10 IANA media types, each 1 to 255 characters; a bare pdf is refused not_allowed with application/pdf suggested. Default none.

Maximum array length: 10
Required string length: 1 - 255

How strictly adult content is filtered: off, moderate or strict. Where a source has the setting it is mapped to the nearest level, said with the notice filter_emulated; it never removes a source. Never looser than the key's policy.safe_search, which is policy-limit-exceeded. Default moderate.

Available options:
off,
moderate,
strict
source_kinds
string[]

Only these kinds of publisher, 1 to 24 of the kinds of SourceProfile.kind, never unknown; a filter that removes, where ranking_priorities only reorders. Default none.

Required array length: 1 - 24 elements

One publisher kind, a value of SourceProfile.kind.

Minimum string length: 1
source_independence
enum<string>

Only sources independent of the subject, or only its own; independent or self. Needs a subject resolved from subject_identifiers, else the notice field_not_applicable. Default none, any.

Available options:
independent,
self
as_of_date
string<date>

Search each source as it stood at the end of that day, UTC, and read any inline fetch from an archive's copy of that day. A date not after today. Default none, the sources as they stand now. A source that keeps no history reports no_history.

Example:

"2026-10-01"

max_per_datasource
integer
default:10

Results taken from each source per wording, before merging; capped by the source's maximum. 1 to 100; default 10.

Required range: 1 <= x <= 100
ranking_instructions
string

Your instructions to the ranking model, at most 2,000 characters; kept in the record. Default none. Refused model-work-refused under deterministic_only.

Required string length: 1 - 2000
ranking_priorities
enum<string>[]

Source facts that go first, in this order, up to 4 of official, independent, primary, reviewed; the leads grouped by them, then ordered within each group by ranking_order. Default none. independent with no subject resolved makes the notice field_not_applicable.

Maximum array length: 4

A fact about a source that puts it first in the ranking: official, a publisher of one of the six public kinds of SourceProfile.kind, a state, a court, a regulator, a statistics office, an intergovernmental body or a standards body; independent, independent of the subject; primary, a primary source; reviewed, a stated review. A closed set.

Available options:
official,
independent,
primary,
reviewed
ranking_order
enum<string>
default:relevance

The order within each priority group; relevance, newest or oldest; undated pages last under the date orders; the relevance cut-off applies in every case. Default relevance.

Available options:
relevance,
newest,
oldest
ranking_preferred_domains
string[]

Sites ranked first among results of equal relevance; other sites still count. Up to 500 of the forms of allowed_domains, each reaching what it reaches there, each 1 to 2,048 characters. Default none. A value outside allowed_domains when it is set, or in blocked_domains, is refused dependent.

Maximum array length: 500
Required string length: 1 - 2048
ranking_max_per_domain
integer

The most leads kept from one site in the answer, 1 to 50. Default none. With one allowed site it makes the notice field_not_applicable.

Required range: 1 <= x <= 50
max_candidates
integer
default:10

The leads returned, 1 to 50; default 10. The results past them are read free by get_search.

Required range: 1 <= x <= 50
max_excerpt_characters
integer
default:600

The excerpt per lead, in characters, 0 to 4,000; 0 means none. Default 600.

Required range: 0 <= x <= 4000
max_total_characters
integer
default:40000

The whole answer's text, excerpts and fetched pages together, 1,000 to 200,000; the excerpts first, cut from the last lead backwards when they alone pass it, then the fetched pages in rank order while they fit in what remains, a page that would pass it coming as sections_only; each cut the notice total_characters_cut. Default 40,000. Below max_excerpt_characters it is refused order.

Required range: 1000 <= x <= 200000
contents
object

Fetch this many top leads in the same call, under the inline fetch's rules; contents.max_characters bounds one page, max_total_characters the whole answer. Default none. The options without top are refused required; top above max_candidates order; with wait_seconds below 5, the least a fetch needs, order.

view
enum<string>
default:full

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.

Available options:
full,
compact
wait_seconds
number
default:10

The most seconds this call may work, the ranking, the choice of sources and every inline fetch inside, counted from the start of the work; what did not finish comes back partial, named. 0.2 to 60; default 10.

Required range: 0.2 <= x <= 60
max_cost
object

The most this call may cost, in the account's currency. When it cannot cover everything, the extras are cut in order, each with the notice cost_cut: first each inline fetch's own extras, then whole fetches, then the ranking, then the choice of sources, then the results taken per source. Default the key's cap on one call. Below the smallest call's price, one searches and one datasource_queries, it is refused cost-exceeds-cap with minimum_cap.

deterministic_only
boolean
default:false

Turn off every step a model judges: the ranking and the choice of sources, which the answer then says; the publisher's kind only from what getclean already knows; the inline fetch's json_schema and summary refused by name and its highlights found verbatim only. Text recognition on a scanned page fetched inline still runs and is listed. Default false. Sending false under a key whose policy forbids model work is policy-limit-exceeded.

pinned_version
string

The version of getclean to run under, at most 64 characters. Default the current version. A version not served is version-withdrawn.

Required string length: 1 - 64
Example:

"1.0.0"

run_id
string
default:run_default

The run the record belongs to, an existing run of the key. Default the key's default run. An unknown run is refused not_allowed.

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

Have the search written up for a reviewer: plain, in plain words, or prisma, in the PRISMA form a systematic review reports; an open set. Default none, no write-up.

Minimum string length: 1
Examples:

"plain"

"prisma"

metadata
object

Your own labels, returned on the record as sent and never passed to a source: at most 20 string pairs, keys of 1 to 64 characters, values of 1 to 512. Default none. An empty map is refused bound.

max_source_price
object

The most you allow for a datasource that charges per query, or for a site an inline fetch meets that asks a price. A source whose fee passes it is not searched, the coverage gap over_price, never a refusal. getclean pays no site for a page, so a page that asks a price ends payment_required. Default none.

retention
enum<string>

How long the search record and every inline record are kept: hold, 48 hours after the last call and at most 30 days, allowed only under a hold policy; none, nothing kept past the answer. Default the key's policy.retention.

Available options:
hold,
none

Response

The search record, Search, with Location naming it; the outcome first, then the notices and coverage gaps, then the leads in rank order with the facts of each, the receipt per source, the ranking, the execution and the cost.

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