Python SDKAPI ReferenceComponents

WebSearchServerToolConfig - Python SDK

WebSearchServerToolConfig method reference

The Python SDK and docs are currently in beta. Report issues on GitHub.

Configuration for the openrouter:web_search server tool

Fields

FieldTypeRequiredDescriptionExample
allowed_domainsList[str]➖Limit search results to these domains. Supported by Exa, Firecrawl, Parallel, and most native providers (Anthropic, OpenAI, xAI). Not supported with Perplexity. Cannot be used with excluded_domains.
engineOptional[components.WebSearchEngineEnum]➖Which search engine to use. “auto” (default) uses native if the provider supports it, otherwise Exa. “native” forces the provider’s built-in search. “exa” forces the Exa search API. “firecrawl” uses Firecrawl (requires BYOK). “parallel” uses the Parallel search API.auto
excluded_domainsList[str]➖Exclude search results from these domains. Supported by Exa, Firecrawl, Parallel, Anthropic, and xAI. Not supported with OpenAI (silently ignored) or Perplexity. Cannot be used with allowed_domains.
max_charactersOptional[int]➖Exact maximum number of characters of content per search result. Applies to the Exa and Parallel engines; ignored with native provider search and Firecrawl. For Exa, caps highlight content per result. For Parallel, caps excerpt content per result (default 1,500 when omitted). When both max_characters and search_context_size are set, max_characters takes precedence for both engines. When omitted, falls back to search_context_size mapping (Exa) or engine defaults (Parallel).2000
max_resultsOptional[int]➖Maximum number of search results to return per search call. Defaults to 5. Applies to Exa, Firecrawl, and Parallel engines; ignored with native provider search.5
max_total_resultsOptional[int]➖Maximum total number of search results across all search calls in a single request. Once this limit is reached, the tool will stop returning new results. Useful for controlling cost and context size in agentic loops. Defaults to 50 when not specified.50
search_context_sizeOptional[components.SearchQualityLevel]➖How much context to retrieve per result. Applies to Exa and Parallel engines; ignored with native provider search and Firecrawl. For Exa, pins a fixed per-result character cap (low=5,000, medium=15,000, high=30,000); when omitted, Exa picks an adaptive size per query and document (typically ~2,000–4,000 characters per result). For Parallel, controls the total characters across all results; when omitted, Parallel uses its own default size. Overridden by max_characters when both are set.medium
user_locationOptional[components.WebSearchUserLocationServerTool]➖Approximate user location for location-biased results.{"city": "San Francisco","country": "US","region": "California","timezone": "America/Los_Angeles","type": "approximate"}