X Search for Marketing: Handles, Dates, and Filters

Turn X into a Marketing Monitoring Tool

X (formerly Twitter) remains one of the richest platforms for actionable marketing data in real time. With the x_search tool in the Grok API, you can query this mass of information in a structured, filtered, and automatable way, directly from your applications or scripts.

Unlike manual search on X, the API lets you target specific accounts, periods, and topics precisely. For a marketing manager, this means moving from artisanal monitoring to a programmable competitive intelligence collection system.

Enable X Search in the Grok API

You enable the x_search tool by declaring it in the tools array of your API request. It works exclusively on the Responses API (the legacy Chat Completions endpoint is deprecated for search).

from openai import OpenAI

client = OpenAI(
    api_key="your-xai-key",
    base_url="https://api.x.ai/v1"
)

response = client.responses.create(
    model="grok-4.20-0309-reasoning",
    input="What are the latest posts from @nike about their marketing campaigns?",
    tools=[{"type": "x_search"}]
)

The model automatically decides when to launch a search on X based on your question. You do not need to manage the triggering manually.

Filter by Handles: Target Specific Accounts

The allowed_x_handles parameter lets you restrict the search to a maximum of 10 specific X accounts. This is the ideal tool for monitoring your direct competitors or partners.

response = client.responses.create(
    model="grok-4.20-0309-reasoning",
    input="Summarize the product announcements from these brands this week",
    tools=[{
        "type": "x_search",
        "allowed_x_handles": [
            "nike", "adidas", "puma",
            "newbalance", "reebok"
        ]
    }]
)

Conversely, excluded_x_handles lets you exclude up to 10 accounts from the results. Note: these two parameters are mutually exclusive (you cannot combine them in the same request).

Marketing Use Cases

• Competitive monitoring: track the 5–10 accounts of your direct competitors
• Partnerships: follow posts from your partners and ambassadors
• Ecosystem: exclude your own accounts to see only the market

Filter by Dates: Isolate a Period

The from_date and to_date parameters accept dates in ISO 8601 format (YYYY-MM-DD). This lets you target a specific campaign, a sector event, or compare two periods.

response = client.responses.create(
    model="grok-4.20-0309-reasoning",
    input="Analyze reactions to the Black Friday campaign from these brands",
    tools=[{
        "type": "x_search",
        "allowed_x_handles": ["amazon_fr", "cdiscount", "fnac"],
        "from_date": "2025-11-25",
        "to_date": "2025-12-02"
    }]
)

This combination of handles + dates gives you an extremely precise search scope, comparable to an automated market research brief.

Understand Post Images and Videos

Two boolean parameters enrich your visual monitoring:

• enable_image_understanding: the model analyzes images contained in posts (campaign visuals, infographics, screenshots)
• enable_video_understanding: the model interprets videos (ad spots, product teasers, demonstrations)

tools=[{
    "type": "x_search",
    "allowed_x_handles": ["apple"],
    "enable_image_understanding": True,
    "enable_video_understanding": True
}]

For a marketer, this means Grok can describe your competitors’ ad visuals, identify color codes used, or summarize the content of a promotional video, all programmatically.

Hands-On: Weekly Monitoring Script

Here is a complete script that generates a weekly monitoring report on your competitors:

from datetime import datetime, timedelta

# Calculate the past week
today = datetime.now().strftime("%Y-%m-%d")
last_week = (datetime.now() - timedelta(days=7)).strftime("%Y-%m-%d")

response = client.responses.create(
    model="grok-4.20-0309-reasoning",
    input="""Analyze these brands' posts from the last week.
    For each brand, identify:
    1. Major product announcements
    2. Marketing campaigns launched
    3. Tone and positioning used
    4. Posts that generated the most engagement""",
    tools=[{
        "type": "x_search",
        "allowed_x_handles": [
            "concurrent1", "concurrent2", "concurrent3"
        ],
        "from_date": last_week,
        "to_date": today,
        "enable_image_understanding": True
    }]
)

print(response.output_text)

Key Takeaways

• X Search costs $5 per 1,000 calls, making it a very affordable monitoring tool
• You can filter by handles (max 10) or dates (ISO 8601 format), or combine both
• allowed_x_handles and excluded_x_handles are mutually exclusive
• Image and video analysis in posts is exclusive to X Search (not available on Web Search)
• Use the Responses API (not Chat Completions, which is deprecated for search)