How can a failed Gemini URL retrieval be identified?

Definition: A failed Gemini URL retrieval is identified in the URL Context response metadata by a failure status attached to the requested URL. Google documents error, paywall and unsafe as failure statuses in the Interactions API, and documents the corresponding Generate Content enum values.

Key facts

• Google's URL Context documentation says the url_context_result step contains metadata for each URL retrieval attempt, including its status and retrieved URL.
• The Generate Content API reference defines UrlContextMetadata as a list of URL context records and UrlMetadata as the retrieved URL plus its retrieval status.
• In the Interactions API, success, error, paywall and unsafe are the documented URL retrieval status values.
• paywall identifies content behind a paywall, unsafe identifies content that failed the URL safety check, and error identifies a retrieval failure due to an error.
• The URL Context documentation says the tool first tries an internal index cache and falls back to a live fetch when the URL is absent from that index.

Which response fields should you inspect?

For the current Interactions API, inspect the step whose type is url_context_result. Its result items contain status and url; the API reference describes url as the URL that was fetched. A failed item therefore has a requested or fetched URL beside a value such as error, paywall or unsafe.

For the Generate Content API, inspect url_context_metadata.url_metadata[]. Each item has retrieved_url and url_retrieval_status. The legacy URL Context example shows two items in that array, each with a retrieved URL and URL_RETRIEVAL_STATUS_SUCCESS.

{
  "url_context_metadata": {
    "url_metadata": [
      {
        "retrieved_url": "https://www.example.com/page",
        "url_retrieval_status": "URL_RETRIEVAL_STATUS_PAYWALL"
      }
    ]
  }
}

What does each failure status mean?

The Generate Content API reference uses uppercase enum names. URL_RETRIEVAL_STATUS_ERROR means the retrieval failed due to an error. URL_RETRIEVAL_STATUS_PAYWALL means the content is behind a paywall. URL_RETRIEVAL_STATUS_UNSAFE means the content is unsafe. The same reference lists URL_RETRIEVAL_STATUS_SUCCESS for a successful retrieval and says URL_RETRIEVAL_STATUS_UNSPECIFIED is the default value and is unused.

Google's URL Context documentation adds that the system performs a content moderation check on URLs. When a URL fails that check, the url_context_result step shows a status of unsafe. The documented status fields identify the retrieval outcome, while the API reference gives no further subdivision for the generic error value.

How should a website audit record the result?

Record the status together with the URL field from the same result item. This keeps a paywall response separate from a safety rejection and from the generic error category. The URL Context documentation describes the result metadata as mainly useful for debugging, and it separately describes inline url_citation annotations that link answer text segments to source URLs.

The tool's retrieval path can affect how an investigation is interpreted. Google documents a two-step process: an internal index cache is tried first, followed by a live fetch when the URL is unavailable in the index, such as for a very new page. A status is therefore evidence about that URL Context retrieval attempt, not a general indexing report for the website.

Related terms

• Gemini
• How many webpage URLs can the Gemini URL context tool read in one request?
• Which webpage and document formats can Gemini URL context read?
• HTTP status codes

FAQ

Which value shows that a URL was behind a paywall?

Use paywall in the Interactions API or URL_RETRIEVAL_STATUS_PAYWALL in the Generate Content response. Google defines that value as a retrieval failure because the content is behind a paywall.

Which value shows a safety rejection?

Use unsafe or URL_RETRIEVAL_STATUS_UNSAFE. Google's URL Context documentation connects this result to the URL content moderation check.

Does a successful retrieval create a citation?

The response can contain inline url_citation annotations, and the URL Context documentation explains that they link answer text segments to source URLs. Retrieval status and citation annotations are separate response metadata described by the documentation.

Sources

1. Google AI for Developers, "URL context", 13 October 2026
2. Google AI for Developers, "Generating content", 13 October 2026
3. Google AI for Developers, "URL context | Gemini Generate Content API (Legacy)", 13 October 2026
4. Google AI for Developers, "Gemini Interactions API", 15 October 2026

---

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