Skip to main content
POST

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
query
string
required

What to search for.

Maximum string length: 2000
Example:

"best espresso machine"

sources
enum<string>[]

Where to search. research returns academic papers and preprints, and developer returns GitHub issues and pull requests. Each source comes back as its own list.

Minimum array length: 1
Available options:
web,
news,
images,
videos,
research,
developer
limit
integer
default:10

Results per source.

Required range: 1 <= x <= 20
page
integer
default:1

Which page of results to return. Once you have a result, prefer pageTokens, which continues the exact same result set.

Required range: 1 <= x <= 5
pageTokens
object

Tokens from an earlier result's nextPageTokens, keyed by source, such as { "web": "v1...." }. Send them with the next page number. A token that has expired isn't an error: that source runs as a fresh search.

country
string

The country to search from, which changes which results you get. A two-letter code such as us, gb or de, or global, eu or asia.

Example:

"gb"

timeRange
enum<string>

Only return results from this recent period. Some sources don't support every value, and ignore one they can't apply.

Available options:
hour,
day,
week,
month,
year
includeDomains
string[]

Only return results from these domains, such as ["github.com"]. Can't be used with excludeDomains.

Maximum array length: 20
excludeDomains
string[]

Leave out results from these domains. Can't be used with includeDomains.

Maximum array length: 20
filetype
enum<string>

Only return PDF files.

Available options:
pdf
wait
boolean
default:false

Waits up to 20 seconds and answers 200 with the result. If the search takes longer, you get 202 and poll as usual. Ignored with scrapeOptions.

scrapeOptions
object

Reads the top web results and adds each page's Markdown to its result as markdown. Only web results are read. The search takes as long as the slowest page, up to about two minutes.

Response

Only with wait: true. The search finished within 20 seconds. status is completed with the result, or failed with the reason in error.

status
enum<string>
Available options:
completed,
failed
jobId
string<uuid>

The job's ID. Works with GET /search/{jobId} for the next hour.

progress
object
result
object | null

The result when status is completed, null otherwise.

error
string | null

Why the search failed. null otherwise.