> Discover all available pages from the documentation index: https://mastra.ai/llms.txt

# Parallel

The `@mastra/parallel` package exposes [Parallel Search](https://docs.parallel.ai/search/search-quickstart) and [Extract](https://docs.parallel.ai/search/extract-quickstart) as Mastra-compatible tools. Each factory returns a tool created with [`createTool()`](https://mastra.ai/reference/tools/create-tool) and a typed Zod input and output schema.

## Installation

**npm**:

```bash
npm install @mastra/parallel parallel-web zod
```

**pnpm**:

```bash
pnpm add @mastra/parallel parallel-web zod
```

**Yarn**:

```bash
yarn add @mastra/parallel parallel-web zod
```

**Bun**:

```bash
bun add @mastra/parallel parallel-web zod
```

Set `PARALLEL_API_KEY` in your environment. You can also pass an API key directly to any factory.

## Quick start

Use `createParallelTools()` to create both tools with shared client configuration:

```typescript
import { createParallelTools } from '@mastra/parallel'

export const parallelTools = createParallelTools()
// Or pass an explicit API key:
// export const parallelTools = createParallelTools({ apiKey: 'parallel-api-key' })
```

The returned object contains `parallelSearch` and `parallelExtract`.

Create either tool separately when an agent doesn't need both:

```typescript
import { createParallelExtractTool, createParallelSearchTool } from '@mastra/parallel'

export const searchTool = createParallelSearchTool()
export const extractTool = createParallelExtractTool({ apiKey: 'parallel-api-key' })
```

The client isn't initialized until the tool executes. A missing API key therefore fails at execution time with a configuration error.

## Configuration

All factories accept `ParallelClientOptions`, an alias of `ClientOptions` from the official `parallel-web` client:

**apiKey** (`string`): Parallel API key. Falls back to the PARALLEL\_API\_KEY environment variable.

**baseURL** (`string`): Override the Parallel API base URL. The client also reads PARALLEL\_BASE\_URL.

**timeout** (`number`): Timeout in milliseconds for one request attempt.

**fetch** (`Fetch`): Custom fetch implementation.

**fetchOptions** (`RequestInit`): Additional options passed to each fetch call.

**maxRetries** (`number`): Maximum retries for temporary failures. (Default: `2`)

**defaultHeaders** (`HeadersLike`): Headers included with every request.

**defaultQuery** (`Record<string, string | undefined>`): Query parameters included with every request.

**logLevel** (`LogLevel`): Client log level. Falls back to PARALLEL\_LOG, then warn.

**logger** (`Logger`): Client logger implementation.

The package also exports `getParallelClient()` for applications that need the configured official client directly.

## `createParallelSearchTool()`

Creates the `parallel-search` tool. Search returns ranked URLs and excerpts focused on the supplied queries and objective.

```typescript
import { createParallelSearchTool } from '@mastra/parallel'

const searchTool = createParallelSearchTool()
```

### Search input

**searchQueries** (`string[]`): One or more concise keyword queries. Parallel recommends 2-3 queries of 3-6 words each.

**objective** (`string`): Self-contained description of the goal driving the search.

**mode** (`'turbo' | 'fast' | 'basic' | 'advanced'`): Search mode. (Default: `'advanced'`)

**clientModel** (`string`): Model that will consume the results. Parallel uses it to tailor response defaults.

**maxResults** (`number`): Maximum number of results to return.

**excerptMaxCharsPerResult** (`number`): Maximum excerpt characters for each result.

**maxCharsTotal** (`number`): Maximum excerpt characters across all results.

**location** (`string`): ISO 3166-1 alpha-2 country code for geo-targeted results.

**includeDomains** (`string[]`): Only return results from these domains. Include and exclude lists can contain at most 200 domains combined.

**excludeDomains** (`string[]`): Exclude results from these domains. Include and exclude lists can contain at most 200 domains combined.

**afterDate** (`string`): Only return content published on or after this YYYY-MM-DD date.

**fetchPolicy** (`FetchPolicy`): Controls live fetching and cached-content fallback.

**fetchPolicy.maxAgeSeconds** (`number`): Maximum cached-content age before a live fetch. The minimum is 600 seconds.

**fetchPolicy.timeoutSeconds** (`number`): Timeout for a live fetch.

**fetchPolicy.disableCacheFallback** (`boolean`): Return an error instead of older cached content when a live fetch fails.

**sessionId** (`string`): Session identifier shared across related Search and Extract calls.

### Search output

Search returns `searchId`, `sessionId`, and `results`. Optional `usage` and `warnings` arrays preserve metadata from Parallel.

**searchId** (`string`): Parallel Search request ID.

**sessionId** (`string`): Session ID returned by Parallel.

**results** (`SearchResult[]`): Results ordered by decreasing relevance.

**results.url** (`string`): Result URL.

**results.title** (`string`): Page title.

**results.publishDate** (`string`): Page publication date.

**results.excerpts** (`string[]`): Relevant Markdown excerpts.

**usage** (`UsageItem[]`): SKU names and counts for the request.

**warnings** (`Warning[]`): Validation or request warnings from Parallel.

## `createParallelExtractTool()`

Creates the `parallel-extract` tool. Extract returns relevant excerpts or full content for up to 20 public URLs and reports per-URL failures separately.

```typescript
import { createParallelExtractTool } from '@mastra/parallel'

const extractTool = createParallelExtractTool()
```

### Extract input

**urls** (`string[]`): One to 20 URLs to extract.

**objective** (`string`): Information to focus on while extracting.

**searchQueries** (`string[]`): Keyword queries used with the objective to focus excerpts.

**clientModel** (`string`): Model that will consume the results. Parallel uses it to tailor response defaults.

**excerptMaxCharsPerResult** (`number`): Maximum excerpt characters for each URL.

**fullContent** (`boolean | number`): Return full page content. Pass a number to cap characters for each URL.

**maxCharsTotal** (`number`): Maximum excerpt characters across all results.

**fetchPolicy** (`FetchPolicy`): Controls live fetching and cached-content fallback.

**fetchPolicy.maxAgeSeconds** (`number`): Maximum cached-content age before a live fetch. The minimum is 600 seconds.

**fetchPolicy.timeoutSeconds** (`number`): Timeout for a live fetch.

**fetchPolicy.disableCacheFallback** (`boolean`): Return an error instead of older cached content when a live fetch fails.

**sessionId** (`string`): Session identifier shared across related Search and Extract calls.

### Extract output

**extractId** (`string`): Parallel Extract request ID.

**sessionId** (`string`): Session ID returned by Parallel.

**results** (`ExtractResult[]`): Successful URL results.

**results.url** (`string`): Extracted URL.

**results.title** (`string`): Page title.

**results.publishDate** (`string`): Page publication date.

**results.excerpts** (`string[]`): Relevant Markdown excerpts.

**results.fullContent** (`string`): Full Markdown content when requested.

**errors** (`ExtractError[]`): Requested URLs that weren't returned as results.

**errors.url** (`string`): URL that failed.

**errors.errorType** (`string`): Parallel error type.

**errors.httpStatusCode** (`number`): HTTP status code when available.

**errors.content** (`string`): Response content when available.

**usage** (`UsageItem[]`): SKU names and counts for the request.

**warnings** (`Warning[]`): Validation or request warnings from Parallel.

## Use the tools with an agent

```typescript
import { Agent } from '@mastra/core/agent'
import { createParallelTools } from '@mastra/parallel'

export const researchAgent = new Agent({
  id: 'research-agent',
  name: 'Research Agent',
  model: 'anthropic/claude-sonnet-4-6',
  instructions:
    'Search the web for current sources, then extract relevant content from the best pages.',
  tools: createParallelTools(),
})
```

## Related

- [Parallel Search documentation](https://docs.parallel.ai/search/search-quickstart)
- [Parallel Extract documentation](https://docs.parallel.ai/search/extract-quickstart)
- [`createTool()` reference](https://mastra.ai/reference/tools/create-tool)