# AI Mode

> Source: https://scrape.do/documentation/google-scraper-api/search/ai-mode/

Get AI-generated answers with references and shopping results from Google AI Mode

Google AI Mode is a conversational search mode that returns a full AI-generated response as the primary content, rather than traditional search results. Instead of a list of links, you get structured text blocks with inline references, shopping results, and detailed answers.

The endpoint fetches Google's AI Mode async payload directly, so JavaScript rendering is not required. There is no render fee, and latency is lower than a full-browser scrape.

---

## Endpoint

```
GET https://api.scrape.do/plugin/google/search/ai-mode
```

> [!NOTE]
> **Credit cost: 10 credits** per successful AI Mode response. If Google does not return AI Mode content for the query, the response contains empty arrays and is not charged.

## How It Works

AI Mode is a two-step flow on Google's side. The first Google response carries short-lived tokens, and the AI-generated content is returned by a follow-up async endpoint. Scrape.do handles both hops internally and retries transient upstream failures with a fresh session before returning an error.

Not every query is eligible for AI Mode. Google A/B-tests this surface heavily, so the same query can return AI Mode content on one request and no AI Mode content on another.

---

## Request Parameters

### Required

| Parameter | Type | Description |
|-----------|------|-------------|
| `token` | string | Your Scrape.do API authentication token |
| `q` | string | Search query. URL-encode spaces and special characters. `best+noise+cancelling+headphones+2025` |

### General

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `device` | string | `desktop` | Device type. Accepted values: `desktop`, `mobile` |
| `include_html` | boolean | `false` | When `true`, the raw HTML is included in the response `html` field |

### Localization & Geo-targeting

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `hl` | string | `en` | **Host Language.** Controls the language of the Google UI. ISO 639-1 codes. Examples: `tr`, `de`, `fr`, `ja`. [Full list →](/documentation/google-scraper-api/localization#language-parameter-hl) |
| `gl` | string | `us` | **Geo Location.** Country perspective for results. ISO 3166-1 alpha-2 codes. Examples: `tr`, `de`, `gb`. [Full list →](/documentation/google-scraper-api/localization#country-parameter-gl) |
| `google_domain` | string | `google.com` | Google domain to query. Examples: `google.com.tr`, `google.de`, `google.co.uk`. [Full list →](/documentation/google-scraper-api/localization#supported-google-domains) |
| `location` | string | - | Location name in Google's canonical format. Examples: `Istanbul,Istanbul,Turkey`, `New York,New York,United States` |
| `uule` | string | - | Google UULE-encoded location string. Auto-generated from `location` when not provided |

### Filtering

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `safe` | string | - | **SafeSearch.** Send `active` to filter adult content |

---

## Example Usage

### Step 1: Define Your Search Query

AI Mode works best with informational and research-oriented queries:
- **Product research**: `best noise cancelling headphones 2025`
- **Explanations**: `how does mRNA vaccine work`
- **Comparisons**: `python vs javascript for beginners`

For this example, we'll search for "best noise cancelling headphones 2025":

### Step 2: Send the API Request

**cURL (API mode)**

```bash
curl --location --request GET 'https://api.scrape.do/plugin/google/search/ai-mode?token=<SDO-token>&q=best+noise+cancelling+headphones+2025'
```

**Python (API mode)**

```python
import requests
import json

token = "<SDO-token>"
query = "best+noise+cancelling+headphones+2025"

url = f"https://api.scrape.do/plugin/google/search/ai-mode?token={token}&q={query}"

response = requests.request("GET", url)

print(json.dumps(response.json(), indent=2))
```

**Node.js (API mode)**

```javascript
const axios = require('axios');

const token = "<SDO-token>";
const query = "best+noise+cancelling+headphones+2025";

const url = `https://api.scrape.do/plugin/google/search/ai-mode?token=${token}&q=${query}`;

axios.get(url)
  .then(response => {
    console.log(JSON.stringify(response.data, null, 2));
  })
  .catch(error => {
    console.error(error);
  });
```

*(Go, Ruby, Java, C#, PHP examples are also available on the HTML version.)*

### Step 3: Receive AI-Generated Results

The API returns a JSON object with the AI-generated response structured into text blocks, references, and optional shopping results:

```json
{
  "search_parameters": {
    "q": "best noise cancelling headphones 2025",
    "hl": "en",
    "gl": "us",
    "device": "desktop",
    "google_domain": "google.com"
  },
  "text_blocks": [
    {
      "type": "paragraph",
      "snippet": "For 2025, the noise-cancelling headphone market is dominated by the Sony WH-1000XM6, which launched in May 2025 as the new industry leader.",
      "snippet_links": [
        { "text": "Sony WH-1000XM6", "link": "https://example.com/sony" }
      ],
      "reference_indexes": [0, 1, 2]
    },
    {
      "type": "heading",
      "snippet": "Top Over-Ear Recommendations",
      "level": 3
    },
    {
      "type": "list",
      "list": [
        {
          "snippet": "Sony WH-1000XM6 — best overall noise cancellation",
          "reference_indexes": [0]
        },
        {
          "snippet": "Bose QuietComfort Ultra — best comfort for long wear",
          "reference_indexes": [1]
        }
      ]
    }
  ],
  "references": [
    {
      "title": "Sony WH-1000XM6 Review",
      "link": "https://example.com/sony-review",
      "snippet": "The XM6 offers industry-leading ANC...",
      "source": "TechRadar",
      "source_icon": "https://example.com/techradar-icon.png",
      "index": 0
    },
    {
      "title": "Bose QC Ultra Review",
      "link": "https://example.com/bose-review",
      "snippet": "Bose's latest flagship...",
      "source": "RTINGS",
      "index": 1
    }
  ],
  "shopping_results": [
    {
      "title": "Sony WH-1000XM6",
      "product_link": "https://example.com/buy-sony",
      "thumbnail": "https://example.com/sony.jpg",
      "price": "$399.99",
      "extracted_price": 399.99,
      "old_price": "$460.00",
      "extracted_old_price": 460.00,
      "source": "Sony",
      "rating": 4.7,
      "reviews": 5300,
      "index": 0
    }
  ]
}
```

---

## Response Structure

### Top-Level Fields

| Field | Type | When Empty | Description |
|-------|------|------------|-------------|
| `search_parameters` | object | always present | Echo of the request parameters |
| `text_blocks` | array | `[]` | AI-generated content blocks (paragraphs, headings, lists, reference cards) |
| `references` | array | `[]` | Sources cited by the AI response |
| `shopping_results` | array | `[]` | Product results with pricing (when relevant) |
| `html` | string | omitted | Raw HTML. Only present when `include_html=true` |

When Google has no AI Mode content for a query, the endpoint returns `200` with empty `text_blocks`, `references`, and `shopping_results`. This is not treated as an error and is not charged.

---

### text_blocks[]

The AI response is structured as an ordered array of content blocks. Each block has a `type` that determines which fields are present.

| Field | Type | Description |
|-------|------|-------------|
| `type` | string | `"heading"`, `"paragraph"`, `"list"`, `"ordered_list"`, or `"reference_cards"` |
| `snippet` | string | Text content (for headings and paragraphs) |
| `level` | integer | Heading level, e.g. `3` (only when `type=heading`) |
| `snippet_links` | array | Inline links within the snippet (optional) |
| `list` | array | List items when `type=list` or `type=ordered_list` (optional) |
| `cards` | array | Reference preview cards when `type=reference_cards` (optional) |
| `reference_indexes` | array of int | Indexes into the `references` array (optional) |

#### ListItem Object

| Field | Type | Description |
|-------|------|-------------|
| `snippet` | string | Item text |
| `snippet_links` | array | Inline links (optional) |
| `shopping_result` | object | Embedded shopping result (optional) |
| `list` | array | Nested sub-items (optional, recursive) |
| `reference_indexes` | array of int | Indexes into the `references` array (optional) |

#### SnippetLink Object

| Field | Type | Description |
|-------|------|-------------|
| `text` | string | Link text |
| `link` | string | URL |

#### ReferenceCard Object

| Field | Type | Description |
|-------|------|-------------|
| `title` | string | Card title |
| `link` | string | URL |
| `snippet` | string | Preview text (optional) |

---

### references[]

Sources cited by the AI-generated response. Each reference has an `index` that text blocks point to via `reference_indexes`.

| Field | Type | Description |
|-------|------|-------------|
| `title` | string | Page title |
| `link` | string | URL |
| `snippet` | string | Description excerpt |
| `source` | string | Domain or site name |
| `source_icon` | string | Favicon URL (optional) |
| `thumbnail` | string | Preview image URL (optional) |
| `index` | integer | Position index |

---

### shopping_results[]

Product results with pricing and ratings. Present when the query has commercial intent.

| Field | Type | Description |
|-------|------|-------------|
| `title` | string | Product name |
| `product_link` | string | Product URL |
| `thumbnail` | string | Image URL (optional) |
| `price` | string | Display price, e.g. `"$399.99"` (optional) |
| `extracted_price` | float | Numeric price (optional) |
| `old_price` | string | Original price before discount (optional) |
| `extracted_old_price` | float | Numeric old price (optional) |
| `source` | string | Retailer name (optional) |
| `rating` | float | Star rating (optional) |
| `reviews` | integer | Review count (optional) |
| `index` | integer | Position index |

---

## Error Responses

| Status | Body | Cause |
|--------|------|-------|
| `400` | `{ "error": "token is required" }` | Missing `token` parameter |
| `400` | `{ "error": "q (search query) is required" }` | Missing `q` parameter |
| `400` | `{ "error": "device must be one of: desktop, mobile" }` | Invalid `device` value |
| `400` | `{ "error": "invalid google_domain" }` | Unsupported Google domain |
| `502` | `{ "error": "request failed" }` | Transient upstream Google request failure after retries. Not charged. |
| `502` | `{ "error": "folwr request failed" }` | Transient follow-up fetch failure after retries. Not charged. |
| `500` | `{ "error": "failed to parse AI Mode results" }` | Parser error. Retry the request, and contact support if it persists. |

---

## Differences from AI Overview

| | AI Overview | AI Mode |
|---|---|---|
| Trigger | Automatic on regular SERP | Dedicated endpoint |
| Endpoint | `/plugin/google/search` | `/plugin/google/search/ai-mode` |
| Content | Optional panel within SERP results | Full AI response (primary content) |
| Shopping results | No | Yes (when relevant) |
| Headings | No | Yes (`type=heading`) |
| Ordered lists | No | Yes (`type=ordered_list`) |
| Reference cards | No | Yes (`type=reference_cards`) |
| Credits | Same as SERP (or 5 for deferred follow-up) | 10 |

---

## Example Requests

**Basic AI Mode search:**
```
/plugin/google/search/ai-mode?token=TOKEN&q=best+noise+cancelling+headphones+2025
```

**Turkish results from Turkey:**
```
/plugin/google/search/ai-mode?token=TOKEN&q=en+iyi+kulaklık&hl=tr&gl=tr&google_domain=google.com.tr
```

**Location-targeted search:**
```
/plugin/google/search/ai-mode?token=TOKEN&q=best+restaurants&location=New+York,New+York,United+States
```

**Mobile device:**
```
/plugin/google/search/ai-mode?token=TOKEN&q=python+vs+javascript&device=mobile
```

**SafeSearch enabled:**
```
/plugin/google/search/ai-mode?token=TOKEN&q=family+friendly+movies&safe=active
```

**Include raw async HTML:**
```
/plugin/google/search/ai-mode?token=TOKEN&q=tea+vs+coffee+caffeine&include_html=true
```

> [!WARNING]
> Search queries must be URL-encoded. Treat every AI Mode field as optional because Google can vary the response shape, references, and shopping cards across requests.

---

## Scraping an AI Mode URL Directly

If you scrape an AI Mode search URL through the standard API instead of this endpoint — anything matching `google.*/search?...&udm=50` — you get the page's HTML back, with the AI Mode answer already included:

```bash
curl "https://api.scrape.do/?token=YOUR_TOKEN&url=https%3A%2F%2Fwww.google.com%2Fsearch%3Fq%3Dbest%2Brunning%2Bshoes%26gl%3Dus%26hl%3Den%26udm%3D50"
```

Google serves that page as a shell and loads the answer separately once the page is open, so the raw HTML Google returns first contains **no** answer text. The API completes that second step for you and merges the result into the HTML inside a container you can select on:

```html
<div id="scrapedo-ai-mode" data-subtree="aimfl"> … answer markup … </div>
```

Points worth knowing:

- **`render=true` is not needed and is ignored** on these URLs. The answer is retrieved without a browser, so you are not charged a render fee.
- **The answer is not always there.** When Google returns no AI Mode content for the query, you get the page HTML without the `scrapedo-ai-mode` container. Check for it before parsing.
- **Expect the HTML to be large** — roughly double the page without the answer, typically ~1 MB.
- **`cache=true` works on these URLs**, with a shorter lifetime than usual: a cached AI Mode page expires after **1 hour**, because the answer is a point-in-time synthesis that Google refreshes. A cache hit returns the merged page without re-fetching anything.
- **Use this endpoint instead when you want structured data.** Scraping the URL gives you Google's raw markup, whose class names change without warning; `/plugin/google/search/ai-mode` returns parsed text blocks and references and is the stable contract.