How many webpage URLs can the Gemini URL context tool read in one request?

Definition: Google's Gemini URL context tool can process up to 20 URLs in one request. The tool retrieves content from URLs supplied in the prompt, subject to limits on the size, accessibility and type of each URL's content.

Key facts

• Google's URL context documentation, updated 13 October 2026, sets the request limit at 20 URLs.
• The maximum content size retrieved from a single URL is 34MB.
• URLs must be publicly accessible on the web. Localhost addresses, private networks and tunneling services are unsupported.
• The model retrieves content from the URLs supplied in the prompt, rather than from nested links.
• Retrieved URL content counts as input tokens, and the usage object reports the tool-use input token count.

What does the 20 URL limit mean?

Google states that the URL context tool can process “up to 20 URLs per request.” The limit is therefore a per-request URL count. A request that compares several documents can place those URLs in the prompt while enabling the tool with this configuration:

"tools": [{"type": "url_context"}]

The same documentation presents URL context as a way to extract information from multiple URLs, compare reports, combine source URLs into a response, and analyze code or documentation. It describes the request limit separately from the maximum content size for a single URL, so the two constraints should be recorded as separate fields when a batch is checked.

Google documents the ceiling but does not describe the server response for a request that exceeds it. The safe documented boundary is 20 URLs in one request.

What else can prevent a URL from being read?

The 20 URL ceiling is only one of the documented limitations. The maximum retrieved content size for one URL is 34MB. The URL must also be publicly accessible. Google specifically excludes localhost addresses such as localhost and 127.0.0.1, private networks and tunneling services such as ngrok and pinggy.

The page's best practices say to provide direct URLs to the content to analyze. The model only retrieves the URLs supplied by the requester, so links nested inside those pages are outside the documented retrieval scope. Google also recommends the complete URL including its protocol, such as https://www.google.com rather than google.com.

Which content types does the tool support?

Google's documentation lists text content types including text/html, application/json, text/plain, text/xml, text/css, text/javascript, text/csv and text/rtf. It also lists PNG, JPEG, BMP and WebP images, plus PDF files. Paywalled content, YouTube videos, Google Workspace files such as Google Docs or spreadsheets, and video or audio files are listed as unsupported.

The content format is separate from the request count. A request may contain up to 20 URLs, but each URL still has to meet the documented accessibility, size and content-type conditions.

How can an application inspect retrieval?

The URL context page says that model text includes inline url_citation annotations. It also documents a url_context_result step with metadata for each URL retrieval attempt, including its status and retrieved URL.

Google's Generating content API reference describes the response's urlContextMetadata as metadata related to the URL context retrieval tool. Its urlMetadata field is a list of URL context records, and each record contains retrievedUrl and urlRetrievalStatus. The reference defines successful retrieval, an error, paywall failure and unsafe-content failure as possible retrieval statuses.

Related terms

• Gemini
• Does enabling Google Search make every Gemini API prompt run a search?
• Where are the search queries in a grounded Gemini API response?

FAQ

Can one request contain more than 20 webpage URLs?

Google's URL context documentation sets the maximum at 20 URLs per request. It does not document an over-limit error or fallback behavior.

Is 34MB the total size for the whole request?

Google defines 34MB as the maximum content size retrieved from a single URL. The request limit counts URLs, while this size limit applies to each URL's retrieved content.

Does URL context follow links found on a supplied page?

The model only retrieves content from the URLs supplied in the prompt. Google's best-practices section says content from nested links is not retrieved.

Sources

1. Google AI for Developers, "URL context", 13 October 2026
2. Google AI for Developers, "Generating content", 13 October 2026

---

Check how a page reads to answer engines. Open the GEO score analyzer