Gemini API Guide: URL Context and Search Grounding

InYourLeague Research · 2026-09-05

Answer in brief

Gemini API provides built-in tool capabilities for URL context and Google Search grounding to enrich model interactions with web content. These tools allow developers to supply specific URLs for deep examination or automatically query the broader web to cite verifiable real-time sources. No product-specific selectable model ID has been verified for this entry.

Key facts at a glance

Failure modes and verification

FAQ

How does the URL context tool retrieve web page content?

The URL context tool uses a two-stage process: it first attempts to retrieve content from an internal index cache, and if the page is missing, it falls back to a live fetch.

What models are officially verified as supported for these tools?

No product-specific selectable model ID has been verified for this entry. Example configurations showing identifiers like gemini-3.6-flash or gemini-3.8-flash serve as illustrative examples rather than comprehensive model lists.

How can applications inspect retrieved sources and citations?

The model response includes url_citation annotations inside text content blocks, specifying the exact start_index, end_index, title, and source URL for citations.

Can URL context and Google Search grounding tools be combined?

Yes, both url_context and google_search tools can be specified together in the tools array to combine web-wide searching with deep analysis of target URLs.

Where can developers access the official documentation for grounding?

Official documentation is published at https://ai.google.dev/gemini-api/docs/url-context for URL context and https://ai.google.dev/gemini-api/docs/google-search for search grounding.

Sources and freshness

• Official source
• Official source
• Last verified: 2026-09-05

Extended guide

The Gemini API supports URL context and Google Search grounding tools within the Interactions API to connect model reasoning directly to web content. URL context retrieves and analyzes target web documents supplied by a caller, whereas Google Search grounding dynamically executes web queries to ground responses in fresh public data.

Core Grounding Capabilities and Architecture

When developing with the Gemini API, URL context and search grounding provide distinct retrieval workflows:

1. URL Context: Accepts target web addresses in requests to extract content, compare documents, synthesize summaries, or examine code repositories. The service executes a two-stage retrieval strategy: it checks an internal index cache for rapid responses and falls back to a live fetch if the page is missing from the index. Fetched web content is accounted for in interaction usage metrics as tool input tokens, and the system runs safety moderation checks where failing pages receive an unsafe status.
2. Google Search Grounding: When the google_search tool is enabled, the model evaluates user prompts, generates search queries autonomously if needed, processes search results, and outputs synthesized answers with inline citations. The returned interaction steps include search query calls (google_search_call) and search suggestion markup (google_search_result).
3. Combined Grounding: Applications can combine url_context and google_search simultaneously. This allows the model to leverage wide web search alongside detailed parsing of specific URLs.

Model Verification and Availability

No product-specific selectable model ID has been verified for this entry. While documentation examples demonstrate models such as gemini-3.6-flash for URL context and gemini-3.8-flash for Google Search, these selections represent illustrative sample configurations rather than an exhaustive specification or permanent default.

Step-by-Step Implementation Workflow

Setting up URL context and search grounding involves the following numbered steps:

1. Initialize the official SDK client (Client from google.genai).
2. Define tool definitions in the interaction request using {"type": "url_context"}, {"type": "google_search"}, or both.
3. Send the interaction request with the prompt and chosen tool configurations.
4. Traverse the interaction steps to extract generated text from model_output blocks.
5. Inspect the inline url_citation annotations attached to content blocks to link exact response character ranges (start_index to end_index) to source URLs.

Tool Comparison Table

Implementation Checklist

• Official documentation reviewed at URL Context Documentation and Google Search Grounding Documentation.
• Tools declared explicitly in the interaction request parameters (url_context, google_search).
• Inline url_citation annotations handled using start_index, end_index, title, and url attributes.
• Moderation status checked for URL fetching steps to handle potential unsafe flags.
• Note that no product-specific selectable model ID has been verified for this entry.