Google AI Mode

Google AI Mode is Google’s conversational search experience: a follow-up-friendly, chat-style answer built on top of Search. Captures come from the live experience in a real browser, then normalize into the exact same Envelope every other surface returns, so one parser reads AI Mode, ChatGPT, Perplexity, and the rest.

Enum: google_ai_mode · Credits: 4 per successful capture · Typically returns: a conversational answer with provenance

What it returns

Section	Google AI Mode
`answer.text` / `answer.markdown`	Conversational answer (`markdown` always populated)
`answer.blocks[]`	Structured blocks, each typed with `text` and `referenceIds`
`provenance.model`	The observed model label and confidence
`provenance.surfacePresent`	Whether AI Mode returned an answer
`provenance.region`	Requested vs. effective region
`evidence.sources[]`	Cited/retrieved sources `answer.blocks[].referenceIds` point to (own-fleet, so `evidence.fanOut` is `none`)

Everything maps to the same fields, so your rendering logic never branches per surface. See Output formats for how text, markdown, and blocks relate.

Request

Add google_ai_mode to surfaces on POST /v1/search. A single-surface request with no webhook runs synchronously by default; add ?mode=async for the durable path — one child per surface × region.

curl -X POST "https://api.aisearchapi.dev/v1/search?mode=async" \
  -H "Authorization: Bearer $AISEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "best noise-cancelling headphones under $300",
    "surfaces": ["google_ai_mode"],
    "regions": [{ "country": "US" }]
  }'

const res = await fetch('https://api.aisearchapi.dev/v1/search?mode=async', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.AISEARCH_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    query: 'best noise-cancelling headphones under $300',
    surfaces: ['google_ai_mode'],
    regions: [{ country: 'US' }],
  }),
});

const { jobId, children } = await res.json();
console.log(jobId, children);

import os, requests

res = requests.post(
    "https://api.aisearchapi.dev/v1/search",
    params={"mode": "async"},
    headers={"Authorization": f"Bearer {os.environ['AISEARCH_API_KEY']}"},
    json={
        "query": "best noise-cancelling headphones under $300",
        "surfaces": ["google_ai_mode"],
        "regions": [{"country": "US"}],
    },
)
print(res.json())

The async call returns 202 with a parent job and one child id per surface × region:

{
  "jobId": "job_8t2q",
  "status": "processing",
  "children": ["job_8t2q.google_ai_mode.us"]
}

Fetch the child id (dotted) once it completes to get the Envelope:

curl https://api.aisearchapi.dev/v1/jobs/job_8t2q.google_ai_mode.us \
  -H "Authorization: Bearer $AISEARCH_API_KEY"

Sync alias

For a single surface and region, the alias POST /v1/search/google_ai_mode is sync-by-default (like any single-surface call) and returns the result inline (200, the Envelope in children[0]). It accepts prompt (an alias of query) and a flat country.

curl -X POST https://api.aisearchapi.dev/v1/search/google_ai_mode \
  -H "Authorization: Bearer $AISEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "best noise-cancelling headphones under $300",
    "country": "US"
  }'

const res = await fetch(
  'https://api.aisearchapi.dev/v1/search/google_ai_mode',
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.AISEARCH_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      prompt: 'best noise-cancelling headphones under $300',
      country: 'US',
    }),
  },
);

const result = await res.json();
console.log(result.children[0].answer.markdown);

Envelope (trimmed)

Every surface returns this shape, four sections: job, provenance, answer, evidence.

{
  "job": {
    "id": "job_8t2q.google_ai_mode.us",
    "query": "best noise-cancelling headphones under $300",
    "surface": "google_ai_mode",
    "region": "us",
    "status": "completed",
    "warnings": [],
    "requestedAt": "2026-06-27T00:00:00.000Z",
    "completedAt": "2026-06-27T00:00:05.100Z"
  },
  "provenance": {
    "model": {
      "providerId": null,
      "observedLabel": "AI Mode",
      "inferred": true,
      "confidence": 0.6
    },
    "webSearch": { "enabled": true, "known": true },
    "triggerState": "search",
    "persona": "anonymous_default_model",
    "loginState": "logged_out",
    "surfacePresent": true,
    "region": { "requested": "US", "effective": "US" },
    "capturedAt": "2026-06-27T00:00:05.000Z",
    "callUuid": "call_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
    "schemaVersion": "2026-06-27"
  },
  "answer": {
    "markdown": "For most people under $300, the **Sony WH-1000XM5** leads on cancellation and comfort, while the **Bose QuietComfort** is the pick if you want a lighter clamp.",
    "text": "For most people under $300, the Sony WH-1000XM5 leads on cancellation and comfort, while the Bose QuietComfort is the pick if you want a lighter clamp.",
    "blocks": [
      {
        "type": "paragraph",
        "text": "The Sony WH-1000XM5 leads on cancellation and comfort.",
        "referenceIds": [0]
      },
      {
        "type": "paragraph",
        "text": "The Bose QuietComfort is the pick for a lighter clamp.",
        "referenceIds": [1]
      }
    ]
  },
  "evidence": {
    "sources": [
      {
        "id": 0,
        "url": "https://www.sony.com",
        "title": "Sony WH-1000XM5",
        "role": "cited",
        "cited": true,
        "charRanges": [[22, 37]]
      },
      {
        "id": 1,
        "url": "https://www.bose.com",
        "title": "Bose QuietComfort",
        "role": "cited",
        "cited": true,
        "charRanges": [[92, 109]]
      }
    ],
    "fanOut": { "provenance": "none", "queries": [] },
    "mentions": null,
    "shopping": null,
    "ads": null
  }
}

If provenance.surfacePresent is false and the child carries a surface_absent warning, AI Mode returned nothing for that query. The job still completes with an empty answer. Parse it the same way and check surfacePresent before rendering.

Notes

Credits

Each successful google_ai_mode capture costs 4 credits, charged only on success. You start with 500 free credits.

Regions

Pass regions: [{ country, state?, city?, language? }] (ISO-3166 alpha-2; omitted means one untargeted GLOBAL capture). Each surface × region produces one child. Compare provenance.region.requested with effective to see whether the region was honored exactly. See Regions.

One parser, every surface

AI Mode, ChatGPT, Claude, Perplexity, Copilot, Google AI Overview, Google Search, and Google News all normalize to this Envelope. Write your rendering once against answer and every surface flows through it.

Output formats

How answer.text, answer.markdown, and answer.blocks[] relate.

Search endpoint

The full async request body, fields, and lifecycle.

Endpoints

Account & discovery

Watches

By surface

What it returns

Request

Sync alias

Envelope (trimmed)

Notes

Output formats

Search endpoint

​What it returns

​Request

​Sync alias

​Envelope (trimmed)

​Notes

Output formats

Search endpoint

What it returns

Request

Sync alias

Envelope (trimmed)

Notes