Perplexity API Domain Filter Returns No Results: Cause

When you apply a domain filter in the Perplexity API, the response can return zero results even though you know relevant content exists on the specified site. This typically happens because the API enforces a combined search scope that treats the domain filter as a secondary constraint rather than a primary query operator. In this article, you will learn the exact technical cause of this behavior and how to adjust your API calls to get the results you expect.

Why the Perplexity API Domain Filter Returns Zero Results

The Perplexity API uses a two-stage search architecture. First, it queries a general web index. Then it applies the domain filter as a post-processing step on the retrieved documents. When the initial index query does not return enough documents from the specified domain, the filter removes all results, leaving you with an empty set.

The root cause is that the search_domain parameter does not force the API to prioritize content from that domain. Instead, it acts as a hard filter after retrieval. If the index returns fewer than, for example, three documents from the target domain, the API discards them all because it cannot form a coherent answer from such a small sample.

Additionally, the API has a built-in deduplication and relevance scoring mechanism. Documents from the same domain are often ranked lower if the query does not explicitly mention the domain name. This means that even if the domain has relevant pages, they may be outranked by general web results and never reach the filter stage.

Steps to Diagnose and Fix the Domain Filter Issue

To resolve the empty results problem, you need to adjust your API request structure and test with different parameter combinations. Follow these steps in order.

Method 1: Use the site: Operator Inside the Query String

1. Remove the search_domain parameter
   Delete or comment out the search_domain field from your API request body. This parameter is the most common cause of empty results because it applies a strict post-filter.
2. Add site:example.com to your query string
   Prepend the site: operator to your query. For example, change "query": "latest AI research" to "query": "site:arxiv.org latest AI research". This tells the index to prioritize content from that domain during retrieval.
3. Increase the max_results parameter
   Set max_results to a higher value, such as 10 or 15. The default value is often 5, which may be too low for domain-restricted queries. A higher value gives the API more documents to work with before applying relevance scoring.
4. Test with a broad query first
   Send a request without any domain filter to confirm that the API can retrieve results for your topic. If you get zero results even without the filter, the issue is with the query itself, not the domain parameter.

Method 2: Combine search_domain with Explicit Domain in Query

1. Keep search_domain set to the target domain
   In your API request, set "search_domain": "example.com". This parameter still applies the post-filter, but you will compensate with the next step.
2. Add the domain name as a keyword in the query
   Include the domain name or a recognizable part of it in the query string. For example, if you are searching Microsoft documentation, use "query": "Microsoft docs Azure setup". This nudges the index to retrieve documents that mention the domain.
3. Set recency to "day" or "week"
   Use the recency parameter to limit results to recent content. This can help if the domain has a lot of old pages that the index ranks low. The API will then focus on newer, more relevant documents from that domain.
4. Check the API response for usage metadata
   Inspect the usage object in the API response. It shows how many documents were retrieved and how many were filtered. If filtered_count is high and result_count is zero, you know the domain filter is too aggressive.

If the Domain Filter Still Returns No Results

API Returns Empty Array for All Domain Filters

If you test multiple domains and all return zero results, the issue is likely with your API key or the endpoint you are using. Verify that your API key has access to the /search endpoint and that you are not hitting a rate limit. Check the HTTP status code: a 429 status means you have exceeded your quota. Wait for the reset period or upgrade your plan.

Another possibility is that the API model you selected does not support domain filtering. The sonar-pro model supports it, but the sonar-small model may not. Switch to sonar-pro or sonar-medium and test again.

Domain Filter Works in the Web UI but Not in the API

The Perplexity web interface uses a different search pipeline than the API. The web UI applies the domain filter during the query planning stage, while the API applies it after retrieval. This architectural difference means the same filter can behave differently. To mimic web UI behavior, use the site: operator inside the query string as shown in Method 1 above.

You can also try setting the "focus": "web" parameter in the API request. This tells the API to use the general web index rather than a specialized knowledge base, which often returns more domain-filtered results.

Perplexity API Domain Filter Methods: search_domain vs site: Operator

Item	search_domain Parameter	site: Operator in Query
Method of filtering	Post-retrieval hard filter	Index-level query modifier
Effect on retrieval	Does not influence which documents are initially retrieved	Forces the index to prioritize documents from the specified domain
Empty results risk	High if the domain has low coverage in the index	Low, because the index actively seeks content from the domain
Compatibility with other filters	Can be combined with recency and max_results	Works with any query parameter but may conflict with search_domain

You can now diagnose and fix the Perplexity API domain filter issue by switching from the search_domain parameter to the site: operator inside your query string. Test your API call with a broad query first, then gradually add the domain restriction. For persistent empty results, verify your API key permissions and model selection. As an advanced tip, use the usage metadata in the API response to monitor how many documents are filtered and adjust your max_results value accordingly.