Perplexity API Cannot Set Focus Mode: Workaround

When using the Perplexity API, you may find that there is no direct parameter to set Focus Mode. The API does not expose a focus_mode field, so you cannot programmatically switch between Web, Academic, Writing, Math, Video, or Social search domains. This limitation means your API calls will always use the default search domain, which is Web. This article explains why Focus Mode is missing from the API and provides a practical workaround to simulate domain-specific searches using prompt engineering and query formatting.

Why Perplexity API Lacks a Focus Mode Parameter

The Perplexity web interface includes a Focus Mode dropdown that lets you restrict search results to a specific domain. This feature is implemented as a client-side filter on the web application. The API, however, is designed to be a general-purpose search and answer engine. It does not include a parameter for Focus Mode because the API’s primary use case is to provide answers from the entire web.

The API team has confirmed that Focus Mode is not part of the public API specification. Instead, the API uses the model parameter to select the underlying language model. Different models may have different strengths. For example, sonar-pro is optimized for deep research, while sonar-reasoning is better for step-by-step reasoning. However, none of these models restrict the search domain to a specific category like Academic or Video.

This means that if you need domain-specific search results through the API, you must implement a workaround on your side. The workaround involves three techniques: selecting the right model, crafting a focused prompt, and filtering the API response by source domain.

Steps to Simulate Focus Mode Using Prompt Engineering

Follow these steps to instruct the Perplexity API to return results that mimic a specific Focus Mode. The key is to include a clear domain instruction at the beginning of your query.

1. Select the appropriate model
   Choose a model that aligns with the focus domain. For research-heavy queries, use sonar-pro. For general web search, use sonar-small-online. Set the model parameter in your API request. Example: "model": "sonar-pro".
2. Add a Focus Mode instruction to the prompt
   Prepend your query with a sentence that tells the model to restrict its search. For Academic mode, write: Focus mode: Academic. Search only academic sources. For Writing mode: Focus mode: Writing. Search only writing and grammar resources. For Math mode: Focus mode: Math. Search only mathematical sources. For Video mode: Focus mode: Video. Search only video transcripts and descriptions. For Social mode: Focus mode: Social. Search only social media posts.
3. Set the system prompt
   If your API client supports a system prompt, set it to: You are a search assistant that only returns results from the specified domain. Follow the Focus mode instruction exactly. This reinforces the domain restriction.
4. Make the API request
   Send your request with the above parameters. For example, using curl:
   curl -X POST https://api.perplexity.ai/chat/completions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "sonar-pro", "messages": [{"role": "system", "content": "You are a search assistant that only returns results from the specified domain. Follow the Focus mode instruction exactly."}, {"role": "user", "content": "Focus mode: Academic. What is the latest research on quantum computing?"}]}'
5. Check the response sources
   Parse the sources array in the API response. Filter the sources to keep only those that match the desired domain. For Academic mode, keep sources with domains ending in .edu, .org, or from known academic publishers like nature.com or sciencedirect.com. Discard the rest.
6. Re-query if results are not satisfactory
   If the model ignores the Focus mode instruction, adjust the prompt. Make it more explicit: IMPORTANT: Only search academic papers and scholarly articles. Do not use general web sources. Then repeat the request.

Additional Workaround: Use the Web Interface API Endpoints

An alternative workaround is to call the same API endpoints that the Perplexity web interface uses when you select a Focus Mode. This is an unofficial approach and may break if the web interface changes. Use it at your own risk.

1. Open browser developer tools
   Open Perplexity in your browser. Press F12 to open Developer Tools. Go to the Network tab.
2. Select a Focus Mode
   Click the Focus Mode dropdown and choose, for example, Academic. Observe the network request that appears.
3. Copy the request details
   Right-click the request and select Copy > Copy as cURL. This gives you the full request with headers and body. Note that the request includes a focus_mode field in the JSON payload.
4. Replicate the request in your code
   Use the copied cURL command as a template for your API calls. Replace the session token with your own. Keep the focus_mode field set to the desired value.
5. Handle authentication
   You will need a valid session cookie or token. This approach bypasses the official API and uses the web interface’s internal API. It is not supported by Perplexity and may stop working after updates.

If the Workaround Does Not Work

The Model Ignores the Focus Mode Instruction

If the model returns general web results despite your prompt, the instruction may be too weak. Strengthen it by adding the phrase CRITICAL at the start. Also, set the temperature parameter to 0 to reduce creativity. Example: "temperature": 0. This forces the model to follow the instruction more strictly.

The Response Contains No Sources

Some API models, like sonar-reasoning, may not return a sources array. Switch to a model that does, such as sonar-pro or sonar-small-online. Check the API documentation for the list of models that support source citations.

Filtering Removes All Sources

If your filter removes all sources, the model may not have found any domain-specific results. Widen your filter criteria. For Academic mode, consider including .gov domains and preprint servers like arxiv.org. For Video mode, include youtube.com and vimeo.com. Adjust the filter and re-query.

Perplexity API Models vs Focus Mode Simulation

Item	API Model (sonar-small-online)	API Model (sonar-pro)
Best for Focus Mode	General web search (default Web mode)	Academic, Writing, Math (deep research)
Source citation support	Yes	Yes
Prompt instruction adherence	Moderate	Strong
Cost per 1M tokens	$0.20	$5.00
Use case	Quick answers, general knowledge	In-depth research, domain-specific queries

The Perplexity API does not support Focus Mode directly. You can simulate it by selecting the right model, crafting a precise prompt, and filtering the response sources. For best results, use sonar-pro for academic or deep research queries and sonar-small-online for general web searches. Always test your prompts with a few sample queries to verify the model follows the domain instruction. If the workaround fails, consider using the web interface’s internal API endpoints, but be prepared for potential breaking changes.