You can use the URL context tool to provide Gemini with URLs as additionalcontext for your prompt. The model can then retrieve content from the URLs anduse that content to inform and shape its response.

This tool is useful for tasks like the following:

• Extracting key data points or talking points from articles
• Comparing information across multiple links
• Synthesizing data from several sources
• Answering questions based on the content of a specific page or pages
• Analyzing content for specific purposes (like writing a jobdescription or creating test questions)

Note that the index used to pull data may not necessarily be up to date, so someinformation may be stale.

This guide explains how to use the URL context tool in the Gemini API in Vertex AI.

Supported models

The following models provide support for URL Context:

• Gemini 3 PropreviewPreview model
• Gemini 2.5 Pro
• Gemini 2.5 FlashpreviewPreview model
• Gemini 2.5 Flash-LitepreviewPreview model
• Gemini 2.5 Flash
• Gemini 2.5 Flash-Lite
• Gemini 2.0 Flash

Use URL context

You can use the URL context tool in two main ways, by itself or in conjunctionwithGrounding with Google Search.

URL context only

You can provide specific URLs that you want the model to analyze directly inyour prompt:

Summarize this document:YOUR_URLsExtract the key features from the product description on this page:YOUR_URLs

fromgoogleimportgenaifromgoogle.genai.typesimportTool,GenerateContentConfig,HttpOptions,UrlContextclient=genai.Client(http_options=HttpOptions(api_version="v1"))model_id="gemini-2.5-flash"url_context_tool=Tool(url_context=UrlContext)response=client.models.generate_content(model=model_id,contents="Compare recipes fromYOUR_URL1 andYOUR_URL2",config=GenerateContentConfig(tools=[url_context_tool],response_modalities=["TEXT"],))foreachinresponse.candidates[0].content.parts:print(each.text)# get URLs retrieved for contextprint(response.candidates[0].url_context_metadata)

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values# with appropriate values for your project.exportGOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECTexportGOOGLE_CLOUD_LOCATION=globalexportGOOGLE_GENAI_USE_VERTEXAI=True

import{GoogleGenAI}from"@google/genai";constai=newGoogleGenAI({vertexai:true,project:process.env.GOOGLE_CLOUD_PROJECT,location:process.env.GOOGLE_CLOUD_LOCATION,apiVersion:'v1',});asyncfunctionmain(){constresponse=awaitai.models.generateContent({model:"gemini-2.5-flash",contents:["Compare recipes fromYOUR_URL1 andYOUR_URL2",],config:{tools:[{urlContext:{}}],},});console.log(response.text);// To get URLs retrieved for contextconsole.log(response.candidates[0].urlContextMetadata)}awaitmain();

curl-XPOST\-H"Authorization: Bearer$(gcloudauthprint-access-token)"\-H"Content-Type: application/json"\https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/publishers/google/models/gemini-2.5-flash:generateContent\-d'{      "contents": [          {              "role": "user",              "parts": [                  {"text": "Compare recipes fromYOUR_URL1 andYOUR_URL2"}              ]          }      ],      "tools": [          {              "url_context": {}          }      ]  }' >result.jsoncatresult.json

Grounding with Google Search with URL context

You can also enable both URL context and Grounding with Google Search,using prompts with or without URLs. The model may firstsearch for relevant information and then use the URL context tool to read thecontent of the search results for a more in-depth understanding.

This feature is experimental and available in API versionv1beta1.

Example prompts:

Give me a three day event schedule based onYOUR_URL. Also let me know what needs to taken care of considering weather and commute.Recommend 3 books for beginners to read to learn more about the latestYOUR_SUBJECT.

fromgoogleimportgenaifromgoogle.genai.typesimportTool,GenerateContentConfig,HttpOptions,UrlContext,GoogleSearchclient=genai.Client(http_options=HttpOptions(api_version="v1beta1"))model_id="gemini-2.5-flash"tools=[]tools.append(Tool(url_context=UrlContext))tools.append(Tool(google_search=GoogleSearch))response=client.models.generate_content(model=model_id,contents="Give me three day events schedule based onYOUR_URL. Also let me know what needs to taken care of considering weather and commute.",config=GenerateContentConfig(tools=tools,response_modalities=["TEXT"],))foreachinresponse.candidates[0].content.parts:print(each.text)# get URLs retrieved for contextprint(response.candidates[0].url_context_metadata)

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values# with appropriate values for your project.exportGOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECTexportGOOGLE_CLOUD_LOCATION=globalexportGOOGLE_GENAI_USE_VERTEXAI=True

import{GoogleGenAI}from"@google/genai";constai=newGoogleGenAI({vertexai:true,project:process.env.GOOGLE_CLOUD_PROJECT,location:process.env.GOOGLE_CLOUD_LOCATION,apiVersion:'v1beta1',});asyncfunctionmain(){constresponse=awaitai.models.generateContent({model:"gemini-2.5-flash",contents:["Give me a three day event schedule based onYOUR_URL. Also let me know what needs to taken care of considering weather and commute.",],config:{tools:[{urlContext:{}},{googleSearch:{}}],},});console.log(response.text);// To get URLs retrieved for contextconsole.log(response.candidates[0].urlContextMetadata)}awaitmain();

curl-XPOST\-H"Authorization: Bearer$(gcloudauthprint-access-token)"\-H"Content-Type: application/json"\https://aiplatform.googleapis.com/v1beta1/projects/GOOGLE_CLOUD_PROJECT/locations/global/publishers/google/models/gemini-2.5-flash:generateContent\-d'{      "contents": [          {              "role": "user",              "parts": [                  {"text": "Give me a three day event schedule based onYOUR_URL. Also let me know what needs to taken care of considering weather and commute."}              ]          }      ],      "tools": [          {              "url_context": {}          },          {              "google_search": {}          }      ]  }' >result.jsoncatresult.json

For more details about Grounding with Google Search, see theoverview page.

Web Grounding for Enterprise with URL context

You can enable both URL context and Web Grounding for Enterpriseif you have specific compliance needs or are in a regulated industrylike health, finance, or the public sector. The web index used in Web Grounding for Enterpriseis more limited than the standard Grounding with Google Search index, as ituses a subset of what's available on Google Search.

For more details about Web Grounding for Enterprise, see theWeb Grounding for Enterprise page.

Contextual response

The model's response is based on the content it retrieved from the URLs. If themodel retrieved content from URLs, the response will includeurl_context_metadata. Such a response might look something like the following(parts of the response have been omitted for brevity):

{"candidates":[{"content":{"parts":[{"text":"... \n"}],"role":"model"},..."url_context_metadata":{"url_metadata":[{"retrieved_url":"https://cloud.google.com/vertex-ai/generative-ai/docs/multimodal/code-execution","url_retrieval_status":<UrlRetrievalStatus.URL_RETRIEVAL_STATUS_SUCCESS:"URL_RETRIEVAL_STATUS_SUCCESS">},{"retrieved_url":"https://cloud.google.com/vertex-ai/generative-ai/docs/grounding/grounding-with-google-search","url_retrieval_status":<UrlRetrievalStatus.URL_RETRIEVAL_STATUS_SUCCESS:"URL_RETRIEVAL_STATUS_SUCCESS">},]}}]}

For more information about this object, see theUrlContextMetadata API reference.

Live fetch

The URL context tool fetches live versions of web pages to keep your informationcurrent.

To efficiently retrieve web page content, the URL context tool uses a two-stageprocess designed to balance speed, cost, and access to the most currentinformation:

1. Indexed content retrieval: This is the first stage. When you provide aURL, the tool first attempts to fetch the content from Google'sextensive and highly optimized web index. This method provides fast access toa vast collection of crawled web pages.

2. Live fetch fallback: This is the second stage. If the content for a givenURL isn't available in the index (for example, if the page is very new andnot yet indexed), the tool automatically performs a live fetch. This fallbackmechanism can directly access the URL, and retrieve the latest version of thecontent in real-time.

Safety checks

The system performs a content moderation check on the URL to confirm that theURL meets safety standards. If the URL that you provided fails this check, youget aurl_retrieval_status ofURL_RETRIEVAL_STATUS_UNSAFE.

Token count

The input token count includes content retrieved from the URLs that you specifyin your prompt. From the model output, you can see the token count for yourprompt and tools usage in theusage_metadata object. The following is anexample output:

'usage_metadata':{'candidates_token_count':45,'prompt_token_count':27,'prompt_tokens_details':[{'modality': <MediaModality.TEXT:'TEXT'>,'token_count':27}],'thoughts_token_count':31,'tool_use_prompt_token_count':10309,'tool_use_prompt_tokens_details':[{'modality': <MediaModality.TEXT:'TEXT'>,'token_count':10309}],'total_token_count':10412}

Price per token depends on the model that you use. For more information, seeCost of building and deploying AI models inVertex AI.

Supported and unsupported content types

The URL context tool can extract content from URLs with the following contenttypes:

The URL context tool doesn't support the following content types:

• Paywalled content
• YouTube videos (For more information, seeVideounderstanding.)
• Google Workspace files like Google Docs or Google Sheets
• Video and audio files

Limitations

• The URL context tool consumes up to 20 URLs per request for analysis.
• For best results during experimental phase, use the tool on standard web pagesrather than multimedia content such as YouTube videos.