Google Search AI Mode — Apify 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.

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

{
    "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

{
    "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.

---