Repository Public
1# URL context23> [!NOTE]4> **Note** : This version of the page covers the new [Interactions API](https://ai.google.dev/gemini-api/docs/interactions/interactions-overview), which is currently in Beta. 5> For stable production deployments, we recommend you continue to use the `generateContent` API. You can use the toggle on this page to switch between the versions.67The URL context tool lets you provide additional context to the models in the8form of URLs. By including URLs in your request, the model will access9the content from those pages (as long as it's not a URL type listed in the10[limitations section](https://ai.google.dev/gemini-api/docs/interactions/url-context#limitations)) to inform11and enhance its response.1213The URL context tool is useful for tasks like the following:1415- **Extract Data**: Pull specific info like prices, names, or key findings from multiple URLs.16- **Compare Documents**: Analyze multiple reports, articles, or PDFs to identify differences and track trends.17- **Synthesize \& Create Content**: Combine information from several source URLs to generate accurate summaries, blog posts, or reports.18- **Analyze Code \& Docs**: Point to a GitHub repository or technical documentation to explain code, generate setup instructions, or answer questions.1920The following example shows how to compare two recipes from different websites.2122### Python2324 # This will only work for SDK newer than 2.0.025 from google import genai2627 client = genai.Client()2829 url1 = "https://www.foodnetwork.com/recipes/ina-garten/perfect-roast-chicken-recipe-1940592"30 url2 = "https://www.allrecipes.com/recipe/21151/simple-whole-roast-chicken/"3132 interaction = client.interactions.create(33 model="gemini-3.5-flash",34 input=f"Compare the ingredients and cooking times from the recipes at {url1} and {url2}",35 tools=[{"type": "url_context"}]36 )3738 # Print the model's text response and its source annotations39 for step in interaction.steps:40 if step.type == "model_output":41 for content_block in step.content:42 if content_block.type == "text":43 print(content_block.text)44 if content_block.annotations:45 print("\nSources:")46 for annotation in content_block.annotations:47 if annotation.type == "url_citation":48 print(f" - {annotation.title}: {annotation.url}")4950### Javascript5152 // This will only work for SDK newer than 2.0.053 import { GoogleGenAI } from "@google/genai";5455 const client = new GoogleGenAI({});5657 async function main() {58 const interaction = await client.interactions.create({59 model: "gemini-3.5-flash",60 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/",61 tools: [{ type: "url_context" }]62 });6364 // Print the model's text response and its source annotations65 for (const step of interaction.steps) {66 if (step.type === 'model_output') {67 for (const contentBlock of step.content) {68 if (contentBlock.type === 'text') {69 console.log(contentBlock.text);70 if (contentBlock.annotations) {71 console.log("\nSources:");72 for (const annotation of contentBlock.annotations) {73 if (annotation.type === 'url_citation') {74 console.log(` - ${annotation.title}: ${annotation.url}`);75 }76 }77 }78 }79 }80 }81 }82 }8384 await main();8586### REST8788 # Specifies the API revision to avoid breaking changes when they become default89 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \90 -H "x-goog-api-key: $GEMINI_API_KEY" \91 -H "Content-Type: application/json" \92 -H "Api-Revision: 2026-05-20" \93 -d '{94 "model": "gemini-3.5-flash",95 "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/",96 "tools": [{"type": "url_context"}]97 }'9899## How it works100101The URL Context tool uses a two-step retrieval process to102balance speed, cost, and access to fresh data. When you provide a URL, the tool103first attempts to fetch the content from an internal index cache. This acts as a104highly optimized cache. If a URL is not available in the index (for example, if105it's a very new page), the tool automatically falls back to do a live fetch.106This directly accesses the URL to retrieve its content in real-time.107108## Combining with other tools109110You can combine the URL context tool with other tools to create more powerful111workflows.112113[Gemini 3 models](https://ai.google.dev/gemini-api/docs/interactions/url-context#supported-models) support combining built-in tools114(like URL Context) with custom tools (function calling). Learn more on the115[tool combinations](https://ai.google.dev/gemini-api/docs/interactions/tool-combination) page.116117### Grounding with search118119When both URL context and120[Grounding with Google Search](https://ai.google.dev/gemini-api/docs/grounding) are enabled,121the model can use its search capabilities to find122relevant information online and then use the URL context tool to get a more123in-depth understanding of the pages it finds. This approach is powerful for124prompts that require both broad searching and deep analysis of specific pages.125126### Python127128 # This will only work for SDK newer than 2.0.0129 from google import genai130131 client = genai.Client()132133 interaction = client.interactions.create(134 model="gemini-3.5-flash",135 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.",136 tools=[137 {"type": "url_context"},138 {"type": "google_search"}139 ]140 )141142 for step in interaction.steps:143 if step.type == "model_output":144 for content_block in step.content:145 if content_block.type == "text":146 print(content_block.text)147148### Javascript149150 // This will only work for SDK newer than 2.0.0151 import { GoogleGenAI } from "@google/genai";152153 const client = new GoogleGenAI({});154155 async function main() {156 const interaction = await client.interactions.create({157 model: "gemini-3.5-flash",158 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.",159 tools: [160 { type: "url_context" },161 { type: "google_search" }162 ]163 });164165 for (const step of interaction.steps) {166 if (step.type === 'model_output') {167 for (const contentBlock of step.content) {168 if (contentBlock.type === 'text') console.log(contentBlock.text);169 }170 }171 }172 }173174 await main();175176### REST177178 # Specifies the API revision to avoid breaking changes when they become default179 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \180 -H "x-goog-api-key: $GEMINI_API_KEY" \181 -H "Content-Type: application/json" \182 -H "Api-Revision: 2026-05-20" \183 -d '{184 "model": "gemini-3.5-flash",185 "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.",186 "tools": [187 {"type": "url_context"},188 {"type": "google_search"}189 ]190 }'191192## Understanding the response193194When the model uses the URL context tool, its text response includes inline195`url_citation` annotations on the text content block. Each annotation links a196segment of the response text (via `start_index` and `end_index`) to the source197URL it was derived from. This is the primary way to surface citations in your198application --- see the [main example above](https://ai.google.dev/gemini-api/docs/interactions/url-context#get-started) for how to extract them.199200The response also includes a `url_context_result` step with metadata about each201URL retrieval attempt (status, retrieved URL). This is mainly useful for202debugging.203204### Safety checks205206The system performs a content moderation check on URLs to confirm207they meet safety standards. If a URL fails this check, the corresponding208`url_context_result` step will show a `status` of `"unsafe"`.209210### Token count211212The content retrieved from the URLs you specify in your prompt is counted213as part of the input tokens. You can see the token count in the214`usage` object of the interaction. The following is an example:215216 'usage': {217 'output_tokens': 45,218 'input_tokens': 27,219 'input_tokens_details': [{'modality': 'TEXT', 'token_count': 27}],220 'thoughts_tokens': 31,221 'tool_use_input_tokens': 10309,222 'tool_use_input_tokens_details': [{'modality': 'TEXT', 'token_count': 10309}],223 'total_tokens': 10412224 }225226Price per token depends on the model used, see the227[pricing](https://ai.google.dev/gemini-api/docs/pricing) page for details.228229## Supported models230231| Model | URL Context |232|---|---|233| [Gemini 3.5 Flash](https://ai.google.dev/gemini-api/docs/models/gemini-3.5-flash) | ✔️ |234| [Gemini 3.1 Pro Preview](https://ai.google.dev/gemini-api/docs/models/gemini-3.1-pro-preview) | ✔️ |235| [Gemini 3.1 Flash-Lite](https://ai.google.dev/gemini-api/docs/models/gemini-3.1-flash-lite) | ✔️ |236| [Gemini 3 Flash Preview](https://ai.google.dev/gemini-api/docs/models/gemini-3-flash-preview) | ✔️ |237| [Gemini 2.5 Pro](https://ai.google.dev/gemini-api/docs/models/gemini-2.5-pro) | ✔️ |238| [Gemini 2.5 Flash](https://ai.google.dev/gemini-api/docs/models/gemini-2.5-flash) | ✔️ |239| [Gemini 2.5 Flash-Lite](https://ai.google.dev/gemini-api/docs/models/gemini-2.5-flash-lite) | ✔️ |240241## Best Practices242243- **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.244- **Check for accessibility**: Verify that the URLs you provide don't lead to pages that require a login or are behind a paywall.245- **Use the complete URL**: Provide the full URL, including the protocol (e.g., https://www.google.com instead of just google.com).246247## Limitations248249- Request limit: The tool can process up to 20 URLs per request.250- URL content size: The maximum size for content retrieved from a single URL is 34MB.251- 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.252- Gemini API only: URL Context is only available in the Gemini API, not through Gemini Enterprise Agent Platform.253254### Supported and unsupported content types255256The tool can extract content from URLs with the following content types:257258- Text (text/html, application/json, text/plain, text/xml, text/css, text/javascript , text/csv, text/rtf)259- Image (image/png, image/jpeg, image/bmp, image/webp)260- PDF (application/pdf)261262The following content types are **not** supported:263264- Paywalled content265- YouTube videos (See [video understanding](https://ai.google.dev/gemini-api/docs/interactions/video-understanding#youtube) to learn how to process YouTube URLs)266- Google workspace files like Google docs or spreadsheets267- Video and audio files