Filter by Handles and Dates on X

Target your X searches precisely

X Search delivers real value once you master its filtering parameters. Instead of pulling a raw feed of posts, you can target specific accounts, set precise time windows, and exclude sources of noise. These filters transform a general-purpose search tool into a precision monitoring instrument.

Filter by handles: allowed_x_handles and excluded_x_handles

Monitor specific accounts

The allowed_x_handles parameter restricts the search to posts published by the accounts you list. You can target up to 10 handles simultaneously:

response = client.responses.create(
    model="grok-4.5",
    input="Summary of recent announcements from these tech accounts",
    tools=[{
        "type": "x_search",
        "allowed_x_handles": [
            "elonmusk",
            "sama",
            "demishassabis",
            "ylecun"
        ]
    }]
)

Exclude noisy accounts

The excluded_x_handles parameter works in reverse. It allows all accounts except those you specify. Useful for eliminating bots or accounts with irrelevant content:

response = client.responses.create(
    model="grok-4.5",
    input="Serious discussions on AI regulation",
    tools=[{
        "type": "x_search",
        "excluded_x_handles": ["bot_spam_1", "compte_parodie"]
    }]
)

Mutual exclusivity rule

Like web domains, allowed_x_handles and excluded_x_handles are mutually exclusive. You cannot combine them in a single call. The limit is 10 handles per parameter, double the limit for web domains.

Filter by dates: from_date and to_date

Time parameters let you define a precise search window in ISO 8601 format (YYYY-MM-DD):

response = client.responses.create(
    model="grok-4.5",
    input="Reactions to the Grok 4.5 announcement",
    tools=[{
        "type": "x_search",
        "from_date": "2026-03-01",
        "to_date": "2026-03-15"
    }]
)

These filters are particularly useful for:

• Analyze the impact of an event: define the period around the event
• Compare sentiment before/after: run two queries with different windows
• Avoid older noise: focus on recent discussions

Usage with the native Python SDK

The xAI SDK accepts Python datetime objects in addition to ISO strings:

from xai_sdk.tools import x_search
from datetime import datetime

response = client.chat.create(
    model="grok-4.5",
    tools=[x_search(
        from_date=datetime(2026, 3, 1),
        to_date=datetime(2026, 3, 31)
    )]
)

camelCase convention in JavaScript

The Vercel AI SDK uses the camelCase convention for parameter names:

tools: [xai.tools.xSearch({
  allowedXHandles: ["elonmusk"],
  fromDate: "2026-03-01",
  toDate: "2026-03-31"
})]

Combining filters

You can combine handles and dates in a single call for maximum precision:

response = client.responses.create(
    model="grok-4.5",
    input="What did Sam Altman say about GPT-5 in March 2026?",
    tools=[{
        "type": "x_search",
        "allowed_x_handles": ["sama"],
        "from_date": "2026-03-01",
        "to_date": "2026-03-31"
    }]
)

Build a dynamic monitoring system

By combining these filters programmatically, you can build a configurable monitoring tool:

def create_x_monitor(handles, days_back=7):
    from datetime import datetime, timedelta
    today = datetime.now()
    start = (today - timedelta(days=days_back)).strftime("%Y-%m-%d")

    return {
        "type": "x_search",
        "allowed_x_handles": handles,
        "from_date": start,
        "to_date": today.strftime("%Y-%m-%d")
    }

# Monitor AI leaders for the week
tool = create_x_monitor(
    handles=["sama", "demishassabis", "ylecun"],
    days_back=7
)

Practice

Configure a targeted X search for 3 to 5 influential accounts in your sector. Set a one-week time window and compare the results with a search without handle filters. Measure the difference in relevance.

Key takeaways

• allowed_x_handles and excluded_x_handles filter by account (10 max each)
• Both handle parameters are mutually exclusive
• from_date and to_date define the time window in YYYY-MM-DD format
• Dates are combinable with handle filters
• The Python SDK accepts datetime objects, the JavaScript SDK uses camelCase
• These filters transform X Search from a general-purpose tool into a targeted monitoring instrument