--- title: "Search" method: POST path: "/v1beta/search" tags: ["Search (Beta)"] --- # Search `POST /v1beta/search` Searches the web. ## Headers - `parallel-beta` string, nullable ## Request body - SearchRequest — Request to Search API. - `excerpts` ExcerptSettings — Optional settings for returning relevant excerpts. - `max_chars_per_result` integer, nullable — Optional upper bound on the total number of characters to include per url. Excerpts may contain fewer characters than this limit to maximize relevance and token efficiency. Values below 1000 will be automatically set to 1000. - `max_chars_total` integer, nullable — Optional upper bound on the total number of characters to include across all urls. Results may contain fewer characters than this limit to maximize relevance and token efficiency. Values below 1000 will be automatically set to 1000. This overall limit applies in addition to max_chars_per_result. - `fetch_policy` FetchPolicy — Policy for live fetching web results. - `disable_cache_fallback` boolean — If false, fallback to cached content older than max-age if live fetch fails or times out. If true, returns an error instead. - `max_age_seconds` integer, nullable — Maximum age of cached content in seconds to trigger a live fetch. Minimum value 600 seconds (10 minutes). - `timeout_seconds` number, nullable — Timeout in seconds for fetching live content if unavailable in cache. - `location` string, nullable — ISO 3166-1 alpha-2 country code for geo-targeted search results. - `max_chars_per_result` integer, nullable — DEPRECATED: Use `excerpts.max_chars_per_result` instead. - `max_results` integer, nullable — Upper bound on the number of results to return. Defaults to 10 if not provided. - `mode` 'one-shot' | 'agentic' | 'fast', nullable — Presets default values for parameters for different use cases. - `one-shot` returns more comprehensive results and longer excerpts to answer questions from a single response - `agentic` returns more concise, token-efficient results for use in an agentic loop - `fast` trades some quality for lower latency, with best results when used with concise and high-quality objective and keyword queries - `objective` string, nullable — Natural-language description of what the web search is trying to find. May include guidance about preferred sources or freshness. At least one of objective or search_queries must be provided. - `processor` 'base' | 'pro', nullable — DEPRECATED: use `mode` instead. - `search_queries` string[], nullable — Optional list of traditional keyword search queries to guide the search. May contain search operators. At least one of objective or search_queries must be provided. - `session_id` string, nullable — Session identifier to track calls across separate search and extract calls, to be used as part of a larger task. Specifying it may give better contextual results for subsequent API calls. - `source_policy` SourcePolicy — Source policy for web search results. This policy governs which sources are allowed/disallowed in results. - `after_date` string, date, nullable — Optional start date for filtering search results. Results will be limited to content published on or after this date. Provided as an RFC 3339 date string (YYYY-MM-DD). - `exclude_domains` string[] — List of domains to exclude from results. If specified, sources from these domains will be excluded. Accepts plain domains (e.g., example.com, subdomain.example.gov) or bare domain extension starting with a period (e.g., .gov, .edu, .co.uk). The combined number of domains in include_domains and exclude_domains cannot exceed 200. - `include_domains` string[] — List of domains to restrict the results to. If specified, only sources from these domains will be included. Accepts plain domains (e.g., example.com, subdomain.example.gov) or bare domain extension starting with a period (e.g., .gov, .edu, .co.uk). The combined number of domains in include_domains and exclude_domains cannot exceed 200. ## Response `200` Successful Response - SearchResponse — Output for the Search API. - `results` WebSearchResult[], required — A list of WebSearchResult objects, ordered by decreasing relevance. - `excerpts` string[], nullable — Relevant excerpted content from the URL, formatted as markdown. - `publish_date` string, nullable — Publish date of the webpage in YYYY-MM-DD format, if available. - `title` string, nullable — Title of the webpage, if available. - `url` string, required — URL associated with the search result. - `search_id` string, required — Search ID. Example: `search_cad0a6d2dec046bd95ae900527d880e7` - `usage` UsageItem[], nullable — Usage metrics for the search request. - `count` integer, required — Count of the SKU. - `name` string, required — Name of the SKU. - `warnings` Warning[], nullable — Warnings for the search request, if any. - `detail` object, nullable — Optional detail supporting the warning. - `message` string, required — Human-readable message. - `type` 'spec_validation_warning' | 'input_validation_warning' | 'warning', required — Type of warning. Note that adding new warning types is considered a backward-compatible change. ## Other responses - `422` — Request validation error ## Changes - **2026-04-21** `57e1c56be094` — 2 info - added the new optional request property `location` - added the new optional request property `session_id` - **2026-03-09** `970b780e8649` — 3 info - `header` request parameter `parallel-beta` was deprecated - the `max_results` request property default value `10` was removed - added the new `fast` enum value to the request property `mode/anyOf[subschema #1]/` - **2026-01-13** `105d778ad64d` — 2 breaking, 1 warning, 8 info - the `excerpts` request property type/format changed from ``/`` to `object`/`` - the `error` response's property type/format changed from ``/`` to `object`/`` for status `422` - removed `#/components/schemas/ExcerptSettings` from the `excerpts` request property `allOf` list - added the new optional request property `excerpts/max_chars_per_result` - …7 more - **2025-11-06** `a2d634b57a8e` — 4 breaking, 10 info - the response property `results/items/excerpts` became optional for the status `200` - the response property `results/items/title` became optional for the status `200` - response property `results/items/excerpts` list-of-types was widened by adding types `null` to media type `application/json` of response `200` - response property `results/items/title` list-of-types was widened by adding types `null` to media type `application/json` of response `200` - …10 more - …earlier changes not shown [Full history](https://skmtc.dev/parallel-web/apis/parallel-api/changes/v1beta/search/post.md) --- [API](https://skmtc.dev/parallel-web/apis/parallel-api.md) · [All operations](https://skmtc.dev/parallel-web/apis/parallel-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/parallel-web/parallel-api/revisions/57e1c56be094/schema)