# Perplexity Agent API ultra effort: what the top level costs

URL: https://infro.io/blog/perplexity-agent-api-ultra-effort-what-the-top-level-costs
Author: INFRO Editorial (https://infro.io/blog/editorial)
Publisher: INFRO
Published: 2026-11-09
Last modified: 2026-11-09
Last reviewed: 2026-11-09 (next review due 2026-12-09)
Topic: Cost and FinOps
Format: Analysis

> Perplexity does not publish a per-run price for ultra. It runs anthropic/claude-opus-5-5 with long runs, so its cost is the token and tool-call volume you measure on your own prompts [^pplx-changelog]. Compare levels by cost per successful task, and allow ultra only on routes where each extra success is worth more than the extra spend.

Key takeaways:
- Perplexity's changelog says ultra runs on anthropic/claude-opus-5-5 and can run for a long time, but it gives no per-run price, so the number has to come from your own measurements.
- A run bills model tokens at the model's rate plus per-invocation tool fees, so ultra's cost is mostly how many steps, searches and output tokens it uses on your prompts.
- Compare levels by cost per successful task and by marginal cost per extra success; ultra only pays when a failed run costs you more than that marginal figure.
- Cap ultra with max_steps, token budgets on web_search, background mode with a client-side cancel deadline, and an application-side route policy, because the effort name alone sets no spend limit.
- Pin the returned effort version for any route where cost stability matters, since a dynamic level can change its configuration.

## What ultra is, and what the docs leave open

Perplexity's changelog for November 2026 adds `effort="ultra"` (version `ultra@2026-11-05.0`). It is meant for broad research and data-gathering tasks where coverage matters most. The entry says runs can take a long time, so it suggests background mode. It also says ultra runs on `anthropic/claude-opus-5-5` and has no frozen configuration; you call it by name or pin the returned version.[1]

The effort page describes ultra as the level for when you "want the most complete result and can accept long runs." Each effort level bundles a model, search config, reasoning steps, system prompt and tools.[2]

What I could not confirm: ultra's step limit, its search type and its output-token budget. Those sit in the "current effort level values" section of the effort page, which came back truncated. I also found no per-run price for any level. Perplexity bills tokens and tools, so the price of ultra is a measurement you make, not a number you look up. The rest of this post is how to make it.

Two older facts matter for anyone who tried ultra early. In October the undocumented `ultra` name was removed and returned an error, and `ultra-preview` was introduced as the level for the same use. `max_steps` was raised to accept values up to 500.[1] If any code still sends `ultra-preview`, check what it resolves to before you assume it matches `ultra`.

## What the lower levels cap, and what that implies

The changelog gives hard limits for the levels below ultra. They show how much headroom each step up adds.[1]

| Level | Model | Limits stated in the changelog |
| --- | --- | --- |
| high | openai/gpt-6.1-terra | Max steps 40; at most 40 tool calls per run |
| xhigh | anthropic/claude-opus-5-5, fallback openai/gpt-6.1-sol | Max steps 300; compaction from 150,000 tokens; output budget up to 512,000 tokens |
| ultra | anthropic/claude-opus-5-5 | Not confirmed in the pages I read |

Table: Stated limits per effort level, from Perplexity's changelog.

Two readings follow. First, xhigh and ultra share a model, so the difference between them is configuration, not a pricier model per token. Second, xhigh can already run up to 300 steps with context compaction, so a long ultra run is plausibly many more tool calls and more re-read context than your xhigh baseline. Treat that as a hypothesis to measure, not a fact. Perplexity also says updates to an effort level target the same cost and latency band, which is a reason to pin a version if you need a stable bill.[2]

## What a run bills

Agent API token rates are Perplexity's published per-model rates, which the models page says may differ from provider list prices. For `anthropic/claude-opus-5-5` the page lists $4.00 per million input tokens, $20.00 per million output tokens and $0.20 per million cache-read tokens.[3] Requests that use an `anthropic/*` model must include `max_output_tokens`, or the API returns HTTP 400.[3] Reasoning tokens bill at the output rate on models that report them.

Tools bill separately per invocation: `web_search` is $0.0025 standard or $0.001 with Fast Search, `fetch_url` is $0.0005, and a `sandbox` session is $0.03 for a 20-minute billing window.[4] The changelog says xhigh uses Fast Search.[1] I do not know which search type ultra uses.

The shape of the bill is then:

```text
run cost = (uncached input × input rate)
         + (cached input × cache-read rate)
         + (output + reasoning tokens × output rate)
         + Σ tool invocations × tool fee
```

Long runs change the mix. Each step re-reads the growing context, so input tokens, not output, tend to dominate unless caching works. Dynamic effort levels set a stable `prompt_cache_key` for the shared system prompt and tool definitions, which helps reuse across requests.[2] Whether it is enough inside a 150-step run is something your cached-token counts will show.

## Measure tokens, tool calls and latency per level

Run the same prompt set at every level, in background mode for the long ones, and record what each run did. Background mode returns a response id immediately; you poll `GET /v1/agent/{id}` until the status is `completed`, `failed`, `cancelled` or `incomplete`, and you can cancel with `POST /v1/agent/{id}/cancel`.[5] Completed responses carry `usage` with token counts and, when present, `usage.cost.total_cost`.[4] The effort that ran comes back in an `effort` field.[2]

```python
import os, time, collections, json, requests
from perplexity import Perplexity

client = Perplexity()
H = {"Authorization": f"Bearer {os.environ['PERPLEXITY_API_KEY']}"}
TERMINAL = {"completed", "failed", "cancelled", "incomplete"}

def run_once(prompt: str, effort: str, deadline_s: int) -> dict:
    t0 = time.monotonic()
    r = client.responses.create(effort=effort, input=prompt, background=True)
    while r.status not in TERMINAL:
        if time.monotonic() - t0 > deadline_s:
            requests.post(f"https://api.perplexity.ai/v1/agent/{r.id}/cancel", headers=H)
            deadline_s = 10**9  # cancel once; keep polling for the final state
        time.sleep(5)
        r = client.responses.retrieve(r.id)
    u = r.usage
    kinds = collections.Counter(getattr(i, "type", "?") for i in (r.output or []))
    return {
        "effort_ran": r.effort,            # e.g. ultra@2026-11-05.0
        "status": r.status,
        "seconds": round(time.monotonic() - t0, 1),
        "input_tokens": u.input_tokens,
        "cached_tokens": u.input_tokens_details.cached_tokens,
        "output_tokens": u.output_tokens,
        "reasoning_tokens": u.output_tokens_details.reasoning_tokens,
        "reported_cost": getattr(getattr(u, "cost", None), "total_cost", None),
        "item_kinds": dict(kinds),         # print once, then pick the tool-call types
    }

for effort in ["high", "xhigh", "ultra"]:
    for prompt in open("prompts.txt").read().splitlines():
        print(json.dumps({"effort": effort, "prompt": prompt[:60],
                          **run_once(prompt, effort, deadline_s=1800)}))
```

Three cautions. The item type names for searches and fetches are not something I confirmed, so print `item_kinds` on a first run and count the ones that are tool calls. I also did not confirm whether `reported_cost` includes tool fees, so recompute a cost from tokens and tool counts at the rates above and compare it to the reported figure on the first batch. And repeat each prompt at least three times per level: a run that takes many steps is variable, so report the median and p90, not the mean.

## Cost per successful task across levels

Per-run cost is the wrong comparison, because a level that costs more per run may need fewer reruns or fewer human fixes. [INFRO's cost-per-successful-task method](https://infro.io/blog/cost-per-successful-task) puts every attempt in the numerator and only successes in the denominator.[6] The general form is cost per run divided by success rate. For research tasks, define success with a check you already run, for example the share of a known list of required entities the answer covers, with a fixed threshold.

> **Example: Illustrative: six levels on a 40-prompt coverage task**
> These figures are invented to show the arithmetic. They are not Perplexity measurements. Success means the answer covered at least 90% of a hand-built checklist. A failed run is finished by a person at an assumed $6 of handling time.
> 
> The xhigh and ultra costs are built from the Opus 5.5 rates above. xhigh: 0.3M uncached input at $4.00 is $1.20, 0.5M cached at $0.20 is $0.10, 40k output at $20.00 is $0.80, 60 Fast Searches are $0.06, 30 fetches are $0.015 and one sandbox session is $0.03, giving about $2.21. ultra: 0.5M uncached input is $2.00, 1.0M cached is $0.20, 80k output is $1.60, 120 searches at the standard fee are $0.30 and 60 fetches are $0.03, giving $4.13.
> 
> | Level | Median tool calls | Median latency | Cost per run | Success rate | Cost per successful task | Cost per task with $6 human fix |
> | --- | --- | --- | --- | --- | --- | --- |
> | fast | 1 | 4 s | $0.004 | 5% | $0.08 | $5.70 |
> | low | 4 | 20 s | $0.02 | 20% | $0.10 | $4.82 |
> | medium | 12 | 60 s | $0.08 | 45% | $0.18 | $3.38 |
> | high | 30 | 3 min | $0.35 | 70% | $0.50 | $2.15 |
> | xhigh | 90 | 12 min | $2.21 | 80% | $2.76 | $3.41 |
> | ultra | 180 | 35 min | $4.13 | 85% | $4.86 | $5.03 |
> 
> Table: Illustrative cost per successful task by effort level.
> 
> Marginal cost per extra success, step to step: fast to low $0.11, low to medium $0.24, medium to high $1.08, high to xhigh $18.60, xhigh to ultra $38.40.

Read the table by the marginal column. Going from xhigh to ultra adds $1.92 per run for five more points of success, so each extra success costs $38.40. That number is also the break-even: ultra beats xhigh on this task only if a failed run costs you more than $38.40 to finish or lose. At $6 per failure, `high` is the cheapest way to complete the task. Your numbers will differ, but the method is the same: measure the three inputs, then divide the cost difference by the success difference.

## Cap ultra before you allow it

The effort name sets no spend limit. These are the levers I can document, in order of how directly they bound a run:

- **Step budget.** `max_steps` is an override you can pass beside the effort, and tools merge per tool rather than replacing the set.[2] The changelog says `max_steps` accepts values up to 500.[1] Set it below your measured p90 steps and see how success moves.
- **Search size.** `web_search` accepts `max_tokens` and `max_tokens_per_page`, which tune search depth under an effort level.[2] The changelog shows the lower levels already raised these from 2,000 to 4,000.[1]
- **Tool-call limit.** The response object carries a `max_tool_calls` field.[7] High is described as limited to 40 tool calls.[1] Whether you can set it as a request cap on ultra is something to test, not assume.
- **Wall-clock deadline.** Background mode lets your client cancel a run. Cancellation is asynchronous, so a run may bill a little past your deadline.[5]
- **Token rate limits.** If your organization hits a token limit mid-run, the response stays `in_progress` with a paused object until it resumes, so a slow ultra run is not a failed one. Do not resubmit it.[5]

I did not find a documented way to read spend-so-far on an in-flight run, so a watchdog can bound time and steps but not dollars until the run completes. That is why a per-route ceiling on how many ultra runs can start matters more than a per-run dollar cap.

## Gate ultra per route

Keep the policy in your application, keyed by the workload, not by a user-supplied parameter. A route gets a ceiling effort. Ultra is allowed only on listed routes, only as an escalation after a cheaper level failed the coverage check, and only under a daily run count.

```python
CEILING = {
    "support-lookup": "low",
    "market-brief": "high",
    "diligence-sweep": "xhigh",
}
ULTRA_ROUTES = {"diligence-sweep"}
ULTRA_PER_DAY = 25
LADDER = ["fast", "low", "medium", "high", "xhigh", "ultra"]

def next_effort(route: str, last: str | None, covered: bool, ultra_today: int) -> str | None:
    if last is not None and covered:
        return None                                # done, no escalation
    start = CEILING.get(route, "low")
    if last is None:
        return start
    nxt = LADDER[LADDER.index(last) + 1] if last != "ultra" else None
    if nxt == "ultra" and (route not in ULTRA_ROUTES or ultra_today >= ULTRA_PER_DAY):
        return None                                # hand to a person instead
    return nxt
```

Escalation has a cost of its own: the failed lower-level run is already billed, so tag both attempts with the same run id and count them together. If you escalate from xhigh to ultra on 30% of tasks, your effective cost per task is the xhigh cost plus 30% of the ultra cost, not the ultra cost alone. Pin versions on gated routes, for example `effort="ultra@2026-11-05.0"`, so a Perplexity update does not move the cost band under a policy you tuned.[2]

## Recording the cost per run

The numerator for the table above is the sum of every call's cost in a run. If your calls go through a gateway that records cost per request, INFRO's [unit economics](https://infro.io/docs/api/unit-economics) endpoint returns requests, runs, estimated cost, and median and p90 cost per run grouped by `metadata.workflow` and `metadata.trace_id`, with the unpriced share beside each row.[8] Your own success record is the denominator. Budgets on a project or key add a hard cap above the route policy. Check that your Perplexity usage is covered by a connection before relying on either; the response-side `usage` fields shown earlier work regardless. For the model-id side of Perplexity's changes, see [the dropped model ids post](https://infro.io/blog/perplexity-agent-api-dropped-model-ids-what-breaks-what-to-check).

## Before you turn ultra on

- [ ] Run 30 or more real prompts at high, xhigh and ultra, three repeats each, and keep the median and p90 of cost, tool calls and seconds.
- [ ] Recompute cost from tokens and tool counts and compare it to `usage.cost.total_cost` to see whether tool fees are included.
- [ ] Define success with a check your system already runs, and fix it before comparing.
- [ ] Compute the marginal cost per extra success from xhigh to ultra and compare it to what a failed run costs you.
- [ ] Set `max_steps`, search token limits and a cancel deadline, and confirm the cap holds on a deliberately broad prompt.
- [ ] Put ultra behind an allowlisted route with a daily count, and escalate only after a cheaper level failed.
- [ ] Pin the version you measured, and re-run the sample when Perplexity ships a new one.

## Questions

### Can I pin ultra to a frozen configuration?

Not as a frozen configuration. The changelog says ultra has no frozen configuration and can be called by name or pinned to the returned version, which is ultra@2026-11-05.0 today [1]. Read the effort field on a response and send it back as effort to keep that version.

### Does service_tier flex lower the cost of an ultra run?

Probably not. Flex and priority apply only to models whose Service tiers column lists them, and anthropic/claude-opus-5-5 shows none there [3]. Check response.service_tier on a real run.

## Sources

1. Changelog — Perplexity. https://docs.perplexity.ai/docs/resources/changelog (accessed 2026-11-09)
2. Effort — Perplexity. https://docs.perplexity.ai/docs/agent-api/effort (accessed 2026-11-09)
3. Agent API Models — Perplexity. https://docs.perplexity.ai/docs/agent-api/models (accessed 2026-11-09)
4. Pricing — Perplexity. https://docs.perplexity.ai/docs/getting-started/pricing (accessed 2026-11-09)
5. Background Mode — Perplexity. https://docs.perplexity.ai/docs/agent-api/background-mode (accessed 2026-11-09)
6. Cost per successful task: the LLM metric that matters — INFRO. https://infro.io/blog/cost-per-successful-task (accessed 2026-11-09)
7. Agent API quickstart — Perplexity. https://docs.perplexity.ai/docs/agent-api/quickstart (accessed 2026-11-09)
8. Unit economics API reference — INFRO. https://infro.io/docs/api/unit-economics (accessed 2026-11-09)
