# Get Google search results as JSON with Litescrape's API

Litescrape's search results API returns a Google results page as structured JSON from one GET request, with no browser or proxy to run. Each search costs $0.00015 per request, drawn from a plan your credential holds: the Free trial or Credits. Send `GET https://agents.litescrape.com/zcj/wpffydlobwk8/api/google/search?q=<query>` with `Authorization: Bearer <token>`.

## At a glance

- **Endpoint:** `GET https://agents.litescrape.com/zcj/wpffydlobwk8/api/google/search`
- **Query:** `q` (the search), `gl` (country), `hl` (language), `num` (number of results)
- **Price:** $0.00015 per request. Every Litescrape engine bills one request per call at the same flat rate.
- **Access:** `Authorization: Bearer <token>` for a free agent credential that holds a plan. There is no per-call payment.
- **Plans:** the Free trial ($0.0015 of credit, once per human, after your human claims the credential with a verified email) or Credits (from $0.01 on a wallet rail, $0.50 by card)
- **Payment for Credits:** one priced 402, the purchase quote, settled over x402 or MPP (USDC wallet rails) or by card
- **Response:** JSON with `search_metadata`, `search_parameters`, `organic_results` and `related_searches`. The charge is in the `zc-billing` header.
- **Full purchase flow:** [the buyer skill](https://agents.litescrape.com/zcj/wpffydlobwk8/SKILL.md)

## Get your first Google search result

1. **Get a bearer token.** Register a free agent credential and exchange it for a short-lived access token. Registration is one free call with no email. [The identity guide](https://agents.litescrape.com/zcj/wpffydlobwk8/auth.md) has the commands. If you already hold a credential from a ZeroClick storefront, reuse it.

2. **Hold a plan.** First check what the credential already owns:

   ```bash
   curl -s "https://agents.litescrape.com/zcj/wpffydlobwk8/agent/entitlements" -H "Authorization: Bearer $ACCESS_TOKEN"
   ```

   The response lists active plans with `remainingCreditUsd`. If none covers Google Search, buy one. The plan id and `purchase.url` are under `plans[]` in `https://agents.litescrape.com/zcj/wpffydlobwk8/manifest.json`, by slug `free-trial` or `credit`.

   ```bash
   curl -s -X POST "https://agents.litescrape.com/zcj/wpffydlobwk8/plans/{planId}/purchase" \
     -H "Authorization: Bearer $ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"amountUsd": "<whole-cent amount>"}'
   ```

   For Credits, the storefront answers with a priced 402 carrying `payment.amountUsd`, the `plan` and a challenge for each rail. Nothing is charged until you settle it. For a hosted card checkout page, add `"checkout": true`. To claim the Free trial, send the same request with an empty body and no payment. Success returns `purchased: true` and `access`.

3. **Run the search.**

   ```bash
   curl -s "https://agents.litescrape.com/zcj/wpffydlobwk8/api/google/search?q=cold+brew+coffee&gl=us&hl=en&num=3" \
     -H "Authorization: Bearer $ACCESS_TOKEN" -D headers.txt
   ```

   The response is a `200` with a JSON body. The example below is that call's response, trimmed to one item per list. The call took 4.1 seconds and drew $0.00015 from the plan's credit.

   ```json
   {
     "search_metadata": {"status": "Success"},
     "search_parameters": {"q": "cold brew coffee", "google_domain": "google.com", "gl": "us", "hl": "en", "num": "3", "device": "desktop"},
     "search_information": {"query_displayed": "cold brew coffee", "total_results": 168},
     "organic_results": [
       {"position": 1, "title": "roy g biv cold brew filter packs", "link": "https://www.stonecreekcoffee.com/[path]", "displayed_link": "https://www.stonecreekcoffee.com › Collections", "snippet": "Refresh your ritual with our Cold Brew-smooth, bold, and brewed slow for a natur…", "snippet_highlighted_words": ["Cold Brew"], "source": "Stone Creek Coffee"}
     ],
     "related_searches": [
       {"query": "Cold brew coffee recipe", "link": "https://www.google.com/[path]", "block_position": 0}
     ],
     "pagination": {"next_page_token": "gs1.[redacted]…"}
   }
   ```

4. **Read the charge.** On a plan-funded call, the `zc-billing` header has the shape `{"status":"settled","fundingSource":"credit","chargedUsd":"…","remainingCreditUsd":"…"}`. `chargedUsd` is what this request debited from your balance. The example call's header showed `fundingSource` as `credit` and `chargedUsd` as $0.00015.

## Set country, language and result count

| To set | Parameter | Example value |
| --- | --- | --- |
| The search terms | `q` | `cold+brew+coffee` |
| The country of the results | `gl` | `us` |
| The language of the results | `hl` | `en` |
| How many results to request | `num` | `3` |

The Google Search operation also localizes by device and by a named location or coordinates. It narrows results by date, vertical or advanced query operators. The full parameter list is in `https://agents.litescrape.com/zcj/wpffydlobwk8/services/google-search/openapi.json`.

## What the JSON holds

These are the fields the example search returned.

| Field | Contents |
| --- | --- |
| `search_metadata` | `id`, `status`, timestamps, `google_url`, `json_endpoint` |
| `search_parameters` | The parameters as applied, including `gl`, `hl`, `num`, `device` |
| `search_information` | `query_displayed`, `total_results` |
| `organic_results` | Each result's `position`, `title`, `link`, `displayed_link`, `snippet`, `source` |
| `related_searches` | Each suggestion's `query` and `link` |
| `pagination` | `next_page_token` for the next page |

Other blocks appear when Google shows them for a query. For this query they were `filters`, `immersive_products`, `inline_images` and `shopping_results`. The Google Search service also covers Google's AI Overview, when one is generated, and a dedicated AI Mode endpoint that returns Google's answer with the sources it cited. Both are documented on the Google Search service page, `https://agents.litescrape.com/zcj/wpffydlobwk8/services/google-search`.

## Cost and boundaries

- One call is one request at $0.00015 per request, whichever engine you call. 1,000 searches cost $0.15. A delivered response without a `zc-billing` header billed nothing.
- Every call draws on a plan. A call without a bearer, or without a covering plan, returns an error instead of a price.
- Unused Credits stay on the balance. Add more with `POST https://agents.litescrape.com/zcj/wpffydlobwk8/extend` and `{"amountUsd": "<amount>"}`.
- An anonymous credential that nobody claims lapses within a few days, taking any plans bought with it. Have your human claim it to keep purchases.

## Errors

| Error | Meaning | Action |
| --- | --- | --- |
| `401 bearer_required` | No agent credential on the call | Register at [auth.md](https://agents.litescrape.com/zcj/wpffydlobwk8/auth.md) and send the bearer |
| `401 invalid_token` | The token expired or did not verify | Re-exchange the stored assertion for a fresh token |
| `403 plan_required` | No plan covers this call | Buy one of the `plans` in the body, then retry |
| `403 verified_email_required` | The Free trial needs a claimed credential | Have your human complete the claim, then retry |
| `409 free_plan_already_claimed` | Your human already holds the Free trial | Use the existing trial |
| `usage_exhausted` | The plan's credit ran out | Top up with `POST /extend` or buy Credits |
| `503 service_unavailable` | The scraper could not complete the request | Not billed. Retry with bounded backoff. |

## Other engines and data

| Need | Service | Reference |
| --- | --- | --- |
| Google's AI Overview and AI Mode | Google Search | `https://agents.litescrape.com/zcj/wpffydlobwk8/services/google-search` |
| Places, ratings and filters on Google Maps | Google Maps | `https://agents.litescrape.com/zcj/wpffydlobwk8/services/google-maps` |
| Reviews for one Google Maps place | Google Reviews | `https://agents.litescrape.com/zcj/wpffydlobwk8/services/google-reviews` |
| Product search with prices and merchants | Google Shopping | `https://agents.litescrape.com/zcj/wpffydlobwk8/services/google-shopping` |
| Bing web search | Bing | `https://agents.litescrape.com/zcj/wpffydlobwk8/services/bing` |
| DuckDuckGo web search | DuckDuckGo | `https://agents.litescrape.com/zcj/wpffydlobwk8/services/duckduckgo` |

Each service's operations are in `https://agents.litescrape.com/zcj/wpffydlobwk8/services/<slug>/openapi.json`.

## Frequently asked questions

### Does the Google search results API need proxies or a browser?

No. Litescrape runs the search and returns the results page as structured JSON. You send one GET request with a bearer token.

### How much does a Google search cost?

$0.00015 per request. Bing, DuckDuckGo, Google Maps, Google Shopping and the other engines bill the same rate per request. The Free trial includes $0.0015 of credit.

### Can I pay for a single search without a plan?

No. Every call draws on a plan your credential holds. Credits start at $0.01 on a wallet rail and $0.50 by card. The Free trial needs no payment.

### Where do I see what a call cost?

In the `zc-billing` response header, as `chargedUsd`. A delivered response with no `zc-billing` header billed nothing. `GET https://agents.litescrape.com/zcj/wpffydlobwk8/agent/entitlements` shows your remaining credit.

### Can I get the AI Overview as JSON?

Yes, when Google generates one: `GET https://agents.litescrape.com/zcj/wpffydlobwk8/api/google/ai-overview?q=<query>` returns its text blocks and the references they cite. The Google Search reference lists its parameters.

## Keep reading

- [Buyer skill](https://agents.litescrape.com/zcj/wpffydlobwk8/SKILL.md): the full purchase flow
- [Identity](https://agents.litescrape.com/zcj/wpffydlobwk8/auth.md): register, claim and exchange the agent credential
- [How to pay](https://agents.litescrape.com/zcj/wpffydlobwk8/payment.md): Credits, the Free trial and each rail
- [Google Search service](https://agents.litescrape.com/zcj/wpffydlobwk8/services/google-search): rates, plans and the operation reference
- [Error reference](https://agents.litescrape.com/zcj/wpffydlobwk8/errors.md): every error code

---

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