Perplexity logo with its teal geometric mark and the perplexity wordmark, the company behind the Agent API

Perplexity Agent API: Power-User Guide to Effort Levels, Tool Approvals and Pricing

by

Last updated: October 31, 2026

The Perplexity Agent API changed in October 2026. The preset parameter is now called effort, a new ultra-preview level targets long research runs, high moved to a newer model, high and xhigh got bigger step budgets, and MCP and connector tool calls can now require your approval before they run.

This guide is based on Perplexity’s API changelog, its effort documentation and its MCP tool guide. If you use Perplexity’s probability endpoint, see our separate Perplexity Decisions API guide.

Contents

What is new in the Perplexity Agent API

The Agent API is Perplexity’s hosted agent endpoint, POST https://api.perplexity.ai/v1/agent. It runs models from several providers with built-in web search and other tools and returns a cited answer. Perplexity’s October 2026 changelog lists these changes:

  • preset renamed to effort. This is a naming change only. Models, prompts, tools, limits and pricing stay the same, preset is still accepted as a deprecated alias, and responses return both fields. Python SDK 0.46.0 and TypeScript SDK 0.41.0 add the parameter.
  • New ultra-preview level for broad research and data gathering. The undocumented ultra name was removed and now returns an error, and the wide-research alias now selects xhigh.
  • Bigger budgets. high moved to openai/gpt-6.1-terra with 40 steps instead of 15, xhigh rose from 100 to 300 steps, and max_steps now accepts up to 500, up from 100.
  • More search context. low, medium and high raised web_search max_tokens and max_tokens_per_page from 2,000 to 4,000.
  • Tool approvals for mcp and connector tools through require_approval, in Python SDK 0.43.8 and TypeScript SDK 0.38.8.
  • Cheaper search under presets. low through xhigh now use Fast Search, which drops web_search from $2.50 to $1.00 per 1,000 calls and is about 800 ms faster.

Effort levels compared

The table summarizes the current values in the effort documentation and the versions named in the changelog.

Effort Current version Model Max steps Max output tokens Best for
fast fast@2026-10-16.0 gpt-6-luna, falls back to gpt-5.6-luna 1 8,192 Single-fact lookups and quick summaries
low low@2026-10-24.0 gpt-6-luna 5 128,000 Everyday research with light tool use
medium medium@2026-10-22.1 gpt-6-luna 15 128,000 Multi-hop browsing across many sources
high high@2026-10-28.0 gpt-6.1-terra 40 (max 40 tool calls) 128,000 Deep, source-heavy research without code
xhigh xhigh@2026-10-29.0 claude-opus-5-5, falls back to gpt-6.1-sol 300 512,000 Open-ended agent work, sandbox code, long tool loops
ultra-preview Not listed Not published (no frozen configuration) Not published Not published Broad research where coverage matters most

low through xhigh now remind the model of its remaining step budget, and xhigh starts context compaction at 150,000 tokens and no longer sets a system prompt.

How to use and pin an effort level

The effort documentation describes three ways to run a level. Use this sequence for a production integration:

  1. Upgrade the SDK to Python 0.46.0 or TypeScript 0.41.0 or later so effort is a typed parameter.
  2. Replace preset with effort in each request, for example effort="low". Do not send ultra, which now returns an error.
  3. Read the effort field in the response. It names the version that ran, such as fast@2026-10-16.0.
  4. Pin where stability matters by sending that versioned value back as effort. An unknown name or version returns HTTP 400.
  5. Override only what you need. model, max_steps or max_output_tokens replace defaults; tools merge per tool.
  6. Run ultra-preview in background mode for long jobs, then poll or stream the result as described in the background mode guide.

A request cannot set both effort and profile. Note that the top-level effort is separate from reasoning.effort, which controls the chosen model’s reasoning.

How to require tool approvals

By default, the Agent API runs MCP tool calls without approval. The approvals section of the MCP guide explains the new control:

  • "never", null or omitted runs every call without approval.
  • "always" requires approval for every call.
  • A filter object with always and never rules can match by exact tool_names, by read_only, or both. Calls that match neither rule require approval.

For example, {"never": {"read_only": true}} runs read-only tools freely and asks about everything else. Perplexity warns that read_only comes from the server’s own annotations and does not guarantee a tool has no side effects.

When a call needs approval, the response contains an mcp_approval_request item and the tool does not run. Send a new request with previous_response_id and an mcp_approval_response item that sets approval_request_id and approve. To build an “Always allow” button, add the approved tool to the never filter in later requests, and match on the server URL and tool name rather than the label alone.

Our Claude Code guide and Cursor Agent SDK guide cover similar permission prompts in coding agents.

Pricing

According to Perplexity’s pricing page, the Agent API bills per token at each model’s rate plus tool fees. Effort levels have no separate fee, and a completed response can report its cost in usage.cost.total_cost. Current tool fees:

  • web_search with Fast Search: $1.00 per 1,000 calls; standard web search: $2.50 per 1,000.
  • fetch_url: $0.0005 per call.
  • image_search: $2.50 per 1,000 successful calls; people_search and finance_search: $5 per 1,000.
  • sandbox: $0.03 per session, plus $0.0025 per SDK search query inside it.

Model rates are on the Agent API models page. For example, openai/gpt-6-luna is listed at $0.10 input and $0.50 output per million tokens up to 272k input tokens, and anthropic/claude-opus-5-5 at $4.00 input and $20.00 output. The flex tier halves and priority doubles token rates on models that support them. See our GPT-6.1 Terra guide and Claude Duet guide, which covers an app built on Claude Opus 5.5.

Comparison with the previous setup

Compared with September 2026, the biggest practical change is depth. A high run can now take 40 steps instead of 15 and an xhigh run 300 instead of 100, so complex research finishes in one request more often. Longer runs can use more tokens and tool calls, although Perplexity says level updates target the same cost and latency band.

Approvals help teams that connect write-capable MCP servers: previously every MCP call ran automatically.

Limitations

  • ultra-preview is a preview with no published frozen values, and runs can take a long time.
  • Dynamic levels change over time; pin a version if you need reproducible output.
  • Frozen configurations cannot reproduce settings outside the request schema, such as step reminders and context compaction, so update any copied values.
  • Each approval adds a request round trip.

Frequently asked questions

What is the effort parameter in the Perplexity Agent API?

Effort selects a Perplexity-managed configuration that bundles a model, search settings, step budget, system prompt and tools. The values are fast, low, medium, high, xhigh and ultra-preview. It replaced the older preset parameter in October 2026, and preset still works as a deprecated alias.

Is effort the same as reasoning.effort?

No. The top-level effort parameter picks the Agent API configuration, while reasoning.effort controls how much the selected model reasons. Perplexity documents them as separate settings, so you can set both in one request.

What is the ultra-preview effort level?

Ultra-preview is a new effort level for broad research and data-gathering tasks where coverage matters most. Runs can take a long time, it has no frozen configuration, and you call it by name with effort set to ultra-preview, optionally in background mode.

How do I require approval before an MCP tool runs?

Set require_approval on the mcp or connector tool. A call that needs approval returns an mcp_approval_request item and does not run. You then send an mcp_approval_response with approve set to true or false, plus previous_response_id from the first response.

How much does the Perplexity Agent API cost?

You pay per token at each model’s published rate plus tool fees. Perplexity’s pricing page lists Fast Search web_search at $1.00 per 1,000 calls, standard web search at $2.50 per 1,000, fetch_url at $0.0005 per call and sandbox at $0.03 per session.

How do I stop an effort level from changing under me?

Pin a version. Each response returns an effort field such as fast@2026-10-16.0, and sending that value back as effort keeps that exact configuration after Perplexity updates the level. You can also copy the current values into a frozen configuration.

Sources

Image: Perplexity AI logo, public domain, 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 guide: DeepSeek Search API and Fetch API guide: setup, pricing and limits.



Related answers

Leave a Comment