Upgrade from Beta to GA

Migrate from Beta to GA (V1) Search API

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 .md to its URL or sending Accept: text/markdown.

This guide helps you migrate from the Beta Search API (/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

1. search_queries is now required — At least one non-empty query must be provided. In Beta, only one of objective or search_queries was required.

2. Settings reorganized under advanced_settings — source_policy, fetch_policy, excerpt settings, and max_results are now nested under a single new advanced_settings object (previously top-level fields). See Advanced Settings for more details.

3. New location field — Set advanced_settings.location to 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.

4. Updated modes — V1 has four modes (turbo, fast, basic, advanced), with advanced as the new default. For most use cases, map both fast and one-shot to basic, and map agentic to advanced. turbo and fast are new in V1 with no Beta equivalents — V1 fast shares a name with Beta fast but is a different, lower-latency mode.

   • basic: The V1 equivalent of Beta fast and one-shot. Returns extended snippets per result and works best with 2-3 high-quality search_queries. Reach for it when you want longer excerpts per source in a single call. For most applications, prefer V1 fast (see below).
   • advanced (default): The V1 equivalent of Beta agentic. Provides higher quality with more advanced retrieval and compression. Best for complex queries where result quality matters more than latency.
   • turbo and fast (new in V1): Lower-latency, lower-cost modes for high-volume and latency-sensitive workloads, with no Beta equivalent. fast delivers high-quality results in around 700ms and is the recommended default for most agents; turbo (~250ms) is built for real-time, high-volume grounding. See Search Modes.

Overview of Changes

Component	Beta	V1
Endpoint	/v1beta/search	/v1/search
Modes	fast, one-shot, agentic (default one-shot)	turbo, fast, basic, advanced (default advanced). Beta fast and one-shot map to basic, agentic maps to advanced. turbo and fast are new modes with no Beta equivalent (V1 fast is not Beta fast)
SDK method	client.beta.search() (parallel-web before 1.0)	client.search() (parallel-web 1.0+)
search_queries	Optional (one of objective or search_queries required)	Required (at least one non-empty query)
objective	Required if search_queries omitted	Optional
max_chars_total	Inside excerpts object	Promoted to top-level request field
client_model (new)	—	Top-level field for model-specific optimizations
location (new)	—	advanced_settings.location — ISO 3166-1 alpha-2 country code for geo-targeted results
advanced_settings (new)	—	New object nesting source_policy, fetch_policy, excerpt_settings, max_results, and location

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

curl https://api.parallel.ai/v1beta/search \
  -H "Content-Type: application/json" \
  -H "x-api-key: $PARALLEL_API_KEY" \
  -d '{
    "objective": "Find latest information about Parallel Web Systems. Focus on new product releases, benchmarks, or company announcements.",
    "search_queries": ["Parallel Web Systems products", "Parallel Web Systems announcements"],
    "mode": "fast",
    "excerpts": {
      "max_chars_per_result": 10000,
      "max_chars_total": 50000
    }
  }'

After (V1)

cURL

curl https://api.parallel.ai/v1/search \
  -H "Content-Type: application/json" \
  -H "x-api-key: $PARALLEL_API_KEY" \
  -d '{
    "objective": "Find latest information about Parallel Web Systems. Focus on new product releases, benchmarks, or company announcements.",
    "search_queries": ["Parallel Web Systems products", "Parallel Web Systems announcements"],
    "mode": "basic",
    "max_chars_total": 50000,
    "advanced_settings": {
      "excerpt_settings": {
        "max_chars_per_result": 10000
      }
    }
  }'

Additional Resources

• Search Quickstart - Get started with the Search API
• Best Practices - Optimize your search requests
• Search MCP - Use Search via Model Context Protocol
• API Reference - Complete parameter specifications

Questions? Contact [e-mail].