xai-x-search

xAI X (Twitter) Search

Real-time Twitter/X search using Grok's native X integration - a capability unique to xAI.

Quick Start

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("XAI_API_KEY"),
    base_url="https://api.x.ai/v1"
)

# Simple X search
response = client.chat.completions.create(
    model="grok-4-1-fast",
    messages=[{
        "role": "user",
        "content": "Search X for what people are saying about Tesla stock today"
    }]
)
print(response.choices[0].message.content)

Search Capabilities

1. Topic Search

def search_x_topic(topic: str) -> str:
    """Search X for posts about a topic."""
    response = client.chat.completions.create(
        model="grok-4-1-fast",
        messages=[{
            "role": "user",
            "content": f"Search X for recent posts about {topic}. Summarize the main discussions and sentiment."
        }]
    )
    return response.choices[0].message.content

2. Ticker/Stock Search

def search_stock_mentions(ticker: str) -> str:
    """Search X for stock ticker mentions."""
    response = client.chat.completions.create(
        model="grok-4-1-fast",
        messages=[{
            "role": "user",
            "content": f"""Search X for mentions of ${ticker} stock.
            Find:
            - Recent discussions
            - Sentiment (bullish/bearish)
            - Key influencer opinions
            - Breaking news mentions
            Return structured analysis."""
        }]
    )
    return response.choices[0].message.content

3. Account Monitoring

def monitor_account(handle: str) -> str:
    """Get recent posts from a specific X account."""
    response = client.chat.completions.create(
        model="grok-4-1-fast",
        messages=[{
            "role": "user",
            "content": f"Search X for the most recent posts from @{handle}. Summarize their latest activity."
        }]
    )
    return response.choices[0].message.content

4. Trending Topics

def get_trending() -> str:
    """Get current trending topics on X."""
    response = client.chat.completions.create(
        model="grok-4-1-fast",
        messages=[{
            "role": "user",
            "content": "What are the current trending topics on X? List the top 10 with brief descriptions."
        }]
    )
    return response.choices[0].message.content

Agent Tools API (Advanced)

For more control, use the Agent Tools API:

# Using Responses API with x_search tool
response = client.chat.completions.create(
    model="grok-4-1-fast",
    messages=[{
        "role": "user",
        "content": "Search X for posts about Bitcoin from the last 24 hours"
    }],
    tools=[{
        "type": "x_search",
        "x_search": {
            "enabled": True,
            "date_range": {
                "start": "2025-12-04",
                "end": "2025-12-05"
            }
        }
    }]
)

Filter by Handles

# Search only specific accounts
response = client.chat.completions.create(
    model="grok-4-1-fast",
    messages=[{
        "role": "user",
        "content": "What are these financial analysts saying about the market?"
    }],
    tools=[{
        "type": "x_search",
        "x_search": {
            "enabled": True,
            "allowed_x_handles": [
                "jimcramer",
                "elonmusk",
                "chaikinadx",
                "unusual_whales"
            ]
        }
    }]
)

Common Use Cases

Financial News Monitoring

def monitor_financial_news() -> dict:
    """Monitor financial news on X."""
    response = client.chat.completions.create(
        model="grok-4-1-fast",
        messages=[{
            "role": "user",
            "content": """Search X for breaking financial news in the last hour.
            Focus on:
            - Market-moving news
            - Earnings announcements
            - Fed/economic news
            - Major analyst calls

            Return as JSON:
            {
                "breaking_news": [...],
                "market_sentiment": "bullish/bearish/neutral",
                "key_events": [...]
            }"""
        }]
    )
    return response.choices[0].message.content

Earnings Reaction Tracking

def track_earnings_reaction(ticker: str) -> str:
    """Track X reaction to earnings announcement."""
    response = client.chat.completions.create(
        model="grok-4-1-fast",
        messages=[{
            "role": "user",
            "content": f"""Search X for reaction to ${ticker} earnings.
            Analyze:
            - Overall sentiment
            - Key concerns raised
            - Positive highlights mentioned
            - Notable influencer reactions
            - Volume of discussion"""
        }]
    )
    return response.choices[0].message.content

Competitor Analysis

def compare_sentiment(tickers: list) -> str:
    """Compare X sentiment across multiple stocks."""
    ticker_str = ", ".join([f"${t}" for t in tickers])
    response = client.chat.completions.create(
        model="grok-4-1-fast",
        messages=[{
            "role": "user",
            "content": f"""Compare X sentiment for: {ticker_str}
            For each, provide:
            - Current sentiment score (-1 to +1)
            - Key themes being discussed
            - Notable mentions
            Return as structured comparison."""
        }]
    )
    return response.choices[0].message.content

Search Parameters

Parameter	Description	Max
allowed_x_handles	Only search these accounts	10
excluded_x_handles	Exclude these accounts	10
date_range.start	Start date (ISO8601)	-
date_range.end	End date (ISO8601)	-
include_media	Analyze images/videos	-

Rate Limits & Costs

Metric	Value
Cost per search	$0.005 ($5/1,000)
Max handles filter	10
Date range	Any

Best Practices

1. Be Specific

# Bad - too vague
"Search X for stocks"

# Good - specific query
"Search X for posts about $AAPL stock price movement today from verified financial accounts"

2. Request Structured Output

# Request JSON for easier parsing
content = """Search X for $NVDA sentiment. Return JSON:
{
    "sentiment": "bullish/bearish/neutral",
    "score": -1 to 1,
    "key_posts": [...],
    "influencer_opinions": [...]
}"""

3. Use Handle Filters for Quality

# Filter to trusted sources
financial_handles = [
    "DeItaone",  # Breaking news
    "unusual_whales",  # Options flow
    "Fxhedgers",  # Market news
    "zaborsky"  # Analysis
]

4. Combine with Other Data

# Combine X sentiment with price data
x_sentiment = search_stock_mentions("AAPL")
price_data = finnhub_client.get_quote("AAPL")
# Analyze together

Limitations

1. Sarcasm detection - May misinterpret sarcastic posts
2. Bot content - Cannot always filter bot posts
3. Historical depth - Best for recent data
4. Rate limits - $5/1,000 searches

Error Handling

def safe_x_search(query: str) -> dict:
    """X search with error handling."""
    try:
        response = client.chat.completions.create(
            model="grok-4-1-fast",
            messages=[{"role": "user", "content": query}],
            timeout=30
        )
        return {
            "success": True,
            "data": response.choices[0].message.content
        }
    except Exception as e:
        return {
            "success": False,
            "error": str(e)
        }

Related Skills

• xai-sentiment - Sentiment analysis
• xai-stock-sentiment - Stock-specific sentiment
• xai-agent-tools - Advanced tool usage

References

• xAI Live Search
• Agent Tools API