Parallel Web Systems API

Overview

This skill gives access to Parallel Web Systems APIs for web search, deep research, and content extraction. In the scientific-writing workflow it is the default tool for general web information — news, market and technical data, documentation — while scholarly paper retrieval goes to alterlab-research-lookup.

Primary interface: Chat API (Beta, OpenAI-compatible, POST /v1beta/chat/completions) for search and research. Secondary interface: Extract API v1 (POST /v1/extract) for URL verification and special cases.

API Documentation: https://docs.parallel.ai API Key: https://platform.parallel.ai Environment Variable: PARALLEL_API_KEY

When to Use This Skill

Use this skill for:

• Web Search: queries that need current information from the internet
• Deep Research: comprehensive, multi-source research reports on a topic
• Market Research: industry analysis, competitive intelligence, market data
• Current Events: news, recent developments, announcements
• Technical Information: documentation, specifications, product details
• Statistical Data: market sizes, growth rates, industry figures

Use the Extract API only for citation verification (confirming what a specific URL says) and for cases where you need raw content from a known URL.

Does NOT Trigger

Three Capabilities

1. Web Search (search command)

Search the web via the Chat API (base model) and get a synthesized summary with cited sources.

Best for: General web searches, current events, fact-finding, technical lookups, news, market data.

# Basic search
python scripts/parallel_web.py search "latest advances in quantum computing 2025"

# Use core model for more complex queries
python scripts/parallel_web.py search "compare EV battery chemistries NMC vs LFP" --model core

# Save results to file
python scripts/parallel_web.py search "renewable energy policy updates" -o results.txt

# JSON output for programmatic use
python scripts/parallel_web.py search "AI regulation landscape" --json -o results.json

Key Parameters:

• objective: Natural language description of what you want to find
• --model: Chat model to use (base default, or core for deeper research)
• -o: Output file path
• --json: Output as JSON

Response includes: Synthesized summary organized by themes, with inline citations and a sources list.

2. Deep Research (research command)

Run comprehensive multi-source research via the Chat API (core model) that produces detailed reports with citations.

Best for: Market research, comprehensive analysis, competitive intelligence, technology surveys, industry reports, any question requiring synthesis of many sources.

# Default deep research (core model)
python scripts/parallel_web.py research "comprehensive analysis of the global EV battery market"

# Save research report to file
python scripts/parallel_web.py research "AI adoption in healthcare 2025" -o report.md

# Use base model for faster, lighter research
python scripts/parallel_web.py research "latest funding rounds in AI startups" --model base

# JSON output
python scripts/parallel_web.py research "renewable energy storage market in Europe" --json -o data.json

Key Parameters:

• query: Research question or topic
• --model: Chat model to use (core default for deep research, or base for faster results)
• -o: Output file path
• --json: Output as JSON

3. URL Extraction (extract command) — Verification Only

Extract content from specific URLs (up to 20 per call). Use it for citation verification and special cases; for general research, use search or research.

# Verify a citation's content
python scripts/parallel_web.py extract "https://example.com/article" --objective "key findings"

# Also return the full page as markdown (excerpts are always returned)
python scripts/parallel_web.py extract "https://docs.example.com/api" --full-content

# Save extraction to file
python scripts/parallel_web.py extract "https://paper-url.com" --objective "methodology" -o extracted.md

Model Selection Guide

The script uses the Chat API research models: base for most searches and core for deep research.

• search defaults to base — fast, good for most queries
• research defaults to core — thorough, good for comprehensive reports
• Override with --model when you need a different depth/speed trade-off

Parallel also offers APIs the script does not wrap (see references/api_reference.md): the Search API v1 (ranked URLs with excerpts, modes turbo/fast/basic/advanced, domain source policies), the Task API (async deep research with processors from lite to ultra8x), and the Responses API (OpenAI Responses-compatible, model parallel with reasoning.effort low/medium/high; launched July 2026, and the Chat API quickstart in Parallel's docs now redirects to it). Call those through the parallel-web SDK or HTTP when you need domain pinning, structured output, or async runs.

Python API Usage

Search

from parallel_web import ParallelSearch

searcher = ParallelSearch()
result = searcher.search(
    objective="Find latest information about transformer architectures in NLP",
    model="base",
)

if result["success"]:
    print(result["response"])  # Synthesized summary
    for src in result["sources"]:
        print(f"  {src['title']}: {src['url']}")

Deep Research

from parallel_web import ParallelDeepResearch

researcher = ParallelDeepResearch()
result = researcher.research(
    query="Comprehensive analysis of AI regulation in the EU and US",
    model="core",
)

if result["success"]:
    print(result["response"])  # Full research report
    print(f"Citations: {result['citation_count']}")

Extract (Verification Only)

from parallel_web import ParallelExtract

extractor = ParallelExtract()
result = extractor.extract(
    urls=["https://docs.example.com/api-reference"],
    objective="API authentication methods and rate limits",
)

if result["success"]:
    for r in result["results"]:
        print(r["excerpts"])

Save Results to the Sources Folder

Save every web search, deep research, and extraction result to the project's sources/ folder. Saved results make each claim traceable to its raw source material (reproducibility, audit, peer review), let you recover context if the conversation is compacted, and avoid paying twice for the same query.

Saving Rules

Pass -o pointing into sources/ on every call:

# Web search
python scripts/parallel_web.py search "latest advances in quantum computing 2025" \
  -o sources/search_20250217_143000_quantum_computing.md

# Deep research
python scripts/parallel_web.py research "comprehensive analysis of the global EV battery market" \
  -o sources/research_20250217_144000_ev_battery_market.md

# URL extraction (verification only)
python scripts/parallel_web.py extract "https://example.com/article" --objective "key findings" \
  -o sources/extract_20250217_143500_example_article.md

Before a new query, check whether a relevant result already exists (ls sources/) and re-read it instead of calling the API again. After saving, log the file:

[HH:MM:SS] SAVED: Search results to sources/search_20250217_143000_quantum_computing.md
[HH:MM:SS] SAVED: Deep research report to sources/research_20250217_144000_ev_battery_market.md

Routing

When writing scientific documents: gather background with search/research before drafting a section, verify any specific URL with extract, and route purely academic paper searches to alterlab-research-lookup. Check sources/ first and save every result back.

Environment Setup

# Required: set your Parallel API key
export PARALLEL_API_KEY="your_api_key_here"

# Python packages
uv pip install openai          # Chat API (search/research)
uv pip install parallel-web    # Extract API v1 (>= 1.0; imports as `parallel`)
# Or run ad hoc without a venv:
#   uv run --with openai --with parallel-web scripts/parallel_web.py search "query"

Get your API key at https://platform.parallel.ai. The script sends your queries and URLs to Parallel's servers.

Error Handling

The script returns structured error responses rather than raising:

{
  "success": false,
  "error": "Error description",
  "timestamp": "2025-02-14 12:00:00"
}

Common issues:

• PARALLEL_API_KEY not set: set the environment variable
• openai not installed: run uv pip install openai
• parallel-web not installed: run uv pip install parallel-web (only needed for extract)
• 'BetaResource' object has no attribute 'extract': an old copy of the script is calling the Beta method removed in parallel-web 1.0 — use this skill's current script (client.extract())
• Rate limit exceeded: wait and retry (defaults: Chat 300 requests/min, Extract 600 requests/min)

Complementary Skills

See the Routing table above for alterlab-research-lookup (scholarly papers) and alterlab-citation-mgmt (Scholar/PubMed/CrossRef). Also:

Part of the AlterLab Academic Skills suite.