Skip to main content
POST
web.search-options

Authorizations

Authorization
string
header
required

API key: sk_live_…

Headers

Idempotency-Key
string

Optional. A retry with the same key returns the stored result.

Maximum string length: 255
Pramaan-Max-Price-Micro
string

Optional. The most this request may be priced at, in micro-USD (a whole number above 0). It replaces the capability's own price ceiling for this request, lower or higher. Sources that could cost more are left out; when none is left the answer is 400 with the lowest limit that would work.

Pattern: ^[1-9]\d{0,14}$

Body

application/json
query
string
required

Search words, at most 2,048 characters.

limit
integer
default:10

Most results, 1 to 20. Default 10.

Required range: 1 <= x <= 20
depth
enum<string>
default:basic

Search effort. Default basic; auto permits a dearer choice.

Available options:
basic,
fast,
ultra-fast,
advanced,
auto
chunksPerSource
integer

Most excerpts per result, 1 to 3.

Required range: 1 <= x <= 3
topic
enum<string>
default:general

Search category. Default general.

Available options:
general,
news,
finance
timeRange
enum<string>

Recent publication window.

Available options:
day,
week,
month,
year
startDate
string

Earliest publication estimate, YYYY-MM-DD.

Pattern: ^\d{4}-\d{2}-\d{2}$
endDate
string

Latest publication estimate, YYYY-MM-DD.

Pattern: ^\d{4}-\d{2}-\d{2}$
includeDates
boolean

Request estimated publication dates.

strictDates
boolean

Strict date-window filtering also removes undated pages.

answer
enum<string>
default:none

Optional generated answer. Default none.

Available options:
none,
basic,
detailed
content
enum<string>
default:none

Optional page content. Default none.

Available options:
none,
text,
markdown
includeImages
boolean

Request source images.

describeImages
boolean

Request image descriptions; requires includeImages.

includeIcon
boolean

Request source icons.

includeDomains
string[]

Included or preferred hosts, up to 300; no paths or wildcards.

Required array length: 1 - 300 elements
Pattern: ^[a-zA-Z0-9.-]+$
excludeDomains
string[]

Excluded hosts, up to 150; no paths or wildcards.

Maximum array length: 150
Pattern: ^[a-zA-Z0-9.-]+$
domainMode
enum<string>

Restrict to included domains or merely prefer them.

Available options:
restrict,
prefer
countryBoost
string

Country preference for general search; a boost rather than a filter.

Required string length: 1 - 64
language
string

Preferred language name or code.

Required string length: 1 - 64
strictLanguage
boolean

Filter to the requested language.

autoParameters
boolean

Permit automatic filter selection; explicit depth still wins.

exactMatch
boolean

Require quoted query phrases to match exactly.

Filter adult content where supported.

session
string

Your opaque session token; isolated to your account.

Required string length: 1 - 128
userTag
string

Your opaque end-user token; isolated to your account.

Required string length: 1 - 128

Response

The result

results
object[]
required

At most 20 relevant pages.

truncated
boolean
required

True when output was cut to fit limits.

answer
string

Requested answer, at most 50,000 characters.

images
object[]

At most 20 query-related source images.

appliedOptions
object

Selected automatic options, when reported.

ref
string

Reference to what this call created. Pass it as ref to web.search-feedback.