Web Search Grounding

Gemini models can ground a generation in live Google Search results instead of relying only on what they learned in training. Add one parameter:

{ "web_search": true }

It is off by default, so existing calls are unaffected.

Grounding is worth reaching for when the answer depends on something current — a record, a price, a recent release — and worth leaving off when it does not, because it costs more and adds latency.

Supported models

On any other model the parameter is simply ignored.

Reading the evidence

Every grounded response tells you which searches ran and which pages informed the answer — but where that arrives depends on the model kind and the API version, because a sync image response has no JSON body to put it in.

Text models

The grounding rides inline on the candidate, under groundingMetadata:

{
  "candidates": [
    {
      "content": { "parts": [{ "text": "..." }] },
      "finishReason": "STOP",
      "groundingMetadata": {
        "webSearchQueries": [
          "who won the most recent FIFA World Cup",
          "FIFA World Cup 2022 winner"
        ],
        "groundingChunks": [
          { "web": { "uri": "https://...", "title": "wikipedia.org" } }
        ],
        "groundingSupports": [ ... ],
        "searchEntryPoint": { "renderedContent": "<div>...</div>" }
      }
    }
  ]
}

Image models on v2

An image model cannot carry metadata inside its output, so the async result envelope gains a top-level grounding object:

{
  "status": "COMPLETED",
  "output": "https://images.segmind.com/generations/...jpeg",
  "grounding": {
    "web_search_queries": [
      "men's marathon world record athlete and time"
    ],
    "sources": [
      { "title": "wikipedia.org", "uri": "https://..." }
    ],
    "search_entry_point_html": "<div>...</div>"
  }
}

Image models on v1

A synchronous image call returns the image bytes as the body, so there is nowhere in the response to put the evidence. The queries come back in a header instead:

x-web-search-queries: ["tallest building in the world 2025", "tallest building in the world height"]

It carries the queries that ran, as a JSON array, and is truncated for very long lists. Expect fewer entries than you might guess: the model batches related questions, so a prompt asking about a dozen things often resolves to two or three searches.

If you need the sources as well, use the v2 endpoint — the header has no room for them.

Asking for grounding does not guarantee it

web_search: true gives the model permission to search — not an obligation. If it judges that it does not need to, it answers from training and the response carries no grounding at all: no groundingMetadata, no grounding object, no header.

So treat the evidence as optional. Check whether it is present rather than indexing into it:

grounding = result.get("grounding")          # image models on v2
if grounding:
    print(grounding["web_search_queries"])

An ungrounded answer to a grounded request is normal, not an error.

Displaying the widget

searchEntryPoint on text models and search_entry_point_html on image models hold the same thing: a block of HTML for Google's Search Suggestions widget.

What it costs

Grounding adds a surcharge on top of the model's normal price, and it is charged only when the response actually comes back grounded — a request that opts in and is not grounded is not surcharged for search.

How the surcharge is counted depends on the model generation: newer Gemini models are billed per search query executed, where one prompt can fire several, and earlier ones a flat amount per grounded prompt. Because the query count is not known ahead of the call, a grounded request's cost is not fixed — read the cost in the response's metrics, or see Cost Analytics for the totals.