---
title: "Google search"
description: "Search Google directly, or give your model current sources."
canonical_url: "https://minirouter.sh/docs/google-search"
markdown_url: "https://minirouter.sh/docs/google-search.md"
last_updated: "2026-10-13"
---

# Google search

Search Google directly, or give your model current sources.

## Search without a model

[Open Google Search](https://minirouter.sh/dashboard/tools?tool=google_search), or call `POST /v1/tools/google-search` with a funded integration API key. No model request is needed. The playground requires sign-in; Google searches have no free trial.

```sh
idempotency_key="$(uuidgen)"

curl 'https://api.minirouter.sh/v1/tools/google-search' \
  --request POST \
  --header 'Authorization: Bearer YOUR_MINIROUTER_API_KEY' \
  --header 'Content-Type: application/json' \
  --header "Idempotency-Key: $idempotency_key" \
  --data '{
  "query": "MiniRouter API documentation",
  "region": "GB",
  "max_results": 5
}'
```

| Field | Behavior |
| --- | --- |
| `query` | Required search text: 1–2,048 characters. |
| `max_results` | One to ten results. Default: five. Google may return fewer. |
| `region` | Optional uppercase country code, such as `GB` or `US`. |

1. **Query**: Send search text and optional country.
2. **Results**: Read titles, URLs and snippets from Google.
3. **Receipt**: Check the completed count and settled charge.

Check `GET /v1/tools` → `google_search` for availability, price and limits. Read results in `data.results`, the query in `data.query`, and the completion time in `data.retrieved_at`. `usage.google_search_requests` counts completed searches; `cost.amount` is the settled USD charge. Each completed search costs $0.01, including searches with no results. No model tokens are charged.

Send a fresh UUIDv4 `Idempotency-Key` for each new search. After an interruption, check `GET /v1/tools/operations?client_request_id=YOUR_UUID` with the same account credential. A `running` or missing receipt does not confirm failure. Retry only with the original key and identical input; do not reuse a key across tools.

Replays return the receipt with `data: null` and `result_available: false`. Queries and results are not saved for recovery. Receipts remain available for 30 days. Starting another search creates a new charge. Keys with model or provider restrictions cannot use standalone tools.

## Search with a model

Set `MINIROUTER_KEY` to your funded [integration API key](https://minirouter.sh/key). Use Chat Completions and a paid, tool-capable model. Free models, chat-session keys and provider keys (BYOK) are unsupported.

```sh
curl https://api.minirouter.sh/v1/chat/completions \
  -H "Authorization: Bearer $MINIROUTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "google/gemma-4-26b-a4b-it",
  "messages": [
    {
      "role": "user",
      "content": "Search Google for MiniRouter API documentation. Summarize what you find and cite the source URLs."
    }
  ],
  "tools": [
    {
      "type": "minirouter:google_search",
      "parameters": {
        "max_uses": 1,
        "max_results": 5,
        "region": "GB"
      }
    }
  ],
  "max_tool_calls": 1,
  "max_tokens": 512
}'
```

Read the answer in `choices[0].message.content`. MiniRouter handles the tool call for you.

1. **Ask**: Give the model a task and permission to search.
2. **Search**: Google results arrive through Serper: titles, URLs and snippets.
3. **Answer**: The model answers using those results in the same response.

Ask explicitly for search; the model may otherwise skip it. Raw results go to the model. Treat source content as untrusted.

## Set limits and region

| Option | Behavior |
| --- | --- |
| `max_uses` | Search attempts per request: 1–10. Default: 3. Dispatched attempts count even if they fail. |
| `max_results` | Results per search: 1–10. Default: 5. Each has `title`, `url` and `description`. Fewer may be available. |
| `region` | Optional uppercase country code, such as `GB` or `US`. |

Set these in `parameters`. The model supplies a `query` of 1–2,048 characters. Date, language and domain filters are unsupported.

`max_tool_calls` caps Google, datetime and web-fetch calls together: 1–30, default 5. Once this cap is reached, the model finishes without tools.

## Cost and usage

Each completed search costs $0.01. Chat Completions also charges model tokens. A completed search with no matches still counts. Failed or timed-out searches have no search fee.

*1 completed search costs $0.01; 3 completed searches cost $0.03; 10 completed searches cost $0.10. Model tokens are additional.*

Credit is reserved for the allowed searches before dispatch. Each model round costs tokens; `max_tokens` applies per round. Completed searches remain billable if the final answer fails.

`usage.server_tool_use.google_search_requests` counts completed searches. `usage.cost` includes search fees and all model rounds.

For streaming, add `stream: true` and `stream_options: {"include_usage": true}`. Totals arrive in the final usage chunk. Keep-alives precede the completed answer; intermediate rounds are not streamed token by token.

## Support and errors

In Chat Completions, search runs independently of the model provider and requires a supported paid route.

| Result | What to do |
| --- | --- |
| Invalid request | Check the endpoint, model and option ranges. |
| Insufficient credits | Add credit or lower search and output limits. Funds must cover searches and model tokens. |
| Search fails | The model receives the failure and can answer without results or retry within your limits. |

Search times out after 15 seconds. Handle [HTTP and streaming errors](https://minirouter.sh/docs/errors); check answers for missing sources.

Use [web fetch](https://minirouter.sh/docs/tools#available-server-tools) to read a full page, or compare [web and news search](https://minirouter.sh/docs/tools#search-the-web) for other search options.