Gemini Search Grounding

Gemini Search Grounding lets supported Gemini models use Google Search to obtain recent information and associate answer segments with web sources through groundingMetadata.

Grounding is more than turning on a search switch. The client must also read the mapping between queries, sources, and text segments before it can display verifiable citations in the interface.

Protocol support does not guarantee model support

Generate Content can represent the Google Search tool, but actual availability depends on the current model and account. First confirm the model in the Model marketplace, then follow the Gemini Generate Content Reference.

Send a Grounding request

The native Gemini path appends /v1beta to the site Origin. Do not append /v1beta to a Base URL that already contains /v1:

curl --request POST \
  'https://api.agtcloud.cn/v1beta/models/MODEL_ID:generateContent' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer your-api-key' \
  --data '{
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "text": "What AI news is worth following today? Include the sources."
          }
        ]
      }
    ],
    "tools": [
      {
        "google_search": {}
      }
    ]
  }'

The model decides whether a search is needed and can generate one or more search queries. Do not assume that enabling the tool always produces Grounding Metadata.

Grounding workflow

1. Submit the question and search tool

Put the user's question in contents[].parts and enable Google Search in tools.

2. Read the answer text

Read the model-generated text from the candidate's content.parts. Do not assume there is always only one candidate or one Part.

3. Read Grounding Metadata

Save the search queries, web sources, and associations between answer segments and source indexes.

4. Display clickable citations

Insert citation markers at segment boundaries or display source cards next to the answer so users can return to the original pages for verification.

Understand `groundingMetadata`

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {"text": "According to recent reports, the developments include..."}
        ]
      },
      "groundingMetadata": {
        "webSearchQueries": [
          "artificial intelligence news today"
        ],
        "groundingChunks": [
          {
            "web": {
              "uri": "https://example.com/article",
              "title": "Source title"
            }
          }
        ],
        "groundingSupports": [
          {
            "segment": {
              "startIndex": 0,
              "endIndex": 27,
              "text": "According to recent reports"
            },
            "groundingChunkIndices": [0]
          }
        ]
      }
    }
  ]
}

Field	Client use
`webSearchQueries`	Record the queries actually used by the model for troubleshooting and explaining the search scope
`groundingChunks`	Store source information such as web page URIs and titles
`groundingSupports`	Map answer text segments to one or more source indexes

Some responses might omit one or more of these fields. The client should use optional access and empty arrays as defaults.

Insert citations into text

When inserting citations, process segment.endIndex from largest to smallest so earlier insertions do not shift later positions:

function addCitations(text, supports = [], chunks = []) {
  const sorted = [...supports].sort(
    (a, b) => (b.segment?.endIndex ?? 0) - (a.segment?.endIndex ?? 0),
  );

  for (const support of sorted) {
    const endIndex = support.segment?.endIndex;
    if (endIndex == null) continue;

    const links = (support.groundingChunkIndices ?? [])
      .map((index) => {
        const source = chunks[index]?.web;
        return source?.uri ? `[${index + 1}](${source.uri})` : null;
      })
      .filter(Boolean);

    if (links.length > 0) {
      text = `${text.slice(0, endIndex)}${links.join('')}${text.slice(endIndex)}`;
    }
  }

  return text;
}

When rendering model output in a browser, use a safe Markdown or HTML processing method and add secure new-tab attributes to external links.

Failures and fallback behavior

Symptom	Action
No `groundingMetadata`	Display the answer normally and make it clear that this response has no Grounding sources to show
A source index is out of range	Ignore the invalid association, record the redacted response, and do not insert an incorrect link
Text positions do not match	Use a source list at the end of the answer instead of inserting citations at incorrect positions
Search failed	Use the response error to decide whether to retry a limited number of times or fall back to a non-search answer
Sources conflict	Show multiple sources and dates so the user can decide, rather than hiding important differences

Pre-production checklist

The current model supports Google Search Grounding.
The Gemini Endpoint uses the site Origin and does not produce /v1/v1beta.
Answer text, queries, sources, and segment mappings are stored separately.
An invalid citation index cannot crash the page.
External web content is not treated directly as trusted business instructions.
Missing sources never produce fabricated citations.

If the application uses Chat instead of the native Gemini structure, use the Chat search fields explicitly supported by the target model instead of copying the groundingMetadata parser directly.

On this page