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

# Search

`POST /v1/search`

Searches the web.

The legacy Search API reference is available [here](https://docs.parallel.ai/api-reference/legacy/search-beta/search).

## Request body

- V1SearchRequest — Search request.
  - `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.
    - `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. Values below 1000 will be automatically set to 1000.
    - `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_results` integer, nullable — Upper bound on the number of results to return. Defaults to 10 if not 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). 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.
  - `client_model` string, nullable — The model generating this request and consuming the results. Enables optimizations and tailors default settings for the model's capabilities.
  - `max_chars_total` integer, nullable — Upper bound on total characters across excerpts from all results.
  - `mode` 'basic' | 'advanced', nullable — Search mode preset: supported values are `basic` and `advanced`. Basic mode offers the lowest 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.
  - `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.
  - `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.

## Response `200`

Successful Response

- V1SearchResponse — Search response.
  - `results` V1WebSearchResult[], required — A list of search results, ordered by decreasing relevance.
    - `excerpts` string[], required — 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`
  - `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.
  - `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` — 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/57e1c56be094/schema)