Guide

Sonar Chat Completions Retires 27 September. Agent API Is Not a Rename.

By Istar editors
At a glance

Perplexity is retiring Sonar endpoints on 27 September 2026. For small tools: what changes in path, request/response, billing, failure mode, and when to leave instead of migrating.

If you wired Perplexity Sonar into a client report, a Slack bot, or a one-person research gadget, the 13 August 2026 forum post is a calendar problem, not a quality-benchmark problem. Perplexity announced that Sonar endpoints retire on 27 September 2026 and named the Agent API as the replacement. It keeps grounded web search and adds multi-step research, code execution, built-in tools, and more than one model family behind one interface. Perplexity’s forum claim is that on BrowseComp and WideSearch, Agent API more than doubles the best Sonar score. That is vendor benchmarking. Your breaking changes are the path, the JSON, the search switch, and the meter.[1]

Core sources were accessed on 28 August 2026: the API Platform forum thread, Migrate from Sonar to the Agent API, How to migrate from Sonar, and Pricing, plus the linked official pages for presets and conversation state. Anything the current documentation does not specify remains marked confirm.

What actually moves

The how-to is explicit. Point requests at /v1/agent. Switch the SDK call from chat.completions.create() to responses.create(). The same guide names the old HTTP endpoint as https://api.perplexity.ai/v1/sonar. Inventory that exact path as well as SDK calls.[2]

Request shape is not a rename:

  • Sonar takes a messages array and returns choices (answer in choices[0].message.content), plus top-level citations / search_results in the example payload on the overview page.
  • Agent API takes input and returns a typed output array — one item per step. Answer text is response.output_text. Sources come back as an output item with type: "search_results", each result carrying an id that maps to inline [n] markers.[3]

For a single user string you can pass input="..." as a plain string. System prompts become top-level instructions or typed { "type": "message", "role": "...", "content": "..." } items. For multi-turn state, set previous_response_id to the ID of a completed prior response instead of resending the transcript.[2]

Streaming is a parser rewrite. Sonar chunks expose choices[0].delta.content. Agent API streams typed SSE events. Consume response.output_text.delta for answer text; tool calls and reasoning arrive as response.output_item.* and response.reasoning.*, not as text deltas. Async Sonar maps to background: true plus poll-by-id. stream still exists. temperature and top_p are accepted; whether they do anything depends on the selected model. Current documentation says GPT-5, o1, and o3 families—including gpt-5.6-sol—silently ignore them.[2]

Search is no longer implicit

This is the silent break for “I just wanted citations.”

On Sonar, grounded web search was always on. On Agent API you add web_search to tools. If you do not, the model answers from its own knowledge. Sonar’s top-level search_recency_filter and search_domain_filter move onto that tool’s filters. Inline [n] citations were default on Sonar. Agent presets fast / low / medium / high already include inline citations, but the marker style is not identical: fast uses numbered [1]; low / medium / high use source-typed markers such as [web:1]. If you pin a model and tools yourself instead of a preset and require inline citations, the how-to says to add citation instructions in instructions. Any downstream regex that assumes [n] only will mis-parse low and above.[2]

Suggested starting map from the how-to and overview (performance claims are Perplexity’s, not independent):

Sonar Chat Completions Agent API
sonar preset fast
sonar-pro preset low
sonar-reasoning-pro preset medium
sonar-deep-research preset high

xhigh is the extra tier for “state-of-the-art deep research.” You can also skip presets and pass model="perplexity/sonar" with tools. Presets are dynamic rather than version-pinned. On 28 August 2026, the presets page listed fast, low, and medium on openai/gpt-5.6-luna, while high and xhigh used openai/gpt-5.6-sol; Perplexity may change those underlying models. Agent API otherwise exposes OpenAI, Anthropic, Google, xAI, Z.AI, Moonshot AI, NVIDIA, plus Perplexity’s Sonar, and claims Open Responses compatibility. Built-in tools on the overview: web search, URL fetch, sandbox, MCP, finance search, people search. Do not assume every Sonar parameter has a 1:1 field. The how-to says some rows are “closest pattern,” and missing behavior should go to api@perplexity.ai.[3]

Billing is not the same meter

The 13 August official forum announcement is the dated source for the 27 September 2026 retirement. The current pricing page no longer repeats that date, while the migration overview says Chat Completions remains supported without giving a deadline. For a contract SLA, confirm the cutover with your account team.[4]

Sonar Chat Completions (until sunset) — total cost per query = tokens + a request fee that varies by search context size (the fee applies to Sonar, Sonar Pro, and Sonar Reasoning Pro). Token card on the current pricing page:

  • Sonar: $1 / $1 per 1M input / output; request fee $5 / $8 / $12 per 1,000 requests (low / medium / high context)
  • Sonar Pro: $3 / $15; request fee $6 / $10 / $14
  • Sonar Reasoning Pro: $2 / $8; request fee $6 / $10 / $14
  • Sonar Deep Research: $2 / $8, plus citation tokens $2 / 1M, search queries $5 / 1K, reasoning tokens $3 / 1M (no request-fee row in that table)

Pro Search on Sonar Pro is a separate Sonar-era surcharge selected through web_search_options.search_type (pro or auto) and requires stream: true. The migration guide maps pro to preset low or explicit max_steps; it says there is no direct Agent API equivalent for the auto classifier. Search context size is not the model context window.[4]

Agent API — model tokens at listed provider rates, “no markup” is Perplexity’s wording. Tools are extra, per invocation, on top of tokens:

  • web_search: $0.0025
  • fetch_url: $0.0005
  • people_search / finance_search: $0.005
  • sandbox: $0.03 per session (20-minute billing window, not a runtime cap); sandbox SDK searches bill like web_search

A representative low preset run on the pricing page (2,000 in + 1,000 out, 1 web search + 1 fetch) is $0.007. That is an example, not a cap. Completed responses may expose usage.cost.total_cost. Agent API is usage-metered by tokens and tool calls; Sonar was tokens plus a per-request search-context fee. Same product name (sonar) on Agent API is not the old bill. Under the 28 August 2026 configuration, model="perplexity/sonar" and preset fast use different model-and-tool configurations, so do not assume equal cost; dynamic presets can change. Re-run your actual prompts; do not copy last month’s unit economics. Overview copy says Agent API is “more performant and cost-effective,” and that high is “often at a lower per-request cost than Sonar Deep Research.” That is a claim, not a rate-card identity.[4]

Search API remains a separate product: $5 per 1,000 successful POST /search requests, no token charge. Invalid, rate-limited, and upstream failures are not billed; a successful empty result is. If your tool only needed URLs and snippets, Agent API is the wrong migration.[4]

If you do nothing

The 13 August forum post said Sonar endpoints were fully available at that time and would retire on 27 September 2026. Current official pages do not publish the post-sunset HTTP status, error body, or any grace window (confirm). For planning, treat a hard failure as the conservative possibility rather than assuming a grace period. Dual-run before the date. Do not discover the error shape in production on a Monday morning.[1]

When to leave instead of migrating

Migrate if you still want Perplexity-grounded answers inside a small app and can rewrite the client: new path, input/output_text, explicit web_search, new citation markers, new cost meters.

Switch the design if any of these is true:

  • You only needed ranked web results. Stay on Search API, or another SERP. Do not buy an agent loop for a search box.
  • Your code is an OpenAI Chat Completions adapter (messages / choices / delta.content) and you will not own an SSE event switch. Agent API is Open Responses-shaped, not a Chat Completions alias.
  • Your product promise is “always search, always [n] citations, always a citations array.” That was Sonar default behavior. Agent API makes search a tool and changes marker flavor by preset.
  • Tool-invocation variance is unacceptable. Current medium and high presets expose web_search and fetch_url; xhigh exposes web_search, finance_search, and sandbox. Actual invocation counts can vary by run. Sonar’s request fee was coarse but predictable per call.
  • You were on Sonar because it was cheap at high volume ($5–$12 / 1K request fees plus cheap Sonar tokens). Re-estimate; do not assume the forum’s “cost-effective” line holds for your traffic mix.

Three-line checklist

  1. Inventory every /v1/sonar, chat.completions, and sonar* call; retarget /v1/agent responses.create with input and output_text (and SSE response.output_text.delta if you stream) before 27 September 2026.
  2. Turn search back on with tools: [{ "type": "web_search", "filters": { ... } }] and remap sonar→fast, sonar-pro→low, sonar-reasoning-pro→medium, sonar-deep-research→high — or pin model="perplexity/sonar".
  3. Re-price on Agent token + tool meters (web_search $0.0025, etc.) using usage.cost.total_cost where present; dual-run until sunset — if you only needed snippets, move to Search API instead of Agent.