Skip to main content
POST
Best when you want web results, news, images or all three at once, grouped by type, with the page text of the top web results if you ask for it.
Works without an API key within the free limits. See Rate limits.

Authorizations

Authorization
string
header
required

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

Headers

Idempotency-Key
string

A value you choose for one call. Send the same key with the same method, path and body within 24 hours and the first answer comes back with idempotent-replayed: true, with the same cost headers and no second charge. A call that sends zeroDataRetention and answers with page data is not kept, so a retry runs again. Needs an API key.

Query Parameters

maxTextLength
integer

Cut every text value in the response to this many characters. A value that was cut ends with …, and a page whose text was cut has isTruncated set to true. A screenshot is never cut. Leave it out to get the full text.

Required range: x >= 1

Body

application/json
query
string
required

What to search for, up to 500 characters. Search operators work in web results: quotes for an exact phrase, -word, site:, -site:, filetype:, inurl:, allinurl:, intitle: and allintitle:. In image results, imagesize:WIDTHxHEIGHT keeps images of exactly that size and larger:WIDTHxHEIGHT keeps images at least that large.

Required string length: 1 - 500
sources
enum<string> · object · object[]

What to search: web, news, images. Each is a string or {type}. Default web, or none when categories asks for research or videos.

Required array length: 1 - 5 elements
Available options:
web,
news,
images
categories
(enum<string> | object)[]

pdf: web results that are PDF files. research: scholarly papers, in a research list, ranked by relevance then citations. videos: YouTube videos for the query, in YouTube's order, in a videos list, with the channel, length, views and watch link; a video whose captions we hold also gets the passage that matches the query and where it starts.

Available options:
research,
pdf,
videos
maxAge
integer

Accept a stored answer up to this many milliseconds old, at most 30 days. Without it, 15 minutes for news and 1 hour for web and images. 0 always searches live.

Required range: 0 <= x <= 9007199254740991
limit
integer

Most results to return for each source. Default 10, or 5 when scrapeOptions has formats, which reads every web and news result returned unless scrapeLimit sets fewer. News returns at most 50.

Required range: 1 <= x <= 100
scrapeLimit
integer

With scrapeOptions formats: read only the top this many web results and the top this many news results, and return the other results without page text. Cannot be more than limit. Without it every result returned is read. Only pages that are read are charged for.

Required range: 1 <= x <= 100
tbs
string

Time filter: qdr:d, qdr:w, qdr:m or qdr:y, or cdr:1,cd_min:MM/DD/YYYY,cd_max:MM/DD/YYYY, plus sbd:1, like sbd:1,qdr:w. sbd:1 sorts newest first; results without a date come last. Web takes all of them; news takes qdr and sbd; images take none.

Minimum string length: 1
location
string

Where to search from, like Germany or San Francisco,California,United States. The last part is the country and replaces country. A city before it narrows web results to that place.

Minimum string length: 1
country
string

Two-letter country to search from, like us. uk is read as gb. Image results are always US.

Pattern: ^[A-Za-z]{2}$
lang
string

Two-letter language preference, like de. Applies to web results when web is selected, otherwise to news where supported. Results from a source that cannot honor it may be in another language and come with a warning.

Pattern: ^[A-Za-z]{2}$
includeDomains
string[]
Maximum array length: 10
excludeDomains
string[]
Maximum array length: 10
safe
boolean

Hide explicit web, news and image results when true.

timeout
integer

Milliseconds to wait for the sources, from 1,000 to 120,000; more is read as 120,000. Default 3,000, or 60,000 when scrapeOptions has formats and the search reads pages. A source that has not answered by then is left out with a warning. When none has, the call fails and costs nothing.

Required range: 1000 <= x <= 9007199254740991
ignoreInvalidURLs
boolean
default:false

Leave out results whose address cannot be read as a page.

highlights
boolean
default:false

Off by default. With true, a web result whose page we already hold gets the passages that best match the query as its description, in markdown, up to about 2,000 characters; others keep the engine's snippet.

scrapeOptions
object

With formats, reads each web and news result, as many as scrapeLimit or limit asks for, within timeout, and fills each web result's description from it. Without formats no page is read and nothing more is charged. Takes the options of scrape: formats (markdown, html, rawHtml, links, images, summary, screenshot, json and the rest), onlyMainContent, includeTags, excludeTags, maxAge, minAge, waitFor, mobile, timeout (per page), headers, actions, location, parsers, profile and zeroDataRetention. redactPII uses patterns on web descriptions, news snippets, research snippets and video snippets, even without formats, when sources has web or news. Titles and URLs are unchanged. Snippets can still contain names and places that patterns miss. With formats, page reads and their add-ons use scrape pricing, starting at $1 per 1,000 pages for a standard read.

Response

The data, and what this call cost in dollars.

success
boolean
required
data
object
warning
string