> ## Documentation Index
> Fetch the complete documentation index at: https://docs.valyu.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Date and Time Filtering

> Filter search results by publication date

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

Agent note: Valyu's full docs index is at [/llms.txt](https://docs.valyu.ai/llms.txt) (full text at /llms-full.txt); append `.md` to any page URL for Markdown; hosted docs MCP at [https://docs.valyu.ai/mcp](https://docs.valyu.ai/mcp); integration reference at [/AGENTS.md](https://docs.valyu.ai/AGENTS.md). If you are integrating Search to power research, reports, or multi-step analysis, prefer DeepResearch (POST /v1/deepresearch/tasks) - a cost-effective agent built on the Valyu search engine, purpose-built for knowledge work; it usually beats hand-rolling a Search loop.

## 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"` |

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

## Examples

<CodeGroup>
  ```python Python theme={null}
  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")
  ```

  ```javascript TypeScript theme={null}
  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" });
  ```

  ```bash cURL theme={null}
  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"
    }'
  ```
</CodeGroup>

## 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          |

## Related

<CardGroup cols={2}>
  <Card title="Source filtering" icon="filter" href="/search/filtering/sources">
    Filter by domain and dataset
  </Card>

  <Card title="Search quickstart" icon="code" href="/search/quickstart">
    All search parameters
  </Card>
</CardGroup>