Search the web
Start with a query and the number of results. See the Quickstart for authentication and SDK setup.results for ranked pages. Request fields and the complete response are in the Search reference.
Choose what to return
numResults ranges from 1 to 100 and defaults to 10. The actual number returned can be smaller. Use filters to restrict domains, recency, and location. Result content covers page reads and per-result failures.
Set descriptionMaxCharacters to cap each result’s description; it defaults to null (no cap). When descriptionMaxCharacters is above 0, the request has no includeDomains or excludeDomains filter, and the query uses no search operator, news-index results fill that space with the article passages that best match your query.
Set timeoutOpts.behavior to return-partial if a subset of results is useful at your deadline, and inspect partial.
Add policies to apply access policies; a URL must pass every policy. Use tags to label requests for usage filtering, and set zdr to "enabled" for zero data retention when your organization has ZDR access.
Read the response
Each result carries arelevance of high, medium, or low relative to your query. cache_metadata.status is hit, miss, or zdr, and cache_metadata.age_ms is the age of the cached data in milliseconds; it is 0 for a miss or ZDR response.
Research papers
Research-style queries, such as “transformer models for protein folding”, can also return indexed research papers alongside web pages. A paper result’surl links to the paper, and its description is a passage from the paper that matches your query. freshness filters papers by publication date, and languages applies to them too.
Papers are left out when you set includeDomains or excludeDomains, or when the query uses an operator such as site:, OR, a quoted phrase, or a - exclusion.
Use Scrape when you already know the URL. Use Answers when you want a researched answer in a specific JSON shape.