Display Perplexity Sonar citations in responses

Feature Requests
1

Right now, Perplexity Sonar is failing to return citations, and I have the fix.

The Perplexity Sonar API returns source citations with every response as separate top-level fields (citations and search_results) alongside the message content. Pickaxe currently does not display them. End users see bare markers like [1] in the response text with no source list attached.

This makes Sonar models hard to use for research-style tools. The grounding sources are the main reason to choose Sonar over other models, and the data is already included in every API response Pickaxe receives. It just is not rendered.

This is a known integration gap for platforms that pass Perplexity through generic OpenAI-compatible handling, and other platforms have already hit and addressed it:

Perplexity’s own documentation confirms citations are returned by default on all requests and recommends reading URLs from the citation fields rather than asking the model to write them in prose (Sonar Prompt Guide). Since Pickaxe does not surface those fields, builders are pushed toward prompting the model to write URLs into the response text, which is exactly what Perplexity advises against.

Request: When a Sonar model is selected, render the citations array as a numbered source list below the response, ideally with clickable links. Bonus points for mapping the inline [1] markers to the corresponding sources, and for showing the source list in Message Insights alongside the existing token and action data.

Use case: I run a suite of AI tools for authors. One tool performs comparable-title research where every recommended book needs a verifiable source link. Sonar’s grounding quality is excellent and the per-run cost is a fraction of tool-loop alternatives, but without the citations rendering, the output ships without the links that make it trustworthy and usable.

The Reason Perplexity Doesn't Work on Pickaxe: It's Your Prompts
2

Hi @thomasumstattd,

We’re looking into this right now! I’ll let you know when I have an update on Perplexity Sonar citations!

3

Thanks @kyle_support !

Update from the field: whatever your team shipped is working.

As of this morning, my sonar-reasoning-pro tool returns citation markers as clickable markdown links pointing at the actual source pages, and the model is quoting retrieved evidence cleanly again. This is the feature I asked for, live in production. Thank you!

For your engineers’ records, the rollout was visible from outside as a sequence of states on identical inputs, and the middle states were rough. Session IDs in case the logs are useful:

  1. Evening of July 21 (session c62ed6af, my account): a response claiming tool access was “disabled,” with zero verifiable output. In hindsight this looks like a request that reached the model malformed during active work.

  2. Later that evening (session b24087f8-c1c5-43c7-a41b-7b6da7c547f2): linked citation markers appeared for the first time, but Pickaxe Latency jumped from my 2 to 3 second baseline to 12.28 seconds, and retrieval shifted from product pages toward forum threads and listicles, which degraded what the model could verify.

  3. Morning of July 22 (session f8fde23c-e840-4fd8-9122-e3f9b0f1ec19): latency normalized but responses arrived with no citations at all, and the model reported tools unavailable and answered from memory. That one looks like requests going out without search attached.

  4. Later this morning: healthy. Linked markers, grounded quotes, normal behavior.

Two remaining suggestions:

  1. Pass the citations through to Message Insights. Builders debugging research tools need to see what the model retrieved, next to the token and action data that is already there.

  2. Consider an optional numbered source list below the response in addition to the inline links. Some end users never click inline markers, and a visible source list is what makes grounded output legible as grounded.

Happy to keep testing. My comp-research tool quotes evidence from search results on every run, so it surfaces citation regressions in the first response. If you want a canary for future Perplexity work, I volunteer.

4

Follow-up with two more data points since my post above, because the picture changed within the hour.

The behavior is intermittent, not fully resolved. About twenty minutes after the healthy run I described in state 4, the identical tool, prompt, and inputs produced a response with zero citations of any kind, no markers and no links, and the model reported that tool access for searches was unavailable, so it could not verify anything (session b222e382-a117-4a67-b6c8-4b1701310f29, July 22). Pickaxe Latency was a normal 3.10 seconds on that run, so latency alone will not flag the broken requests. Runs are currently coin-flipping between healthy and citation-free, which looks from outside like a rolling deploy where some requests hit updated instances and others do not. I will post again once I see a stretch of consecutive healthy runs.

A possibly related duplication bug. On that same session (b222e382), the end-user document upload appears twice in Message Insights for a single upload, doubling the billed input tokens. I have logs of the same file listed twice across multiple sessions on different days going back over a week, and the duplication comes and goes, which makes me wonder if it lives near the request-assembly code your team is touching for the citations work. Happy to share the session IDs for the doubled runs if useful.

Canary offer stands. My tool quotes evidence from search results on every response, so I see citation regressions on the first run.

5

Hi @thomasumstattd,

Sorry you were experiencing issues with the citations only showing intermittently. We have pushed a new fix so now Perplexity Sonar models should be displaying all citations properly! Please go test it out and let me know how it’s working. If you do find that there are more bugs with the citations, send over some session IDs and I’ll review them right away!

6

Thanks @kyle_support!

I ran a batch of tests on the new fix and have results, plus two bugs your team should see while they are in this code, one configuration question, and one feature idea.

The citations fix is working. Linked citation markers are now rendering consistently across fresh sessions on sonar-reasoning-pro, including on runs where retrieval came back thin and the model had little to cite. Examples from today: session 60f29420-6bed-4168-a9d1-26a247b06d3d (rich multi-source citations, ISBN corroborated across three sources) and session e43819bb-1afc-441c-a749-35bdbe77df4e (thin retrieval, citations still rendering correctly). This resolves my original request. Thank you and the team.

Bug 1: the reasoning level selector swaps the model on Perplexity.

With my tool set to sonar-reasoning-pro, selecting the “Smartest” reasoning tier caused the run to execute on gpt-5.1 instead. Session c1dd41e1-3a70-4c10-aea6-4bb674eb6c4b, and the Model used field in Message Insights shows it plainly. The output lost all search grounding and citations, ran nearly 2 minutes to first token, and billed 10,400 output tokens. A settings control that silently changes the underlying model is a billing and trust problem, especially for builders who chose a search-grounded model specifically for verification.

For background: Perplexity’s sonar-reasoning-pro does not support a variable reasoning effort parameter. That parameter exists on sonar-deep-research, not on the reasoning models, so the Fast / Smart / Smartest picker has nothing valid to map to on Sonar. My suggestion is to hide or disable the reasoning picker when a Perplexity model is selected, or document what each tier actually sends. Related question: do Fast and Smart change anything at all on Sonar requests, or are they ignored? I have been unable to tell from behavior alone, and knowing the answer would help builders configure research tools correctly.

Bug 2: end-user uploads intermittently counted twice.

A single document upload sometimes appears twice in Message Insights, doubling the billed input tokens. Sessions showing the same file listed twice include 60f29420-6bed-4168-a9d1-26a247b06d3d, b222e382-a117-4a67-b6c8-4b1701310f29, and c1dd41e1-3a70-4c10-aea6-4bb674eb6c4b, and I have logs of the same duplication going back two weeks across different models, so it predates the citations work. Other sessions on the same tool show the file listed once, so it comes and goes. On a large manuscript upload this doubles the main cost driver of every affected run.

Configuration question: what search_context_size do Sonar requests use?

Perplexity’s API exposes web_search_options.search_context_size (low, medium, high), and it defaults to low. My runs alternate between draws rich in product and catalog pages and draws that return only listicles and forum threads with no publication data. If Pickaxe currently sends low or nothing, exposing this setting per Pickaxe, or defaulting search models to medium, would meaningfully improve research-style tools, and builders could decide whether the higher per-request search fee is worth it for their use case.

Feature Idea: Replace the reasoning level selector with search context size. Or just have the current selector control context size rather than reasoning.

7

Hi @thomasumstattd,

Thanks for giving such a detailed report!

Bug 1

I took a look at your run and it does seem like your agent used GPT 5.1 instead of Sonar Reasoning Pro. After investigating this session, I think that during this run, Sonar Reasoning Pro ran into an error(provider error, stream error, or something else) which caused the fallback model to be used. This is why GPT 5.1 was used for this run instead. I tried using Sonar Reasoning Pro on the “Smartest” reasoning and found that it did use the correct model for the response.

Perplexity’s Sonar API, which includes Sonar Reasoning Pro, supports the “reasoning_effort” field which maps to our reasoning options. Regular Sonar Pro does not seem to support this field so we hide our reasoning toggle when that model is selected. In our testing we have found that Fast and Smart do have an effect on Sonar’s responses, but please let us know if you find otherwise!

Screenshot 2026-07-23 at 11.28.13 AM
Screenshot 2026-07-23 at 11.28.13 AM1920×1007 170 KB

Bug 2
After looking through the sessions that you provided, I can confirm that duplicate files are being uploaded. My findings also showed that duplicated file uploads are not doubling your costs and billed input tokens. For session 60f29420-6bed-4168-a9d1-26a247b06d3d, your uploaded file was duplicated and 6,666 input tokens were used(input cost: 0.013332). For session 1d04db6d-c90c-4319-9cca-f6e89163b8b3, your file was not duplicated and 6659 input tokens were used (input cost: 0.013318). In both sessions, the uploaded file was the exact same. We ensure that all file uploads have to be unique meaning that if duplicated files are uploaded, only one of them will actually be processed. That being said, the duplicated file being uploaded is annoying and I will create a ticket for this issue.

Feature Request
Our engineers are currently looking into the option of allowing users to set web_search_options.search_context_size. I’ll let you know when I get an update on the matter!

8

Hi @thomasumstattd,

Just a quick update on the duplicate file upload. Our engineers released a fix so the files should no longer upload twice. Please let me know if you still see this behavior happening!