> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://openrouter.ai/docs/llms.txt.
> For full documentation content, see https://openrouter.ai/docs/llms-full.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://openrouter.ai/docs/_mcp/server.

# WebSearchConfig - Python SDK

The Python SDK and docs are currently in beta.
Report issues on [GitHub](https://github.com/OpenRouterTeam/python-sdk/issues).

## Fields

| Field                 | Type                                                                                                       | Required             | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Example                                                                                                                    |
| --------------------- | ---------------------------------------------------------------------------------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `allowed_domains`     | List\[*str*]                                                                                               | :heavy\_minus\_sign: | 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\]](../components/websearchengineenum.md)                         | :heavy\_minus\_sign: | 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*]                                                                                               | :heavy\_minus\_sign: | 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_characters`      | *Optional\[int]*                                                                                           | :heavy\_minus\_sign: | 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_results`         | *Optional\[int]*                                                                                           | :heavy\_minus\_sign: | 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]*                                                                                           | :heavy\_minus\_sign: | 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\]](../components/searchqualitylevel.md)                           | :heavy\_minus\_sign: | 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_location`       | [Optional\[components.WebSearchUserLocationServerTool\]](../components/websearchuserlocationservertool.md) | :heavy\_minus\_sign: | Approximate user location for location-biased results.                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `{"city": "San Francisco","country": "US","region": "California","timezone": "America/Los_Angeles","type": "approximate"}` |