Search batch
Run 1 to 20 searches in one call, one record each. You get the tally first, then one result per item in input order, each a search record or the problem that skipped it; nothing is atomic, so a skipped item leaves the others standing. Each item carries its own question, wordings, identifiers, country and purpose; every other field of search stands once at the top and is shared by every item.
What it costs
The key needssearch:run. The price is the sum of the searches’ costs, units summed by name. The answer is 200 with SearchBatch. The body is at most 4 MiB.
The idempotency key
Idempotency-Key is required here, since a repeated batch would run and bill every search twice; its absence is 400 invalid-request naming the header. A replay repeats the whole answer with this call’s request_id, the current expires_at of every record and replayed true on every cost; the same key in flight is 409 idempotency-key-in-flight; the same key with another body 422 idempotency-key-reused.
Faults and limits
- A datasource behind an unregistered login, a policy the item’s sites break, a legal demand, or the remainder of the ceiling: that item comes back
skippedwith its problem, withoutstatus, and the batch still runs. A fault of a shared top field skips every item. A fault of the batch’s shape or of any field’s rule refuses the whole call. wait_secondsis each item’s own deadline from its own start. The call’s whole time is bounded bybounds.search.batch_seconds, and an item not started when it ends isskippedwith the problemoverloaded,retry_after_secondsset.max_cost: the whole call is refused below one search’s smallest price, with the problem of the limit that binds; else it is reserved at the start and split in input order, each item its smallest call and the model steps asked by name. The items the remainder cannot cover areskippedwith the problem of the limit that binds:cost-exceeds-capfor the request’smax_cost,policy-limit-exceededfor the key’s cap,credit-exhausted,run-budget-exhaustedorkey-budget-exhausted.- An item’s
Searchcarries the batch call’srequest_id, itsapplied_requestthe item’s fields merged with the top’s, the top’smetadata, and its ownexpires_at.
Refused before any work
, every violation of the body reported at once inviolations:
- Fewer than 1 or more than 20 items:
invalid-field,bound. - An item with neither
querynorsubject_identifiers:required. - A
labelrepeated:duplicate; alabeloutside its character set or length:syntax,bound. - A top-only field inside an item, or an item field at the top:
misplaced. - Every rule of
searchon the top fields and on an item’s own fields refuses the whole call, except a named source behind a login the key has not registered, a site the key’s policy forbids and a legal block, which skip the items they touch. - An unknown field, at the top or in an item:
unknown_field. Idempotency-Keyabsent:400 invalid-request.
Notices this operation makes
Every notice ofsearch inside each item’s record, version_retiring inside each too.
Problem types
For the whole call:- 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, for a setting, a minimum or a widening of the key’s domain policy;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. - 500
internal-error, The service failed. - 503
overloaded, The service is overloaded.
status: datasource-access-required, policy-limit-exceeded, legal-block, cost-exceeds-cap, credit-exhausted, run-budget-exhausted, key-budget-exhausted, 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.
Required on this operation, where a duplicate would cost the most; without it the call is 400 invalid-request naming the header. 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, the currentexpires_atandreplayedtrue on everycost. Nothing is billed again. On the upload the body is compared by a digest over the document and the fields, and a retried start with the same key is the same job. - 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 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_batch: the items, each a question with its own wordings, identifiers, country and purpose, and every other field of search once at the top, shared by every item and meaning what it means on search. An item field at the top, or a top-only field inside an item, is refused misplaced. An explicit null equals an absent field and gets the default. The object is closed; an unknown field at the top or in an item is refused invalid-field, unknown_field.
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 - 2048Each search's whole 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 of each search 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 the whole call may cost, in the account's currency; reserved at the start and split in input order, each item its smallest call and the model steps asked by name, the items the remainder cannot cover skipped. Default the key's cap on one call. Below one search's smallest price, one searches and one datasource_queries, it is refused with the problem of the limit that binds, cost-exceeds-cap with minimum_cap for the request's own.
Turn off, for every search, 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. 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 tally first, then one result per item in input order, each a search record or a problem without status, then the sum of the searches' costs.
The answer of search_batch: the tally first, then one result per item in input order, then the sum of the searches' costs.