Search the web
search_webSearch the web for a query and return the ranked results, each with its title, url and snippet. The results are read from Google's results page, or Bing's when Google refuses. Use it to find pages whose URLs you do not know. It searches the web, unlike list_pages with q, which searches inside a project's stored run. For URLs you already have use scrape_urls; scrape_urls with full=true reads one result in full. Inputs: query as typed into a search engine, e.g. 'python http client'. scrape=true also fetches each result's page as markdown in the same call. include_domains=['python.org'] keeps the search to those sites; exclude_domains drops sites, and an exclude wins. Cost: Google's results page is read with a browser, 4 credits or more where it needs the stealth tier; Bing's, used when Google refuses, is a plain fetch at 1. A results page the engines refused is free. An equal search (same query, country, lang, freshness and domains) within an hour of a finished one comes from cache with no charge for the results page. Scraped pages are charged, cached or not. Timing: it waits for the results. If a search outlasts the connection's time limit, a job comes back for get_job; a scraping search whose pages are still landing returns its results with a job for the pages. Needs write access; a read-only connection is refused with code 'read_only'.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| lang | No | A language code for the results, e.g. 'en'; omit for the default. | |
| limit | No | How many results to return, 1 to 10 (default 10). | |
| query | Yes | What to search the web for, 1 to 400 characters, as it would be typed into a search engine. | |
| scrape | No | true also fetches each result's page as markdown; each page costs credits. false (default) returns the results only. | |
| country | No | A 2-letter country code to search from, e.g. 'us' or 'de'; omit for the default. | |
| freshness | No | Only results from the last hour, day, week, month or year; omit for any time. | |
| exclude_domains | No | Up to 20 sites to leave out of the results, e.g. ['pinterest.com']; an exclude wins over an include. | |
| include_domains | No | Up to 20 sites to search within, e.g. ['python.org']; omit for the whole web. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | The search's id: for get_job with kind 'search'. | |
| job | No | While it is still going: {kind: 'search', id} for get_job. A scraping search can carry its results and a job for the pages still landing. | |
| code | No | Only on a failure: a machine-readable reason, e.g. read_only, validation, plan_limit or not_found. | |
| note | No | The cache rule, and what to do next when it is still going. | |
| error | No | Only when the call failed: what went wrong, in words an assistant can act on. | |
| query | No | The query as searched. | |
| cached | No | true when an equal search within the hour answered it, with no charge for the results page. | |
| detail | No | Only on a failure: the API's own wording, when the error was rephrased. | |
| engine | No | The engine whose results page answered, e.g. 'google' or 'bing'. | |
| status | No | 'done'; 'blocked' when every engine refused the results page (nothing charged); 'running' with a `job` while it goes on. On an error, the HTTP status code. | |
| results | No | Up to 10, as ranked, each {position, title, url, snippet, source, engine}; when scraped also `page`, {url, title, words, status, links (a count), markdown excerpt}, the excerpts sharing 60,000 characters. | |
| attempts | No | Blocked only: each engine tried, and why it was refused. | |
| creditsUsed | No | Credits this search spent, scraped pages included. |