Search 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'.