> ## 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. Find recent breakthroughs or analyse historical trends.

<Note>
  Dates use **ISO 8601 format**: `YYYY-MM-DD`. Both `start_date` and `end_date` are optional and work independently or together.
</Note>

## What You Can Do

* **Find recent developments** - Get the latest research, news, or market data
* **Access historical content** - Research how topics evolved over time
* **Reduce noise** - Focus on relevant time periods
* **Enable trend analysis** - Compare content across different eras

## Parameters

<CardGroup cols={2}>
  <Card title="start_date" icon="calendar-days">
    **Format**: `YYYY-MM-DD`

    Include content published **on or after** this date.

    *Example*: `"2024-01-01"`
  </Card>

  <Card title="end_date" icon="calendar-check">
    **Format**: `YYYY-MM-DD`

    Include content published **on or before** this date.

    *Example*: `"2024-12-31"`
  </Card>
</CardGroup>

## Date Format

<Warning>
  Dates must match `YYYY-MM-DD` exactly (ISO 8601 standard).
</Warning>

| ✅ **Correct**  | ❌ **Incorrect**    |
| -------------- | ------------------ |
| `"2024-03-15"` | `"3/15/2024"`      |
| `"2024-01-01"` | `"March 15, 2024"` |
| `"2024-12-31"` | `"15-03-2024"`     |

## Examples

### Recent Content

<CodeGroup>
  ```python Python theme={null}
  from valyu import Valyu

  valyu = Valyu("your-api-key-here")
  response = valyu.search(
      "quantum computing breakthroughs",
      start_date="2024-06-01"  # June 2024 onwards
  )
  ```

  ```javascript TypeScript theme={null}
  import { Valyu } from 'valyu-js';

  const valyu = new Valyu("your-api-key-here");

  const response = await valyu.search(
    "quantum computing breakthroughs",
    {
      startDate: '2024-06-01'
    }
  );
  ```

  ```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": "quantum computing breakthroughs",
      "start_date": "2024-06-01"
    }'
  ```
</CodeGroup>

### Date Range

<CodeGroup>
  ```python Python theme={null}
  from valyu import Valyu

  valyu = Valyu("your-api-key-here")
  response = valyu.search(
      "artificial intelligence ethics",
      start_date="2023-01-01",
      end_date="2023-12-31"  # All of 2023
  )
  ```

  ```javascript TypeScript theme={null}
  import { Valyu } from 'valyu-js';

  const valyu = new Valyu("your-api-key-here");

  const response = await valyu.search(
    "artificial intelligence ethics",
    {
      startDate: '2023-01-01',
      endDate: '2023-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>

### Historical Research

<CodeGroup>
  ```python Python theme={null}
  from valyu import Valyu

  valyu = Valyu("your-api-key-here")
  response = valyu.search(
      "machine learning foundations",
      end_date="2015-12-31"  # Pre-deep learning era
  )
  ```

  ```javascript TypeScript theme={null}
  import { Valyu } from 'valyu-js';

  const valyu = new Valyu("your-api-key-here");

  const response = 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": "machine learning foundations",
      "end_date": "2015-12-31"
    }'
  ```
</CodeGroup>

## Use Cases

### Market Intelligence

<CodeGroup>
  ```python Python theme={null}
  from valyu import Valyu

  valyu = Valyu("your-api-key-here")
  response = valyu.search(
      "cryptocurrency adoption trends Q4 2024",
      start_date="2024-10-01",
      search_type="all",
      max_num_results=10
  )
  ```

  ```javascript TypeScript theme={null}
  import { Valyu } from 'valyu-js';

  const valyu = new Valyu("your-api-key-here");

  const response = await valyu.search(
    "cryptocurrency adoption trends Q4 2024",
    {
      startDate: '2024-10-01',
      searchType: 'all',
      maxNumResults: 10
    }
  );
  ```
</CodeGroup>

### Academic Research

<CodeGroup>
  ```python Python theme={null}
  from valyu import Valyu

  valyu = Valyu("your-api-key-here")
  response = valyu.search(
      "CRISPR gene editing therapeutic applications",
      search_type="proprietary",
      start_date="2023-06-01",
      max_num_results=15
  )
  ```

  ```javascript TypeScript theme={null}
  import { Valyu } from 'valyu-js';

  const valyu = new Valyu("your-api-key-here");

  const response = await valyu.search(
    "CRISPR gene editing therapeutic applications",
    {
      searchType: 'proprietary',
      startDate: '2023-06-01',
      maxNumResults: 15
    }
  );
  ```
</CodeGroup>

### Trend Analysis

<CodeGroup>
  ```python Python theme={null}
  from valyu import Valyu

  valyu = Valyu("your-api-key-here")

  # Early AI era
  early_ai = valyu.search(
      "artificial intelligence capabilities",
      start_date="1980-01-01",
      end_date="2000-12-31"
  )

  # Modern AI era
  modern_ai = valyu.search(
      "artificial intelligence capabilities", 
      start_date="2020-01-01",
      end_date="2024-12-31"
  )
  ```

  ```javascript TypeScript theme={null}
  import { Valyu } from 'valyu-js';

  const valyu = new Valyu("your-api-key-here");

  // Early AI era
  const earlyAi = await valyu.search(
    "artificial intelligence capabilities",
    {
      startDate: '1980-01-01',
      endDate: '2000-12-31'
    }
  );

  // Modern AI era
  const modernAi = await valyu.search(
    "artificial intelligence capabilities",
    {
      startDate: '2020-01-01', 
      endDate: '2024-12-31'
    }
  );
  ```
</CodeGroup>

### Event-Based Research

<CodeGroup>
  ```python Python theme={null}
  from valyu import Valyu

  valyu = Valyu("your-api-key-here")
  response = valyu.search(
      "remote work productivity studies",
      start_date="2020-03-01",
      end_date="2022-12-31",  # Pandemic era
      search_type="all",
      max_num_results=20
  )
  ```

  ```javascript TypeScript theme={null}
  import { Valyu } from 'valyu-js';

  const valyu = new Valyu("your-api-key-here");

  const response = await valyu.search(
    "remote work productivity studies",
    {
      startDate: '2020-03-01',
      endDate: '2022-12-31',
      searchType: 'all',
      maxNumResults: 20
    }
  );
  ```
</CodeGroup>

## Best Practices

<Tip>
  More specific date ranges typically improve response times and result relevance.
</Tip>

### Recommended Ranges

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