---
title: Perplexity
description: "Learn how to use Perplexity's Agent API with the AI SDK."
url: "https://ai-sdk.dev/v5/providers/ai-sdk-providers/perplexity"
docs_index: /llms.txt
---

> For an index of all documentation, see [/llms.txt](/llms.txt).

The [Perplexity](https://www.perplexity.ai) provider offers access to the
[Agent API](https://docs.perplexity.ai/docs/agent-api/quickstart). The Agent API
can route across models, search the web, call tools, and return cited answers.

API keys can be obtained from the [Perplexity Platform](https://docs.perplexity.ai).

## Setup

The Perplexity provider is available via the `@ai-sdk/perplexity` module. You can install it with:

#### pnpm

```
pnpm add @ai-sdk/perplexity
```

#### npm

```
npm install @ai-sdk/perplexity
```

#### yarn

```
yarn add @ai-sdk/perplexity
```

#### bun

```
bun add @ai-sdk/perplexity
```

## Provider Instance

You can import the default provider instance `perplexity` from `@ai-sdk/perplexity`:

```ts
import { perplexity } from '@ai-sdk/perplexity';
```

For custom configuration, you can import `createPerplexity` and create a provider instance with your settings:

```ts
import { createPerplexity } from '@ai-sdk/perplexity';

const perplexity = createPerplexity({
  apiKey: process.env.PERPLEXITY_API_KEY ?? '',
});
```

You can use the following optional settings to customize the Perplexity provider instance:

- **baseURL** *string*

  Use a different URL prefix for API calls.
  The default prefix is `https://api.perplexity.ai`.

- **apiKey** *string*

  API key that is being sent using the `Authorization` header. It defaults to
  the `PERPLEXITY_API_KEY` environment variable.

- **headers** *Record\<string,string>*

  Custom headers to include in the requests.

- **fetch** *(input: RequestInfo, init?: RequestInit) => Promise\<Response>*

  Custom [fetch](https://developer.mozilla.org/en-US/docs/Web/API/fetch) implementation.

## Language Models

You can create Perplexity models using a provider instance:

```ts
import { perplexity } from '@ai-sdk/perplexity';
import { generateText } from 'ai';

const { text } = await generateText({
  model: perplexity('low'),
  prompt: 'What are the latest developments in quantum computing?',
});
```

The Agent API provides the `fast`, `low`, `medium`, `high`, and `xhigh`
presets. You can also pass an Agent API model ID directly, such as
`perplexity/sonar`.

Starting with version 2.1.0, language generation uses the Agent API
exclusively. Legacy Sonar model IDs and provider options are not mapped; see
[Migrating from Sonar to the Agent API](#migrating-from-sonar-to-the-agent-api)
before upgrading.

### Sources

Websites that have been used to generate the response are included in the `sources` property of the result:

```ts
import { perplexity } from '@ai-sdk/perplexity';
import { generateText } from 'ai';

const { text, sources } = await generateText({
  model: perplexity('low'),
  prompt: 'What are the latest developments in quantum computing?',
});

console.log(sources);
```

### Agent Tools

Pass native Agent API tools through `providerOptions.perplexity.tools`:

```ts
import {
  perplexity,
  type PerplexityLanguageModelOptions,
} from '@ai-sdk/perplexity';
import { generateText } from 'ai';

const { text, sources } = await generateText({
  model: perplexity('low'),
  prompt: 'Summarize recent US federal AI policy from official sources.',
  providerOptions: {
    perplexity: {
      tools: [
        {
          type: 'web_search',
          filters: {
            search_domain_filter: [
              'whitehouse.gov',
              'congress.gov',
              'federalregister.gov',
            ],
            search_recency_filter: 'month',
          },
          max_results: 10,
          search_context_size: 'medium',
        },
      ],
    } satisfies PerplexityLanguageModelOptions,
  },
});
```

Supported native tools are `web_search`, `fetch_url`, `people_search`,
`finance_search`, `sandbox`, `mcp`, and `connector`. Agent API presets include
preconfigured tools that remain enabled; the `tools` option can add explicit
tools or supply tools when using a direct model ID.

Search and fetch results are exposed as AI SDK sources. Other native tool traces,
including finance, sandbox, and MCP results, are available in `response.body`
and raw stream chunks (`includeRawChunks: true`). They are not exposed as
AI SDK client tool calls. Accounts with zero data retention may reject
file-capable tools such as `finance_search` and `sandbox`.

AI SDK function tools can be passed through the top-level `tools` option:

```ts
import { perplexity } from '@ai-sdk/perplexity';
import { generateText, tool } from 'ai';
import { z } from 'zod';

const result = await generateText({
  model: perplexity('low'),
  prompt: 'What is the weather in San Francisco?',
  tools: {
    weather: tool({
      description: 'Get the weather for a city',
      inputSchema: z.object({ city: z.string() }),
      execute: async ({ city }) => ({ city, temperature: 18 }),
    }),
  },
});
```

### Provider Options and Metadata

The Perplexity provider includes additional metadata in the response through `providerMetadata`.
Additional configuration options are available through `providerOptions`.

```ts
import {
  perplexity,
  type PerplexityLanguageModelOptions,
} from '@ai-sdk/perplexity';
import { generateText } from 'ai';

const result = await generateText({
  model: perplexity('low'),
  prompt: 'What are the latest developments in quantum computing?',
  providerOptions: {
    perplexity: {
      max_steps: 5,
      store: true,
      reasoning: { effort: 'low' },
    } satisfies PerplexityLanguageModelOptions,
  },
});

console.log(result.providerMetadata);
// Example output:
// {
//   perplexity: {
//     usage: { citationTokens: null, numSearchQueries: 1 },
//     images: null,
//     cost: { totalCost: 0.006, currency: 'USD', ... },
//     toolCalls: { search_web: { invocation: 1 } },
//   },
// }
```

#### Provider Options

The following Agent API options are available:

- **instructions** *string*

  Top-level instructions for the Agent API run.

- **tools** *array*

  Native Agent API tools and their configuration.

- **models** *string\[]*

  A fallback model list for Agent API routing.

- **max\_steps** *number*

  The maximum number of agentic steps.

- **max\_tool\_calls** *number*

  The maximum number of native tool calls. Setting this to `0` disables all
  preset tools.

- **previous\_response\_id** *string*

  Continue a conversation from an earlier Agent API response.

- **store** *boolean*

  Whether the response can be retrieved later. Setting `store: false` hides it
  from retrieval; it does not disable persistence, and the response can still
  be used as a `previous_response_id` continuation source. See Perplexity's
  [conversation state documentation](https://docs.perplexity.ai/docs/agent-api/conversation-state)
  for retention behavior and account-specific zero data retention restrictions.

- **language\_preference** *string*

  Preferred response language as an ISO 639-1 language code.

- **reasoning** *object*

  Reasoning configuration. `effort` supports `'minimal'`, `'low'`, `'medium'`,
  `'high'`, and `'xhigh'`.

- **skills** *array*

  Agent API skill configuration.

See the [Perplexity Agent API
documentation](https://docs.perplexity.ai/docs/agent-api/quickstart) for
details about native request fields.

#### Provider Metadata

The response metadata includes:

- `usage`: `citationTokens` (always `null` for Agent API responses) and the
  number of search queries
- `cost`: Token, tool, and total costs returned by Perplexity
- `toolCalls`: Invocation counts grouped by native tool
- `images`: Always `null`; the Agent API does not return Sonar image results

### Structured Output

`generateObject`, `streamObject`, and `experimental_output` send an Agent API
JSON schema response format. JSON output without a schema is not supported.

### Input Images

Image URL and data inputs are converted to Agent API `input_image` parts.
The Agent API does not provide a Sonar-equivalent PDF input field, so PDF file
parts are not supported.

### Migrating from Sonar to the Agent API

Version 2.1.0 is a breaking migration from Sonar Chat Completions to the
Agent API. It does not provide legacy model aliases, translate Sonar provider
options, or emit migration warnings at runtime.

Perplexity supports Sonar Chat Completions only until September 27, 2026.
Upgrade language-generation applications to the Agent API before that date;
staying on version 2.0.45 or earlier does not preserve service after the
Sonar shutdown.

Replace each Sonar model ID with an Agent API preset or direct Agent API model
ID. These presets are suggested starting points, not equivalent aliases: a
preset can select different models and tools, so cost, latency, and output can
change.

| Sonar model           | Suggested Agent API starting point |
| --------------------- | ---------------------------------- |
| `sonar`               | `fast`                             |
| `sonar-pro`           | `low`                              |
| `sonar-reasoning`     | `medium`                           |
| `sonar-reasoning-pro` | `medium`                           |
| `sonar-deep-research` | `high`                             |

For example:

```ts
// 2.0.45 and earlier (Sonar)
perplexity('sonar-pro');

// 2.1.0 and later (Agent API)
perplexity('low');
```

Move Sonar search and reasoning options to their Agent API locations:

| Sonar provider option                    | Agent API option                       |
| ---------------------------------------- | -------------------------------------- |
| Domain, recency, and date filters        | `tools[].filters` on `web_search`      |
| `num_search_results`                     | `tools[].max_results`                  |
| `web_search_options.search_context_size` | `tools[].search_context_size`          |
| `web_search_options.user_location`       | `tools[].user_location`                |
| `reasoning_effort`                       | `reasoning.effort`                     |
| `disable_search`                         | Omit `web_search` for direct model IDs |

Preset tools cannot be removed individually. Use a direct model ID without a
`web_search` tool when search must be disabled, or set `max_tool_calls: 0` to
disable all preset tool calls.

The Agent API has no equivalent for Sonar PDF or video inputs, image or video
results, `search_language_filter`, or `stream_mode`. Related questions require
prompting or structured output. Remove these options during migration.

Language requests now use `/v1/agent`. Custom `baseURL` proxies must route that
path. Raw responses and streams use the Agent API's typed output and SSE event
formats, and Perplexity provider metadata, usage, cost, and source identifiers
can differ. The embeddings API is unchanged.

For PDF inputs, extract the document text before sending it to the Agent API,
or choose another provider that supports PDF input. Move image/video retrieval
and language-filtered search to a separate service if your application requires
those features. Rework consumers of raw Sonar stream events for typed Agent
events. See Perplexity's [migration
guide](https://docs.perplexity.ai/docs/agent-api/migrate-from-sonar/how-to)
for the full API-level comparison.

## Model Capabilities

| Model    | Image Input | Object Generation | Tool Usage | Tool Streaming |
| -------- | ----------- | ----------------- | ---------- | -------------- |
| `fast`   | ✓           | ✓                 | ✓          | ✓              |
| `low`    | ✓           | ✓                 | ✓          | ✓              |
| `medium` | ✓           | ✓                 | ✓          | ✓              |
| `high`   | ✓           | ✓                 | ✓          | ✓              |
| `xhigh`  | ✓           | ✓                 | ✓          | ✓              |

Please see the [Perplexity docs](https://docs.perplexity.ai) for detailed API
documentation and the latest updates.

---

For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md)

For an index of all available documentation, see [/llms.txt](/llms.txt)

For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)