Parallel

https://docs.parallel.ai/
Admin
Parallel is an AI platform providing Web Tools and Web Agents via an API for web search, data...
Tokens:660,081
Snippets:4,530
Trust Score:8.2
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Parallel Search API setup and Python example

Source: https://docs.parallel.ai/llms-full.txt

Setup and usage for the Parallel Search API. Install the parallel-web SDK (Python or TypeScript), set the PARALLEL_API_KEY environment variable, then create a client and call client.search with both objective and search_queries. The example prints result titles, URLs, and the first 200 characters of each excerpt.

```bash
pip install "parallel-web>=1.0.1"    # Python SDK — package is "parallel-web", import as `from parallel import Parallel`
npm install "parallel-web@^1.0.1"    # TypeScript SDK — package is "parallel-web", import as `import Parallel from "parallel-web"`

# 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"
```

```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="turbo" in your handler for the lowest latency (p50 ~200ms) in real-time,
# high-volume workloads, or mode="basic" for quick retrieval with deeper context per call.
# 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])
```

--------------------------------

### Install SDKs and Set API Keys

Source: https://docs.parallel.ai/llms-full.txt

Install the required SDKs and set environment variables for the Parallel and Anthropic API keys. The Python example uses pip, while the TypeScript example uses npm.

```bash
pip install anthropic parallel-web
export PARALLEL_API_KEY="your-parallel-api-key"
export ANTHROPIC_API_KEY="your-anthropic-api-key"
```

```bash
npm install @anthropic-ai/sdk parallel-web
export PARALLEL_API_KEY="your-parallel-api-key"
export ANTHROPIC_API_KEY="your-anthropic-api-key"
```

--------------------------------

### Verify Parallel CLI setup

Source: https://docs.parallel.ai/integrations/claude-code-marketplace

Runs the setup command to verify the Parallel CLI is installed and authenticated.

```bash
/parallel:setup
```

--------------------------------

### Setup: Pull model, install SDKs, set API key

Source: https://docs.parallel.ai/integrations/ollama-tool-calling

Install Ollama, pull a tool-capable model, install the Python SDKs, and set the Parallel API key environment variable.

```bash
ollama pull qwen3.5:0.8b
pip install ollama parallel-web
export PARALLEL_API_KEY="your-parallel-api-key"

```

--------------------------------

### Manual CLI setup

Source: https://docs.parallel.ai/integrations/cursor-marketplace

Manually install the Parallel CLI and authenticate if you prefer not to use the plugin's setup command.

```bash
pipx install "parallel-web-tools[cli]" && pipx ensurepath
parallel-cli login

```

--------------------------------

### Install OpenAI SDK (Python)

Source: https://docs.parallel.ai/responses-api/responses-quickstart

Installs the OpenAI SDK for Python, required for the Python example.

```bash
pip install openai

```

--------------------------------

### Install OpenAI SDK (TypeScript)

Source: https://docs.parallel.ai/responses-api/responses-quickstart

Installs the OpenAI SDK for TypeScript/JavaScript, required for the TypeScript example.

```bash
npm install openai

```

--------------------------------

### Parallel Search API setup prompt

Source: https://docs.parallel.ai/getting-started/overview

Setup prompt for integrating the Parallel Search API. It instructs the agent to install the SDK (Python or TypeScript) and set the PARALLEL_API_KEY environment variable, which should be treated like a password and loaded from .env or a secrets manager.

```markdown
# 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>=1.0.1"    # Python SDK — package is "parallel-web", import as `from parallel import Parallel`
npm install "parallel-web@^1.0.1"    # TypeScript SDK — package is "parallel-web", import as `import Parallel from "parallel-web"`

# 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"
```
```

--------------------------------

### Set up prerequisites for Parallel Task API

Source: https://docs.parallel.ai/llms-full.txt

Setup commands for the Parallel Task API. Install the required tool or SDK (cURL/jq, Python, TypeScript, or Python Async) and set the PARALLEL_API_KEY environment variable. The Python and Python (Async) setups use the same commands.

```bash
echo "Install curl and jq via brew, apt, or your favorite package manager"
export PARALLEL_API_KEY="PARALLEL_API_KEY"
```

```bash
pip install parallel-web
export PARALLEL_API_KEY="PARALLEL_API_KEY"
```

```bash
npm install parallel-web
export PARALLEL_API_KEY="PARALLEL_API_KEY"
```

```bash
pip install parallel-web
export PARALLEL_API_KEY="PARALLEL_API_KEY"
```

--------------------------------

### Onboard agent with Parallel CLI setup prompt

Source: https://docs.parallel.ai/getting-started/overview

Prompt to paste into your coding agent to set up the Parallel CLI. The agent reads the setup instructions from parallel.ai/agents.md and performs the installation.

```text
Use curl to read parallel.ai/agents.md and perform the setup to install Parallel
```

--------------------------------

### Install Python SDKs and set API keys

Source: https://docs.parallel.ai/integrations/anthropic-tool-calling

Install the required Python SDKs and set the environment variables for the Parallel and Anthropic API keys.

```bash
pip install anthropic parallel-web
export PARALLEL_API_KEY="your-parallel-api-key"
export ANTHROPIC_API_KEY="your-anthropic-api-key"

```

--------------------------------

### Install parallel-web-tools with DuckDB support

Source: https://docs.parallel.ai/data-integrations/duckdb

Install the package with DuckDB-specific dependencies using pip. Use this for a minimal setup.

```bash
pip install parallel-web-tools[duckdb]

```

--------------------------------

### Quick start: create and retrieve a task run

Source: https://docs.parallel.ai/task-api/task-quickstart

Demonstrates the three-step Task API workflow: create a task run, wait for completion, and retrieve the result. Uses the Python SDK with a base processor and an output schema.

```python
from parallel import Parallel

client = Parallel(api_key="PARALLEL_API_KEY")

# 1. Create a task run
task_run = client.task_run.create(
    input="Stripe",
    task_spec={"output_schema": "The founding year and total funding raised"},
    processor="base"
)

# 2-3. Retrieve the result (blocks until complete)
run_result = client.task_run.result(task_run.run_id, api_timeout=3600)
print(run_result.output)

```

--------------------------------

### Install AI SDK and set AI Gateway API key

Source: https://docs.parallel.ai/llms-full.txt

Install the AI SDK and set the AI Gateway API key for local development with Vercel AI Gateway.

```bash
npm install ai
export AI_GATEWAY_API_KEY="your-ai-gateway-api-key"
```

--------------------------------

### Install OpenClaw and ClawHub

Source: https://docs.parallel.ai/integrations/clawhub

Install OpenClaw and ClawHub. The OpenClaw gateway is bound to loopback for security, and the dashboard starts the chat interface.

```bash
# Install OpenClaw (recommended: run locally for security)
npm install -g openclaw@latest
openclaw gateway --port 18789 --bind loopback
openclaw dashboard  # start the chat interface

# Install ClawHub CLI
npm install -g clawhub

```

--------------------------------

### Start LiteLLM gateway

Source: https://docs.parallel.ai/integrations/litellm

Start the LiteLLM gateway using the config.yaml file and bind to localhost.

```bash
litellm --config config.yaml --host 127.0.0.1

```

--------------------------------

### Install Python SDKs and set API keys

Source: https://docs.parallel.ai/integrations/openai-tool-calling

Install the required Python SDKs and set environment variables for Parallel and OpenAI API keys.

```bash
pip install openai parallel-web
export PARALLEL_API_KEY="your-parallel-api-key"
export OPENAI_API_KEY="your-openai-api-key"

```

--------------------------------

### Set Up Prerequisites with Python SDK

Source: https://docs.parallel.ai/extract/extract-quickstart

Set up the Extract API prerequisites using the Python SDK. Install the parallel-web package and set the PARALLEL_API_KEY environment variable.

```bash
pip install parallel-web
export PARALLEL_API_KEY="PARALLEL_API_KEY"

```

--------------------------------

### GET /api

Source: https://docs.parallel.ai/integrations/agentic-payments

Returns the full API schema, docs, and examples as JSON. Free to call.

```APIDOC
## [GET] /api

### Description
Returns the full API schema, documentation, and examples as JSON. Free to call.

### Method
GET

### Endpoint
/api

### Response
#### Success Response (200)
- Full API schema as JSON.
```

--------------------------------

### Install AI SDK and Parallel tools

Source: https://docs.parallel.ai/llms-full.txt

Install AI SDK v6, the OpenAI provider, and version 1 of Parallel's tool package, then set the required API keys as environment variables.

```bash
npm install ai@^6 @ai-sdk/openai@^3 @parallel-web/ai-sdk-tools@^1
export PARALLEL_API_KEY="your-parallel-api-key"
export OPENAI_API_KEY="your-openai-api-key"
```

--------------------------------

### List monitors via REST API (Java/curl)

Source: https://docs.parallel.ai/api-reference/monitor/list-monitors

Makes a GET request to the /v1/monitors endpoint with an API key. The Java example uses Unirest; the curl example uses the command line.

```java
HttpResponse<String> response = Unirest.get("https://api.parallel.ai/v1/monitors")
  .header("x-api-key", "<api-key>")
  .asString();
```

```bash
curl --request GET \
  --url https://api.parallel.ai/v1/monitors \
  --header 'x-api-key: <api-key>'
```

--------------------------------

### GET /api

Source: https://docs.parallel.ai/integrations/agentic-payments

Free endpoint that returns the full API schema, docs, and examples in JSON format.

```APIDOC
## GET /api

### Description
Full API schema, docs, and examples (JSON).

### Method
GET

### Endpoint
/api

### Response
#### Success Response (200)
- JSON containing API schema, docs, and examples

#### Response Example
(No example provided in source)

```

--------------------------------

### Set Up Prerequisites with cURL

Source: https://docs.parallel.ai/extract/extract-quickstart

Set up the Extract API prerequisites using cURL. Install curl and jq, then set the PARALLEL_API_KEY environment variable.

```bash
echo "Install curl and jq via brew, apt, or your favorite package manager"
export PARALLEL_API_KEY="PARALLEL_API_KEY"

```

--------------------------------

### GET /v1/monitors/{monitor_id}

Source: https://docs.parallel.ai/api-reference/monitor/retrieve-monitor

Retrieves a monitor by its ID. Includes Python, JavaScript, HTTP, and cURL examples.

```APIDOC
## GET /v1/monitors/{monitor_id}

### Description
Retrieves a monitor by its unique identifier. Returns the monitor's configuration, status, and latest output.

### Method
GET

### Endpoint
`https://api.parallel.ai/v1/monitors/{monitor_id}`

### Parameters
#### Path Parameters
- **monitor_id** (string) - Required - The unique identifier of the monitor to retrieve.

#### Headers
- **x-api-key** (string) - Required - API key for authentication.

### Request Example
```
curl --request GET \
  --url https://api.parallel.ai/v1/monitors/{monitor_id} \
  --header 'x-api-key: <api-key>'
```

### Response
#### Success Response (200)
Returns the monitor object with the following fields:
- **type** (string) - The type of the monitor, e.g., "event_stream".
- **monitor_id** (string) - The unique identifier of the monitor.
- **status** (string) - The current status of the monitor, e.g., "active".
- **frequency** (string) - The polling frequency, e.g., "1h".
- **processor** (string) - The processor type, e.g., "lite".
- **created_at** (string) - The creation timestamp in ISO 8601 format.
- **settings** (object) - The monitor's settings, including query, output_schema, include_backfill, and advanced_settings.
- **webhook** (object) - Webhook configuration with url and event_types.
- **metadata** (object) - Arbitrary metadata associated with the monitor.
- **last_run_at** (string) - The timestamp of the last run.
- **output** (object) - The latest output, including latest_snapshot with basis, type, content, mcp_tool_calls, and beta_fields.

#### Response Example
```
{
  "type": "event_stream",
  "monitor_id": "<string>",
  "status": "active",
  "frequency": "1h",
  "processor": "lite",
  "created_at": "2025-01-15T10:30:00Z",
  "settings": {
    "query": "Extract recent news about AI",
    "output_schema": {
      "json_schema": {
        "additionalProperties": false,
        "properties": {
          "gdp": {
            "description": "GDP in USD for the year, formatted like '$3.1 trillion (2023)'",
            "type": "string"
          }
        },
        "required": ["gdp"],
        "type": "object"
      },
      "type": "json"
    },
    "include_backfill": true,
    "advanced_settings": {
      "source_policy": {
        "include_domains": ["wikipedia.org", "docs.python.org/3", ".edu"]
      },
      "location": "us"
    }
  },
  "webhook": {
    "url": "https://example.com/webhook",
    "event_types": ["monitor.event.detected"]
  },
  "metadata": {
    "slack_thread_id": "1234567890.123456",
    "user_id": "U123ABC"
  },
  "last_run_at": "2025-01-15T10:30:00Z",
  "output": {
    "latest_snapshot": {
      "basis": [
        {
          "field": "<string>",
          "reasoning": "<string>",
          "citations": [],
          "confidence": "low"
        }
      ],
      "type": "text",
      "content": "<string>",
      "mcp_tool_calls": [
        {
          "tool_call_id": "<string>",
          "server_name": "<string>",
          "tool_name": "<string>",
          "arguments": "<string>",
          "content": "<string>",
          "error": "<string>"
        }
      ],
      "beta_fields": {}
    }
  }
}
```

#### Error Responses
- **401 Unauthorized**: Invalid or missing credentials.
  ```
  {
    "type": "error",
    "error": {
      "ref_id": "fcb2b4f3-c75e-4186-87bc-caa1a8381331",
      "message": "Unauthorized: invalid or missing credentials"
    }
  }
  ```
- **404 Not Found**: Monitor not found.
  ```
  {
    "type": "error",
    "error": {
      "ref_id": "fcb2b4f3-c75e-4186-87bc-caa1a8381331",
      "message": "Monitor not found"
    }
  }
  ```
- **422 Unprocessable Entity**: Validation error.
  ```
  {
    "detail": [
      {
        "loc": ["<string>"],
        "msg": "<string>",
        "type": "<string>"
      }
    ]
  }
  ```
```

--------------------------------

### Install LiteLLM and set Parallel API key

Source: https://docs.parallel.ai/integrations/litellm

Install LiteLLM and set the Parallel API key as an environment variable before using the native Search provider.

```bash
pip install litellm
export PARALLEL_API_KEY="your-parallel-api-key"

```

--------------------------------

### Python: Initialize Parallel client and run a search

Source: https://docs.parallel.ai/getting-started/overview

Creates a Parallel client reading PARALLEL_API_KEY from the environment, then calls client.search with a natural-language objective and 2-3 diverse keyword queries. Both objective and search_queries are required; mode defaults to 'advanced' (slower, highest quality) and can be set to 'turbo' (p50 ~200ms) or 'basic' in the handler. Keep tuning parameters out of the tool schema.

```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="turbo" in your handler for the lowest latency (p50 ~200ms) in real-time,
# high-volume workloads, or mode="basic" for quick retrieval with deeper context per call.
# 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])
```

--------------------------------

### Get FindAll Run Result (Python and TypeScript)

Source: https://docs.parallel.ai/public-openapi.json

Retrieve the result of a FindAll run by its ID. The Python example uses the `parallel` package and prints the result as JSON; the TypeScript example uses the `parallel-web` package and logs the result as JSON. Both require a valid `findall_id`.

```Python
from parallel import Parallel

client = Parallel()

run_result = client.beta.findall.result(
    findall_id="findall_56ccc4d188fb41a0803a935cf485c774",
)

print(f"FindAll run {run_result.run.findall_id} result: {run_result.model_dump_json(indent=2)}")
```

```TypeScript
import Parallel from "parallel-web";

const client = new Parallel();

const runResult = await client.beta.findall.result("findall_56ccc4d188fb41a0803a935cf485c774");

console.log(`FindAll run ${runResult.run.findall_id} result: ${JSON.stringify(runResult, null, 2)}`);
```

--------------------------------

### Install TypeScript SDKs and set API keys

Source: https://docs.parallel.ai/integrations/anthropic-tool-calling

Install the required TypeScript SDKs and set the environment variables for the Parallel and Anthropic API keys.

```bash
npm install @anthropic-ai/sdk parallel-web
export PARALLEL_API_KEY="your-parallel-api-key"
export ANTHROPIC_API_KEY="your-anthropic-api-key"

```

--------------------------------

### Get Task Group Runs with Parallel SDK

Source: https://docs.parallel.ai/public-openapi.json

Retrieve runs for a task group using the Parallel SDK. The Python example uses client.task_group.get_runs("taskgroup_id") and iterates over the returned runs. The TypeScript example uses client.taskGroup.getRuns('taskgroup_id') and iterates asynchronously.

```Python
from parallel import Parallel

client = Parallel()

task_group_runs = client.task_group.get_runs("taskgroup_id")
for run in task_group_runs:
    print(run)

```

```TypeScript
import Parallel from "parallel-web";

const client = new Parallel();

const taskGroupRuns = await client.taskGroup.getRuns(
    'taskgroup_id',
);
for await (const run of taskGroupRuns) {
    console.log(run);
}

```

--------------------------------

### List monitors with SDKs and HTTP

Source: https://docs.parallel.ai/api-reference/monitor/list-monitors

Client library and raw HTTP examples for listing monitors. The Python and JavaScript SDKs use `client.monitor.list` with a `limit` option and iterate over `page.monitors`. The Java example uses Unirest with the `x-api-key` header, and the curl command sends a GET request to `https://api.parallel.ai/v1/monitors` with the same header.

```python
from parallel import Parallel

client = Parallel()

page = client.monitor.list(limit=10)
for monitor in page.monitors:
    print(monitor.monitor_id, monitor.status)
```

```javascript
import Parallel from "parallel-web";

const client = new Parallel();

const page = await client.monitor.list({ limit: 10 });
for (const monitor of page.monitors) {
    console.log(monitor.monitor_id, monitor.status);
}
```

```java
HttpResponse<String> response = Unirest.get("https://api.parallel.ai/v1/monitors")
  .header("x-api-key", "<api-key>")
  .asString();
```

```bash
curl --request GET \
  --url https://api.parallel.ai/v1/monitors \
  --header 'x-api-key: <api-key>'
```

--------------------------------

### Install SDKs and Set API Keys

Source: https://docs.parallel.ai/llms-full.txt

Install the required SDKs and set API keys for Python (pip) and TypeScript (npm). Both commands export the Parallel and OpenAI API keys as environment variables.

```bash
pip install openai parallel-web
export PARALLEL_API_KEY="your-parallel-api-key"
export OPENAI_API_KEY="your-openai-api-key"
```

```bash
npm install openai parallel-web
export PARALLEL_API_KEY="your-parallel-api-key"
export OPENAI_API_KEY="your-openai-api-key"
```
Tokens:
Raw