---
source_url: "https://docs.parallel.ai/getting-started/overview"
title: Parallel API Overview - Parallel
mirrored_at: 2026-08-08T01:04:20.777Z
host: docs.parallel.ai
cited_in_42a: true
mirror_canonical: "https://index.42a.ai/docs.parallel.ai/getting-started/overview"
---

> **Original source:** https://docs.parallel.ai/getting-started/overview

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

## 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="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])
```

## 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) |
| **Entity Search** | One round-trip; natural-language people/company search → set of matching results | Latency-sensitive workflows that require a fast starting set of people or companies to filter or enrich downstream |
| **Monitor** | Scheduled NL query + webhook notifications on change | Continuous tracking (news, regulatory, competitive watchlists) |
````