# Get the AI Overview Google shows for a search

Returns the AI Overview Google shows for a search, with the sources it cites and any products it shows. Use it to see which sites AI answers cite.

Tool `google.serp.ai-overview` on Google. Contract version 1, released 2026-10-27.

## Example call

Over REST, send the input in the body. Over MCP, pass the same input to `call_tool`.

cURL:

```bash
curl https://api.voxoria.ai/v1/tools/google.serp.ai-overview/calls \
  -H "Authorization: Bearer $VOXORIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input":{"query":"what is photosynthesis","language":"en"}}'
```

Python:

```python
import os

import httpx

response = httpx.post(
    "https://api.voxoria.ai/v1/tools/google.serp.ai-overview/calls",
    headers={"Authorization": f"Bearer {os.environ['VOXORIA_API_KEY']}"},
    json={
        "input": {"query": "what is photosynthesis", "language": "en"},
    },
    timeout=60,
)
print(response.json())
```

TypeScript:

```ts
const response = await fetch("https://api.voxoria.ai/v1/tools/google.serp.ai-overview/calls", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VOXORIA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "input": {"query": "what is photosynthesis", "language": "en"},
  }),
});
console.log(await response.json());
```

MCP (`tools/call` params):

```json
{
  "name": "call_tool",
  "arguments": {
    "tool": "google.serp.ai-overview",
    "input": {
      "query": "what is photosynthesis",
      "language": "en"
    }
  }
}
```

Both return [the full response](/docs/call-response.md): the call's ID, status and cost, with this tool's result in `output`.

## Input

| Input | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `query` | string | Yes |  | The search query. |
| `country` | string | No | `us` | Two-letter ISO 3166-1 country code. Case-insensitive. One of the 249 values of the `countries` list: ISO 3166-1 alpha-2 country codes, lowercase. |
| `language` | string | No | `en` | Two-letter ISO 639-1 language code. Case-insensitive. One of the 184 values of the `languages` list: ISO 639-1 two-letter language codes, lowercase. |
| `location` | string | No |  | Google location name, such as "New York, New York, United States". |
| `device` | string | No | `desktop` | One of `desktop`, `mobile`, `tablet`. |

## Output

A successful call returns these blocks in its `output`. A field not marked required can be `null`.

### text_blocks

A list of rows. Always present, possibly empty. The overview in reading order. Empty when Google shows no AI Overview for the query.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | string | Yes | Kind of block: paragraph, heading, list, table, image or code. One of `paragraph`, `heading`, `list`, `table`, `image`, `code`. |
| `text` | string | No | Text of a paragraph or heading, the code of a code block, or the caption of an image. Null for a list and a table. |
| `url` | string | No | Where an image links to, such as the product it shows. Null for any other block. |
| `image_url` | string | No | Address of an image. Null for any other block. |
| `list_items` | array of object | No | The items of a list, in reading order. Null for any other block. |
| `list_items.title` | string | No | Lead-in of the item, such as "Grind size". Null for an item without one. |
| `list_items.text` | string | No | The rest of the item. Null for an item that is only its title. |
| `list_items.url` | string | No | The item's own link, such as the product it names. Null for an item without one. |
| `table_header` | array of string | No | The header cells of a table, left to right; an empty cell is null. Null for any other block. |
| `table_rows` | array of object | No | The body rows of a table, top to bottom, the header excluded. Null for any other block. |
| `table_rows.cells` | array of string | No | The row's cells, left to right, as plain text. An empty cell is null. |
| `reference_positions` | array of integer | No | The sources the block cites, each by its position in references, in the order cited. Null for a block that cites none, or when the provider does not say. |

### references

A list of rows. Can be `null`. The sources of the overview, each once: the cited in citation order, then the uncited.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `position` | integer | Yes | Rank among the sources, starting at 1. What reference_positions refers to. |
| `title` | string | No | Title of the source. |
| `url` | string | No | Address of the cited page. Null for a source Google shows without a link, such as a product. |
| `domain` | string | No | Host of url, such as "www.reddit.com". |
| `source` | string | No | Name of the publisher, such as "Reddit". |
| `snippet` | string | No | The passage of the page the overview draws on. |

### products

A list of rows. Can be `null`. The products the overview shows as shopping cards, in reading order.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `title` | string | Yes | Name of the product. |
| `url` | string | No | Google's page for the product. |
| `price` | number | No | Current price, in currency. |
| `regular_price` | number | No | Price before a discount, in currency. Null when not discounted. |
| `currency` | string | No | ISO 4217 code of the prices, such as "USD". |
| `displayed_price` | string | No | The price as Google shows it, such as "$499.99 $580". |
| `rating` | number | No | Average rating, out of 5. |
| `rating_votes` | integer | No | Number of ratings the average is of. |
| `seller` | string | No | The store offering the price. |
| `image_url` | string | No | Address of the product's image. |

### answer

One object. Can be `null`. The whole overview as one document. Null when the provider sends none.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `markdown` | string | Yes | The overview as markdown, as the provider writes it. |

## Example output

The `output` of a real call, each list cut to 3 items.

```json
{
  "text_blocks": [
    {
      "type": "paragraph",
      "text": "Photosynthesis is the biological process that green plants, algae, and certain bacteria use to convert light energy into chemical energy .",
      "url": null,
      "image_url": null,
      "list_items": null,
      "table_header": null,
      "table_rows": null,
      "reference_positions": [
        1
      ]
    },
    {
      "type": "heading",
      "text": "The Formula",
      "url": null,
      "image_url": null,
      "list_items": null,
      "table_header": null,
      "table_rows": null,
      "reference_positions": null
    },
    {
      "type": "paragraph",
      "text": "During this process, plants absorb carbon dioxide and water and use solar energy to transform them into glucose (sugar) and oxygen:",
      "url": null,
      "image_url": null,
      "list_items": null,
      "table_header": null,
      "table_rows": null,
      "reference_positions": [
        5
      ]
    }
  ],
  "references": [
    {
      "position": 1,
      "title": "Introduction to Photosynthesis for Children: FreeSchool",
      "url": "https://www.youtube.com/watch?v=XCzFE0SB2N4&t=8",
      "domain": null,
      "source": "YouTube",
      "snippet": "you may have heard it said that plants make their own food. but have you ever wondered how they can do that. the answer is a proce..."
    },
    {
      "position": 2,
      "title": "What is Photosynthesis?",
      "url": "https://www.youtube.com/watch?v=E22APTvfwyE&t=7",
      "domain": null,
      "source": "YouTube",
      "snippet": "all organisms need energy from food animals get food they need by eating plants other animals or both plants and animals are also ..."
    },
    {
      "position": 3,
      "title": null,
      "url": "https://www.youtube.com/watch?v=CL9A8YhwUps&t=16",
      "domain": null,
      "source": "YouTube",
      "snippet": null
    }
  ],
  "products": null,
  "answer": null
}
```