How to Set Search Recency Filter via Perplexity API

When you query the Perplexity API, the default search behavior returns results from any time period. This can include outdated information that is not useful for tasks requiring the latest news, recent events, or time-sensitive data. The search recency filter lets you restrict results to a specific time range, such as the past day, week, or month.

This article explains how to configure the recency parameter in your API requests. You will learn the exact JSON field name, accepted values, and how to set it using Python, cURL, or any HTTP client. By the end, you will be able to control the freshness of search results from your Perplexity API calls.

What the Search Recency Filter Does

The Perplexity API uses an online language model that searches the web in real time. Without a recency filter, the model retrieves the most authoritative result regardless of its publication date. This is fine for evergreen topics like historical facts or scientific principles but fails for breaking news, stock prices, or recent product launches.

The search_recency_filter parameter instructs the model to prioritize or restrict results to a specific time window. The filter works by passing the time constraint to the underlying search engine before the model processes the results. The model then generates an answer based only on sources that match the recency requirement.

Supported Values

The parameter accepts four string values:

• day — restrict results to the past 24 hours
• week — restrict results to the past 7 days
• month — restrict results to the past 30 days
• any — no time restriction, equivalent to not setting the filter

Prerequisites

Before using the recency filter, ensure you have:

• A valid Perplexity API key from the Perplexity API dashboard
• An HTTP client such as cURL, Python with the requests library, or Postman
• Knowledge of how to send a POST request to the Perplexity API endpoint

Steps to Set the Search Recency Filter in Your API Request

The filter is set by adding a single JSON key-value pair to the request body. The exact placement matters: the parameter must be at the top level of the JSON object, not inside the messages array.

Method 1: Using cURL

1. Open your terminal or command prompt
   Ensure cURL is installed on your system. On Windows 10 and Windows 11, you can use PowerShell or the Command Prompt.
2. Compose the POST request
   Use the following command, replacing YOUR_API_KEY with your actual key:
   curl -X POST https://api.perplexity.ai/chat/completions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "pplx-7b-online", "messages": [{"role": "user", "content": "What is the latest news about AI regulation?"}], "search_recency_filter": "week"}'
3. Execute the request
   Press Enter. The API will return a response with sources and text limited to the past week.
4. Verify the filter in the response
   Check that the usage object in the response includes search_recency_filter set to week.

Method 2: Using Python with the Requests Library

1. Import the requests library
   Add import requests at the top of your Python script.
2. Define the API endpoint and headers
   url = "https://api.perplexity.ai/chat/completions"
headers = {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json"
}
3. Build the payload with the recency filter
   payload = {
"model": "pplx-7b-online",
"messages": [
{"role": "user", "content": "What are the latest cybersecurity threats?"}
],
"search_recency_filter": "day"
}
4. Send the POST request
   response = requests.post(url, headers=headers, json=payload)
print(response.json())
5. Run the script
   Execute the Python file. The response will contain results from the last 24 hours only.

Method 3: Using Postman

1. Create a new POST request
   Set the request URL to https://api.perplexity.ai/chat/completions.
2. Set the Authorization header
   Add a header with key Authorization and value Bearer YOUR_API_KEY.
3. Set the Content-Type header
   Add a header with key Content-Type and value application/json.
4. Write the JSON body
   In the Body tab, select “raw” and paste:
   {
"model": "pplx-7b-online",
"messages": [
{"role": "user", "content": "What are the latest tech stock prices?"}
],
"search_recency_filter": "month"
}
5. Send the request
   Click Send. The response will show results from the last 30 days.

Common Mistakes and Things to Avoid

Filter Not Applied Even Though Parameter Is Set

If the API returns results from outside the specified time range, check that the search_recency_filter parameter is at the top level of the JSON body. Placing it inside the messages array or nested under another key will cause it to be ignored. Also verify that the string value is lowercase and spelled correctly: day, week, month, or any.

Filter Works with Some Models but Not Others

The recency filter is supported on all online models but may not work on offline models that do not have internet access. Ensure you are using a model name that includes -online in its identifier, such as pplx-7b-online or mixtral-8x7b-instruct.

Filter Is Ignored When Search Disabled

If you set "search_domain": false or omit the search domain entirely, the model does not perform a web search. The recency filter has no effect because no search is executed. Always include a search domain or leave the default behavior intact.

Perplexity API Search Recency Filter: Available Values and Effect

Filter Value	Time Restriction	Use Case
day	Past 24 hours	Breaking news, live event results, urgent alerts
week	Past 7 days	Weekly summaries, recent product reviews, stock market trends
month	Past 30 days	Monthly reports, policy changes, software version updates
any	No restriction	Evergreen content, historical facts, foundational knowledge

The recency filter applies to the search results before the model generates the answer. It does not filter the model’s own knowledge cutoff date. For example, if you ask about a historical event using search_recency_filter: "day", the model will still use its training data but will only search the web for recent articles about that event.

You can combine the recency filter with other parameters like temperature, max_tokens, and search_domain. The filter does not affect the number of search results returned; it only restricts their publication time.

Now you can set the search recency filter in any Perplexity API request to get time-bound answers. Start by testing with the week value for the best balance of freshness and result availability. For a more granular approach, combine the recency filter with the search_domain parameter to restrict results to a specific website and time range simultaneously.