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.
- 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/agentwith aneffortlevel. Sonar and Sonar Pro map tofast, Reasoning Pro tolow, Deep Research tohigh. - Prices:
perplexity/sonaris $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.
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.
- Sign in to the API Console. Go to console.perplexity.ai and sign in with your Perplexity account.
- Open your Project. A Project is your workspace. It holds billing, payment methods and API keys.
- 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.
- Buy credits. Click Buy more credits. Billing is pay as you go.
- 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.
- Create the key. Open API keys (console.perplexity.ai/project/keys) and generate a new key. Copy it once and store it safely.
- Set the environment variable. On macOS or Linux run
export PERPLEXITY_API_KEY="your_key". On Windows PowerShell runsetx 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) andpplx-decider-flash-v1.3(4B) return probabilities for yes/no, multiple-choice and rubric questions, not generated text. - Embeddings: the
pplx-embed-v1family, 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,monthoryear. - Date filters:
search_after_date_filter,search_before_date_filterand thelast_updated_*pair, all in MM/DD/YYYY format. - Location:
user_locationtakes a two-lettercountry, plus optional region, city and coordinates. - Result count:
max_resultsfrom 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’sid.
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_resultsfrom 1 to 20 (default 10). - Content budget:
max_tokens(up to 1,000,000) andmax_tokens_per_page. - Filters:
countryandsearch_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 theRetry-Aftertime, 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
- Perplexity Docs: Migrate from Sonar to the Agent API
- Perplexity Docs: How to migrate from Sonar
- Perplexity Docs: Agent API vs Sonar benchmarks
- Perplexity Docs: Pricing
- Perplexity Docs: Agent API Models
- Perplexity Docs: Effort levels
- Perplexity Docs: Web Search tool
- Perplexity Docs: Search API quickstart
- Perplexity Docs: Rate Limits and Usage Tiers
- Perplexity Docs: OpenAI Compatibility
- Perplexity Help Center: API Payment and billing
- Perplexity API Forum: Sonar is moving to the Agent API



