Sonar API
Send a question, get a written answer grounded in live web search, with citations. The usual starting point.
/v1/sonar
Overview
Which Perplexity API should you use?
Search API
Get ranked web results (title, URL, snippet, date) to feed into your own model or pipeline.
/search
Agent API
Run models from Perplexity, OpenAI, Anthropic, Google and others with built-in tools like web search and URL fetching.
/v1/agent
Router API
Use open-weight models with the OpenAI SDK by changing the base URL.
/router/v1
There’s also an Embeddings API for semantic search and RAG. All APIs share one API key and are billed per use, separately from Perplexity Pro and Max.
Quickstart
Make your first API call in 5 steps
Create an API key
Sign in to the Perplexity API console, add a payment method and some credit, then create a key on the API Keys page.
Keep your key secret. Never put it in front-end code, a public repo or a screenshot. Call the API from your server, and rotate the key if it leaks.
Store the key as an environment variable
export PERPLEXITY_API_KEY="your_api_key_here"
Install the Python SDK (optional)
Using Python? Install the official package. Any language that can send HTTP requests works too.
pip install perplexityai
Call the Sonar API
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": "What are the latest developments in AI agents?"} ] }'from perplexity import Perplexity client = Perplexity() # reads PERPLEXITY_API_KEY from your environment completion = client.chat.completions.create( model="sonar", messages=[ {"role": "user", "content": "What are the latest developments in AI agents?"} ], ) print(completion.choices[0].message.content)// Node.js 18+ (built-in fetch). Keep this on your server, never in the browser. const res = await fetch("https://api.perplexity.ai/v1/sonar", { method: "POST", headers: { "Authorization": `Bearer ${process.env.PERPLEXITY_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ model: "sonar", messages: [{ role: "user", content: "What are the latest developments in AI agents?" }], }), }); const data = await res.json(); console.log(data.choices[0].message.content);Read the answer and its sources
The answer is in choices[0].message.content. Sources come back in citations (URLs) and search_results (titles, URLs, dates, snippets). Show them in your app so users can check the answer.
{ "model": "sonar", "choices": [ { "message": { "role": "assistant", "content": "Recent developments include ... [1][2]" } } ], "citations": [ "https://example.com/source-1", "https://example.com/source-2" ], "search_results": [ { "title": "...", "url": "https://example.com/source-1", "date": "...", "snippet": "..." } ], "usage": { "prompt_tokens": 14, "completion_tokens": 212 } }# Show the sources under your answer for i, url in enumerate(completion.citations, start=1): print(f"[{i}] {url}")
Models
Sonar models and pricing
Token prices are per 1 million tokens. Request fees are per 1,000 requests and depend on the search context size you choose (low, medium or high).
| Model ID | Best for | Input | Output | Request fee (low / med / high) |
|---|---|---|---|---|
| sonar | Fast, low-cost answers | $1 | $1 | $5 / $8 / $12 |
| sonar-pro | Harder, multi-part questions | $3 | $15 | $6 / $10 / $14 |
| sonar-reasoning-pro | Step-by-step reasoning | $2 | $8 | $6 / $10 / $14 |
| sonar-deep-research | Long research reports | $2 | $8 | + $2/1M citation, $3/1M reasoning tokens, $5 per 1K searches |
Search API: $5 per 1,000 requests ($1 per 1,000 in fast mode). Prices from Perplexity’s pricing docs, October 2026; check there before you budget. More detail in our API pricing guide.
Perplexity API cost calculator
Estimate your monthly bill for the Sonar models. Results are estimates; actual token counts vary by question and answer length.
Token cost–
Request fees–
Estimated total / month–
Per 1,000 requests–
Other APIs
Search, Agent and Router APIs
Search API: raw web results
curl -X POST https://api.perplexity.ai/search \
-H "Authorization: Bearer $PERPLEXITY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "SpaceX Starship", "max_results": 5}'Agent API: models with built-in tools
from perplexity import Perplexity
client = Perplexity()
response = client.responses.create(
preset="low",
input="Compare the three most popular open-source vector databases.",
)
print(response.output_text)Router API: use the OpenAI SDK
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ.get("PERPLEXITY_API_KEY"),
base_url="https://api.perplexity.ai/router/v1",
)Production
Best practices
Call from your server
Keep the API key on the backend. Expose your own endpoint to the front end.
Show the citations
Display the sources next to each answer. It builds trust and lets users verify.
Pick the smallest model that works
Start with sonar and low context; upgrade only for questions that need it.
Cache repeat questions
Store answers for common queries for a short time to cut cost and latency.
Retry with backoff
On 429 or 5xx errors, wait and retry with exponential backoff and jitter.
Set limits and alerts
Watch usage in the console and set spending alerts so a bug can’t run up a bill.
Troubleshooting
Common API errors
| Code | Meaning | Fix |
|---|---|---|
| 400 | Bad request | Check the JSON body, the model name and the messages format. |
| 401 | Unauthorized | Check the key is set, correct and sent as Authorization: Bearer …. |
| 402 | Payment required | Add credit or a payment method in the API console. |
| 429 | Rate limited | Slow down, retry with backoff, and cache repeated queries. |
| 5xx | Server error | Retry after a short wait; check Perplexity’s status page if it persists. |
More fixes in our API troubleshooting guide.
FAQ
Perplexity API questions
Is the Perplexity API free?
No. The API is pay-as-you-go: you add credit in the API console and pay per token, per request or per search. It’s billed separately from Perplexity Pro and Max subscriptions.
What’s the difference between the Sonar API and the Search API?
Sonar returns a written answer with citations, generated from a live web search. The Search API returns ranked web results (title, URL, snippet, date) without writing an answer, so you can use them in your own pipeline or with your own model.
Which model should I start with?
Start with sonar: it’s the cheapest and fastest. Move to sonar-pro for harder, multi-part questions, sonar-reasoning-pro for step-by-step reasoning, and sonar-deep-research for long reports.
Can I use the OpenAI SDK with Perplexity?
Yes, for the Router API, by setting the base URL to https://api.perplexity.ai/router/v1. For Sonar, the official perplexityai Python package or a plain HTTP call is the simplest route.
How do I get the sources from an API response?
Sonar responses include a citations array of URLs and a search_results array with titles, URLs, dates and snippets. Show them to your users so they can check answers.
Why am I getting a 429 error?
You’ve hit a rate limit for your usage tier. Slow down, retry with exponential backoff, and cache repeated queries. Limits rise as your account’s usage tier increases.
More API guides
Build
Get your API key and ship your first feature
Create a key in the official console, paste the quickstart code, and you’ll have cited answers in your app in minutes.