Date Filtering

Define the search time window

X Search offers a feature Web Search doesn’t have: date filtering. You can define a specific period to limit results to posts published within that time window. This is a powerful tool for trend analysis, event tracking, and targeted monitoring.

Date parameters

Two parameters control the time window:

• from_date: search start date (inclusive)
• to_date: search end date (inclusive)

Both are optional and independent. You can use one without the other:

• from_date only: all posts since this date
• to_date only: all posts up to this date
• Both together: posts within the defined window

Date format

Dates follow the ISO 8601 format: YYYY-MM-DD (year-month-day).

response = client.responses.create(
    model="grok-4.20-0309-reasoning",
    input="What were the reactions to the Grok 4 launch?",
    tools=[{
        "type": "x_search",
        "from_date": "2026-03-01",
        "to_date": "2026-03-31"
    }]
)

This query searches only for posts published in March 2026.

SDK syntax

xAI SDK (Python)

The Python SDK accepts both strings and datetime objects:

from xai_sdk.tools import x_search
import datetime

# Using strings
tools=[x_search(
    from_date="2026-01-01",
    to_date="2026-04-01"
)]

# Using datetime objects
tools=[x_search(
    from_date=datetime.datetime(2026, 1, 1),
    to_date=datetime.datetime(2026, 4, 1)
)]

Using datetime objects is preferred in production because it allows you to calculate dates dynamically (for example, “the last 7 days”).

OpenAI SDK (Python)

tools=[{
    "type": "x_search",
    "from_date": "2026-01-01",
    "to_date": "2026-04-01"
}]

Vercel AI SDK (JavaScript)

tools: [xai.tools.xSearch({
  fromDate: "2026-01-01",
  toDate: "2026-04-01"
})]

camelCase convention: fromDate and toDate.

Combine dates and handles

Combining time filtering with handle filtering is particularly powerful:

response = client.responses.create(
    model="grok-4.20-0309-reasoning",
    input="Summarize xAI's announcements this month",
    tools=[{
        "type": "x_search",
        "allowed_x_handles": ["xaboratory", "xaboratorydev"],
        "from_date": "2026-04-01",
        "to_date": "2026-04-30"
    }]
)

This query combines three filters: only posts from official xAI accounts, only in April 2026.

Use cases

Event analysis

Track reactions in real time during an event (conference, product launch, announcement):

# Reactions during a keynote
tools=[{
    "type": "x_search",
    "from_date": "2026-03-25",
    "to_date": "2026-03-26"
}]

Automated weekly monitoring

Create an automatic monitoring report for the past week:

from datetime import datetime, timedelta

today = datetime.now()
week_ago = today - timedelta(days=7)

tools=[{
    "type": "x_search",
    "from_date": week_ago.strftime("%Y-%m-%d"),
    "to_date": today.strftime("%Y-%m-%d")
}]

Trend analysis

Compare discussions around a topic at different periods by making multiple requests with distinct time windows.

Best practices

Experience shows shorter windows work best: a one-to-seven-day period yields significantly more precise results than an entire month, where significant posts get lost in the volume. In production, never hardcode these dates—calculate them with datetime on every run. Otherwise, your “7-day monitoring” window will query the same week forever from deployment. Finally, the time window only defines the result set: the prompt dictates what to do with it. Specify what you expect—“trend summary”, “most engaged posts”, “major announcements”—and the model will filter results accordingly instead of returning everything.

Key takeaways

• from_date and to_date in ISO 8601 format (YYYY-MM-DD)
• Both parameters are optional and independent
• Combine with handle filtering for highly targeted searches
• Python SDK accepts both strings and datetime objects
• X Search exclusive—Web Search doesn’t offer time filtering