How can URLs fetched per Perplexity tool call be bounded?

Definition: max_urls is an optional integer setting on Perplexity's Agent API fetch_url tool. It bounds the number of URLs that one tool call may fetch, with documented values from 1 to 10.

Key facts

• Perplexity describes fetch_url as the tool for extracting content from URLs that an application already knows, while web_search is used when the model must find pages. The Fetch URL Content documentation states this separation.
• The setting is optional and has the description "Maximum number of URLs to fetch per tool call". The same page documents the allowed range as 1 to 10.
• The Agent API schema maps the fetch_url tool type to the FetchUrlTool schema. Its max_urls property is an integer with a minimum of 1 and a maximum of 10, as shown in the Create Agent Response reference.
• A fetch response can contain a fetch_url_results item. Each fetched content item includes the requested URL, page title and extracted snippet.

How do you set the cap?

The cap is part of the tool object in the request's tools array. The Agent API reference describes that array as the place for tools available to the model, and its schema maps the fetch_url discriminator to FetchUrlTool.

{
  "tools": [
    {
      "type": "fetch_url",
      "max_urls": 10
    }
  ]
}

The value belongs alongside type, rather than in the input prompt. The schema makes type required and leaves max_urls optional. A value from 1 through 10 is within the documented schema range.

What does max_urls limit?

The setting limits the maximum number of URLs fetched by one fetch_url tool call. Perplexity recommends it for keeping fetches bounded and predictable, and says that fewer URLs usually reduce latency and leave more context for the model's reasoning and final answer, according to the tool documentation.

The published scope is one tool call. The page does not specify a separate cumulative URL limit for an entire Agent API request, so max_urls should be recorded as a per-call bound. The optional setting also has no documented default value on that page.

What happens when a requested URL cannot be fetched?

The limit counts URLs presented to the fetch tool. It does not turn every request into successful page content. Perplexity describes fetch_url as best-effort: successful result items contain extracted text, while failed items contain a marker in the snippet for the requested URL.

The same documentation lists HTTP client errors, robots-policy blocks and rate limiting as possible reasons for a failure marker. It also says redirects are followed when the destination can be fetched, while the returned url field keeps the URL requested by the caller. Fetched content may be truncated for longer pages, and the documented supported schemes are absolute http:// and https:// URLs.

Related terms

• Perplexity
• Perplexity Sonar
• How does Perplexity's Search API differ from its Agent API?

FAQ

What is the largest documented value for max_urls?

The largest documented value is 10 URLs per fetch_url tool call.

What happens if max_urls is omitted?

The field is optional in the tool schema. The fetched documentation does not publish a default value, so an integration should not infer one from the schema alone.

Does max_urls control web search results?

It controls the fetch_url tool. Perplexity documents web search as a separate tool for discovering relevant pages, while fetch_url reads URLs that are already known.

Sources

1. Perplexity, "Fetch URL Content", undated
2. Perplexity, "Create Agent Response", undated

---

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