Skip to main content
POST
Search batch

What it costs

The key needs search: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 skipped with its problem, without status, 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_seconds is each item’s own deadline from its own start. The call’s whole time is bounded by bounds.search.batch_seconds, and an item not started when it ends is skipped with the problem overloaded, retry_after_seconds set.
  • 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 are skipped with the problem of the limit that binds: cost-exceeds-cap for the request’s max_cost, policy-limit-exceeded for the key’s cap, credit-exhausted, run-budget-exhausted or key-budget-exhausted.
  • An item’s Search carries the batch call’s request_id, its applied_request the item’s fields merged with the top’s, the top’s metadata, and its own expires_at.

Refused before any work

, every violation of the body reported at once in violations:
  • Fewer than 1 or more than 20 items: invalid-field, bound.
  • An item with neither query nor subject_identifiers: required.
  • A label repeated: duplicate; a label outside 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 search on 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-Key absent: 400 invalid-request.

Notices this operation makes

Every notice of search 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.
Inside a skipped item, each without status: datasource-access-required, policy-limit-exceeded, legal-block, cost-exceeds-cap, credit-exhausted, run-budget-exhausted, key-budget-exhausted, 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
required

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 current expires_at and replayed true on every cost. 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, 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 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_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.

items
object[]
required

The searches, 1 to 20 SearchBatchItem objects in the order the results come back; the same question may repeat and makes two records. Required.

Required array length: 1 - 20 elements
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 an item's 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 per search, 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

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

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

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

view
enum<string>
default:full

How much of each 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 each search may work, counted from its own start, the ranking, the choice of sources and every inline fetch inside; the call's whole time is bounded by bounds.search.batch_seconds. 0.2 to 60; default 10.

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

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.

deterministic_only
boolean
default:false

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.

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 every 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 each 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 every search 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 every search record and inline record of the batch is 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 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.

counts
object
required

How the items ended, by outcome kind, with the items skipped before any search; the six add up to the number of items.

results
object[]
required

One result per item, in input order.

cost
object
required

The sum of the searches' costs, units summed by name; ceiling the whole call's.

request_id
string
required

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

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

"req_02Cibui4kSLfZhLrsUYlO2"