Google AI Mode API

Request

curl -X POST "https://api.answerline.dev/v1/monitor/aimode" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Family-friendly hotels in Lisbon","country":"PT","hl":"en"}'

Request options

* required. Nested fields are written with a dot, e.g. include.markdown.

What you get back

Full field definitions are in the API reference.

AI Mode answers versus Google’s developer APIs

Google AI Mode is Google Search’s conversational answer surface. This endpoint returns that answer for a prompt, market, city and language, with citation pills, places, map pins, shopping cards, videos and, when Google shows sponsored products, ads as structured fields. inlineProducts is in the schema and comes back empty: Google shows an inline product mention without a name or price.

Google’s long-standing developer route to search results is the Custom Search JSON API. Its overview (checked 2026-09-17, developers.google.com) says it returns web and image results from a Programmable Search Engine, offers 100 free queries per day and $5 per 1,000 beyond that up to 10,000 per day, is closed to new customers, and gives existing customers until January 1, 2027 to transition. Its cse.list reference (checked 2026-09-17, developers.google.com) documents gl, hl, cr and lr parameters and does not mention AI Overviews, ads, local packs or knowledge panels.

In AI Mode users read a composed response instead of scanning ten links, so whether your brand is named, and in which sentence, is the visibility metric. Citations appear as [Label +N] chips that bundle several sources; citationPills records every source behind every chip, so you can measure both “cited at all” and “cited first in a chip”. Products (shoppingCards), sponsored products (ads), local businesses (places, map) and videos sit inside the answer and vary by location and device.

An annotated response

The excerpt follows the result schema for POST /v1/monitor/aimode. Values are illustrative.

{
  "success": true,
  "result": {
    "text": "For families, look for hotels near the riverfront with interconnecting rooms...",
    "sources": [
      {
        "position": 1,
        "url": "https://www.example-travel.com/lisbon/family-hotels",
        "label": "Best family hotels in Lisbon",
        "description": "Rooms for four, pools and quiet streets..."
      }
    ],
    // One entry per (chip, source). citationPillId is 1-based; position points
    // into result.sources. redirectLink appears only when Google served a /goto link.
    "citationPills": [
      {
        "label": "Best family hotels in Lisbon",
        "citationPillId": 1,
        "url": "https://www.example-travel.com/lisbon/family-hotels",
        "domain": "example-travel.com",
        "position": 1
      }
    ],
    "places": [
      {
        "title": "Example Riverside Hotel",
        "link": "https://www.google.com/viewer/place?example",
        "placeId": "ChIJexampleLisbon",
        "index": 0,
        "rating": 4.6,
        "reviews": 2140,
        "type": "Hotel",
        "priceLevel": "€€€",
        "address": "Rua Exemplo 10, Lisboa"
      }
    ],
    "map": [
      {
        "title": "Example Riverside Hotel",
        "placeId": "ChIJexampleLisbon",
        "gps_coordinates": { "latitude": 38.707, "longitude": -9.136 },
        "rating": 4.6
      }
    ],
    // position is 0-indexed within the shopping carousel.
    "shoppingCards": [],
    // ads is an object: a section title plus the ads in it.
    "ads": { "title": "Sponsored", "ads": [] },
    "videos": [
      {
        "title": "Lisbon with kids: where to stay",
        "link": "https://www.youtube.com/watch?v=example",
        "platform": "YouTube",
        "channel": "Example Family Travel",
        "duration": "12:04"
      }
    ]
  }
}

Shape details to code for:

• ads is an object with title and ads[], not an array, and null when the answer shows no sponsored products. Each ad has title, url, position and store.
• shoppingCards[].position is 0-indexed; inlineProducts[].position is 1-indexed. Prices are objects: price.value is numeric, and price.raw keeps the displayed string on shopping cards.
• reviews is a string on shopping cards and ads, but an integer on places and map.
• redirectLink sits beside resolved links on sources, pills, snippet links, ads and videos. Resolve one yourself with POST /v1/monitor/google/goto, which is free and runs at most 4 calls per account at once.
• include.googleGoto is deprecated and ignored; redirect links are returned without it.

Synchronous calls

A synchronous call waits up to five minutes. It costs $0.00206 on every tier, the same as a task.

Python (httpx)

import os
import httpx

API = "https://api.answerline.dev"

with httpx.Client(base_url=API, headers={"Authorization": f"Bearer {os.environ['API_KEY']}"}, timeout=330) as client:
    resp = client.post("/v1/monitor/aimode", json={
        "prompt": "Family-friendly hotels in Lisbon",
        "country": "PT",
        "hl": "en",
    })
if resp.status_code != 200:
    raise RuntimeError(f"{resp.status_code} {resp.headers.get('X-Request-Id')} {resp.text}")

result = resp.json()["result"]
chips = {}
for pill in result.get("citationPills", []):
    chips.setdefault(pill["citationPillId"], []).append(pill["domain"])
print("chips:", chips)
print("places:", [(p.get("title"), p.get("rating")) for p in result.get("places", [])])
print("credits charged:", resp.headers.get("X-Credits-Charged"))

TypeScript (fetch)

const API = "https://api.answerline.dev";

const res = await fetch(`${API}/v1/monitor/aimode`, {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    prompt: "best standing desk for a small apartment",
    gl: "us",
    location: "Austin,Texas,United States",
    include: { markdown: true },
  }),
  signal: AbortSignal.timeout(330_000),
});
if (!res.ok) throw new Error(`${res.status} ${res.headers.get("X-Request-Id")} ${await res.text()}`);

const { result } = await res.json();
for (const card of result.shoppingCards ?? []) {
  console.log(card.position, card.title, card.price?.raw ?? card.price?.value, card.store);
}
for (const ad of result.ads?.ads ?? []) console.log("ad:", ad.position, ad.title, ad.store);

Batches: async tasks and a webhook

Tasks cost $0.00206 on every tier, wait in your queue until they start, and post to your webhook. POST /v1/async/task/batch takes 1 to 500 tasks, each admitted on its own and answered by index.

Python: a city grid

import datetime
import os
import requests

API = "https://api.answerline.dev"
HEADERS = {"Authorization": f"Bearer {os.environ['API_KEY']}"}
day = datetime.date.today().isoformat()

cities = ["Austin,Texas,United States", "Denver,Colorado,United States", "Seattle,Washington,United States"]
prompts = ["emergency plumber near me", "best pizza for delivery"]
tasks = [
    {
        "taskType": "AIMODE",
        "payload": {"prompt": prompt, "country": "US", "location": city},
        "idempotencyKey": f"aim-{i}-{city.split(',')[0].lower()}-{day}",
        "webhook": {"url": "https://your-app.example/hooks/answers"},
    }
    for i, prompt in enumerate(prompts)
    for city in cities
]

resp = requests.post(f"{API}/v1/async/task/batch", headers=HEADERS, json=tasks, timeout=60)
resp.raise_for_status()
body = resp.json()
print(body["summary"], "reserved:", sum(r["credits"]["creditsToCharge"] for r in body["results"] if r["success"]))

TypeScript: receive deliveries and check your listing (Express)

Each delivery is the GET /v1/async/task/{taskId} body. Verify Webhook-Signature over the raw body before parsing.

import express from "express";
import { createHmac, timingSafeEqual } from "node:crypto";

const MY_PLACE_IDS = new Set(["ChIJexampleLisbon"]);

function verify(raw: Buffer, header: string | undefined, secret: string, toleranceSeconds = 300): boolean {
  const pairs = (header ?? "").split(",").map((part) => part.split("="));
  const stamps = pairs.filter(([k]) => k === "t").map(([, v]) => v);
  const sigs = pairs.filter(([k]) => k === "v1").map(([, v]) => v);
  if (stamps.length !== 1 || !/^\d+$/.test(stamps[0]) || sigs.length === 0) return false;
  if (Math.abs(Date.now() / 1000 - Number(stamps[0])) > toleranceSeconds) return false;
  const expected = createHmac("sha256", secret).update(`${stamps[0]}.`).update(raw).digest();
  return sigs.some((sig) => {
    const given = Buffer.from(sig, "hex");
    return given.length === expected.length && timingSafeEqual(given, expected);
  });
}

const app = express();
app.post("/hooks/answers", express.raw({ type: "application/json" }), (req, res) => {
  if (!verify(req.body, req.get("webhook-signature"), process.env.WEBHOOK_SECRET!)) return res.sendStatus(400);
  const delivery = JSON.parse(req.body.toString("utf8"));
  if (delivery.test) return res.sendStatus(204);
  const { task, response } = delivery;
  if (task.status !== "COMPLETED") {
    console.warn(task.idempotencyKey, "failed:", response.error.code);
    return res.sendStatus(204);
  }
  const ranks = (response.result.places ?? []).filter((p: any) => MY_PLACE_IDS.has(p.placeId)).map((p: any) => p.index);
  console.log(task.idempotencyKey, ranks.length ? "listed at" : "not listed", ranks);
  res.sendStatus(204);
});
app.listen(3000);

Deduplicate on task.id; see webhooks.

Geo and language targeting

For a region or city below the country, use location (for example Texas,United States).

Include flags and what they cost

An AI Mode task is $2.06 per 1,000 on every tier.

Common workloads

• AI visibility tracking in Google’s conversational search. See AI visibility tracking and the AI Mode API post.
• Local rank tracking: position of your business in places by city. See local rank tracking.
• Rank tracking beyond blue links: pair AI Mode with Google Search results for the same keyword. See rank tracking.
• Competitor and shelf analysis: which stores and products appear in shoppingCards and sponsored ads. See competitor analysis.

Pitfalls

location expects Google’s canonical City,Region,Country names from the Google Ads geotargets list. Copy names from that list instead of typing them, and keep a vetted list per client.

hl overrides the language derived from the country. When comparing markets, set hl explicitly; see multilingual AI answers.

shoppingCards[].position starts at 0 and inlineProducts[].position at 1. Normalize before storing ranks.

A city grid grows fast: 2 prompts × 3 cities is 6 tasks per day before repeated samples, and answers vary enough between runs that you want several per combination (AI answer volatility). There is no concurrency cap and no request rate limit; tasks queue (about 100,000 tasks of a typical prompt at a time). See rate limits.

How failures are billed

Accepted requests reserve their maximum cost (credits.creditsToCharge) and are charged the actual cost on success (credits.creditsCharged, or X-Credits-Charged on a synchronous call), never more than reserved. A failed request is charged nothing and its reservation is released, including tasks that never start within 4 hours (QUEUE_WAIT_EXCEEDED). Synchronous calls may complete and be charged after a dropped connection, so resend only if the request never reached the server. See credits.

Related: getting AI Mode answers as JSON and monitoring Google AI Overviews.

Other engines