Building on Perplexity?

Perplexity Sonar not returning what you expected? We sort it out.

Perplexity's search-grounded models look magical in a demo and start showing seams the moment you put them behind real traffic: citations that point at the wrong paragraph, a Sonar Pro call that cost ten times what you budgeted, or a response schema that quietly changed between model versions. We work the integration back into something predictable.

  • Since 2015Fixing technology
  • FreeEstimates
  • US teamReal engineers

perplexity-sonar.log

still flaky

What it is

Perplexity API at a glance

The Perplexity API, marketed as Sonar, exposes the same search-grounded language models that run the public Perplexity.ai product. Each completion runs a live web search behind the scenes, grounds the answer in retrieved sources, and returns an inline list of citation URLs alongside the generated text.

It ships Sonar, Sonar Pro, and reasoning variants. Pricing is a mix of per-million input and output tokens plus a per-request search fee, so costs behave differently from pure chat APIs. The REST surface is compatible with the OpenAI chat completions shape, which makes it easy to wire into an existing stack, as long as you remember the citation array and the fact that responses are not purely deterministic.

Type
Search-grounded chat completion API
First released
2023 public beta
License
Commercial API, usage based billing
Maintained by
Perplexity AI, Inc.
Typically used for
Research assistants, citation-backed Q&A, live-knowledge chatbots, agent search tools

The honest version

Perplexity API pros and cons

No technology is all upside. This is where Perplexity API earns its place and where it tends to cause trouble.

Where Perplexity API is strong

  • Answers come with sources attachedEvery completion returns a citations array with the pages the model actually consulted, which is far easier to audit than a vanilla LLM response that may have hallucinated the fact.
  • OpenAI-shaped request bodyThe chat completions schema is deliberately close to OpenAI's, so swapping in Sonar is usually a base URL change plus a small bit of citation handling.
  • Live web knowledge without plumbing a search stackYou do not need to wire Bing, Brave or SerpAPI yourself; the retrieval loop runs server side and the model is already tuned to cite what it found.
  • Streaming works the way engineers expectSSE streaming returns tokens and citation chunks in order, so building a typing-style UI on top of it is not much work.
  • Reasonable latency for a search-grounded callA Sonar request typically returns in a handful of seconds, which is acceptable for an interactive assistant that would otherwise need a chain of tool calls.

Where Perplexity API bites

  • Citations can be confidently wrongThe returned URL sometimes supports a different sentence than the one the model wrote, or points at a listicle that merely restates the claim. You still need to spot-check if the output matters.
  • Sonar Pro costs add up quietlyPer-request search fees land on top of token pricing, and a chat UI that fires a request per message can run several times the cost of a comparable non-grounded model within a month.
  • Rate limits are stricter than the OpenAI ceilingBurst traffic to Sonar Pro meets 429 responses sooner than teams migrating from GPT-4o expect, and lifting the cap requires a support conversation rather than a dashboard toggle.
  • Model names churnOlder identifiers like pplx-7b-online have already been retired once, and anything hard coded in a worker will break on the next sunset unless you track their changelog.
  • Deterministic output is not really on offerEven with temperature 0, the underlying search layer returns different pages hour to hour, so the same prompt can produce materially different answers.
  • Narrow tooling ecosystemLangChain, LlamaIndex and the agent frameworks have adapters but they lag the first-party SDK, so niche features like domain filters and recency controls often need a raw HTTP call.

Sound familiar?

Common Perplexity API problems we fix

The Perplexity API problems that bring people to us, and what you have once each one is fixed.

429 rate limit exceeded for sonar-pro

The integration keeps hitting rate caps

A chat endpoint that fans out one Sonar call per user turn, with no concurrency bucket or backoff, and a trial tier limit lower than the traffic you actually have.

Backoff in place, tier matched to load

citation index out of range

Citations do not line up with the text

A parser assuming citations are inline footnotes rather than a separate array, or a response where the model wrote more claims than it cited and the frontend silently dropped half of them.

Citations rendered accurately

400 model has been deprecated

A model ID stopped working overnight

An older online model identifier that Perplexity sunset without any code change on your side, surfaced as a plain 400 the morning after rollout.

Pinned to a supported model

billing up 340% month over month

The Sonar bill tripled

A prompt that was moved from Sonar to Sonar Pro for a quality bump, combined with a UI that fires a search on every keystroke rather than on submit.

Spend back under control

ReadTimeout api.perplexity.ai

Requests hang until the client times out

An upstream search provider that is slow, no request timeout set in your HTTP client, and a worker pool that fills up waiting for responses that will never arrive.

Timeouts and retries that behave

stream chunk missing citations field

The stream parser crashes on partial chunks

Downstream code assuming every SSE event contains a citations array, when in reality the field only arrives on the final chunk for some model variants.

Stream handling hardened

search_domain_filter ignored

Domain filters are silently dropped

A request passing search_domain_filter on a tier where the parameter is not honoured, so results still include the sites you explicitly tried to exclude.

Filtering working as documented

What we do

Perplexity API help, from rescue to upkeep

Bring us one failing endpoint, or hand over the whole Sonar integration.

Rescue
Rate caps hitting in production, citations rendering wrong, or a bill that tripled. We stabilise the call path and work back to the cause.
Prompt and tier design
Choosing between Sonar, Sonar Pro and reasoning variants against your actual accuracy and latency budget, with cost numbers before you commit.
Citation rendering
A frontend that shows the right source next to the right claim, handles missing citations gracefully, and does not break when the response shape changes.
Streaming and fallbacks
SSE handlers that cope with partial chunks, timeouts and reconnects, plus a non-grounded fallback for when Perplexity is having a bad hour.
Migration
Moving a feature from OpenAI or Anthropic to Sonar, or the other way around, without rewriting half the product.
Managed Tech
Spend dashboards, model-sunset alerts, latency tracking, and engineers on call when Sonar behaviour shifts after a release.

How it works

From first message to fixed

  1. Look Free estimate

    Tell us what's going wrong. We look at it, then tell you plainly what's wrong and what it will cost.

  2. Fix

    We fix the cause, not the symptom. If something is down, getting it back up comes first.

  3. Harden

    Backups, monitoring, updates and access, so the same problem can't quietly come back.

  4. Hand back or stay on

    You get a plain-language write-up. Or we stay on for hosting, upkeep and new work.

Often found together

Running Perplexity API alongside something else?

We work on the whole stack, so the problem can be wherever it actually is.

Questions

Perplexity API questions

Something else? Call+1 737 727 7327

When should we use Perplexity Sonar instead of OpenAI or Anthropic?

When the answer genuinely needs fresh web knowledge and you want the citations in the response rather than a separate retrieval step. For a product support bot grounded in your own docs, a retrieval layer over GPT or Claude will usually be cheaper and more controllable. For a research-style assistant that needs to quote current sources, Sonar is doing work that would otherwise be several tool calls.

Why are Sonar citations sometimes inaccurate?

The retrieval layer picks pages that look relevant to the query, and the model then writes a grounded answer, but it does not always point at the exact paragraph that supports a given sentence. If your product treats citations as proof, you need either a spot-check step or a second pass that re-ranks citations against the generated text.

How do we keep Sonar Pro costs under control?

Three things usually help. Cap requests per user session, route easy queries to the cheaper Sonar tier and reserve Pro for ones that failed quality checks, and debounce the frontend so it does not fire a search per keystroke. We also put a hard monthly ceiling at the API layer so a runaway loop cannot drain the account.

Can we trust Sonar for a production customer-facing feature?

For non-critical uses, yes, with normal safety rails. For anything that must be accurate like financial, legal or medical content, we would pair it with a human-reviewed source list, a stricter domain filter, and a disclaimer on the output. The model hallucinates less than a pure LLM but it does still hallucinate.

Does Sonar support function calling or tools like OpenAI?

Not in the same way. The API is focused on search-grounded chat, so if your use case needs structured tool calls or a complex agent loop, you will typically pair Sonar with another model that does tooling well, and use Sonar only for the knowledge retrieval step.

How much does Perplexity API help cost?

The estimate is free. Send over the endpoint, the current prompt and a sample of the responses that are misbehaving, and we return a price before any work starts.

Free estimate

Perplexity API giving you trouble?

Tell us what you're running and what's going wrong. A person reads it and comes back with an estimate.

  • No charge to find out what it will take
  • If it's urgent, say so

Replies come from a person. By sending, you authorize us to email you back. No marketing.