> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://respan.ai/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://respan.ai/docs/_mcp/server.

# Provider: Perplexity

> **Note**
>
> This page is for **Respan LLM Gateway** users.

Respan supports both Perplexity Sonar models and the Perplexity Agent API while keeping unified observability for logs, cost, latency, and reliability.

| Perplexity API         | Respan endpoint              | How to select it                            |
| ---------------------- | ---------------------------- | ------------------------------------------- |
| Sonar Chat Completions | `POST /api/chat/completions` | Use a model such as `perplexity/sonar-pro`. |
| Agent API              | `POST /api/responses`        | Set `X-Respan-Route-Provider: perplexity`.  |

The Agent API can call Perplexity's own Sonar model or third-party models offered by Perplexity. Through Respan, use an explicit model or a nonempty fallback chain; preset-only requests do not pass the current model validation.

> **Note**
>
> Perplexity Sonar models require **bring your own key (BYOK)**. Sonar usage cannot be paid with Respan credits. The [Agent API](#use-perplexity-agent-api) has separate credential handling.

## Quick setup

#### Get a Respan API key

[Sign up](https://platform.respan.ai) and create a key on the [API keys page](https://platform.respan.ai/platform/gateway/api-keys).

#### Add your Perplexity credentials

Configure your Perplexity credentials on the [Providers page](https://platform.respan.ai/platform/gateway/api-keys?providers=1) before using the Sonar examples below. See [Use your own Perplexity key](#use-your-own-perplexity-key-byok).

## Send your first request

After configuring your Perplexity credentials in Respan, pick the integration that matches your stack. The base URL is `https://api.respan.ai/api` and your application authenticates with `RESPAN_API_KEY`.

#### OpenAI SDK

Perplexity is OpenAI-compatible. Point the OpenAI SDK at the Respan gateway and call any Perplexity model.

**`Python`**

```python Python
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_RESPAN_API_KEY",
    base_url="https://api.respan.ai/api",
)

response = client.chat.completions.create(
    model="perplexity/sonar-pro",
    messages=[{"role": "user", "content": "Hello, Perplexity!"}],
)
print(response.choices[0].message.content)
```

**`TypeScript`**

```typescript TypeScript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.RESPAN_API_KEY,
  baseURL: "https://api.respan.ai/api",
});

const response = await client.chat.completions.create({
  model: "perplexity/sonar-pro",
  messages: [{ role: "user", content: "Hello, Perplexity!" }],
});
console.log(response.choices[0].message.content);
```

#### Vercel AI SDK

Call `respan.chat(...)` explicitly to use the Gateway Chat Completions endpoint.

Use `@ai-sdk/openai` and point `createOpenAI` at the Respan gateway.

**`TypeScript`**

```typescript TypeScript
import { createOpenAI } from "@ai-sdk/openai";
import { generateText } from "ai";

const respan = createOpenAI({
  apiKey: process.env.RESPAN_API_KEY!,
  baseURL: "https://api.respan.ai/api",
});

const result = await generateText({
  model: respan.chat("perplexity/sonar-pro"),
  prompt: "Hello, Perplexity!",
});
console.log(result.text);
```

#### Respan API

Call the Respan REST API directly from any language.

**`Python`**

```python Python
import requests

response = requests.post(
    "https://api.respan.ai/api/chat/completions",
    headers={
        "Authorization": "Bearer YOUR_RESPAN_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "model": "perplexity/sonar-pro",
        "messages": [{"role": "user", "content": "Hello, Perplexity!"}],
    },
)
print(response.json()["choices"][0]["message"]["content"])
```

**`TypeScript`**

```typescript TypeScript
const response = await fetch("https://api.respan.ai/api/chat/completions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.RESPAN_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "perplexity/sonar-pro",
    messages: [{ role: "user", content: "Hello, Perplexity!" }],
  }),
});

const data = await response.json();
console.log(data.choices[0].message.content);
```

## Use Perplexity Agent API

Perplexity's Agent API uses the OpenAI Responses shape. The route is activated only by the `X-Respan-Route-Provider: perplexity` header. These examples call Perplexity's own Sonar model, `perplexity/sonar`.

**`Python`**

```python Python
import os
import requests

response = requests.post(
    "https://api.respan.ai/api/responses",
    headers={
        "Authorization": f"Bearer {os.environ['RESPAN_API_KEY']}",
        "Content-Type": "application/json",
        "X-Respan-Route-Provider": "perplexity",
    },
    json={
        "model": "perplexity/sonar",
        "input": "Research recent advances in retrieval-augmented generation.",
        "max_steps": 1,
        "respan_params": {
            "credential_override": {
                "": {
                    "api_key": os.environ["PERPLEXITY_API_KEY"],
                }
            }
        },
    },
)
response.raise_for_status()
print(response.json()["output"])
```

**`TypeScript`**

```typescript TypeScript
const response = await fetch("https://api.respan.ai/api/responses", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.RESPAN_API_KEY}`,
    "Content-Type": "application/json",
    "X-Respan-Route-Provider": "perplexity",
  },
  body: JSON.stringify({
    model: "perplexity/sonar",
    input: "Research recent advances in retrieval-augmented generation.",
    max_steps: 1,
    respan_params: {
      credential_override: {
        "": {
          api_key: process.env.PERPLEXITY_API_KEY,
        },
      },
    },
  }),
});
if (!response.ok) throw new Error(await response.text());
console.log((await response.json()).output);
```

This request uses `RESPAN_API_KEY` for Respan authentication and `PERPLEXITY_API_KEY` as a request-scoped provider credential. You can omit `respan_params.credential_override` if Perplexity is already configured under **Gateway → API keys → Bring your own key**, or when managed Perplexity credentials are available through Respan credits for the Agent API route.

The response reports the model returned by Perplexity and its authoritative USD cost. Set `stream: true` for Responses API server-sent events, or use `models` for an ordered fallback chain. Respan requires an explicit model or a nonempty fallback chain; preset-only requests do not pass its model validation.

For third-party model choices, see [Perplexity's Agent API model list](https://docs.perplexity.ai/docs/agent-api/models). Requests to those models still use the Perplexity route header and Perplexity credentials.

See the [Responses API guide](/docs/documentation/features/gateway/routing-and-passthrough#responses-api) for all request shapes, Agent API parameters, header rules, logging, and billing behavior.

## More integrations

Perplexity models work with every Respan gateway integration:

* [OpenAI SDK](/docs/integrations/openai-sdk)
* [OpenAI Agents SDK](/docs/integrations/openai-agents-sdk)
* [LangChain](/docs/integrations/langchain)
* [LangGraph](/docs/integrations/langgraph)
* [LlamaIndex](/docs/integrations/llama-index)
* [Pydantic AI](/docs/integrations/pydantic-ai)
* [Respan native (OTel)](/docs/documentation/features/gateway/gateway-quickstart)

## Switch models

Change the `model` parameter to call any supported model through the same client. Use the `perplexity/` prefix to disambiguate when routing across providers. Browse the full list on the [Models page](https://platform.respan.ai/platform/models).

```python
client.chat.completions.create(model="perplexity/sonar", messages=messages)
client.chat.completions.create(model="perplexity/sonar-pro", messages=messages)
client.chat.completions.create(model="perplexity/sonar-reasoning-pro", messages=messages)
client.chat.completions.create(model="openai/gpt-6-sol", messages=messages)
client.chat.completions.create(model="anthropic/claude-opus-5-5", messages=messages)
```

## Use your own Perplexity key (BYOK)

Perplexity Sonar models require your own Perplexity credentials. Configure them in Respan or pass them with each request using one of the options below.

#### Global (UI)

> **Note**
>
> Agent API credentials are provider-scoped. Legacy Sonar values in `available_models` do not restrict Agent API model, preset, or fallback requests.

#### Open Providers

Go to the [Providers page](https://platform.respan.ai/platform/gateway/api-keys?providers=1).

#### Add Perplexity

Select **Perplexity** and paste your `perplexity.api_key`. Grab one from the [Perplexity API settings page](https://www.perplexity.ai/settings/api).

#### Load balancing (Optional)

Add multiple credential sets and use **Load balancing weight** to distribute traffic across them.

#### Per-request (Code)

Pass `customer_credentials` on each [Gateway request](/docs/apis/gateway/create-chat-completion). Useful when serving end-user keys.

```json
{
  "customer_credentials": {
    "perplexity": {
      "api_key": "YOUR_PERPLEXITY_API_KEY"
    }
  }
}
```

### Override credentials per model (Optional)

Use [`credential_override`](/docs/documentation/admin/llm-provider-keys#per-model-credential-override) when one model on a request should use a different Perplexity key than the default.

```json
{
  "customer_credentials": {
    "perplexity": { "api_key": "YOUR_PERPLEXITY_API_KEY" }
  },
  "credential_override": {
    "perplexity/sonar-pro": { "api_key": "ANOTHER_PERPLEXITY_API_KEY" }
  }
}
```

## Log without proxying (Optional)

Already calling Perplexity directly? Send logs to Respan asynchronously to track cost, latency, and performance for those external calls.

```python
import requests

requests.post(
    "https://api.respan.ai/api/request-logs/create/",
    headers={
        "Authorization": "Bearer YOUR_RESPAN_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "model": "perplexity/sonar-pro",
        "prompt_messages": [{"role": "user", "content": "Hello, how are you?"}],
        "completion_message": {"role": "assistant", "content": "Hello from Perplexity through Respan."},
        "cost": 0.001,
        "generation_time": 1.2,
        "customer_params": {"customer_identifier": "user_123"},
    },
)
```

See the [logging guide](/docs/apis/spans/create-span) for the full setup.