Perplexity Focus Mode Cannot Be Changed in API Calls: Workaround

If you use the Perplexity API to automate searches or build applications, you may have noticed that the Focus Mode setting does not change when you specify it in your API request. This means your API calls always return results from the default search domain, ignoring parameters meant to switch to Academic, Writing, Math, Video, or other modes. The root cause is that the Perplexity API currently does not support dynamic Focus Mode selection through standard request parameters. This article explains why this limitation exists and provides a concrete workaround using alternative API endpoints and query modifications to achieve the same result.

Why Perplexity API Ignores the Focus Mode Parameter

The Perplexity API is designed primarily to perform web searches and generate answers using large language models. The Focus Mode feature available in the Perplexity web interface is a client-side setting that adjusts the search domain and model behavior for specific use cases. When you send an API call, the server processes the request based on the default endpoint configuration. The API specification does not include a dedicated focus_mode parameter in the request schema. Instead, the API uses a different parameter called search_focus that is not documented in the official quickstart guide.

The search_focus parameter is a query-level override that tells the underlying search engine to prioritize results from a specific domain or source type. This parameter is separate from the model selection and does not change the underlying language model. The web interface uses this same parameter internally when you switch Focus Modes. By using search_focus in your API calls, you can replicate the behavior of Focus Mode without relying on the unsupported focus_mode field.

Steps to Change Focus Mode in API Calls Using search_focus

The following steps show how to modify your API request to include the search_focus parameter. You can use any programming language or tool that supports HTTP POST requests. The example uses cURL for clarity.

1. Identify your API endpoint and authentication
   Your API call must target the correct endpoint. Use https://api.perplexity.ai/chat/completions for the chat-based endpoint. Include your API key in the Authorization header as Bearer YOUR_API_KEY. Without a valid key, the request will fail with a 401 error.
2. Add the search_focus parameter to the request body
   Inside your JSON request body, include the search_focus field at the same level as model and messages. Set its value to one of the supported strings: academic, writing, math, video, web, or social. For example: "search_focus": "academic". This tells the API to return results from scholarly sources.
3. Send the modified request
   Use a tool like cURL to test the change. A complete cURL command looks like this:
   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": "user", "content": "What is the latest research on quantum computing?"}], "search_focus": "academic" }'
4. Verify the response includes domain-specific sources
   Check the response JSON for the sources array. With search_focus: academic, the sources should include domains like arxiv.org, pubmed.ncbi.nlm.nih.gov, or scholar.google.com. If the sources still show general web domains like wikipedia.org or news.com, the parameter may be misspelled or the endpoint version may not support it.

Supported search_focus Values and Their Effects

The following values for search_focus correspond to the Focus Modes in the web interface:

• academic – Returns results from peer-reviewed journals, preprints, and academic databases.
• writing – Returns results from blogs, writing communities, and style guides.
• math – Returns results from mathematics-focused sites and forums like Math Stack Exchange.
• video – Returns results from video platforms like YouTube and Vimeo.
• web – Default behavior. Returns general web search results.
• social – Returns results from social media platforms like Reddit and Twitter.

If search_focus Does Not Work for Your Use Case

“I need Reddit or News Focus Mode”

The search_focus parameter does not include a dedicated reddit or news value. To achieve similar results, modify the user message content itself. Prepend site:reddit.com or site:news.yahoo.com to your query. For example: "content": "site:reddit.com best budget laptops 2025". This forces the search engine to return only results from the specified domain. This method works for any domain you want to target.

“The API returns an error when I add search_focus”

If your API call returns a 400 Bad Request error after adding search_focus, check that you are using the correct endpoint. The /chat/completions endpoint supports search_focus starting from API version v2. If you are using an older endpoint like /v1/completions, upgrade to https://api.perplexity.ai/chat/completions. Also verify that your JSON is valid: use double quotes, not single quotes, and ensure no trailing commas.

“The sources still show general web results”

This can happen if the search_focus value is misspelled or if the model you are using does not support domain filtering. Models like sonar-pro and sonar-reasoning-pro support search_focus. Models labeled mixtral or llama may not. Switch to a supported model and double-check the spelling: academic not academics, writing not write.

Perplexity API Focus Mode: Default vs search_focus Override

Item	Default API Behavior	With search_focus Parameter
Focus Mode selection	Always uses Web mode	Can use Academic, Writing, Math, Video, Social
Parameter name	None (ignores focus_mode)	search_focus
Supported endpoints	All endpoints	/chat/completions only
Domain restriction	No restriction	Restricts to specific source types
Query modification needed	No	No, but can be combined with site: prefix for unsupported modes

Perplexity API does not support Focus Mode changes via the standard focus_mode parameter. Use search_focus for supported modes or prepend site: queries for custom domains. Always test with a supported model and the correct endpoint. For the most up-to-date list of search_focus values, check the Perplexity API documentation under the search_focus section.