--- 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. - `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. - `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. - `processor` 'base' | 'pro', nullable — DEPRECATED: use `mode` instead. - `max_results` integer, nullable — Upper bound on the number of results to return. Defaults to 10 if not provided. - `max_chars_per_result` integer, nullable — DEPRECATED: Use `excerpts.max_chars_per_result` instead. - `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. - `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. This overall limit applies in addition to max_chars_per_result. - `location` string, nullable — ISO 3166-1 alpha-2 country code for geo-targeted search results. - `source_policy` SourcePolicy — Source policy for web search results. This policy governs which sources are allowed/disallowed in results. - `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. - `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. - `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). - `fetch_policy` FetchPolicy — Policy for live fetching web results. - `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. - `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. - `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. - `client_model` string, nullable — The model generating this request and consuming the results. Enables optimizations and tailors default settings for the model's capabilities. ## Response `200` Successful Response - SearchResponse — Output for the Search API. - `search_id` string, required — Search ID. Example: `search_cad0a6d2dec046bd95ae900527d880e7` - `results` WebSearchResult[], required — A list of WebSearchResult objects, ordered by decreasing relevance. - `url` string, required — URL associated with the search result. - `title` string, nullable — Title of the webpage, if available. - `publish_date` string, nullable — Publish date of the webpage in YYYY-MM-DD format, if available. - `excerpts` string[], nullable — Relevant excerpted content from the URL, formatted as markdown. - `warnings` Warning[], nullable — Warnings for the search request, if any. - `type` 'spec_validation_warning' | 'input_validation_warning' | 'warning', required — Type of warning. Note that adding new warning types is considered a backward-compatible change. - `message` string, required — Human-readable message. - `detail` object, nullable — Optional detail supporting the warning. - `usage` UsageItem[], nullable — Usage metrics for the search request. - `name` string, required — Name of the SKU. - `count` integer, required — Count of the SKU. ## Other responses - `422` — Request validation error ## Changes - **2026-04-22** `66ee13c3475d` — 1 info - added the new optional request property `client_model` - **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 [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/1595294c8795/schema)