Skip to main content
POST
/
v1beta
/
search
Python
from parallel import Parallel

client = Parallel(api_key="API Key")

search = client.beta.search(
    objective="What was the GDP of France in 2023?"
)
print(search.results)
{
  "search_id": "search_fcb2b4f3-c75e-4186-87bc-caa1a8381331",
  "results": [
    {
      "url": "https://www.example.com",
      "title": "Sample webpage title",
      "publish_date": "2024-01-15",
      "excerpts": [
        "Sample excerpt 1",
        "Sample excerpt 2"
      ]
    }
  ]
}

Authorizations

​
x-api-key
string
header
required

Headers

​
parallel-beta
string | null

Body

application/json

Base class for search queries.

​
mode
enum<string> | null
default:one-shot

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.

Available options:
one-shot,
agentic
​
objective
string | null

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[] | null

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.

​
processor
enum<string> | null
deprecated

DEPRECATED: use mode instead.

Available options:
base,
pro
​
max_results
integer | null
default:10

Upper bound on the number of results to return. May be limited by the processor. Defaults to 10 if not provided.

​
max_chars_per_result
integer | null
deprecated

DEPRECATED: Use excerpts.max_chars_per_result instead.

​
excerpts
object

Optional settings to configure excerpt generation. Optional settings for returning relevant excerpts.

​
source_policy
object | null

Optional source policy governing preferred and disallowed domains in search results. Source policy for web search results.

This policy governs which sources are allowed/disallowed in results.

​
fetch_policy
object | null

Fetch policy: determines when to return cached content from the index (faster) vs fetching live content (fresher). Default is to disable live fetch and return cached content from the index. Policy for live fetching web results.

Response

Successful Response

Output for the Search API.

​
search_id
string
required

Search ID. Example: search_cad0a6d2dec046bd95ae900527d880e7

​
results
WebSearchResult · object[]
required

A list of WebSearchResult objects, ordered by decreasing relevance.

​
warnings
Warning · object[] | null

Warnings for the search request, if any.

​
usage
UsageItem · object[] | null

Usage metrics for the search request.