Perplexity AI wordmark logo on a white background, used as the featured image for the FreeAnswers Perplexity Agent ultra guide

Perplexity Agent Ultra: Power-User Guide to GA Effort and Decisions Web Grounding

by

Last updated: November 6, 2026

Perplexity Agent ultra is now generally available as effort ultra@2026-11-05.0 for broad research on Claude Opus 5.5. The same November 2026 changelog also adds Decisions API web_grounding, URL fetching with max_staleness, and a $0.001 fee per search or successful URL fetch.

This guide covers the new GA effort and the Decisions updates using Perplexity’s API changelog, effort docs, Decisions quickstart and pricing page. For the October effort and MCP approval changes, see our earlier Perplexity Agent API effort guide. For the original Decisions models, see the Perplexity Decisions API guide.

Contents

What is new in November 2026

Perplexity’s November 2026 changelog lists three related platform updates:

  • Agent API ultra effort. New GA level ultra (ultra@2026-11-05.0) for broad research and data gathering where coverage matters most. Runs can take a long time and may use background mode. It runs on anthropic/claude-opus-5-5 and has no frozen configuration.
  • Decisions web grounding. Set mode to "web_grounding" on POST /v1/decisions to run one Fast Search per question (up to 100) before the model answers. Evidence appears in search_results.
  • URL fetching and freshness. Pass a page URL as state with web grounding to fetch its text first. Use max_staleness (seconds since last crawl) to force a fresh crawl, and read the page from fetched_results.

October 2026 temporarily removed the undocumented ultra name in favor of ultra-preview. November restores ultra as a versioned GA effort. Our October Agent API guide still covers renaming, MCP approvals and the other October level updates.

How Perplexity Agent ultra works

Perplexity’s effort documentation lists fast, low, medium, high, xhigh and ultra. Each level bundles a model, search config, reasoning steps, system prompt and tools. The top-level effort parameter is separate from reasoning.effort.

Feature ultra xhigh
Best for Broad research where coverage matters most Open-ended agent work with sandbox and long tool loops
Model anthropic/claude-opus-5-5 anthropic/claude-opus-5-5, fallback openai/gpt-6.1-sol
Frozen configuration None; call by name Published (max_steps 300, max_output_tokens 512,000)
Version example ultra@2026-11-05.0 xhigh@2026-10-29.0
Background mode Recommended for long runs Available

Because some ultra settings sit outside the documented request schema, you cannot freeze its full configuration by copying public fields. Call it by name, or pin the version returned in the response effort field. For long jobs, use background mode so the run continues after the client disconnects.

How to run ultra and pin the version

  1. Send effort="ultra" on POST https://api.perplexity.ai/v1/agent with a research prompt that needs wide coverage.
  2. Prefer background mode for long runs: submit with background enabled, then poll or stream by response id.
  3. Read the response effort field, which returns the version that ran (for example ultra@2026-11-05.0).
  4. Pin that version in later requests when you need a stable configuration after Perplexity updates the dynamic level.
  5. Override only what you need, such as tools or max_steps; do not expect a full frozen copy of ultra’s private settings.
curl https://api.perplexity.ai/v1/agent \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"effort":"ultra","input":"Build a data-backed market map for AI coding agents: gather recent launches, compare pricing and benchmarks, and score capability coverage."}'

Decisions API web grounding and URL fetch

The Decisions API still returns probabilities for noul, choice and score questions. November 2026 adds grounding so those probabilities can use live web evidence. Per the web grounding section of the quickstart:

  • Set mode: "web_grounding". The Python library and TypeScript SDK do not yet expose a typed mode field, so send it in the request body (extra_body in Python, or a spread in TypeScript).
  • The API runs one Fast Search per question, up to 100 questions, and merges results into state.
  • Pass a single http://, https:// or www. URL as state to fetch the page first; the response includes fetched_results (up to 40,000 characters of page text in snippet).
  • Set max_staleness to a non-negative integer of seconds to cap stored page age; omit it to accept any stored copy.
curl -X POST https://api.perplexity.ai/v1/decisions \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"pplx-decider-latest","mode":"web_grounding","max_staleness":86400,"state":"https://en.wikipedia.org/wiki/James_Webb_Space_Telescope","questions":{"launched":{"type":"noul","instructions":"Does the page say Webb launched in December 2021?"}}}'

For an adjacent search-and-fetch workflow from another vendor, see our DeepSeek Search API and Fetch API guide.

Pricing for ultra and web grounding

Figures below come from Perplexity’s pricing page and Agent API models page.

  • ultra model tokens: anthropic/claude-opus-5-5 is listed at $4.00 per million input tokens, $0.20 cached input and $20.00 output, plus Agent tool fees (for example Fast Search web_search at $0.001 per invocation).
  • Decisions tokens: $0.02 per million input on pplx-decider-v1.2 and $0.01 on pplx-decider-flash-v1.2; output tokens remain free.
  • Web grounding extras: each search costs $0.001 ($1 per 1,000), and each successful URL fetch costs $0.001. Failed fetches are not billed. Fetched text and search evidence also count as input tokens.

A request with one successful fetch and three successful searches therefore adds $0.004 before token charges.

How ultra compares with xhigh and other research tools

Within Perplexity, choose xhigh for the published sandbox configuration with a 300-step budget, and ultra when coverage matters more than a frozen public config. Both currently use Claude Opus 5.5. Unlike a single reasoning knob in other vendors’ APIs, Perplexity bundles model, tools and search into an effort level. Decisions web grounding is different again: it returns probabilities over web evidence rather than a research essay, so you can gather with ultra and gate claims with web_grounding.

Related FreeAnswers coverage includes the GPT-6 Cyber guide for another November 2026 model release and Claude Haiku 5.5 guide for a lower-cost Anthropic option also listed on the Agent API.

Limitations

  • ultra has no frozen configuration; pin a version for reproducibility.
  • Long runs can cost more in tokens and tool calls than lower efforts.
  • Decisions mode and search_results are not typed in the SDKs yet; send and read them on the raw body.
  • Web grounding allows at most 100 questions; searches time out after about 1 second each and 3 seconds total.
  • A URL mixed with other text in state is searched as text, not fetched.

Frequently asked questions

What is Perplexity Agent ultra?

Perplexity Agent ultra is a November 2026 Agent API effort level for broad research and data-gathering where coverage matters most. The changelog names the released version ultra@2026-11-05.0. It runs on anthropic/claude-opus-5-5, has no frozen configuration, and you call it with effort set to ultra.

How is ultra different from ultra-preview and xhigh?

In October 2026 Perplexity shipped ultra-preview and removed the undocumented ultra name. In November 2026 ultra returned as a generally available effort with version ultra@2026-11-05.0. Like xhigh it uses Claude Opus 5.5, but ultra has no published frozen configuration and is aimed at the most complete long research runs.

How do I call the ultra effort level?

Send effort set to ultra on POST https://api.perplexity.ai/v1/agent, or pin the response version such as ultra@2026-11-05.0. Because runs can take a long time, Perplexity also recommends background mode. The top-level effort parameter is separate from reasoning.effort.

What is Decisions API web grounding?

Set mode to web_grounding on POST /v1/decisions so the API runs one Fast Search per question, up to 100 questions, and adds the results to state before the model answers. The response lists evidence in search_results. Requests without mode are unchanged.

How do URL fetching and max_staleness work?

With mode set to web_grounding, pass a single page URL as state to fetch its text before searching. The response returns the page in fetched_results. Set max_staleness to the maximum page age in seconds since its last crawl; an older stored copy triggers a fresh crawl. Omitting it uses a stored copy with no age limit.

How much do ultra and web grounding cost?

Ultra bills Agent API model tokens for Claude Opus 5.5 at $4.00 per million input and $20.00 per million output, plus tool fees. Decisions web grounding adds $0.001 per search and $0.001 per successful URL fetch, on top of Decisions input-token rates of $0.02 or $0.01 per million.

Sources

Image: Perplexity AI logo, public domain (PD textlogo), via Wikimedia Commons. Placed on a white background and resized. Perplexity is a trademark of Perplexity AI, Inc. FreeAnswers is not affiliated with or endorsed by Perplexity.



Related answers

Leave a Comment