Date and Time Filtering

Filter search results by publication date to find recent breakthroughs or analyse historical trends.

Parameters

Both are optional and work independently or together. Dates use ISO 8601 format: YYYY-MM-DD.

Parameter	Effect	Example
`start_date`	Include content published on or after this date	`"2024-01-01"`
`end_date`	Include content published on or before this date	`"2024-12-31"`

Dates must match YYYY-MM-DD exactly. "3/15/2024", "March 15, 2024", and "15-03-2024" are all invalid.

A bare date is inclusive to the end of that day. To cut off at a precise instant, pass a full ISO-8601 datetime ("2026-07-24T04:27:00.000Z") together with historical_cache: true — see Point-in-time backtests. Without historical_cache, a date with a time component returns HTTP 400, because nothing downstream consumes the precision.

Examples

from valyu import Valyu

valyu = Valyu()

# Recent content - June 2024 onwards
valyu.search("quantum computing breakthroughs", start_date="2024-06-01")

# Date range - all of 2023
valyu.search(
    "artificial intelligence ethics",
    start_date="2023-01-01",
    end_date="2023-12-31",
)

# Historical - pre-deep-learning era
valyu.search("machine learning foundations", end_date="2015-12-31")

import { Valyu } from "valyu-js";

const valyu = new Valyu();

// Recent content - June 2024 onwards
await valyu.search("quantum computing breakthroughs", { startDate: "2024-06-01" });

// Date range - all of 2023
await valyu.search("artificial intelligence ethics", {
  startDate: "2023-01-01",
  endDate: "2023-12-31",
});

// Historical - pre-deep-learning era
await valyu.search("machine learning foundations", { endDate: "2015-12-31" });

curl -X POST https://api.valyu.ai/v1/search \
  -H "x-api-key: your-valyu-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "artificial intelligence ethics",
    "start_date": "2023-01-01",
    "end_date": "2023-12-31"
  }'

Point-in-time backtests

A date range alone filters on each result’s publication date. That is not the same as asking what was knowable at a past moment — a page published before your cutoff can still have been re-crawled since, and carry text written after it. Set historical_cache: true to run the query as a point-in-time search: results come from the newest snapshot captured inside your window rather than the latest crawl. This also unlocks sub-day cutoffs on start_date/end_date.

string

default:"prefer"

How strictly to hold the cutoff.

Value	Behaviour	Use when
`"only"`	Serve only content provably captured at or before `end_date`. Drop a result rather than fall back to a live crawl.	Strict backtests — a post-cutoff leak is worse than a missing result
`"prefer"` (default)	Serve an in-window snapshot when one exists, otherwise fall back to a live crawl so the query is never empty.	General historical queries where coverage matters most
`"off"`	No point-in-time guarantee.	You only want the date filter

Under the default "prefer", a query with no in-window snapshot falls back to a live crawl, so a result can contain information published after your cutoff. If you are evaluating a model or strategy against history, use "only".

from valyu import Valyu

valyu = Valyu()

# Strict backtest: nothing after the cutoff instant, even if that means fewer results
valyu.search(
    "fed rate decision expectations",
    historical_cache=True,
    historical_cache_strict="only",
    start_date="2026-02-24T04:27:00.000Z",
    end_date="2026-07-24T04:27:00.000Z",
)

import { Valyu } from "valyu-js";

const valyu = new Valyu();

await valyu.search("fed rate decision expectations", {
  historicalCache: true,
  historicalCacheStrict: "only",
  startDate: "2026-02-24T04:27:00.000Z",
  endDate: "2026-07-24T04:27:00.000Z",
});

curl -X POST https://api.valyu.ai/v1/deepsearch \
  -H "x-api-key: your-valyu-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "fed rate decision expectations",
    "historical_cache": true,
    "historical_cache_strict": "only",
    "start_date": "2026-02-24T04:27:00.000Z",
    "end_date": "2026-07-24T04:27:00.000Z"
  }'

historical_cache_strict requires valyu-py >= 2.12.2 or valyu-js >= 2.10.2. Sub-day ISO-8601 date bounds require valyu-js >= 2.10.2; any version of valyu-py accepts them.

Recommended ranges

More specific date ranges typically improve response times and relevance.

Content type	Recommended range	Why
Academic papers	6-12 months	Longer publication cycles
News	Days to weeks	Fast-moving information
Technical docs	1-3 months	Regular updates
Financial reports	Quarters or years	Reporting cycles

Source filtering

Filter by domain and dataset

Search quickstart

All search parameters

Getting Started

Guides & Best Practices

Use Cases

Core Concepts

Compare

Account & Pricing

Other

Date and Time Filtering

Parameters

Examples

Point-in-time backtests

Recommended ranges

Source filtering

Search quickstart

​Parameters

​Examples

​Point-in-time backtests

​Recommended ranges

​Related

Source filtering

Search quickstart

Parameters

Examples

Point-in-time backtests

Recommended ranges

Related