Sonar Chat Completions is retired
Since 27 September 2026, the models sonar, sonar-pro, sonar-reasoning-pro and sonar-deep-research are no longer served. Requests to the Sonar endpoint are reported to fail with HTTP 403 agent_api_migration_required.
Move to the Agent API at https://api.perplexity.ai/v1/agent. Your API key stays the same.
Timeline
What happened and when
- /v1/agent becomes canonicalThe Agent API endpoint moves to /v1/agent; /v1/responses stays as an alias.
- “Sonar Chat Completions is now Agent API”Perplexity’s changelog announces the move and publishes the migration guide.
- Retirement date announcedPerplexity confirms Sonar tiers retire on 27 September 2026.
- Sonar retiredSonar models stop working. The Agent API is the main way to build with Perplexity.
Legacy reference
How the Sonar API worked
Useful for reading and updating old code. Don’t build new projects on it.
| Sonar model | Was used for | Replace with preset |
|---|---|---|
| sonar | Fast, low-cost cited answers | fast |
| sonar-pro | Harder, multi-part questions | fast |
| sonar-reasoning-pro | Step-by-step reasoning | low |
| sonar-deep-research | Long research reports | high |
Legacy request and response shape
POST https://api.perplexity.ai/v1/sonar (legacy: /chat/completions)
{
"model": "sonar", // sonar | sonar-pro | sonar-reasoning-pro | sonar-deep-research
"messages": [{"role": "user", "content": "..."}],
"max_tokens": 500,
"stream": false,
"search_domain_filter": ["example.com"],
"search_recency_filter": "week",
"web_search_options": {"search_context_size": "medium"}
}
// Response: choices[0].message.content, citations[], search_results[], usageMigration
Migrate from Sonar to the Agent API in 5 steps
1Upgrade the SDK
The Agent API uses client.responses.create in the official SDK.
pip install --upgrade perplexityai
2Swap model for preset
Presets bundle a model, tools and settings. Use the mapping table below as a starting point.
3Rename parameters and move search filters
messages becomes input, max_tokens becomes max_output_tokens, and search filters move into a web_search tool inside tools.
4Update how you read responses
Read the answer from output_text. Sources arrive as output items with type: "search_results"; each [n] marker in the text matches a result’s id. For streaming, consume response.output_text.delta events.
5Test, compare and deploy
Run your real queries through the new presets, compare quality and cost, then switch every caller to /v1/agent, including background jobs and no-code tools.
Shortcut: Perplexity publishes a migration skill you can hand to an AI coding agent to update your code automatically. Review the changes before deploying.
Reference
Sonar to Agent API mapping tables
| Sonar parameter | Agent API | Notes | |
|---|---|---|---|
| model | → | preset | fast, low, medium or high |
| messages | → | input | A string or an array of messages |
| max_tokens | → | max_output_tokens | Direct rename |
| stream | → | stream | Unchanged; events are typed |
| search_domain_filter | → | tools[0].filters.search_domain_filter | |
| search_recency_filter | → | tools[0].filters.search_recency_filter | |
| search_context_size | → | tools[0].search_context_size | |
| user_location | → | tools[0].user_location | |
| num_search_results | → | tools[0].max_results |
| Sonar response | Agent API response | |
|---|---|---|
| choices[0].message.content | → | output_text |
| Inline [n] citations | → | Still in output_text; sources in output items with type "search_results", matched by id |
| image_url input | → | input_image content part |
| file_url / pdf_url input | → | input_file (base64 or HTTPS URL, 50 MiB total) |
| Removed (no equivalent) | What to do |
|---|---|
| search_language_filter | Ask for a language in the prompt, or use the Search API’s language filter |
| stream_mode | Use the typed streaming events |
| video_url, return_videos | Not supported |
| response_format type "regex" | Use JSON schema output instead |
| return_images, return_related_questions | Reported as no longer returned; remove UI that depends on them |
Code
Before and after
from perplexity import Perplexity
client = Perplexity()
completion = client.chat.completions.create(
model="sonar",
messages=[{"role": "user", "content": "Latest AI agent developments?"}],
)
print(completion.choices[0].message.content)from perplexity import Perplexity
client = Perplexity()
response = client.responses.create(
preset="fast",
input="Latest AI agent developments?",
)
print(response.output_text)const completion = await client.chat.completions.create({
model: 'sonar',
messages: [{ role: 'user', content: 'Renewable energy policy updates' }],
search_recency_filter: 'month',
search_domain_filter: ['iea.org', 'energy.gov']
});const response = await client.responses.create({
preset: 'fast',
input: 'Renewable energy policy updates',
tools: [{
type: 'web_search',
filters: {
search_recency_filter: 'month',
search_domain_filter: ['iea.org', 'energy.gov']
}
}],
});curl https://api.perplexity.ai/v1/sonar \
-H "Authorization: Bearer $PERPLEXITY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "sonar", "messages": [...], "stream": true}'curl https://api.perplexity.ai/v1/agent \
-H "Authorization: Bearer $PERPLEXITY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"preset": "fast", "input": "...", "stream": true}'Examples from Perplexity’s official migration guide.
Sonar → Agent API request converter
Paste a Sonar request body (JSON). You’ll get the Agent API equivalent, plus warnings for anything that no longer exists. It runs in your browser; nothing is sent anywhere.
Performance
Agent API vs Sonar: Perplexity’s benchmarks
Perplexity’s published results on three research benchmarks (higher is better). Company-reported figures.
Reported cost per query: Agent API fast about $0.006–$0.010; Agent API high about $0.36–$0.88; Sonar Deep Research about $0.57–$0.61. Source: Agent API vs Sonar benchmarks.
Sonar migration checklist
FAQ
Sonar retirement and migration questions
Is the Perplexity Sonar API shut down?
Yes. Perplexity retired Sonar Chat Completions (models sonar, sonar-pro, sonar-reasoning-pro and sonar-deep-research) on 27 September 2026. The Agent API at /v1/agent is the replacement.
What error does Sonar return now?
Developers report that Sonar requests now fail with HTTP 403 and the error code agent_api_migration_required. If you see it, follow this guide.
Which Agent API preset replaces my Sonar model?
Per Perplexity’s migration guide: sonar → fast, sonar-pro → fast, sonar-reasoning-pro → low, sonar-deep-research → high. Test with your own queries, because quality and cost differ.
Do I need a new API key?
No. Your existing Perplexity API key works with the Agent API.
Is the Search API affected?
The Search API (/search) is a separate product for raw web results and isn’t part of the Sonar Chat Completions retirement.
What features have no Agent API equivalent?
According to Perplexity’s guide: search_language_filter, stream_mode, video options and regex response formats. Gateways also report that images and related questions are no longer returned.
Is the Agent API more expensive than Sonar?
Not necessarily. In Perplexity’s benchmarks the fast preset cost about $0.006–$0.010 per query, and the high preset outperformed Sonar Deep Research on all three tests, often for less money. Check current preset pricing in the docs.
Is there an automatic migration tool?
Perplexity publishes a migration skill you can give to an AI coding agent to update your code automatically. Review its changes before deploying.
Official sources
- Perplexity: How to migrate from Sonar
- Perplexity: Agent API vs Sonar benchmarks
- Perplexity API changelog
- Perplexity migration skill for coding agents (GitHub)
More API guides
Next step
Move your first call to the Agent API
Change model to preset, messages to input, and read output_text. Most simple integrations migrate in under an hour.