For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
Enrich your Supabase data with live web intelligence using [Supabase Edge Functions](https://supabase.com/docs/guides/functions) and Parallel's Task API.
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
The `advanced_settings` object on the Extract API lets you tune fetch behavior (cached vs live), excerpt sizing, and full content extraction. Most callers don't need it — the defaults return focused excerpts from the cached index, which works well for the majority of tool-calling and research use cases.
## Fields
| Field | Type | Notes | Example |
| ----------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
| fetch\_policy | object | Controls when to return indexed content (faster) vs fetching live content (fresher). Default is to use cached content from the index. Enabling live fetch significantly increases latency. For more info including field details, see [Fetch Policy](#fetch-policy) below. | `{"max_age_seconds": 3600}` |
| excerpt\_settings | object | Controls excerpt sizes. Provide `max_chars_per_result` for fine-grained control, or omit to use defaults. | `{"max_chars_per_result": 10000}` |
| full\_content | bool or object | Controls full content extraction. Defaults to `false` (disabled). Set to `true` to enable with defaults, or provide a settings object. | `false` or `{"max_chars_per_result": 50000}` |
## Fetch Policy
The `fetch_policy` parameter controls when to return indexed content (faster) or fetch
fresh content from the source (fresher). Fetching fresh content may take up to a minute
and is subject to rate limits to manage the load on source websites.
| Field | Type | Default | Notes |
| ------------------------ | ------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| max\_age\_seconds | int | dynamic | Maximum age of indexed content in seconds. If older, fetches live. Minimum 600 (10 minutes). If unspecified, uses dynamic policy based on URL and objective. |
| timeout\_seconds | number | dynamic | Timeout for fetching live content. If unspecified, uses a dynamic timeout based on URL and content type (typically 15s-60s). |
| disable\_cache\_fallback | bool | false | If `true`, returns an error when live fetch fails. If `false`, falls back to older indexed content. |
## Excerpt and Full Content Settings
Both `excerpt_settings` and `full_content` are configured inside the `advanced_settings` object.
**Enable full content with custom excerpt sizes:**
```json wrap theme={"system"}
{
"urls": ["https://example.com"],
"advanced_settings": {
"excerpt_settings": {
"max_chars_per_result": 5000
},
"full_content": {
"max_chars_per_result": 50000
}
}
}
```
**Enable full content with default excerpts:**
```json wrap theme={"system"}
{
"urls": ["https://example.com"],
"advanced_settings": {
"full_content": true
}
}
```
**Notes:**
* When `full_content` is enabled, you'll receive both excerpts and full content in the response
* Excerpts are always focused on relevance; full content always starts from the beginning
* Without `objective` or `search_queries`, excerpts will be redundant with full content. The request still succeeds, but may return less relevant content and may include a warning.
* `max_chars_total` (top-level) controls total excerpt size but does not affect full content
# Extract API Best Practices
Source: https://docs.parallel.ai/extract/best-practices
Learn how to optimize web content extraction with objectives, search queries, and fetch policies for LLM-ready markdown output
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
The Extract API converts any public URL into clean, LLM-optimized markdown—handling JavaScript-heavy pages and PDFs automatically. Extract focused excerpts aligned to your objective, or retrieve full page content as needed.
The guidance below applies whether you call the API directly or your model fills **`urls`**, **`objective`**, and **`search_queries`** through function calling. For the copy-paste tool schema, jump to [Extract Tool Definition](#extract-tool-definition) below.
## Key Benefits
* **LLM-optimized markdown**: Extract returns clean markdown from any public URL — including JavaScript-heavy pages and PDFs — with headings, lists, and links preserved for direct use as model input.
* **Objective-focused excerpts**: When you supply `objective` and/or `search_queries`, Extract returns ranked excerpts aligned to the goal, skipping boilerplate and irrelevant sections.
* **Batch-friendly**: Submit a list of URLs in a single request to consolidate what would otherwise be multiple fetches into one round-trip.
## Request Fields
The Extract API accepts the following parameters. The `urls` field is required; all
other fields are optional. See the [API
Reference](/api-reference/extract/extract) for complete parameter
specifications and constraints.
| Field | Type | Notes | Example |
| ------------------ | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| urls | string\[] | List of URLs to extract content from. Up to 20 URLs per request. | `["https://example.com/article"]` |
| objective | string | Natural-language description of what information you're looking for, including broader task context. When provided, focuses extracted content on relevant information. Maximum 5000 characters. | "I'm researching React performance optimization. Find best practices for preventing unnecessary re-renders." |
| search\_queries | string\[] | Optional keyword queries to focus extraction. Use with or without objective to emphasize specific terms. 2-3 queries is best practice; maximum 5 queries, 200 characters per query. | `["React.memo", "useMemo", "useCallback"]` |
| max\_chars\_total | int | Upper bound on total characters across excerpts from all results. Does not affect `full_content`. Default is dynamic based on urls, objective, and client\_model. | 50000 |
| client\_model | string | The model generating this request and consuming the results. Enables optimizations tailored to the model's capabilities. | `"claude-opus-4-7"`, `"gpt-5.4"`, `"gemini-3.1-pro"` |
| session\_id | string | Optional identifier for grouping related calls. Use the same `session_id` across search and extract calls that are part of the same task, and a new unique id for each new task. Any string works — use one meaningful in your app, or reuse a `session_id` returned by an earlier search or extract call. UUIDs work well — see [Session Identifiers](#session-identifiers) below. | `"session_
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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 Extract API (`/v1beta`) to the GA version (`/v1`).
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
The **Extract API** converts any public URL into clean markdown, including
JavaScript-heavy pages and PDFs. It returns focused excerpts aligned to your objective,
or full page content if requested.
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
## Overview
A **candidate** is an entity that FindAll discovers during the generation phase of a run. Each candidate represents a potential match that is evaluated against your match conditions.
### Candidate States
Candidates progress through these states during evaluation:
* **Generated**: Discovered from web data, queued for evaluation
* **Matched**: Successfully satisfied all match conditions
* **Unmatched**: Failed to satisfy one or more match conditions
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
FindAll offers different generators that determine the quality and thoroughness of FindAll run results. See [Pricing](/getting-started/pricing) for generator costs and all API rates.
## Generators
| Generator | Best For | Candidate Pool | Expected Match Rate |
| --------- | --------------------------------------------------------- | ------------------------- | ------------------------------------------------------ |
| `preview` | Testing queries before committing to a full run | \~10 candidates evaluated | Varies — use to validate schema |
| `base` | Broad, common queries where you expect many matches | Moderate pool | Higher (broad criteria match more candidates) |
| `core` | Specific queries with moderate expected matches | Large pool | Moderate (balanced breadth and depth) |
| `pro` | Highly specific queries with rare or hard-to-find matches | Largest pool | Lower per candidate (thorough search for rare matches) |
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
## Run Statuses and Termination Reasons
FindAll runs progress from `queued` → `running` → terminal state (`completed`, `failed`, or `cancelled`).
A run is considered **active** when it has status `queued`, `running` and has active candidate generation, evaluation, and enrichments ongoing.
### Status Definitions
| Status | Description | Can Extend? | Can Enrich? |
| ----------- | -------------------------------------------- | ----------- | ----------- |
| `queued` | Run is waiting to start processing | N/A | N/A |
| `running` | Run is actively evaluating candidates | ❌ No | ✅ Yes |
| `completed` | Run finished (see termination reasons below) | Depends\* | ✅ Yes |
| `failed` | Run encountered an error | ❌ No | ❌ No |
| `cancelled` | Run was cancelled by user | ❌ No | ❌ No |
\* See termination reasons below for extendability
### Termination Reasons
When a run reaches a terminal state, it will have one of these termination reasons:
| Termination Reason | Description | Can Extend? |
| ---------------------- | -------------------------------------------------- | ------------------------------------ |
| `match_limit_met` | Successfully found the requested number of matches | ✅ Yes |
| `low_match_rate` | Match rate too low to continue efficiently | ❌ No - try a more powerful generator |
| `candidates_exhausted` | All available candidates have been processed | ❌ No - broaden query |
| `error_occurred` | Run encountered an error and cannot be continued | ❌ No |
| `timeout` | Run timed out and cannot be continued | ❌ No |
| `user_cancelled` | Run was cancelled by the user | ❌ No |
## Related Topics
* **[Generators and Pricing](/findall-api/core-concepts/findall-generator-pricing)**: Understand generator options and pricing
* **[Preview](/findall-api/features/findall-preview)**: Test queries with \~10 candidates before running full searches
* **[Enrichments](/findall-api/features/findall-enrich)**: Extract additional structured data for matched candidates
* **[Extend Runs](/findall-api/features/findall-extend)**: Increase match limits without paying new fixed costs
* **[Streaming Events](/findall-api/features/findall-sse)**: Receive real-time updates via Server-Sent Events
* **[Webhooks](/findall-api/features/findall-webhook)**: Configure HTTP callbacks for run completion and matches
* **[API Reference](/api-reference/findall/create-findall-run#response-status)**: Complete endpoint documentation
# Cancel
Source: https://docs.parallel.ai/findall-api/features/findall-cancel
Stop FindAll runs early to control costs
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
Stop a running FindAll search when you have enough matches or need to control costs. Results found before cancellation are preserved.
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
• "Has the company raised Series A funding?"
• "Is the company in the healthcare industry?" | • "What is the CEO's name?"
• "What is the company's revenue?"
• "What products does the company offer?" | ### Why This Separation Matters This two-stage approach is efficient and cost-effective: 1. **Filter first**: Match conditions quickly narrow down candidates to relevant matches 2. **Enrich selectively**: Extract detailed data only from the matches that matter This means you don't pay to enrich hundreds of candidates that won't match your criteria. ## Adding Enrichments Enrichments can be added anytime after a FindAll run is created, even for completed runs. Once added: * Enrichments will run on **all matches** (both ones that exist when the request is made and all future matches) * If enrichments are present, **extend** will also perform the same set of enrichments on all extended matches ## Creating Enrichments
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
## Overview
Extend allows you to increase the `match_limit` of an existing FindAll run to get more results using the same evaluation criteria—without paying the fixed cost again. Start with a small limit (10-20) to validate your criteria, then extend to get more matches.
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
Preview mode lets you quickly and inexpensively test your FindAll queries with a small sample of candidates before committing to a full run. It's ideal for validating your match conditions and enrichments.
**When to use preview:**
* Test query structure before running on large datasets
* Validate match conditions work as expected
* Iterate quickly on FindAll schema and descriptions
## How Preview Works
Preview mode uses the same API endpoint as regular FindAll runs, but with `generator: "preview"`. It generates approximately 10 evaluated candidates (both matched and unmatched) to give you a representative sample of results.
## Preview vs. Full Run
| Feature | Preview Mode | Full Run |
| ------------------------ | -------------- | --------------------------------- |
| **Generator** | `preview` | `base`, `core`, `pro` |
| **Candidates Generated** | \~10 evaluated | Until `match_limit` matches found |
| **Match Limit** | Up to 10 | 5 to 1000 (inclusive) |
| **Speed** | Fast (minutes) | Slower (varies by generator) |
| **Cost** | Flat, cheap | Variable, higher |
| **Outputs** | Full | Full |
| **Enrichments** | ❌ No | ✅ Yes |
| **Can Extend** | ❌ No | ✅ Yes |
| **Can Cancel** | ❌ No | ✅ Yes |
### Key Characteristics
* **Fast & Cost-Effective**: Much faster and cheaper than full runs
* **Sample Size**: Generates \~10 evaluated candidates with no guarantee of match rate
* **Full Outputs**: Candidates include full match outputs, reasoning, and citations (just like regular runs)
* **Capped Limit**: `match_limit` is capped at 10 and interpreted as candidates to evaluate, not matches to find
* **No Modifications**: Cannot be extended or cancelled after creation
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
## Overview
Scheduled jobs allow you to run the same FindAll query on a regular basis to discover newly emerging entities and track changes to existing ones. This is ideal for ongoing monitoring use cases like market intelligence, lead generation, or competitive tracking.
Rather than manually re-running queries, you can programmatically create new FindAll runs using a previous run's schema, while excluding candidates you've already discovered.
## Use Cases
Scheduled FindAll jobs are particularly useful for:
* **Market monitoring**: Track new companies entering a market space over time
* **Lead generation**: Continuously discover new potential customers matching your criteria
* **Competitive intelligence**: Monitor emerging competitors and new funding announcements
* **Investment research**: Track new companies meeting specific investment criteria
* **Regulatory compliance**: Discover new entities that may require compliance review
## How It Works
Creating a scheduled FindAll job involves two steps:
1. **Retrieve the schema** from a previous successful run
2. **Create a new run** using that schema, with an exclude list of previously discovered candidates
This approach ensures:
* **Consistent criteria**: Use the exact same evaluation logic across runs
* **No duplicates**: Automatically exclude candidates from previous runs
* **Cost efficiency**: Only pay to evaluate net new candidates
## Step 1: Retrieve the Schema
Get the schema from a completed FindAll run to reuse its `entity_type`, `match_conditions`, and `enrichments`:
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
## Overview
The `/v1beta/findall/runs/{findall_id}/events` endpoint provides real-time updates on candidates as they are discovered and evaluated using Server-Sent Events (SSE). Events are delivered in chronological order, each including `event_id`, `timestamp`, `type`, and `data`.
**Resumability**: Use `last_event_id` query parameter to resume from any point after disconnections. The `last_event_id` is included in each event and in the `/result` endpoint response—if null, the stream starts from the beginning.
**Duration**: Streams remain open while the run is active or until an optional `timeout` (seconds) is reached. A `findall.status` heartbeat is sent every 10 seconds to keep connections alive.
## Accessing the Event Stream
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
| Term | Definition |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| API key | A unique identifier used to authenticate requests to Parallel APIs. Generate your API key at [platform.parallel.ai](https://platform.parallel.ai). |
| Asynchronous API | An API that returns a run ID immediately and processes the request in the background. Task, FindAll, and Monitor APIs are asynchronous. Poll for status or use webhooks to receive results. |
| Cadence | The frequency at which a monitor executes: `hourly`, `daily`, or `weekly`. |
| Candidate | A potential entity discovered during a FindAll run. Candidates are generated from web data and evaluated against match conditions. |
| Chat API | A synchronous API that provides OpenAI-compatible streaming chat completions with web-grounded responses. Supports both speed-optimized and research-grade models. |
| Citation | A reference to a web source that contributed to an output field. Includes the URL and relevant excerpts from the source. |
| Confidence level | A reliability rating for each output field: **high** (strong evidence from multiple authoritative sources), **medium** (adequate evidence with some inconsistencies), or **low** (limited or conflicting evidence). |
| Enrichment | Additional structured data extracted for matched candidates using the Task API. Enrichments run automatically on candidates that pass all match conditions. |
| Event | A detected change or update that matches a monitor's query. Events include the detected information, event date, and source URLs. |
| Event group | A collection of related events detected during a single monitor execution. |
| Excerpt | A focused portion of page content that's relevant to your objective. Optimized for LLM consumption. |
| Extract API | A synchronous API that converts any public URL into clean, LLM-optimized markdown. Handles JavaScript-heavy pages and PDFs. |
| Fast processor | A processor variant optimized for speed over data freshness. Append `-fast` to any processor name (e.g., `core-fast`) for 2-5x faster response times. |
| FieldBasis | The specific object containing citations, reasoning, and confidence for an individual output field within the research basis. |
| FindAll API | An asynchronous API for web-scale entity discovery. Turns natural language queries into structured, enriched databases by generating candidates, validating them against criteria, and optionally enriching matches. |
| FindAll run | A single execution of a FindAll query. Includes candidate generation, evaluation, and optional enrichment. |
| Generator | The engine that determines the quality and thoroughness of FindAll run results. Options include `preview`, `base`, `core`, and `pro`. |
| Match condition | A criterion that candidates must satisfy to be included in FindAll results. Defined in natural language as part of the query. |
| Match status | The state of a candidate after evaluation: `matched` (satisfies all conditions), `unmatched` (fails one or more conditions), or `generated` (not yet evaluated). |
| MCP (Model Context Protocol) | A protocol for connecting AI models to external tools and data sources. Parallel provides MCP servers for Search and Task APIs. |
| Monitor | A scheduled query that continuously tracks the web for changes relevant to a specific topic. |
| Monitor API | An asynchronous API for continuous web tracking. Creates scheduled queries that detect relevant changes and deliver updates via webhooks. |
| Objective | A natural language description of what you're looking for. Used by Search and Extract APIs to focus results on relevant content. |
| Processor | The engine that executes Task Runs. Processors vary in performance characteristics, latency, and reasoning depth. Options include `lite`, `base`, `core`, `core2x`, `pro`, `ultra`, `ultra2x`, `ultra4x`, and `ultra8x`. Each is available in standard and fast variants. |
| Rate limit | The maximum number of API requests allowed within a time period. See [Rate limits](/getting-started/rate-limits) for default quotas. |
| Research Basis | The structured explanation detailing the reasoning and evidence behind each Task Run result. Includes citations, reasoning, and confidence levels. |
| SDK | Software Development Kit. Parallel provides official SDKs for [Python](https://pypi.org/project/parallel-web/) and [TypeScript](https://www.npmjs.com/package/parallel-web). |
| Search API | A synchronous API that executes natural language web searches and returns LLM-optimized excerpts. Replaces multiple keyword searches with a single call for broad or complex queries. |
| Search query | A specific search term or phrase used to find relevant pages. Multiple search queries can be combined in a single Search API request. |
| Source policy | Configuration that controls which web sources can be accessed during research. Can include or exclude specific domains. |
| Synchronous API | An API that returns results immediately in the response. Search, Extract, and Chat APIs are synchronous. |
| Task API | An asynchronous API that combines AI inference with web search and live crawling to turn complex research tasks into repeatable workflows. Returns structured outputs with citations and confidence levels. |
| Task Group | A collection of Task Runs that can be executed and tracked together. Useful for batch processing multiple inputs. |
| Task Run | A single execution of a task specification. Each Task Run processes one input and produces one output with its associated research basis. |
| Task spec | The definition of what a Task Run should accomplish. Includes input schema, output schema, and optional instructions. |
| Webhook | An HTTP callback that delivers notifications when specific events occur (e.g., task completion, monitor event detection). |
# Overview
Source: https://docs.parallel.ai/getting-started/overview
Explore Parallel's web API products for building intelligent applications.
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
Build with Parallel APIs
Pick a product, copy the setup prompt, and paste it into your coding agent.
````markdown theme={"system"}
# Parallel Search API — Setup Prompt
You're integrating the **Parallel Search API**: a natural-language web search that returns LLM-optimized excerpts.
## When to use it
Use Search when the model needs current facts, specific entities, or web data to ground a response. One round-trip: natural-language objective + 2-3 keyword queries → LLM-optimized excerpts (pre-compressed, citation-aware) ready to feed into model context. Faster than multi-hop research; better than raw keyword search because the excerpts arrive shaped for the model.
## Setup
```bash
pip install "parallel-web>=0.5.0" # Python SDK — package is "parallel-web", import as `from parallel import Parallel`
# or: npm install parallel-web # TypeScript SDK
# Treat PARALLEL_API_KEY like a password — load from .env or a secrets manager, don't commit it.
export PARALLEL_API_KEY="your-api-key"
```
## Example (Python — adapt to my codebase's language)
```python
from parallel import Parallel
client = Parallel() # reads PARALLEL_API_KEY from env
# Both objective and search_queries are required — they play distinct roles:
# objective = natural-language research goal (task context, full sentences OK);
# search_queries = 2-3 diverse 3-6-word keyword queries (vary entities/angles, no sentences).
# Mode and other tuning (max_results, max_chars_total) are handler-side levers —
# keep them OUT of the tool schema your agent sees (exposing them often hurts quality).
# Mode defaults to "advanced" (slower, highest-quality — background agents, complex queries).
# Pass mode="basic" in your handler for lower latency in real-time / foreground agents.
# See https://docs.parallel.ai/search/modes and https://docs.parallel.ai/integrations/tool-definition.
search = client.search(
objective="Find recent benchmarks and cost comparisons between major vector databases (pgvector, Pinecone, Weaviate, Qdrant).",
search_queries=[
"pgvector Pinecone benchmark 2025",
"vector database cost comparison",
"Weaviate Qdrant performance review",
],
)
for result in search.results:
print(f"{result.title}: {result.url}")
for excerpt in result.excerpts:
print(excerpt[:200])
```
## Tool definition (for agent function-calling)
Register this in your agent's tool list (OpenAI function-calling format):
```json
{
"type": "function",
"function": {
"name": "search_web",
"description": "Searches the live web using a natural-language objective plus keyword queries, returning LLM-optimized excerpts (pre-compressed, citation-aware) ready to feed into model context. Use whenever the model needs current facts, specific named entities, recent events, or information that likely isn't in training data. Prefer over repeated keyword searches — one call covers the ground of 2-3 traditional queries with better relevance.",
"parameters": {
"type": "object",
"properties": {
"objective": {
"type": "string",
"description": "A concise, self-contained search query. Must include the key entity or topic being searched for."
},
"search_queries": {
"type": "array",
"description": "2-3 diverse keyword search queries, each 3-6 words. Must be diverse — vary entity names, synonyms, and angles. Each query must include the key entity or topic. NEVER write sentences, instructions, or use site: operators.",
"items": { "type": "string" },
"minItems": 2,
"maxItems": 3
}
},
"required": ["objective", "search_queries"]
}
}
}
```
## TypeScript notes
- Import: `import Parallel from "parallel-web"` (default export, not `import { Parallel }`).
- Request/response fields stay snake_case: `search_queries`, `search.results[].url`. Don't camelCase them — your linter may try.
- Wrap the call in an `async` function and `await` it.
- Need Anthropic-format tools instead of OpenAI? Drop the `"type": "function"` envelope, rename `parameters` → `input_schema`, and lift `name` / `description` to the top level.
## Links
- [Search API Reference](https://docs.parallel.ai/api-reference/search/search) — full parameter specs
- [Search Quickstart](https://docs.parallel.ai/search/search-quickstart) + [Best Practices](https://docs.parallel.ai/search/best-practices)
- [OpenAPI Spec](https://docs.parallel.ai/public-openapi.json) — machine-readable schema
- [Python SDK (PyPI)](https://pypi.org/project/parallel-web/) · [TypeScript SDK (npm)](https://www.npmjs.com/package/parallel-web)
- [Cookbook](https://github.com/parallel-web/parallel-cookbook) · [Platform (get API key)](https://platform.parallel.ai)
## Other Parallel APIs
| API | Shape | Use when |
|-----|-------|----------|
| **Search** | One round-trip; natural-language objective + keyword queries → LLM-optimized excerpts | The model needs current facts or specific entities to ground a response |
| **Extract** | URL → clean markdown (handles JS pages and PDFs) | Pulling the contents of a specific page, usually after narrowing via Search |
| **Task** | Multi-hop research agent; runs seconds to hours (webhooks for long tiers) | Deep research with cited structured output; answers you can't get in one search |
| **FindAll** | NL criteria → verified list of matching entities | Building a list from scratch (lead gen, competitive mapping, datasets) |
| **Monitor** | Scheduled NL query + webhook notifications on change | Continuous tracking (news, regulatory, competitive watchlists) |
````
````markdown theme={"system"}
# Parallel Extract API — Setup Prompt
You're integrating the **Parallel Extract API**: converts any public URL into clean, LLM-optimized markdown.
## When to use it
Use Extract when you already know which URL(s) to read — typically after Search has narrowed the list, or when the user hands the agent a URL directly. Handles JavaScript-rendered pages and PDFs, not just static HTML. Pass a `target_content` objective to get focused excerpts; omit it for a full-page markdown dump. Up to 20 URLs per call.
## Setup
```bash
pip install "parallel-web>=0.5.0" # Python SDK — package is "parallel-web", import as `from parallel import Parallel`
# or: npm install parallel-web # TypeScript SDK
# Treat PARALLEL_API_KEY like a password — load from .env or a secrets manager, don't commit it.
export PARALLEL_API_KEY="your-api-key"
```
## Example (Python — adapt to my codebase's language)
```python
from parallel import Parallel
client = Parallel() # reads PARALLEL_API_KEY from env
# Provide an objective to focus extraction on relevant content.
# Up to 20 URLs per request. Pages that fail to fetch appear in extract.errors.
extract = client.extract(
urls=["https://arxiv.org/pdf/1706.03762"],
objective="Explain the multi-head self-attention mechanism and why it replaces recurrence.",
)
for result in extract.results:
print(f"{result.title}: {result.url}")
for excerpt in result.excerpts:
print(excerpt[:200])
# Don't silently drop failed URLs — inspect extract.errors[].url / .error_type.
for err in extract.errors:
print(f"FAILED {err.url}: {err.error_type}")
```
## Tool definition (for agent function-calling)
Register this in your agent's tool list (OpenAI function-calling format). In your tool handler, map `target_content` → the Extract API `objective` field when the model provides it.
```json
{
"type": "function",
"function": {
"name": "web_fetch",
"description": "Fetches one or more URLs and returns clean LLM-optimized markdown — handles JavaScript-rendered pages and PDFs, not just static HTML. When target_content is provided, narrows the response to excerpts most relevant to that target; otherwise returns the full page. Use after search_web to pull the contents of a specific page the model decided it needs to read in depth, or when the user hands the agent a URL directly.",
"parameters": {
"type": "object",
"properties": {
"urls": {
"type": "array",
"description": "The URLs to fetch content from.",
"items": { "type": "string" }
},
"target_content": {
"type": "string",
"description": "The content to target from the page. For example, information about a certain method or a class in a page. If not provided, the entire page is fetched."
}
},
"required": ["urls"]
}
}
}
```
## TypeScript notes
- Import: `import Parallel from "parallel-web"` (default export, not `import { Parallel }`).
- Method: `await client.extract({ urls, objective })` — top-level on the client, not `client.extractions.*`.
- Response fields stay snake_case: `result.publish_date`, `result.full_content`, `err.error_type`, `err.http_status_code`. Don't camelCase them.
- Wrap the call in an `async` function and `await` it.
- PDF handling is server-side — no TS-side parsing needed for the arxiv example above.
## Links
- [Extract API Reference](https://docs.parallel.ai/api-reference/extract/extract) — full parameter specs
- [Extract Quickstart](https://docs.parallel.ai/extract/extract-quickstart) + [Best Practices](https://docs.parallel.ai/extract/best-practices)
- [OpenAPI Spec](https://docs.parallel.ai/public-openapi.json) — machine-readable schema
- [Python SDK (PyPI)](https://pypi.org/project/parallel-web/) · [TypeScript SDK (npm)](https://www.npmjs.com/package/parallel-web)
- [Cookbook](https://github.com/parallel-web/parallel-cookbook) · [Platform (get API key)](https://platform.parallel.ai)
## Other Parallel APIs
| API | Shape | Use when |
|-----|-------|----------|
| **Search** | One round-trip; natural-language objective + keyword queries → LLM-optimized excerpts | The model needs current facts or specific entities to ground a response |
| **Extract** | URL → clean markdown (handles JS pages and PDFs) | Pulling the contents of a specific page, usually after narrowing via Search |
| **Task** | Multi-hop research agent; runs seconds to hours (webhooks for long tiers) | Deep research with cited structured output; answers you can't get in one search |
| **FindAll** | NL criteria → verified list of matching entities | Building a list from scratch (lead gen, competitive mapping, datasets) |
| **Monitor** | Scheduled NL query + webhook notifications on change | Continuous tracking (news, regulatory, competitive watchlists) |
````
````markdown theme={"system"}
# Parallel Task API (Deep Research) — Setup Prompt
You're integrating the **Parallel Task API** for deep research: a single API call that takes a plain-language input and returns comprehensive, cited results.
## When to use it
Use the Task API for multi-hop research that needs minutes (not seconds) and citations — questions a single Search call can't answer because they require synthesis across many sources. Plain-language input, structured cited output in `result.output.basis`. For `pro` (~10 min), blocking is fine; for `ultra`/`ultra8x` (up to 2hr), use webhooks. If you only need one search pass, use Search instead.
## Setup
```bash
pip install "parallel-web>=0.5.0" # Python SDK — package is "parallel-web", import as `from parallel import Parallel`
# or: npm install parallel-web # TypeScript SDK
# Treat PARALLEL_API_KEY like a password — load from .env or a secrets manager, don't commit it.
export PARALLEL_API_KEY="your-api-key"
```
## Example (Python — adapt to my codebase's language)
```python
from parallel import Parallel
client = Parallel() # reads PARALLEL_API_KEY from env
# For deep research, use the "pro" or "ultra" processors.
# Append "-fast" for lower latency (e.g. "pro-fast", "ultra-fast").
# For "ultra" / "ultra8x" (up to ~2hr), don't block — use webhooks instead.
# See https://docs.parallel.ai/task-api/webhooks. Blocking is only a good pattern for "pro" (<10 min).
task_run = client.task_run.create(
input="Research the latest developments in AI search technology",
processor="pro",
)
# Block until the task completes (appropriate for "pro"; avoid for ultra-tier).
result = client.task_run.result(task_run.run_id, api_timeout=3600)
# result.output.content is the research answer.
# result.output.basis is a list of per-field citations + reasoning.
print(result.output.content)
for field in result.output.basis:
print(f"- {field.field}: {len(field.citations)} citations")
```
## TypeScript notes
- Import: `import Parallel from "parallel-web"` (default export).
- Methods are camelCase (`client.taskRun.create`), but body/response fields stay snake_case (`task_run.run_id`, `result.output.basis`). Mixed casing is load-bearing — don't let your linter normalize it.
- **For `pro` runs (<10 min, blocking is fine):** Python's `api_timeout=3600` has no TS equivalent. Use `{ timeout: 25 }` (per-request seconds) inside a poll loop, retrying ~144 times for a 1-hour budget. `catch` generic errors and rethrow on the last iteration. See the TypeScript tab at [/task-api/examples/task-deep-research](https://docs.parallel.ai/task-api/examples/task-deep-research).
- Strict-flow note: `let runResult` isn't proven defined after the poll loop, so reference it as `runResult!` (or guard with `if (!runResult) throw ...`) when accessing `.output.content` / `.output.basis`.
- **For `ultra` / `ultra8x` runs (up to 2hr), don't poll — use webhooks.** Blocking an HTTP connection for hours is not the design. Register a webhook at create time: `client.beta.taskRun.create({ webhook: { url, event_types: ["task_run.status"] }, betas: ["webhook-2025-08-12"] })`. See [/task-api/webhooks](https://docs.parallel.ai/task-api/webhooks).
## Links
- [Task API Reference](https://docs.parallel.ai/api-reference/tasks/create-task-run) — full parameter specs
- [Deep Research Example](https://docs.parallel.ai/task-api/examples/task-deep-research) + [Task Quickstart](https://docs.parallel.ai/task-api/task-quickstart)
- [OpenAPI Spec](https://docs.parallel.ai/public-openapi.json) — machine-readable schema
- [Python SDK (PyPI)](https://pypi.org/project/parallel-web/) · [TypeScript SDK (npm)](https://www.npmjs.com/package/parallel-web)
- [Cookbook](https://github.com/parallel-web/parallel-cookbook) · [Platform (get API key)](https://platform.parallel.ai)
## Other Parallel APIs
| API | Shape | Use when |
|-----|-------|----------|
| **Search** | One round-trip; natural-language objective + keyword queries → LLM-optimized excerpts | The model needs current facts or specific entities to ground a response |
| **Extract** | URL → clean markdown (handles JS pages and PDFs) | Pulling the contents of a specific page, usually after narrowing via Search |
| **Task** | Multi-hop research agent; runs seconds to hours (webhooks for long tiers) | Deep research with cited structured output; answers you can't get in one search |
| **FindAll** | NL criteria → verified list of matching entities | Building a list from scratch (lead gen, competitive mapping, datasets) |
| **Monitor** | Scheduled NL query + webhook notifications on change | Continuous tracking (news, regulatory, competitive watchlists) |
````
````markdown theme={"system"}
# Parallel Task API (Enrichment) — Setup Prompt
You're integrating the **Parallel Task API** for data enrichment: populate structured fields about an entity (company, person, product) from live web data.
## When to use it
Use the Task API with a JSON output schema when you already have a list of entities and need to populate structured fields about each — founding date, funding, employee count, whatever. Per-field citations come back in `result.output.basis` for audit trails. For many records in one go, use the Group API. If you don't have the list yet, use FindAll to discover first.
## Setup
```bash
pip install "parallel-web>=0.5.0" # Python SDK — package is "parallel-web", import as `from parallel import Parallel`
# or: npm install parallel-web # TypeScript SDK
# Treat PARALLEL_API_KEY like a password — load from .env or a secrets manager, don't commit it.
export PARALLEL_API_KEY="your-api-key"
```
## Example (Python — adapt to my codebase's language)
```python
from parallel import Parallel
client = Parallel() # reads PARALLEL_API_KEY from env
# Enrich a record with structured web data.
# Processors: lite (~2 fields), base (~5 fields), core (~10 fields), core2x (~10 fields, complex),
# pro (~20 fields, exploratory), ultra/ultra2x/ultra4x/ultra8x (~20-25 fields, deep research).
# Append "-fast" for lower latency (e.g. "core-fast"). See https://docs.parallel.ai/task-api/guides/choose-a-processor.
# Tip: structured input (dict) grounds the run better than a bare string.
task_run = client.task_run.create(
input={"company": "Stripe", "website": "stripe.com"},
task_spec={
"output_schema": {
"type": "json",
"json_schema": {
"type": "object",
"properties": {
"founding_date": {
"type": "string",
"description": "Founding date in MM-YYYY format"
},
"employee_count": {
"type": "string",
"description": "Estimated number of employees"
},
"funding_sources": {
"type": "string",
"description": "Description of funding sources and amounts"
}
},
"required": ["founding_date", "employee_count", "funding_sources"],
"additionalProperties": False
}
}
},
processor="base", # ~5 fields. Use "core" for ~10, "pro" for ~20+.
)
# Block until the enrichment completes. For many records, use the Group API: https://docs.parallel.ai/task-api/group-api
result = client.task_run.result(task_run.run_id, api_timeout=3600)
# result.output.content is the populated JSON dict.
# result.output.basis carries per-field citations + reasoning (auditable provenance).
print(result.output.content)
for field in result.output.basis:
print(f"- {field.field}: {len(field.citations)} citations")
```
## TypeScript notes
- Import: `import Parallel from "parallel-web"` (default export).
- Methods camelCase (`client.taskRun.create`), body fields snake_case (`task_spec`, `output_schema`, `json_schema`, `additional_properties` stays as JSON-Schema `additionalProperties: false`). Your linter may try to camelCase body fields — the call will fail if it does.
- **Python's `api_timeout=3600` has no TS equivalent.** Use `{ timeout: 25 }` in a poll loop, retrying ~144 times for a 1-hour budget. `catch` generic errors and rethrow on the last iteration (don't try to match a specific status code — any non-`break` outcome means "not ready yet"). See the TypeScript tab at [/task-api/examples/task-enrichment](https://docs.parallel.ai/task-api/examples/task-enrichment).
- For batch enrichment, the Group API at [/task-api/group-api](https://docs.parallel.ai/task-api/group-api) uses the same snake_case body convention — drop-in familiar.
## Links
- [Task API Reference](https://docs.parallel.ai/api-reference/tasks/create-task-run) — full parameter specs
- [Enrichment Example](https://docs.parallel.ai/task-api/examples/task-enrichment) + [Task Quickstart](https://docs.parallel.ai/task-api/task-quickstart)
- [OpenAPI Spec](https://docs.parallel.ai/public-openapi.json) — machine-readable schema
- [Python SDK (PyPI)](https://pypi.org/project/parallel-web/) · [TypeScript SDK (npm)](https://www.npmjs.com/package/parallel-web)
- [Cookbook](https://github.com/parallel-web/parallel-cookbook) · [Platform (get API key)](https://platform.parallel.ai)
## Other Parallel APIs
| API | Shape | Use when |
|-----|-------|----------|
| **Search** | One round-trip; natural-language objective + keyword queries → LLM-optimized excerpts | The model needs current facts or specific entities to ground a response |
| **Extract** | URL → clean markdown (handles JS pages and PDFs) | Pulling the contents of a specific page, usually after narrowing via Search |
| **Task** | Multi-hop research agent; runs seconds to hours (webhooks for long tiers) | Deep research with cited structured output; answers you can't get in one search |
| **FindAll** | NL criteria → verified list of matching entities | Building a list from scratch (lead gen, competitive mapping, datasets) |
| **Monitor** | Scheduled NL query + webhook notifications on change | Continuous tracking (news, regulatory, competitive watchlists) |
````
````markdown theme={"system"}
# Parallel Monitor API — Setup Prompt
You're integrating the **Parallel Monitor API**: continuously track the web for changes relevant to a natural-language query, on a schedule you control. Updates are delivered via webhook (recommended) or pulled via the events endpoint.
## When to use it
Use Monitor when you need to track something continuously — not ask-and-forget. Define a `type=event_stream` monitor with a natural-language query and a `frequency` (1h–30d); when material changes are detected, Parallel POSTs events to your webhook. Good for news tracking, regulatory watch, competitor pricing, executive changes, or anything you'd otherwise build with a cron + diff pipeline. Don't bake dates into the query — Monitor handles freshness automatically. To diff a structured Task Run output across executions instead, use `type=snapshot` (see [Snapshot Monitor](https://docs.parallel.ai/monitor-api/quickstart-snapshot)).
## Best practices
- **Scope queries with intent, not keywords.** `"Notable funding or product launches at OpenAI and Anthropic"` beats `OpenAI OR Anthropic AND funding OR launch`.
- **Pick a frequency that matches signal velocity.** `"1h"` for fast-moving topics, `"1d"` for most news, `"1w"` for slower changes.
- **Prefer webhooks over polling.** Lower latency, no infrastructure to maintain.
- **Pick `processor` for query difficulty.** `"lite"` (default) handles routine queries; `"base"` increases recall and breadth for harder queries, at higher cost.
- **Cancel unused monitors.** Each active monitor consumes usage on every scheduled run.
- **Don't use Monitor for historical research.** It tracks updates from the time of creation. Use [Deep Research](https://docs.parallel.ai/task-api/examples/task-deep-research) for retrospective queries.
## Setup
```bash
pip install "parallel-web>=0.5.0" # Python SDK — package is "parallel-web", import as `from parallel import Parallel`
# or: npm install parallel-web # TypeScript SDK
# Treat PARALLEL_API_KEY like a password — load from .env or a secrets manager, don't commit it.
export PARALLEL_API_KEY="your-api-key"
```
## Example (Python — adapt to my codebase's language)
```python
from parallel import Parallel
client = Parallel() # reads PARALLEL_API_KEY from env
# type="event_stream" monitors a search query for material changes.
# frequency: "1h" to "30d" (e.g. "1h", "6h", "1d", "1w", "30d").
# processor: "lite" (default) for routine queries; "base" for harder queries needing higher recall/breadth, at higher cost.
# Don't bake dates into the query — Monitor tracks new updates automatically.
monitor = client.monitor.create(
type="event_stream",
frequency="1d",
processor="base",
settings={
"query": "Notable news, funding, product launches, or regulatory events about OpenAI and Anthropic.",
},
webhook={
"url": "https://your-app.example.com/parallel-webhook",
"event_types": ["monitor.event.detected"],
},
metadata={"source": "docs-home"},
)
print(f"Monitor created: {monitor.monitor_id} (status={monitor.status})")
# Webhooks deliver { type: "monitor.event.detected", data: { monitor_id, event: { event_group_id }, metadata } }.
# Use the event_group_id to fetch events for that execution:
events = client.monitor.events(monitor.monitor_id, event_group_id="")
for event in events.events:
print(event.event_id, event.event_date, event.output.content)
# Or list recent events across executions: client.monitor.events(monitor_id, limit=20)
# Pass include_completions=True to also see no-change runs.
# See https://docs.parallel.ai/monitor-api/monitor-events.
```
## TypeScript notes
- Import: `import Parallel from "parallel-web"` (default export).
- Methods are typed: `await client.monitor.create({ type, frequency, settings: { query }, webhook })`. No more low-level `client.post(...)` for monitor calls.
- Body/response fields stay snake_case: `event_types`, `event_group_id`, `monitor_id`, `event_id`. Don't camelCase.
- Wrap in `async` function; await `client.monitor.create(...)` and `client.monitor.events(...)`.
- **Signature verification is production hardening, not required to prototype.** For a first integration you can trust the payload and skip verification. Before you ship to prod: verify the HMAC-SHA256 of `${webhook_id}.${webhook_timestamp}.${raw_body}` using your account webhook secret (get it at **Settings → Webhooks** on platform.parallel.ai; convention: `process.env.PARALLEL_WEBHOOK_SECRET`). The `webhook-signature` header is `v1,` (RFC 4648, space-delimited if rotating). Use the **raw request body** (not parsed JSON) for the HMAC. See [/resources/webhook-setup](https://docs.parallel.ai/resources/webhook-setup) for a ready-to-copy Node.js verifier.
## Migrating from Alpha?
If you're on `/v1alpha/monitors`, see the [Monitor Migration Guide](https://docs.parallel.ai/monitor-api/monitor-migration-guide) — V1 reorganizes the request shape (`settings` wrapper, `advanced_settings`), renames endpoints (Update/Cancel/Trigger), restructures event payloads (stable `event_id`, typed `output` with `basis`), and exposes typed SDK and CLI bindings.
## Links
- [Monitor API Reference](https://docs.parallel.ai/api-reference/monitor/create-monitor) — full parameter specs
- [Monitor Quickstart](https://docs.parallel.ai/monitor-api/monitor-quickstart) + [Events model](https://docs.parallel.ai/monitor-api/monitor-events)
- [Snapshot Quickstart](https://docs.parallel.ai/monitor-api/quickstart-snapshot) — track Task Run output diffs
- [Migration Guide (Alpha → V1)](https://docs.parallel.ai/monitor-api/monitor-migration-guide)
- [OpenAPI Spec](https://docs.parallel.ai/public-openapi.json) — machine-readable schema
- [Python SDK (PyPI)](https://pypi.org/project/parallel-web/) · [TypeScript SDK (npm)](https://www.npmjs.com/package/parallel-web)
- [Cookbook](https://github.com/parallel-web/parallel-cookbook) · [Platform (get API key)](https://platform.parallel.ai)
## Other Parallel APIs
| API | Shape | Use when |
|-----|-------|----------|
| **Search** | One round-trip; natural-language objective + keyword queries → LLM-optimized excerpts | The model needs current facts or specific entities to ground a response |
| **Extract** | URL → clean markdown (handles JS pages and PDFs) | Pulling the contents of a specific page, usually after narrowing via Search |
| **Task** | Multi-hop research agent; runs seconds to hours (webhooks for long tiers) | Deep research with cited structured output; answers you can't get in one search |
| **FindAll** | NL criteria → verified list of matching entities | Building a list from scratch (lead gen, competitive mapping, datasets) |
| **Monitor** | Scheduled NL query + webhook notifications on change | Continuous tracking (news, regulatory, competitive watchlists) |
````
````markdown theme={"system"}
# Parallel FindAll API — Setup Prompt
You're integrating the **Parallel FindAll API** (beta): discover and verify entities matching criteria you describe in plain language.
## When to use it
Use FindAll to build a list from scratch — you describe what you're looking for in natural language, it searches the web, evaluates candidates against your match conditions, and returns verified matches. If you already have the list and just need to populate fields about each entity, use the Task API (enrichment) instead.
## Setup
```bash
pip install "parallel-web>=0.5.0" # Python SDK — package is "parallel-web", import as `from parallel import Parallel`
# or: npm install parallel-web # TypeScript SDK
# Treat PARALLEL_API_KEY like a password — load from .env or a secrets manager, don't commit it.
export PARALLEL_API_KEY="your-api-key"
```
## Example (Python — adapt to my codebase's language)
```python
import time
from parallel import Parallel
client = Parallel() # reads PARALLEL_API_KEY from env
# Tip: start with generator="preview" to test your query (~10 candidates, low cost).
# Generators: preview (test), base (broad/common matches), core (specific),
# pro (rare/hard-to-find matches, most thorough)
# match_limit must be between 5 and 1000.
# Write match_conditions as concrete, testable predicates (not tautologies).
findall_run = client.beta.findall.create(
objective="Find all AI startups that raised Series A in 2024",
entity_type="companies",
match_conditions=[
{
"name": "ai_core_product_check",
"description": "Company's core product or platform must be AI-focused (not merely AI-adjacent).",
},
{
"name": "series_a_2024_check",
"description": "Company must have announced a Series A funding round between 2024-01-01 and 2024-12-31.",
},
],
generator="core",
match_limit=20,
)
# Poll until the run is no longer active, then fetch results.
# For a production integration, prefer SSE or webhooks — see https://docs.parallel.ai/findall-api/features/findall-sse.
while client.beta.findall.retrieve(findall_id=findall_run.findall_id).status.is_active:
time.sleep(5)
result = client.beta.findall.result(findall_id=findall_run.findall_id)
for candidate in result.candidates:
print(f"{candidate.name}: {candidate.url}")
print(f" {candidate.description}")
```
## TypeScript notes
- Import: `import Parallel from "parallel-web"` (default export).
- Methods live under `client.beta.findall.*` (four-deep). Request/response fields stay snake_case: `entity_type`, `match_conditions`, `match_limit`, `findall_id`, `status.is_active`, `candidate.name` / `.url` / `.description`.
- `retrieve()` and `result()` take a **positional string** id, not an object param: `await client.beta.findall.retrieve(findallId)`.
- The `parallel-beta: findall-2025-09-15` header is set automatically by the SDK — don't add it manually.
- **Prefer SSE over polling** for production: `const stream = await client.beta.findall.events(findallId); for await (const event of stream) { ... }`. Events are a discriminated union keyed on `event.type` (`"findall.candidate.matched"` carries `event.candidate`; `"findall.status"` carries the run status; terminal states set `status.is_active: false` — break the loop there). Full shape at [/findall-api/features/findall-sse](https://docs.parallel.ai/findall-api/features/findall-sse).
## Links
- [FindAll API Reference](https://docs.parallel.ai/api-reference/findall/create-findall-run) — full parameter specs
- [FindAll Quickstart](https://docs.parallel.ai/findall-api/findall-quickstart)
- [OpenAPI Spec](https://docs.parallel.ai/public-openapi.json) — machine-readable schema
- [Python SDK (PyPI)](https://pypi.org/project/parallel-web/) · [TypeScript SDK (npm)](https://www.npmjs.com/package/parallel-web)
- [Cookbook](https://github.com/parallel-web/parallel-cookbook) · [Platform (get API key)](https://platform.parallel.ai)
## Other Parallel APIs
| API | Shape | Use when |
|-----|-------|----------|
| **Search** | One round-trip; natural-language objective + keyword queries → LLM-optimized excerpts | The model needs current facts or specific entities to ground a response |
| **Extract** | URL → clean markdown (handles JS pages and PDFs) | Pulling the contents of a specific page, usually after narrowing via Search |
| **Task** | Multi-hop research agent; runs seconds to hours (webhooks for long tiers) | Deep research with cited structured output; answers you can't get in one search |
| **FindAll** | NL criteria → verified list of matching entities | Building a list from scratch (lead gen, competitive mapping, datasets) |
| **Monitor** | Scheduled NL query + webhook notifications on change | Continuous tracking (news, regulatory, competitive watchlists) |
````
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
## Summary
| API | Price | Use case | Reasoning | Type | Latency |
| ------- | ----------- | ------------------------------------------ | --------- | ------------ | --------- |
| Search | \$ | Page and excerpt retrieval | - | Synchronous | 1-3s |
| Extract | \$ | Page content retrieval | - | Synchronous | 1-20s |
| Chat | \$ | Grounded chat completions | Low | Synchronous | 1-3s |
| Task | \$-\$\$\$\$ | Deep research, enrichment, custom research | Low-High | Asynchronous | 10s - 2hr |
| FindAll | \$-\$\$\$\$ | List / database building | Low-High | Asynchronous | 10s - 2hr |
| Monitor | \$-\$\$ | Always-on web monitoring | Low | Asynchronous | Ambient |
## Web Tools
### Search API
By default, the Search API returns 10 page results and their excerpts per request.
| Component | Cost (\$/1000) |
| -------------------------------------------- | -------------- |
| Per 1,000 requests (default 10 results) | 5 |
| Per 1,000 additional page results & excerpts | 1 |
**Cost formula:**
$$
\text{total cost} = 0.005 + (0.001 \times \text{additional results \& excerpts})
$$
### Extract API
| Component | Cost (\$/1000) |
| -------------- | -------------- |
| Per 1,000 URLs | 1 |
## Web Agents
### Chat API
Chat API pricing is based on the model you select. Research models (`lite`, `base`, `core`) are Chat API wrappers over [Task API processors](/task-api/guides/choose-a-processor) and share the same pricing.
| Model | Type | Processor | Cost (\$/1000) |
| ------- | ------------------ | --------- | -------------- |
| `speed` | Simple completions | - | 5 |
| `lite` | Research | `lite` | 5 |
| `base` | Research | `base` | 10 |
| `core` | Research | `core` | 25 |
### Task API
Task API pricing is based on the [processor](/task-api/guides/choose-a-processor) you select. Cost is per 1,000 Task Runs. Fast processors have the same pricing as their standard counterparts.
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
The following table shows the default rate limits for each Parallel API product:
| Product | Default Quota | What Counts as a Request |
| ---------------- | ------------- | ---------------------------------------------------------------------------------------- |
| Search | 600 per min | Each POST to `/v1/search` |
| Extract | 600 per min | Each POST to `/v1/extract` |
| Tasks/TaskGroups | 2,000 per min | Each POST to `/v1/tasks/runs` or `/v1/tasks/groups/{taskgroup_id}/runs` (creating tasks) |
| Chat | 300 per min | Each POST to `/v1beta/chat/completions` |
| FindAll | 300 per hour | Each POST to `/v1beta/findall/runs` (creating a generator) |
| Monitor | 300 per min | Each POST to `/v1alpha/monitors` |
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
Agent Skills let you add Parallel's capabilities to AI coding agents like Cursor, Cline, GitHub Copilot, Windsurf, and 30+ other tools via the [Agent Skills CLI](https://github.com/agentskills/agentskills). Skills are lightweight, declarative integrations that give your agent access to live web data without writing any code.
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
Integrate Parallel with [Tempo](https://tempo.xyz) and the [Machine Payments Protocol (MPP)](https://mpp.dev/) to enable AI agents to autonomously pay for and access Parallel's web research APIs. MPP supports payments integration with **Stripe** and **Tempo stablecoins** (pathUSD / USDC).
## Overview
The Machine Payments Protocol (MPP) is an open protocol that enables machine-to-machine payments over HTTP. MPP allows AI agents to pay for services programmatically using the HTTP `402 Payment Required` status code.
The Parallel MPP gateway at `parallelmpp.dev` exposes Parallel's Search, Extract, and Task APIs with pay-per-use pricing. You can pay using:
* **Stripe**: Pay with a credit card — no crypto wallet required
* **Tempo stablecoins**: Pay with pathUSD or USDC on the [Tempo blockchain](https://tempo.xyz) for sub-millidollar transaction fees
* **x402**: Pay with USDC on Base using the [x402 protocol](https://x402.org)
When combined with Parallel, your agents can:
* **Pay for web services autonomously**: Agents discover, negotiate, and settle payments without human intervention
* **Use micropayments**: Per-request pricing starting at \$0.01 for search and extract
* **Access paid APIs and data**: Agents can pay for premium data sources, compute, and services during task execution
* **Handle the full payment lifecycle**: The `mppx` CLI automatically handles `402` challenges, signs payment credentials, and retries requests
## How MPP works
MPP uses a challenge-response flow built on standard HTTP semantics:
```text theme={"system"}
┌─────────────────┐ ┌─────────────────┐
│ AI Agent │ ── POST /api ────▶ │ Parallel MPP │
│ (with wallet │ │ Gateway │
│ or Stripe) │◀── 402 + payment ──│ │
│ │ requirements │ │
│ │ │ │
│ │ ── POST /api ────▶ │ │
│ │ + payment │ │
│ │ credential │ │
│ │ │ │
│ │◀── 200 + data ─────│ │
└─────────────────┘ └─────────────────┘
```
1. An agent requests a resource from the Parallel MPP gateway
2. The gateway returns `402 Payment Required` with payment details (amount, recipient, currency)
3. The `mppx` client signs a payment credential (via Stripe or Tempo wallet)
4. The agent retries the request with the signed credential attached
5. The gateway verifies payment and returns the requested data
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
Give your Claude-powered applications real-time web search by registering Parallel Search as a tool. This guide shows how to define Parallel Search using Anthropic's Messages API and handle the tool-call loop.
## Overview
Anthropic's [tool use](https://docs.claude.com/en/docs/agents-and-tools/tool-use/overview) lets Claude emit a structured `tool_use` block when it wants to call a function you've defined. Your application executes the function and returns a `tool_result` block in a follow-up `user` message. By registering Parallel Search as a tool, Claude can:
* Search the web for current information
* Access real-time news, research, and facts
* Cite sources with URLs in responses
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
Parallel's APIs are available through the [Amazon Web Services (AWS) Marketplace](https://aws.amazon.com/marketplace/pp/prodview-zpw7j3ozjqlb4).
You can use your AWS account to access all of Parallel's features.
Signing up through AWS allows you to provision resources based on your requirements and pay through your existing AWS billing.
## How to Sign Up Through AWS Marketplace
1. Navigate to [AWS Marketplace](https://us-east-1.console.aws.amazon.com/marketplace/search) and search for
Parallel Web Systems, or go directly to our [product listing](https://aws.amazon.com/marketplace/pp/prodview-zpw7j3ozjqlb4).
2. Click on the product listing, then select `View purchase`.
3. Subscribe to our listing. You can review pricing for different processors
[here](/task-api/guides/choose-a-processor).
4. Click `Set up your account`. You will need to create a new organization linked to your AWS account,
even if you're already part of other organizations. See our
[FAQ](#frequently-asked-questions) for more details.
5. After creating your new organization, you can use our products as usual through our API or
platform interface.
Your usage charges will appear in the AWS Billing & Cloud Management dashboard with your other AWS services.
## Frequently Asked Questions
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
Integrate Browser Use with the Parallel Task API to access authenticated web content and private data during task execution. The Browser Use MCP server enables Parallel to interact with websites through a browser that you configure, allowing access to content behind logins, paywalls, or other authentication barriers.
## Overview
By connecting the [Browser Use](https://browser-use.com) MCP server to your Parallel tasks, you can:
* **Access authenticated content**: Research data behind logins, such as internal dashboards, CRM systems, or subscription services
* **Interact with dynamic web applications**: Navigate SPAs and JavaScript-heavy sites that require browser rendering
* **Automate browser workflows**: Fill forms, click buttons, and navigate multi-step processes as part of research tasks
* **Extract private data**: Pull information from accounts and services that require authentication
## Prerequisites
* A Parallel API key from [Platform](https://platform.parallel.ai)
* A Browser Use API key from [Browser Use](https://browser-use.com)
* For authenticated content: A Browser Use profile with saved login sessions. Profiles are persistent storage containers that maintain your credentials and cookies across browser sessions. See the [Browser Use Profile Documentation](https://docs.cloud.browser-use.com/concepts/profile) for setup instructions.
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
The Parallel plugin for Claude Code gives your coding agent access to live web search, content extraction, deep research, and data enrichment — all available as slash commands and automatic skills directly inside Claude Code.
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
[ClawHub](https://clawhub.ai) is the public skill registry for [OpenClaw](https://openclaw.ai), an open-source AI agent that runs locally on your machine. Parallel publishes four official skills on ClawHub that give OpenClaw access to web search, content extraction, deep research, and data enrichment via the [Parallel CLI](/integrations/cli).
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
The `parallel-cli` is a command-line tool for interacting with the Parallel API. It works interactively or fully via command-line arguments, making it the recommended way to use Parallel in standalone agents. For best results, pair the CLI with [Agent Skills](/integrations/agent-skills) or [Claude Code](/integrations/claude-code-marketplace) to give your agent structured access to search, extract, enrich, and research capabilities.
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
Give Cursor an advanced suite of web search tools for harder tasks that standard search struggles with — available as slash commands and automatic skills directly inside Cursor.
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
Parallel offers three integration paths for developers. The right choice depends on where your agent runs, how it authenticates, and how much control you need.
| Integration | Best for | Auth model | Docs |
| ----------------------------- | -------------------------------------- | ---------------------- | ----------------------------------------------------------------------------------------------------------- |
| **CLI + Skills** | Coding agents with terminal access | API key or OAuth login | [CLI](/integrations/cli), [Agent Skills](/integrations/agent-skills) |
| **MCP Servers** | Chat assistants and LLM-powered apps | OAuth or API key | [MCP Quickstart](/integrations/mcp/quickstart), [Programmatic Use](/integrations/mcp/programmatic-use) |
| **SDK / Native Tool Calling** | Production agents needing full control | API key | [Python](https://pypi.org/project/parallel-web/), [TypeScript](https://www.npmjs.com/package/parallel-web/) |
## Decision guide
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
See [Google Vertex AI](/integrations/google-vertex) for setup instructions.
# Google Vertex AI
Source: https://docs.parallel.ai/integrations/google-vertex
Use Parallel as a grounding provider in Google Vertex AI
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
The Parallel Search API is available in Google Vertex AI as an external grounding provider. Use it to ground Gemini model responses with up-to-date context from the public web.
There are two ways to get started:
| | Google Cloud Marketplace | Bring Your Own Key (BYOK) |
| ------------------ | -------------------------------------- | --------------------------------------------------------------------- |
| **Setup** | Subscribe via Google Cloud Marketplace | Get an API key from [Parallel Platform](https://platform.parallel.ai) |
| **Authentication** | Automatic — no API key needed | API key passed in each request |
| **Billing** | Consolidated through Google Cloud | Billed through Parallel |
| **Quota** | 200 prompts per minute | 200 prompts per minute |
Read Google's official documentation [here](https://docs.cloud.google.com/vertex-ai/generative-ai/docs/grounding/grounding-with-parallel).
## Use cases
* Using web data for information completion or enrichment.
* Multi-hop agents that require deeper web searches for complex questions.
* Building APIs that integrate web search data.
* Employee-facing assistants for up-to-date analysis and reporting.
* Consumer apps (retail, travel) supporting informed purchase decisions.
* Automated agents (e.g., news analysis, KYC checks).
* Vertical agents (sales, coding, finance) fetching the latest context from the web.
## Example
Who won the 2025 Las Vegas F1 Grand Prix?
| Without Grounding | With Grounding |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The 2025 Las Vegas Grand Prix has not happened yet. The race is scheduled to take place on the weekend of November 20-22, 2025. Therefore, the winner is currently unknown. | The winner of the 2025 Las Vegas F1 Grand Prix was Max Verstappen of Red Bull Racing. The race took place on November 22, 2025. Sources: domain1.com, domain2.com, ... |
## Supported models
The following models support Grounding with Parallel web search:
* Gemini 3 Flash
* Gemini 3 Pro Image
* Gemini 2.5 Pro
* Gemini 2.5 Flash
* Gemini 2.5 Flash-Lite
* Gemini 2.5 Flash with Live API native audio
* Gemini 2.0 Flash with Live API
* Gemini 2.0 Flash
## Setup
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
Parallel’s Google Sheets integration brings AI-powered web research and retrieval into your spreadsheets.
Ask a natural‑language question, optionally specify the data to target, and add contextual guidance—all from a single formula.
The integration is designed for creating and enriching datasets in Sheets (e.g., enrichment, summaries, classifications, and quick insights).
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
Add Parallel's search and extract tools and search-powered chat model to your LangChain applications.
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
When building an agent or chat experiences that requires search, deep research, or batch task processing capabilities, it can be a good choice to integrate with our MCPs. When you desire more control over the reasoning and tool descriptions for niche use-cases (if the system prompt isn't sufficient) or want to limit or simplify the tools, it may be better to use the APIs directly to build your own tools, for example using the [AI SDK](https://ai-sdk.dev/docs/ai-sdk-core/tools-and-tool-calling). Using the [MCP-to-AI-SDK](https://github.com/vercel-labs/mcp-to-ai-sdk) is an excellent starting point in that case.
## Authentication
| Server | Default endpoint | API key required? |
| -------------------------------------- | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Search MCP** | `https://search.parallel.ai/mcp` | **No.** Free to use without an `Authorization` header. Pass a Parallel API key as a Bearer token only if you want higher rate limits. OAuth is not available here — clients that do OAuth discovery will not find metadata on this endpoint. |
| **Search MCP (OAuth / auth-enforced)** | `https://search.parallel.ai/mcp-oauth` | Yes. Bearer API key or OAuth. Anonymous requests return `401`. Use this endpoint if you want OAuth sign-in or enforced auth. |
| **Task MCP** | `https://task-mcp.parallel.ai/mcp` | Yes. Either perform the [OAuth flow](/integrations/oauth-provider) or pass your Parallel API key as a Bearer token. |
When passing a Parallel API key, use the provider-specific field:
* **OpenAI Responses API** — `headers: { Authorization: "Bearer
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
## When to use Parallel MCPs?
Our MCP servers are the fastest way to explore what's possible with the Parallel APIs — you can use them without writing any code, and compare results across use cases before integrating at scale.
The Parallel MCP Servers expose Parallel APIs to AI assistants and large language model (LLM) workflows, delivering high-quality, relevant results from the web while optimizing for the price-performance balance your AI applications need at scale.
As can be seen in the following table, our MCPs can be useful for quick experimentation with deep research and task groups, or for daily use.
| Use Case | What |
| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| Agentic applications where low-latency search is a tool call | **[Search MCP](/integrations/mcp/search-mcp)** |
| Daily use for everyday deep-research tasks in chat-based clients | **[Task MCP](/integrations/mcp/task-mcp)** |
| Enriching a dataset (eg. a CSV) with web data via chat-based clients | **[Task MCP](/integrations/mcp/task-mcp)** |
| Running benchmarks on Parallel processors across a series of queries | **[Task MCP](/integrations/mcp/task-mcp)** |
| Building high-scale production apps that integrate with Parallel APIs | **[Search MCP](/integrations/mcp/search-mcp) and [Tasks](/task-api/task-quickstart)** |
## Available MCP Servers
Parallel offers two MCP servers that can be installed in any MCP client. They can also be [used programmatically](/integrations/mcp/programmatic-use) by providing your Parallel API key in the Authorization header as a Bearer token.
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
The Parallel Search MCP Server provides drop-in web search and content extraction capabilities for any MCP-aware model. The tools invoke the [Search API](/search/search-quickstart) and [Extract API](/extract/extract-quickstart) endpoints but present a simpler interface to ensure effective use by agents. Search runs in [`basic` mode](/search/modes) — tuned for low-latency responses inside agent loops — and total excerpts per tool call are capped to roughly 25,000 characters to stay within typical MCP client output limits.
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
The Task MCP Server provides two core capabilities: deep research tasks that generate comprehensive reports, and enrichment tasks that transform existing datasets with web intelligence. Built on the same infrastructure that powers our [Task API](/task-api/task-quickstart), it delivers the highest quality at every price point while eliminating complex integration work.
The Task MCP comprises four tools:
* **`createDeepResearch`** — Initiates a [deep research](/task-api/examples/task-deep-research) task. Use for complex questions that need thorough multi-step research with citations, where depth matters more than latency.
* **`createTaskGroup`** — Initiates a [task group](/task-api/group-api) to enrich multiple items in parallel. Use for lists or tabular data (CSV uploads, company lists, entity tables) that need consistent web-sourced fields per row.
* **`getStatus`** — Lightweight status check for an in-flight task (\~50 tokens). Use this when polling instead of fetching the full result.
* **`getResultMarkdown`** — Retrieves the final output from a deep research or task group in an LLM-friendly markdown format. Call once the task is complete.
The Task MCP Server uses an async architecture that lets agents start research tasks and continue executing other work without blocking. This allows spawning any number of tasks in parallel while continuing the conversation. Due to current MCP and LLM client limitations, you need to request the result tool call in an additional turn after results are ready.
The Task MCP works best when following this process:
1. **Choose a data source** - See [Enrichment data sources and destinations](#enrichment-data-sources-and-destinations).
2. **Initiate your tasks** - After you have your initial data, the MCP can initiate deep research or task groups. See [Use cases](#use-cases) for inspiration.
3. **Analyze the results** - The LLM provides a link to view progress as results come in. After completion, prompt the LLM to analyze the results and answer your questions.
## One-Click Install
Install in any of the following clients with a single click.
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
Integrate Parallel's AI-powered web research directly into your n8n workflows with our community node package.
## Installation
Install the community node directly in n8n through the Community Nodes section in your n8n settings.
**Links:**
* [NPM Package](https://www.npmjs.com/package/n8n-nodes-parallel)
* [n8n Integration Hub](https://n8n.io/integrations/parallel/)
## Available Nodes
| Node | Operation | Description | Use Case |
| ---------------------------------------- | -------------------- | --------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| **Parallel Node** | Sync Web Enrichment | Execute tasks synchronously (up to 5 minutes) | Lead enrichment, competitive analysis, content research |
| **Parallel Node** | Async Web Enrichment | Long-running research tasks (up to 30 minutes) | Complex multi-source research, deep competitive intelligence |
| **Parallel Node** | Web Search | AI-powered web search with domain filtering | Natural language search with structured results and citations |
| **Parallel Node** | Web Chat | Real-time web-informed AI responses (\< 5 seconds) | Current events queries, fact-checking, research-backed conversations |
| **Parallel Task Run Completion Trigger** | Webhook Trigger | Automatically trigger workflows when async tasks complete | Use with Async Web Enrichment - paste trigger webhook URL into the async node's "Webhook URL" field |
## Common Use Cases
* **Sales**: Lead scoring, account research, contact discovery
* **Marketing**: Content research, trend analysis, competitor monitoring
* **Operations**: Vendor research, risk assessment, due diligence
* **Support**: Real-time information lookup, documentation generation
For detailed configuration and advanced features, see the [Task API guide](../task-api/task-quickstart).
# OAuth Provider
Source: https://docs.parallel.ai/integrations/oauth-provider
Integrate with the Parallel OAuth Provider to get a Parallel API key on behalf of your users
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
Parallel provides an OAuth 2.0 provider that allows applications to securely access user API keys with explicit user consent. This enables building applications that can make API calls to Parallel on behalf of users without requiring them to manually share their API keys.
## Provider URL
**[https://platform.parallel.ai](https://platform.parallel.ai)**
## Quick Start
### 1. Start Authorization Flow
```javascript theme={"system"}
// Generate PKCE parameters
function generatePKCE() {
const codeVerifier = btoa(crypto.getRandomValues(new Uint8Array(32))).replace(
/[+/=]/g,
(m) => ({ "+": "-", "/": "_", "=": "" }[m])
);
return crypto.subtle
.digest("SHA-256", new TextEncoder().encode(codeVerifier))
.then((hash) => ({
codeVerifier,
codeChallenge: btoa(String.fromCharCode(...new Uint8Array(hash))).replace(
/[+/=]/g,
(m) => ({ "+": "-", "/": "_", "=": "" }[m])
),
}));
}
// Redirect user to authorization
const { codeVerifier, codeChallenge } = await generatePKCE();
localStorage.setItem("code_verifier", codeVerifier);
const authUrl = new URL("https://platform.parallel.ai/getKeys/authorize");
authUrl.searchParams.set("client_id", "yourapp.com");
authUrl.searchParams.set("redirect_uri", "https://yourapp.com/callback");
authUrl.searchParams.set("response_type", "code");
authUrl.searchParams.set("scope", "key:read");
authUrl.searchParams.set("code_challenge", codeChallenge);
authUrl.searchParams.set("code_challenge_method", "S256");
authUrl.searchParams.set("state", "random-state-value");
window.location.href = authUrl.toString();
```
### 2. Handle Callback & Exchange Code
```javascript theme={"system"}
// On your callback page
const urlParams = new URLSearchParams(window.location.search);
const code = urlParams.get("code");
const codeVerifier = localStorage.getItem("code_verifier");
const response = await fetch("https://platform.parallel.ai/getKeys/token", {
method: "POST",
headers: { "Content-Type": "application/x-www-form-urlencoded" },
body: new URLSearchParams({
grant_type: "authorization_code",
code: code,
client_id: "yourapp.com",
redirect_uri: "https://yourapp.com/callback",
code_verifier: codeVerifier,
}),
});
const { access_token } = await response.json();
// access_token is the user's Parallel API key
```
### 3. Use the API Key
```javascript theme={"system"}
const response = await fetch("https://api.parallel.ai/v1/tasks/runs", {
method: "POST",
headers: {
"x-api-key": access_token,
"Content-Type": "application/json",
},
body: JSON.stringify({
input: "What was the GDP of France in 2023?",
processor: "base",
}),
});
const taskRun = await response.json();
console.log(taskRun.run_id);
```
## Authentication Flow
The OAuth flow follows these steps:
1. **Authorization Request**: Redirect user to Parallel's authorization endpoint
2. **User Consent**: User sees your application hostname and grants permission
3. **API Key Selection**: User selects an existing API key or generates a new one
4. **Authorization Code**: User is redirected back with an authorization code
5. **Token Exchange**: Exchange the code for the user's API key using PKCE
## Features
* **PKCE Required**: Code challenge/verifier mandatory for all clients
* **No Client Secret**: Public client design - no secrets to manage
* **User Consent**: Users explicitly approve each application by hostname
* **One-Time Codes**: Authorization codes can only be used once
* **Direct Access**: The `access_token` returned is the user's actual Parallel API key
## MCP Compatibility
This OAuth provider is fully compatible with the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization) specification for authorization. MCP clients can discover and use this OAuth provider automatically through the well-known endpoints at `/.well-known/oauth-authorization-server`.
You can see an example of this OAuth provider being used in practice in the [Parallel Tasks SSE recipe](https://github.com/parallel-web/parallel-cookbook/blob/main/typescript-recipes/parallel-tasks-sse/index.html).
# Ollama Tool Calling
Source: https://docs.parallel.ai/integrations/ollama-tool-calling
Use Parallel Search as a tool with local Ollama models for real-time web access
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
Give locally-hosted models running under [Ollama](https://ollama.com) real-time web search by registering Parallel Search as a tool. This guide uses Ollama's native Python SDK, which derives the tool schema directly from your function signature and docstring.
## Overview
Modern Ollama models (Qwen 3.5, Gemma 4, Llama 3.1+) support [native tool calling](https://docs.ollama.com/capabilities/tool-calling): you pass `tools=[...]` on a chat call, the model emits structured `tool_calls`, your code executes them, and you feed results back in a follow-up turn. By registering Parallel Search as a tool, your local model can:
* Search the web for current information
* Access real-time news, research, and facts
* Cite sources with URLs in responses
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
Give your OpenAI-powered applications real-time web search capabilities by integrating Parallel Search as a tool. This guide shows how to define Parallel Search as an OpenAI function and handle tool calls in your application.
## Overview
OpenAI's [tool calling](https://platform.openai.com/docs/guides/function-calling) (formerly function calling) allows GPT models to output structured JSON indicating they want to call a function you've defined. Your application then executes the function and returns results to the model. By defining Parallel Search as a tool, your model can:
* Search the web for current information
* Access real-time news, research, and facts
* Cite sources with URLs in responses
## Prerequisites
1. Get your Parallel API key from [Platform](https://platform.parallel.ai)
2. Get your OpenAI API key from [OpenAI](https://platform.openai.com/api-keys)
3. Install the required SDKs:
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
The Parallel plugin for [OpenCode](https://opencode.ai) adds `parallel-search` and `parallel-fetch` tools to your coding agent. Once configured, any requests to search the web or fetch a webpage will automatically use Parallel.
**Why use Parallel tools?**
* More accurate and relevant search results
* Intelligent content extraction that understands page structure
* Extended excerpts optimized for LLM context windows
* Faster and more reliable than built-in alternatives
## Setup
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
Integrate Parallel's AI-powered web intelligence with Superhuman to bring real-time web data
into your writing.
## Installation
* Search for Parallel on the Superhuman agent store and install.
* Or install the agent integration directly [here](https://superhuman.com/store/agents/parallel-web-intelligence-45397).
## Available Skills
* **Verify claims and suggest modifications**: verify any claims made in your writing and have the agent suggest modifications
inplace.
* **Generate citations**: for any text, ask the agent to generate citations that you can use to establish
authenticity and provenance
* **Write or extend a report**: for any topic or a partial report, ask the agent to write a report or if the report is already
partially complete, complete it
## Tips
* Keep the context small and verify claims as you go instead of verifying claims for a long text at once.
* Ask the agent to verify claims to trigger the claim verification skill
* To get the agent to generate citations, ask it to generate citations in the Superhuman chat box.
# Vercel
Source: https://docs.parallel.ai/integrations/vercel
Use Parallel with Vercel
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
Use Parallel Search in the Vercel AI SDK. Get started quickly by installing Parallel in the Vercel Agent Marketplace.
## Vercel AI Gateway
Parallel Search is available as a built-in tool in [Vercel AI Gateway](https://vercel.com/docs/ai-gateway). AI Gateway provides a unified API to access hundreds of models through a single endpoint, with built-in web search capabilities.
The `parallelSearch` tool can be used with any model regardless of the model provider. When the model needs current information, it calls the tool and AI Gateway routes the request to Parallel's Search API.
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
Integrate Parallel's AI-powered web research into your Zapier workflows with our official app.
## Installation
Search for "Parallel Web Systems" when adding a step to your Zap,
or use [this link](https://zapier.com/apps/parallel-web-systems/integrations) to get started.
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
Monitors produce a stream of events on each execution. Every event object has an `event_type` field that discriminates the variant:
| `event_type` | Description |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `event_stream` | A new material change detected by an event\_stream monitor. See [Event Stream Quickstart](/monitor-api/monitor-quickstart). |
| `snapshot` | A change to the monitored task output detected by a snapshot monitor. See [Snapshot Quickstart](/monitor-api/quickstart-snapshot). |
| `completion` | Execution completed with no new detections. |
| `error` | Execution failed. |
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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 enumerates the contract differences between the Alpha Monitor API (`/v1alpha/monitors`) and the GA version (`/v1/monitors`), and outlines the steps required to migrate.
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
Define a query once and Monitor continuously watches the web for new, relevant updates—surfacing only what changed and delivering it to your systems via webhook. No cron jobs, no manual polling, no custom deduplication pipelines.
**Use cases:**
* **Finance and investing**: Fund activity, M\&A signals, earnings releases, new investment announcements
* **People and companies**: Executive changes, hiring signals, office openings, competitive product launches
* **Sciences**: Clinical trial updates, regulatory submissions, drug pipeline changes, research publications
* **Legal and policy**: Regulatory rule changes, enforcement actions, compliance updates across jurisdictions
* **eCommerce**: Pricing changes, stock availability, product listing updates
* **Real estate**: Listing changes, zoning updates, market reports
## Best Practices
1. **Scope your query**: Intent-heavy natural language outperforms keyword strings. Describe what you're looking for, not how to find it.
2. **Choose the right frequency**: `"1h"` for fast-moving topics, `"1d"` for most news and signals, `"1w"` for slower changes.
3. **Pick a processor**: `"lite"` (default) handles routine queries; `"base"` increases recall and breadth for harder queries, at higher cost.
4. **Use webhooks**: Push delivery is lower latency than polling and requires no infrastructure to maintain.
5. **Cancel unused monitors**: Reduces usage costs.
6. **Don't use for historical research**: Monitor tracks new updates from the time of creation. Use [Deep Research](/task-api/examples/task-deep-research) for retrospective queries.
### Writing Effective Queries
| ❌ Avoid | ✅ Prefer |
| -------------------------------------------------- | ---------------------------------------------------------------------- |
| `"Parallel OR Parallel AI AND Funding OR Launch"` | `"Parallel Web Systems (parallel.ai) funding or launch announcements"` |
| `"Find all AI funding news from the last 2 years"` | `"AI startup funding announcements"` |
| `"Tesla news after December 12, 2025"` | `"Tesla news and announcements"` |
## Prerequisites
Generate your API key on [Platform](https://platform.parallel.ai). Python and TypeScript SDKs are also available (`pip install parallel-web` / `npm install parallel-web`).
```bash theme={"system"}
export PARALLEL_API_KEY="PARALLEL_API_KEY"
```
***
## Event Stream Quickstart
### Step 1. Create a monitor
Create a monitor that tracks daily AI funding news:
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
The Parallel Slack app brings [Monitor](/monitor-api/monitor-quickstart) directly into your Slack workspace. Create monitors with slash commands and receive updates in dedicated threads.
## Installation
1. Go to [platform.parallel.ai](https://platform.parallel.ai) and navigate to the Integrations section
2. Click **Add to Slack** to begin the OAuth flow
3. Authorize the Parallel app in your workspace
4. Invite the bot to any channel where you want to use monitoring: `/invite @Parallel`
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
Monitor events can feed directly into a Task API call to go deeper on any detected signal. Use follow-up tasks to enrich a signal with structured fields or launch a full research report—without any manual handoff. The flow is the same in both cases: receive a webhook, fetch the event, pass its `output.content` as the `input` and its `event_id` as `previous_interaction_id` to a new Task Run.
Passing `event_id` as `previous_interaction_id` carries the monitor event's full context forward into the Task run, preserving provenance through every step of the chain. See [Interactions](/task-api/guides/interactions) for details.
## Scenario 1: Structured Enrichment on a Detected Event
Use this when you want to extract machine-readable fields from a detected event—for example, pulling `company`, `amount`, and `round` from a funding announcement.
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
A snapshot monitor watches the output of a Task Run on a schedule. Each execution re-runs the same task and compares the result against the previous snapshot. When the system detects a material change—new data, a removed field, a significant value shift—it fires a webhook.
Snapshot monitors work with **any** task output—text or structured JSON, `base`, `core`, `pro`, `ultra`, or any other processor. They are especially powerful for **structured enrichment tasks**, where the JSON schema acts as a stable template the monitor can diff field-by-field across runs, surfacing precisely which properties changed and why.
This gives you task cron with built-in deduplication and reasoning about what actually changed, at a fraction of the cost of running full Task API calls independently.
**Typical use cases:**
* Executive team or board changes at a company
* Competitor pricing or product page updates
* Regulatory filing status changes
* Job posting additions or removals
* Periodic deep-research briefs on a watchlist of companies, people, or topics
## Prerequisites
Generate your API key on [Platform](https://platform.parallel.ai):
```bash theme={"system"}
export PARALLEL_API_KEY="PARALLEL_API_KEY"
```
***
## Step 1. Create a Task Run to establish a baseline
A snapshot monitor requires a completed Task Run as its starting point. The run's input, processor, and output schema become the template the monitor re-executes on each tick. Any Task Run works—free-form text outputs are diffed as a whole, while structured JSON outputs are diffed field-by-field for the most precise change detection.
The example below uses a **structured enrichment task** that extracts the executive team of a company. Structured outputs are recommended whenever you care about specific fields (prices, statuses, lists of entities) rather than narrative text:
```bash cURL theme={"system"}
curl --request POST \
--url https://api.parallel.ai/v1/tasks/runs \
--header 'Content-Type: application/json' \
--header "x-api-key: $PARALLEL_API_KEY" \
--data '{
"input": "Who are the current C-suite executives at Acme Corp (acme.com)?",
"processor": "base",
"output_schema": {
"type": "json",
"json_schema": {
"type": "object",
"properties": {
"executives": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": { "type": "string" },
"title": { "type": "string" }
}
}
}
}
}
}
}'
```
**Response:**
```json theme={"system"}
{
"run_id": "taskrun_a1b2c3d4e5f6",
"status": "queued"
}
```
Wait for the run to complete (poll `GET /v1/tasks/runs/{run_id}` or use a webhook). Once `status` is `"completed"`, note the `run_id`—you'll use it in the next step.
See [Task API Quickstart](/task-api/examples/task-enrichment) for full details on creating and polling task runs.
## Step 2. Create a snapshot monitor
Create a snapshot monitor that re-runs the same task weekly and fires when the output changes:
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
## ShapBot
ShapBot helps discover and index websites for Parallel's web APIs. To maximize your site's visibility in search results, we suggest allowing ShapBot access in your robots.txt configuration and permitting connections from our designated IP ranges.
Full user-agent string: Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko); compatible; ShapBot/0.1.0
For the complete list of ShapBot IPs, see [shapbot.json](https://docs.parallel.ai/resources/shapbot.json).
## Contact & Support
If you have questions about our crawlers or need assistance, please contact us at [support@parallel.ai](mailto:support@parallel.ai)
## Changes to This Documentation
We may update this documentation periodically to reflect changes in our crawler behavior or policies. Please check back regularly for updates.
# FAQs
Source: https://docs.parallel.ai/resources/faqs
Frequently asked questions about Parallel APIs, billing, security, and platform features
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
## Platform
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
The Source Policy feature allows you to precisely control which domains Parallel processors can
access during web research and to apply a freshness constraint. It's available for both Tasks and
Web Tools and lets you tailor search results by specifying domains to include or exclude and by
setting a start date so results are limited to recent content.
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
# Warnings and Errors
Source: https://docs.parallel.ai/resources/warnings-and-errors
Breakdown of warnings and errors
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
The Task API may return various warnings and errors during operation. This page documents the possible error types you might encounter when using the API.
## Errors
Errors result in a failure to process your request and are returned with appropriate HTTP status codes (4xx or 5xx).
| Error | Description | Resolution |
| ------------------------------ | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| **Invalid JSON Schema** | The JSON schema provided in the task spec for input or output is invalid. | Review your schema against JSON Schema specifications and ensure it follows the required format. |
| **Task Spec + Input Too Long** | The combined task specification and input exceeds 25,000 characters. | Reduce the size of your task spec or input data. Consider splitting into multiple tasks if necessary. |
| **Too-Complex Output Schema** | The output schema exceeds allowed complexity in terms of nesting depth or number of fields. | Simplify your output schema by reducing nested levels to 3 or less. |
## Warnings
Warnings indicate potential issues that don't prevent the request from being processed but may affect results.
| Warning | Description | Resolution |
| ------------------------------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| **Input Fails Validation** | The provided input does not conform to the input schema. | Verify your input against the schema requirements and make necessary adjustments. |
| **Task Spec + Input Over Size Limit** | The combined task specification and input exceeds the character limit. | Consider optimizing your input or task spec for better performance. |
| **Too Many Output Fields** | The number of requested output fields exceeds the recommended limit. | Consider reducing the number of output fields. |
## Warning Handling
The Task API uses a warning system to provide guidance without blocking execution. Warnings are generated during validation and can be handled in two ways:
### Basis Properties
It is recommended to use `FieldBasis` in the run output rather than requesting similar information in the output schema.
This means you've included fields like `citations`, `reasoning`, or `sources` in your output schema, but this information is **already provided automatically** in every Task Run result through the [Basis](/task-api/guides/access-research-basis) feature.
**What is Basis?** Every Task Run result includes a `basis` array containing citations, reasoning, and confidence levels for each output field. This is provided automatically; you don't need to request it in your schema.
**Why not include these in the output schema?**
* **Redundant**: You'll get duplicate data, wasting tokens and processing
* **Less structured**: The automatic Basis provides properly structured citations with URLs and excerpts
* **Less reliable**: Asking the model to generate its own citations may produce less accurate results than the built-in citation tracking
The following field names trigger this warning:
* `citations`
* `confidence`
* `evidence`
* `reasoning`
* `source`
* `sources`
* `source_urls`
**Instead of this:**
```json theme={"system"}
{
"properties": {
"company_name": { "type": "string" },
"reasoning": { "type": "string" },
"sources": { "type": "array", "items": { "type": "string" } }
}
}
```
**Do this:**
```json theme={"system"}
{
"properties": {
"company_name": { "type": "string" }
}
}
```
Then access `output.basis` in the response to get citations, reasoning, and confidence for each field. See [Accessing Research Basis](/task-api/guides/access-research-basis) for details.
## Error Reference
| Status Code | Meaning | Retry? | Description | Resolution Approach |
| ----------- | --------------------- | ------ | ------------------------------- | ---------------------------------------------------------------------- |
| **401** | Unauthorized | No | Invalid or missing credentials | Verify API key and authentication headers |
| **402** | Payment Required | No | Insufficient credit in account | See [402 Troubleshooting](#402-payment-required-troubleshooting) below |
| **403** | Forbidden | No | Invalid processor in request | Check processor availability and permissions |
| **404** | Not Found | No | Run ID or resource not found | Verify run ID and resource existence |
| **408** | Request Timeout | Yes | Synchronous request timed out | Use asynchronous polling |
| **422** | Unprocessable Content | No | Request validation failed | Review error details and validate schema |
| **429** | Too Many Requests | Yes | Rate limited or quota exceeded | Implement exponential backoff |
| **500** | Internal Server Error | Yes | Server-side processing error | Retry with backoff, contact support if persistent |
| **502** | Bad Gateway | Yes | Upstream service error | Retry, usually temporary |
| **503** | Service Unavailable | Yes | Service temporarily unavailable | Retry with backoff |
## Error Response Format
All errors return a consistent JSON structure:
```json theme={"system"}
{
"error": {
"message": "Human-readable error description",
"detail": {
// Additional error-specific information
}
}
}
```
For validation errors (422), the `detail` field contains specific information about which fields failed validation and why.
## 402 Payment Required Troubleshooting
A 402 error indicates your account has insufficient credits to process the request. This can occur even if your account shows a positive balance due to **in-flight balance reservations**.
### Understanding In-Flight Balance
When you submit a task, the system reserves credits for the estimated cost before processing begins. This reservation is called the "in-flight balance." Your **available balance** equals your **total balance** minus the **in-flight balance** from all currently running tasks.
**Example scenario:**
* Account balance: \$10.00
* 5 running `pro` tasks (each reserves \~$0.10): $0.50 reserved
* Available balance: \$9.50
If your available balance is insufficient for a new task, you'll receive a 402 error even though your total balance appears positive.
### Common Causes
| Cause | Solution |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| **Multiple concurrent tasks** | Running many tasks simultaneously reserves credits for each. Wait for some to complete or reduce concurrency. |
| **Higher-tier processors** | `ultra` and `pro` processors reserve more credits than `base` or `lite`. Consider using lower-tier processors for less complex tasks. |
| **Insufficient account balance** | Add credits at [platform.parallel.ai](https://platform.parallel.ai). |
| **Large task groups** | Task groups reserve credits for all runs upfront. Split into smaller batches if needed. |
### How to Resolve
1. **Check your balance**: View your current balance and usage at [platform.parallel.ai](https://platform.parallel.ai)
2. **Wait for tasks to complete**: In-flight reservations are released when tasks finish
3. **Add credits**: Top up your account balance if genuinely low
4. **Reduce concurrency**: Lower the number of parallel tasks to reduce reserved credits
5. **Use lower-tier processors**: Reserve fewer credits per task by using `base` or `lite` processors where appropriate
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
## Overview
Webhooks allow you to receive real-time notifications when events occur in your Parallel API operations, eliminating the need for constant polling. Our webhooks follow [standard webhook conventions](https://github.com/standard-webhooks/standard-webhooks/blob/main/spec/standard-webhooks.md) to ensure security and interoperability.
## Setup
### 1. Record your webhook secret
Go to **Settings → Webhooks** to view your account webhook secret. You'll need this to verify webhook signatures.
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
The `advanced_settings` object on the Search API lets you tune source selection, freshness, excerpt sizing, geo-targeting, and result count. Most callers don't need it — the defaults are chosen to produce the best results for typical requests, and setting these knobs unnecessarily can hurt quality or latency.
## Fields
| Field | Type | Notes | Example |
| ----------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------- |
| source\_policy | [SourcePolicy](/resources/source-policy) | Controls your sources: include/exclude specific domains and optionally set a start date for freshness control via `after_date`. Can significantly reduce result quality by excluding relevant pages — use only when absolutely necessary. See [Using include\_domains](#using-include_domains) below. | [Source policy example](/resources/source-policy#example) |
| fetch\_policy | object | Controls when to return indexed content (faster) vs fetching live content (fresher). Default is to use cached content from the index. Enabling live fetch significantly increases latency. For more info including field details, see [Fetch Policy](/extract/advanced-extract-settings#fetch-policy). | `{"max_age_seconds": 3600}` |
| excerpt\_settings | object | Controls excerpt sizes. Provide `max_chars_per_result` for fine-grained control, or omit to use defaults. | `{"max_chars_per_result": 10000}` |
| location | string | ISO 3166-1 alpha-2 country code for geo-targeted search results. Only a subset of countries are currently supported; unsupported or invalid values (e.g., `"uk"`) are ignored with a warning. | `"us"`, `"gb"`, `"de"`, `"jp"` |
| max\_results | int | Upper bound on the number of results to return. Defaults to 10 if not provided. | 10 |
## Using include\_domains
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
The Search API returns ranked, LLM-optimized excerpts from web sources based on natural
language objectives or keyword queries. Results are designed to serve directly as model
input, enabling faster reasoning and higher-quality completions with minimal
post-processing.
The guidance below applies whether you call the API directly or your model fills **`objective`** and **`search_queries`** through function calling. For the copy-paste tool schema, jump to [Search Tool Definition](#search-tool-definition) below.
## Key Benefits
* **Context engineering for token efficiency**: The API ranks and compresses web results based on reasoning utility rather than human engagement, delivering the most relevant tokens for each agent's specific objective.
* **Single-hop resolution of complex queries**: Where traditional search forces agents to make multiple sequential calls, accumulating latency and costs, Parallel resolves complex multi-topic queries in a single request.
* **Multi-hop efficiency**: For deep research workflows requiring multiple reasoning steps, agents using Parallel complete tasks in fewer tool calls while achieving higher accuracy and lower end-to-end latency.
## Request Fields
`search_queries` is required (at least one non-empty query). The remaining
fields are optional. See the [API
Reference](/api-reference/search/search) for complete parameter
specifications and constraints.
| Field | Type | Notes | Example |
| ------------------ | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| search\_queries | string\[] | Concise keyword search queries, 3-6 words each. At least one query is required; provide 2-3 for best results. Maximum 5 queries, 200 characters per query. | `["Parallel Web Systems products", "Parallel Web Systems announcements"]` |
| objective | string | Natural-language description of the web research goal, including source or freshness guidance and broader context from the task. Maximum 5000 characters. | "Find latest information about Parallel Web Systems. Focus on new product releases, benchmarks, or company announcements." |
| mode | string | Presets with varying trade-off profiles for different types of use cases. See [Modes](/search/modes) for details. Defaults to `advanced`. | `"advanced"` |
| max\_chars\_total | int | Upper bound on total characters across excerpts from all results. Default is dynamic based on search\_queries, objective, and client\_model. | 50000 |
| client\_model | string | The model generating this request and consuming the results. Enables optimizations tailored to the model's capabilities. | `"claude-opus-4-7"`, `"gpt-5.4"`, `"gemini-3.1-pro"` |
| session\_id | string | Optional identifier for grouping related calls. Use the same `session_id` across search and extract calls that are part of the same task, and a new unique id for each new task. Any string works — use one meaningful in your app, or reuse a `session_id` returned by an earlier search or extract call. UUIDs work well — See [Session Identifiers](#session-identifiers) below. | `"session_
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
The `mode` parameter presets defaults for different use cases. Defaults to `advanced` if not specified.
* **`basic`**: Offers lower latency and works best with 2-3 high-quality search\_queries. Best for real-time applications where speed is critical, such as foreground agents where lower latency is important.
* **`advanced`** (default): Uses a more advanced retrieval and compression pipeline for higher-quality results. Best for complex queries where result quality matters more than latency, such as background agents.
## Example
Using basic mode:
```json theme={"system"}
{
"mode": "basic",
"objective": "What are the latest advances in quantum error correction?",
"search_queries": ["quantum error correction 2026", "QEC algorithms"]
}
```
# Search MCP
Source: https://docs.parallel.ai/search/search-mcp
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
# Search Migration Guide: Beta to GA
Source: https://docs.parallel.ai/search/search-migration-guide
Migrate from Beta to GA (V1) Search API
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`).
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
The **Search API** takes a natural language objective and returns relevant excerpts
optimized for LLMs, replacing multiple keyword searches with a single call for broad or
complex queries.
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
# Interactive Research
Source: https://docs.parallel.ai/task-api/examples/interactive-research
Build an interactive research app with multi-turn context chaining
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
## Overview
This guide walks through building an interactive research application using [interactions](/task-api/guides/interactions). By chaining `interaction_id` values across requests, each follow-up question automatically has the full context of prior turns — so you can drill deeper into a topic without restating what was already researched.
## Example: Multi-Turn Research Session
Consider a research session where each question builds on the last:
1. **"Which country won the most Winter Olympics gold medals in 2026?"** — initial broad question
2. **"How many medals did they win?"** — a follow-up that only makes sense with context from step 1
3. **"How does that compare to the second place country?"** — drills deeper into the same thread
Without interactions, each request would be independent and the API wouldn't know what "they" or "second place" refers to. With interactions, context carries forward automatically.
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
## Overview
Deep Research is designed for open-ended research questions where you don't have structured input data to enrich. Instead of bringing data to enhance, you bring a research question or topic, and the Task API conducts comprehensive multi-step web exploration to deliver analyst-grade intelligence.
This powerful capability compresses hours of manual research into minutes, delivering high-quality intelligence at scale. Optimized within the `pro` and `ultra` [processor families](/task-api/guides/choose-a-processor), Deep Research transforms natural language research queries into comprehensive reports complete with inline citations and verification.
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
## What is Enrichment?
Enrichment is when you have existing structured data—like a list of companies, products, or contacts—and want to enhance it with additional information from the web. The Task API makes it easy to define what data you have and what additional fields you need, then automatically researches and populates those fields at scale.
## How Enrichment Works
With enrichment, you define two schemas:
1. **Input Schema**: The data fields you already have (e.g., company name, website)
2. **Output Schema**: The new fields you want to add (e.g., employee count, funding sources, founding date)
The Task API researches the web and populates your output fields with accurate, cited information.
## 1. Set up Prerequisites
Generate your API key on [Platform](https://platform.parallel.ai). Then, set up with the TypeScript SDK, Python SDK or with cURL:
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
The Parallel Task Group API enables you to batch process hundreds or thousands of Tasks efficiently. Instead of running Tasks one by one, you can organize them into groups, monitor their progress collectively, and retrieve results in bulk. The API is comprised of the following endpoints:
**Creation**: To run a batch of tasks in a group, you first need to create a task group, after which you can add runs to it, which will be queued and processed.
* `POST /v1/tasks/groups` (Create task-group)
* `POST /v1/tasks/groups/{taskgroup_id}/runs` (Add runs. Up to 1,000 runs per POST request.)
**Progress Snapshot**: At any moment during the task, you can get an instant snapshot of the state of it using `GET /{taskgroup_id}` and `GET /{taskgroup_id}/runs`. Please note that the runs endpoint streams back the requested runs instantly (using SSE) to allow for large payloads without pagination, and it doesn't wait for runs to complete. Runs in a task group are stored indefinitely, so unless you have high performance requirements, you may not need to keep your own state of the intermediate results. However, it's recommended to still do so after the task group is completed.
* `GET /v1/tasks/groups/{taskgroup_id}` (Get task-group summary)
* `GET /v1/tasks/groups/{taskgroup_id}/runs` (Fetch task group runs)
**Realtime updates**: You may want to provide efficient real-time updates to your app. For a high-level summary and run completion events, you can use `GET /{taskgroup_id}/events`. To also retrieve the task run result upon completion you can use the [task run endpoint](/api-reference/tasks/retrieve-task-run-result)
* `GET /v1/tasks/groups/{taskgroup_id}/events` (Stream task-group events)
* `GET /v1/tasks/runs/{run_id}/result` (Get task-run result)
To determine whether a task group is fully completed, you can either use realtime update events, or you can poll the task-group summary endpoint. You can also keep adding runs to your task group indefinitely.
## Key Concepts
### Task Groups
A Task Group is a container that organizes multiple task runs. Each group has:
* A unique `taskgroup_id` for identification
* A status object with `is_active` (boolean) and `task_run_status_counts` (counts by status)
* The ability to add new Tasks dynamically
### Group Status
Track progress with real-time status updates:
* Total number of task runs
* Count of runs by status (queued, running, completed, failed)
* Whether the group is still active (`is_active` becomes `false` when all runs finish)
* Human-readable status messages
## Quick Start
### 1. Define Types and Task Structure
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
When you execute a task using the Task API, the response includes both the generated output and its corresponding research basis—a structured explanation detailing the reasoning and evidence behind each result. This transparency enables you to understand how the system arrived at its conclusions and to assess the reliability of the output.
## Terminology
To avoid confusion, this document uses the following terminology:
* **Research Basis**: The overall feature that provides transparency into how Task API results are generated
* **Basis**: The `basis` field in the API response, which contains an array of field-specific evidence
* **FieldBasis**: The specific object type that contains citations, reasoning, and confidence for individual output fields
## Task Run Result
Every Task Run Result object contains the following fields:
| Field | Type | Description |
| -------- | ---------------------------- | ------------------------------------------------------------------------------------------ |
| `run` | object | Task Run object with status and id, detailed above. |
| `output` | TaskRunOutput object or null | Output from the task conforming to the output schema. Present iff run.status == completed. |
A TaskRunOutput object can be one of two types:
* TaskRunTextOutput
* TaskRunJsonOutput
Both have the following fields:
| Field | Type | Description |
| --------- | ------------------ | ---------------------------------------------------------------------------------------------- |
| `content` | string | JSON or plain text according to the output schema. |
| `basis` | array\[FieldBasis] | Array of FieldBasis objects, one for each top-level output field. See FieldBasis object below. |
| `type` | string | Always `text` |
## Research Basis Structure
The `basis` field contains an array of FieldBasis objects that correspond to each top-level field in your output. This allows you to trace exactly which sources on the web contributed to each specific piece of information in your result.
```mermaid theme={"system"}
graph TD
TaskRunResult[Task Run Result]
TaskRunOutput[Task Run Output]
Content[Output Content]
Basis[Output Basis]
TaskRunResult --> TaskRunOutput
TaskRunOutput --> Content
TaskRunOutput --> Basis
Content --> Field1["Company: Microsoft"]
Content --> Field2["Founded: 1975"]
Basis --> BasisField1[Basis for Company]
Basis --> BasisField2[Basis for Founded]
BasisField1 --> C1[Citations + Reasoning]
BasisField2 --> C2[Citations + Reasoning]
style TaskRunResult fill:#FCFCFA,stroke:#1D1B16,stroke-width:1px,color:#1D1B16
style TaskRunOutput fill:#FCFCFA,stroke:#1D1B16,stroke-width:1px,color:#1D1B16
style Content fill:#FCFCFA,stroke:#1D1B16,stroke-width:1px,color:#1D1B16
style Field1 fill:#FCFCFA,stroke:#1D1B16,stroke-width:1px,color:#1D1B16
style Field2 fill:#FCFCFA,stroke:#1D1B16,stroke-width:1px,color:#1D1B16
style Basis fill:#D8D0BF,stroke:#1D1B16,stroke-width:1px,color:#1D1B16
style BasisField1 fill:#D8D0BF,stroke:#1D1B16,stroke-width:1px,color:#1D1B16
style BasisField2 fill:#D8D0BF,stroke:#1D1B16,stroke-width:1px,color:#1D1B16
style C1 fill:#FB631B,stroke:#1D1B16,stroke-width:1px,color:#1D1B16
style C2 fill:#FB631B,stroke:#1D1B16,stroke-width:1px,color:#1D1B16
```
## The FieldBasis object
Each FieldBasis object has these components:
| Field | Type | Description |
| ------------ | ---------------- | ------------------------------------------------------- |
| `field` | string | Name of the corresponding output field |
| `citations` | array\[Citation] | List of web sources supporting the output field |
| `reasoning` | string | Explanation of how the system processed the information |
| `confidence` | string or null | Reliability rating for each output field |
### Citations
Citations provide the exact URLs where information was found. Each citation includes excerpts from the source that contributed to the output:
| Field | Type | Description |
| ---------- | ---------------------- | ----------------------------- |
| `url` | string | The source URL |
| `excerpts` | array\[string] or null | Relevant text from the source |
Having multiple citations for an output field often indicates stronger evidence, as the information was verified across multiple sources.
### Reasoning
The reasoning field explains how the system evaluated, compared, and synthesized information from different sources. This is particularly valuable when:
* Information from different sources needed to be reconciled
* Calculations or conversions were performed
* The system needed to make judgments about conflicting data
### Confidence Levels
All processors include a confidence rating for each output field:
* **High**: Strong evidence from multiple authoritative sources with consistent information
* **Medium**: Adequate evidence but with some inconsistencies or from less authoritative sources
* **Low**: Limited or conflicting evidence, or information from less reliable sources
### Per-element Basis (beta)
By default, `basis` entries are emitted only for the top-level fields in your output schema.
If a top-level field is an array and you need citations for each element, opt in to the **field-basis** beta header:
```text theme={"system"}
parallel-beta: field-basis-2025-11-25
```
When this header is present on task creation requests:
* The Task API still returns top-level FieldBasis objects.
* Each element of a Top-level field with an array value gains an additional FieldBasis and it's own `field` which follows the pydash-style dot notation (e.g., `key_executives.0`, `key_executives.1`).
* No other schema changes are required; you simply read the expanded `basis` array.
## Examples
### Output with Research Basis
Here's an example of a complete Task Run output that includes research basis information:
```json theme={"system"}
{
"content": "{\"company\":\"Microsoft\",\"founded\":\"1975\",\"headquarters\":\"Redmond, Washington, USA\"}",
"basis": [
{
"field": "company",
"citations": [
{
"url": "https://www.microsoft.com/en-us/about",
"excerpts": ["Microsoft Corporation is an American multinational technology corporation headquartered in Redmond, Washington."]
}
],
"reasoning": "The company name is clearly identified on the official corporate website.",
"confidence": "high"
},
{
"field": "founded",
"citations": [
{
"url": "https://www.microsoft.com/en-us/about/company",
"excerpts": ["Founded in 1975, Microsoft (Nasdaq "MSFT") enables digital transformation for the era of an intelligent cloud and an intelligent edge."]
},
{
"url": "https://en.wikipedia.org/wiki/Microsoft",
"excerpts": ["Microsoft Corporation was founded by Bill Gates and Paul Allen on April 4, 1975, to develop and sell BASIC interpreters for the Altair 8800."]
}
],
"reasoning": "Multiple authoritative sources consistently state 1975 as the founding year. The official company website and Wikipedia both confirm this date, with Wikipedia providing the specific day (April 4).",
"confidence": "high"
},
{
"field": "headquarters",
"citations": [
{
"url": "https://www.microsoft.com/en-us/about/company",
"excerpts": ["Headquartered in Redmond, Washington, Microsoft has offices in over 100 countries."]
}
],
"reasoning": "The official company website explicitly states the headquarters location as Redmond, Washington, USA.",
"confidence": "high"
}
],
"type": "json"
}
```
### High vs. Low Confidence Outputs
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
Processors are the engines that execute Task Runs. The choice of Processor determines the performance profile and reasoning behavior used. Any Task Run can be executed on any Processor.
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
Task runs are stateful objects, which means that creating a Task Run and retrieving its results are separate calls to the API. Each Task Run is an independent instance that progresses through a series of states from `queued` to `completed`. This asynchronous design enables efficient scaling of web research operations.
### Task Run States
| Status | Description | Can Transition To |
| ----------- | -------------------------------------------------- | --------------------- |
| `queued` | Task created and waiting for processing | `running`, `failed` |
| `running` | Task actively being processed | `completed`, `failed` |
| `completed` | Task successfully completed with results available | (Terminal state) |
| `failed` | Task encountered an error | (Terminal state) |
**Note**: Running time varies by processor type and task complexity.
## Creating a Task Run
The basic requirements of a task run are:
* Input data (string or JSON object)
* A processor selection
* Output schema (optional but recommended)
Optionally, you can include:
* Input schema (optionally used to validate run input)
* Metadata (for tracking or organizing runs)
A Task Run, once created, can be identified by its `run_id`. A Task Run Result can be accessed once the Task Run status becomes `completed`.
## Rate Limits
The Task API enforces a limit of **2,000 requests per minute** per API key. This limit applies across all POST and GET requests and helps ensure consistent performance for all users.
When you exceed this limit, the API returns a `429 Too Many Requests` status code.
## Examples
### Completed Status Example
```json theme={"system"}
{
"run_id": "b0679f70-195e-4f42-8b8a-b8242a0c69c7",
"status": "completed",
"is_active": false,
"result": {
"population": "29.5 million (2022 estimate)",
"growth_rate": "1.4% annually",
"major_cities": [
"Houston",
"Dallas",
"San Antonio"
]
},
"result_url": "https://api.parallel.ai/v1/tasks/runs/b0679f70-195e-4f42-8b8a-b8242a0c69c7/result",
"warnings": null,
"errors": null,
"processor": "core",
"metadata": null,
"created_at": "2025-04-08T04:28:59.913464",
"modified_at": "2025-04-08T04:29:32.651298"
}
```
### Failed Status Example
If a Task Run encounters an error, the status will be set to `failed` and details will be available in the `errors` field:
```json theme={"system"}
{
"run_id": "b0679f70-195e-4f42-8b8a-b8242a0c69c7",
"status": "failed",
"is_active": false,
"result": null,
"result_url": null,
"warnings": null,
"errors": [
{
"code": "processing_error",
"message": "Unable to process task due to invalid input format",
"details": {
"field": "input",
"reason": "Expected JSON object but received string"
}
}
],
"processor": "core",
"metadata": null,
"created_at": "2025-04-08T04:28:59.913464",
"modified_at": "2025-04-08T04:29:01.234567"
}
```
# Interactions
Source: https://docs.parallel.ai/task-api/guides/interactions
Chain context across multiple API calls using interaction IDs
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
## Overview
Interactions let you chain context between API calls. Each response includes an `interaction_id`, which you can pass as `previous_interaction_id` in a subsequent request to carry forward the context from the previous call. This enables multi-turn research workflows like follow-up questions, iterative refinement, and conversational agents.
Interactions work across both the [Task API](/task-api/task-quickstart) and [Chat API](/chat-api/chat-quickstart).
## How It Works
1. **Make an initial request** — the response includes an `interaction_id`
2. **Pass it forward** — include that value as `previous_interaction_id` in your next request
3. **Continue the chain** — each new response returns its own `interaction_id`, so you can keep building on prior context
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
## Task Spec
A Task Specification ([Task Spec](/api-reference/tasks/create-task-run#body-task-spec-output-schema)) is a declarative template that defines the structure and requirements for the outputs of a web research operation. While optional in each Task Run, Task Specs provide significant advantages when you need precise control over your research data.
Task Specs ensure consistent results by enforcing a specific output structure across multiple runs. They validate schema against expected formats and create reusable templates for common research patterns. By defining the expected outputs clearly, they also serve as self-documentation for your tasks, making them easier to understand and maintain.
| Component | Required | Purpose | Format |
| ----------------- | -------- | ----------------------------------------------------- | ------------------- |
| **Output Schema** | Yes | Defines the structure and fields of the task result | JSON Schema or Text |
| **Input Schema** | No | Specifies expected input parameters and their formats | JSON Schema or Text |
## Task Spec Structure
A Task Spec consists of:
| Field | Type | Required | Description |
| -------- | ----------------------- | -------- | ----------------------------------------------- |
| `output` | Schema object or string | Yes | Description and structure of the desired output |
| `input` | Schema object or string | No | Description and structure of input parameters |
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
## API Overview
The Parallel Ingest API provides endpoints for creating intelligent task runs that can perform web research and data extraction. The API is built around a stateful architecture where task creation and result retrieval are separate operations.
## Endpoints
### Suggest Task
`POST /v1beta/tasks/suggest`
Generate a task specification based on user intent. This endpoint helps you create properly structured tasks by analyzing your requirements and suggesting appropriate schemas.
#### Request Parameters
| Parameter | Type | Required | Description |
| --------------- | ------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `user_intent` | string | Yes | Natural language description of what you want to accomplish |
| `previous_task` | `SuggestedTaskSpec` | No | Previous task specification to iterate upon and improve, or to restrict input columns to a predefined set (see [example](#select-input-columns-from-a-predefined-set) below) |
#### Response Schema
Returns a `SuggestedTaskSpec` object with the following fields:
| Field | Type | Description |
| --------------- | ------ | ----------------------------------------------------------- |
| `input_schema` | object | JSON schema defining expected input structure |
| `output_schema` | object | JSON schema defining expected output structure |
| `inputs` | array | Sample input data, if provided in the user intent |
| `title` | string | Suggested title for the task |
| `warnings` | array | Optional list of warnings about the generated specification |
**Warning Types:**
| Warning Type | Description |
| ----------------------- | ------------------------------------------------------------- |
| `schema_generalization` | Some fields were generalized to create a more reusable schema |
| `unparsable_input` | User-provided input data couldn't be fully parsed |
| `unattainable_task` | The requested task cannot be created exactly as specified |
#### Example Request
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
parallel-beta: mcp-server-2025-07-17 header when using the Task API.
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
# Task MCP
Source: https://docs.parallel.ai/task-api/task-mcp
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
# Task API Quickstart
Source: https://docs.parallel.ai/task-api/task-quickstart
Transform complex knowledge work into programmable, repeatable operations powered by AI web research
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
The **Task API** combines AI inference with web search and live crawling to turn complex research tasks into repeatable workflows. Define what you need in plain language or JSON, and the Task API handles the research, synthesis, and structured output—complete with citations and confidence levels.
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.
parallel-beta: events-sse-2025-07-24 header when using the Task API.
For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](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`.