You can use the URL context tool to provide Gemini with URLs as additional context for your prompt. The model can then retrieve content from the URLs and use 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 job description or creating test questions)
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:
Use URL context
You can use the URL context tool in two main ways, by itself or in conjunction with Grounding with Google Search .
URL context only
You can provide specific URLs that you want the model to analyze directly in your prompt:
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": [
{
"role": "user",
"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
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 v1beta1
.
Example prompts:
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": [
{
"role": "user",
"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
For more details about Grounding with Google Search, see the overview page.
Contextual response
The model's response will be based on
the content it retrieved from the URLs. If the model retrieved content from URLs,
the response will include url_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"
:
< UrlRe
tr
ievalS
tatus
.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"
:
< UrlRe
tr
ievalS
tatus
.URL_RETRIEVAL_STATUS_SUCCESS
:
"URL_RETRIEVAL_STATUS_SUCCESS"
>
},
]
}
}
]
}
Limitations
- The tool will consume up to 20 URLs per request for analysis.
- The tool does not fetch live versions of web pages, so there may be some issues with freshness or potentially out-of-date information.
- For best results during experimental phase, use the tool on standard web pages rather than multimedia content such as YouTube videos.
