Python SDKAPI ReferenceComponents
WebSearchServerToolConfig - Python SDK
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
| Field | Type | Required | Description | Example |
|---|---|---|---|---|
allowed_domains | List[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. | |
engine | Optional[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_domains | List[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_results | Optional[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_results | Optional[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_size | Optional[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. | medium |
user_location | Optional[components.WebSearchUserLocationServerTool] | ➖ | Approximate user location for location-biased results. | {"city": "San Francisco","country": "US","region": "California","timezone": "America/Los_Angeles","type": "approximate"} |