# Google AI Mode ## Overview | Property | Value | |----------|-------| | **Status** | active | | **Method** | `GET` | | **Endpoint** | `/v2/google/search/ai` | | **Base URL** | `https://api.autom.dev` | | **Credit Cost** | 3 credits per call | | **Documentation** | https://www.piloterr.com/library/google-search-ai | ## Description Scrape real-time Google AI Mode answers: text_blocks, references, and shopping_results. ## Authentication - **Key Name:** `x-api-key` - **Location:** HTTP Header - **Get an API key:** https://app.autom.dev/register ## Example Request ```bash curl --location --request GET 'https://api.autom.dev/v2/google/search/ai' \ --header 'Content-Type: application/json' \ --header 'x-api-key: YOUR_API_KEY' ``` ## Example Response ### AI Mode 'what is mozilla firefox'. US/English ```json { "references": [ { "link": "https://www.mozilla.org/firefox/", "index": 0, "title": "Firefox Browser", "source": "mozilla.org", "snippet": "Official Firefox download and overview.", "thumbnail": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcFirefoxThumb", "source_icon": "https://www.google.com/s2/favicons?domain=mozilla.org&sz=128" }, { "link": "https://en.wikipedia.org/wiki/Firefox", "index": 1, "title": "Firefox - Wikipedia", "source": "en.wikipedia.org" } ], "text_blocks": [ { "type": "paragraph", "snippet": "Mozilla Firefox is a free, open-source web browser developed by the Mozilla Foundation. It is available on desktop and mobile, supports extensions, and focuses on privacy controls such as Enhanced Tracking Protection." }, { "type": "heading", "level": 3, "snippet": "Key features" }, { "list": [ { "title": "Open source", "snippet": "Free and open-source, maintained by the Mozilla Foundation.", "snippet_links": [ { "link": "https://www.mozilla.org/", "text": "Mozilla Foundation" } ], "reference_indexes": [ 0 ] }, { "snippet": "Available on desktop and mobile platforms." }, { "snippet": "Enhanced Tracking Protection to limit cross-site tracking." } ], "type": "list" } ], "shopping_results": [], "search_parameters": { "q": "what is mozilla firefox", "gl": "us", "hl": "en", "engine": "google_ai_mode" }, "reconstructed_markdown": "Mozilla Firefox is a free, open-source web browser developed by the Mozilla Foundation. It is available on desktop and mobile, supports extensions, and focuses on privacy controls such as Enhanced Tracking Protection.\n\n### Key features\n\n- Free and open-source, maintained by the Mozilla Foundation.\n- Available on desktop and mobile platforms.\n- Enhanced Tracking Protection to limit cross-site tracking." } ``` ### AI Mode 'meilleure machine espresso 2026'. Paris/French ```json { "references": [ { "link": "https://www.example.com/espresso-2026", "index": 0, "title": "Guide machines espresso", "source": "example.com" } ], "text_blocks": [ { "type": "paragraph", "snippet": "Les machines espresso les plus citées en 2026 mélangent modèles super-automatiques et machines à levier pour un usage quotidien. Les critères récurrents sont la stabilité thermique, la facilité d'entretien et le rapport qualité-prix." } ], "shopping_results": [], "search_parameters": { "q": "meilleure machine espresso 2026", "gl": "fr", "hl": "fr", "engine": "google_ai_mode", "location": "Paris, France" }, "reconstructed_markdown": "Les machines espresso les plus citées en 2026 mélangent modèles super-automatiques et machines à levier pour un usage quotidien. Les critères récurrents sont la stabilité thermique, la facilité d'entretien et le rapport qualité-prix." } ``` ### AI Mode 'antoine'. US/English ```json { "references": [], "text_blocks": [ { "type": "paragraph", "snippet": "It looks like your message was just a single name. Depending on what you're looking for, Antoine can refer to a few different things:" }, { "type": "paragraph", "snippet": "Could you tell me which Antoine you are looking for or what specific information you need?" } ], "shopping_results": [], "search_parameters": { "q": "antoine", "gl": "us", "hl": "en", "engine": "google_ai_mode" }, "reconstructed_markdown": "It looks like your message was just a single name. Depending on what you're looking for, Antoine can refer to a few different things:\n\nCould you tell me which Antoine you are looking for or what specific information you need?" } ``` ### No AI Mode answer ```json { "error": "Google hasn't returned an AI Mode answer for this query.", "references": [], "text_blocks": [], "shopping_results": [], "search_parameters": { "q": "xyzzyplugh undeliverable query", "gl": "us", "hl": "en", "engine": "google_ai_mode" } } ``` ### AI Mode 'best noise cancelling headphones 2026'. US/English ```json { "references": [ { "link": "https://www.google.com", "index": 0, "title": "Bose QuietComfort Ultra Wireless Headphones", "source": "Google", "snippet": "Bose QuietComfort Ultra Headphones 2nd Gen deliver personalized sound with CustomTune that adapts to your ears for a premium liste...", "thumbnail": "https://encrypted-tbn3.gstatic.com/images?q=tbn:ANd9GcTgnGBPjPkitJyM9rsKloenNol_0MQxwOwQ_zguvFfxiSEodDWIjdPUIWEZymcgpE_YVoOluaR75vPHIdI", "source_icon": "https://encrypted-tbn1.gstatic.com/faviconV2?url=https://www.google.com&client=AIM&size=128&type=FAVICON&fallback_opts=TYPE,SIZE,URL" } ], "text_blocks": [ { "type": "paragraph", "snippet": "The landscape for active noise-cancelling (ANC) over-ear headphones features standout heavyweights delivering top-tier isolation, rich sound profiles, and all-day comfort." }, { "type": "paragraph", "snippet": "Here are the top picks for the best noise-cancelling headphones:" }, { "list": [ { "snippet": "Bose QuietComfort Ultra Headphones (2nd Gen): Widely considered the gold standard for pure silence. The CustomTune technology auto-calibrates ANC and sound performance to your specific ear shape. It features class-leading \"Quiet Mode\" and spatialized Bose Immersive Audio, alongside a comfortable build and up to 30 hours of battery life (about 23–24 hours with immersive audio enabled). Check options and pricing directly on the Bose Store.", "shopping_result": { "title": "Bose QuietComfort Ultra Wireless Headphones", "source": "Google", "thumbnail": "https://encrypted-tbn3.gstatic.com/images?q=tbn:ANd9GcTgnGBPjPkitJyM9rsKloenNol_0MQxwOwQ_zguvFfxiSEodDWIjdPUIWEZymcgpE_YVoOluaR75vPHIdI", "product_link": "https://www.google.com/search?q=product&prds=pvt:hg,productid:13548375814046357679,catalogid:5935180288566721863,gpcid:3222417658520627649,mid:576462841335551667&ibp=oshop" }, "reference_indexes": [ 0 ] } ], "type": "list" } ], "shopping_results": [ { "index": 0, "title": "Bose QuietComfort Ultra Wireless Headphones", "source": "Google", "thumbnail": "https://encrypted-tbn3.gstatic.com/images?q=tbn:ANd9GcTgnGBPjPkitJyM9rsKloenNol_0MQxwOwQ_zguvFfxiSEodDWIjdPUIWEZymcgpE_YVoOluaR75vPHIdI", "product_link": "https://www.google.com/search?q=product&prds=pvt:hg,productid:13548375814046357679,catalogid:5935180288566721863,gpcid:3222417658520627649,mid:576462841335551667&ibp=oshop" }, { "index": 1, "title": "Sony WH-1000XM6 Wireless Noise Canceling Headphones", "source": "Google", "thumbnail": "https://encrypted-tbn1.gstatic.com/images?q=tbn:ANd9GcT2uMw-0SbIbDoJEVqb8ywtZFPemCDzpob9t9YeaabiUq-n-LGmmge3rKJx0Rs7D8jrvqzHWXTJ0lHrmf0", "product_link": "https://www.google.com/search?q=product&prds=pvt:hg,productid:6627216456244837110,catalogid:530011814861709152,gpcid:16337411903393755079,mid:576462827077625129&ibp=oshop" } ], "search_parameters": { "q": "best noise cancelling headphones 2026", "gl": "us", "hl": "en", "engine": "google_ai_mode" }, "reconstructed_markdown": "The landscape for active noise-cancelling (ANC) over-ear headphones features standout heavyweights delivering top-tier isolation, rich sound profiles, and all-day comfort." } ``` ## Documentation ## Overview Query Google AI Mode for a natural-language question or search query. The response always includes `search_parameters`, `text_blocks`, `references`, and `shopping_results`. This endpoint is **active**. The response shape may evolve. Pair with [Google Search](https://www.piloterr.com/library/google-search) when you also need organic listings. ## Quickstart ``` POST https://api.piloterr.com/v2/google/search/ai Content-Type: application/json {"query": "what is mozilla firefox", "gl": "us", "hl": "en"} ``` GET and POST are supported. On GET, pass parameters in the query string. On POST, send the same fields as a JSON body. ``` GET https://api.piloterr.com/v2/google/search/ai?query=what+is+mozilla+firefox&gl=us&hl=en ``` ## Parameters | Parameter | Type | Required | Description | |---|---|---|---| | `query` | string | yes | Question or search query for Google AI Mode. | | `location` | string | no | City-level location (mutually exclusive with `uule`) | | `uule` | string | no | Google-encoded location (mutually exclusive with `location`) | | `gl` | string | no | 2-letter country code e.g. `us`, `fr`, `gb` | | `hl` | string | no | 2-letter language code e.g. `en`, `fr`, `de` | ## Response fields | Field | Type | Description | |---|---|---| | `search_parameters.engine` | string | Always `google_ai_mode` | | `search_parameters.q` | string | Echoed search query | | `search_parameters.gl` | string | Country code | | `search_parameters.hl` | string | Language code | | `search_parameters.location` | string | Human-readable location when set | | `search_parameters.uule` | string | Encoded location when set | | `text_blocks[]` | array | Always present. Types: `paragraph`, `heading`, `list`, `ordered_list` | | `text_blocks[].snippet` | string | Block text. Headings also include `level` | | `text_blocks[].list[]` | array | Items for `list` and `ordered_list`. Optional `title`, `snippet`, `snippet_links`, `reference_indexes`, `shopping_result` | | `reconstructed_markdown` | string | Markdown reconstruction. Omitted when the answer is empty | | `references[]` | array | Always present | | `references[].title` | string | Source title | | `references[].link` | string | Cited page URL. A Google redirect is resolved; the destination is not re-encoded | | `references[].source` | string | Source site name | | `references[].index` | number | 0-based citation index | | `references[].snippet` | string | Source excerpt, when present | | `references[].source_icon` | string | Favicon URL, when present | | `references[].thumbnail` | string | Thumbnail URL, when present | | `shopping_results[]` | array | Always present. Product cards, or `[]` | | `shopping_results[].title` | string | Product name | | `shopping_results[].product_link` | string | Product URL as returned, often a Google Shopping `prds` link | | `shopping_results[].source` | string | Seller or source label, when present | | `shopping_results[].thumbnail` | string | Image URL, when present | | `shopping_results[].price` | string | Display price, when Google includes it | | `shopping_results[].extracted_price` | number | Numeric price, when present | | `shopping_results[].old_price` | string | Previous display price, when present | | `shopping_results[].extracted_old_price` | number | Numeric previous price, when present | | `shopping_results[].rating` | number | Star rating, when present | | `shopping_results[].reviews` | number | Review count, when present | | `shopping_results[].index` | number | 0-based product index | | `error` | string | Only when the AI Mode page could not be fetched | ## Notes - Status: active. Response structure may evolve. - Cost: 3 credits per call - `location` and `uule` are mutually exclusive: use only one at a time - Unset `location` / `uule` are omitted from `search_parameters` - A fetched page with no answer content returns empty `text_blocks`, `references`, and `shopping_results`, without `error` - HTTP `400` when `query` is missing - HTTP `500` on fetch or parse failure ## Main use cases - Archive AI Mode answers for a keyword set - Extract cited domains and links for citation checks - Pull structured summaries for research pipelines - Compare AI Mode answers over time, country, and language