Skip to content
, ,

Perplexity Sonar API Guide (Nov 2026): Key, Pricing, Agent API Migration

11–16 minutes
Woman in a teal sweater in a dark studio holding a Sonar card, hook Sonar moved to Agent API

The Perplexity Sonar API changed a lot in 2026. Official support for Sonar Chat Completions ended on September 27, 2026, and Perplexity now points every new project to its Agent API.

If you searched for a Sonar tutorial, old guides will send you down the wrong path. This one covers what still works, what it costs today and how to move your code over.

Everything below was checked against docs.perplexity.ai and Perplexity’s own help center in November 2026.

TLDR

  • Sonar status: support ended Sept 27, 2026. Sync and streaming calls still work and are being reformulated as Agent API calls. Async Sonar calls are no longer supported.
  • Replacement: the Agent API at /v1/agent with an effort level. Sonar and Sonar Pro map to fast, Reasoning Pro to low, Deep Research to high.
  • Prices: perplexity/sonar is $0.25 in / $2.50 out per 1M tokens. Web search tool calls cost $2.50 per 1,000 (or $1.00 with Fast Search).
  • Search API: raw ranked results with no answer, $5 per 1,000 requests ($1 with Fast Search).
  • Key: create it at console.perplexity.ai, add credits, and set PERPLEXITY_API_KEY.

What happened to the Sonar API

Perplexity announced on its API forum in August 2026 that Sonar was moving to the Agent API. The Sonar endpoints retired on September 27, 2026, 45 days after that post.

The docs now show the same notice on every Sonar page. Here is what it means for your existing code:

  • Synchronous requests: still work. Perplexity is reformulating them as Agent API requests, rolling out gradually by model.
  • Streaming requests: also still work, with the same reformulation.
  • Asynchronous Sonar requests: not reformulated and no longer supported. Use Agent API background mode instead.
  • New projects: Perplexity recommends the Agent API for all of them.
Quick answer: Your old model: "sonar" calls will not break overnight, but they are on borrowed time. Plan a move to /v1/agent now, while you can test both side by side.

Why did Perplexity do this? Its migration page says the Agent API is “more performant and cost-effective for production workloads”. It also adds multi-step tool loops, a code sandbox, MCP support and models from several providers in one API.

If you only use Perplexity in the browser, none of this affects you. Our guide to using Perplexity covers the consumer app.

How to get a Perplexity API key

API access is a separate service from the Perplexity app. Perplexity’s help center says a subscription is not required to buy API credits or use the API.

  1. Sign in to the API Console. Go to console.perplexity.ai and sign in with your Perplexity account.
  2. Open your Project. A Project is your workspace. It holds billing, payment methods and API keys.
  3. Add a payment method. Open Billing in the sidebar (Admins only) and click Add payment method. Payment runs through Stripe, and adding a card does not charge it.
  4. Buy credits. Click Buy more credits. Billing is pay as you go.
  5. Turn on auto reload. Click Change preferences next to Auto reload and pick a threshold. The help center describes a top-up when the balance falls below $2.
  6. Create the key. Open API keys (console.perplexity.ai/project/keys) and generate a new key. Copy it once and store it safely.
  7. Set the environment variable. On macOS or Linux run export PERPLEXITY_API_KEY="your_key". On Windows PowerShell run setx PERPLEXITY_API_KEY "your_key".

Note: Some new accounts get a one-time $10 signup credit that expires 60 days after it is added. Purchased credits do not expire, and unused credits can be refunded within 14 days of purchase.

What about the old monthly API credit for Pro subscribers? The current docs and billing help page no longer mention it. Check the Billing page in your console to see whether any bonus shows up for your account.

If your balance hits zero, your keys are blocked until you add credits. That is why auto reload is worth turning on for anything in production.

Sonar models and their Agent API replacements

The four classic Sonar models were sonar, sonar-pro, sonar-reasoning-pro and sonar-deep-research. Perplexity now maps each one to an Agent API effort level.

Old Sonar model Best for (per docs) Replace with
sonar Single-fact lookups, definitions, quick summaries effort: "fast"
sonar-pro Everyday research with current information effort: "fast"
sonar-reasoning-pro Multi-hop browsing across many sources effort: "low"
sonar-deep-research Expert reasoning, exhaustive coverage effort: "high" (or xhigh)

What each effort level runs

Each effort level is a preset bundle of model, tools and limits. These are the November 2026 defaults:

Effort Model Max steps Max output tokens Tools
fast GPT-6 Luna 1 8,192 web_search
low GPT-6 Luna 5 32,768 web_search, fetch_url
medium GPT-6 Luna 15 128,000 web_search, fetch_url
high GPT-6 Sol 15 128,000 web_search, fetch_url
xhigh Claude Opus 5.5 100 512,000 web_search, finance_search, sandbox

All levels use Fast Search by default. You can override any field, for example model, max_steps or reasoning, while keeping the rest of the preset.

Perplexity says preset updates aim to stay in the same cost band, but the model underneath can change. To freeze behaviour, copy the preset values into your request and leave out effort.

How the replacements compare

Perplexity’s own migration benchmarks claim big gains. These are vendor numbers, not independent tests:

  • Sonar vs fast: BrowseComp accuracy 7.00% vs 26.67%, at about $0.0070 vs $0.0014 per request.
  • Sonar Deep Research vs high: 29.10% vs 78.00%, at about $0.611 vs $0.136 per request.
  • xhigh: 85.33% on BrowseComp, at about $0.78 per request.

Other Perplexity models worth knowing

  • perplexity/sonar: still listed as a model on the Agent API, described as “Perplexity’s grounded search model”.
  • Decisions API: pplx-decider-v1.3 (27B) and pplx-decider-flash-v1.3 (4B) return probabilities for yes/no, multiple-choice and rubric questions, not generated text.
  • Embeddings: the pplx-embed-v1 family, in 0.6B and 4B sizes.
  • Orchestrator API: a Chat Completions style gateway, still in private preview (request access by email).

Perplexity API pricing in November 2026

The Agent API bills per token at each model’s rate, plus tool fees. There is no flat per-request fee on top. Here are the main numbers from the official pricing pages:

Item Input / 1M Output / 1M Other
perplexity/sonar $0.25 $2.50 Cache read $0.0625
GPT-6 Luna (fast, low, medium) $0.10 $0.50 Up to 272k context; higher above it
GPT-6 Sol (high) $2.00 $10.00 Up to 272k context; higher above it
Claude Opus 5.5 (xhigh) $4.00 $20.00 Cache read $0.20
web_search (standard) $2.50 per 1,000 calls Fast Search: $1.00 per 1,000
image_search $2.50 per 1,000 successful calls Failed calls not billed
fetch_url $0.0005 per call
sandbox $0.03 per session (20-minute window) Plus $0.0025 per search inside it
Search API $5.00 per 1,000 requests Fast Search: $1.00 per 1,000
Decisions API $0.01 to $0.02 Free No request fee

Some models also offer a flex service tier at 0.5x and a priority tier at 2x. Only models that list those tiers support them.

Tip: Sonar set search depth with the named search_context_size option. On the Agent API you pay for the search context tokens actually used, so capping max_tokens on the web_search tool is your main cost lever.

Want to compare these numbers with OpenAI, Anthropic and Google? See our AI API pricing comparison.

Your first call with curl and Python

Install the official SDK with pip install perplexityai (Python) or npm install @perplexity-ai/perplexity_ai (TypeScript). Then try one of the calls below.

Agent API with curl

curl https://api.perplexity.ai/v1/agent \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"effort": "fast", "input": "What changed in the EU AI Act this month?"}'

Agent API with the Perplexity Python SDK

from perplexity import Perplexity

client = Perplexity()  # reads PERPLEXITY_API_KEY

response = client.responses.create(
    effort="fast",
    input="What changed in the EU AI Act this month?",
)
print(response.output_text)

Using the OpenAI SDK (OpenAI-compatible)

The Agent API follows the OpenAI Responses format. Point the OpenAI client at https://api.perplexity.ai/v1 and pass Perplexity-only fields through extra_body:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["PERPLEXITY_API_KEY"],
    base_url="https://api.perplexity.ai/v1",
)

response = client.responses.create(
    input="Summarise today's top AI news in 5 bullets.",
    extra_body={"effort": "low"},
)
print(response.output_text)

The path /v1/responses is accepted as an alias for /v1/agent. That is why the stock OpenAI SDK works with only a base URL change. New to that SDK? Our OpenAI API Python tutorial covers the basics.

The legacy Sonar call (for reference)

Old code that still runs looks like this. It now goes to /v1/sonar in the docs and uses the Chat Completions shape:

curl https://api.perplexity.ai/v1/sonar \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "sonar", "messages": [{"role": "user", "content": "..."}]}'

To migrate, rename messages to input, swap model for effort, and rename max_tokens to max_output_tokens. You then read output_text instead of choices[0].message.content.

Search filters: domains, recency, images and context size

On Sonar, search options sat at the top level of the request. On the Agent API they move inside the web_search tool’s filters object. The names mostly stay the same.

Sonar parameter Agent API equivalent
search_domain_filter Same name, inside web_search.filters
search_recency_filter Same name, inside web_search.filters
return_images Add the image_search tool
web_search_options.search_context_size No named sizes. Set max_tokens and max_tokens_per_page on web_search
reasoning_effort reasoning.effort
disable_search Leave out the web_search tool
return_videos, media_response Not supported

Filter rules you need to know

  • Domain filter: up to 20 domains or URLs. Use an allowlist or a denylist, never both. Put a minus sign in front to exclude, like "-reddit.com".
  • Recency filter: hour, day, week, month or year.
  • Date filters: search_after_date_filter, search_before_date_filter and the last_updated_* pair, all in MM/DD/YYYY format.
  • Location: user_location takes a two-letter country, plus optional region, city and coordinates.
  • Result count: max_results from 1 to 50 per call.
  • Search type: "fast" or "web". This needs Python SDK 0.43.6+ or TypeScript SDK 0.38.6+.

A filtered request in Python

response = client.responses.create(
    effort="fast",
    input="Latest guidance on heat pump subsidies",
    tools=[{
        "type": "web_search",
        "max_tokens": 6000,
        "max_tokens_per_page": 1200,
        "filters": {
            "search_domain_filter": ["energy.gov", "iea.org"],
            "search_recency_filter": "month",
        },
    }],
)

Tools merge per tool. Adding web_search with a filter changes only that tool, and the effort level’s other tools stay on.

Getting images back

Add {"type": "image_search"} to tools. It returns an image_search_results item with image_url, origin_url, width and height for each image.

You can set max_results from 1 to 30 (default 5), plus domain_filter, format_filter and safe_search. The model decides when to call the tool unless you set tool_choice.

How to handle citations

Sonar put inline [n] markers in its answers by default. The Agent API keeps citations, but the format depends on the effort level.

  • fast: numbered markers like [1].
  • low, medium, high: source-typed markers like [web:1].
  • Sources: returned in an output item with type: "search_results". Each marker number matches a result’s id.

Each result carries id, url, title, snippet, date, last_updated and source. The docs call id and url the source of truth for citations.

sources = {}
for item in response.output:
    if item.type == "search_results":
        for r in item.results:
            sources[r.id] = r.url

print(response.output_text)
for n, url in sorted(sources.items()):
    print(f"[{n}] {url}")

Warning: When you pick a model directly instead of an effort level, the model adds inline markers only if your prompt asks for them. Add a line like “cite sources as [n]” to your instructions.

The separate Search API

Need raw search results for your own model or RAG pipeline? The Search API at POST https://api.perplexity.ai/search returns ranked web results with no generated answer.

  • Queries: one string, or an array of up to 5 related queries.
  • Results: max_results from 1 to 20 (default 10).
  • Content budget: max_tokens (up to 1,000,000) and max_tokens_per_page.
  • Filters: country and search_domain_filter (up to 20 domains).
  • Price: $5 per 1,000 successful requests, or $1 with search_type: "fast". A 5-query request is billed once.
search = client.search.create(
    query=["perplexity agent api effort levels"],
    max_results=5,
    search_domain_filter=["docs.perplexity.ai"],
)
for r in search.results:
    print(r.title, r.url)

Failed, invalid and rate-limited Search requests are not billed. Price also does not change with your token budget.

Usage tiers and rate limits

Your tier depends on lifetime credit purchases, not your current balance. Tiers only go up.

Tier Total purchases Agent API QPS Tokens per minute
0 $0 1 5M
1 $50+ 3 6M
2 $250+ 8 8M
3 $500+ 17 10M
4 $1,000+ 33 13M
5 $5,000+ 33 16M

The Search API has a flat limit of 50 query units per second (burst 50) on every tier. A 5-query request uses 5 units.

Agent API limits use rolling windows shared across all keys in your organization. If the token budget runs out mid-request, the request pauses and resumes on its own, so do not resubmit it. For a cross-provider view, read our LLM API rate limits guide.

Troubleshooting: Common Problems and Fixes

401 Unauthorized

The request could not be authenticated. Check that the key is current and sent as Authorization: Bearer <key>. A revoked or mistyped key is the usual cause.

402 Payment Required

Your credits ran out and your keys are blocked. Buy credits on the Billing page and turn on auto reload so it does not happen again.

429 Too Many Requests

Read error.type in the response body:

  • request_rate_limit_exceeded: you hit the QPS cap. Wait the Retry-After time, normally 1 second.
  • token_rate_limit_exceeded: you hit TPM or TPH. Wait, then retry with exponential backoff and jitter.
  • overloaded: the upstream model is busy. Retry with backoff or use a fallback model.

500 and other 5xx errors

These are server-side and usually short. Retry with backoff, log the X-Request-ID header and check Perplexity’s status page. The SDKs already retry 408, 409, 429 and 5xx responses twice by default.

My async Sonar jobs stopped working

Async Sonar requests are not reformulated and no longer supported. Move them to background mode: send background: true to /v1/agent, then poll GET /v1/agent/{id} until the status is completed, failed, cancelled or incomplete.

The OpenAI SDK rejects my tools or effort

These are Perplexity extensions. In Python, pass effort and tools through extra_body. In TypeScript, cast the request object.

My answers have no citation markers

Direct-model requests only add markers when asked. Use an effort level, or tell the model to cite sources and map markers to search_results ids. Also set max_steps to at least 3 on direct-model runs, or the model gets only one step.

Frequently Asked Questions

Is the Perplexity Sonar API shut down?

Official support ended on September 27, 2026. Synchronous and streaming Sonar calls still work and are being reformulated as Agent API calls, but async Sonar calls are no longer supported.

What should I use instead of sonar-pro?

Perplexity maps both sonar and sonar-pro to the Agent API with effort: "fast". If you need more depth, try low or medium.

How much does the Perplexity API cost?

The Agent API bills per token at each model’s rate plus tool fees. For example, perplexity/sonar is $0.25 in and $2.50 out per 1M tokens, and each standard web search call is $0.0025.

Do I need Perplexity Pro to use the API?

No. Perplexity’s help center says a subscription is not required to buy API credits or use the API. The current docs do not mention a monthly API credit for Pro subscribers.

Is the Perplexity API compatible with OpenAI?

Yes. The Agent API follows the OpenAI Responses format at https://api.perplexity.ai/v1. Chat Completions format is offered through the Orchestrator API, which is in private preview.

What is the difference between the Agent API and the Search API?

The Agent API returns a written, cited answer and can run multi-step tool loops. The Search API returns only ranked results and snippets for your own model to use.

Can I still use search_context_size?

There is no named-size equivalent on the Agent API. Control search depth and cost with max_tokens and max_tokens_per_page on the web_search tool.

Want to see what Perplexity can do as a full agent in the app? Read our Perplexity Computer guide.

Sources

Free weekly email

Get new AI guides every week

One short weekly email with our newest local AI, ComfyUI and AI tool guides. No spam, no pop-ups, just the good stuff.

Free. Unsubscribe anytime in one click. We only use your email to send this newsletter. See our privacy policy.

Woman in a teal sweater in a dark studio holding a Sonar card, hook Sonar moved to Agent API