Perplexity API: Agent, Search, Router, Sonar and Embeddings Explained
The Perplexity API is now a broader developer platform rather than a single Sonar endpoint. Learn which API to choose, how to make a first request, where costs arise and how to build dependable, source-grounded research applications for SEO, content and outreach work.
Fact checked against Perplexity’s official developer documentation in August 2026. Endpoints, models, prices and limits can change, so confirm the live documentation before deployment.
search_results: [source_1, source_2]
What is the Perplexity API?
The Perplexity API lets developers add models, live web search, cited answers, agent tools and embeddings to their own software. It is separate from the consumer Perplexity AI website and apps: your code sends authenticated requests to an endpoint, receives structured responses and is billed for API usage.
The current platform has four core product families: Router, Agent, Search and Embeddings. Sonar Chat Completions is still supported, but Perplexity now lists Sonar under its legacy API documentation and recommends Agent API for new projects. That distinction matters because many older tutorials use Sonar as a synonym for the entire Perplexity API.
The Perplexity API types and what each one does
Choose the interface from the output you need. A generated answer, raw results, direct model access and vector embeddings solve different problems.
Agent API
A unified responses-style API for web-grounded answers, multi-provider models and multi-step work. Add hosted tools such as web search, URL fetching, people search, finance search and a code sandbox, or connect MCP and custom tools.
Best for AI assistants, cited research features, structured extraction and agentic workflows.
POST /v1/agentSearch API
Returns real-time ranked results as structured data, with controls for domains, language, region and extracted content. It can accept up to five related queries in one request.
Best for your own search interface, retrieval pipeline, monitoring tool or model-independent workflow.
POST /searchRouter API
Provides one endpoint and key for open-weight models hosted by Perplexity, with OpenAI- and Anthropic-compatible routes. Perplexity positions it for model-agnostic workloads and managed routing or failover.
Best when your application needs direct model output without the full agent tool loop.
OpenAI / Anthropic compatibleEmbeddings API
Turns text into vectors for semantic search, clustering and retrieval-augmented generation. Standard embeddings suit independent text; contextualised embeddings preserve relationships between chunks from the same document.
Best for knowledge bases, recommendations and document retrieval rather than answer generation.
Standard + contextualisedWhich Perplexity API should you use?
Start from the data your application needs to receive, then add only the model and tools required to produce it.
How to use the Perplexity API
This Agent API example uses a dynamic preset rather than hard-coding a model that may be retired. Keep authentication on the server and never expose the key in browser-side JavaScript.
Create or join an API group
Sign in to the API Console and create an API group. Groups organise keys, billing and access across projects or environments.
Add billing and generate a key
Create a dedicated key for development. Perplexity displays the full key once, so copy it into a secure secret manager and never commit it to a repository.
Install the official SDK
Use pip install perplexityai for Python or npm install @perplexity-ai/perplexity_ai for TypeScript and JavaScript.
Set the environment variable
Store the secret as PERPLEXITY_API_KEY. The official SDK reads it automatically, keeping the credential out of the request code.
Send, inspect and log safely
Make a small test call, check status, output, sources, usage and cost. Log response IDs and operational metrics, but do not copy keys or sensitive prompts into logs.
Agent API features for production applications
The Agent API can move beyond one prompt and one completion by combining reasoning, retrieval, tools and controlled outputs in a single run.
Web search and URL fetch
Let the model discover current pages with web_search or retrieve known pages with fetch_url. Domain, recency and location controls can narrow the evidence.
Hosted and custom tools
Add finance, people or sandbox tools; connect a remote MCP server; or declare your own function schema and return the result to the run.
Structured outputs
Use JSON Schema when downstream software needs predictable fields. Validate the response anyway, particularly where an output can trigger a database or publishing action.
Streaming and background work
Stream user-facing answers or run longer jobs in the background and retrieve them by response ID. Design timeout, reconnect and cancellation behaviour deliberately.
Multi-provider models
Use models from several providers behind a consistent interface. Presets can select a tested configuration; explicit models provide more control when requirements are fixed.
Fallback and budgets
Configure model fallback for reliability, set token and step limits, and restrict the tool set. These controls help contain latency, failure modes and unexpected spend.
How Perplexity API pricing works
API access is pay as you go and does not require a consumer subscription. The bill can include model tokens, search request fees or tool invocations depending on the API.
Agent API
Model tokens are charged at the chosen provider’s published rate with no markup, while enabled tools are billed separately when invoked.
Token + tool Current example: web_search $0.0025 per invocationSearch API
A successful request is one billing unit, even if it contains up to five queries. Rate limiting still counts every query in that array.
$5 / 1K Successful POST /search requestsRouter API
Billed per model token at the requested model’s published rate, including applicable cache and long-context pricing.
Per model No separate per-request feeSonar API
Sonar pricing combines input and output tokens with a request fee determined by model and search-context size.
Token + request Deep Research has additional billing dimensionsPerplexity API use cases for SEO and guest posting
Use the API to build repeatable research systems, not to manufacture evidence or send indiscriminate outreach at scale.
Search-change monitor
Run scheduled Search API queries for official search-engine updates, filter by trusted domains and store titles, dates and URLs for editorial review.
Publisher-guideline parser
Fetch known contributor pages and return a validated JSON record for topic fit, word count, link policy, contact route and evidence date.
Editorial gap research
Search a publication’s recent coverage, cluster topics and identify potentially useful angles. A human should confirm that the gap is real before pitching.
Claim-to-source checker
Compare draft claims with primary sources and flag missing, stale or contradictory evidence. Store the source URL and retrieval date beside each finding.
Internal knowledge search
Index approved service pages, editorial rules and campaign notes, then retrieve relevant passages before an answer or brief is generated.
Prospect-quality review
Collect public evidence about topical relevance, editorial activity and contributor information. Keep commercial notes separate from editorial-quality assessment.
How to build a dependable Perplexity API integration
A good demo returns an answer. A good production system controls evidence, output shape, failure recovery, cost and downstream consequences.
Restrict the evidence
Use domain and recency filters for sensitive topics. Prefer primary sources and record the source list returned with the response.
Validate structured output
JSON Schema improves consistency but is not a substitute for server-side validation, type checks and safe defaults.
Handle 429 responses
Respect Retry-After where supplied, use exponential backoff with jitter and avoid retrying invalid requests.
Design for partial failure
Search can return no results, a page can block extraction and a model can time out. Show a useful state rather than a fabricated answer.
Measure answer quality
Create an evaluation set for citation correctness, factuality, freshness, latency and field-level extraction accuracy.
Control spend
Limit steps, output tokens, search depth and enabled tools. Cache safe results and deduplicate repeated background jobs.
Perplexity API privacy and subscription rules
API data handling and API billing are separate from the settings and subscription attached to the consumer Perplexity product.
Data privacy and retention
Perplexity documents zero-day retention of user prompt data for the API and says customer data is not used for model training. It retains essential billable metadata such as token counts, model, timestamp, duration and key identification.
That policy does not remove your own obligations. Minimise personal data, review any third-party model or tool implications and keep secrets out of prompts and logs. Read the current Privacy & Security documentation.
API access vs Pro or Enterprise
A Perplexity Pro or Max subscription pays for features inside the Perplexity product; it does not provide unlimited API usage. The API uses its own console, groups, keys, credits, usage tiers and pay-as-you-go billing.
Perplexity Enterprise may be relevant for organisation-wide search, collaboration and admin controls, while an API integration is for embedding capabilities into your own application or workflow. Some organisations may need both.
Why a Perplexity API request fails
Check credentials, endpoint shape, model or preset availability, billing and rate limits before changing the prompt.
Missing or invalid key
Confirm the Authorization header, environment variable and API group. Rotate the key immediately if it appeared in public code, client-side JavaScript or a shared screenshot.
Request shape is invalid
Agent uses an input and typed output model, while Sonar uses messages and choices. Do not send one API’s payload to another endpoint.
Rate limit exceeded
Usage tiers affect several limits, while Search API has its own query-unit limit. Queue bursts and retry only after the documented interval.
Credit or billing issue
Check the API Console rather than the consumer subscription page. API groups require their own billing setup and available credit.
Structured output is incomplete
Allow enough output tokens, keep the schema focused and validate after receipt. Define a recovery path when required fields are missing.
Sources are weak or missing
Improve the query, adjust recency or domain filters and return an explicit insufficient-evidence state rather than filling gaps from assumption.
Perplexity API questions
Direct answers about access, Sonar, search results, keys, pricing and production use.
Is the Perplexity API free?
The platform is pay as you go. Perplexity says no subscription is required, but production requests are billed according to the API, model, tokens and tools used. The Search Playground may allow testing without a key, which is not the same as free production usage.
Do I need Perplexity Pro to use the API?
No. API access and billing are separate from consumer Pro, Max and Enterprise subscriptions. Set up an API group, billing and an API key in the API Console.
Is Sonar API deprecated?
Perplexity still supports Sonar Chat Completions, but documents it under Legacy API and recommends Agent API for new projects. Existing teams should evaluate migration based on required tools, response format, testing effort and risk.
What is the difference between Search API and Agent API?
Search API returns raw ranked web results for your software to process. Agent API uses models and optional tools to produce an answer or multi-step result, with source and tool output available in the response.
Does Perplexity train on API prompts?
Perplexity’s API documentation states that user prompt data has zero-day retention and is not used for AI training. It retains essential billing and service metadata. Always review the current policy and your own compliance obligations.
Which API is best for an SEO research tool?
Use Search API when you want raw results and will perform your own analysis. Use Agent API when you want a cited answer, structured extraction or a multi-step workflow. Use Embeddings for retrieval across your own approved document library.
Build the smallest reliable Perplexity API workflow first
Choose one endpoint, one clearly defined output and a small evaluation set. Prove citation quality, failure handling and cost before adding more models, tools or automation.
