Filtering by X Handles

Target specific accounts on X

Just as Web Search lets you filter by domains, X Search lets you filter by accounts (handles). You can restrict searches to posts from a specific set of accounts, or exclude certain accounts from results. This filtering is essential for use cases like monitoring, brand tracking, or influencer analysis.

The two filtering parameters

X Search offers two handle filtering parameters:

• allowed_x_handles: limits the search to posts from the listed accounts (allowlist)
• excluded_x_handles: excludes posts from the listed accounts (blocklist)

Like Web Search, these parameters are mutually exclusive. You cannot use both in the same request.

Each parameter accepts an array of up to 10 handles (compared to 5 domains for Web Search).

Using allowed_x_handles (allowlist)

This parameter is ideal for monitoring communications from specific accounts:

response = client.responses.create(
    model="grok-4.20-0309-reasoning",
    input="What are the latest announcements from xAI?",
    tools=[{
        "type": "x_search",
        "allowed_x_handles": ["xaboratory", "xaboratorydev"]
    }]
)

The model will only search for posts published by these accounts.

Allowlist use cases

• Competitive intelligence: monitor your competitors’ announcements
• Brand monitoring: track your official accounts and those of your ambassadors
• Influencer analysis: aggregate opinions from a panel of experts
• Institutional tracking: follow accounts from regulators or official organizations

Using excluded_x_handles (blocklist)

This parameter lets you exclude certain accounts, such as bots or irrelevant accounts:

response = client.responses.create(
    model="grok-4.20-0309-reasoning",
    input="What do developers think about the latest version of Python?",
    tools=[{
        "type": "x_search",
        "excluded_x_handles": ["bot_python_news", "spam_account"]
    }]
)

Blocklist use cases

• Exclude bots: remove automated accounts from results
• Exclude spam: filter out accounts known for low-quality content
• Exclude your own accounts: analyze external reactions without your own posts

SDK Syntax

xAI SDK (Python)

from xai_sdk.tools import x_search

tools=[x_search(
    allowed_x_handles=["elonmusk", "xaboratory"]
)]

OpenAI SDK (Python)

tools=[{
    "type": "x_search",
    "allowed_x_handles": ["elonmusk", "xaboratory"]
}]

Vercel AI SDK (JavaScript)

tools: [xai.tools.xSearch({
  allowedXHandles: ["elonmusk", "xaboratory"]
})]

Note the camelCase convention in the JavaScript SDK: allowedXHandles instead of allowed_x_handles.

Best practices

Choosing between allowlist and blocklist

Use the allowlist when you have a defined set of accounts and only want their posts. This is the most precise and token-efficient method.

Use the blocklist when you want a broad search but need to clean it up by eliminating known noise sources.

Optimizing the number of handles

With a limit of 10 handles, be selective. If you need to monitor more than 10 accounts, group your requests by topic or make multiple sequential calls.

Handle format

Handles do not include the @ symbol (for example, xaboratory). Verify that the handles are correct—a misspelled handle will simply return no results for that account.

Key takeaways

• Two parameters: allowed_x_handles (allowlist) and excluded_x_handles (blocklist)
• Mutually exclusive: only one at a time per request
• Maximum 10 handles per parameter
• Handles are written without the @: "elonmusk", not "@elonmusk"
• Ideal for monitoring, brand tracking, and influencer analysis