AI engines
Gemini API grounding with Google Search: what it returns
The google_search tool returns the queries it ran, inline url_citation annotations and a Search Suggestions snippet, at $14 per 1,000 searches after 5,000 free.

By Mathias C.SEO consultant, and more recently GEO, at MentionBox
Grounding with Google Search is a tool you declare in a Gemini API call. The model reads your prompt, decides on its own whether a search would improve the answer, writes and runs its own Google queries, then returns one synthesised answer. Google's guide for the tool describes what travels back with that answer: a google_search_call step holding the queries it executed, a google_search_result step holding a search_suggestions HTML snippet for your interface, and the answer text carrying url_citation annotations with a url, a title, a start_index and an end_index. On Gemini 3 and newer models the project is billed for each search the model chooses to run, at $14 per 1,000 search requests after 5,000 free a month, under a default ceiling of 1,500 requests a day. Three things do not come back: the publisher's own URL, any ranking or share figure, and permission to keep the links as an index.
This page is written for the developer who wired the tool into a Gemini app and found the citations unusable, and for whoever hoped an official Google key would measure brand visibility in Gemini. It covers the request, every field of the response in both shapes of the API, the four things the tool keeps to itself, what the terms allow you to store, the arithmetic of a month of calls, and the point where grounding stops being the right instrument.
What a grounded request looks like
The current shape is one POST to the Interactions endpoint, with the tool declared by type and nothing else:
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-3.8-flash",
"input": "best AI visibility API for an agency",
"tools": [{"type": "google_search"}]
}'
The same call in Python is three lines through the google-genai client, client.interactions.create() with model, input and the same tools array. Google's guide lists Gemini 4 Argon, the Gemini 3.x family, Gemini 2.5 Pro, Flash and Flash-Lite and Gemini 2.0 Flash as supported, and notes that older models use a google_search_retrieval tool instead of google_search. That older tool is where the dynamic retrieval setting lived: when Google opened grounding to the Gemini API in December 2024 it explained that a prediction score between 0 and 1 decides whether a prompt needs grounding at all, with a default threshold of 0.3 that a developer could move.
Nothing in the declared tool sets a country, a language or a domain filter. That is the first practical gap against the equivalent on the OpenAI side, whose web search tool documents a user_location object and a filters parameter taking up to 100 allowed or blocked domains.
What comes back, field by field
Two response shapes are in circulation, and an integration written against one does not read the other. The Interactions API returns steps and annotations; the generateContent endpoint, which Google now labels legacy, returns a groundingMetadata object on the candidate.
| What you get | Interactions API | generateContent | What it is for |
|---|---|---|---|
| The queries the model ran | google_search_call.queries | groundingMetadata.webSearchQueries | seeing the fan-out behind one prompt, and counting what you are billed for |
| The cited pages | url and title on each url_citation annotation | groundingChunks[].web.uri and .web.title | the source list, as redirect links |
| The link between answer and source | start_index and end_index on each annotation | groundingSupports[].segment with startIndex, endIndex, text, plus groundingChunkIndices | building inline citations in your own interface |
| Search Suggestions | google_search_result.search_suggestions | groundingMetadata.searchEntryPoint.renderedContent | the HTML and CSS Google requires you to display |
| Token accounting | usage with total_input_tokens, total_output_tokens, total_tool_use_tokens | not part of groundingMetadata | the second half of the bill |
Field names from Google's grounding guide, its legacy generateContent page and the Interactions API reference, read on October 30, 2026.
The groundingSupports array is the part worth reading closely, because it is the only place the API says which sentence rests on which source. Google's page calls it the array of chunks that connects the response text to the sources in groundingChunks, each one linking a text segment to one or more groundingChunkIndices. In the shape its own example shows, with our prompt in place of its football question:
{
"groundingMetadata": {
"webSearchQueries": [
"best AI visibility API for agencies",
"AI visibility API resale white label"
],
"searchEntryPoint": { "renderedContent": "<!-- HTML and CSS for the Search Suggestions -->" },
"groundingChunks": [
{ "web": { "uri": "https://vertexaisearch.cloud.google.com/grounding-api-redirect/...", "title": "example.com" } }
],
"groundingSupports": [
{
"segment": { "startIndex": 0, "endIndex": 85, "text": "..." },
"groundingChunkIndices": [0]
}
]
}
}
One answer therefore gives you a query list, a source list, and a sentence-level map between them. For an application that shows citations to a reader, that is the whole job. For anything that counts, it is the beginning of one.
The four things grounding does not return
The publisher's URL. In the example response on Google's own page, the uri of each grounding chunk points at vertexaisearch.cloud.google.com and the title is the bare domain, aljazeera.com in its case. So the domain is readable, the page address is not, and reaching it means following the redirect. A feature request for actual source URLs has sat on Google's developer forum since 2026 without a published answer, with developers in the thread noting the same two symptoms, a redirect in web.uri and a domain-only web.title.
Any position or share figure. The annotations tell you which segment leans on which source. They say nothing about where a brand name sits inside the answer, how often it appears across repeated runs, or which competitors were named beside it. That arithmetic is yours to write, and the terms in the next section decide whether you may write it at all.
A country or a language setting. The tool is declared by type alone in every example Google publishes. The announcement describes grounding as working across all available languages, which is a statement about capability rather than a control you can set. If the measurement you need is country-specific, the request shape does not express it.
A guarantee that a search ran. The guide states that the model determines whether a Google Search can improve the answer, which means a time-sensitive question can come back fluent, confident and out of date. The absence of a google_search_call step, or of webSearchQueries in the legacy shape, is the only signal that it happened.
A fifth absence belongs here as well, because it is the most common misreading of this tool. A grounded Gemini answer is not the AI Overviews or AI Mode answer a person sees in Google Search. Those are Search features, documented for site owners under AI features and your website, and no Google API returns their text. Our guide on collecting AI Mode answers through an API covers that route, and the same split exists at OpenAI, set out in the web search tool against ChatGPT answers.
What the terms let you keep
Most pages about this tool stop at the response shape. The Gemini API terms carry a dedicated section on grounding, and it governs what a project may legally do with everything described above.
- Display is tied to one reader. You will only display the grounded results with the associated Search Suggestions to the end user who submitted the prompt, in applications you own and operate.
- Five suggestions, unmodified. A maximum of five Search Suggestions may be displayed with the final results, and you will not modify, or intersperse any other content with, the grounded results or the Search Suggestions. Nothing may sit between a link and its destination page.
- Two years, three purposes. The grounded text may be stored for up to two years, and only to evaluate how it is displayed, to maintain a user's chat history, or to resubmit text temporarily for a refined result, with the Search Suggestions shown each time.
- No caching for anything else. The terms forbid caching, framing, syndicating, reselling, analysing or training on the results, and forbid collecting the links or using automated means to build an index of them.
- Google keeps its own copy for 30 days. Prompts, contextual information and output are stored for thirty days to create the grounded results and to support debugging and testing.
What a month of grounding costs
The bill has two halves, and the second one is easy to forget: the searched pages reach the model as tokens, charged at the model's own rate.
| Setup | What Google charges |
|---|---|
Gemini 3 and newer, google_search | $14 per 1,000 search requests, after 5,000 free a month shared across those models; each query the model runs counts separately |
Gemini 2.5 and older, google_search | $35 per 1,000 grounded prompts, with 1,500 free requests a day shared between Flash and Flash-Lite |
| Tokens on Gemini 3.8 Flash | $0.75 per 1M input, $3.75 per 1M output |
| Tokens on Gemini 2.5 Flash | $0.30 per 1M input, $2.50 per 1M output |
| Tokens on Gemini 2.5 Pro | $1.25 per 1M input, $10.00 per 1M output |
url_context alongside the search | retrieved page content billed as input tokens, up to 20 URLs per request and 34 MB per URL |
Rates from Google's pricing page, its rate limits page and its URL context guide, read on October 30, 2026.
The switch from per-prompt to per-query billing has a break-even point you can compute: $35 divided by $14 is 2.5, so a prompt that triggers fewer than two and a half searches is cheaper on Gemini 3 and newer, and a research-style prompt that fans out into eight searches costs $0.112 there against $0.035 flat on Gemini 2.5. Google's own documented example splits one short factual question into two queries, which is the low end of that range. Comparative prompts, the kind a brand actually wants answered, sit at the high end, and nothing in the API caps the count.
A worked month, on Gemini 3.8 Flash, for 200 prompts run once a week: 200 × 4.3, about 860 prompts. At two searches each, 1,720 search requests, so nothing billed in the first month against the 5,000 free allowance, and $24.08 once that allowance is used. Google publishes no average for the volume of page content a search feeds the model, so take 8,000 input and 500 output tokens per answer as a working assumption: the token side comes to $0.008 per answer, about $6.80 for the month. The search line and the token line land in the same order of magnitude, which is the part a rate card alone will not tell you. Our explainer on query fan-out in AI search covers why that search count moves so much between question types.
Five things that break a grounded integration
- Trusting the citation list without resolving it. Store the domain from
web.titleand the redirect fromweb.urias two separate columns, and resolve the redirect only when you actually need the page, inside what the terms allow. - Assuming the search happened. Record the presence of the
google_search_callstep with every answer. Without that column, a month of logs mixes grounded and ungrounded answers and no later analysis can separate them. - Dropping the Search Suggestions. The
renderedContentHTML is not decoration. Discarding it puts an application outside the terms it was built under. - Sizing a budget on prompts. On Gemini 3 and newer the billable unit is the query the model invents, not the question you sent. Log
webSearchQueries.lengthper call and read the real distribution before committing to a volume. - Mixing the two response shapes in one table.
groundingChunksandurl_citationannotations carry overlapping but differently named data. Normalise on the way in, or a later migration recounts a year of rows.
Where grounding stops, and what replaces it
Grounding with Google Search is an answer-quality tool for an application you own. It makes a Gemini-powered feature cite real pages, and it does that well, with a sentence-level map most engines do not provide. Measuring what AI engines tell buyers is a different exercise: the same prompts run repeatedly across several engines, brand names matched through aliases, positions and share of voice computed per run, and a licence that allows the results to be stored and shown to a client.
That last clause is what separates the two categories. As a concrete example of the second, API for GEO runs a stored prompt list natively on each engine, in the country and language asked for, and returns the answer with cited URLs by category, brand mentions, position, share of voice, sentiment and the fan-out questions the engine asked, at $13 per 1,000 answers down to $7 at its largest tier, with resale and white label published as an intended use. Gemini sits among its engines, confirmed in our hands-on test of October 26, 2026 rather than documented on apiforgeo.com, as were its webhooks, OpenAPI spec and official SDKs. MentionBox, which publishes this site, has a commercial link with API for GEO.
Grounding is also not the only source Google will plug into a Gemini model. The grounding overview on the Gemini Enterprise Agent Platform lists Google Maps, Agent Search, Elasticsearch, your own search API and third-party web search among the options, each with its own terms. If the blocker is the clause rather than the field names, changing the grounding source is a shorter path than changing the model.
Frequently asked questions
How much does Gemini API grounding with Google Search cost?
On Gemini 3 and newer models the project is billed for each search query the model decides to execute, at $14 per 1,000 search requests after 5,000 free a month shared across those models. Gemini 2.5 and older models are billed per grounded prompt instead, at $35 per 1,000, with 1,500 free requests a day shared between Flash and Flash-Lite. The pages the search feeds the model are billed on top as tokens at the model's own rate, $0.75 per 1M input and $3.75 per 1M output on Gemini 3.8 Flash. Rates read on Google's pricing page on October 30, 2026.
Does the Gemini API return the real URLs of the pages it cited?
Not in the grounding metadata. The example response on Google's own documentation page shows each source as a `web.uri` pointing at `vertexaisearch.cloud.google.com` with a `web.title` reduced to the domain, such as `aljazeera.com`, so the publisher address is reached by following the redirect rather than read from the payload. A feature request asking for the actual source URLs has been open on Google's developer forum since 2026 with no published answer. Plan for a resolution step, and read the terms before you store what it gives back.
Can I tell whether the model actually searched?
Yes, by looking for the search step. A grounded answer carries a `google_search_call` with the queries it ran in the Interactions API, or a `groundingMetadata.webSearchQueries` array in the generateContent shape; an answer with neither came out of the model's weights. Google's guide describes the decision as the model's own, and the Interactions API reference lists `tool_choice.mode` with `auto`, `any`, `none` and `validated` plus an `allowed_tools` list as the levers over tool use. Log the presence or absence of that step next to every answer you keep.
Can I use grounding with Google Search to track my brand's visibility in Gemini?
The terms do not allow it. The Gemini API terms state that you will only display the grounded results with their Search Suggestions to the end user who submitted the prompt, cap the display at five Search Suggestions, allow storage of the grounded text for up to two years for three named purposes only, and forbid caching, syndicating, reselling, analysing or training on the results as well as collecting the links or using automated means to build an index. Measuring an engine means repeated runs, per-brand counting and a licence that permits storage, which is a different product from an answer-quality tool.
Is grounding with Google Search the same as AI Overviews or AI Mode?
No. A grounded call answers from the Gemini model you named in the request, with Google Search attached as a tool, while AI Overviews and AI Mode are features of Google Search itself that Google documents for site owners under AI features. The two run different pipelines over different prompts, so the answer text and the source list differ, and Google publishes no API that returns the AI Mode answer. Keep the two in separate columns if you store both.
What rate limits apply to grounding?
Google's rate limits page states that grounding with Google Search on Gemini 3 and newer models carries a default limit of 1,500 requests per day per project on the Gemini Developer API, with increases requested through AI Studio. On Gemini 2.5 and older models the free allowance is also 1,500 requests a day, shared between Flash and Flash-Lite. A nightly job of 200 prompts that each fan out into five searches reaches that ceiling at 1,000 search requests, so size the schedule on searches rather than on prompts.