AI engines
Perplexity Sonar API citations: what the Agent API returns
Sonar Chat Completions ended on September 27, 2026: citations now arrive as a search_results output item in the Agent API, with web search from $1 per 1,000 calls.

By Mathias C.SEO consultant, and more recently GEO, at MentionBox
If you came looking for the citation fields of the Perplexity Sonar API, the endpoint behind them has moved. Perplexity's migration guide states that Sonar Chat Completions support ended on September 27, 2026, and that synchronous and streaming requests keep working only because they are "being reformulated as Agent API requests, rolling out gradually by model". Citations now arrive as an item in the Agent API's output array, with type: "search_results", a queries array holding the searches that were run and a results array whose entries carry an id, url, title, snippet, source, date and last_updated. The search itself became a line on the invoice: the web_search tool is billed at $0.0025 per invocation, or $0.001 with Fast Search, on top of the tokens.
This page is for the developer with a working Sonar integration that reads citations and search_results off a chat completion, and for anyone who assumed an official Perplexity key would show what a Perplexity user sees. Below: what ended and what still works, the exact shape of a cited answer, the three Perplexity endpoints that return sources, the arithmetic of one answer, the filters that decide the source list, and where the official route stops being the right instrument for brand tracking.
What ended, and what still works
Three separate things carry the Sonar name, and only one of them is gone.
- Sonar Chat Completions, the endpoint. The migration guide puts its end of life at September 27, 2026 and gives the old address as
POST https://api.perplexity.ai/v1/sonar. Perplexity's changelog dates the move itself to July 2026, under the entry "Sonar Chat Completions is now Agent API". - Sonar async. Asynchronous Sonar requests stopped outright. The replacement is
background: trueon the Agent API, with the response polled by id. perplexity/sonar, the model. Still selectable, listed on the Agent API models page at $0.25 per 1M input and $2.50 per 1M output tokens, which makes it the cheapest Perplexity-badged model in that catalogue.
The Agent API lives at POST https://api.perplexity.ai/v1/agent, and its OpenAI compatibility page notes that POST /v1/responses is accepted as an alias, so client.responses.create() from the OpenAI SDK reaches it with nothing but a base URL change. The field renaming is mechanical, and the how-to guide prints the whole mapping. The parts a citation-reading integration touches:
| Sonar | Agent API |
|---|---|
model: "sonar" | effort: "fast", or a model id such as perplexity/sonar |
messages | input, a plain string or an array of typed items |
| the system message | instructions, a top-level field |
search_domain_filter | tools: [{"type": "web_search", "filters": {"search_domain_filter": [...]}}] |
search_recency_filter | the same filters object on the web_search tool |
web_search_options.user_location | user_location on the web_search tool, outside filters |
num_search_results | max_results on the web_search tool |
max_tokens | max_output_tokens |
choices[0].message.content | output_text |
| citation sources | the output item with type: "search_results" |
return_images, num_images | a separate image_search tool with its own max_results |
Mapping from Perplexity's "How to migrate from Sonar" guide and its Agent API reference, read on November 3, 2026.
Two Sonar features did not survive the move: search_language_filter was dropped, and video results (return_videos, num_videos) are not supported. A response_format.type: "regex" has to be redesigned around a JSON schema.
Where the citations live now
A searched call declares the tool and nothing else, the way the equivalents at OpenAI and Google do:
curl https://api.perplexity.ai/v1/agent \
-H "Authorization: Bearer $PERPLEXITY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "perplexity/sonar",
"input": "best AI visibility API for an agency",
"tools": [{"type": "web_search", "max_results": 15}]
}'
The response is a typed output array rather than a choices array, and the sources sit in their own item. The shape, from Perplexity's Agent API quickstart, with our prompt in place of its example:
{
"output": [
{
"type": "search_results",
"queries": ["best AI visibility API for agencies"],
"results": [
{
"id": 1,
"title": "Page title",
"url": "https://example.com/page",
"snippet": "Result snippet text",
"date": "2026-01-15",
"source": "web",
"last_updated": "2026-02-23T20:10:25"
}
]
},
{
"type": "message",
"role": "assistant",
"status": "completed",
"content": [{ "type": "output_text", "text": "Answer text with [web:1] markers", "annotations": [] }]
}
]
}
| What you get | Where to read it | What it is good for |
|---|---|---|
| The searches that ran | queries on the search_results item | reading the fan-out behind one prompt, and counting what the tool bills |
| The retrieved pages | results with id, url, title, snippet, source, date, last_updated | the source list, as publisher URLs rather than redirects |
| The link between answer and source | inline [web:ID] markers in output_text | matching a sentence to an entry by its id |
| The tool trace | output items such as fetch_url_results, image_search_results, sandbox_results | seeing what else the run touched |
| The bill | usage with input_tokens, output_tokens, tool_calls_details and a cost object | per-run cost, split by tokens and by tool |
Field names from Perplexity's Agent API quickstart, its web search tool page and the Create Agent Response reference, read on November 3, 2026.
Two details are worth keeping in your schema. The id on each result is an integer index for the citation markers, so it is local to one response and means nothing across runs; store the URL as the key. And date and last_updated both appear, which gives you the publication date and the freshness of each cited page without a second fetch, something the Google and OpenAI tools do not return. Perplexity's own guidance on output control adds a warning for structured output: asking the model to put links inside a JSON answer "may not always work reliably and can result in hallucinations or broken links", so read the links from search_results instead.
Three Perplexity endpoints that return sources
A citation-reading integration has a real choice to make here, because the three endpoints bill differently and return different objects.
| Endpoint | What it returns | Sources as | Price |
|---|---|---|---|
POST /v1/agent | a generated answer plus the whole tool trace | search_results item with queries and results | tokens at the model's rate, plus $0.0025 per web search invocation, or $0.001 with Fast Search |
POST /search | ranked web results, no answer | results with title, url, snippet, date, last_updated | $5.00 per 1,000 requests, $1.00 with Fast Search, no token billing |
POST /orchestrator/v1/chat/completions | a generated answer in the OpenAI schema | annotations with url_citation objects holding url, title, start_index, end_index | tokens at each model's rate, no per-request fee |
Endpoints, fields and rates from Perplexity's Search API overview, its Create Chat Completion reference and its pricing page, read on November 3, 2026.
The Search API is the one most citation projects overlook. It returns Perplexity's ranked retrieval set as JSON with no generated answer and no token billing, up to 20 results for a web search, and a multi-query request counts as one billing unit while each query in the array consumes a rate-limit unit. If the question you are answering is "which pages does Perplexity's index put forward for this query", that endpoint answers it for half a cent, without a model in the loop.
The Orchestrator endpoint is the opposite trade: it accepts the OpenAI Chat Completions schema, charges tokens only with no per-request fee, and gives you character ranges instead of ids, which is the better shape if you already parse url_citation annotations from OpenAI.
What a cited answer costs
The web_search tool is priced per invocation, and the number of invocations is a consequence of the effort level you ask for. Perplexity's effort page publishes the bundles: fast runs openai/gpt-6-luna with a single step and makes at most one tool call, low allows 5 steps, medium 15, high 40, and xhigh runs anthropic/claude-opus-5-5 with up to 300 steps and 512,000 output tokens. From low upward the search budget is fixed at max_results: 15, max_tokens: 4000 and max_tokens_per_page: 4000.
| Setup | Billed for one cited answer |
|---|---|
One Fast Search invocation, low effort on openai/gpt-6-luna | $0.001 for the search, plus about 4,500 input and 700 output tokens at $0.10 and $0.50 per 1M, near $0.0018 in total |
One Fast Search invocation, perplexity/sonar | $0.001, plus the same tokens at $0.25 and $2.50 per 1M, near $0.0039 |
| One standard web search invocation | $0.0025 instead of $0.001, tokens unchanged |
| A research-style run with ten search invocations | $0.01 of tool calls alone, before a single token |
fetch_url on top, per page opened | $0.0005 per invocation |
| The Search API, one request of up to five queries | $0.005, or $0.001 with Fast Search, no tokens |
Rates from Perplexity's pricing page, its Agent API models page and its effort page, read on November 3, 2026. Token volumes are a working assumption, since Perplexity publishes a search budget rather than an average.
Two numbers in that table are the ones to plan around. The first is the invocation count, since an xhigh run with 300 available steps has no published ceiling on how many searches it will choose to make, and each is billable. The changelog records the move that softened this in October 2026: the low, medium, high and xhigh levels adopted Fast Search, which took web search "from $2.50 to $1.00 per 1,000 invocations". The second is the model, where the spread between openai/gpt-6-luna at $0.10 input and anthropic/claude-fable-5 at $10.00 input is a factor of one hundred for the same retrieved pages.
Volume has a ceiling as well. The rate limits page sets the Agent API at 60 requests per minute on Tier 0, rising to 180 at Tier 1 after $50 of cumulative spend and 1,980 at Tier 4 after $1,000, while the Search API holds 50 query units per second across every tier.
The filters that decide the source list
The source list is the output you are measuring, and four parameters move it. All of them live on the web_search tool.
search_domain_filter, up to 20 entries, as an allowlist (["nasa.gov"]) or a denylist with a minus prefix (["-reddit.com"]). Narrowing to your own domain tells you whether Perplexity can retrieve your pages at all, which is a different question from whether it chooses them.search_recency_filter, one ofhour,day,week,month,year, plus the four date filters that take MM/DD/YYYY values and split publication date from last update.user_location, an object withcountry,region,city,latitudeandlongitude, sitting outsidefilters. A bare call has no country, and a located buyer does.search_type,webfor the standard index orfastfor the cheaper, lower-latency one. The two do not necessarily return the same pages, so pick one and keep it fixed for anything you compare over time.
What it changes for brand tracking
The citation fields look like a visibility feed, and they are not one. Perplexity states the gap plainly in its FAQ: "The API uses the same search system as the UI with differences in configuration, so their outputs may differ", and, on the same page, that the two "share search infrastructure, but their tools, configuration, and models differ, so results can differ". On the Agent API you also choose the model, the instructions, the effort level and the filters, so four variables that a perplexity.ai reader never touches are set by you.
Three more absences shape what you can honestly report:
- No position and no share of voice. One response gives one retrieved set. Where a brand sits inside the answer, how often it survives across repeated runs, and which competitors appear beside it are counts you write yourself. The formulas are in our piece on GEO metrics.
- No guarantee the search happened. The tool is model-decided, so the absence of a
search_resultsitem inoutputmeans the answer came from the weights. Record its presence as a column. - No settled retention story. Perplexity's privacy and security page states that zero data retention "is available only to eligible customers through an account-level configuration under a written agreement with Perplexity", and warns that if it has not been enabled, "do not assume that Perplexity or its model providers apply zero data retention to your requests". It also states that Perplexity does not use customer content to train generative AI models.
Perplexity's crawler page is a useful cross-check on the other side of the same question. PerplexityBot is described as the agent that surfaces and links websites in search results on Perplexity, and is "not used to crawl content for AI foundation models", while Perplexity-User fetches a page when a user's question needs it and "generally ignores robots.txt rules". Neither entry says anything about the fetch path behind an API call, so a site owner reading server logs cannot attribute a hit to an API request from the user agent alone.
Vendors that sell the consumer surface write the distinction into their own pages, which is the sentence to look for before buying. cloro states that "Sonar returns a model response with citation URLs but strips the source metadata, related-question suggestions, and shopping cards", and that its own requests read the rendered interface, returning sources with their position, related queries, shopping cards and the sub-queries Perplexity used. In our view that is the right way to read such a claim: not as a verdict on which product is better, but as a statement of which surface each one measures.
| Route to Perplexity sources | What it reads | What comes back | Price per 1,000 answers |
|---|---|---|---|
| API for GEO | Perplexity run natively, in the country and language asked for | raw answer, cited URLs by category, brand mentions, position, share of voice, sentiment, themes, fan-out questions | $13, down to $7 at its largest tier |
Agent API, web_search tool | the model you selected, with Perplexity's search attached | search_results with queries and results, inline [web:ID] markers | about $1.80 at low effort on openai/gpt-6-luna |
| Perplexity Search API | Perplexity's ranked index, no answer | results with title, url, snippet, date, last_updated | $5.00, or $1.00 with Fast Search |
| cloro | the perplexity.ai interface | answer in markdown, sources with position, related questions, shopping cards, sub-queries | $4 on the Lite plan |
| Bright Data AI Scrapers | the interface | raw answer, cited URLs, shopping products | $1.50 |
| DataForSEO AI Optimization | the interface and the official API, as separate endpoints | raw answer, cited URLs, brand mentions, fan-out queries, shopping products | $1.20 |
Vendor prices and capabilities from our comparator, checked on October 23, 2026; Perplexity rates from its pricing page, read on November 3, 2026.
API for GEO sits first in that table as the concrete example of the computed layer: it lists Perplexity among the engines it runs natively, and returns brand mentions, position, share of voice, sentiment and the fan-out questions already counted, at $13 per 1,000 answers down to $7 at its largest tier, with reads over stored runs free and resale allowed. The trade-off is in plain sight in the same column: $13 against $1.20 to $4 for the scraping APIs that hand you raw answers, and four of its ten engines, along with its webhooks, OpenAPI spec and official SDKs, were confirmed in our hands-on test of October 26, 2026 rather than documented on apiforgeo.com. MentionBox, which publishes this site, has a commercial link with API for GEO.
Five things that break a Sonar migration
- Reading
choicesinstead ofoutput. The answer text isoutput_text, and the sources are a sibling item in a typed array. Code that indexeschoices[0]returns nothing rather than failing loudly. - Storing the result
idas a key. It is an integer index scoped to one response, reused on the next call. Key on the URL and keep the id only for resolving[web:ID]markers in that same answer. - Sizing the budget on prompts. From
loweffort upward, several search invocations per run are normal and each one bills. Readtool_calls_detailsinusagebefore committing to a volume. - Mixing
search_typevalues in one table. The standard and fast indexes are priced differently and need not return the same pages, so a series that switches mid-month compares two things. - Expecting
search_language_filterto still work. It was dropped in the migration. Language targeting now runs throughuser_locationon the Agent API, or through the Search API, which still accepts up to 20 language codes.
A fair summary of the move is that Perplexity traded a chat endpoint with a citation list for an agent endpoint with a full trace, and made the retrieval a metered line item. For anyone building a product on top of Perplexity, the trace is more useful than what Sonar returned, since the queries, the retrieved set, the cited subset and the per-tool cost all arrive in one object. For anyone counting what engines tell buyers, the arithmetic above still has to happen somewhere. Our guide on tracking the AI citations of your pages sets out that pipeline across engines, and our ranking of self-serve APIs for developers covers the keys you can get on your own.
Frequently asked questions
Is the Perplexity Sonar API still available?
Sonar Chat Completions reached end of life on September 27, 2026, per Perplexity's own migration guide, which adds that synchronous and streaming requests keep working because they are being reformulated as Agent API requests, rolling out gradually by model. Asynchronous Sonar requests stopped and have to be rewritten with `background: true` on the Agent API. The name survives in two places: `perplexity/sonar` is still a model you can select, at $0.25 per 1M input and $2.50 per 1M output tokens, and Perplexity's own search infrastructure still powers the `web_search` tool.
How do I get citations from the Perplexity API?
On the Agent API, read the `output` array and pick the item whose `type` is `search_results`. It carries a `queries` array with the searches that were run and a `results` array in which each entry has an `id`, `url`, `title`, `snippet`, `source`, `date` and `last_updated`. The answer text refers to those entries with inline `[web:ID]` markers, so the mapping from a sentence to a source is the id rather than a character range. On the Orchestrator chat completions endpoint the shape differs: sources arrive as `annotations` holding `url_citation` objects with `url`, `title`, `start_index` and `end_index`, and no `search_results` item is documented there.
Does the Perplexity API return the same sources as perplexity.ai?
No, and Perplexity says so in its FAQ: "The API uses the same search system as the UI with differences in configuration, so their outputs may differ", and elsewhere on the same page, that the API and the web interface "share search infrastructure, but their tools, configuration, and models differ, so results can differ". You also pick the model and the instructions, which the web product does for you. Treat an API source list as a measurement of your own configuration.
How much does a Perplexity API answer with citations cost?
Two lines on the invoice. The `web_search` tool is $0.0025 per invocation, or $0.001 with `search_type: "fast"`, and the tokens are billed at the rate of the model you selected. On the `low` effort level, which Perplexity documents as `openai/gpt-6-luna` with a 4,000-token search budget, one answer of about 700 output tokens lands near $0.0018, so roughly $1.80 per 1,000 answers. The same answer on `perplexity/sonar` at $0.25 per 1M input and $2.50 per 1M output comes to about $3.90 per 1,000 with Fast Search. Rates read on Perplexity's pricing and models pages on November 3, 2026.
Can I limit Perplexity's search to certain domains, dates or a country?
Yes, through the `filters` object on the `web_search` tool. `search_domain_filter` takes up to 20 entries and works as an allowlist or, with a minus prefix such as `-reddit.com`, as a denylist; `search_recency_filter` accepts `hour`, `day`, `week`, `month` or `year`; `search_after_date_filter`, `search_before_date_filter`, `last_updated_after_filter` and `last_updated_before_filter` take MM/DD/YYYY dates. Location sits outside `filters`, as a `user_location` object with `country`, `region`, `city`, `latitude` and `longitude`. The `search_language_filter` that existed on Sonar was dropped in the move, though the standalone Search API still accepts up to 20 language codes.
Can I measure my brand's visibility in Perplexity with the official API?
You can count the sources your own configuration retrieved, which is a narrower figure than what a buyer reads on perplexity.ai. The API returns one answer with its retrieved set and no position, no share of voice and no repetition across runs, so the counting is yours to write. Retention is a second thing to settle before you store a year of answers: Perplexity's privacy page states that zero data retention "is available only to eligible customers through an account-level configuration under a written agreement", and warns against assuming it applies otherwise.