# Search Google AI Mode

Returns Google AI Mode's answer to a question, with the sources it cites and any products it shows. Send its continuation token back to ask a follow-up.

Tool `google.serp.ai-mode` 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-mode/calls \
  -H "Authorization: Bearer $VOXORIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input":{"query":"i'\''m looking for a camera to use on holidays, i'\''d like to create both photos and videos, what is a beginner friendly camera for under $500 i should consider","language":"en"}}'
```

Python:

```python
import os

import httpx

response = httpx.post(
    "https://api.voxoria.ai/v1/tools/google.serp.ai-mode/calls",
    headers={"Authorization": f"Bearer {os.environ['VOXORIA_API_KEY']}"},
    json={
        "input": {
            "query": "i'm looking for a camera to use on holidays, i'd like to create both photos and videos, what is a beginner friendly camera for under $500 i should consider",
            "language": "en",
        },
    },
    timeout=60,
)
print(response.json())
```

TypeScript:

```ts
const response = await fetch("https://api.voxoria.ai/v1/tools/google.serp.ai-mode/calls", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VOXORIA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "input": {
      "query": "i'm looking for a camera to use on holidays, i'd like to create both photos and videos, what is a beginner friendly camera for under $500 i should consider",
      "language": "en",
    },
  }),
});
console.log(await response.json());
```

MCP (`tools/call` params):

```json
{
  "name": "call_tool",
  "arguments": {
    "tool": "google.serp.ai-mode",
    "input": {
      "query": "i'm looking for a camera to use on holidays, i'd like to create both photos and videos, what is a beginner friendly camera for under $500 i should consider",
      "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 question to ask. Required on every turn of a conversation. |
| `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 "Austin, Texas". |
| `device` | string | No | `desktop` | One of `desktop`, `mobile`, `tablet`. |
| `continuation_token` | string | No |  | Continues a conversation. Take it from conversation.continuation_token of the previous answer, and send the same country, language and location. Expires after 30 minutes. |

## 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 answer in reading order.

| 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 answer, 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 answer draws on. |

### products

A list of rows. Can be `null`. The products the answer 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 answer as one document. Null when the provider sends none.

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

### conversation

One object. Can be `null`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `continuation_token` | string | No | Send as continuation_token with the next question to follow up. Null when Google offers no follow-up. |

## Example output

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

```json
{
  "text_blocks": [
    {
      "type": "heading",
      "text": "Shared",
      "url": null,
      "image_url": null,
      "list_items": null,
      "table_header": null,
      "table_rows": null,
      "reference_positions": null
    },
    {
      "type": "paragraph",
      "text": "Finding a dedicated holiday camera for under $500 that handles both crisp photos and decent video means balancing ease-of-use with versatility. Brand-new traditional cameras under $500 are limited, but a few strong contenders hit the sweet spot for beginners.",
      "url": null,
      "image_url": null,
      "list_items": null,
      "table_header": null,
      "table_rows": null,
      "reference_positions": null
    },
    {
      "type": "paragraph",
      "text": "Often found bundled right around $450 - $499. This is an entry-level mirrorless camera that gives you the benefit of interchangeable lenses down the road. It has a great 24.2MP sensor for photos, reliable Canon autofocus, and straightforward guide modes for beginners. It does shoot 4K video, though with a heavy crop, so it shines brightest for 1080p travel vlogging and stunning still photography. You can look at deals on the Canon EOS R100 at Lowe's.",
      "url": null,
      "image_url": null,
      "list_items": null,
      "table_header": null,
      "table_rows": null,
      "reference_positions": null
    }
  ],
  "references": [
    {
      "position": 1,
      "title": "Canon EOS R100 Mirrorless Camera with 18-45mm Lens",
      "url": null,
      "domain": null,
      "source": "Google",
      "snippet": "The Canon EOS R100 is an entry-level mirrorless camera featuring a 24.2MP APS-C CMOS sensor and DIGIC 8 image processor. Capture s..."
    },
    {
      "position": 2,
      "title": "Canon PowerShot V10 Camera",
      "url": null,
      "domain": null,
      "source": "Google",
      "snippet": "Channel your on-the-go creativity with the Canon PowerShot V10 Vlogging Camera for Content Creators. The PowerShot V10 is a vlog a..."
    },
    {
      "position": 3,
      "title": "Canon EOS Rebel T7 Camera",
      "url": null,
      "domain": null,
      "source": "Google",
      "snippet": "Canon T7 EOS Rebel DSLR Camera** The Canon T7 EOS Rebel DSLR Camera, bundled with an EF-S 18-55mm f/3.5-5.6 IS II lens and a colle..."
    }
  ],
  "products": null,
  "answer": null,
  "conversation": {
    "continuation_token": "ai1.2lhjjikwDbgWZuF-VazLbRKimjN-n4Q1"
  }
}
```