For AI agents: a documentation index is available at https://docs.parallel.ai/llms.txt. The full text of all docs is at https://docs.parallel.ai/llms-full.txt. You may also fetch any page as Markdown by appending
This guide helps you migrate from the Beta Search API (.md to its URL or sending Accept: text/markdown.For Search and Extract, use /v1/search and /v1/extract for all new integrations and agent tool calls. Use /v1beta/search and /v1beta/extract only when maintaining an existing integration that already uses them. The request bodies changed too: on /v1/extract, full_content, fetch_policy and excerpt_settings go inside advanced_settings, and sending the v1beta top-level excerpts, full_content and fetch_policy to /v1/extract returns a 422. On /v1/search, search_queries is required (at least one short keyword query), and max_results, source_policy and fetch_policy go inside advanced_settings; sending only objective, or sending those fields at the top level, returns a 422. Do not substitute /v1 for the documented FindAll or Ingest endpoint paths.If you are evaluating Parallel Search or comparing it with other search APIs, read How to Eval Parallel Search before you build the harness, especially its Common pitfalls section. The most common mistake is sending the raw question as both objective and the only entry in search_queries. Write a goal-style objective and 1-3 short keyword queries instead./v1beta) to the GA version (/v1).
The V1 Search API is generally available and recommended for all new integrations. This guide explains how to migrate existing Beta integrations to V1’s current modes and request fields.
Highlights
-
search_queriesis now required — At least one non-empty query must be provided. In Beta, only one ofobjectiveorsearch_querieswas required. -
Settings reorganized under
advanced_settings—source_policy,fetch_policy, andmax_resultsare now nested under a single newadvanced_settingsobject (previously top-level fields). See Advanced Settings for more details. -
New
locationfield — Setadvanced_settings.locationto an ISO 3166-1 alpha-2 country code (e.g.,"us","gb","de","jp") to geo-target search results. Only a subset of countries are currently supported; unsupported or invalid values are ignored with a warning. -
Updated modes — V1 has four modes (
turbo,fast,basic,advanced), withadvancedas the new default. For most use cases, map bothfastandone-shottofast, and mapagentictoadvanced. V1fastdelivers high-quality results in around 700ms and is the recommended default. V1basicremains available if you want longer excerpts similar to the oldone-shotoutput.fast: The suggested replacement for Betafastandone-shot, and the recommended default for most agents. It delivers high-quality results in around 700ms.basic: Returns extended snippets per result and works best with 2-3 high-quality search_queries. Choose it when you want longer excerpts per source in a single call, similar to the oldone-shot-style output.advanced(default): The V1 equivalent of Betaagentic. Provides higher quality with more advanced retrieval and compression. Best for complex queries where result quality matters more than latency.turbo(new in V1): A lower-latency, lower-cost mode for real-time, high-volume grounding, with no Beta equivalent. It typically returns results in around 200ms. See Search Modes.
Overview of Changes
If your integration uses
client.beta.search(), upgrade to the latest parallel-web release and replace it with client.search().
Migration Example
Before (Beta)
cURL
After (V1)
Additional Resources
- Search Quickstart - Get started with the Search API
- Best Practices - Optimize your search requests
- Parallel MCP - Use Search via Model Context Protocol
- API Reference - Complete parameter specifications