Perplexity for technical research: modes, Projects, and the API

Perplexity answers a technical question by searching, writing a short synthesis, and attaching numbered sources. That is useful when you are debugging an error string or comparing two designs. It is not a substitute for the vendor page the citation points at. This lab uses the product’s own names as they stood on the help center and API docs read in October 2026.

What a search actually returns

The “How does Perplexity work” help article describes three moves: search the web, compress the relevant bits into one answer, and attach numbered citations that link to the originals. Follow-up questions stay in the same session.

Pro Search is the deeper pass. The Pro article says it is not a toggle. When you search, Perplexity applies it automatically if your plan includes it, up to that plan’s limit. You can leave the model on Best, which picks a model per question, or choose a model in the model menu. The Pro help page, as read for this article, names examples including GPT-5.2, Claude Sonnet 4.6, and Gemini 3.1 Pro. The Pro Search article’s examples are not identical. Treat the menu in your account as the list, and those names as illustrations from the help pages, not a contract.

The same “how it works” article describes Research as a longer loop: many searches, many sources, and a report it says arrives in about two to four minutes. Use that when the question is a design survey. Use a normal search when you need one fact and a link.

Prompt shape for everyday questions is the same habit as the ChatGPT prompting cheat sheet: name the object, the constraint, and what the answer must cite.

Focus, sources, and search modes

The Pro Search help article says the crawl depends on the focus you select, and it gives Web, Academic, Finance, and Files as examples. It also says you can narrow to content types such as Academic, Finance, or your own files.

Enterprise Pro is different. The help-center collection states that Focus was replaced by Choose sources. The Internal Knowledge Search article lists the choices: Web, Org Files, Web + Org Files, or None. Deselect Web when you want only the organization’s files. Deselect both when you want an answer that does not use those sources.

Finance focus is not “the whole web, but about money.” The help center’s premium-data collection lists connectors such as FactSet, PitchBook, Morningstar, Daloopa, and others, some of which require your own authorization. A Finance answer can still miss a filing. For anything you would put in a design doc, open the citation.

On the API, the old Sonar field search_mode accepted web, academic, and sec. The migration guide says academic has no direct equivalent on the Agent API. Use the web_search tool with a domain filter, and say in the instructions that you want peer-reviewed or primary sources. For sec, the guide says to use Finance Search, or web_search limited to SEC sources. Do not keep sending search_mode: academic on new code and expect the old behavior.

Projects, not a second kind of chat

The Projects help article describes a Project as a persistent workspace: searches, Computer tasks, files, instructions, and connected tools, shared with collaborators. Files in the Project are context for that work. Viewers and editors can view files. The article says only editors can edit, delete, or upload.

Enterprise help adds the practical bits. Files you upload to a personal Project are not automatically part of the organization-wide repository. You can set custom instructions for how answers should be written, and you can pick a model for that Project. The enterprise article’s model examples include GPT-5 and Claude 4.5 Sonnet. Those examples disagree slightly with the Pro page’s model list. Use them as evidence that the menu changes, not as a lineup to memorize.

A debugging Project is a good fit for one service: the last incident notes, the config snippet, and an instruction such as “quote the error string, then list only causes that appear in the attached files or in a citation.” An architecture Project is the same idea with ADRs and a constraint like “prefer the current major version and say when a citation is older than 18 months.”

Files and what happens to them

The file-upload help article says you attach files from the search bar with + Attach, or by dragging a file or a folder. It says textual files (plain text, code, PDFs), images, audio, and video are in scope. Audio and video are transcribed so the speech can be searched. Short files can be used in full. A long file is reduced to the parts the system treats as most relevant to the question. If the answer misses a section you know is in the PDF, the extraction is the first suspect. Ask again with the page or heading named, or paste that section.

The Internal Knowledge Search article, in its comparison of upload versus the org repository, says you can attach up to five files per thread, that those files are for that session, and that they are deleted after seven days. That is a limit from that help page, as read in October 2026. Org repository files and Project files are the durable option. The same article says organization administrators can upload up to 500 files to the org repository. Do not plan a personal upload as an archive.

Citations you can check

Every answer the help articles describe includes links back to sources. Inline citations from internal files, on the enterprise page, can be opened or downloaded from the reference. That is the whole value of the product for operations work. A paragraph with no citation is a draft. A paragraph with a citation is still a draft until you open the URL.

Check three things on the source page:

• The page is the vendor’s own doc, not a repost.
• The sentence you might copy is actually on that page.
• The version and the date match the cluster or CLI you run.

If the citation is a forum post, say so in your notes. If two citations disagree, keep the newer primary doc. Perplexity will not reliably tell you which one changed last week.

Prompts for debugging and for design research

Write the prompt so a citation can falsify it. Include the exact error text, the version, and the output you want.

Debugging:

Kubernetes 1.31. The kubelet event says "Failed to pull image" and the container reason is ImagePullBackOff.
Search current container-runtime and registry docs.
Return: the three most common causes, each with the doc URL and the sentence you used.
If a cause is not in a citation, omit it.

Architecture:

Compare external-dns and a cloud-controller Service load balancer for a single regional cluster.
Use docs from the last 18 months.
Return a table: who creates the DNS record, what is stored in the cluster, and what fails closed.
Cite every cell.

Add “do not recommend a flag you cannot cite” when you are about to paste the answer into a runbook. For a multi-step investigation you would rather automate, an agent with tools is a different system. See what is agentic AI. Calling Perplexity from a workflow is an HTTP step in n8n first workflow, using the API below, not a scrape of the website.

API: Sonar names, Agent API calls

As of the migration guide read in October 2026, Sonar Chat Completions support ended on September 27, 2026. Synchronous and streaming Sonar requests still respond. They are being reformulated into Agent API requests, rolling out by model. Asynchronous Sonar requests are not reformulated. Move those to the Agent API’s background mode.

The Sonar model ids the older API reference enumerated were sonar, sonar-pro, sonar-reasoning-pro, and sonar-deep-research. The guide maps them onto effort levels:

New requests go to POST https://api.perplexity.ai/v1/agent with Authorization: Bearer and PERPLEXITY_API_KEY. The official Python client is perplexity.Perplexity, then client.responses.create. Effort presets fill in tools. The migration notes say tools: [] does not clear an effort level’s tools, and that max_tool_calls: 0 is the blunt way to stop tool calls.

curl https://api.perplexity.ai/v1/agent \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"effort\":\"low\",\"input\":\"Why does a Kubernetes Ingress return 404 after a canary deploy? Cite the docs you used.\"}"

import os
from perplexity import Perplexity

client = Perplexity()
response = client.responses.create(
    effort="low",
    input="Why does a Kubernetes Ingress return 404 after a canary deploy? Cite the docs you used.",
)
print(response.output_text)

The key is the environment variable the client expects. Do not put it in the script. The Agent API response is a list of steps: a search_results item and a message item, not the old Sonar choices plus a top-level citations array. Read the URLs from search_results and check them.

Domain filters moved onto the web_search tool’s filters, under the same names (search_domain_filter, recency, date). search_mode: academic does not come across. The Agent API also documents a code sandbox and MCP alongside web search. MCP as a protocol is explained in MCP servers explained. A different vendor’s model list, if you outgrow a single research API, is in the Gemini tools cheat sheet.

When not to trust it

Do not trust it for a flag, a default, or a quota you have not opened on the vendor’s site. The citation can be a secondary blog that paraphrased an old default.

Do not trust it for a long PDF you did not spot-check. The upload help article says long files are reduced to relevant parts.

Do not trust a model name in an old screenshot. Two official help articles, read the same week, used different example model names.

Do not send secrets, customer data, or an unreleased design into a consumer thread if your company’s rule is that prompts are not a private store. Project sharing means other members with access can see the files. The enterprise article says viewers can view files.

Do not keep an async Sonar integration. That path is the one the migration guide says is no longer supported.

Research output is a reading list with a draft summary. The decision still belongs to the person who opens the links.

FAQ

What happened to the Perplexity Sonar API?

Sonar Chat Completions support ended on September 27, 2026. Perplexity’s migration guide says synchronous and streaming Sonar calls still run because they are being rewritten as Agent API requests, gradually by model. Asynchronous Sonar calls are not rewritten and are no longer supported. New work should call the Agent API.

Are Perplexity Spaces still a feature?

The help center page read for this article describes Projects, not a product named Spaces. A Project holds searches, files, instructions, and connected tools for the people you share it with. Enterprise help also says Focus was replaced by Choose sources for Enterprise Pro users.

Does a numbered citation mean the sentence is correct?

It means the product attached a source. Open the link and check that the page states the claim. Long uploads are summarized from extracted parts, not always read in full. The help center says short files can be analyzed entirely and long files are reduced to the parts the system treats as relevant.

Which Agent API effort level replaces Sonar Deep Research?

The migration guide maps Sonar Deep Research to effort high. It maps Sonar and Sonar Pro to fast, and Sonar Reasoning Pro to low. It points at xhigh when you want the deepest tier in that lineup. Academic search mode has no direct field. Filter web_search domains and say so in the instructions.