# Date\_Filtering\_Guide

## Purpose

Use this guide to set date filters correctly in GovTribe `Search_*` tools using plain dates or Elasticsearch date math. Use it when:

* users ask for time-bounded results such as last 30 days or due next week.
* setting any `*_date_range` field in a request payload.
* building broad award/IDV horizon scans that should be aggregation-first.

## Construction Rules

### Range Object Shape

* Date range objects should include both keys:
  * `from`
  * `to`
* If one side is open-ended, keep the key and set it to `null`.

### Supported Date Values

* Use one of these value styles:
  * plain date values (example `2026-03-02`)
  * Elasticsearch date math (example `now-90d/d`, `2026-01-01||+1M/d`)
* Use fixed dates when reproducibility matters.

### Field Selection Guide

* Use the date field that matches user intent:
  * `award_date_range`: award issue date.
  * `posted_date`: posting date.
  * `due_date_range`: response deadline.
  * `ultimate_completion_date_range`: completion horizon.
  * `last_date_to_order_range`: IDV ordering deadline.
  * `estimated_solicitation_release_date_range`: forecasted release timing.
  * `anticipated_award_start_date_range`: forecasted start timing.
* For broad award/IDV horizon scans, pair date windows with `aggregations` first.

## Examples

Rolling 90-day federal award scan (agg-first): Tool: `Search_Federal_Contract_Awards`

```json
{
  "award_date_range": {
    "from": "now-90d/d",
    "to": "now/d"
  },
  "aggregations": ["top_awardees_by_dollars_obligated"]
}
```

Open-ended posted-date filter: Tool: `Search_Federal_Contract_Opportunities`

```json
{
  "posted_date": {
    "from": "2026-01-01",
    "to": null
  }
}
```

Future due-date window: Tool: `Search_Federal_Contract_Opportunities`

```json
{
  "due_date_range": {
    "from": "now/d",
    "to": "now+30d/d"
  }
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.govtribe.com/user-guide/mcp/guides/date_filtering_guide.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.