# Get Google's AI Overview and its sources as JSON with Litescrape

Litescrape returns Google's AI Overview for a query as JSON. The generated answer arrives as `text_blocks`, the pages it cites arrive as `references`, and each block points at its sources by index. Each call is one request at $0.00015 per request, drawn from a plan held by the agent credential the storefront issues: send `GET https://agents.litescrape.com/zcj/i7fo7fft6vme/api/google/ai-overview?q=<query>` with `Authorization: Bearer <token>`.

## At a glance

- **Endpoint:** `GET https://agents.litescrape.com/zcj/i7fo7fft6vme/api/google/ai-overview?q=<query>`, with optional `gl` (country) and `hl` (language)
- **AI Mode:** `GET https://agents.litescrape.com/zcj/i7fo7fft6vme/api/google/ai-mode?q=<query>` returns Google's AI Mode answer with the sources it cited
- **Price:** $0.00015 per request on either endpoint. 1,000 calls cost $0.15.
- **Payment:** each call draws on a plan held by your bearer credential, either Free trial or Credits. There is no per-call payment.
- **Auth:** `Authorization: Bearer <token>`, using the agent credential the storefront issues. No upstream API key is needed.
- **Response:** JSON with `search_metadata`, `search_parameters` and `ai_overview`, which holds `text_blocks` and `references`
- **Billing:** a `zc-billing` response header states `chargedUsd`. A failed call is not billed.
- **Full purchase flow:** [the buyer skill](https://agents.litescrape.com/zcj/i7fo7fft6vme/SKILL.md)

## Get the AI Overview for a query

1. Hold a plan on your bearer credential, the agent identity the storefront issues. Calls draw on Free trial ($0.0015 of credit) or Credits (from $0.01 on a wallet rail, $0.50 by card). [The buyer skill](https://agents.litescrape.com/zcj/i7fo7fft6vme/SKILL.md) and [auth.md](https://agents.litescrape.com/zcj/i7fo7fft6vme/auth.md) have the steps to register the credential and buy a plan.

2. Send the query:

   ```bash
   curl -s "https://agents.litescrape.com/zcj/i7fo7fft6vme/api/google/ai-overview?q=what+is+a+passkey&gl=us&hl=en" \
     -H "Authorization: Bearer $ACCESS_TOKEN"
   ```

3. Read `ai_overview` from the response. An excerpt of the response to this request is below, shortened where it shows `…`:

   ```json
   {
     "search_parameters": {"q": "what is a passkey", "google_domain": "google.com", "gl": "us", "hl": "en", "start": "0", "device": "desktop"},
     "ai_overview": {
       "text_blocks": [
         {
           "type": "paragraph",
           "snippet": "A passkey is a modern, passwordless login method that replaces traditional passw…",
           "snippet_highlighted_words": ["a modern, passwordless login method that replaces traditional passwords with cry…"],
           "reference_indexes": [1, …]
         },
         …
       ],
       "references": [
         {
           "title": "What is a Passkey? | Yubico",
           "link": "https://www.yubico.com/[path]",
           "index": 1,
           "snippet": "Definition: Passwordless authentication method using public-private key cryptogr…",
           "source": "Yubico"
         },
         …
       ]
     }
   }
   ```

   This overview held nine text blocks and 13 references, and the call drew $0.00015 from credit.

4. Join each block to its sources. Each number in a block's `reference_indexes` matches the `index` of an entry in `references`:

   ```bash
   jq '.ai_overview as $o | $o.text_blocks[] | {snippet, sources: [.reference_indexes[]? as $i | $o.references[] | select(.index == $i) | .link]}' overview.json
   ```

## What the AI Overview response holds

| Field | What it holds |
| --- | --- |
| `ai_overview.text_blocks[].type` | The kind of block, such as `paragraph` |
| `ai_overview.text_blocks[].snippet` | The generated text of the block |
| `ai_overview.text_blocks[].snippet_highlighted_words` | The phrases Google highlights in the block |
| `ai_overview.text_blocks[].reference_indexes` | The `index` values of the references that support the block |
| `ai_overview.references[]` | Each cited page: `title`, `link`, `source`, `snippet`, `index` |
| `search_parameters` | The query as run: `q`, `gl`, `hl`, `device`, `google_domain` |
| `search_metadata` | `id`, `status`, timestamps and `google_ai_overview_url` |

## Choose the country and language

| Parameter | Sets | Value in the example request |
| --- | --- | --- |
| `gl` | The country | `us` |
| `hl` | The language | `en` |

The response echoes both values in `search_parameters`. When you track one query over time, send the same `gl` and `hl` on every run.

## Ask Google's AI Mode

`GET https://agents.litescrape.com/zcj/i7fo7fft6vme/api/google/ai-mode?q=<query>` returns Google's AI Mode answer with the sources it cited. It is one request at $0.00015 per request, on the same plan and bearer as the AI Overview endpoint.

| To | Use |
| --- | --- |
| Ask a question | `q` |
| Answer for a place | `location` |
| Answer for a device | `device` |
| Ask about an image | `image_url` |
| Continue a conversation | `continuable`, `subsequent_request_token` |

The response carries `text_blocks`, `references` and a `subsequent_request_token`. A follow-up request sends that token back to continue the conversation. Exact parameter names and types are in [the AI Mode operation](https://agents.litescrape.com/zcj/i7fo7fft6vme/openapi.json?path=%2Fapi%2Fgoogle%2Fai-mode&method=get).

## Limits

- An AI Overview exists only when Google generates one for the query.
- A call without a bearer answers `401`. No call is priced on its own.
- A failed call is not billed. A delivered response without a `zc-billing` header billed nothing.

## Errors

| Response | Meaning | Action |
| --- | --- | --- |
| `401 bearer_required` | The call carried no agent credential | Register at [auth.md](https://agents.litescrape.com/zcj/i7fo7fft6vme/auth.md), then retry with the bearer |
| `401 invalid_token` (`token_expired`) | The access token expired | Exchange the stored assertion for a fresh token and retry |
| `403 plan_required` | The credential holds no plan that covers the call | Buy one of the `plans` in the body, then retry |
| `usage_exhausted` | The credit ran out | Top up with `POST https://agents.litescrape.com/zcj/i7fo7fft6vme/extend` and `{"amountUsd": "..."}` |
| `rate_limit_exceeded` | Too many requests | Wait `retry_after` or `Retry-After`, then retry |
| `503 service_unavailable` | The scraper could not complete the request | Not billed. Retry with bounded backoff. |

## Frequently asked questions

### Does every Google query return an AI Overview?

No. Google generates an AI Overview only for some queries, and the response includes `ai_overview` only when it does.

### Which pages does a Google AI Overview cite?

They are the entries in `ai_overview.references`, each with `title`, `link`, `source`, `snippet` and `index`. To find which pages support a passage, match the block's `reference_indexes` to the references' `index` values.

### How much does it cost to track AI Overviews?

Each call is one request at $0.00015 per request, so 1,000 queries cost $0.15. Calls draw on Credits, bought from $0.01, or on the Free trial's $0.0015 of credit.

### What is the difference between the AI Overview and AI Mode endpoints?

The AI Overview endpoint returns the overview Google places on a search results page for a query. The AI Mode endpoint returns Google's AI Mode answer with its cited sources. AI Mode also takes `location`, `device` and `image_url`, and it continues a conversation with `subsequent_request_token`. Both cost the same per request.

## Keep reading

- [Buyer skill](https://agents.litescrape.com/zcj/i7fo7fft6vme/SKILL.md): the full purchase flow
- [Identity](https://agents.litescrape.com/zcj/i7fo7fft6vme/auth.md): register and reuse an agent credential
- [How to pay](https://agents.litescrape.com/zcj/i7fo7fft6vme/payment.md): plans, rails and top-ups
- [Error reference](https://agents.litescrape.com/zcj/i7fo7fft6vme/errors.md): every error code
- [Google Search service](https://agents.litescrape.com/zcj/i7fo7fft6vme/services/google-search): prices and plans for this service

---

Updated 2026-11-05. All Litescrape guides: https://agents.litescrape.com/guides.md. Storefront: https://agents.litescrape.com/zcj/i7fo7fft6vme/llms.txt.