> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usegoro.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Web search

> Run a Google web search and get back ranked organic results with title, url, and snippet.

Run a Google web search and get back ranked organic results with title, url, and snippet.

<Note>Use when you need current information from the web, to find pages about a topic, or to answer questions that need fresh sources. Billed per result page, about 10 results each.</Note>

## Price

**\$0.0075 per page.** That is the rate you pay for each page the call returns, so the total depends on how many it produces.

Billing follows actual usage, so a call that returns fewer pages costs less. `discover` and `inspect` also return a ceiling for your specific request, which is a maximum you will never be charged above.

## Input

| Field                             | Type      | Required | Notes                                                                                                                                                                                                                             |
| --------------------------------- | --------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `site`                            | `string`  |          | Limit to one site, e.g. example.com                                                                                                                                                                                               |
| `queries`                         | `string`  | yes      | Search term(s), or Google Search URLs. Newline-separate for multiple. Supports advanced operators like site: and OR.                                                                                                              |
| `saveHtml`                        | `boolean` |          | Attach each results page's raw HTML to its item as html. Useful when you want to parse the page yourself, and it makes the response very large.                                                                                   |
| `afterDate`                       | `string`  |          | Only results from after this date. Same formats as beforeDate. Do not combine with quickDateRange.                                                                                                                                |
| `fileTypes`                       | `array`   |          | Only results of these file types, the filetype: operator, e.g. pdf, xlsx, csv. Several types are combined with OR.                                                                                                                |
| `aiOverview`                      | `object`  |          | PAID ADD-ON. Capture Google's AI Overview in full for each query. Set scrapeFullAiOverview true inside this object. Billed $0.002 per query where an overview is actually captured, against $0.0025 for the search page itself.   |
| `aiOverview.scrapeFullAiOverview` | `boolean` |          |                                                                                                                                                                                                                                   |
| `beforeDate`                      | `string`  |          | Only results from before this date. Absolute (2026-05-03, read as UTC) or relative (8 days, 3 months). Do not combine with quickDateRange.                                                                                        |
| `wordsInUrl`                      | `array`   |          | Words that must appear in the URL, the inurl: operator.                                                                                                                                                                           |
| `countryCode`                     | `string`  |          | Two-letter country code, sets the Google domain (e.g. es for google.es)                                                                                                                                                           |
| `wordsInText`                     | `array`   |          | Words that must appear in the page text, the intext: operator.                                                                                                                                                                    |
| `aiModeSearch`                    | `object`  |          | PAID ADD-ON. Also answer each query from Google AI Mode, the conversational search surface, with cited sources. Set enableAiMode true inside this object. Billed \$0.005 per answer returned, twice the price of the search page. |
| `aiModeSearch.enableAiMode`       | `boolean` |          |                                                                                                                                                                                                                                   |
| `geminiSearch`                    | `object`  |          | PAID ADD-ON. Also answer each query from Google Gemini. Set enableGemini true inside this object. Billed \$0.005 per answer returned.                                                                                             |
| `geminiSearch.enableGemini`       | `boolean` |          |                                                                                                                                                                                                                                   |
| `includeIcons`                    | `boolean` |          | Include base64 icon image data on organic, paid and suggested results. Large.                                                                                                                                                     |
| `languageCode`                    | `string`  |          | Interface language (hl)                                                                                                                                                                                                           |

<Note>
  Goro forwards your input to the underlying tool unchanged, so any field the
  tool accepts works here even if it is not listed above.
</Note>

## Example

```bash theme={null}
curl -X POST https://api.usegoro.ai/v1/run \
  -H "Authorization: Bearer $GORO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"slug":"web.search","input":{"queries":"example","maxPagesPerQuery":3}}'
```

## Response

One row of the response. Values are illustrative.

```json theme={null}
{
  "url": "https://example.com/ai-agents",
  "title": "What is an AI agent?",
  "snippet": "An AI agent is a program that can act autonomously...",
  "position": 1
}
```