Python SDKAPI ReferenceComponents

ChatWebSearchShorthand - Python SDK

ChatWebSearchShorthand method reference

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

Web search tool using OpenAI Responses API syntax. Automatically converted to openrouter:web_search.

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_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
parametersOptional[components.WebSearchConfig]➖N/A{"max_results": 5,"search_context_size": "medium"}
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.medium
typecomponents.ChatWebSearchShorthandType✔️N/A
user_locationOptional[components.WebSearchUserLocationServerTool]➖Approximate user location for location-biased results.{"city": "San Francisco","country": "US","region": "California","timezone": "America/Los_Angeles","type": "approximate"}