The URL context tool lets you provide Gemini with URLs as additional context for your prompt. The model retrieves content from the URLs and uses that content to inform and shape its response. This tool is useful for tasks such as the following: This page shows you how to use the URL context tool with the Gemini API in Vertex AI. The following models support URL context: You can use the URL context tool in two main ways, by itself or in conjunction
with Grounding with Google Search. You can provide specific URLs that you want the model to analyze directly in
your prompt: You can also enable both URL context and Grounding with Google Search
together. You can enter a prompt with or without URLs. The model may first
search for relevant information and then use the URL context tool to read the
content of the search results for a more in-depth understanding. This feature is experimental and available in API version Example prompts: For more details about Grounding with Google Search, see the
overview page. The model's response is based on the content it retrieves from the URLs. If the model retrieves content from URLs, the response includes
Supported models
Use URL context
URL context only
Summarize this document: YOUR_URLs
Extract the key features from the product description on this page: YOUR_URLs
Python
from google import genai
from google.genai.types import Tool, GenerateContentConfig, HttpOptions, UrlContext
client = 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 from YOUR_URL1 and YOUR_URL2",
config=GenerateContentConfig(
tools=[url_context_tool],
response_modalities=["TEXT"],
)
)
for each in response.candidates[0].content.parts:
print(each.text)
# get URLs retrieved for context
print(response.candidates[0].url_context_metadata)
Javascript
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True
import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({
vertexai: true,
project: process.env.GOOGLE_CLOUD_PROJECT,
location: process.env.GOOGLE_CLOUD_LOCATION,
apiVersion: 'v1',
});
async function main() {
const response = await ai.models.generateContent({
model: "gemini-2.5-flash",
contents: [
"Compare recipes from YOUR_URL1 and YOUR_URL2",
],
config: {
tools: [{urlContext: {}}],
},
});
console.log(response.text);
// To get URLs retrieved for context
console.log(response.candidates[0].urlContextMetadata)
}
await main();
REST
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-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": [
{
"parts": [
{"text": "Compare recipes from YOUR_URL1 and YOUR_URL2"}
]
}
],
"tools": [
{
"url_context": {}
}
]
}' > result.json
cat result.json
Grounding with Google Search with URL context
v1beta1
.Give me a three day event schedule based on YOUR_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 latest YOUR_SUBJECT.
Python
from google import genai
from google.genai.types import Tool, GenerateContentConfig, HttpOptions, UrlContext, GoogleSearch
client = 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 on YOUR_URL. Also let me know what needs to taken care of considering weather and commute.",
config=GenerateContentConfig(
tools=tools,
response_modalities=["TEXT"],
)
)
for each in response.candidates[0].content.parts:
print(each.text)
# get URLs retrieved for context
print(response.candidates[0].url_context_metadata)
Javascript
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True
import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({
vertexai: true,
project: process.env.GOOGLE_CLOUD_PROJECT,
location: process.env.GOOGLE_CLOUD_LOCATION,
apiVersion: 'v1beta1',
});
async function main() {
const response = await ai.models.generateContent({
model: "gemini-2.5-flash",
contents: [
"Give me a three day event schedule based on YOUR_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 context
console.log(response.candidates[0].urlContextMetadata)
}
await main();
REST
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-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": [
{
"parts": [
{"text": "Give me a three day event schedule based on YOUR_URL. Also let me know what needs to taken care of considering weather and commute."}
]
}
],
"tools": [
{
"url_context": {}
},
{
"google_search": {}
}
]
}' > result.json
cat result.json
Contextual response
url_context_metadata
. The following example shows a response that includes this metadata. For brevity, parts of the response are omitted.{
"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">
},
]
}
}
}
Limitations
URL context
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-08-25 UTC.