--- title: "Search" method: POST path: "/v1beta/search" tags: ["Search (Beta)"] --- # Search `POST /v1beta/search` Searches the web. To access this endpoint, pass the `parallel-beta` header with the value `search-extract-2025-10-10`. ## 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, but will never contain fewer than 1000 characters per result. - `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, but will never contain fewer than 1000 characters per result.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. - `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. May be limited by the processor. Defaults to 10 if not provided. - `mode` 'one-shot' | 'agentic', 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, while `agentic` returns more concise, token-efficient results for use in an agentic loop. - `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. - `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). - `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). ## 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-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 - **2025-10-21** `e853fc79f3b4` — 2 breaking, 5 info - removed the enum value `base` of the request property `processor` - removed the enum value `pro` of the request property `processor` - api tag `Search and Extract API (Beta)` added - api tag `Search API` removed - …3 more - **2025-08-31** `1aeb1c81a849` — 1 info - endpoint added - **2025-08-31** `ff0d5939e135` — 1 breaking - api path removed without deprecation [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/105d778ad64d/schema)