How can a Perplexity Agent read a known webpage directly?

Definition: A Perplexity Agent can use the fetch_url tool to fetch and extract content from a URL that the application already knows. The tool is for inspecting a supplied page, article, document or report during an Agent API request.

Key facts

• Perplexity describes fetch_url as a tool for full page content from known URLs, while web_search is for finding relevant pages. The fetch URL documentation gives that distinction.
• The tool configuration requires type set to "fetch_url"; max_urls is optional and accepts values from 1 to 10.
• A successful response can contain a fetch_url_results item before the final assistant message. Each content item has the requested URL, page title and extracted snippet.
• The supported schemes are absolute http:// and https:// URLs; file:, data:, ftp: and browser-extension URLs produce no usable content.
• Perplexity documents a price of $0.50 per 1,000 fetch_url invocations. Model token usage is billed separately.

When should you use fetch_url?

Use fetch_url when you already have the URL and need fuller content from a specific source. Perplexity's tool documentation contrasts this with web_search, which is used when the model needs to find relevant pages or gather snippets from multiple sources. The same documentation also describes a combined workflow: search can find pages, then fetch_url can retrieve the most important URLs for fuller context.

For a website owner, this is a supplied-URL retrieval path. Open-ended page finding belongs to web_search, while the application supplies a URL for the Agent to inspect through the input or surrounding workflow.

How do you enable the tool?

The Agent API request includes the tool object and can tell the model to fetch before summarizing. Perplexity's example uses this configuration:

{
  "tools": [
    {
      "type": "fetch_url"
    }
  ],
  "instructions": "Fetch the URL before summarizing it."
}

The official Agent API quickstart documents POST https://api.perplexity.ai/v1/agent as the endpoint and says that the SDK examples read the PERPLEXITY_API_KEY environment variable. The fetch URL example shows Python, TypeScript and cURL request forms. In Python, the SDK returns response.output_text for the final text; the fetch result itself appears as an output item before that final message.

If several known URLs are needed, set max_urls within the documented range of 1 to 10. Longer pages may be truncated because fetched content is extracted into snippets for model context.

What happens if a fetch fails?

fetch_url is best-effort. Perplexity states that an Agent response can still complete when a URL cannot be fully fetched or extracted. Successful items contain extracted page text, while failed items contain an explicit marker in the snippet field. A missing upstream result produces a marker containing no_result_returned.

The fetch URL error documentation lists several cases. Access controls are not bypassed: a paywall or login wall can produce a failure marker, and the origin may require credentials or a non-GET method. Redirects are followed when the destination can be fetched, but the returned url remains the URL requested. PDFs, binary downloads and anti-bot challenge pages can produce limited or unrelated extracted content. Unreachable URLs and timeouts return a failure marker with the available reason.

The documentation leaves the fetcher's user-agent and general robots policy unspecified; it only reports a robots-policy block as a possible failure marker. It presents fetch_url as a retrieval tool for the supplied URL.

Related terms

• Perplexity
• How does Perplexity's Search API differ from its Agent API?
• How do Perplexity Agent API source identifiers map to cited URLs?

FAQ

Does fetch_url search for a page?

No. Perplexity documents it for a URL that is already known. Use web_search when the model needs to find relevant pages.

Can fetch_url read a page behind a login?

Perplexity documents access controls as a failure case. A paywall or login wall can produce a marker explaining that credentials or a non-GET method may be required.

Does a redirect change the URL in the result?

The destination can be fetched after an HTTP redirect, but the returned url field reflects the URL requested rather than the final destination.

Sources

1. Perplexity, "Fetch URL Content", 25 September 2026
2. Perplexity, "Agent API", 2026

---

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