# Track AI Mode answers

`POST https://api.answerline.dev/v1/monitor/aimode`

Get structured output from AI Mode on your brand, your products or any other topic, in many regions

From $2.06 per 1,000 requests. Failed requests are free. Also runs as an async task of type `AIMODE`.

## Body

- `prompt` (string, required): Prompt submitted to Google AI Mode, up to 2,000 characters. A longer prompt is refused with a 400 that states its length.
- `country` (string): Code of the country or region used to localize the response
- `gl` (string): Google's own name for the result-geography parameter, usable in place of `country`. Takes ISO 3166-1 alpha-2 codes, as `country` does, in upper or lower case (`us` or `US`), and the country has to be one this endpoint supports (list them with `GET /v1/countries`; Google News has no `model` value there, and its edition countries are listed at https://answerline.dev/docs/coverage#countries). Send either `country` or `gl`; if both are sent with differing values, the request fails with `400`.
- `state` (string): US state code (e.g. "CA", "DC" included). Sent without a country, the request asks for the US; sent with any country other than "US", it is refused with a 400, uncharged. ChatGPT and Gemini answer as a person in that state sees it; every other engine accepts it and answers for the whole US, at the price of a request without it. provenance.requestedState reports the state asked. See https://answerline.dev/docs/coverage#states
- `hl` (string): Interface language, in the format of Google's `hl` parameter (for example `en`, `de`, `pt-BR`). Case-insensitive free text; Google defines which codes exist. Takes precedence over the language Answerline infers from the country, which lets interface language and result geography differ.
- `location` (string): Location name in Google's canonical form, used for geo-targeted results, written comma-separated as 'City,Region,Country' (https://developers.google.com/google-ads/api/reference/data/geotargets lists every supported location, ~100,000 in all). Combine it with 'country' to target a specific city. Cannot be combined with 'uule'; send only one of the two.
- `uule` (string): A ready-made Google UULE string for exact geo-targeting, in the location-name form (starting w+CAIQICI); the coordinate form (a+) is refused with a 400. Supply it when you already have an encoded UULE rather than a location name. Cannot be sent together with 'location'; pass only one of the two.
- `device` ("desktop" | "mobile"): Type of device the results are fetched for
- `include` (object): Flags that add extra output formats to the response (optional)
  - `include.html` (boolean): A copy of the AI Mode page as it was when the answer was captured, stored on our file host and linked in `html`, to check the answer against. No extra cost.
  - `include.markdown` (boolean): Add a markdown version of the response to the result
  - `include.expandProducts` (boolean): Not available yet: a request that sets it is refused with 400 before anything runs or is charged. It is meant to look up merchant offers for the response's product clusters and return them in 'result.productResults'.
  - `include.googleGoto` (boolean): Has had no effect since 8th September 2026. Each redirect link is now always returned as `redirectLink` next to its target, so you get both without setting this flag. Requests that still include it are handled as though it were omitted.
  - `include.rawWire` (boolean): Return the engine's own response as received in result.rawWire: the answer stream, the rendered results pages or the RSS feed, without Gemini's detected location or ChatGPT's session tokens; null where it was not captured. Free. See https://answerline.dev/docs/output-formats#raw-wire
  - `include.screenshot` (boolean): Return a full-page PNG screenshot of the engine's page as it showed the finished answer, in result.screenshot: a link, or one link per results page on Google Search. On ChatGPT, Gemini, AI Mode, Google Search, Perplexity and Grok; other engines refuse it with a 400. Absent when the answer was read without a rendered page or its page was not available. Free. See https://answerline.dev/docs/output-formats#screenshots
- `answerDepth` ("any" | "full" | "quick"): Accepted so existing requests stay valid; it does not change the answer or the price. Every engine writes one depth: Perplexity answers every request with its Quick Search answer, and provenance.answerDepth says quick. See https://answerline.dev/docs/engine-features/#answer-depth

## Returns

- `result.text` (string): Text of the AI Mode answer
- `result.html` (string): Present when include.html is true: the link to the stored copy of the AI Mode page.
- `result.sources` (object[]): Sources the response cites
- `result.citationPills` (object[]): Citation pills that appear inline in the AI Mode answer. Every element pairs one pill with one source: a pill backed by N sources (Google's `[Label +N]` chips) yields N elements with the same `citationPillId`, each holding that source's own `label`, `url` and `domain`. Grouping by `citationPillId` rebuilds the pills. Empty when the answer has no pills.
- `result.markdown` (string): The AI Mode answer rendered as Markdown (present when include.markdown is true)
- `result.places` (object[]): Place cards embedded inline in the response
- `result.shoppingCards` (object[]): Shopping-related product details parsed from the response
- `result.ads` (object): Section of sponsored ads parsed from the response
  - `result.ads.title` (string): Heading of the ads section
  - `result.ads.ads` (object[]): List of sponsored ads
- `result.inlineProducts` (object[]): Product cards that appear inside the AI answer text
- `result.videos` (object[]): Video cards shown inline within the AI response (YouTube for now)
- `result.map` (object[]): Locations pulled from the response, enriched with GPS coordinates
- `result.screenshot` (string): Present when include.screenshot is true and the answer came from a rendered page: the link to the PNG screenshot of the AI Mode page once the answer finished.
- `result.links` (object[]): The links in the answer's text, in the order a reader meets them: one entry per web (http or https) link the answer shows, images and code aside, with the words it shows (text), where it goes (url), its domain and its 1-based position. Sources cited by pills are in citationPills; links to the same page appear in both when the answer does both. Empty when the text links nowhere.

## Responses

- 200: AI Mode monitoring result (success)
- 400: Bad Request - the request failed validation
- 401: Unauthorized - authentication failed
- 403: Forbidden - INSUFFICIENT_CREDITS: the balance does not cover this request
- 404: Not Found - No such route, or the engine is paused
- 409: Conflict - the resource is in a conflicting state
- 429: Too Many Requests - the call could not start now (`CONCURRENT_LIMIT_EXCEEDED`), or the service dropped the request because it was overloaded (`SERVICE_OVERLOADED`); that case returns `Retry-After` without any limit headers. `RATE_LIMIT_EXCEEDED`, with `Retry-After`, is sent only when one address presented too many unknown keys
- 499: Client Closed Request - the client cancelled the request
- 500: Internal Server Error
- 502: Bad Gateway - the engine failed

## Request

curl:

```bash
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"}'
```

TypeScript:

```ts
import { Client } from "@answerline/sdk";

const client = new Client({ apiKey: process.env.API_KEY! });
const answer = await client.monitor.aimode({
  "prompt": "Family-friendly hotels in Lisbon",
  "country": "PT",
  "hl": "en"
});
```

Python:

```python
import os
from answerline import Client

with Client(os.environ["API_KEY"]) as client:
    answer = client.monitor.aimode(
        prompt="Family-friendly hotels in Lisbon",
        country="PT",
        hl="en",
    )
```


## Example responses

200:

```json
{
  "success": true,
  "result": {
    "text": "These are strong tablet picks for digital drawing and note-taking...",
    "html": "https://files.answerline.dev/html/c45a5081-808d-4ed3-9c86-e4baf16c8ab8/1/page-1.html",
    "sources": [
      {
        "position": 1,
        "url": "https://example.com/ai-recommendations",
        "label": "AI Source",
        "description": "AI-selected monitor picks"
      }
    ],
    "citationPills": [
      {
        "label": "Top Monitors of 2026 — The Verge",
        "citationPillId": 1,
        "url": "https://example.com/best-laptops-2026",
        "domain": "example.com",
        "description": "An overview of this year's strongest monitors for coding work.",
        "position": 1
      },
      {
        "label": "iPad Air M3 First Impressions",
        "citationPillId": 1,
        "url": "https://example.com/macbook-pro-review",
        "domain": "example.com",
        "position": 3
      }
    ],
    "markdown": "These are strong tablet picks for digital drawing and note-taking...",
    "places": [
      {
        "title": "Gion District",
        "link": "https://www.google.com/viewer/place?mid=/g/11bw3yq9kp",
        "placeId": "/g/11bw3yq9kp",
        "index": 0,
        "thumbnail": "https://lh5.googleusercontent.com/p/example",
        "rating": 4.5,
        "reviews": 2900,
        "type": "Tourist attraction",
        "priceLevel": "$$",
        "address": "Nishiki Market, Nakagyo Ward, Kyoto",
        "status": "Open now"
      }
    ],
    "shoppingCards": [
      {
        "title": "Wireless Headphones",
        "price": {
          "value": 99.99,
          "currency": "$",
          "raw": "$129.99"
        },
        "store": "Amazon",
        "rating": 4.2,
        "reviews": "2.3k",
        "thumbnail": "https://example.com/product.jpg",
        "productLink": "https://www.google.com/example",
        "oldPrice": {
          "value": 129.99,
          "currency": "$",
          "raw": "$129.99"
        },
        "snippet": "Waterproof Bluetooth speaker with 20-hour battery life",
        "snippet_links": [
          {
            "text": "noise canceling",
            "link": "https://www.google.com/search?q=noise+canceling",
            "redirectLink": "https://www.google.com/goto?url=CAESaAHrOzAVev0pi_wnTxm1qpiZTmMyAllabLr1or10ZCfvJKPk"
          }
        ],
        "position": 0
      }
    ],
    "ads": {
      "title": "A few espresso machines worth a look",
      "ads": [
        {
          "title": "Prusa Core One",
          "url": "https://www.google.com/aclk?sa=L&ai=abc",
          "position": 1,
          "price": {
            "value": 899,
            "currency": "$"
          },
          "store": "Prusa Store",
          "rating": 4.7,
          "reviews": "584",
          "redirectLink": "https://www.google.com/goto?url=CAESaAHrOzAVev0pi_wnTxm1qpiZTmMyAllabLr1or10ZCfvJKPk"
        }
      ]
    },
    "inlineProducts": [
      {
        "title": "Sony WH-1000XM5",
        "position": 1,
        "price": {
          "value": 298,
          "currency": "$"
        },
        "oldPrice": {
          "value": 399.99,
          "currency": "$"
        },
        "store": "Amazon",
        "thumbnail": "https://encrypted-tbn0.gstatic.com/images?q=example",
        "productLink": "https://www.google.com/shopping/product/example"
      }
    ],
    "videos": [
      {
        "title": "I Tested 5 Budget Drones So You Don't Have To",
        "link": "https://www.youtube.com/watch?v=g0DZnQdI-xQ",
        "platform": "YouTube",
        "channel": "Layer Lines Workshop",
        "duration": "08:49",
        "thumbnail": "https://encrypted-tbn3.gstatic.com/images?q=tbn:ANd9GcS5Bntg3F0Y7P3YgTPgdyillyeCguV_YQJ99KFUmNYxmQtVt1f2",
        "redirectLink": "https://www.google.com/goto?url=CAESaAHrOzAVev0pi_wnTxm1qpiZTmMyAllabLr1or10ZCfvJKPk"
      }
    ],
    "map": [
      {
        "title": "Riverside Bistro",
        "link": "https://www.google.com/viewer/place?mid=/g/11bw3yq9kp",
        "placeId": "/g/11bw3yq9kp",
        "index": 0,
        "gps_coordinates": {
          "latitude": 40.7831,
          "longitude": -73.9712
        },
        "thumbnail": "https://lh5.googleusercontent.com/p/example",
        "rating": 4.5,
        "reviews": 1234,
        "type": "Coffee shop",
        "address": "450 Lexington Ave, New York",
        "status": "Open now"
      }
    ],
    "screenshot": "https://files.answerline.dev/html/c45a5081-808d-4ed3-9c86-e4baf16c8ab8/1/3f9a1c2e8b7d4a6f9e0c1b2a3d4e5f60/page-1.png",
    "links": [
      {
        "position": 1,
        "text": "Nike Pegasus 42",
        "url": "https://www.nike.com/t/pegasus-42-mens-road-running-shoes",
        "domain": "nike.com"
      }
    ]
  }
}
```

400:

```json
{
  "success": false,
  "error": "Request validation failed",
  "details": [
    {
      "field": "prompt",
      "message": "Prompt must not be empty"
    }
  ]
}
```

502:

```json
{
  "error": {
    "code": "EXTERNAL_SERVICE_ERROR",
    "message": "External service error: the service failed",
    "details": {
      "service": "CHATGPT"
    },
    "timestamp": "2025-01-15T12:00:00.000Z"
  }
}
```