Domain Filtering — Integrated Tools: Web, X, Code

Control search sources

By default, Web Search explores the entire web. This works well for general queries, but it often falls short for professional use cases where you need reliable, controlled sources. Domain filtering lets you restrict or exclude specific sites.

Two mutually exclusive parameters

Web Search offers two filtering parameters:

allowed_domains: restricts search to specified domains (allowlist)
excluded_domains: excludes specific domains from results (blocklist)

These two parameters are mutually exclusive. You can’t use both in the same request. If you try, the API returns an error.

Each parameter accepts an array of up to 5 domains.

Use allowed_domains (allowlist)

Use this parameter when you know exactly which sources you want to consult. For example, for academic research:

response = client.responses.create(
    model="grok-4.20-0309-reasoning",
    input="What are the latest publications on transformers?",
    tools=[{
        "type": "web_search",
        "allowed_domains": ["arxiv.org", "nature.com", "science.org"]
    }]
)

The model searches only these three domains. This ensures results come from verified scientific sources.

Allowlist use cases

Academic research: limit to arxiv.org, scholar.google.com, nature.com
Technical documentation: limit to official technology sites
Competitive intelligence: limit to competitor sites
Regulatory compliance: limit to government or regulatory sources

Use excluded_domains (blocklist)

Use this parameter when you want a broad search but need to exclude unreliable or irrelevant sources:

response = client.responses.create(
    model="grok-4.20-0309-reasoning",
    input="What are the best JavaScript frameworks in 2026?",
    tools=[{
        "type": "web_search",
        "excluded_domains": ["reddit.com", "quora.com"]
    }]
)

The model searches the entire web except for the excluded domains.

Blocklist use cases

Exclude forums: avoid unverified opinions
Exclude aggregators: avoid duplicate content
Exclude competitors: keep their content out of your results
Exclude paywalls: avoid sites with inaccessible content

SDK syntax

xAI SDK

tools=[client.tools.web_search(
    allowed_domains=["arxiv.org", "nature.com"]
)]

OpenAI SDK

tools=[{
    "type": "web_search",
    "excluded_domains": ["reddit.com"]
}]

Vercel AI SDK

tools: [xai.tools.webSearch({
  allowedDomains: ["arxiv.org", "nature.com"]
})]

Note the camelCase convention (allowedDomains) in the JavaScript SDK.

Limits and best practices

The 5-domain limit might seem restrictive. In practice, it forces you to be selective about sources, which improves result quality. If you need more flexibility, you can run multiple requests with different domains and aggregate the results on the client side.

When using allowed_domains, ensure the chosen domains cover the requested topic. A domain that’s too restrictive might prevent the model from finding relevant information, which could lead it to respond without up-to-date data.

Key takeaways

Two parameters available: allowed_domains (allowlist) and excluded_domains (blocklist)
Mutually exclusive: you can’t combine them in the same request
Maximum 5 domains per parameter
Allowlist is ideal for controlled, reliable sources
Blocklist works for broad searches with a few exclusions