Gemini API URL Context Tool: Code and Limits

The Gemini API URL context tool lets you pass public web links directly into your prompt so the model fetches and analyzes the live page content. Instead of scraping HTML, stripping boilerplate, and managing custom web scrapers, you hand the URL to Gemini, and Google's backend retrieves the text, image, or PDF data for you.

To enable it, pass {"type": "url_context"} inside the tools array of an interactions.create call using the Google GenAI SDK (version 2.0.0 or newer). The retrieved document data is converted into tokens and charged as regular input tokens based on your chosen model.

How the URL context tool works#

Google's URL context documentation notes that the tool uses a two-step retrieval workflow to balance speed, fresh data, and overhead:

1. Index cache check: The engine first checks an internal, optimized index cache for the requested URL.
2. Live fetch fallback: If the URL is fresh, unindexed, or missing from that cache, the tool automatically performs a real-time HTTP fetch to retrieve the live content.

Once retrieved, the document text feeds directly into the interaction context alongside your prompt text. The response also gives you back structured source citations and diagnostic steps so you can inspect how each link was evaluated.

Supported models and status#

According to the official Gemini changelog, Google moved the URL context tool to general availability (GA) on August 18, 2025. As of October 20, 2026, the tool works across both preview and stable releases in the Gemini 2.5, Gemini 3, and Gemini 4 families.

Official docs list URL context support across these specific models:

• gemini-4-argon
• gemini-3.8-flash
• gemini-3.6-flash
• gemini-3.5-flash-lite
• gemini-3.1-pro-preview
• gemini-3.1-flash-lite
• gemini-3-flash-preview
• gemini-2.5-pro
• gemini-2.5-flash
• gemini-2.5-flash-lite

If you want to run standard prompts and streaming with the newer SDK before layering in tools, review our guide on Gemini API Python setup. To deploy on Google's flagship reasoning model, check out our guide on calling Gemini 4 Argon step by step.

Python example using the GenAI SDK#

To use the tool in Python, you must use SDK version newer than 2.0.0 (google-genai). The tool connects through the interactions.create interface rather than legacy text generation endpoints.

Here is how to compare two live recipe URLs:

# Requires google-genai SDK > 2.0.0
from google import genai

client = genai.Client()

url1 = "https://www.foodnetwork.com/recipes/ina-garten/perfect-roast-chicken-recipe-1940592"
url2 = "https://www.allrecipes.com/recipe/21151/simple-whole-roast-chicken/"

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=f"Compare the ingredients and cooking times from the recipes at {url1} and {url2}",
    tools=[{"type": "url_context"}]
)

for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)

Extracting citations and step metadata#

When Gemini relies on a URL, it populates url_citation blocks inside the annotations array for that text block. Each citation provides the source title, the target URL, and integer character offsets (start_index and end_index) marking which part of the answer relies on that page.

The interaction also returns a url_context_result step. If a link triggers moderation flags, this step will show a status of "unsafe".

You can inspect how citations map to output blocks locally using plain Python:

response_data = {
    "text": "The Ina Garten recipe calls for roasting at 425 degrees F, while the Allrecipes version bakes at 350 degrees F.",
    "annotations": [
        {
            "type": "url_citation",
            "title": "Perfect Roast Chicken",
            "url": "https://www.foodnetwork.com/recipes/ina-garten/perfect-roast-chicken-recipe-1940592",
            "start_index": 0,
            "end_index": 66
        },
        {
            "type": "url_citation",
            "title": "Simple Whole Roast Chicken",
            "url": "https://www.allrecipes.com/recipe/21151/simple-whole-roast-chicken/",
            "start_index": 74,
            "end_index": 113
        }
    ]
}

text = response_data["text"]
print("Model text:")
print(text)
print("\nExtracted citations:")
for citation in response_data["annotations"]:
    segment = text[citation["start_index"]:citation["end_index"]]
    print(f"- [{citation['title']}] ({citation['url']})")
    print(f"  Claims: \"{segment}\"")

REST API request#

If you are calling the Gemini API from cURL or an HTTP client, send a POST request to the /v1beta/interactions endpoint. Make sure your payload declares the tools array alongside your prompt string:

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": "Compare the ingredients and cooking times from the recipes at https://www.foodnetwork.com/recipes/ina-garten/perfect-roast-chicken-recipe-1940592 and https://www.allrecipes.com/recipe/21151/simple-whole-roast-chicken/",
    "tools": [{"type": "url_context"}]
  }'

Combining URL context with Google Search#

Gemini 3 models allow mixing built-in tools. You can pair url_context with google_search so the model can search Google for broader context (such as local weather or road closures) and combine that data with a specific schedule link:

# Requires google-genai SDK > 2.0.0
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Give me three day events schedule based on https://example.com/festival. Also let me know what needs to taken care of considering weather and commute.",
    tools=[
        {"type": "url_context"},
        {"type": "google_search"}
    ]
)

for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)

Token counts and pricing impact#

The URL context tool is free of platform surcharges, but all content retrieved from the web is parsed and billed as input tokens according to the selected model's standard rates on Google's pricing page.

When a response arrives, the usage object details your billable footprint under tool_use_input_tokens:

'usage': {
 'output_tokens': 45,
 'input_tokens': 27,
 'input_tokens_details': [{'modality': 'TEXT', 'token_count': 27}],
 'thoughts_tokens': 31,
 'tool_use_input_tokens': 10309,
 'tool_use_input_tokens_details': [{'modality': 'TEXT', 'token_count': 10309}],
 'total_tokens': 10412
}

In this example, your original prompt was 27 tokens, but reading the target webpage added 10,309 tokens under tool_use_input_tokens, bringing total billable input tokens to 10,336. If you are tracking tokens or evaluating long-horizon costs, see our breakdown of Gemini 4 Argon pricing and token limits.

Strict limits and unsupported formats#

Google enforces hard boundaries on what the tool can retrieve. Keep these limits in mind when validating user input:

Supported MIME types#

The tool natively handles three main categories: * Text: text/html, application/json, text/plain, text/xml, text/css, text/javascript, text/csv, and text/rtf. * Images: image/png, image/jpeg, image/bmp, and image/webp. * PDFs: application/pdf.

Common pitfalls#

• Omitting the protocol schema: Passing foodnetwork.com/... instead of https://foodnetwork.com/... causes the fetcher to fail. Always supply the absolute URI including https://.
• Assuming crawl traversal: The model only reads the specific URL provided. It will not click nested links or crawl child pages.
• Using deprecated models: Avoid calling retired endpoints like gemini-2.0-flash, gemini-3.5-flash, or gemini-3.7-flash. As noted in the October 8, 2026 changelog update, gemini-3.7-flash is replaced by gemini-3.8-flash, and gemini-3.5-flash is replaced by gemini-3.6-flash.
• Testing against private dev servers: Pointing the tool at staging servers, intranet hosts, or tunneling utilities like ngrok fails silently or yields safety check errors because Google's crawlers cannot reach private hosts.

Quick implementation checklist#

• Upgrade to google-genai SDK version > 2.0.0.
• Use the /v1beta/interactions endpoint or client.interactions.create.
• Declare tools=[{"type": "url_context"}].
• Include complete URLs starting with https:// directly inside the prompt text.
• Keep total URLs at 20 or fewer per API call.
• Keep individual page sizes below 34MB.
• Parse annotations inside content blocks to show citations in your interface.

Quick answers