Skip to main content
POST /v1/web/search runs a query against the web and returns ranked results. Turn on scrapeResults and every result also comes back with its page read and cleaned, so one call turns a question into documents your model can use.

When to use it

  • You know what you are looking for but not the exact URLs.
  • You want the top few sources on a topic as clean Markdown.
  • You want results from a recent window, a region or a set of sites.
For recent articles with dates, use News instead. Search answers “which pages are about this”; News answers “what was reported, and when”.

Example

Each result has a rank, title, URL and snippet. With scrapeResults on, each also has data, the page read as clean data. Otherwise data is null.

Options

string
required
What to search for, up to 500 characters.
number
default:"5"
How many results to return, from 1 to 15.
boolean
default:"false"
Also read each result’s page and return it as clean data, at 1 extra credit per page read. Leave it off to get just the title, URL and snippet.
object
How to read each result, with the same options as Scrape: formats, location, timeout, maxAge and so on. Formats are limited to markdown, html, rawHtml, links and structured. Ignored when scrapeResults is off.
string
Only results from the last day, week, month or year.
string
A two-letter country code, such as us or de, to lean results toward that country.
string[]
Only return results from these sites. Up to 15.
string[]
Leave out results from these sites. Up to 15.

Response fields

string
ok when results were found, no_results when the web had nothing for the query. If the search cannot be run at all, the call fails with 503 instead of returning an empty list.
object[]
The ranked results. Each has title, url, snippet, rank and data.

Cost

1 credit per search. With scrapeResults, each page actually read costs 1 more, the same as scraping it directly. A search that finds nothing, or fails, costs nothing. See Credits.

News

Recent articles, newest first, with outlet and date.

Extract

Turn found pages into JSON, or let extract search for you.

Scrape

Read one page you already have.

API reference

The full schema, with a live playground.