Perplexity's Sonar to Agent API Migration: Web Search Is Now Opt-In

This page digests Perplexity's own documentation for moving from Sonar Chat Completions to the Agent API. Perplexity wrote the docs. 99Visibility's research pass fetched them and recorded what they say, with the evidence base verified on 2026-08-22. No hands-on test was run for this page.

The docs matter to anyone who measures Perplexity answers through code. That includes AI visibility tools, internal brand-monitoring scripts and agencies running their own prompt sets. If you are asking whether the change touched your numbers, start with whether the Sonar retirement affected AI visibility tracking.

The core fact is simple. On the Agent API, web search is something the caller turns on. It is not the default behaviour.

The evidence base compared two things.

1. The migration docs. These describe how to move from Sonar to the Agent API, and they state that web_search is opt-in on the new endpoint.
2. The retirement date. Sonar Chat Completions was scheduled to retire on 2026-09-27. That date came from a Perplexity forum announcement. It was not in Perplexity's migration documentation when the evidence base checked it.

The research also logged what the Agent API returns when search runs. Each result in search_results carries an id, url, title, snippet, date, last_updated and source. Perplexity cites whole sources by integer index, which Perplexity citations explained covers in detail.

One caveat on method: these are documentation claims. They describe how Perplexity says the API behaves, not a measured failure rate.

Web search is opt-in

The Agent API does not search unless the request enables it. A request without that setting still returns a fluent answer. It just comes from the model's training data instead of live pages.

The failure is silent

The evidence base puts it plainly: unmigrated Sonar code silently returns ungrounded answers. Nothing errors. The output looks like a normal answer, so a dashboard keeps filling with data.

The date lived outside the docs

The 2026-09-27 retirement was announced on a forum, not in the migration docs. Teams that only watched the documentation had no dated warning there.

Post-migration studies inherit the risk

The evidence base flags that any study run after the migration may be measuring an LLM with no web access. That applies to vendor reports, academic work and your own exports. This pattern is not unique to Perplexity. Retrieval is per-query and discretionary on every platform, as whether AI APIs search the web by default explains.

The migration docs tell you how the API behaves. They do not tell you several things people tend to assume.

• They do not show how many tracking setups broke. Nobody has published a count of unmigrated or misconfigured integrations.
• They do not describe the consumer app. As of a 2026-09-21 snapshot, secondary reports say Perplexity's free app uses an auto-router called "Best" and paid plans offer a menu of eight models. No single API model is the app. See API answers vs consumer app answers.
• They do not say a retrieved page shaped the answer. Citation is not the same as use. Mechanistic research (arXiv:2606.28358) repaired over 90% of missed citations by adjusting model internals without changing the sources.
• They do not tell you what the ungrounded answer knows. A retrieval-off answer reflects a training cutoff, and nothing a publisher does this quarter reaches it.

So a grounded Perplexity API answer is one measurement of one surface. It is useful, and it is not the whole picture.

If you track Perplexity answers through the API, run these checks before trusting any data from late September 2026 onward.

1. Confirm the request enables web_search. Read the code or the vendor's documentation. Do not assume a migrated endpoint searches by default.
2. Check every stored response for search_results. A grounded answer returns URLs. An empty or missing list means retrieval was off for that answer. How to tell whether an AI answer used live web search covers the signals per platform.
3. Relabel suspect data as retrieval-off. Results from unmigrated setups, or any run without search results, belong in a separate bucket. Do not blend them into a grounded trend line.
4. Break your trend at the retirement date. A jump or drop around 2026-09-27 may be a configuration change, not a change in how Perplexity sees your brand.
5. Log retrieved sources, not just citations. Keeping the full search_results list lets you audit later. The playbook for logging retrieved vs cited sources shows the fields to keep.
6. Decide deliberately whether you want search on. Both states are worth measuring, but they answer different questions. Pick one per test and record it.

If you buy tracking from a vendor, ask one direct question: does every Perplexity call enable web search, and can you show the retrieved URLs for each answer?

When did Perplexity retire Sonar Chat Completions? The scheduled retirement date was 2026-09-27. That date came from a Perplexity forum announcement. When the evidence base checked Perplexity's migration documentation, the date was not stated there. Teams that relied only on the docs for deprecation notices would not have seen it, which is why it is worth checking any integration that was built against Sonar before that date.

What does an ungrounded Perplexity API answer look like? It looks like a normal answer. The model writes fluent text from its training data, with no live retrieval behind it. The practical difference is in the response payload: a grounded answer includes a `search_results` list with URLs, titles and snippets, while an ungrounded one does not. Check the payload, not the prose, because the prose gives no reliable sign.

Does the Agent API change how Perplexity cites sources? Perplexity cites whole sources by integer index, and each search result carries an id, url, title, snippet, date, last_updated and source field. That differs from Claude's API, which cites short text spans. Because the units differ, Perplexity citation counts cannot be averaged directly with counts from other engines without stating what was counted.

Should AI visibility tracking run with web search on or off? It depends on the question. Search-on answers show what the engine retrieves and cites now. Search-off answers show what the model says from training data alone. Both are legitimate, but mixing them in one score hides which is which. Pick a state for each test, record it, and see [whether to test with search on or off](/questions/ai-visibility-testing-search-on-off) for the trade-offs.

Do other AI APIs have the same opt-in problem? Retrieval is per-query and discretionary across platforms, but defaults differ. Anthropic's API defaults web search on at the organisation level, though that does not describe Claude.ai consumer behaviour. ChatGPT search in the app is model-discretionary. The safe habit is the same everywhere: confirm the setting in code and check each response for retrieved sources.