# Google Search Ai Mode (`ilborso/google-search-ai-mode`) Actor

Fetch AI-generated answers from Google AI Mode. The actor returns structured text blocks, inline references, and shopping results as clean JSON pushed to an Apify Dataset.

- **URL**: https://apify.com/ilborso/google-search-ai-mode.md
- **Developed by:** [Fabio Borsotti](https://apify.com/ilborso) (community)
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.90 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Google Search AI Mode — Apify Actor

Fetch **AI-generated answers** from [Google AI Mode](https://blog.google/products/search/ai-mode-search/). The actor returns structured text blocks, inline references, and shopping results as clean JSON pushed to an Apify Dataset.

Google AI Mode is a conversational search surface that returns a **full AI-generated response** as the primary content — instead of a traditional list of blue links. The response includes paragraphs, headings, ordered/unordered lists, reference cards, cited sources, and (when relevant) shopping product cards with pricing.

***

### Input Parameters

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `q` | string | **Yes** | — | Search query. URL-encode spaces and special characters. Example: `best+noise+cancelling+headphones+2025` |
| `device` | string | No | `desktop` | Device type. Accepted values: `desktop`, `mobile`. |
| `include_html` | boolean | No | `false` | When `true`, the raw async HTML is included in the response `html` field. |
| `hl` | string | No | `en` | **Host Language.** Controls the language of the Google UI. ISO 639-1 codes. Examples: `tr`, `de`, `fr`, `ja`. |
| `gl` | string | No | `us` | **Geo Location.** Country perspective for results. ISO 3166-1 alpha-2 codes. Examples: `tr`, `de`, `gb`. |
| `google_domain` | string | No | `google.com` | Google domain to query. Examples: `google.com.tr`, `google.de`, `google.co.uk`. |
| `location` | string | No | — | Location name in Google's canonical format. Examples: `Istanbul,Istanbul,Turkey`, `New York,New York,United States`. |
| `uule` | string | No | — | Google UULE-encoded location string. Auto-generated from `location` when not provided. |
| `safe` | string | No | `""` | **SafeSearch.** Accepted values: `""` (disabled / not set), `"active"` (filter adult content). |

#### Example Input

```json
{
    "q": "best noise cancelling headphones 2025",
    "device": "desktop",
    "hl": "en",
    "gl": "us",
    "google_domain": "google.com"
}
```

***

### Output Structure

The actor pushes the **full JSON response** to the Apify Dataset. The top-level structure is:

#### Top-Level Fields

| Field | Type | When Empty | Description |
|---|---|---|---|
| `search_parameters` | object | Always present | Echo of the request parameters used for the search. |
| `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`. |

> **Note:** 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.

***

#### `search_parameters` Object

| Field | Type | Description |
|---|---|---|
| `q` | string | The search query that was used. |
| `hl` | string | Host language code. |
| `gl` | string | Geo location code. |
| `device` | string | Device type used (`desktop` or `mobile`). |
| `google_domain` | string | Google domain queried. |

***

#### `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). |

##### SnippetLink Object

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

##### 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 — recursive (optional). |
| `reference_indexes` | array of int | Indexes into the `references` array (optional). |

##### 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. |

***

### Example Output

```json
{
    "search_parameters": {
        "q": "what is an MCP server for AI?",
        "hl": "en",
        "gl": "us",
        "device": "mobile",
        "google_domain": "google.com"
    },
    "text_blocks": [
        {
            "type": "paragraph",
            "snippet": "AI Mode reply for what is an MCP server for AI?"
        },
        {
            "type": "paragraph",
            "snippet": "An MCP (Model Context Protocol) server is a software program that acts as a universal adapter for artificial intelligence..."
        },
        {
            "type": "heading",
            "snippet": "How the MCP architecture works",
            "level": 3
        },
        {
            "type": "list",
            "list": [
                {
                    "snippet": "The AI Host: The application the user interacts with directly.",
                    "snippet_links": [
                        { "text": "Cursor IDE", "link": "/goto?url=..." },
                        { "text": "Microsoft Copilot", "link": "/goto?url=..." }
                    ]
                },
                {
                    "snippet": "The MCP Client: The component integrated within the AI app."
                },
                {
                    "snippet": "The MCP Server: The service that translates external-world data."
                }
            ],
            "reference_indexes": [0]
        }
    ],
    "references": [
        {
            "title": "What is the Model Context Protocol?",
            "link": "https://cloud.google.com/discover/what-is-model-context-protocol",
            "snippet": "Uses JSON-RPC 2.0 messages to communicate between client and server...",
            "source": "Google Cloud",
            "source_icon": "https://encrypted-tbn0.gstatic.com/faviconV2?url=https://cloud.google.com&...",
            "index": 0
        },
        {
            "title": "What is the Model Context Protocol (MCP)?",
            "link": "https://www.redhat.com/en/topics/ai/what-is-model-context-protocol-mcp",
            "snippet": "",
            "source": "Red Hat",
            "index": 1
        }
    ],
    "shopping_results": []
}
```

***

### Error Handling

The actor fails with a descriptive message when:

| Condition | Actor Behavior |
|---|---|
| `q` input parameter missing or empty | Actor fails immediately with a validation error. |
| `device` not `desktop` or `mobile` | Actor fails immediately with a validation error. |
| Scrape.do API returns HTTP 4xx/5xx | Actor fails with the HTTP status and response body preview. |
| Network timeout or error | Actor fails with the network error details. |
| Invalid JSON response | Actor fails with a parse error message. |

#### Scrape.do API Error Codes

| Status | Body | Cause |
|---|---|---|
| `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 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. |

***

# Actor input Schema

## `q` (type: `string`):

Search query. URL-encode spaces and special characters. Example: best+noise+cancelling+headphones+2025

## `device` (type: `string`):

Device type for the search. Accepted values: desktop, mobile.

## `include_html` (type: `boolean`):

When true, the raw HTML is included in the response 'html' field.

## `hl` (type: `string`):

Controls the language of the Google UI. ISO 639-1 codes. Examples: en, tr, de, fr, ja.

## `gl` (type: `string`):

Country perspective for results. ISO 3166-1 alpha-2 codes. Examples: us, tr, de, gb.

## `google_domain` (type: `string`):

Google domain to query. Examples: google.com, google.com.tr, google.de, google.co.uk.

## `location` (type: `string`):

Location name in Google's canonical format. Examples: Istanbul,Istanbul,Turkey or New York,New York,United States.

## `uule` (type: `string`):

Google UULE-encoded location string. Auto-generated from 'location' when not provided.

## `safe` (type: `string`):

Send 'active' to filter adult content from search results.

## Actor input object example

```json
{
  "device": "desktop",
  "include_html": false,
  "hl": "en",
  "gl": "us",
  "google_domain": "google.com"
}
```

# Actor output Schema

## `aiModeResults` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "gl": "us",
    "google_domain": "google.com"
};

// Run the Actor and wait for it to finish
const run = await client.actor("ilborso/google-search-ai-mode").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "gl": "us",
    "google_domain": "google.com",
}

# Run the Actor and wait for it to finish
run = client.actor("ilborso/google-search-ai-mode").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "gl": "us",
  "google_domain": "google.com"
}' |
apify call ilborso/google-search-ai-mode --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,ilborso/google-search-ai-mode"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/dQtEcDSQZnBzA8hcS/builds/kco2fO4hiooidh8iM/openapi.json