---
title: "Search"
method: POST
path: "/v1/search"
tags: ["Search"]
---

# Search

`POST /v1/search`

Searches the web.

The legacy Search API reference (`/v1beta/search` endpoint) is available
[here](https://docs.parallel.ai/api-reference/legacy/search-beta/search), and
migration guide is [here](https://docs.parallel.ai/search/search-migration-guide).

## Request body

- V1SearchRequest — Search request.
  - `objective` string, nullable — Natural-language description of the underlying question or goal driving the search. Used together with search_queries to focus results on the most relevant content. Should be self-contained with enough context to understand the intent of the search.
  - `search_queries` string[], required — Concise keyword search queries, 3-6 words each. At least one query is required, provide 2-3 for best results. Used together with objective to focus results on the most relevant content.
  - `mode` 'turbo' | 'fast' | 'basic' | 'advanced', nullable — Search mode preset: supported values are `turbo`, `fast`, `basic`, and `advanced`. Turbo mode is optimized for the fastest responses. Use Fast mode for high quality search within a 1-second latency budget. Basic mode offers low latency and works best with 2-3 high-quality search_queries. Advanced mode provides higher quality with more advanced retrieval and compression. Defaults to `advanced` when omitted.
  - `max_chars_total` integer, nullable — Upper bound on total characters across excerpts from all results.
  - `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.
  - `advanced_settings` AdvancedSearchSettings — Advanced search configuration. These settings may impact result quality and latency unless used carefully. See https://docs.parallel.ai/search/advanced-search-settings for more info.
    - `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.
    - `excerpt_settings` V1ExcerptSettings — 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.
    - `location` string, nullable — ISO 3166-1 alpha-2 country code for geo-targeted search results.
    - `max_results` integer, nullable — Upper bound on the number of results to return. Defaults to 10 if not provided.

## Response `200`

Successful Response

- V1SearchResponse — Search response.
  - `search_id` string, required — Search ID. Example: `search_cad0a6d2dec046bd95ae900527d880e7`
  - `results` V1WebSearchResult[], required — A list of search results, 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[], required — 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.
  - `session_id` string, required — Session identifier, echoed back from the request if provided, otherwise generated by the server. Should be passed to future search and extract calls made by the agent as part of the same larger task.

## Other responses

- `422` — Request validation error

## Changes

- **2026-08-12** `1595294c8795` — 1 info
  - added the new `fast` enum value to the request property `mode/anyOf[subschema #1]/`
- **2026-06-08** `973957d74ceb` — 1 info
  - added the new `turbo` enum value to the request property `mode/anyOf[subschema #1]/`
- **2026-04-21** `57e1c56be094` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/parallel-web/apis/parallel-api/changes/v1/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)