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; when Google refuses or reads short, from DuckDuckGo's and then Bing's, and the answer with most results about the query is given, topped up from the others. 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: at most 4 credits a search, whatever read it: Google's results page, and DuckDuckGo's or Bing's at 1 each when their results are used, within those 4. A results page an engine refused, or one about something else, 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. A search aims to answer within about 35 seconds; a retry on the residential browser after Google's wall can take longer. 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'.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"query": "<query>"
},
"name": "search_web"
}
}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: 'google', 'duckduckgo' or 'bing'. | |
| notice | No | Only when a limit, not the site, held pages back: one line saying what they needed and why (the plan, the stealth trial or the credits left). Tell the person; it comes first in the answer. | |
| status | No | 'done'; 'blocked' when no engine answered (see `outcome`); 'running' with a `job` while it goes on. On an error, the HTTP status code. | |
| notices | No | With `notice`: one per reason, {reason, pages, needs, examples, unlockedBy, upgradeUrl}, `engine` on a search's and `outlook` {tier, likely, why} on a page's; unlockedBy is the plan that reads them, null for credits or a cap the workspace set itself. | |
| outcome | No | With status 'blocked': 'no_results' when every engine refused the results page or had nothing about the query (nothing charged); null when the search did not run because the credits left could not pay for a results page -- tell the person, as a top-up or a plan change fixes it. | |
| 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. | |
| waitedMs | No | With status 'running': how long, in milliseconds, this call waited for the search before handing back its job. | |
| creditsUsed | No | Credits this search spent, scraped pages included. |