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/generate-content/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 from google import genai19 from google.genai.types import Tool, GenerateContentConfig2021 client = genai.Client()22 model_id = "gemini-3.8-flash"2324 tools = [25 {"url_context": {}},26 ]2728 url1 = "https://www.foodnetwork.com/recipes/ina-garten/perfect-roast-chicken-recipe-1940592"29 url2 = "https://www.allrecipes.com/recipe/21151/simple-whole-roast-chicken/"3031 response = client.models.generate_content(32 model=model_id,33 contents=f"Compare the ingredients and cooking times from the recipes at {url1} and {url2}",34 config=GenerateContentConfig(35 tools=tools,36 )37 )3839 for each in response.candidates[0].content.parts:40 print(each.text)4142 # For verification, you can inspect the metadata to see which URLs the model retrieved43 print(response.candidates[0].url_context_metadata)4445### Javascript4647 import { GoogleGenAI } from "@google/genai";4849 const ai = new GoogleGenAI({});5051 async function main() {52 const response = await ai.models.generateContent({53 model: "gemini-3.8-flash",54 contents: [55 "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/",56 ],57 config: {58 tools: [{urlContext: {}}],59 },60 });61 console.log(response.text);6263 // For verification, you can inspect the metadata to see which URLs the model retrieved64 console.log(response.candidates[0].urlContextMetadata)65 }6667 await main();6869### REST7071 curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent" \72 -H "x-goog-api-key: $GEMINI_API_KEY" \73 -H "Content-Type: application/json" \74 -d '{75 "contents": [76 {77 "parts": [78 {"text": "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/"}79 ]80 }81 ],82 "tools": [83 {84 "url_context": {}85 }86 ]87 }' > result.json8889 cat result.json9091## How it works9293The URL Context tool uses a two-step retrieval process to94balance speed, cost, and access to fresh data. When you provide a URL, the tool95first attempts to fetch the content from an internal index cache. This acts as a96highly optimized cache. If a URL is not available in the index (for example, if97it's a very new page), the tool automatically falls back to do a live fetch.98This directly accesses the URL to retrieve its content in real-time.99100## Combining with other tools101102You can combine the URL context tool with other tools to create more powerful103workflows.104105[Gemini 3 models](https://ai.google.dev/gemini-api/docs/generate-content/url-context#supported-models) support combining built-in tools106(like URL Context) with custom tools (function calling). Learn more on the107[tool combinations](https://ai.google.dev/gemini-api/docs/tool-combination) page.108109### Grounding with search110111When both URL context and112[Grounding with Google Search](https://ai.google.dev/gemini-api/docs/grounding) are enabled,113the model can use its search capabilities to find114relevant information online and then use the URL context tool to get a more115in-depth understanding of the pages it finds. This approach is powerful for116prompts that require both broad searching and deep analysis of specific pages.117118### Python119120 from google import genai121 from google.genai.types import Tool, GenerateContentConfig, GoogleSearch, UrlContext122123 client = genai.Client()124 model_id = "gemini-3.8-flash"125126 tools = [127 {"url_context": {}},128 {"google_search": {}}129 ]130131 response = client.models.generate_content(132 model=model_id,133 contents="Give me three day events schedule based on YOUR_URL. Also let me know what needs to taken care of considering weather and commute.",134 config=GenerateContentConfig(135 tools=tools,136 )137 )138139 for each in response.candidates[0].content.parts:140 print(each.text)141 # get URLs retrieved for context142 print(response.candidates[0].url_context_metadata)143144### Javascript145146 import { GoogleGenAI } from "@google/genai";147148 const ai = new GoogleGenAI({});149150 async function main() {151 const response = await ai.models.generateContent({152 model: "gemini-3.8-flash",153 contents: [154 "Give me three day events schedule based on YOUR_URL. Also let me know what needs to taken care of considering weather and commute.",155 ],156 config: {157 tools: [158 {urlContext: {}},159 {googleSearch: {}}160 ],161 },162 });163 console.log(response.text);164 // To get URLs retrieved for context165 console.log(response.candidates[0].urlContextMetadata)166 }167168 await main();169170### REST171172 curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent" \173 -H "x-goog-api-key: $GEMINI_API_KEY" \174 -H "Content-Type: application/json" \175 -d '{176 "contents": [177 {178 "parts": [179 {"text": "Give me three day events schedule based on YOUR_URL. Also let me know what needs to taken care of considering weather and commute."}180 ]181 }182 ],183 "tools": [184 {185 "url_context": {}186 },187 {188 "google_search": {}189 }190 ]191 }' > result.json192193 cat result.json194195## Understanding the response196197When the model uses the URL context tool, the response includes a198`url_context_metadata` object. This object lists the URLs the model retrieved199content from and the status of each retrieval attempt, which is useful for200verification and debugging.201202The following is an example of that part of the response203(parts of the response have been omitted for brevity):204205 {206 "candidates": [207 {208 "content": {209 "parts": [210 {211 "text": "... \n"212 }213 ],214 "role": "model"215 },216 ...217 "url_context_metadata": {218 "url_metadata": [219 {220 "retrieved_url": "https://www.foodnetwork.com/recipes/ina-garten/perfect-roast-chicken-recipe-1940592",221 "url_retrieval_status": "URL_RETRIEVAL_STATUS_SUCCESS"222 },223 {224 "retrieved_url": "https://www.allrecipes.com/recipe/21151/simple-whole-roast-chicken/",225 "url_retrieval_status": "URL_RETRIEVAL_STATUS_SUCCESS"226 }227 ]228 }229 }230 ]231 }232233For complete detail about this object , see the234[`UrlContextMetadata` API reference](https://ai.google.dev/api/generate-content#UrlContextMetadata).235236### Safety checks237238The system performs a content moderation check on the URL to confirm239they meet safety standards. If the URL you provided fails this check, you will240get an `url_retrieval_status` of `URL_RETRIEVAL_STATUS_UNSAFE`.241242### Token count243244The content retrieved from the URLs you specify in your prompt is counted245as part of the input tokens. You can see the token count for your prompt and246tools usage in the [`usage_metadata`](https://ai.google.dev/api/generate-content#UsageMetadata)247object of the model output. The following is an example output:248249 'usage_metadata': {250 'candidates_token_count': 45,251 'prompt_token_count': 27,252 'prompt_tokens_details': [{'modality': <MediaModality.TEXT: 'TEXT'>,253 'token_count': 27}],254 'thoughts_token_count': 31,255 'tool_use_prompt_token_count': 10309,256 'tool_use_prompt_tokens_details': [{'modality': <MediaModality.TEXT: 'TEXT'>,257 'token_count': 10309}],258 'total_token_count': 10412259 }260261Price per token depends on the model used, see the262[pricing](https://ai.google.dev/gemini-api/docs/pricing) page for details.263264## Supported models265266| Model | URL Context |267|---|---|268| [Gemini 3.8 Flash](https://ai.google.dev/gemini-api/docs/models/gemini-3.8-flash) | ✔️ |269| [Gemini 3.7 Flash](https://ai.google.dev/gemini-api/docs/models/gemini-3.7-flash) | ✔️ |270| [Gemini 3.6 Flash](https://ai.google.dev/gemini-api/docs/models/gemini-3.6-flash) | ✔️ |271| [Gemini 3.5 Flash-Lite](https://ai.google.dev/gemini-api/docs/models/gemini-3.5-flash-lite) | ✔️ |272| [Gemini 3.5 Flash](https://ai.google.dev/gemini-api/docs/models/gemini-3.5-flash) | ✔️ |273| [Gemini 3.1 Pro Preview](https://ai.google.dev/gemini-api/docs/models/gemini-3.1-pro-preview) | ✔️ |274| [Gemini 3.1 Flash-Lite](https://ai.google.dev/gemini-api/docs/models/gemini-3.1-flash-lite) | ✔️ |275| [Gemini 3 Flash Preview](https://ai.google.dev/gemini-api/docs/models/gemini-3-flash-preview) | ✔️ |276| [Gemini 2.5 Pro](https://ai.google.dev/gemini-api/docs/models/gemini-2.5-pro) | ✔️ |277| [Gemini 2.5 Flash](https://ai.google.dev/gemini-api/docs/models/gemini-2.5-flash) | ✔️ |278| [Gemini 2.5 Flash-Lite](https://ai.google.dev/gemini-api/docs/models/gemini-2.5-flash-lite) | ✔️ |279280## Best Practices281282- **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.283- **Check for accessibility**: Verify that the URLs you provide don't lead to pages that require a login or are behind a paywall.284- **Use the complete URL**: Provide the full URL, including the protocol (e.g., https://www.google.com instead of just google.com).285286## Limitations287288- Function calling: Tool use (URL Context, Grounding with Google Search, etc) with function calling is currently unsupported.289- Request limit: The tool can process up to 20 URLs per request.290- URL content size: The maximum size for content retrieved from a single URL is 34MB.291- 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.292293### Supported and unsupported content types294295The tool can extract content from URLs with the following content types:296297- Text (text/html, application/json, text/plain, text/xml, text/css, text/javascript , text/csv, text/rtf)298- Image (image/png, image/jpeg, image/bmp, image/webp)299- PDF (application/pdf)300301The following content types are **not** supported:302303- Paywalled content304- YouTube videos (See [video understanding](https://ai.google.dev/gemini-api/docs/video-understanding#youtube) to learn how to process YouTube URLs)305- Google workspace files like Google docs or spreadsheets306- Video and audio files307308## What's next309310- Explore the [URL context cookbook](https://colab.sandbox.google.com/github/google-gemini/cookbook/blob/main/quickstarts/Grounding.ipynb#url-context) for more examples.