How is a Perplexity Agent result budget divided across reformulated queries?

Definition: In Perplexity's Agent API, max_results is the upper bound for results collected by one web_search tool call. If that call uses several reformulated queries, Perplexity documents a per-query allocation of roughly ceil(max_results / number_of_queries).

Key facts

• As of 17 October 2026, Perplexity's Agent web search documentation describes web_search as a tool used during an Agent API request.
• max_results is the total budget for one web_search call, so reformulated queries share it rather than each receiving the full value.
• The documented planning rule is roughly ceil(max_results / number_of_queries) for each reformulated query.
• Omitting max_results selects the default budget documented by Perplexity.
• The Agent API reference defines max_results as an upper bound per call from 1 through 50; values outside that range are rejected with HTTP 400.
• The backend may return fewer results than requested, even when the requested value is within the documented range.

What does the budget count?

The budget counts search results collected by a single web_search tool call. The request-level tool object can set it explicitly:

{
  "type": "web_search",
  "max_results": 20
}

Perplexity's web search documentation presents this object as the configuration for a call. Its note distinguishes result breadth from extracted content depth: max_results controls the number of results, while max_tokens_per_page controls content extracted from each result. The API reference separately describes max_tokens as the maximum total token count for search context.

How is a shared value allocated?

The web search documentation says that several reformulated queries divide the call's total budget per query and gives the approximate ceiling formula. For a request with n reformulated queries, the documented planning estimate is ceil(max_results / n) results per query. The word "roughly" matters because the page gives an allocation rule, while the API reference describes max_results as an upper bound on the collected results for the call.

The split applies inside a tool call. A later web_search call has its own max_results value and its own allocation. The documentation does not specify how a remainder is assigned when an exact division is impossible, or whether query order affects that assignment.

What can the request and response show?

max_results belongs to the web_search tool object, alongside controls such as search_type, filters, max_tokens, and max_tokens_per_page. The API reference defines search_type values of web and fast, while the web search documentation says that an omitted search_type inherits the preset's value when one is configured and otherwise uses web.

For streamed responses, the API reference lists a response.reasoning.search_queries event containing the queries being executed and a response.reasoning.search_results event containing returned results. These events expose the query and result stages for a particular response. They do not change the per-call budget rule.

Related terms

• How does Perplexity's Search API differ from its Agent API?
• How do I send multiple queries to Perplexity's Search API?
• Does max_results require Perplexity to return that many pages?
• How do Perplexity Agent API source identifiers map to cited URLs?

FAQ

Does max_results apply separately to every reformulated query?

No. It is the total for one web_search call, and the documented approximate per-query allocation is ceil(max_results / number_of_queries).

Can the response contain fewer results than the requested value?

Yes. The web search documentation says that the backend may return fewer results than requested within the accepted range.

What happens when you omit max_results?

The default budget applies. The documentation does not give that default in the section describing the split.

How can you inspect the reformulated queries?

With a streamed response, inspect the response.reasoning.search_queries event, which the API reference defines as containing the queries being executed.

Sources

1. Perplexity, "Web Search", Accessed 2026-10-17
2. Perplexity, "Create Agent Response", Accessed 2026-10-17

---

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