Fetch URL Content

Fetch and extract content from specific URLs in the Agent API.

Overview

The fetch_url tool fetches and extracts content from specific URLs during an Agent API request. Use it when your application already knows which page, article, document, or report the model should inspect.

Use fetch_url when you need full page content from known URLs. Use web_search when the model first needs to discover relevant pages.

Python

from perplexity import Perplexity

client = Perplexity()

response = client.responses.create(
    model="openai/gpt-5.5",
    input="Summarize the key claims in https://example.com/report.",
    tools=[
        {
            "type": "fetch_url"
        }
    ],
    instructions="Fetch the URL before summarizing it.",
)

print(response.output_text)

When to Use

Use fetch_url when…	Use web_search when…
You already have a URL	You need to discover relevant pages
You need fuller page content	You need snippets from multiple sources
You are summarizing a specific article or document	You are researching a broad topic
You want the model to inspect a known source	You want the model to find current sources

Combine web_search and fetch_url for multi-step research: search to find relevant pages, then fetch the most important URLs for fuller context.

Parameters

Parameter	Type	Required	Description
type	string	Yes	Must be "fetch_url".
max_urls	integer	No	Maximum number of URLs to fetch per tool call. The API schema allows values from 1 to 10.

Response Shape

When fetch_url runs, the response can include a fetch_url_results output item before the final assistant message. Each fetched content item includes the URL, page title, and extracted snippet.

{
  "output": [
    {
      "type": "fetch_url_results",
      "contents": [
        {
          "url": "https://example.com/report",
          "title": "Example Report",
          "snippet": "Extracted content from the fetched page."
        }
      ]
    },
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "The answer generated from the fetched URL content."
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 900,
    "output_tokens": 250,
    "total_tokens": 1150,
    "tool_calls_details": {
      "fetch_url": {
        "invocation": 1
      }
    }
  }
}

Error Handling

fetch_url is best-effort. When a URL cannot be fully fetched or extracted, the API can still return a completed Agent API response with the final assistant message explaining what content was available. Check the fetch_url_results.contents array to see which URLs produced extracted content.

Case	Response behavior
Paywalls and login walls	fetch_url does not bypass access controls. URLs that block access are typically omitted from fetch_url_results.contents, and the final assistant message explains which URLs could not be read.
Redirects	HTTP redirects are followed when the destination can be fetched. In the returned fetch_url_results item, the url field reflects the URL you requested, not the final redirect destination.
Non-HTML content	fetch_url extracts whatever text content the server returns at the URL. PDFs, binary downloads, and URLs that serve anti-bot challenge pages may return limited or unrelated extracted content.
Timeouts and unreachable URLs	URLs that time out or cannot be reached are typically omitted from fetch_url_results.contents. The final assistant message explains what was missed.

Limits / Quotas

Use max_urls to keep fetches bounded and predictable. Fewer URLs usually produce lower latency and leave more context for the model’s reasoning and final answer.

Limit	Value
Maximum URLs per tool call	max_urls can be set from 1 to 10.
Supported URL schemes	Use absolute http:// or https:// URLs. Other schemes (file:, data:, ftp:, browser-extension URLs) are not supported and produce no usable content.
Content size	Fetched content is extracted into snippets for model context and may be truncated for longer pages.

Pricing

fetch_url is billed at $0.50 per 1,000 invocations. Model token usage is billed separately according to Agent API token pricing.

Pricing follows the same pattern as other tool calls: pay for tool invocations plus model tokens. See Pricing.

Next Steps

Web Search

Search the web before fetching source content.

Finance Search

Retrieve structured financial and market data.

People Search

Search for professionals and employees.

API Reference

View complete endpoint documentation.