---
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 — Base class for search queries.
  - `max_chars_per_result` integer, nullable — DEPRECATED: Use `excerpts.max_chars_per_result` instead.
  - `processor` 'base' | 'pro', nullable — DEPRECATED: use `mode` 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.
  - `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_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.
  - `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.
    - `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

- **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
- **2025-08-31** `1aeb1c81a849` — 1 info
  - endpoint added

[Change 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/a2d634b57a8e/schema)