Filter Web Search Domains

Control Sources for Reliable Results

When you integrate web search into a business application, you don’t want the model pulling information from just anywhere. A legal chatbot needs to consult official sources, a medical assistant must stick to scientific publications, and a technology monitoring tool should target reference sites.

The Grok API offers two filtering parameters to control sources: allowed_domains and excluded_domains. These parameters give you granular control over the search scope.

The Two Filtering Modes

Allowlist: `allowed_domains`

This parameter restricts search to only the domains you specify. The model won’t consult any other sites:

response = client.responses.create(
    model="grok-4.5",
    input="What are the latest advancements in AI?",
    tools=[{
        "type": "web_search",
        "allowed_domains": ["arxiv.org", "nature.com", "science.org"]
    }]
)

Exclude List: `excluded_domains`

This parameter allows all sources except those you list. Useful for excluding unreliable sites or competitors:

response = client.responses.create(
    model="grok-4.5",
    input="SaaS market analysis in France",
    tools=[{
        "type": "web_search",
        "excluded_domains": ["reddit.com", "quora.com"]
    }]
)

The Mutual Exclusivity Rule

The allowed_domains and excluded_domains parameters are mutually exclusive. You cannot use both at the same time in a single call. If you try to combine them, the API will return an error.

Choose your strategy based on the use case:

Allowlist (allowed_domains): when you know precisely which sources are reliable and everything else is suspect
Exclude list (excluded_domains): when most sources are acceptable but a few pose problems

Five-Domain Limit

Each parameter accepts a maximum of 5 domains. This constraint forces you to prioritize your sources. If you need to cover more sites, consider making multiple calls with different lists, or use the exclude list to block the few problematic domains.

Domain Syntax

Specify domains without a protocol or trailing slash:

# Correct
"allowed_domains": ["arxiv.org", "nature.com"]

# Incorrect
"allowed_domains": ["https://arxiv.org/", "www.nature.com"]

Practical Use Cases

Scientific Research Assistant

tools=[{
    "type": "web_search",
    "allowed_domains": [
        "arxiv.org",
        "pubmed.ncbi.nlm.nih.gov",
        "scholar.google.com",
        "nature.com",
        "science.org"
    ]
}]

European Regulatory Monitoring

tools=[{
    "type": "web_search",
    "allowed_domains": [
        "eur-lex.europa.eu",
        "legifrance.gouv.fr",
        "cnil.fr",
        "ec.europa.eu"
    ]
}]

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

Dynamic Filtering Strategy

In a real application, you can adapt filtering based on the context of the user’s request:

def get_search_config(category):
    configs = {
        "legal": {
            "allowed_domains": ["legifrance.gouv.fr", "eur-lex.europa.eu"]
        },
        "tech": {
            "excluded_domains": ["pinterest.com", "quora.com"]
        },
        "general": {}
    }
    return configs.get(category, {})

search_params = get_search_config(user_category)
tools = [{"type": "web_search", **search_params}]

Hands-On Practice

Create an assistant specialized in a domain of your choice (legal, scientific, technological). Configure the appropriate domain filtering and test it with several questions. Compare the results obtained with and without filtering to measure the impact on response relevance.

Key Takeaways

allowed_domains restricts search to an allowlist of sites
excluded_domains excludes specific sites from search
Both parameters are mutually exclusive: only one per call
Maximum 5 domains per parameter
Specify domains without a protocol (arxiv.org, not https://arxiv.org)
Adapt the strategy to the use case: allowlist for sensitive domains, exclude list for light filtering