How do I filter Brave Search API results by date?

Definition: As of October 2026, Brave Search API's freshness query parameter filters web search results by page age. It accepts preset age limits or a custom date range, using the most relevant date reported by the content, such as publication or last modification.

Key facts

• Brave's Web Search guide lists pd, pw, pm and py as preset freshness values.
• The Web Search API reference specifies the custom format YYYY-MM-DDtoYYYY-MM-DD, with a start date followed by an end date.
• Brave's authentication guide requires an API key in the X-Subscription-Token HTTP header for every request, including requests with a date filter.

How does a preset filter enter the request?

Brave's Web Search guide demonstrates a request for web pages from the past week with freshness=pw. The parameter accompanies the search query, named q, in the request URL. The following adaptation of that example reads the API key from the BRAVE_API_KEY environment variable:

curl "https://api.search.brave.com/res/v1/web/search?q=machine+learning+tutorials&freshness=pw" \
  -H "X-Subscription-Token: $BRAVE_API_KEY"

The API reference gives the precise age limits:

How does a custom date range work?

The Web Search guide gives 2022-04-01to2022-07-30 as its custom-range example. The start date and end date each use year-month-day order, joined directly by the lowercase text to. The request below uses that documented interval:

curl "https://api.search.brave.com/res/v1/web/search?q=machine+learning+tutorials&freshness=2022-04-01to2022-07-30" \
  -H "X-Subscription-Token: $BRAVE_API_KEY"

The same freshness parameter carries either the preset or the custom interval. A custom range supplies explicit calendar dates; the guide's preset example supplies a relative window covering the past week.

Which response fields help interpret the dates?

The API reference defines page_age in each web result as the page's date, based on publication or last modification. It also defines page_fetched as the date when the web page was last fetched. Both fields are nullable strings, so a response can contain a null value.

The reference also provides web.results.age, a human-readable age with 2 days ago as its example. The content date used for freshness and the fetch date describe separate events.

Related terms

• Brave Search API
• Brave Search localisation
• Article update dates

FAQ

Which value selects pages from the past week?

Use freshness=pw. Brave's Web Search guide demonstrates that value in its weekly filtering request.

Does freshness use only the original publication date?

The API reference describes the most relevant date reported by the content, which can be its published or last modified date.

How should I supply the API key in these examples?

Set BRAVE_API_KEY in the environment before running the commands. Brave's authentication guide documents this variable and recommends environment variables or secure configuration management for key storage.

Sources

1. Brave, "Web Search API reference", undated
2. Brave, "Web Search", undated
3. Brave, "Authentication", undated

---

Check how a page reads to answer engines. Open the GEO score analyzer