Parallel Ai

Parallel.ai API Reference

Fetched 2026-03-15 from docs.parallel.ai

Overview

Parallel is a web integration platform that combines AI inference with live web data for research, enrichment, and automation. It provides two categories of APIs:

Web Tools — Synchronous, low-latency APIs for direct web access (Search, Extract)
Web Agents — AI-powered APIs combining inference with multi-step research workflows (Task, FindAll, Monitor, Chat)

Authentication is via API key passed in the x-api-key header. SDKs are available for Python (parallel-web on PyPI) and TypeScript (parallel-web on npm).

Search API

Searches the web and returns LLM-optimized excerpts.

Endpoint: POST https://api.parallel.ai/v1beta/search
Auth: x-api-key header

Request Body

Parameter	Type	Required	Description
`objective`	string	One of objective/search_queries required	Natural-language description of what to find
`search_queries`	string[]	One of objective/search_queries required	Keyword search queries with optional operators
`mode`	`one-shot` \| `agentic` \| `fast`	No	Controls comprehensiveness vs speed. Default: `one-shot`
`max_results`	integer	No	Upper bound on results. Default: 10
`excerpts`	ExcerptSettings	No	Excerpt configuration (see below)
`source_policy`	SourcePolicy	No	Domain/date filtering
`fetch_policy`	FetchPolicy	No	Cache vs live content strategy

ExcerptSettings:

Field	Type	Description
`max_chars_per_result`	integer	Per-URL character limit (min 1000)
`max_chars_total`	integer	Total characters across all URLs (min 1000)

SourcePolicy:

Field	Type	Description
`include_domains`	string[]	Restrict to these domains/extensions, e.g. `["wikipedia.org", ".edu"]`
`exclude_domains`	string[]	Exclude these domains/extensions
`after_date`	string	RFC 3339 date (YYYY-MM-DD), filter to results on or after this date

FetchPolicy:

Field	Type	Description
`max_age_seconds`	integer	Cache age threshold triggering live fetch. Min 600
`timeout_seconds`	number	Timeout for live content fetching
`disable_cache_fallback`	boolean	If true, error when live fetch fails. Default: false

Response (200)

{
  "search_id": "search_cad0a6d2dec046bd95ae900527d880e7",
  "results": [
    {
      "url": "https://www.example.com",
      "title": "Sample webpage title",
      "publish_date": "2024-01-15",
      "excerpts": ["Relevant excerpt 1", "Relevant excerpt 2"]
    }
  ],
  "warnings": [],
  "usage": [{ "name": "sku_search_additional_results", "count": 1 }]
}

Example (cURL)

curl -X POST https://api.parallel.ai/v1beta/search \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: <api-key>' \
  -d '{"objective": "What was the GDP of France in 2023?"}'

Example (Python)

from parallel import Parallel

client = Parallel()
search = client.beta.search(objective="What was the GDP of France in 2023?")
print(search.results)

Extract API

Extracts clean, LLM-optimized markdown from specific web URLs.

Endpoint: POST https://api.parallel.ai/v1beta/extract
Auth: x-api-key header

Request Body

Parameter	Type	Required	Description
`urls`	string[]	Yes	URLs to extract from
`objective`	string	No	Focuses extraction on a specific objective
`search_queries`	string[]	No	Keyword queries to focus extraction
`fetch_policy`	FetchPolicy	No	Cache vs live fetch behavior
`excerpts`	boolean \| ExcerptSettings	No	Include relevant excerpts. Default: true
`full_content`	boolean \| FullContentSettings	No	Include full page content. Default: false

FullContentSettings:

Field	Type	Description
`max_chars_per_result`	integer	Character limit per URL

Response (200)

{
  "extract_id": "string",
  "results": [
    {
      "url": "https://www.example.com",
      "title": "Page Title",
      "publish_date": "2024-01-15",
      "excerpts": ["Relevant content..."],
      "full_content": "# Full markdown..."
    }
  ],
  "errors": [
    {
      "url": "https://failed.example.com",
      "error_type": "fetch_error",
      "http_status_code": 403,
      "content": "Access denied"
    }
  ],
  "warnings": [],
  "usage": []
}

Example (Python)

from parallel import Parallel

client = Parallel()
extract = client.beta.extract(
    urls=["https://www.example.com"],
    excerpts=True,
    full_content=True
)

Task API

Executes complex, multi-step web research operations. Supports deep research and structured data enrichment with citations, reasoning, and confidence scores.

Create: POST https://api.parallel.ai/v1/tasks/runs
Retrieve status: GET https://api.parallel.ai/v1/tasks/runs/{run_id}
Retrieve result: GET https://api.parallel.ai/v1/tasks/runs/{run_id}/result
Stream events: GET https://api.parallel.ai/v1/tasks/runs/{run_id}/events (SSE)
Auth: x-api-key header

Create Task Run — Request Body

Parameter	Type	Required	Description
`processor`	string	Yes	Processor tier (see Processor Tiers below)
`input`	string \| object	Yes	Input text or structured JSON object
`task_spec`	TaskSpec	No	Task specification with input/output schemas
`metadata`	object	No	User-provided metadata (key max 16 chars, value max 512 chars)
`source_policy`	SourcePolicy	No	Domain filtering for web search
`previous_interaction_id`	string	No	Interaction ID for context reuse
`mcp_servers`	McpServer[]	No	Optional MCP servers for the run
`enable_events`	boolean	No	Enable execution progress tracking
`webhook`	Webhook	No	Callback URL for completion notifications

Create Task Run — Response (202 Accepted)

{
  "run_id": "trun_9907962f83aa4d9d98fd7f4bf745d654",
  "interaction_id": "trun_9907962f83aa4d9d98fd7f4bf745d654",
  "status": "queued",
  "is_active": true,
  "processor": "core",
  "metadata": { "my_key": "my_value" },
  "created_at": "2025-04-23T20:21:48.037943Z",
  "modified_at": "2025-04-23T20:21:48.037943Z"
}

Task statuses: queued, action_required, running, completed, failed, cancelling, cancelled

Retrieve Task Run Result — Response (200)

{
  "run": {
    "run_id": "trun_9907962f83aa4d9d98fd7f4bf745d654",
    "status": "completed",
    "is_active": false,
    "processor": "core"
  },
  "output": {
    "basis": [
      {
        "field": "gdp",
        "reasoning": "Based on World Bank data...",
        "citations": [{ "url": "...", "excerpt": "..." }],
        "confidence": "high"
      }
    ],
    "type": "json",
    "content": { "gdp": "$3.1 trillion (2023)" }
  }
}

Enrichment Pattern

The Task API excels at enriching structured data. Define input and output schemas:

from parallel import Parallel

client = Parallel()
task_run = client.task_run.create(
    processor="core",
    input={"company_name": "Acme Corp", "website": "https://acme.com"},
    task_spec={
        "input_schema": {
            "type": "object",
            "properties": {
                "company_name": {"type": "string", "description": "Company name"},
                "website": {"type": "string", "description": "Company website"}
            }
        },
        "output_schema": {
            "type": "object",
            "properties": {
                "founding_date": {"type": "string", "description": "When the company was founded"},
                "employee_count": {"type": "string", "description": "Approximate number of employees"},
                "funding": {"type": "string", "description": "Total funding raised"}
            }
        }
    }
)

# Poll for result
result = client.task_run.retrieve_result(run_id=task_run.run_id)

Each output field includes basis with citations, reasoning, and confidence (high/medium/low).

Task Groups (Batch Processing)

Create group: POST https://api.parallel.ai/v1beta/tasks/groups
Add runs: POST https://api.parallel.ai/v1beta/tasks/groups/{taskgroup_id}/runs
Retrieve group: GET https://api.parallel.ai/v1beta/tasks/groups/{taskgroup_id}
Fetch runs: GET https://api.parallel.ai/v1beta/tasks/groups/{taskgroup_id}/runs
Stream events: GET https://api.parallel.ai/v1beta/tasks/groups/{taskgroup_id}/events (SSE)

Processor Tiers

Tier	Latency	Max Fields	Best For
lite	10s-60s	~2	Basic metadata, fallback, low latency
base	15s-100s	~5	Standard data enrichment
core	60s-5min	~10	Cross-referenced, moderately complex outputs
core2x	60s-10min	~10	More demanding cross-referenced analysis
pro	2min-10min	~20	Exploratory web research
ultra	5min-25min	~20	Advanced multi-source deep research
ultra2x	5min-50min	~25	Complex extended research
ultra4x	5min-90min	~25	Very difficult deep research
ultra8x	5min-2hr	~25	Extremely difficult research problems

All tiers have -fast variants (e.g., core-fast) that are 2-5x faster but optimize for speed over freshness. Use fast for interactive apps and testing; use standard for freshness-critical tasks.

Error Responses

Status	Description
401	Unauthorized: invalid or missing credentials
402	Payment required: insufficient credit
403	Forbidden: invalid processor
422	Validation error
429	Rate limit exceeded

FindAll API

Discovers and enriches entities from the web matching natural language criteria.

Create: POST https://api.parallel.ai/v1beta/findall/runs
Status: GET https://api.parallel.ai/v1beta/findall/runs/{findall_id}
Result: GET https://api.parallel.ai/v1beta/findall/runs/{findall_id}/result
Stream: GET https://api.parallel.ai/v1beta/findall/runs/{findall_id}/events (SSE)
Extend: POST https://api.parallel.ai/v1beta/findall/runs/{findall_id}/extend
Cancel: POST https://api.parallel.ai/v1beta/findall/runs/{findall_id}/cancel
Ingest: POST https://api.parallel.ai/v1beta/findall/ingest (NL to structured spec)
Auth: x-api-key header

Create FindAll Run — Request Body

Parameter	Type	Required	Description
`objective`	string	Yes	Natural language objective
`entity_type`	string	Yes	Type of entity to find
`match_conditions`	MatchCondition[]	Yes	Conditions entities must satisfy
`generator`	`preview` \| `base` \| `core` \| `pro`	Yes	Generator tier
`match_limit`	integer	Yes	Max matches to find (5-1000)
`exclude_list`	ExcludeCandidate[]	No	Entities to exclude from results
`metadata`	object	No	Custom key-value pairs
`webhook`	Webhook	No	Webhook configuration

MatchCondition:

Field	Type	Description
`name`	string	Condition identifier
`description`	string	Detailed specification with guidance

ExcludeCandidate:

Field	Type	Description
`name`	string	Entity name to exclude
`url`	string	Entity URL to exclude

Response (200)

{
  "findall_id": "findall_56ccc4d188fb41a0803a935cf485c774",
  "status": {
    "status": "queued",
    "is_active": true,
    "metrics": {
      "generated_candidates_count": 0,
      "matched_candidates_count": 0
    },
    "termination_reason": null
  },
  "generator": "base",
  "metadata": {},
  "created_at": "2025-09-10T21:02:08.626446Z",
  "modified_at": "2025-09-10T21:02:08.627376Z"
}

Termination reasons: low_match_rate, match_limit_met, candidates_exhausted, user_cancelled, error_occurred, timeout, insufficient_funds

Ingest Helper

Converts a natural language objective into a structured FindAll spec:

from parallel import Parallel

client = Parallel()
ingest = client.beta.findall.ingest(
    objective="Find all AI companies that raised Series A funding in 2024"
)
run = client.beta.findall.create(
    objective=ingest.objective,
    entity_type=ingest.entity_type,
    match_conditions=[mc.model_dump() for mc in ingest.match_conditions],
    generator="base",
    match_limit=10,
)

Features

Preview: Test queries with small sample before committing to full runs
Extend: Increase match_limit on existing runs without changing criteria
Refresh: Re-run with exclude_list to discover net-new entities over time
Enrichments: Add non-boolean enrichment data to candidates without affecting match conditions
Streaming: Real-time SSE updates on candidate discovery
Webhooks: Async notifications on run events

Monitor API

Tracks web changes via scheduled queries with webhook notifications.

Create: POST https://api.parallel.ai/v1alpha/monitors
List: GET https://api.parallel.ai/v1alpha/monitors
Retrieve: GET https://api.parallel.ai/v1alpha/monitors/{monitor_id}
Update: PUT https://api.parallel.ai/v1alpha/monitors/{monitor_id}
Delete: DELETE https://api.parallel.ai/v1alpha/monitors/{monitor_id}
List events: GET https://api.parallel.ai/v1alpha/monitors/{monitor_id}/events
Retrieve event group: GET https://api.parallel.ai/v1alpha/monitors/{monitor_id}/events/{event_group_id}
Simulate event: POST https://api.parallel.ai/v1alpha/monitors/{monitor_id}/simulate
Auth: x-api-key header

Create Monitor — Request Body

Parameter	Type	Required	Description
`query`	string	Yes	Search query to monitor for material changes
`frequency`	string	Yes	Format: `<number><unit>` where unit is h/d/w. Range: 1h to 30d
`webhook`	MonitorWebhook	No	Webhook configuration for notifications
`metadata`	object	No	User-provided metadata (string values)
`output_schema`	JsonSchema	No	Structured output schema for events

MonitorWebhook:

Field	Type	Description
`url`	string	Webhook destination URL
`event_types`	string[]	`monitor.event.detected`, `monitor.execution.completed`, `monitor.execution.failed`

Create Monitor — Response (201)

{
  "monitor_id": "monitor_b0079f70195e4258a3b982c1b6d8bd3a",
  "query": "Extract recent news about AI",
  "status": "active",
  "frequency": "1d",
  "created_at": "2025-04-23T20:21:48.037943Z",
  "metadata": { "key": "value" },
  "webhook": {
    "url": "https://example.com/webhook",
    "event_types": ["monitor.event.detected"]
  }
}

Monitor statuses: active, canceled

List Monitors — Response (200)

Returns an array of MonitorResponse objects. Supports cursor-based pagination via monitor_id parameter (lexicographic order) and limit parameter (1-10,000).

Key Behaviors

Monitor executes once at creation, then continues per frequency schedule
Supports structured output via output_schema for consistent event formats
Simulate endpoint lets you test webhook integrations without waiting for real events
Slack integration available for receiving updates directly in channels
Events are grouped; up to 300 event groups retained

CLI (parallel-cli)

Installation

# Shell script (no Python required)
curl -fsSL https://parallel.ai/install.sh | bash

# Homebrew
brew install parallel-web/tap/parallel-cli

# pip (with optional extras)
pip install "parallel-cli[yaml,duckdb,bigquery,spark]"

Authentication

parallel-cli login                # Interactive OAuth
parallel-cli login --device       # Headless/device auth
parallel-cli auth                 # Verify auth status

Or set PARALLEL_API_KEY environment variable.

Core Commands

search — Web search with natural language or keywords

parallel-cli search "latest FDA approvals 2024" --mode agentic --max-results 20
parallel-cli search "site:sec.gov 10-K filings" --after-date 2024-01-01

extract — Pull clean markdown from URLs

parallel-cli extract https://example.com --full-content
parallel-cli extract https://example.com --objective "Find pricing details"

research — Deep research with configurable processor tiers

parallel-cli research "What are the top competitors of Acme Corp?" --processor core
parallel-cli research "..." --processor ultra --no-wait  # async

findall — Discover entities matching criteria

parallel-cli findall "AI startups in NYC with Series A funding" --generator base --match-limit 50

monitor — Track web changes

parallel-cli monitor create "SEC filings for AAPL" --frequency 1d --webhook https://...
parallel-cli monitor list
parallel-cli monitor events <monitor_id>

Enrich Command

The enrich command transforms datasets through web research at scale.

# Basic CSV enrichment
parallel-cli enrich companies.csv \
  --source-columns "company_name,website" \
  --enrich-columns "employee_count,founding_date,funding_total" \
  --processor core

# Inline data
parallel-cli enrich --data '["Apple", "Google", "Meta"]' \
  --enrich-columns "market_cap,ceo,headquarters"

# With intent (AI suggests columns)
parallel-cli enrich companies.csv --intent "I need competitive intelligence"

# Dry run to preview
parallel-cli enrich companies.csv --source-columns name --enrich-columns revenue --dry-run

# YAML config for complex jobs
parallel-cli enrich plan  # Interactive YAML config generation
parallel-cli enrich --config enrich-job.yaml

Key options:

Option	Description
`--source-type`	`csv` or `json`
`--source-columns`	Comma-separated input columns
`--enrich-columns`	Comma-separated output columns
`--processor`	Tier: `lite`, `base`, `core-fast`, `core`, `pro`, etc.
`--dry-run`	Preview without API calls
`--no-wait`	Launch async, poll later
`--intent`	AI-powered column suggestion
`--config`	YAML configuration file

Workflow modes:

Direct execution with file paths
Inline data via --data parameter
YAML configs for reproducible jobs
Async via --no-wait with subsequent status/poll commands

Output

All commands support --json for structured output. Exit codes: 0 = success, 2 = input error, 3 = auth error, 4 = API error, 5 = timeout. Supports piped stdin for automation.

Data Integrations

Parallel integrates directly with data platforms for SQL-native enrichment:

BigQuery — Remote functions via parallel-cli bigquery
Snowflake — SQL-native UDTF
Apache Spark — SQL-native UDFs
DuckDB — Native integration with batch processing
Polars — Native DataFrame integration
Supabase — Edge Functions integration
Google Sheets — PARALLEL_QUERY function

Pricing

Free Tier

20,000 free requests to start

Search API

Tier	Cost per 1K requests	Use Case
Base	$4	Standard search
Pro	$9	Enhanced search

Rate limit: 600 req/min
Latency: <3s

Task API

Tier	Cost per 1K requests	Use Case
Lite	$5	Basic information retrieval
Base	$10	Simple web research
Core	$25	Complex web research
Core2x	$50	Very complex web research
Pro	$100	Exploratory web research
Ultra	$300	Extensive deep research
Ultra2x	$600	Advanced deep research (2x compute)
Ultra4x	$1,200	Advanced deep research (4x compute)
Ultra8x	$2,400	Advanced deep research (8x compute)

Rate limit: 2,000 req/min
Latency: 5s to 30min (async)

Chat API

$5 per 1K requests
Rate limit: 300 req/min
Latency: <5s

Extract API

Rate limit: 600 req/min (pricing not listed separately; likely included in Search tier)

FindAll API

Rate limit: 25 req/hour
Pricing varies by generator tier (preview, base, core, pro)

Monitor API

Rate limit: 300 req/min

Enterprise

Volume discounts
Custom rate limits
Data Protection Agreement
Dedicated support and early product access
Startup credits up to $5K for qualified startups
AWS Marketplace pre-committed spend option

Rate Limits

Endpoint	Limit	Window
Search	600	per minute
Extract	600	per minute
Tasks / TaskGroups	2,000	per minute
Chat	300	per minute
FindAll	25	per hour
Monitor	300	per minute

Rate limits apply only to POST requests that create new resources. GET requests (status checks, result retrieval) do not count against these limits.

For expanded quotas, contact support@parallel.ai.

Additional Resources

Python SDK: pip install parallel-web (PyPI)
TypeScript SDK: pnpm add parallel-web (npm)
OpenAPI Spec: https://docs.parallel.ai/public-openapi.json
API Key: https://platform.parallel.ai
MCP Integrations: Search MCP and Task MCP servers for Claude Desktop, Cursor, VS Code
Webhook Setup: https://docs.parallel.ai/resources/webhook-setup.md
Source Policy: https://docs.parallel.ai/resources/source-policy.md
Changelog: https://docs.parallel.ai/resources/changelog.md