Search
Search up to ten datasources with one question, in up to twenty wordings, and get one ranked list of results with the facts of each and a receipt of what ran where, before any page is read.
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 needssearch: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 fromsubject_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,retentionandmax_source_price, and itssubject_countrywhen that is a country getclean can read from, else the key’sdefault_exitwith the noticefield_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 owncost. - 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 noticefetch_not_finished. contents.max_charactersbounds one page.max_total_charactersbounds 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 assections_only; each cut makes the noticetotal_characters_cut.
Money
The ceiling is the lowest of the request’smax_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, incoverage_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 inviolations:
- Neither
querynorsubject_identifiers:invalid-field,required. alternate_querieswithoutquery:dependent.- A scheme that needs an issuer, without one:
dependent; anissuerno catalog entry lists for its scheme:not_allowed, with the listed codes inallowed_values. published_within_dayswithpublished_fromorpublished_until:exclusive;published_untilbeforepublished_from:order; a date after today:bound.- A site in both
allowed_domainsandblocked_domains:exclusive; aranking_preferred_domainsvalue outsideallowed_domainswhen that is set, or inblocked_domains:dependent. - A site name in
datasources, or a datasource id inallowed_domains,blocked_domainsorranking_preferred_domains:misplaced,change.fieldnaming the field it belongs in. contentswithouttop:required;topabove 10:bound;topabovemax_candidates:order;contentswithwait_secondsbelow 5, the least a fetch needs:order.- Under
deterministic_only:ranking_instructions, andjson_schemaorsummaryinsidecontents:model-work-refused. - More than 20 wordings after OR splits:
bound, with the count. max_costbelow the smallest call’s price, onesearchesand onedatasource_queries:cost-exceeds-cap, withminimum_cap.max_total_charactersbelowmax_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 gapaccess_needed, and the rest run. safe_searchordeterministic_onlylooser than the key’s policy, orallowed_domainswidening the key’s domain policy:403 policy-limit-exceeded.- A value of
source_kinds,source_independence,ranking_prioritiesorranking_orderoutside its set:not_allowed. - Every source would be skipped before work:
no-datasource-can-run. - An unknown datasource id:
datasource-unknown; an unknownset:NAME:domain-set-unknown. - A bare
pdfinmedia_types:not_allowed, withapplication/pdfsuggested. - Any other bound passed:
bound; an unknown field:unknown_field. pinned_versionnot 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
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
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_atas it stands andreplayedtrue on everycost. Nothing is billed again. - The same key while the first call still runs:
409 idempotency-key-in-flight, withRetry-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.
1 - 255^[!-~]{1,255}$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
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.
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.
1 - 2000"EU AI Act article 50 marking obligations"
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.
101 - 2000Exact 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.
10The 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.
^[A-Z]{2}$"DE"
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.
101 - 64Only 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.
5001 - 2048Pages 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.
"2026-01-01"
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.
off, moderate, strict 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.
4A 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.
official, independent, primary, reviewed 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.
5001 - 2048The 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.
1000 <= x <= 200000Fetch 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.
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.
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.
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.
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.
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