Repository Public
1The URL context tool lets you provide additional context to the models in the2form of URLs. By including URLs in your request, the model will access3the content from those pages (as long as it's not a URL type listed in the4[limitations section](https://ai.google.dev/gemini-api/docs/url-context#limitations)) to inform5and enhance its response.67The URL context tool is useful for tasks like the following:89- **Extract Data**: Pull specific info like prices, names, or key findings from multiple URLs.10- **Compare Documents**: Analyze multiple reports, articles, or PDFs to identify differences and track trends.11- **Synthesize \& Create Content**: Combine information from several source URLs to generate accurate summaries, blog posts, or reports.12- **Analyze Code \& Docs**: Point to a GitHub repository or technical documentation to explain code, generate setup instructions, or answer questions.1314The following example shows how to compare two recipes from different websites.1516### Python1718 # This will only work for SDK newer than 2.0.019 from google import genai2021 client = genai.Client()2223 url1 = "https://www.foodnetwork.com/recipes/ina-garten/perfect-roast-chicken-recipe-1940592"24 url2 = "https://www.allrecipes.com/recipe/21151/simple-whole-roast-chicken/"2526 interaction = client.interactions.create(27 model="gemini-3.8-flash",28 input=f"Compare the ingredients and cooking times from the recipes at {url1} and {url2}",29 tools=[{"type": "url_context"}]30 )3132 # Print the model's text response and its source annotations33 for step in interaction.steps:34 if step.type == "model_output":35 for content_block in step.content:36 if content_block.type == "text":37 print(content_block.text)38 if content_block.annotations:39 print("\nSources:")40 for annotation in content_block.annotations:41 if annotation.type == "url_citation":42 print(f" - {annotation.title}: {annotation.url}")4344### Javascript4546 // This will only work for SDK newer than 2.0.047 import { GoogleGenAI } from "@google/genai";4849 const client = new GoogleGenAI({});5051 async function main() {52 const interaction = await client.interactions.create({53 model: "gemini-3.8-flash",54 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/",55 tools: [{ type: "url_context" }]56 });5758 // Print the model's text response and its source annotations59 for (const step of interaction.steps) {60 if (step.type === 'model_output') {61 for (const contentBlock of step.content) {62 if (contentBlock.type === 'text') {63 console.log(contentBlock.text);64 if (contentBlock.annotations) {65 console.log("\nSources:");66 for (const annotation of contentBlock.annotations) {67 if (annotation.type === 'url_citation') {68 console.log(` - ${annotation.title}: ${annotation.url}`);69 }70 }71 }72 }73 }74 }75 }76 }7778 await main();7980### REST8182 # Specifies the API revision to avoid breaking changes when they become default83 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \84 -H "x-goog-api-key: $GEMINI_API_KEY" \85 -H "Content-Type: application/json" \86 -d '{87 "model": "gemini-3.8-flash",88 "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/",89 "tools": [{"type": "url_context"}]90 }'9192## How it works9394The URL Context tool uses a two-step retrieval process to95balance speed, cost, and access to fresh data. When you provide a URL, the tool96first attempts to fetch the content from an internal index cache. This acts as a97highly optimized cache. If a URL is not available in the index (for example, if98it's a very new page), the tool automatically falls back to do a live fetch.99This directly accesses the URL to retrieve its content in real-time.100101## Combining with other tools102103You can combine the URL context tool with other tools to create more powerful104workflows.105106[Gemini 3 models](https://ai.google.dev/gemini-api/docs/url-context#supported-models) support combining built-in tools107(like URL Context) with custom tools (function calling). Learn more on the108[tool combinations](https://ai.google.dev/gemini-api/docs/tool-combination) page.109110### Grounding with search111112When both URL context and113[Grounding with Google Search](https://ai.google.dev/gemini-api/docs/grounding) are enabled,114the model can use its search capabilities to find115relevant information online and then use the URL context tool to get a more116in-depth understanding of the pages it finds. This approach is powerful for117prompts that require both broad searching and deep analysis of specific pages.118119### Python120121 # This will only work for SDK newer than 2.0.0122 from google import genai123124 client = genai.Client()125126 interaction = client.interactions.create(127 model="gemini-3.8-flash",128 input="Give me three day events schedule based on YOUR_URL. Also let me know what needs to taken care of considering weather and commute.",129 tools=[130 {"type": "url_context"},131 {"type": "google_search"}132 ]133 )134135 for step in interaction.steps:136 if step.type == "model_output":137 for content_block in step.content:138 if content_block.type == "text":139 print(content_block.text)140141### Javascript142143 // This will only work for SDK newer than 2.0.0144 import { GoogleGenAI } from "@google/genai";145146 const client = new GoogleGenAI({});147148 async function main() {149 const interaction = await client.interactions.create({150 model: "gemini-3.8-flash",151 input: "Give me three day events schedule based on YOUR_URL. Also let me know what needs to taken care of considering weather and commute.",152 tools: [153 { type: "url_context" },154 { type: "google_search" }155 ]156 });157158 for (const step of interaction.steps) {159 if (step.type === 'model_output') {160 for (const contentBlock of step.content) {161 if (contentBlock.type === 'text') console.log(contentBlock.text);162 }163 }164 }165 }166167 await main();168169### REST170171 # Specifies the API revision to avoid breaking changes when they become default172 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \173 -H "x-goog-api-key: $GEMINI_API_KEY" \174 -H "Content-Type: application/json" \175 -d '{176 "model": "gemini-3.8-flash",177 "input": "Give me three day events schedule based on YOUR_URL. Also let me know what needs to taken care of considering weather and commute.",178 "tools": [179 {"type": "url_context"},180 {"type": "google_search"}181 ]182 }'183184## Understanding the response185186When the model uses the URL context tool, its text response includes inline187`url_citation` annotations on the text content block. Each annotation links a188segment of the response text (via `start_index` and `end_index`) to the source189URL it was derived from. This is the primary way to surface citations in your190application --- see the [main example above](https://ai.google.dev/gemini-api/docs/url-context#get-started) for how to extract them.191192The response also includes a `url_context_result` step with metadata about each193URL retrieval attempt (status, retrieved URL). This is mainly useful for194debugging.195196### Safety checks197198The system performs a content moderation check on URLs to confirm199they meet safety standards. If a URL fails this check, the corresponding200`url_context_result` step will show a `status` of `"unsafe"`.201202### Token count203204The content retrieved from the URLs you specify in your prompt is counted205as part of the input tokens. You can see the token count in the206`usage` object of the interaction. The following is an example:207208 'usage': {209 'output_tokens': 45,210 'input_tokens': 27,211 'input_tokens_details': [{'modality': 'TEXT', 'token_count': 27}],212 'thoughts_tokens': 31,213 'tool_use_input_tokens': 10309,214 'tool_use_input_tokens_details': [{'modality': 'TEXT', 'token_count': 10309}],215 'total_tokens': 10412216 }217218Price per token depends on the model used, see the219[pricing](https://ai.google.dev/gemini-api/docs/pricing) page for details.220221## Supported models222223| Model | URL Context |224|---|---|225| [Gemini 3.8 Flash](https://ai.google.dev/gemini-api/docs/models/gemini-3.8-flash) | ✔️ |226| [Gemini 3.7 Flash](https://ai.google.dev/gemini-api/docs/models/gemini-3.7-flash) | ✔️ |227| [Gemini 3.6 Flash](https://ai.google.dev/gemini-api/docs/models/gemini-3.6-flash) | ✔️ |228| [Gemini 3.5 Flash-Lite](https://ai.google.dev/gemini-api/docs/models/gemini-3.5-flash-lite) | ✔️ |229| [Gemini 3.5 Flash](https://ai.google.dev/gemini-api/docs/models/gemini-3.5-flash) | ✔️ |230| [Gemini 3.1 Pro Preview](https://ai.google.dev/gemini-api/docs/models/gemini-3.1-pro-preview) | ✔️ |231| [Gemini 3.1 Flash-Lite](https://ai.google.dev/gemini-api/docs/models/gemini-3.1-flash-lite) | ✔️ |232| [Gemini 3 Flash Preview](https://ai.google.dev/gemini-api/docs/models/gemini-3-flash-preview) | ✔️ |233| [Gemini 2.5 Pro](https://ai.google.dev/gemini-api/docs/models/gemini-2.5-pro) | ✔️ |234| [Gemini 2.5 Flash](https://ai.google.dev/gemini-api/docs/models/gemini-2.5-flash) | ✔️ |235| [Gemini 2.5 Flash-Lite](https://ai.google.dev/gemini-api/docs/models/gemini-2.5-flash-lite) | ✔️ |236237## Best Practices238239- **Provide specific URLs**: For the best results, provide direct URLs to the content you want the model to analyze. The model will only retrieve content from the URLs you provide, not any content from nested links.240- **Check for accessibility**: Verify that the URLs you provide don't lead to pages that require a login or are behind a paywall.241- **Use the complete URL**: Provide the full URL, including the protocol (e.g., https://www.google.com instead of just google.com).242243## Limitations244245- Request limit: The tool can process up to 20 URLs per request.246- URL content size: The maximum size for content retrieved from a single URL is 34MB.247- Public accessibility: The URLs must be publicly accessible on the web. Localhost addresses (e.g., localhost, 127.0.0.1), private networks, and tunneling services (e.g., ngrok, pinggy) are not supported.248249### Supported and unsupported content types250251The tool can extract content from URLs with the following content types:252253- Text (text/html, application/json, text/plain, text/xml, text/css, text/javascript , text/csv, text/rtf)254- Image (image/png, image/jpeg, image/bmp, image/webp)255- PDF (application/pdf)256257The following content types are **not** supported:258259- Paywalled content260- YouTube videos (See [video understanding](https://ai.google.dev/gemini-api/docs/video-understanding#youtube) to learn how to process YouTube URLs)261- Google workspace files like Google docs or spreadsheets262- Video and audio files