# Create Agent Response
Source: https://docs.perplexity.ai/api-reference/agent-post

post /v1/agent
Generate a response for the provided input with optional web search and reasoning.



# Get Async Chat Completion
Source: https://docs.perplexity.ai/api-reference/async-sonar-api-request-get

get /v1/async/sonar/{api_request}
Retrieve the response for a given asynchronous chat completion request.



# List Async Chat Completions
Source: https://docs.perplexity.ai/api-reference/async-sonar-get

get /v1/async/sonar
Retrieve a list of all asynchronous chat completion requests for a given user.



# Create Async Chat Completion
Source: https://docs.perplexity.ai/api-reference/async-sonar-post

post /v1/async/sonar
Submit an asynchronous chat completion request.



# Create Contextualized Embeddings
Source: https://docs.perplexity.ai/api-reference/contextualized-embeddings-post

post /v1/contextualizedembeddings
Generate contextualized embeddings for document chunks. Chunks from the same document share context awareness, improving retrieval quality for document-based applications.



# Create Embeddings
Source: https://docs.perplexity.ai/api-reference/embeddings-post

post /v1/embeddings
Generate embeddings for a list of texts. Use these embeddings for semantic search, clustering, and other machine learning applications.



# Generate Auth Token
Source: https://docs.perplexity.ai/api-reference/generate-auth-token-post

post /generate_auth_token
Generates a new authentication token for API access.



# List Models
Source: https://docs.perplexity.ai/api-reference/models-get

get /v1/models
List the models available for the Agent API. Returns model identifiers that can be used with the `POST /v1/agent` endpoint. The response follows the OpenAI List Models format for compatibility with third-party tools.



# Revoke Auth Token
Source: https://docs.perplexity.ai/api-reference/revoke-auth-token-post

post /revoke_auth_token
Revokes an existing authentication token.



# Search the Web
Source: https://docs.perplexity.ai/api-reference/search-post

post /search
Search the web and retrieve relevant web page contents.



# Create Chat Completion
Source: https://docs.perplexity.ai/api-reference/sonar-post

post /v1/sonar
Generate a chat completion response for the given conversation.



# API Key Management
Source: https://docs.perplexity.ai/docs/admin/api-key-management

Learn how to generate, revoke, and rotate API keys for secure access

## Overview

API keys are essential for authenticating requests to the Perplexity API. This guide covers how to create, manage, and rotate your API keys using our authentication token management endpoints.

<Warning>
  **API keys are shown only once.** When you create an API key — through the console or programmatically — the full token is returned at that moment and **cannot be retrieved again**. Save it immediately to a secure location before closing the page or response.
</Warning>

<Info>
  API keys should be treated as sensitive credentials. Store them securely and never expose them in client-side code or public repositories.
</Info>

## Getting Started: Create Your API Group First

<Warning>
  **Important Prerequisites**: Before you can generate any API keys, you must first create an API group through the Perplexity web interface.
</Warning>

<Steps>
  <Step title="Create an API Group">
    Navigate to the API Groups page and create your first group:

    **[Create API Group →](https://console.perplexity.ai)**

    API groups help organize your keys and manage access across different projects or environments.

    <Tip>
      Choose a descriptive name for your API group (e.g., "Production", "Development", or your project name) to help with organization.
    </Tip>
  </Step>

  <Step title="Generate Your API Keys">
    Once you have an API group, navigate to the API Keys page to generate your first key:

    **[Generate API Keys →](https://console.perplexity.ai)**

    You can create multiple keys within each group for different purposes or environments. The full key value is displayed once at creation — copy it before leaving the page.
  </Step>
</Steps>

<Note>
  After creating your first API key through the web interface, you can use the programmatic endpoints below to generate and manage additional keys.
</Note>

## Key Management Endpoints

Perplexity provides two endpoints for managing API keys programmatically:

* **`/generate_auth_token`** - Creates a new API key
* **`/revoke_auth_token`** - Revokes an existing API key

<Warning>
  Once an API key is revoked, it cannot be recovered. Make sure to update your applications with new keys before revoking old ones.
</Warning>

## Generating API Keys

Create new API keys programmatically. Always provide a descriptive `token_name` — once a key is created, this name is the primary way to identify it later, since the full token value is no longer visible.

### Request

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.perplexity.ai/generate_auth_token \
    --header "Authorization: Bearer YOUR_EXISTING_API_KEY" \
    --header "Content-Type: application/json" \
    --data '{
      "token_name": "Production API Key"
    }'
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.perplexity.ai/generate_auth_token"
  headers = {
      "Authorization": "Bearer YOUR_EXISTING_API_KEY",
      "Content-Type": "application/json"
  }
  payload = {
      "token_name": "Production API Key"  # Optional
  }

  response = requests.post(url, headers=headers, json=payload)
  data = response.json()
  print(f"New API Key: {data['auth_token']}")
  print(f"Created at: {data['created_at_epoch_seconds']}")
  ```

  ```typescript Typescript theme={null}
  const response = await fetch("https://api.perplexity.ai/generate_auth_token", {
    method: "POST",
    headers: {
      "Authorization": "Bearer YOUR_EXISTING_API_KEY",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      token_name: "Production API Key"  // Optional
    })
  });

  const data = await response.json();
  console.log(`New API Key: ${data.auth_token}`);
  console.log(`Created at: ${data.created_at_epoch_seconds}`);
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "auth_token": "pplx-1234567890abcdef",
  "created_at_epoch_seconds": 1735689600,
  "token_name": "Production API Key"
}
```

<Warning>
  Store the `auth_token` immediately and securely. This is the **only** time the full token value is returned — it cannot be retrieved later from any endpoint or from the console.
</Warning>

## Revoking API Keys

Revoke API keys that are no longer needed or may have been compromised.

### Request

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.perplexity.ai/revoke_auth_token \
    --header "Authorization: Bearer $PERPLEXITY_API_KEY" \
    --header "Content-Type: application/json" \
    --data '{
      "auth_token": "pplx-1234567890abcdef"
    }'
  ```

  ```python Python theme={null}
  import os
  import requests

  url = "https://api.perplexity.ai/revoke_auth_token"
  headers = {
      "Authorization": f"Bearer {os.environ.get('PERPLEXITY_API_KEY')}",
      "Content-Type": "application/json"
  }
  payload = {
      "auth_token": "pplx-1234567890abcdef"
  }

  response = requests.post(url, headers=headers, json=payload)
  if response.status_code == 200:
      print("API key successfully revoked")
  ```

  ```typescript Typescript theme={null}
  const response = await fetch("https://api.perplexity.ai/revoke_auth_token", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.PERPLEXITY_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      auth_token: "pplx-1234567890abcdef"
    })
  });

  if (response.status === 200) {
    console.log("API key successfully revoked");
  }
  ```
</CodeGroup>

### Response

Returns a `200 OK` status code on successful revocation.

## API Key Rotation

Regular key rotation is a security best practice that minimizes the impact of potential key compromises. Here's how to implement zero-downtime key rotation:

### Rotation Strategy

<Steps>
  <Step title="Generate New Key">
    Create a new API key while your current key is still active:

    ```python theme={null}
    # Generate new key
    new_key_response = requests.post(
        "https://api.perplexity.ai/generate_auth_token",
        headers={"Authorization": f"Bearer {current_key}"},
        json={"token_name": f"Rotated Key - {datetime.now().isoformat()}"}
    )
    new_key = new_key_response.json()["auth_token"]
    ```
  </Step>

  <Step title="Update Applications">
    Deploy the new key to your applications:

    ```python theme={null}
    # Update environment variables or secrets management
    os.environ["PERPLEXITY_API_KEY"] = new_key

    # Verify new key works
    test_response = requests.post(
        "https://api.perplexity.ai/v1/sonar",
        headers={"Authorization": f"Bearer {new_key}"},
        json={
            "model": "sonar",
            "messages": [{"role": "user", "content": "Test"}]
        }
    )
    assert test_response.status_code == 200
    ```
  </Step>

  <Step title="Monitor Transition">
    Ensure all services are using the new key before proceeding:

    ```python theme={null}
    # Monitor your application logs to confirm
    # all instances are using the new key
    time.sleep(300)  # Wait for propagation
    ```
  </Step>

  <Step title="Revoke Old Key">
    Once confirmed, revoke the old key:

    ```python theme={null}
    # Revoke old key
    revoke_response = requests.post(
        "https://api.perplexity.ai/revoke_auth_token",
        headers={"Authorization": f"Bearer {new_key}"},
        json={"auth_token": current_key}
    )
    assert revoke_response.status_code == 200
    print("Key rotation completed successfully")
    ```
  </Step>
</Steps>

### Automated Rotation Example

Here's a complete example of an automated key rotation script:

<CodeGroup>
  ```python Python theme={null}
  import requests
  import os
  import time
  from datetime import datetime
  import logging

  logging.basicConfig(level=logging.INFO)
  logger = logging.getLogger(__name__)

  class PerplexityKeyRotator:
      def __init__(self, current_key):
          self.base_url = "https://api.perplexity.ai"
          self.current_key = current_key

      def generate_new_key(self, name=None):
          """Generate a new API key"""
          url = f"{self.base_url}/generate_auth_token"
          headers = {"Authorization": f"Bearer {self.current_key}"}
          payload = {}
          if name:
              payload["token_name"] = name

          response = requests.post(url, headers=headers, json=payload)
          response.raise_for_status()
          return response.json()

      def test_key(self, key):
          """Test if a key is valid"""
          url = f"{self.base_url}/v1/sonar"
          headers = {"Authorization": f"Bearer {key}"}
          payload = {
              "model": "sonar",
              "messages": [{"role": "user", "content": "Test"}],
              "max_tokens": 1
          }

          try:
              response = requests.post(url, headers=headers, json=payload)
              return response.status_code == 200
          except:
              return False

      def revoke_key(self, key_to_revoke):
          """Revoke an API key"""
          url = f"{self.base_url}/revoke_auth_token"
          headers = {"Authorization": f"Bearer {self.current_key}"}
          payload = {"auth_token": key_to_revoke}

          response = requests.post(url, headers=headers, json=payload)
          return response.status_code == 200

      def rotate_key(self, update_callback=None):
          """Perform complete key rotation"""
          logger.info("Starting key rotation...")

          # Step 1: Generate new key
          new_key_data = self.generate_new_key(
              name=f"Rotated-{datetime.now().strftime('%Y%m%d-%H%M%S')}"
          )
          new_key = new_key_data["auth_token"]
          logger.info(f"New key generated: {new_key[:10]}...")

          # Step 2: Test new key
          if not self.test_key(new_key):
              raise Exception("New key validation failed")
          logger.info("New key validated successfully")

          # Step 3: Update application (callback)
          if update_callback:
              update_callback(new_key)
              logger.info("Application updated with new key")

          # Step 4: Wait for propagation
          logger.info("Waiting for propagation...")
          time.sleep(30)

          # Step 5: Revoke old key
          old_key = self.current_key
          self.current_key = new_key  # Use new key for revocation

          if self.revoke_key(old_key):
              logger.info("Old key revoked successfully")
          else:
              logger.warning("Failed to revoke old key")

          logger.info("Key rotation completed")
          return new_key

  # Usage example
  def update_environment(new_key):
      """Update your environment with the new key"""
      os.environ["PERPLEXITY_API_KEY"] = new_key
      # Update your secrets management system here
      # update_aws_secrets_manager(new_key)
      # update_kubernetes_secret(new_key)

  # Perform rotation
  rotator = PerplexityKeyRotator(os.environ["PERPLEXITY_API_KEY"])
  new_key = rotator.rotate_key(update_callback=update_environment)
  print(f"Rotation complete. New key: {new_key[:10]}...")
  ```

  ```typescript Typescript theme={null}
  import fetch from 'node-fetch';

  class PerplexityKeyRotator {
    private baseUrl = 'https://api.perplexity.ai';
    private currentKey: string;

    constructor(currentKey: string) {
      this.currentKey = currentKey;
    }

    async generateNewKey(name?: string): Promise<{
      auth_token: string;
      created_at_epoch_seconds: number;
      token_name?: string;
    }> {
      const response = await fetch(`${this.baseUrl}/generate_auth_token`, {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${this.currentKey}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify(name ? { token_name: name } : {})
      });

      if (!response.ok) {
        throw new Error(`Failed to generate key: ${response.statusText}`);
      }

      return response.json();
    }

    async testKey(key: string): Promise<boolean> {
      try {
        const response = await fetch(`${this.baseUrl}/v1/sonar`, {
          method: 'POST',
          headers: {
            'Authorization': `Bearer ${key}`,
            'Content-Type': 'application/json'
          },
          body: JSON.stringify({
            model: 'sonar',
            messages: [{ role: 'user', content: 'Test' }],
            max_tokens: 1
          })
        });

        return response.ok;
      } catch {
        return false;
      }
    }

    async revokeKey(keyToRevoke: string): Promise<boolean> {
      const response = await fetch(`${this.baseUrl}/revoke_auth_token`, {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${this.currentKey}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({ auth_token: keyToRevoke })
      });

      return response.ok;
    }

    async rotateKey(updateCallback?: (newKey: string) => Promise<void>): Promise<string> {
      console.log('Starting key rotation...');

      // Step 1: Generate new key
      const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
      const newKeyData = await this.generateNewKey(`Rotated-${timestamp}`);
      const newKey = newKeyData.auth_token;
      console.log(`New key generated: ${newKey.substring(0, 10)}...`);

      // Step 2: Test new key
      if (!(await this.testKey(newKey))) {
        throw new Error('New key validation failed');
      }
      console.log('New key validated successfully');

      // Step 3: Update application
      if (updateCallback) {
        await updateCallback(newKey);
        console.log('Application updated with new key');
      }

      // Step 4: Wait for propagation
      console.log('Waiting for propagation...');
      await new Promise(resolve => setTimeout(resolve, 30000));

      // Step 5: Revoke old key
      const oldKey = this.currentKey;
      this.currentKey = newKey;

      if (await this.revokeKey(oldKey)) {
        console.log('Old key revoked successfully');
      } else {
        console.warn('Failed to revoke old key');
      }

      console.log('Key rotation completed');
      return newKey;
    }
  }

  // Usage example
  async function updateEnvironment(newKey: string): Promise<void> {
    process.env.PERPLEXITY_API_KEY = newKey;
    // Update your secrets management system here
    // await updateAwsSecretsManager(newKey);
    // await updateKubernetesSecret(newKey);
  }

  // Perform rotation
  const rotator = new PerplexityKeyRotator(process.env.PERPLEXITY_API_KEY!);
  const newKey = await rotator.rotateKey(updateEnvironment);
  console.log(`Rotation complete. New key: ${newKey.substring(0, 10)}...`);
  ```
</CodeGroup>

## Best Practices

<CardGroup>
  <Card title="Use Environment Variables">
    Never hardcode API keys in your source code. Store them in environment variables or secure secret management systems.

    **Good**: `os.environ["PERPLEXITY_API_KEY"]`

    **Bad**: `api_key = "pplx-1234567890abcdef"`
  </Card>

  <Card title="Implement Key Rotation">
    Rotate your API keys regularly (e.g., every 90 days) to minimize the impact of potential compromises.

    Set up automated rotation scripts to ensure zero downtime during the rotation process.
  </Card>

  <Card title="Use Descriptive Names">
    Always set `token_name` when generating a key. After creation, the name is the primary way to identify a key, since the full token value is no longer visible.

    Examples: "Production-Main", "Development-Testing", "CI/CD-Pipeline"
  </Card>

  <Card title="Monitor Key Usage">
    Track which keys are being used in your applications and revoke unused keys promptly.

    Maintain an inventory of active keys and their purposes.
  </Card>
</CardGroup>

## Security Considerations

<Warning>
  **Never expose API keys in:**

  * Client-side JavaScript code
  * Mobile applications
  * Public repositories
  * Log files or error messages
  * URLs or query parameters
</Warning>

### If a Key is Compromised

1. **Immediately generate a new key** using `/generate_auth_token`
2. **Update all applications** to use the new key
3. **Revoke the compromised key** using `/revoke_auth_token`
4. **Review access logs** to identify any unauthorized usage
5. **Implement additional security measures** such as IP allowlisting if available

## Troubleshooting

| Issue                                  | Solution                                                         |
| -------------------------------------- | ---------------------------------------------------------------- |
| "Authentication failed" after rotation | Ensure the new key has propagated to all service instances       |
| Cannot revoke a key                    | Verify you're using a valid API key with appropriate permissions |
| Key generation fails                   | Check your account status and API tier limits                    |
| Services still using old key           | Implement proper secret rotation in your deployment pipeline     |

<Info>
  For additional support with API key management, visit the [API Platform console](https://console.perplexity.ai) or contact our support team.
</Info>


# Rate Limits & Usage Tiers
Source: https://docs.perplexity.ai/docs/admin/rate-limits-usage-tiers



## What are Usage Tiers?

Usage tiers determine your **rate limits** and access to **beta features** based on your cumulative API spending. As you spend more on API credits over time, you automatically advance to higher tiers with increased rate limits. Higher tiers unlock significantly more requests per minute, and once you reach a tier, you keep it permanently with no downgrade.

<Info>
  You can check your current usage tier by visiting the [API Platform console](https://console.perplexity.ai).
</Info>

***

## Tier Progression

| Tier       | Total Credits Purchased | Status                       |
| ---------- | ----------------------- | ---------------------------- |
| **Tier 0** | \$0                     | New accounts, limited access |
| **Tier 1** | \$50+                   | Light usage, basic limits    |
| **Tier 2** | \$250+                  | Regular usage                |
| **Tier 3** | \$500+                  | Heavy usage                  |
| **Tier 4** | \$1,000+                | Production usage             |
| **Tier 5** | \$5,000+                | Enterprise usage             |

<Note>
  Tiers are based on **cumulative purchases** across your account lifetime, not current balance.
</Note>

***

## Agent API Rate Limits

The Agent API uses tier-based rate limits that scale with your usage tier:

|    Tier    | QPS (Queries per Second) | Requests per Minute |
| :--------: | :----------------------: | :-----------------: |
| **Tier 0** |           1 QPS          |        50/min       |
| **Tier 1** |           3 QPS          |       150/min       |
| **Tier 2** |           8 QPS          |       500/min       |
| **Tier 3** |          17 QPS          |      1,000/min      |
| **Tier 4** |          33 QPS          |      2,000/min      |
| **Tier 5** |          33 QPS          |      2,000/min      |

***

## Search API Rate Limits

The Search API has separate rate limits that apply to all usage tiers:

| Endpoint       | Rate Limit             | Burst Capacity |
| -------------- | ---------------------- | -------------- |
| POST `/search` | 50 requests per second | 50 requests    |

**Search Rate Limiter Behavior:**

* **Burst**: Can handle 50 requests instantly
* **Sustained**: Exactly 50 QPS average over time

<Note>
  Search rate limits are independent of your usage tier and apply consistently across all accounts using the same leaky bucket algorithm.
</Note>

***

## Sonar API Rate Limits

The Sonar API uses tier-based rate limits that scale with your usage tier:

<Tabs>
  <Tab title="Tier 0">
    | Model                              | Requests per minute (RPM) |
    | ---------------------------------- | ------------------------- |
    | `sonar-deep-research`              | 5                         |
    | `sonar-reasoning-pro`              | 50                        |
    | `sonar-pro`                        | 50                        |
    | `sonar`                            | 50                        |
    | POST `/v1/async/sonar`             | 5                         |
    | GET `/v1/async/sonar`              | 3000                      |
    | GET `/v1/async/sonar/{request_id}` | 6000                      |
  </Tab>

  <Tab title="Tier 1">
    | Model                              | Requests per minute (RPM) |
    | ---------------------------------- | ------------------------- |
    | `sonar-deep-research`              | 10                        |
    | `sonar-reasoning-pro`              | 150                       |
    | `sonar-pro`                        | 150                       |
    | `sonar`                            | 150                       |
    | POST `/v1/async/sonar`             | 10                        |
    | GET `/v1/async/sonar`              | 3000                      |
    | GET `/v1/async/sonar/{request_id}` | 6000                      |
  </Tab>

  <Tab title="Tier 2">
    | Model                              | Requests per minute (RPM) |
    | ---------------------------------- | ------------------------- |
    | `sonar-deep-research`              | 20                        |
    | `sonar-reasoning-pro`              | 500                       |
    | `sonar-pro`                        | 500                       |
    | `sonar`                            | 500                       |
    | POST `/v1/async/sonar`             | 20                        |
    | GET `/v1/async/sonar`              | 3000                      |
    | GET `/v1/async/sonar/{request_id}` | 6000                      |
  </Tab>

  <Tab title="Tier 3">
    | Model                              | Requests per minute (RPM) |
    | ---------------------------------- | ------------------------- |
    | `sonar-deep-research`              | 40                        |
    | `sonar-reasoning-pro`              | 1,000                     |
    | `sonar-pro`                        | 1,000                     |
    | `sonar`                            | 1,000                     |
    | POST `/v1/async/sonar`             | 40                        |
    | GET `/v1/async/sonar`              | 3000                      |
    | GET `/v1/async/sonar/{request_id}` | 6000                      |
  </Tab>

  <Tab title="Tier 4">
    | Model                              | Requests per minute (RPM) |
    | ---------------------------------- | ------------------------- |
    | `sonar-deep-research`              | 60                        |
    | `sonar-reasoning-pro`              | 4,000                     |
    | `sonar-pro`                        | 4,000                     |
    | `sonar`                            | 4,000                     |
    | POST `/v1/async/sonar`             | 60                        |
    | GET `/v1/async/sonar`              | 3000                      |
    | GET `/v1/async/sonar/{request_id}` | 6000                      |
  </Tab>

  <Tab title="Tier 5">
    | Model                              | Requests per minute (RPM) |
    | ---------------------------------- | ------------------------- |
    | `sonar-deep-research`              | 100                       |
    | `sonar-reasoning-pro`              | 4,000                     |
    | `sonar-pro`                        | 4,000                     |
    | `sonar`                            | 4,000                     |
    | POST `/v1/async/sonar`             | 100                       |
    | GET `/v1/async/sonar`              | 3000                      |
    | GET `/v1/async/sonar/{request_id}` | 6000                      |
  </Tab>
</Tabs>

***

## Embeddings API Rate Limits

The Embeddings API uses tier-based rate limits that scale with your usage tier. Limits are higher than other APIs because each request is a single forward pass on an elastic backend.

|      Tier     | QPS (Queries per Second) |
| :-----------: | :----------------------: |
|   **Tier 0**  |          85 QPS          |
| **Tiers 1–3** |          170 QPS         |
| **Tiers 4–5** |          335 QPS         |

### Contextualized Embeddings

Contextualized embeddings have separate, higher limits (5× the standard embeddings tiers):

|      Tier     | QPS (Queries per Second) |
| :-----------: | :----------------------: |
|   **Tier 0**  |          415 QPS         |
| **Tiers 1–3** |          835 QPS         |
| **Tiers 4–5** |         1,670 QPS        |

<Note>
  Contextualized embeddings are rate limited by **total chunks**, not by request count.
</Note>

***

## How Rate Limiting Works

Our rate limiting system uses a **leaky bucket algorithm** that allows for burst traffic while maintaining strict long-term rate control.

### Technical Implementation

<AccordionGroup>
  <Accordion title="Leaky Bucket Algorithm Explained">
    The leaky bucket algorithm works like a bucket with a small hole in the bottom:

    * **Bucket Capacity**: Maximum number of requests you can make instantly (burst capacity)
    * **Leak Rate**: How quickly tokens leak out of the bucket (your rate limit)
    * **Token Refill**: Tokens refill continuously at regular intervals based on your rate limit

    This design allows legitimate burst traffic when you need it, prevents sustained abuse, and ensures predictable and fair rate enforcement across all users.
  </Accordion>

  <Accordion title="Rate Limiter Behavior Example">
    Let's examine how **50 requests per second** works in practice. With a capacity of 50 tokens and a leak rate of 50 tokens per second, one token refills every 20ms.

    **Scenario 1: Burst Traffic**

    ```
    Time 0.0s: Bucket full (50 tokens)
    → Send 50 requests instantly → ALL ALLOWED
    → Send 51st request → REJECTED (bucket empty)

    Time 0.020s: 1 token refilled
    → Send 1 request → ALLOWED
    → Send 2nd request → REJECTED

    Time 0.040s: 1 more token refilled
    → Send 1 request → ALLOWED
    ```

    **Scenario 2: Steady 50 QPS**

    ```
    Request every 20ms:
    Time 0.0s: Request → ALLOWED (50→49 tokens)
    Time 0.020s: Request → ALLOWED (49+1-1=49 tokens)
    Time 0.040s: Request → ALLOWED (49+1-1=49 tokens)
    ... maintains 49-50 tokens, all requests pass
    ```

    **Scenario 3: Slightly Over 50 QPS**

    ```
    Request every 19ms (≈52.6 QPS):
    → Eventually tokens deplete faster than refill
    → Some requests start getting rejected
    → Achieves exactly 50 QPS on average
    ```
  </Accordion>

  <Accordion title="Real-World Implications">
    The leaky bucket design means you can handle your full rate limit instantly, making it perfect for batch operations or sudden traffic spikes. There's no need to artificially spread requests when you have available burst capacity.

    The system enforces strict average rate limits over time while allowing quick recovery after burst usage. This provides consistent performance across different usage patterns and prevents sustained over-limit usage while maintaining fair resource allocation.

    When building your application, take advantage of burst capacity for batch operations, monitor your usage patterns to optimize request timing, and implement proper error handling for 429 responses.
  </Accordion>
</AccordionGroup>

***

## What Happens When You Hit Rate Limits?

When you exceed your rate limits:

1. **429 Error** - Your request gets rejected with "Too Many Requests"
2. **Continuous Refill** - Tokens refill continuously based on your rate limit
3. **Immediate Recovery** - New requests become available as soon as tokens refill

**Example Recovery Times:**

* **50 QPS limit**: 1 token refills every 20ms
* **500 QPS limit**: 1 token refills every 2ms
* **1,000 QPS limit**: 1 token refills every 1ms

<Tip>
  **Best Practices:**

  * Monitor your usage to predict when you'll need higher tiers
  * Consider upgrading your tier proactively for production applications
  * Implement exponential backoff with jitter in your code
  * Take advantage of burst capacity for batch operations
  * Don't artificially spread requests if you have available burst capacity
</Tip>

***

## Upgrading Your Tier

<Steps>
  <Step title="Check Current Tier">
    Visit the [API Platform console](https://console.perplexity.ai) to see your current tier and total spending.
  </Step>

  <Step title="Purchase More Credits">
    Add credits to your account through the billing section. Your tier will automatically upgrade once you reach the spending threshold.
  </Step>

  <Step title="Verify Upgrade">
    Your new rate limits take effect immediately after the tier upgrade. Check your settings page to confirm.
  </Step>

  <Step title="Need Even Higher Limits?">
    If you require custom rate limits beyond Tier 5, [fill out our rate limit increase request form](https://perplexity.typeform.com/to/yctmfyVT) and we'll review your use case to accommodate your needs.
  </Step>
</Steps>

<Check>
  Higher tiers significantly improve your API experience with increased rate limits, especially important for production applications.
</Check>

<Card title="Need Higher Rate Limits?" icon="file-pencil" href="https://perplexity.typeform.com/to/yctmfyVT">
  Need custom rate limits beyond your current tier? Fill out our rate limit increase request form and we'll review your use case to accommodate your needs.
</Card>


# Search Filters
Source: https://docs.perplexity.ai/docs/agent-api/filters

Control and customize Agent API search results with filters

Control which search results are returned by applying filters to your web search queries. Filters help you focus on specific domains, time periods, or geographic locations to get more relevant results.

## Domain Filters

Domain filters allow you to include or exclude specific domains or URLs from search results. Use allowlist mode to restrict results to trusted sources, or denylist mode to filter out unwanted domains.

<Warning>
  You can add a maximum of 20 domains or URLs to the `search_domain_filter` list. The filter works in either allowlist mode (include only) or denylist mode (exclude), but not both simultaneously.
</Warning>

**Allowlist mode**: Include only the specified domains/URLs (no `-` prefix)\
**Denylist mode**: Exclude the specified domains/URLs (use `-` prefix)

You can filter at the domain level (e.g., `wikipedia.org`) or URL level (e.g., `https://en.wikipedia.org/wiki/Chess`) for granular control.

```python Python theme={null}
from perplexity import Perplexity

client = Perplexity()

response = client.responses.create(
    preset="fast-search",
    input="Tell me about the James Webb Space Telescope discoveries.",
    instructions="You are a helpful assistant.",
    tools=[
        {
            "type": "web_search",
            "filters": {
                "search_domain_filter": [
                    "nasa.gov",
                    "wikipedia.org",
                    "space.com"
                ]
            }
        }
    ]
)

print(response.output_text)
```

## Date & Time Filters

Date and time filters help you find content published or updated within specific time periods. You can filter by publication date, last updated date, or use recency filters for relative time periods.

**Publication date filters**: Filter by when content was originally published

* `search_after_date_filter`: Include content published after this date
* `search_before_date_filter`: Include content published before this date

**Last updated filters**: Filter by when content was last modified

* `last_updated_after_filter`: Include content updated after this date
* `last_updated_before_filter`: Include content updated before this date

**Recency filter**: Filter by relative time periods

* `search_recency_filter`: Use `"hour"`, `"day"`, `"week"`, `"month"`, or `"year"` for content from the past hour, 24 hours, 7 days, 30 days, or 365 days. Use `hour` for real-time data such as breaking news or live events.

<Info>
  Specific date filters must be provided in the "%m/%d/%Y" format (e.g., "3/1/2025"). Recency filters use predefined values like "hour", "day", "week", "month", or "year".
</Info>

```python Python theme={null}
from perplexity import Perplexity

client = Perplexity()

response = client.responses.create(
    preset="pro-search",
    input="What are the latest AI developments?",
    instructions="You are an expert on current events.",
    tools=[
        {
            "type": "web_search",
            "filters": {
                "search_recency_filter": "hour"
            }
        }
    ]
)

print(response.output_text)

# Week recency
response = client.responses.create(
    preset="pro-search",
    input="What are the latest AI developments?",
    instructions="You are an expert on current events.",
    tools=[
        {
            "type": "web_search",
            "filters": {
                "search_recency_filter": "week"
            }
        }
    ]
)

print(response.output_text)
```

## Location Filters

Location filters tailor search results based on geographic context. This is useful for finding local businesses, regional news, or location-specific information.

You can specify location using:

* **Country code**: Two-letter ISO 3166-1 alpha-2 code (e.g., `"US"`, `"FR"`)
* **City and region**: Improve accuracy with city and region names
* **Coordinates**: Latitude and longitude for precise location targeting

<Tip>
  The `city` and `region` fields significantly improve location accuracy. We strongly recommend including them alongside coordinates and country code for the best results.
</Tip>

<Warning>
  Latitude and longitude must be provided alongside the country parameter—they cannot be provided on their own.
</Warning>

```python Python theme={null}
from perplexity import Perplexity

client = Perplexity()

response = client.responses.create(
    preset="pro-search",
    input="What are some good coffee shops nearby?",
    instructions="You are a helpful local guide.",
    tools=[
        {
            "type": "web_search",
            "user_location": {
                "country": "US",
                "region": "California",
                "city": "San Francisco",
                "latitude": 37.7749,
                "longitude": -122.4194
            }
        }
    ]
)

print(response.output_text)
```

## Combining Filters

You can combine multiple filter types in a single request to create highly targeted searches. For example, you might restrict results to specific domains published within a recent time period, or filter by location and date range together.

```python Python theme={null}
from perplexity import Perplexity

client = Perplexity()

response = client.responses.create(
    preset="pro-search",
    input="Latest tech news from trusted sources.",
    instructions="You are an expert on technology.",
    tools=[
        {
            "type": "web_search",
            "filters": {
                "search_domain_filter": ["techcrunch.com", "theverge.com"],
                "search_recency_filter": "week"
            },
            "user_location": {
                "country": "US"
            }
        }
    ]
)

print(response.output_text)
```

## Next Steps

<CardGroup>
  <Card title="Agent API Quickstart" icon="rocket" href="/docs/agent-api/quickstart">
    Get started with the Agent API.
  </Card>

  <Card title="Models" icon="brain" href="/docs/agent-api/models">
    Explore direct model selection and third-party models.
  </Card>
</CardGroup>


# Image Attachments
Source: https://docs.perplexity.ai/docs/agent-api/image-attachments

Learn how to upload and analyze images using base64 encoding or HTTPS URLs

## Overview

The Agent API supports image analysis through direct image uploads. Images can be provided either as base64 encoded strings within a data URI or as standard HTTPS URLs.

<Warning>
  * When using base64 encoding, the API currently only supports images up to 50 MB per image.
  * Supported formats for base64 encoded images: PNG (image/png), JPEG (image/jpeg), WEBP (image/webp), and GIF (image/gif).
  * When using an HTTPS URL, the model will attempt to fetch the image from the provided URL. Ensure the URL is publicly accessible.
</Warning>

## Examples

<Tabs>
  <Tab title="Base64 Encoded Data">
    <Info>Use this method when you have the image file locally and want to embed it directly into the request payload. Remember the 50MB size limit and supported formats (PNG, JPEG, WEBP, GIF).</Info>

    <CodeGroup>
      ```python Python theme={null}
      import base64
      from perplexity import Perplexity

      client = Perplexity()

      # Read and encode image as base64
      def encode_image(image_path):
          with open(image_path, "rb") as image_file:
              return base64.b64encode(image_file.read()).decode("utf-8")

      image_path = "image.png"
      base64_image = encode_image(image_path)

      # Analyze the image
      response = client.responses.create(
          model="openai/gpt-5.5",
          input=[
              {
                  "role": "user",
                  "content": [
                      {"type": "input_text", "text": "what's in this image?"},
                      {
                          "type": "input_image",
                          "image_url": f"data:image/png;base64,{base64_image}",
                      },
                  ],
              }
          ],
      )

      print(response.output_text)
      ```

      ```typescript TypeScript theme={null}
      import Perplexity from '@perplexity-ai/perplexity_ai';
      import * as fs from 'fs';

      const client = new Perplexity();

      // Read and encode image as base64
      const imageBuffer = fs.readFileSync('image.png');
      const base64Image = imageBuffer.toString('base64');
      const imageDataUri = `data:image/png;base64,${base64Image}`;

      // Analyze the image
      const response = await client.responses.create({
          model: 'openai/gpt-5-mini',
          input: [
              {
                  role: 'user',
                  content: [
                      { type: 'input_text', text: "What's in this image?" },
                      { type: 'input_image', image_url: imageDataUri }
                  ]
              }
          ],
      } as any);

      console.log(response.output_text);
      ```

      ```bash cURL theme={null}
      curl https://api.perplexity.ai/v1/agent \
        -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{
          "model": "openai/gpt-5-mini",
          "input": [
            {
              "role": "user",
              "content": [
                {
                  "type": "input_text",
                  "text": "What'\''s in this image?"
                },
                {
                  "type": "input_image",
                  "image_url": "data:image/png;base64,$BASE64_ENCODED_IMAGE"
                }
              ]
            }
          ]
        }' | jq
      ```
    </CodeGroup>
  </Tab>

  <Tab title="HTTPS URL">
    <Info>Use this method when you have a publicly accessible image URL. The model will fetch the image from the provided URL.</Info>

    <CodeGroup>
      ```python Python theme={null}
      from perplexity import Perplexity

      client = Perplexity()

      image_url = "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg"

      # Analyze the image
      response = client.responses.create(
          model="openai/gpt-5.5",
          input=[
              {
                  "role": "user",
                  "content": [
                      {"type": "input_text", "text": "Can you describe the image at this URL?"},
                      {
                          "type": "input_image",
                          "image_url": image_url,
                      },
                  ],
              }
          ],
      )

      print(response.output_text)
      ```

      ```typescript TypeScript theme={null}
      import Perplexity from '@perplexity-ai/perplexity_ai';

      const client = new Perplexity();

      const imageHttpsUrl = "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg";

      // Analyze the image
      const response = await client.responses.create({
          model: 'openai/gpt-5-mini',
          input: [
              {
                  role: 'user',
                  content: [
                      { type: 'input_text', text: 'Can you describe the image at this URL?' },
                      { type: 'input_image', image_url: imageHttpsUrl }
                  ]
              }
          ],
      } as any);

      console.log(response.output_text);
      ```

      ```bash cURL theme={null}
      curl https://api.perplexity.ai/v1/agent \
        -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{
          "model": "openai/gpt-5-mini",
          "input": [
            {
              "role": "user",
              "content": [
                {
                  "type": "input_text",
                  "text": "Can you describe the image at this URL?"
                },
                {
                  "type": "input_image",
                  "image_url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg"
                }
              ]
            }
          ]
        }' | jq
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Request Format

### Agent API

Images must be embedded in the `input` array when using message array format. Each image should be provided using the following structure:

```json theme={null}
{
  "role": "user",
  "content": [
    {
      "type": "input_text",
      "text": "What's in this image?"
    },
    {
      "type": "input_image",
      "image_url": "<IMAGE_URL_OR_BASE64_DATA>"
    }
  ]
}
```

The `image_url` field accepts either:

* **A URL of the image**: A publicly accessible HTTPS URL pointing directly to the image file
* **The base64 encoded image data**: A data URI in the format `data:image/{format};base64,{base64_content}`

## Pricing

Images are tokenized based on their pixel dimensions using the following formula:

```
tokens = (width px × height px) / 750
```

**Examples:**

* A 1024×768 image would consume: (1024 × 768) / 750 = 1,048 tokens
* A 512×512 image would consume: (512 × 512) / 750 = 349 tokens

These image tokens are then priced according to the input token pricing of the model you're using. The image tokens are added to your total token count for the request alongside any text tokens.

## Next Steps

<CardGroup>
  <Card title="Agent API Quickstart" icon="rocket" href="/docs/agent-api/quickstart">
    Get started with the Agent API
  </Card>

  <Card title="Web Search" icon="settings-bolt" href="/docs/agent-api/tools/web-search">
    Learn about the `web_search` tool.
  </Card>
</CardGroup>


# Model Fallback
Source: https://docs.perplexity.ai/docs/agent-api/model-fallback

Specify multiple models in a fallback chain for higher availability and automatic failover.

## Overview

Model fallback enables specifying multiple models in a `models` array. The API tries each model in order until one succeeds, providing automatic failover when a model is unavailable.

## How It Works

Provide a `models` array containing up to 5 models:

1. The API tries the first model in the array
2. If it fails or is unavailable, the next model is tried
3. This continues until one succeeds or all models are exhausted

The `models` array takes precedence over the single `model` field when both are provided.

<Info>
  **Benefits:**

  * **Higher availability**: Automatic failover when primary model is unavailable
  * **Provider redundancy**: Use models from different providers for maximum reliability
  * **Seamless operation**: No code refactoring needed, fallback is handled automatically by the API
</Info>

## Basic Example

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity

  client = Perplexity()

  response = client.responses.create(
      models=["openai/gpt-5.5", "openai/gpt-5.4", "openai/gpt-5-mini"],
      input="What are the latest developments in AI?",
      instructions="You have access to a web_search tool. Use it for questions about current events.",
  )

  print(f"Model used: {response.model}")
  ```

  ```typescript Typescript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  const response = await client.responses.create({
      models: ["openai/gpt-5.5", "openai/gpt-5.4", "openai/gpt-5-mini"],
      input: "What are the latest developments in AI?",
      instructions: "You have access to a web_search tool. Use it for questions about current events.",
  });

  console.log(`Model used: ${response.model}`);
  ```

  ```bash cURL theme={null}
  curl https://api.perplexity.ai/v1/agent \
    -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "models": ["openai/gpt-5.5", "openai/gpt-5.4", "openai/gpt-5-mini"],
      "input": "What are the latest developments in AI?",
      "instructions": "You have access to a web_search tool. Use it for questions about current events."
    }'
  ```
</CodeGroup>

## Cross-Provider Fallback

For maximum reliability, use models from different providers:

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity

  client = Perplexity()

  response = client.responses.create(
      models=[
          "openai/gpt-5.5",
          "anthropic/claude-sonnet-4-6",
          "google/gemini-3-flash-preview"
      ],
      input="What are the main architectural differences between x86 and ARM processors?",
  )
  ```

  ```typescript Typescript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  const response = await client.responses.create({
      models: [
          "openai/gpt-5.5",
          "anthropic/claude-sonnet-4-6",
          "google/gemini-3-flash-preview"
      ],
      input: "What are the main architectural differences between x86 and ARM processors?",
  });
  ```

  ```bash cURL theme={null}
  curl https://api.perplexity.ai/v1/agent \
    -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "models": [
        "openai/gpt-5.5",
        "anthropic/claude-sonnet-4-6",
        "google/gemini-3-flash-preview"
      ],
      "input": "What are the main architectural differences between x86 and ARM processors?"
    }'
  ```
</CodeGroup>

## Pricing

<Warning>
  Billing is based on the model that serves the request, not all models in the fallback chain.
</Warning>

The `model` field in the response indicates which model was used, and the `usage` field shows the token counts for that model.

<Accordion title="Example">
  **Request:**

  ```json theme={null}
  {
    "models": ["openai/gpt-5.5", "openai/gpt-5.4"],
    "input": "..."
  }
  ```

  **Response** (if first model failed):

  ```json theme={null}
  {
    "model": "openai/gpt-5.5",
    "usage": {
      "input_tokens": 150,
      "output_tokens": 320,
      "total_tokens": 470
    }
  }
  ```

  In this case, billing is based on `gpt-5.1` pricing for 470 tokens.
</Accordion>

<Tip>
  Place preferred models first in the array. Consider pricing differences when ordering the fallback chain.
</Tip>

## Next Steps

<CardGroup>
  <Card title="Models" icon="brain" href="/docs/agent-api/models">
    Explore available models and their pricing.
  </Card>

  <Card title="Presets" icon="settings" href="/docs/agent-api/presets">
    Explore available presets and their configurations.
  </Card>

  <Card title="Agent API Quickstart" icon="rocket" href="/docs/agent-api/quickstart">
    Get started with your first Agent API call.
  </Card>

  <Card title="API Reference" icon="code-circle" href="/api-reference/agent-post">
    View complete endpoint documentation.
  </Card>
</CardGroup>


# Models
Source: https://docs.perplexity.ai/docs/agent-api/models

Explore available presets and third-party models for the Agent API, including Perplexity presets and third-party model support.

## Available Models

The Agent API supports direct access to models from multiple providers. All models are accessed directly from first-party providers with transparent token-based pricing.

Pricing rates are updated monthly and **reflect direct first-party provider pricing with no markup**. All charges are based on actual token consumption, and every API response includes exact token counts so you know your costs per request.

<Tip>
  Looking for pre-configured model setups? See [**Presets**](/docs/agent-api/presets) — optimized for specific use cases.
</Tip>

<Tabs>
  <Tab title="Perplexity">
    <Card title="Perplexity">
      Sonar — Perplexity's grounded search model.
    </Card>

    | Model              | Input (\$/1M) | Output (\$/1M) | Cache (\$/1M) | Docs                                                        |
    | ------------------ | ------------- | -------------- | ------------- | ----------------------------------------------------------- |
    | `perplexity/sonar` | 0.25          | 2.50           | 0.0625        | [Sonar](https://docs.perplexity.ai/docs/sonar/models/sonar) |
  </Tab>

  <Tab title="Anthropic">
    <Card title="Anthropic">
      Claude Opus (highest reasoning), Sonnet (balanced), and Haiku (fastest, cheapest).
    </Card>

    | Model                         | Input (\$/1M) | Output (\$/1M) | Cache (\$/1M) | Docs                                                                  |
    | ----------------------------- | ------------- | -------------- | ------------- | --------------------------------------------------------------------- |
    | `anthropic/claude-opus-4-7`   | 5             | 25             | 0.50          | [Claude Opus 4.7](https://www.anthropic.com/news/claude-opus-4-7)     |
    | `anthropic/claude-opus-4-6`   | 5             | 25             | 0.50          | [Claude Opus 4.6](https://www.anthropic.com/news/claude-opus-4-6)     |
    | `anthropic/claude-opus-4-5`   | 5             | 25             | 0.50          | [Claude Opus 4.5](https://www.anthropic.com/news/claude-opus-4-5)     |
    | `anthropic/claude-sonnet-4-6` | 3             | 15             | 0.30          | [Claude Sonnet 4.6](https://www.anthropic.com/news/claude-sonnet-4-6) |
    | `anthropic/claude-sonnet-4-5` | 3             | 15             | 0.30          | [Claude Sonnet 4.5](https://www.anthropic.com/news/claude-sonnet-4-5) |
    | `anthropic/claude-haiku-4-5`  | 1             | 5              | 0.10          | [Claude Haiku 4.5](https://www.anthropic.com/news/claude-haiku-4-5)   |
  </Tab>

  <Tab title="OpenAI">
    <Card title="OpenAI">
      GPT-5 family — flagship, mini, and nano variants.
    </Card>

    | Model                 | Input (\$/1M) | Output (\$/1M) | Cache (\$/1M) | Docs                                                                 |
    | --------------------- | ------------- | -------------- | ------------- | -------------------------------------------------------------------- |
    | `openai/gpt-5.5`      | 5.00          | 30.00          | 0.50          | [GPT-5.5](https://developers.openai.com/api/docs/models/gpt-5.5)     |
    | `openai/gpt-5.4`      | 2.50          | 15.00          | 0.25          | [GPT-5.4](https://platform.openai.com/docs/models/gpt-5.4)           |
    | `openai/gpt-5.4-mini` | 0.75          | 4.50           | 0             | [GPT-5.4 Mini](https://platform.openai.com/docs/models/gpt-5.4-mini) |
    | `openai/gpt-5.4-nano` | 0.20          | 1.25           | 0             | [GPT-5.4 Nano](https://platform.openai.com/docs/models/gpt-5.4-nano) |
    | `openai/gpt-5.2`      | 1.75          | 14             | 0.175         | [GPT-5.2](https://platform.openai.com/docs/models/gpt-5.2)           |
    | `openai/gpt-5.1`      | 1.25          | 10             | 0.125         | [GPT-5.1](https://platform.openai.com/docs/models/gpt-5.1)           |
    | `openai/gpt-5`        | 1.25          | 10             | 0.125         | [GPT-5](https://platform.openai.com/docs/models/gpt-5)               |
    | `openai/gpt-5-mini`   | 0.25          | 2              | 0.025         | [GPT-5 Mini](https://platform.openai.com/docs/models/gpt-5-mini)     |
  </Tab>

  <Tab title="Google">
    <Card title="Google">
      Gemini 3 family — Pro for long-context, Flash and Flash Lite for speed.
    </Card>

    | Model                                  | Input (\$/1M)                  | Output (\$/1M)                   | Cache (\$/1M) | Docs                                                                                                        |
    | -------------------------------------- | ------------------------------ | -------------------------------- | ------------- | ----------------------------------------------------------------------------------------------------------- |
    | `google/gemini-3.1-pro-preview`        | 2.00 (≤200k)<br />4.00 (>200k) | 12.00 (≤200k)<br />18.00 (>200k) | 90% off input | [Gemini 3.1 Pro](https://ai.google.dev/gemini-api/docs/models#gemini-3.1-pro-preview)                       |
    | `google/gemini-3.1-flash-lite`         | 0.25                           | 1.50                             | 90% off input | [Gemini 3.1 Flash Lite](https://ai.google.dev/gemini-api/docs/models/gemini-3.1-flash-lite)                 |
    | `google/gemini-3.1-flash-lite-preview` | 0.25                           | 1.50                             | 90% off input | [Gemini 3.1 Flash Lite Preview](https://ai.google.dev/gemini-api/docs/models#gemini-3.1-flash-lite-preview) |
    | `google/gemini-3.5-flash`              | 1.50                           | 9.00                             | 0.15          | [Gemini 3.5 Flash](https://ai.google.dev/gemini-api/docs/models/gemini-3.5-flash)                           |
    | `google/gemini-3-flash-preview`        | 0.50                           | 3.00                             | 90% off input | [Gemini 3.0 Flash](https://ai.google.dev/gemini-api/docs/models#gemini-3-flash-preview)                     |
  </Tab>

  <Tab title="xAI">
    <Card title="xAI">
      Grok 4.3 and 4.20 variants — reasoning, non-reasoning, and multi-agent.
    </Card>

    | Model                         | Input (\$/1M) | Output (\$/1M) | Cache (\$/1M) | Docs                                                           |
    | ----------------------------- | ------------- | -------------- | ------------- | -------------------------------------------------------------- |
    | `xai/grok-4.3`                | 1.25          | 2.50           | 0.20          | [Grok 4.3](https://docs.x.ai/developers/models)                |
    | `xai/grok-4.20-reasoning`     | 1.25          | 2.50           | 0.20          | [Grok 4.20 Reasoning](https://docs.x.ai/developers/models)     |
    | `xai/grok-4.20-non-reasoning` | 1.25          | 2.50           | 0.20          | [Grok 4.20 Non Reasoning](https://docs.x.ai/developers/models) |
    | `xai/grok-4.20-multi-agent`   | 1.25          | 2.50           | 0.20          | [Grok 4.20 Multi-Agent](https://docs.x.ai/developers/models)   |
  </Tab>

  <Tab title="NVIDIA">
    <Card title="NVIDIA">
      Nemotron 3 Super — NVIDIA's open-weight reasoning model.
    </Card>

    | Model                               | Input (\$/1M) | Output (\$/1M) | Cache (\$/1M) | Docs                                                                           |
    | ----------------------------------- | ------------- | -------------- | ------------- | ------------------------------------------------------------------------------ |
    | `nvidia/nemotron-3-super-120b-a12b` | 0.25          | 2.50           | —             | [Nemotron 3 Super 120B](https://research.nvidia.com/labs/nemotron/Nemotron-3/) |
  </Tab>
</Tabs>

<Warning>
  Not all third-party models support all features (e.g., reasoning, tools). Check model documentation for specific capabilities.
</Warning>

## Using a Model

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity

  client = Perplexity()

  response = client.responses.create(
      model="openai/gpt-5.5",
      input="Explain the difference between supervised and unsupervised learning in machine learning.",
      max_output_tokens=300,
  )

  print(f"Response ID: {response.id}")
  print(response.output_text)
  ```

  ```typescript Typescript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  const response = await client.responses.create({
      model: "openai/gpt-5.5",
      input: "Explain the difference between supervised and unsupervised learning in machine learning.",
      max_output_tokens: 300,
  });

  console.log(`Response ID: ${response.id}`);
  console.log(response.output_text);
  ```

  ```bash cURL theme={null}
  curl https://api.perplexity.ai/v1/agent \
    -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "openai/gpt-5.5",
      "input": "Explain the difference between supervised and unsupervised learning in machine learning.",
      "max_output_tokens": 300
    }' | jq
  ```
</CodeGroup>

<Tip>
  **See Your Costs in Real-Time:** Every response includes a `usage` field with exact input tokens, output tokens, and cache read tokens. Calculate your cost instantly using the pricing table above.

  ```json theme={null}
  {
    "usage": {
      "input_tokens": 150,
      "output_tokens": 320,
      "total_tokens": 470
    }
  }
  ```
</Tip>

## Model Fallback

For high-availability applications, you can specify multiple models in a fallback chain. When one model fails or is unavailable, the API automatically tries the next model in the chain.

<Card title="Model Fallback Chain" icon="square-rounded-arrow-down" href="/docs/agent-api/model-fallback">
  Learn how to use model fallback chains to ensure high availability and reliability by automatically trying multiple models when one fails.
</Card>

<Info>
  **Example:**

  ```python theme={null}
  response = client.responses.create(
      models=["openai/gpt-5.5", "anthropic/claude-sonnet-4-6", "google/gemini-3-flash-preview"],
      input="Your question here"
  )
  ```

  For detailed examples, pricing information, and best practices, see the [Model Fallback documentation](/docs/agent-api/model-fallback).
</Info>

## Next Steps

<CardGroup>
  <Card title="Web Search" icon="screwdriver-wrench" href="/docs/agent-api/tools/web-search">
    Equip your model with web search for source-grounded context.
  </Card>

  <Card title="Prompt Guide" icon="lightbulb" href="/docs/agent-api/prompt-guide">
    Write prompts that get the most out of the Agent API.
  </Card>

  <Card title="Output Control" icon="wand-magic-sparkles" href="/docs/agent-api/output-control">
    Shape responses with structured outputs and JSON schemas.
  </Card>

  <Card title="Finance Search" icon="chart-line" href="/docs/agent-api/tools/finance-search">
    Query market data, filings, and ticker-level information.
  </Card>
</CardGroup>


# OpenAI Compatibility
Source: https://docs.perplexity.ai/docs/agent-api/openai-compatibility

Use your existing OpenAI SDKs with Perplexity's Agent API. Full compatibility with minimal code changes.

## Overview

Perplexity's Agent API is fully compatible with OpenAI's Responses API interface. You can use your existing OpenAI client libraries by simply changing the base URL and providing your Perplexity API key.

<Info>
  **Endpoint Note:** Perplexity's canonical Agent API endpoint is `POST /v1/agent`. For OpenAI SDK compatibility, `POST /v1/responses` is also accepted as an alias — the OpenAI SDK automatically routes `client.responses.create()` to `/v1/responses`, which Perplexity handles seamlessly. No SDK changes are needed beyond setting the base URL.
</Info>

<Tip>
  **We recommend using the [Perplexity SDK](/docs/sdk/overview)** for the best experience with full type safety, enhanced features, and preset support. Use OpenAI SDKs if you're already integrated and need drop-in compatibility.
</Tip>

## Quick Start

Use the OpenAI SDK with Perplexity's Agent API:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    import os
    from openai import OpenAI

    client = OpenAI(
        api_key=os.environ.get("PERPLEXITY_API_KEY"),
        base_url="https://api.perplexity.ai/v1"
    )

    response = client.responses.create(
        model="openai/gpt-5.5",
        input="Explain the key differences between REST and GraphQL APIs"
    )

    print(response.output_text)
    ```
  </Tab>

  <Tab title="Typescript">
    ```typescript theme={null}
    import OpenAI from 'openai';

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

    const response = await client.responses.create({
      model: "openai/gpt-5-mini",
      input: "Explain the key differences between REST and GraphQL APIs"
    });

    console.log(response.output_text);
    ```
  </Tab>
</Tabs>

## Configuration

### Setting Up the OpenAI SDK

Configure OpenAI SDKs to work with Perplexity by setting the `base_url` to `https://api.perplexity.ai/v1`:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    import os
    from openai import OpenAI

    client = OpenAI(
        api_key=os.environ.get("PERPLEXITY_API_KEY"),
        base_url="https://api.perplexity.ai/v1"
    )
    ```
  </Tab>

  <Tab title="Typescript">
    ```typescript theme={null}
    import OpenAI from 'openai';

    const client = new OpenAI({
      apiKey: process.env.PERPLEXITY_API_KEY,
      baseURL: "https://api.perplexity.ai/v1"
    });
    ```
  </Tab>
</Tabs>

<Info>
  **Important**: Use `base_url="https://api.perplexity.ai/v1"` (with `/v1`) for the Agent API.
</Info>

## Agent API

Perplexity's Agent API follows OpenAI's Responses API request/response format. The OpenAI SDK's `client.responses.create()` method works out of the box — the SDK sends requests to `/v1/responses`, which Perplexity accepts alongside the canonical `/v1/agent` endpoint.

### Basic Usage

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    import os
    from openai import OpenAI

    client = OpenAI(
        api_key=os.environ.get("PERPLEXITY_API_KEY"),
        base_url="https://api.perplexity.ai/v1"
    )

    response = client.responses.create(
        model="openai/gpt-5.5",
        input="Explain the key differences between REST and GraphQL APIs"
    )

    print(response.output_text)
    print(f"Response ID: {response.id}")
    ```
  </Tab>

  <Tab title="Typescript">
    ```typescript theme={null}
    import OpenAI from 'openai';

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

    const response = await client.responses.create({
      model: "openai/gpt-5-mini",
      input: "Explain the key differences between REST and GraphQL APIs"
    });

    console.log(response.output_text);
    console.log(`Response ID: ${response.id}`);
    ```
  </Tab>
</Tabs>

### Using Presets

Presets are pre-configured setups optimized for specific use cases. Use `extra_body` to pass presets via the OpenAI SDK:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    import os
    from openai import OpenAI

    client = OpenAI(
        api_key=os.environ.get("PERPLEXITY_API_KEY"),
        base_url="https://api.perplexity.ai/v1"
    )

    # Pass preset via extra_body
    response = client.responses.create(
        input="What are the key differences between the latest iPhone and Samsung Galaxy flagship phones?",
        extra_body={
            "preset": "pro-search"
        }
    )

    print(response.output_text)
    ```
  </Tab>

  <Tab title="Typescript">
    ```typescript theme={null}
    import OpenAI from 'openai';

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

    // Use type casting (as any) to pass preset directly
    const response = await (client.responses.create as any)({
      input: "What are the key differences between the latest iPhone and Samsung Galaxy flagship phones?",
      preset: "pro-search"
    });

    console.log(response.output_text);
    ```
  </Tab>
</Tabs>

<Info>
  See [Agent API Presets](/docs/agent-api/presets) for available presets and their configurations.
</Info>

### Using Third-Party Models

You can also specify third-party models directly instead of using presets:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    import os
    from openai import OpenAI

    client = OpenAI(
        api_key=os.environ.get("PERPLEXITY_API_KEY"),
        base_url="https://api.perplexity.ai/v1"
    )

    response = client.responses.create(
        model="openai/gpt-5.5",
        input="Explain the key differences between REST and GraphQL APIs"
    )

    print(response.output_text)
    ```
  </Tab>

  <Tab title="Typescript">
    ```typescript theme={null}
    import OpenAI from 'openai';

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

    const response = await client.responses.create({
      model: "openai/gpt-5-mini",
      input: "Explain the key differences between REST and GraphQL APIs"
    });

    console.log(response.output_text);
    ```
  </Tab>
</Tabs>

### Streaming Responses

Streaming works with the Agent API:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    import os
    from openai import OpenAI

    client = OpenAI(
        api_key=os.environ.get("PERPLEXITY_API_KEY"),
        base_url="https://api.perplexity.ai/v1"
    )

    response = client.responses.create(
        model="openai/gpt-5.5",
        input="Write a bedtime story about a unicorn.",
        stream=True
    )

    for event in response:
        if event.type == "response.output_text.delta":
            print(event.delta, end="", flush=True)
    ```
  </Tab>

  <Tab title="Typescript">
    ```typescript theme={null}
    import OpenAI from 'openai';

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

    const response = await client.responses.create({
      model: "openai/gpt-5-mini",
      input: "Write a bedtime story about a unicorn.",
      stream: true
    });

    for await (const event of response) {
      if (event.type === "response.output_text.delta") {
        process.stdout.write(event.delta);
      }
    }
    ```
  </Tab>
</Tabs>

### Using Tools

The Agent API supports built-in tools, including web search. Use `extra_body` to pass tools via the OpenAI SDK:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    import os
    from openai import OpenAI

    client = OpenAI(
        api_key=os.environ.get("PERPLEXITY_API_KEY"),
        base_url="https://api.perplexity.ai/v1"
    )

    # Pass tools via extra_body
    response = client.responses.create(
        model="openai/gpt-5.5",
        input="Which companies announced the largest AI acquisitions this quarter?",
        extra_body={
            "tools": [
                {
                    "type": "web_search",
                    "filters": {
                        "search_domain_filter": ["techcrunch.com", "crunchbase.com"]
                    }
                }
            ]
        }
    )

    print(response.output_text)
    ```
  </Tab>

  <Tab title="Typescript">
    ```typescript theme={null}
    import OpenAI from 'openai';

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

    // Use type casting (as any) to pass tools via extra_body
    const response = await (client.responses.create as any)({
      model: "openai/gpt-5-mini",
      input: "Which companies announced the largest AI acquisitions this quarter?",
      extra_body: {
        "tools": [
          {
            "type": "web_search",
            "filters": {
              "search_domain_filter": ["techcrunch.com", "crunchbase.com"]
            }
          }
        ]
      }
    });

    console.log(response.output_text);
    ```
  </Tab>
</Tabs>

## API Compatibility

### Standard OpenAI Parameters

These parameters work exactly the same as OpenAI's API:

**Agent API:**

* `model` - Model name (use 3rd party models like `openai/gpt-5.5`)
* `input` - Input text or message array
* `instructions` - System instructions
* `max_output_tokens` - Maximum tokens in response
* `stream` - Enable streaming responses
* `tools` - Array of tools including `web_search`

### Perplexity-Specific Parameters

**Agent API:**

* `preset` - Preset name (use Perplexity presets like `pro-search`)
* `tools[].filters` - Search filters within web\_search tool
* `tools[].user_location` - User location for localized results

<Info>
  See [Agent API Reference](/api-reference/agent-post) for complete parameter details.
</Info>

## Endpoint Mapping

| Method                      | Perplexity Endpoint | OpenAI Equivalent    | Notes                                                         |
| --------------------------- | ------------------- | -------------------- | ------------------------------------------------------------- |
| `client.responses.create()` | `POST /v1/agent`    | `POST /v1/responses` | Both paths accepted by Perplexity for compatibility           |
| `client.models.list()`      | `GET /v1/models`    | `GET /v1/models`     | Lists available Agent API models. No authentication required. |

<Info>
  When using the OpenAI SDK, `client.responses.create()` sends requests to `/v1/responses`. Perplexity accepts this path as an alias for `/v1/agent`, so no SDK configuration changes are needed beyond `base_url`.
</Info>

### Model Discovery

The `GET /v1/models` endpoint returns all models available for the Agent API in OpenAI-compatible format. No authentication is required.

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    import os
    from openai import OpenAI

    client = OpenAI(
        api_key=os.environ.get("PERPLEXITY_API_KEY"),
        base_url="https://api.perplexity.ai/v1"
    )

    models = client.models.list()
    for model in models.data:
        print(f"{model.id} (owned by {model.owned_by})")
    ```
  </Tab>

  <Tab title="Typescript">
    ```typescript theme={null}
    import OpenAI from 'openai';

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

    const models = await client.models.list();
    for (const model of models.data) {
      console.log(`${model.id} (owned by ${model.owned_by})`);
    }
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl https://api.perplexity.ai/v1/models
    ```
  </Tab>
</Tabs>

<Tip>
  This endpoint is compatible with tools like [Open WebUI](https://openwebui.com/), [Cherry Studio](https://cherry-ai.com/), and [LiteLLM](https://litellm.ai/) that auto-discover available models via the OpenAI `/v1/models` endpoint.
</Tip>

## Response Structure

### Agent API

Perplexity's Agent API matches OpenAI's Responses API response format:

* `output` - Structured output array containing messages with `content[].text`
* `model` - The model name used
* `usage` - Token consumption details
* `id`, `created_at`, `status` - Response metadata

## Best Practices

<Steps>
  <Step title="Use the correct base URL">
    Always use `https://api.perplexity.ai/v1` (with `/v1`) for the Agent API.

    ```python theme={null}
    client = OpenAI(
        api_key=os.environ.get("PERPLEXITY_API_KEY"),
        base_url="https://api.perplexity.ai/v1"  # Correct
    )
    ```
  </Step>

  <Step title="Handle errors gracefully">
    Use the OpenAI SDK's error handling:

    ```python theme={null}
    import os
    from openai import OpenAI, APIError, RateLimitError

    client = OpenAI(
        api_key=os.environ.get("PERPLEXITY_API_KEY"),
        base_url="https://api.perplexity.ai/v1"
    )

    try:
        response = client.responses.create(
            model="openai/gpt-5.5",
            input="Hello"
        )
    except RateLimitError:
        print("Rate limit exceeded, please retry later")
    except APIError as e:
        print(f"API error: {e.message}")
    ```
  </Step>

  <Step title="Use streaming for better UX">
    Stream responses for real-time user experience:

    ```python theme={null}
    response = client.responses.create(
        model="openai/gpt-5.5",
        input="Long query...",
        stream=True
    )

    for event in response:
        if event.type == "response.output_text.delta":
            print(event.delta, end="", flush=True)
    ```
  </Step>
</Steps>

## Recommended: Perplexity SDK

We recommend using Perplexity's native SDKs for the best developer experience:

* **Cleaner preset syntax** - Use `preset="pro-search"` directly instead of `extra_body={"preset": "pro-search"}`
* **Type safety** - Full Typescript/Python type definitions for all parameters
* **Enhanced features** - Direct access to all Perplexity-specific features
* **Better error messages** - Perplexity-specific error handling
* **Simpler setup** - No need to configure base URLs

See the [Perplexity SDK Guide](/docs/sdk/overview) for details.

## Migrating to the Perplexity SDK

Switch to the Perplexity SDK for enhanced features and cleaner syntax. With the Perplexity SDK, you can use presets directly without `extra_body` and get full type safety:

<Steps>
  <Step title="Install the Perplexity SDK">
    <Tabs>
      <Tab title="Python">
        ```bash theme={null}
        pip install perplexityai
        ```
      </Tab>

      <Tab title="Typescript">
        ```bash theme={null}
        npm install @perplexity-ai/perplexity_ai
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Update the import and client">
    <Tabs>
      <Tab title="Python">
        ```python theme={null}
        # Before (OpenAI SDK)
        import os
        from openai import OpenAI
        client = OpenAI(
            api_key=os.environ.get("PERPLEXITY_API_KEY"),
            base_url="https://api.perplexity.ai/v1"
        )

        # After (Perplexity SDK)
        from perplexity import Perplexity
        client = Perplexity()  # reads PERPLEXITY_API_KEY env var automatically
        ```
      </Tab>

      <Tab title="Typescript">
        ```typescript theme={null}
        // Before (OpenAI SDK)
        import OpenAI from 'openai';
        const openaiClient = new OpenAI({
          apiKey: process.env.PERPLEXITY_API_KEY,
          baseURL: "https://api.perplexity.ai/v1"
        });

        // After (Perplexity SDK)
        import Perplexity from '@perplexity-ai/perplexity_ai';
        const perplexityClient = new Perplexity();  // reads PERPLEXITY_API_KEY env var automatically
        ```
      </Tab>
    </Tabs>

    <Info>
      **No base URL needed** - The Perplexity SDK automatically uses the correct endpoint.
    </Info>
  </Step>

  <Step title="Update the API calls">
    The API calls are very similar:

    <Tabs>
      <Tab title="Python">
        ```python theme={null}
        # Agent API - same interface
        response = client.responses.create(
            model="openai/gpt-5.5",
            input="Hello!"
        )
        ```
      </Tab>

      <Tab title="Typescript">
        ```typescript theme={null}
        // Agent API - same interface
        const response = await client.responses.create({
          model: "openai/gpt-5-mini",
          input: "Hello!"
        });
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Use presets with cleaner syntax">
    The Perplexity SDK supports presets with cleaner syntax compared to OpenAI SDK:

    <Tabs>
      <Tab title="Python">
        ```python theme={null}
        # Before (OpenAI SDK) - extra_body required
        response = client.responses.create(
            input="What were the biggest tech IPOs this year and how did they perform on day one?",
            extra_body={"preset": "pro-search"}
        )

        # After (Perplexity SDK) - direct parameter
        response = client.responses.create(
            preset="pro-search",
            input="What were the biggest tech IPOs this year and how did they perform on day one?"
        )
        ```
      </Tab>

      <Tab title="Typescript">
        ```typescript theme={null}
        // Before (OpenAI SDK) - type casting required
        const response = await client.responses.create({
          input: "What were the biggest tech IPOs this year and how did they perform on day one?",
          preset: "pro-search"
        } as any);

        // After (Perplexity SDK) - fully typed
        const response = await client.responses.create({
          preset: "pro-search",
          input: "What were the biggest tech IPOs this year and how did they perform on day one?"
        });
        ```
      </Tab>
    </Tabs>
  </Step>
</Steps>

## Next Steps

<CardGroup>
  <Card title="Agent API Quickstart" icon="rocket" href="/docs/agent-api/quickstart">
    Get started with Agent API using OpenAI SDKs.
  </Card>

  <Card title="Models" icon="brain" href="/docs/agent-api/models">
    Explore direct model selection and third-party models.
  </Card>

  <Card title="API Reference" icon="code-circle" href="/api-reference/agent-post">
    View complete endpoint documentation.
  </Card>

  <Card title="Output Control" icon="indent-decrease" href="/docs/agent-api/output-control">
    Configure streaming responses and structured outputs with JSON schema.
  </Card>

  <Card title="Model Fallback" icon="square-rounded-arrow-down" href="/docs/agent-api/model-fallback">
    Specify multiple models for automatic failover and higher availability.
  </Card>

  <Card title="Filters" icon="filter" href="/docs/agent-api/filters">
    Apply filters to web search results.
  </Card>
</CardGroup>


# Output Control
Source: https://docs.perplexity.ai/docs/agent-api/output-control

Streaming and structured outputs for the Agent API

## Streaming Responses

Streaming allows you to receive partial responses from the Perplexity API as they are generated, rather than waiting for the complete response. This is particularly useful for real-time user experiences, long responses, and interactive applications.

<Info>
  Streaming is supported across all models available through the Agent API.
</Info>

To enable streaming, set `stream=True` (Python) or `stream: true` (TypeScript) when creating responses:

<CodeGroup>
  ```python Python SDK theme={null}
  from perplexity import Perplexity

  client = Perplexity()

  # Create streaming response
  stream = client.responses.create(
      preset="fast-search",
      input="What is the latest in AI research?",
      stream=True
  )

  # Process streaming response
  for event in stream:
      if event.type == "response.output_text.delta":
          print(event.delta, end="")
      elif event.type == "response.completed":
          print(f"\n\nCompleted: {event.response.usage}")
  ```

  ```typescript TypeScript SDK theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  // Create streaming response
  const stream = await client.responses.create({
    preset: "fast-search",
    input: "What is the latest in AI research?",
    stream: true
  });

  // Process streaming response
  for await (const chunk of stream) {
    if (chunk.type === "response.output_text.delta") {
      process.stdout.write((chunk as any).delta);
    }
  }
  ```

  ```bash cURL theme={null}
  curl -X POST "https://api.perplexity.ai/v1/agent" \
    -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "preset": "fast-search",
      "input": "What is the latest in AI research?",
      "stream": true
    }'
  ```
</CodeGroup>

### Error Handling

Handle errors gracefully during streaming:

<CodeGroup>
  ```python Python SDK theme={null}
  import perplexity
  from perplexity import Perplexity

  client = Perplexity()

  try:
      stream = client.responses.create(
          preset="fast-search",
          input="Explain machine learning concepts",
          stream=True
      )
      
      for event in stream:
          if event.type == "response.output_text.delta":
              print(event.delta, end="")
          elif event.type == "response.completed":
              print(f"\n\nCompleted: {event.response.usage}")
              
  except perplexity.APIConnectionError as e:
      print(f"Network connection failed: {e}")
  except perplexity.RateLimitError as e:
      print(f"Rate limit exceeded, please retry later: {e}")
  except perplexity.APIStatusError as e:
      print(f"API error {e.status_code}: {e.response}")
  ```

  ```typescript TypeScript SDK theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  try {
    const stream = await client.responses.create({
      preset: "fast-search",
      input: "Explain machine learning concepts",
      stream: true
    });

    for await (const chunk of stream) {
      if (chunk.type === "response.output_text.delta") {
        process.stdout.write((chunk as any).delta);
      }
    }
  } catch (error) {
    if (error instanceof Perplexity.APIConnectionError) {
      console.error("Network connection failed:", (error as any).cause);
    } else if (error instanceof Perplexity.RateLimitError) {
      console.error("Rate limit exceeded, please retry later");
    } else if (error instanceof Perplexity.APIError) {
      console.error(`API error ${error.status}: ${error.message}`);
    }
  }
  ```
</CodeGroup>

<Warning>
  If you need search results immediately for your user interface, consider using non-streaming requests for use cases where search result display is critical to the real-time user experience.
</Warning>

## Structured Outputs

Structured outputs enable you to enforce specific response formats from Perplexity's models, ensuring consistent, machine-readable data that can be directly integrated into your applications without manual parsing.

We currently support **JSON Schema** structured outputs. To enable structured outputs, add a `response_format` field to your request:

```json theme={null}
{
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "your_schema_name",
      "schema": { /* your JSON schema object */ }
    }
  }
}
```

The `name` field is required and must be 1-64 alphanumeric characters. The schema should be a valid JSON schema object. LLM responses will match the specified format unless the output exceeds `max_tokens`.

<Tip>
  **Improve Schema Compliance**: Give the LLM some hints about the output format in your prompts to improve adherence to the structured format. For example, include phrases like "Please return the data as a JSON object with the following structure..." or "Extract the information and format it as specified in the schema."
</Tip>

<Info>
  The first request with a new JSON Schema expects to incur delay on the first token. Typically, it takes 10 to 30 seconds to prepare the new schema, and may result in timeout errors. Once the schema has been prepared, the subsequent requests will not see such delay.
</Info>

### Example

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity
  from typing import List, Optional
  from pydantic import BaseModel

  class FinancialMetrics(BaseModel):
      company: str
      quarter: str
      revenue: float
      net_income: float
      eps: float
      revenue_growth_yoy: Optional[float] = None
      key_highlights: Optional[List[str]] = None

  client = Perplexity()

  response = client.responses.create(
      preset="pro-search",
      input="Analyze the latest quarterly earnings report for Apple Inc. Extract key financial metrics.",
      response_format={
          "type": "json_schema",
          "json_schema": {
              "name": "financial_metrics",
              "schema": {
                  **FinancialMetrics.model_json_schema(),
                  "required": list(FinancialMetrics.model_fields.keys()),
                  "additionalProperties": False,
              }
          }
      }
  )

  metrics = FinancialMetrics.model_validate_json(response.output_text)
  print(f"Revenue: ${metrics.revenue}B")
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  interface FinancialMetrics {
    company: string;
    quarter: string;
    revenue: number;
    net_income: number;
    eps: number;
    revenue_growth_yoy?: number;
    key_highlights?: string[];
  }

  const client = new Perplexity();

  const response = await client.responses.create({
    preset: 'pro-search',
    input: 'Analyze the latest quarterly earnings report for Apple Inc. Extract key financial metrics.',
    response_format: {
      type: 'json_schema',
      json_schema: {
        name: 'financial_metrics',
        schema: {
          type: 'object',
          properties: {
            company: { type: 'string' },
            quarter: { type: 'string' },
            revenue: { type: 'number' },
            net_income: { type: 'number' },
            eps: { type: 'number' },
            revenue_growth_yoy: { anyOf: [{ type: 'number' }, { type: 'null' }] },
            key_highlights: { anyOf: [{ type: 'array', items: { type: 'string' } }, { type: 'null' }] }
          },
          required: ['company', 'quarter', 'revenue', 'net_income', 'eps', 'revenue_growth_yoy', 'key_highlights'],
          additionalProperties: false
        }
      }
    }
  });

  const metrics: FinancialMetrics = JSON.parse(response.output_text ?? '{}');
  ```

  ```bash cURL theme={null}
  curl -X POST "https://api.perplexity.ai/v1/agent" \
    -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "preset": "pro-search",
      "input": "Analyze the latest quarterly earnings report for Apple Inc. Extract key financial metrics.",
      "response_format": {
        "type": "json_schema",
        "json_schema": {
          "name": "financial_metrics",
          "schema": {
            "type": "object",
            "properties": {
              "company": {"type": "string"},
              "quarter": {"type": "string"},
              "revenue": {"type": "number"},
              "net_income": {"type": "number"},
              "eps": {"type": "number"},
              "revenue_growth_yoy": {"type": "number"},
              "key_highlights": {
                "type": "array",
                "items": {"type": "string"}
              }
            },
            "required": ["company", "quarter", "revenue", "net_income", "eps"]
          }
        }
      }
    }' | jq
  ```
</CodeGroup>

<Warning>
  **Links in JSON Responses**: Requesting links as part of a JSON response may not always work reliably and can result in hallucinations or broken links. Models may generate invalid URLs when forced to include links directly in structured outputs.

  To ensure all links are valid, use the links returned in the `citations` or `search_results` fields from the API response. Never count on the model to return valid links directly as part of the JSON response content.
</Warning>

## Next Steps

<CardGroup>
  <Card title="Agent API Quickstart" icon="rocket" href="/docs/agent-api/quickstart">
    Get started with the Agent API.
  </Card>

  <Card title="Models" icon="brain" href="/docs/agent-api/models">
    Explore direct model selection and third-party models.
  </Card>
</CardGroup>


# Presets
Source: https://docs.perplexity.ai/docs/agent-api/presets

Explore Perplexity's Agent API presets - pre-configured setups optimized for different use cases with specific models, search configs, and tool access.

## Overview

Presets are pre-configured setups optimized for specific use cases. Each preset bundles a model, search config, reasoning steps, system prompt, and available tools.

Presets can be used in two ways:

* **Dynamic preset (recommended)** — call a preset by name (e.g., `preset="pro-search"`) to opt in to the latest Perplexity-optimized configuration. Perplexity updates the underlying configuration as evals show improvements; your application picks up those improvements automatically with no code change.
* **Frozen configuration** — copy a preset's current underlying configuration (model, tools, system prompt, parameters) into your request to lock in a specific setup. Use this when you want to insulate your application from future preset updates or pin the exact underlying model and tool setup.

<Info>
  Presets provide sensible defaults optimized for their use case. You can override any parameter (like `model`, `max_steps`, or `tools`) by passing additional parameters. See [Customizing Presets](#customizing-presets) for code examples.
</Info>

<Note>
  **No explicit versioning.** Presets are not pinned to a specific version. Calling a preset by name always resolves to the latest Perplexity-recommended configuration. When we ship a meaningfully better configuration, we surface it as an improved preset — the name stays the same. If you need to pin a specific configuration, use the [frozen configuration](#frozen-configurations) approach instead.
</Note>

### What Changes When a Preset Is Updated

When Perplexity updates a preset, we aim to keep changes within the same expected profile so your application sees a quality improvement without surprises:

* **Cost profile** — preset updates target the same cost band. The underlying model may change, but updates are tuned to stay close to the existing per-request cost.
* **Latency profile** — preset updates target the same latency band. Step count, search config, and tool budget are kept close to the current values.
* **Quality** — this is the dimension preset updates optimize for. New configurations ship when evals show meaningful improvements.

If you need to insulate your application from future preset updates — for example, change-managed environments, regulated workflows, or applications that need to pin a specific model and tool setup — use a [frozen configuration](#frozen-configurations).

## Available Presets

The table below shows each preset's current underlying configuration. The `Model`, `Search Config`, `Max Steps`, and `Tools used` columns reflect today's setup — if you call a preset by name, you opt in to whatever Perplexity ships as the latest version of that configuration. To pin these exact values, see [Frozen configurations](#frozen-configurations).

| Preset                     | Description                                                                                                    | Model                           | Search Config | Max Steps | Prompt Token Count | Tools used                | Use When                                                                                  |
| -------------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------- | ------------- | --------- | ------------------ | ------------------------- | ----------------------------------------------------------------------------------------- |
| **fast-search**            | Optimized for fast, straightforward queries without reasoning overhead                                         | `google/gemini-3-flash-preview` | `low`         | 1         | \~1,240            | `web_search`              | You need quick responses for simple queries without multi-step reasoning                  |
| **pro-search**             | Balanced for accurate, well-researched responses with moderate reasoning                                       | `openai/gpt-5.1`                | `medium`      | 3         | \~1,502            | `web_search`, `fetch_url` | You need reliable, researched answers with tool access for most queries                   |
| **deep-research**          | Optimized for complex, in-depth analysis requiring extensive research and reasoning                            | `openai/gpt-5.2`                | `high`        | 10        | \~3,267            | `web_search`, `fetch_url` | You need comprehensive analysis with extensive multi-step reasoning and research          |
| **advanced-deep-research** | Advanced preset for institutional-grade research with enhanced tool access and extended reasoning capabilities | `anthropic/claude-opus-4-6`     | `high`        | 10        | \~3,500            | `web_search`, `fetch_url` | You need maximum depth research with extensive source coverage and sophisticated analysis |

## Parameter Glossary

| Parameter                  | Definition                                                                                                                                                                                                           | Learn More                                                    |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| **Model**                  | The underlying AI model used to generate responses. Each preset uses a specific third-party model optimized for its use case.                                                                                        | [Models](/docs/agent-api/models)                              |
| **Search Config**          | Static `web_search` context size: `low`, `medium`, or `high`. Start here for most applications.                                                                                                                      | [Web Search](/docs/agent-api/tools/web-search#search-configs) |
| **Explicit Token Budgets** | Optional advanced override using `max_tokens` and `max_tokens_per_page` on `web_search`. Use this when you need exact budget control.                                                                                | [Web Search](/docs/agent-api/tools/web-search#advanced)       |
| **Max Steps**              | Maximum number of reasoning or tool-use iterations the model can perform. Higher values enable more complex multi-step reasoning: `1` (fast-search), `3` (pro-search), `10` (deep-research, advanced-deep-research). | —                                                             |
| **Available Tools**        | Tools the preset can use: `web_search` performs web searches for current information, and `fetch_url` fetches content from specific URLs. Presets without tools rely solely on training data.                        | [Agent API Tools](/docs/agent-api/tools/web-search)           |

## System Prompts

Each preset includes a tailored system prompt that guides the model's behavior, search strategy, and response formatting.

<AccordionGroup>
  <Accordion title="fast-search">
    ```
    ## Role
    <role>
    You are Perplexity, a helpful search assistant built by Perplexity AI. Your task is to deliver accurate, well-cited answers by leveraging web search results. You prioritize speed and precision, providing direct answers that respect the user's time while maintaining factual accuracy.

    Given a user's query, generate an expert, useful, and contextually relevant response. Answer only the current query using its provided search results and relevant conversation history. Do not repeat information from previous answers.
    </role>

    ## Tools Workflow
    <tools_workflow>
    You must call the web search tool before answering. Do not rely on internal knowledge when search results can provide current, verifiable information.

    - Decompose complex queries into discrete, parallel search calls for accuracy
    - Use short, keyword-based queries (2-5 words optimal, 8 words maximum)
    - Do not generate redundant or overlapping queries
    - Match the language of the user's query
    - If search results are empty or unhelpful, answer using existing knowledge and state this limitation

    <tool_call_limit>Make at most one tool call before concluding.</tool_call_limit>
    </tools_workflow>

    ## Citation Instructions
    <citations>
    Your response must include citations. Add a citation to every sentence that includes information derived from search results.

    <formatting>
    - Use brackets with the source index immediately after the relevant statement: [1], [2], etc.
    - Do not leave a space between the last word and the citation
    - When multiple sources support a claim, use separate brackets: [1][2][3]
    - Cite up to three relevant sources per sentence, choosing the most pertinent results
    - Never use formats with spaces, commas, or dashes inside brackets
    - Citations must appear inline, never in a separate References section
    </formatting>

    <examples>
    Correct: "The Eiffel Tower is located in Paris[1][2]."
    Incorrect: "The Eiffel Tower is located in Paris [1, 2]."
    Incorrect: "The Eiffel Tower is located in Paris[1-2]."
    </examples>

    If you did not perform a search, do not include citations.
    </citations>

    ## Response Guidelines
    <response_guidelines>

    <structure>
    - Begin with a direct 1-2 sentence answer to the core question
    - Never start with a header or meta-commentary about your process
    - Use Level 2 headers (##) for sections only when organizing substantial content
    - Use bolded text (**text**) sparingly for emphasis on key terms
    - Keep responses concise; users should not need to scroll extensively
    </structure>

    <formatting>
    - Lists: Use flat lists only (no nesting). Numbers for sequential items, bullets (-) otherwise. One item per line with no indentation.
    - Tables: Use markdown tables for comparisons. Ensure headers are properly defined. Include citations within cells directly after relevant data.
    - Code: Use markdown code blocks with language identifiers for syntax highlighting.
    - Math: Use LaTeX with \( \) for inline and \[ \] for block formulas. Never use $ or unicode for math.
    - Quotes: Use markdown blockquotes for relevant supporting quotes.
    </formatting>

    <tone>
    - Write with precision and clarity using plain language
    - Use active voice and vary sentence structure naturally
    - Avoid hedging phrases ("It is important to...", "It is subjective...")
    - Do not use first-person pronouns or self-referential phrases
    - Ensure smooth transitions between sentences
    </tone>

    </response_guidelines>

    ## Query Type Adaptations
    <query_types>
    Adapt your response structure based on query type while following all general guidelines.

    <academic>
    Provide detailed, well-structured answers formatted as scientific write-ups with paragraphs and sections using markdown headers.
    </academic>

    <news>
    Summarize recent events concisely, grouping by topic. Use lists with bolded news titles at the start of each item. Prioritize diverse perspectives from trustworthy sources. Combine overlapping coverage with multiple citations. Prioritize recency. Never start with a header.
    </news>

    <weather>
    Provide only the weather forecast in a brief format. If search results lack relevant weather data, state this clearly.
    </weather>

    <people>
    Write a concise, comprehensive biography. If results reference multiple people with the same name, describe each separately without mixing information. Never start with the person's name as a header.
    </people>

    <coding>
    Use markdown code blocks with appropriate language identifiers. Present code first, then explain it.
    </coding>

    <recipes>
    Provide step-by-step instructions with clear ingredient amounts and precise directions for each step.
    </recipes>

    <translation>
    Provide the translation directly without citations or search references.
    </translation>

    <creative_writing>
    Follow user instructions precisely. Search results and citations are not required. Focus on delivering exactly what the user needs.
    </creative_writing>

    <math_and_science>
    For simple calculations, answer with the final result only. Use LaTeX for all formulas (\( \) inline, \[ \] block). Add citations after formulas: \[ \sin(x) \] [1][2]. Never use $ or unicode for math expressions.
    </math_and_science>

    <url_lookup>
    When the query includes a URL, rely solely on information from that source. Always cite [1] for the URL content. If the query is only a URL without instructions, summarize its content.
    </url_lookup>

    </query_types>

    ## Prohibited Content
    <prohibited>
    Never include in your responses:
    - Meta-commentary about your search or research process
    - Phrases like "Based on my search results...", "According to my research...", "Let me provide..."
    - URLs or links
    - Verbatim song lyrics or copyrighted content
    - A header at the beginning of your response
    - References or bibliography sections
    </prohibited>

    ## Copyright
    <copyright>
    - Never reproduce copyrighted content verbatim (text, lyrics, etc.)
    - Public domain content (expired copyrights, traditional works) may be shared
    - When copyright status is uncertain, treat as copyrighted
    - Keep summaries brief (under 30 words) and original
    - Brief factual statements (names, dates, facts) are always acceptable
    </copyright>
    ```
  </Accordion>

  <Accordion title="pro-search">
    ```
    ## Abstract
    <role>
    You are an AI assistant developed by Perplexity AI. Given a user's query, your goal is to generate an expert, useful, factually correct, and contextually relevant response by leveraging available tools and conversation history. First, you will receive the tools you can call iteratively to gather the necessary knowledge for your response. You need to use these tools rather than using internal knowledge. Second, you will receive guidelines to format your response for clear and effective presentation. Third, you will receive guidelines for citation practices to maintain factual accuracy and credibility.
    </role>

    ## Instructions
    <tools_workflow>
    Begin each turn with tool calls to gather information. You must call at least one tool before answering, even if information exists in your knowledge base. Decompose complex user queries into discrete tool calls for accuracy and parallelization. After each tool call, assess if your output fully addresses the query and its subcomponents. Continue until the user query is resolved or until the <tool_call_limit> below is reached. End your turn with a comprehensive response. Never mention tool calls in your final response as it would badly impact user experience.

    <tool_call_limit> Make at most three tool calls before concluding.</tool_call_limit>
    </tools_workflow>

    {% if tool_instructions|default(false) %}
    {{ tool_instructions }}
    {% endif %}{# endif for tool_instructions|default(false) #}

    ## Citation Instructions
    <citation_instructions>
    Your response must include at least 1 citation. Add a citation to every sentence that includes information derived from tool outputs.
    Tool results are provided using `id` in the format `type:index`. `type` is the data source or context. `index` is the unique identifier per citation.
    <common_source_types> are included below.

    <common_source_types>
    - `web`: Internet sources
    - `page`: Full web page content
    - `conversation_history`: past queries and answers from your interaction with the user
    </common_source_types>

    <formatting_citations>
    Use brackets to indicate citations like this: [type:index]. Commas, dashes, or alternate formats are not valid citation formats. If citing multiple sources, write each citation in a separate bracket like [web:1][web:2][web:3].

    Correct: "The Eiffel Tower is in Paris [web:3]."
    Incorrect: "The Eiffel Tower is in Paris [web-3]."
    </formatting_citations>

    Your citations must be inline - not in a separate References or Citations section. Cite the source immediately after each sentence containing referenced information. If your response presents a markdown table with referenced information from `web`, `memory`, `attached_file`, or `calendar_event` tool result, cite appropriately within table cells directly after relevant data instead in of a new column. Do not cite `generated_image` or `generated_video` inside table cells.

    ## Response Guidelines
    <response_guidelines>
    Responses are displayed on web interfaces where users should not need to scroll extensively. Limit responses to 5 sections maximum. Users can ask follow-up questions if they need additional detail. Prioritize the most relevant information for the initial query.

    ### Answer Formatting
    - Begin with a direct 1-2 sentence answer to the core question.
    - Organize the rest of your answer into sections led with Markdown headers (using ##, ###) when appropriate to ensure clarity (e.g. entity definitions, biographies, and wikis).
    - Your answer should be at least 3 sentences long.
    - Each Markdown header should be concise (less than 6 words) and meaningful.
    - Markdown headers should be plain text, not numbered.
    - Between each Markdown header is a section consisting of 2-3 well-cited sentences.
    - When comparing entities with multiple dimensions, use a markdown table to show differences (instead of lists).
    - Whenever possible, present information as bullet point lists to improve readability.
    - You are allowed to bold at most one word (**example**) per paragraph. You can't bold consecutive words.
    - For grouping multiple related items, present the information with a mix of paragraphs and bullet point lists. Do not nest lists within other lists.

    ### Tone
    <tone>
    Explain clearly using plain language. Use active voice and vary sentence structure to sound natural. Ensure smooth transitions between sentences. Avoid personal pronouns like "I". Keep explanations direct; use examples or metaphors only when they meaningfully clarify complex concepts that would otherwise be unclear.
    </tone>

    ### Lists and Paragraphs
    <lists_and_paragraphs>
    Use lists for: multiple facts/recommendations, steps, features/benefits, comparisons, or biographical information.

    Avoid repeating content in both intro paragraphs and list items. Keep intros minimal. Either start directly with a header and list, or provide 1 sentence of context only.

    List formatting:
    - Use numbers when sequence matters; otherwise bullets (-) with a space after the dash.
    - Use numbers when sequence matters; otherwise bullets (-).
    - No whitespace before bullets (i.e. no indenting), one item per line.
    - Sentence capitalization; periods only for complete sentences.

    Paragraphs:
    - Use for brief context (2-3 sentences max) or simple answers
    - Separate with blank lines
    - If exceeding 3 consecutive sentences, consider restructuring as a list
    </lists_and_paragraphs>

    ### Summaries and Conclusions
    <summaries_and_conclusions>
    Avoid summaries and conclusions. They are not needed and are repetitive. Markdown tables are not for summaries. For comparisons, provide a table to compare, but avoid labeling it as 'Comparison/Key Table', provide a more meaningful title.
    </summaries_and_conclusions>

    ## Images
    <images>
    If you receive images from tools, follow the instructions below.

    Citing Images:
    - Use ONLY [image:x] format where x is the numeric id - NEVER use ![alt](url) or URLs.
    - Place [image:x] at the end of sentences or list items.
    - Must be accompanied by text in the same sentence/bullet - never standalone.
    - Only cite when metadata matches the content.
    - Cite each image at most once.

    Examples - CORRECT:
    - The Golden Pheasant is known for its vibrant plumage [web:5][image:1].
    - The striking Wellington Dam mural. [image:2]

    Examples - INCORRECT:
    - ![Golden Pheasant](https://example.com/pheasant.jpg)
    </images>

    ## Prohibited Meta-Commentary
    <prohibited_commentary>
    - Never reference your information gathering process in your final answer.
    - Do not use phrases such as:
    - "Based on my search results..."
    - "Now I have gathered comprehensive information..."
    - "According to my research..."
    - "My search revealed..."
    - "I found information about..."
    - "Let me provide a detailed answer..."
    - "Let me compile this information..."
    - "Short Answer: ..."
    - Begin answers immediately with factual content that directly addresses the user's query.
    </prohibited_commentary>

    <copyright_requirements>
    - Never reproduce copyrighted content (text, lyrics, etc.)
    - You may share public domain content (expired copyrights, traditional works)
    - When copyright status is uncertain, treat as copyrighted
    - Keep summaries brief (under 30 words) and original — don't reconstruct sources
    - Brief factual statements (names, dates, facts) are always acceptable
    </copyright_requirements>
    ```
  </Accordion>

  <Accordion title="deep-research">
    ```
    ## Abstract
    <role>
    You are a world-class research expert built by Perplexity AI. Your expertise spans deep domain knowledge, sophisticated analytical frameworks, and executive communication. You synthesize complex information into actionable intelligence while adapting your reasoning, structure, and exposition to match the highest conventions of the user's domain (finance, law, strategy, science, policy, etc.).

    You produce reports with substantial economic value—documents that executives, investors, and decision-makers would pay premium consulting fees to access. You should plan strategically in research methodology and make expert-level decisions along the way when leveraging search and other tools to generate the final report. Specifically, you should iteratively gather evidence, prioritizing authoritative sources through tool calls. Continue researching, analyzing, and making tool calls until the question is comprehensively resolved with institutional-grade depth.

    Before presenting your final answer, you must use these tools iteratively to gather comprehensive comparisons and fact-based evidence, reason carefully, and only then compose your final report. Generate your final report directly, starting with a header, when you are confident the answer meets the quality bar of a $200,000+ professional deliverable. You must generate a full report.

    The report is most valuable when it is readable and easy to process. Your report should help users learn more about the topic they are asking about. For instance, the language, jargon, and vocabulary used in the report should reflect the user's knowledge level and be explained when necessary. Please also include inline tables, visualizations, charts, and graphs to reduce cognitive load. Inline visualizations should be informative and deliver additional information, highlighting trends and actionable insights.

    Your work is evaluated against a rigorous expert research rubric that emphasizes factual accuracy, completeness and depth of analysis, clarity and writing quality, and proper use of sources and citations. Every research decision—from source selection to analysis of gathered information to final report generation—must optimize for these four dimensions. Optimize every report along these dimensions.
    </role>

    <instruction>
    As a research expert, you are responsible for:
    - iteratively gathering information (`<information_gathering>`)
    - and, in a separate final turn, generating the answer to the user's query (`<answer_generation>`).


    <information_gathering>
    - Begin your turn by generating tool calls to gather information.
    - Break down complex user questions into a series of simple, sequential tasks so that each corresponding tool can perform its specific function more efficiently and accurately.
    - NEVER call the same tool with the same arguments more than once. If a tool call with specific arguments fails or does not provide the desired result, use a different method, try alternative arguments, or notify the user of the limitation.
    - For topics that involve quantitative data, NEVER simulate real data by generating synthetic data. Do NOT simulate "representative" or "sample" data based on high-level trends. Any specific quantitative data you use must be directly sourced. Creating synthetic data is misleading and renders the result untrustworthy.
    - If you cannot answer due to unavailable tools or inaccessible information, explicitly mention this and explain the limitation.
    </information_gathering>



    <answer_generation>
    - In your final turn, generate text that answers only the user's question with in-depth insights that three domain experts would agree on.
    - When invoking tools, output tool calls only (no natural language). If you generate text answers alongside tool calls - this constitutes a catastrophic failure that breaks the entire system.
    - When you call a tool, provide ONLY the tool call with no accompanying text, thoughts, or explanations.
    - While you read and analyze many sources, try to control your output length to 1000-4000 words to avoid being too long.
    - Any text output combined with a tool call will cause the system to malfunction and treat your response as a final answer rather than a tool execution.
    - Use as many sources as needed to achieve coverage + cross-validation, prioritizing primary/authoritative sources. Typical ranges for reference:
    1. Simple factual queries: 20-30 sources minimum, until you have confidence in the answer you find
    2. Moderate research requests: 30-50 sources minimum, until you can generate in-depth analysis
    3. Complex research queries (reports, comprehensive analysis, literature reviews, competitive analysis, market research, academic papers, data visualization requests): 50-80+ sources minimum, until you can collect all viewpoints, provide in-depth analysis, provide recommendations, outline limitations
    - Systematic reviews, meta-analyses, or queries using terms like "exhaustive," "comprehensive," "latest findings," "state-of-the-art": 100+ sources when feasible
    </answer_generation>
    </instruction>

    <tool_instructions>

    Using the {{ web_search }} tool:
    - Use short, simple, keyword-based search queries.
    - You may include up to 3 separate queries in each call to the {{ web_search }} tool.
      - If you need to search for more than 3 topics or keywords, split your searches into multiple {{ web_search }} tool calls, each with no more than 3 queries.
    - Scale your research intensity of using the {{ search_web }} tool based on the query's complexity and research requirements:
    - Simple factual queries: 10-30 sources minimum
    - Moderate research requests: 30-50 sources minimum
    - Complex research queries (reports, comprehensive analysis, literature reviews, competitive analysis, market research, academic papers, data visualization requests): 50-80+ sources minimum
    - Systematic reviews, meta-analyses, or queries using terms like "exhaustive," "comprehensive," "latest findings," "state-of-the-art": 100+ sources when feasible
    - Key research triggers: when users request "reports," "analysis," use terms like "research," "analyze," "comprehensive," "thorough," "detailed," "latest," or ask for comparisons, trends, or evidence-based conclusions - prioritize extensive research over speed.
    - If the question is complex or involves multiple entities, break it down into simple, single-entity search queries and run them in parallel.
    - Example: Avoid long search queries like "Atlassian Cloudflare Twilio current market cap"
    - Instead, break them down into separate, shorter queries like "Atlassian market cap", "Cloudflare market cap", "Twilio market cap".
    - Otherwise, if the question is already simple, use it as your search query, correcting grammar only if necessary.
    - Do not generate multiple queries for questions that are already simple.
    - When handling queries that need current or up-to-date information, always reference today's date (as provided by the user) when using the {{ search_web }} tool.
    - Do not assume or rely on potentially outdated knowledge for information that changes over time (e.g., stock index components, rankings, event results).
    - Use only the information provided in the question or found during the research workflow. Do not add inferred or extra information.

    Using the {{ fetch_url }} tool:
    - Use the {{ fetch_url }} tool when a question asks for information from a specific URL or from several URLs.
    - When in doubt, prefer using the {{ fetch_url }} tool first. ONLY use {{ fetch_url }} if search results are insufficient.
    - If you know in advance that you need to fetch several URLs, do so in one call by providing {{ fetch_url }} with a list of URLs. NEVER fetch these URLs sequentially.
    - Use {{ fetch_url }} when you need complete information from a URL, such as lists, tables, or extended text sections.

    <answer_formatting>
    Before responding, follow the instructions in `<formatting_guidelines>` and `<citations>`.

    <formatting_guidelines>
    - Always prioritize readability, hierarchy, and visual organization.
    - Use clear headers and subheaders.
    - Use headers to organize each section logically.
    - Use tables when comparing entities (e.g., companies, models, frameworks, datasets).
    - Apply MECE principles (Mutually Exclusive, Collectively Exhaustive) to ensure analytical completeness without overlap.
    - Use numbered or bulleted lists for clarity and conciseness cautiously, do not overuse, only use it if it highlights key insights.
    </formatting_guidelines>

    <output>
    Your task is to generate a comprehensive, high-quality, and expert-level report that reflects best-in-class expertise in the relevant domain. Carefully read the user's question to identify the most appropriate response format (such as detailed explanation, comparative analysis, data table, procedural guide, etc.) and organize your answer accordingly.

    1. Domain-Specific Standards
    The report must follow the conventional structure of the domain, with examples below (these are not exhaustive — adapt as needed):
    - Academic Research: Abstract, Introduction, Literature Review (if applicable), Methodology, Analysis, Discussion, and Conclusion.
    - Investment / Market Reports: Executive Summary, Macro Trends, Industry Overview, Competitive Landscape, Consumer Analysis, Financials, Risks, and Conclusion.
    - Technical Reports: Overview, Architecture, Methodology, Experiments, Results, and Discussion.
    - Policy / Legal Reports: Summary, Context, Stakeholder Analysis, Evidence/Precedent Review, Implications, and Recommendations.
    - Other Domains: Apply structures that are standard for the field (e.g., medical, engineering, UX, marketing, product management, etc.).

    2. Writing as a Domain Expert:
    - The structure, tone, vocabulary, and analytical frameworks must mirror what executives expect from premium professional services
    - Simulate the writing style, analytical depth, and intellectual sophistication of a senior professional in the field. For example:
    1. Finance/Investment: Write as a Managing Director who has led 50+ deals, understands capital markets deeply, and thinks in DCF, multiples, and risk-adjusted returns
    2. Strategy: Write as a McKinsey partner who has advised C-suites across industries, applies Porter's Five Forces and Jobs-to-be-Done intuitively, and structures problems with MECE thinking
    3. Academic: Write as a tenured professor publishing in top-tier journals with rigorous methodology and theoretical grounding
    4. Legal: Write as a senior partner with 25+ years of experience who understands case law, regulatory nuance, and business implications

    3. Tone and Style
    - Default to generate answers in prose; use bullets when they improve scannability (features, steps, trade-offs, risks, recommendations). Prefer prose over bullets: Write in paragraph form as your default. Use bullet points for:
    • Lists of specific items (e.g., regulatory requirements, product features)
    • Step-by-step procedures
    • Parallel comparisons where structure adds clarity
    • Highlighting key insights
    - Do not use bullets for: analysis, explanations, arguments, or narrative content
    - Analysis over description or summaries: Don't summarize—analyze. Explain causation, trade-offs, implications, and provide key takeaway in every topic sentence, back up with data evidence or expert quotes, then write analysis and the implicit indication of the evidence which supports your topic sentence and your thesis. Your analysis should explain causation, trade-offs, implications, and answer the user's question when they "so what?" or "why is this an important piece of information?" for decision-makers.
    - Formal and authoritative: Maintain a professional tone throughout. Never use first-person pronouns ("I," "we," "our") or self-referential phrases ("Based on my research...")
    - Inverted pyramid: Lead with conclusions and key findings, then support with evidence and reasoning
    - Sentence variety: Mix sentence lengths and structures for readability. Avoid monotonous patterns.
    - Quality over arbitrary length: The goal is comprehensiveness and depth, not word count. A 2,000-word report that decisively answers the question is better than a 5,000-word report with filler.

    4. Adaptive Knowledge-Level control:
    Before writing, assess the user's knowledge level by analyzing:
    - Memory entries: Review past topics discussed, technical depth of questions, and vocabulary used
    - Current query vocabulary: Evaluate whether they use domain-specific terminology correctly
    - Question sophistication: Simple factual questions vs. complex strategic questions
    Then adjust your response:
    For Expert Users (uses technical terms correctly, asks sophisticated questions):
    - Use precise domain terminology without explanation
    - Assume familiarity with industry context
    - Dive directly into nuanced analysis
    - Use domain-appropriate vocabulary, but balance professionalism with accessibility:

    For Intermediate Users (some domain knowledge, but gaps evident):
    - Use technical terms but provide brief, inline context
    - Example: "...using a discounted cash flow (DCF) analysis, which values a company based on its projected future cash flows..."
    - Balance accessibility with professionalism

    For General Users (limited domain knowledge, basic questions):
    - Define jargon on first use with concise clarity
    - Example: "The company's EBITDA (earnings before interest, taxes, depreciation, and amortization—a measure of operating profitability) grew 23%..."
    Use analogies sparingly when they clarify complex concepts
    - Maintain professional tone while being educational

    5. Analytical Depth
    - Provide quantitative and qualitative reasoning — cite metrics, data, or frameworks where possible.
    - When sources conflict, explicitly explain the disagreement, justify which sources you rely on, and state any remaining uncertainty or limitations.
    - Offer comparative and contrastive insights when multiple items are involved.
    - Ensure every conclusion is supported by evidence or citation.
    - Apply analytical frameworks explicitly (e.g., user journey, Value Chain Analysis, financial & non-financial dimensions, etc.)
    - Compare and contrast entities using data-driven reasoning

    CRITICAL INSTRUCTION - NEVER VIOLATE:
    - When making tool calls: Output ONLY the tool calls, and NEVER generate text revealing commentary about these tools or their outputs.
    - When generating the final report: Output ONLY the report text with no tool calls.
    - Outputting tool calls and generating text are mutually exclusive. Any violation will cause system failure.
    - Do not include a separate sentence or section about sources.
    - NEVER produce citations containing spaces, commas, or dashes. Citations are restricted to numbers only. All citations MUST contain numbers.
    </output>

    <citations>
    - Citations are essential for referencing and attributing information found from items that have unique id identifiers. Follow the formatting instructions below to ensure citations are clear, consistent, helpful to the user.
    - Do not cite computational or processing tools that perform calculations, transformations, etc.
    - When referencing tool outputs, cite only the numeric portion of each item's ID in square brackets (e.g., [3]), immediately following the relevant statement. - Example: Water boils at 100°C[2]. Here, [2] refers to a returned result such as web:2.
    - When multiple items support a sentence, include each number in its own set of square brackets with no spaces between them (e.g., [2][5]). NEVER USE "water[1-3]" or "water[12-47]".
    - Cite the `id` index for both direct quotes and information you paraphrase.
    - If information is gathered from several steps, list all corresponding `id`.
    - When using markdown tables, include citations within table cells immediately after the relevant data or information, following the same citation format (e.g., "| 25%[3] |" or "| Increased revenue[1][4] |").
    - Cite sources thoroughly for factual claims, research findings, statistics, quotes, and specialized knowledge. Usually, 1-3 citations per sentence are sufficient.
    - Failing to do so can lead to unsubstantiated claims and reduce the reliability of your answer.
    - This requirement is especially important as you approach the end of the response.
    - Maintain consistent citation practices throughout the entire answer, including the final sentences.
    - Citations must not contain spaces, commas, or dashes. Citations are restricted to numbers only. All citations MUST contain numbers.
    - Never include a bibliography, references section, or list citations at the end of your answer. All citations must appear inline and directly after the relevant statement.
    - Never expose or mention full raw IDs or their type prefixes in your final response, except through this approved citation format or special citation cases below.
    </citations>


    </answer_formatting>
    ```
  </Accordion>

  <Accordion title="advanced-deep-research">
    ```
    <role>
    You are a research expert. You synthesize complex information into clear, well-reasoned answers while adapting your vocabulary and depth to match the user's domain and knowledge level.

    Your task: iteratively gather evidence from authoritative sources, analyze it carefully, and produce a comprehensive answer that directly addresses the user's query. Continue researching until you have sufficient evidence to support your conclusions with institutional-grade depth. You are allowed at most 10 steps.

    Before presenting your final answer, use tools iteratively to gather evidence, reason carefully, then compose your final answer. Generate your final answer directly when you are confident you can fully address the query.
    </role>

    <instruction>
    As a research expert, you are responsible for the following steps:
    - iteratively gather information (`<information_gathering>`)
    - in a final step, generate the final answer to the user's query (`<answer_generation>`)


    <information_gathering>
    - Begin your turn by generating tool calls to gather information.
    - Break down complex user queries into a series of simple, sequential tasks so that each corresponding tool can perform its specific function more efficiently and accurately.
    - NEVER call the same tool with the same arguments more than once. If a tool call with specific arguments fails or does not provide the desired result, use a different method, try alternative arguments, or notify the user of the limitation.
    - For topics that involve quantitative data, NEVER simulate real data by generating synthetic data. Do NOT simulate "representative" or "sample" data based on high-level trends. Any specific quantitative data you use must be directly sourced. Creating synthetic data is misleading and renders the result untrustworthy.
    - If you cannot answer due to unavailable tools or inaccessible information, explicitly mention this and explain the limitation.
    </information_gathering>

    <answer_generation>
    - DO NOT write "I'll research..." or "Let me search..." or any explanatory text during research.
    - DO NOT explain your reasoning or plans during information gathering.
    - If you write ANY text during research, the system will immediately terminate and treat it as your final answer.
    - In your final step (and ONLY in your final step), generate text that directly and thoroughly addresses the user's query.
    - Any text output combined with a tool call will cause the system to malfunction and treat your response as a final answer rather than a tool execution.

    LENGTH CALIBRATION:
    Match answer length to query complexity:
    - **Fact-seeking queries** ("What is X?" / "When did Y happen?"): Direct answer with context, 3-6 paragraphs.
    - **Concise/summary requests** ("Brief overview of..." / "Summarize..."): 5-12 paragraphs.
    - **Comparison/ranking requests** ("Compare the top 5..." / "Best options for..."): Structured analysis, 10-25 paragraphs. Prefer tables over lengthy prose.
    - **Open-ended research** ("Analyze..." / "Explain the history and implications of..."): 20-40+ paragraphs.
    - **Explicit depth requests** ("Comprehensive report..." / "Deep dive..."): Length determined by topic scope.

    SOURCE DEPTH:
    Prioritize primary and authoritative sources. When citing, prefer reputable sources first: official documentation, peer-reviewed research, established news outlets, government sources, and recognized industry experts over blogs, forums, or unverified sources. Scale research intensity to query complexity:
    - Simple factual queries: Search until you find consistent, authoritative answers
    - Moderate research: Search until you can provide substantive analysis with multiple perspectives
    - Complex research (reports, competitive analysis, literature reviews): Search until you have covered major viewpoints, can support recommendations with evidence, and can identify limitations or areas of uncertainty

    Cross-validate important claims across multiple sources. When you find conflicting information, investigate further rather than arbitrarily choosing one source.
    </answer_generation>
    </instruction>

    <citations_and_references>
    Use brackets with the source index immediately after the relevant statement: [1], [2], etc. Commas, dashes, or alternate formats are not valid citation formats. If citing multiple sources, write each citation in a separate bracket like [1][2][3].

    Correct: "The Eiffel Tower is in Paris[1][2]."
    Incorrect: "The Eiffel Tower is in Paris [1, 2]."
    Incorrect: "The Eiffel Tower is in Paris[1-2]."

    What requires citation: factual claims, statistics, research findings, quotes, specialized knowledge. Aim for 1-3 citations per substantive claim.

    Distribute citations throughout the answer—maintain consistent citation density from beginning to end. Never include a bibliography; all citations are inline.
    </citations_and_references>

    <tool_instructions>
    You will have the following tools available to assist with your research. After receiving tool results, carefully reflect on their quality and determine optimal next steps before proceeding. Use your thinking to plan and iterate based on this new information, and then take the best next action.
    <tool name="web_search">
    Using the `web_search` tool:
    - Use short, simple, keyword-based search queries.
    - You may include up to 3 separate queries in each call to the `web_search` tool. If you need to search for more than 3 topics, split into multiple calls.
    - If the query is complex or involves multiple entities, break it down into simple, single-entity search queries and run them in parallel.
      - Example: Avoid "Atlassian Cloudflare Twilio current market cap"
      - Instead: "Atlassian market cap", "Cloudflare market cap", "Twilio market cap"
    - If the query is already simple, use it as your search query, correcting grammar only if necessary.
    - When handling queries that need current information, reference today's date (as provided by the user).
    - Do not assume or rely on potentially outdated knowledge for information that changes over time (e.g., stock prices, rankings, current events).
    - Use only information found during research. Do not add inferred or fabricated information.
    </tool name="web_search">

    <tool name="fetch_url">
    Using the `fetch_url` tool:
    - Use when a query asks for information from a specific URL or several URLs.
    - Prefer `web_search` first. Use `fetch_url` only if search results are insufficient.
    - If you need to fetch several URLs, do so in one call. NEVER fetch URLs sequentially.
    - Use when you need complete information from a URL, such as lists, tables, or extended text sections.
    </tool name="fetch_url">
    </tool_instructions>
    ```
  </Accordion>
</AccordionGroup>

## Using Presets

Each preset can be called in two ways — use whichever fits your needs:

* **Dynamic preset (recommended)** — pass `preset="<name>"` and let Perplexity manage the underlying configuration so you automatically pick up future improvements.
* **Frozen configuration** — pass the preset's current model, system prompt, tools, and parameters directly (without `preset`) to lock in today's exact setup.

The examples below show both options for each preset. The frozen configurations mirror the values in the [Available Presets](#available-presets) table and the matching system prompt from the [System Prompts](#system-prompts) section.

### fast-search

Quick factual lookups with minimal latency.

<Tabs>
  <Tab title="Python SDK">
    <CodeGroup>
      ```python Dynamic preset theme={null}
      from perplexity import Perplexity

      client = Perplexity()

      response = client.responses.create(
          preset="fast-search",
          input="Who won the most recent Nobel Prize in Physics and what was their contribution?",
      )

      print(response.output_text)
      ```

      ```python Frozen configuration theme={null}
      from perplexity import Perplexity

      client = Perplexity()

      response = client.responses.create(
          model="google/gemini-3.1-flash-lite",
          input="Who won the most recent Nobel Prize in Physics and what was their contribution?",
          max_steps=1,
          instructions="<paste the fast-search system prompt from the System Prompts section>",
          tools=[
              {
                  "type": "web_search",
                  "snippet_mode": "low",
              },
          ],
      )

      print(response.output_text)
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Typescript SDK">
    <CodeGroup>
      ```typescript Dynamic preset theme={null}
      import Perplexity from '@perplexity-ai/perplexity_ai';

      const client = new Perplexity();

      const response = await client.responses.create({
          preset: "fast-search",
          input: "Who won the most recent Nobel Prize in Physics and what was their contribution?",
      });

      console.log(response.output_text);
      ```

      ```typescript Frozen configuration theme={null}
      import Perplexity from '@perplexity-ai/perplexity_ai';

      const client = new Perplexity();

      const response = await client.responses.create({
          model: "google/gemini-3.1-flash-lite",
          input: "Who won the most recent Nobel Prize in Physics and what was their contribution?",
          max_steps: 1,
          instructions: "<paste the fast-search system prompt from the System Prompts section>",
          tools: [
              {
                  type: "web_search",
                  snippet_mode: "low",
              },
          ],
      });

      console.log(response.output_text);
      ```
    </CodeGroup>
  </Tab>

  <Tab title="cURL">
    <CodeGroup>
      ```bash Dynamic preset theme={null}
      curl https://api.perplexity.ai/v1/agent \
        -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{
          "preset": "fast-search",
          "input": "Who won the most recent Nobel Prize in Physics and what was their contribution?"
        }' | jq
      ```

      ```bash Frozen configuration theme={null}
      curl https://api.perplexity.ai/v1/agent \
        -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{
          "model": "google/gemini-3.1-flash-lite",
          "input": "Who won the most recent Nobel Prize in Physics and what was their contribution?",
          "max_steps": 1,
          "instructions": "<paste the fast-search system prompt from the System Prompts section>",
          "tools": [
            {
              "type": "web_search",
              "snippet_mode": "low"
            }
          ]
        }' | jq
      ```
    </CodeGroup>
  </Tab>
</Tabs>

### pro-search

Researched answers with tool use for most queries.

<Tabs>
  <Tab title="Python SDK">
    <CodeGroup>
      ```python Dynamic preset theme={null}
      from perplexity import Perplexity

      client = Perplexity()

      response = client.responses.create(
          preset="pro-search",
          input="What are the key differences between the latest iPhone and Samsung Galaxy flagship phones released this year?",
      )

      print(response.output_text)
      ```

      ```python Frozen configuration theme={null}
      from perplexity import Perplexity

      client = Perplexity()

      response = client.responses.create(
          model="openai/gpt-5.1",
          input="What are the key differences between the latest iPhone and Samsung Galaxy flagship phones released this year?",
          max_steps=3,
          instructions="<paste the pro-search system prompt from the System Prompts section>",
          tools=[
              {
                  "type": "web_search",
                  "snippet_mode": "medium",
              },
              {"type": "fetch_url"},
          ],
      )

      print(response.output_text)
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Typescript SDK">
    <CodeGroup>
      ```typescript Dynamic preset theme={null}
      import Perplexity from '@perplexity-ai/perplexity_ai';

      const client = new Perplexity();

      const response = await client.responses.create({
          preset: "pro-search",
          input: "What are the key differences between the latest iPhone and Samsung Galaxy flagship phones released this year?",
      });

      console.log(response.output_text);
      ```

      ```typescript Frozen configuration theme={null}
      import Perplexity from '@perplexity-ai/perplexity_ai';

      const client = new Perplexity();

      const response = await client.responses.create({
          model: "openai/gpt-5.1",
          input: "What are the key differences between the latest iPhone and Samsung Galaxy flagship phones released this year?",
          max_steps: 3,
          instructions: "<paste the pro-search system prompt from the System Prompts section>",
          tools: [
              {
                  type: "web_search",
                  snippet_mode: "medium",
              },
              { type: "fetch_url" },
          ],
      });

      console.log(response.output_text);
      ```
    </CodeGroup>
  </Tab>

  <Tab title="cURL">
    <CodeGroup>
      ```bash Dynamic preset theme={null}
      curl https://api.perplexity.ai/v1/agent \
        -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{
          "preset": "pro-search",
          "input": "What are the key differences between the latest iPhone and Samsung Galaxy flagship phones released this year?"
        }' | jq
      ```

      ```bash Frozen configuration theme={null}
      curl https://api.perplexity.ai/v1/agent \
        -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{
          "model": "openai/gpt-5.1",
          "input": "What are the key differences between the latest iPhone and Samsung Galaxy flagship phones released this year?",
          "max_steps": 3,
          "instructions": "<paste the pro-search system prompt from the System Prompts section>",
          "tools": [
            {
              "type": "web_search",
              "snippet_mode": "medium"
            },
            {"type": "fetch_url"}
          ]
        }' | jq
      ```
    </CodeGroup>
  </Tab>
</Tabs>

### deep-research

In-depth analysis requiring multi-step reasoning.

<Tabs>
  <Tab title="Python SDK">
    <CodeGroup>
      ```python Dynamic preset theme={null}
      from perplexity import Perplexity

      client = Perplexity()

      response = client.responses.create(
          preset="deep-research",
          input="Analyze how AI regulation passed in 2025 across the EU, US, and China has affected startup funding and innovation so far.",
      )

      print(response.output_text)
      ```

      ```python Frozen configuration theme={null}
      from perplexity import Perplexity

      client = Perplexity()

      response = client.responses.create(
          model="openai/gpt-5.2",
          input="Analyze how AI regulation passed in 2025 across the EU, US, and China has affected startup funding and innovation so far.",
          max_steps=10,
          instructions="<paste the deep-research system prompt from the System Prompts section>",
          tools=[
              {
                  "type": "web_search",
                  "snippet_mode": "high",
              },
              {"type": "fetch_url"},
          ],
      )

      print(response.output_text)
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Typescript SDK">
    <CodeGroup>
      ```typescript Dynamic preset theme={null}
      import Perplexity from '@perplexity-ai/perplexity_ai';

      const client = new Perplexity();

      const response = await client.responses.create({
          preset: "deep-research",
          input: "Analyze how AI regulation passed in 2025 across the EU, US, and China has affected startup funding and innovation so far.",
      });

      console.log(response.output_text);
      ```

      ```typescript Frozen configuration theme={null}
      import Perplexity from '@perplexity-ai/perplexity_ai';

      const client = new Perplexity();

      const response = await client.responses.create({
          model: "openai/gpt-5.2",
          input: "Analyze how AI regulation passed in 2025 across the EU, US, and China has affected startup funding and innovation so far.",
          max_steps: 10,
          instructions: "<paste the deep-research system prompt from the System Prompts section>",
          tools: [
              {
                  type: "web_search",
                  snippet_mode: "high",
              },
              { type: "fetch_url" },
          ],
      });

      console.log(response.output_text);
      ```
    </CodeGroup>
  </Tab>

  <Tab title="cURL">
    <CodeGroup>
      ```bash Dynamic preset theme={null}
      curl https://api.perplexity.ai/v1/agent \
        -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{
          "preset": "deep-research",
          "input": "Analyze how AI regulation passed in 2025 across the EU, US, and China has affected startup funding and innovation so far."
        }' | jq
      ```

      ```bash Frozen configuration theme={null}
      curl https://api.perplexity.ai/v1/agent \
        -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{
          "model": "openai/gpt-5.2",
          "input": "Analyze how AI regulation passed in 2025 across the EU, US, and China has affected startup funding and innovation so far.",
          "max_steps": 10,
          "instructions": "<paste the deep-research system prompt from the System Prompts section>",
          "tools": [
            {
              "type": "web_search",
              "snippet_mode": "high"
            },
            {"type": "fetch_url"}
          ]
        }' | jq
      ```
    </CodeGroup>
  </Tab>
</Tabs>

### advanced-deep-research

Institutional-grade research with maximum depth.

<Tabs>
  <Tab title="Python SDK">
    <CodeGroup>
      ```python Dynamic preset theme={null}
      from perplexity import Perplexity

      client = Perplexity()

      response = client.responses.create(
          preset="advanced-deep-research",
          input="Provide a competitive analysis of the leading cloud computing providers in 2026, covering market share, pricing strategies, and emerging service differentiators.",
      )

      print(response.output_text)
      ```

      ```python Frozen configuration theme={null}
      from perplexity import Perplexity

      client = Perplexity()

      response = client.responses.create(
          model="anthropic/claude-opus-4-6",
          input="Provide a competitive analysis of the leading cloud computing providers in 2026, covering market share, pricing strategies, and emerging service differentiators.",
          max_steps=10,
          instructions="<paste the advanced-deep-research system prompt from the System Prompts section>",
          tools=[
              {
                  "type": "web_search",
                  "snippet_mode": "high",
              },
              {"type": "fetch_url"},
          ],
      )

      print(response.output_text)
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Typescript SDK">
    <CodeGroup>
      ```typescript Dynamic preset theme={null}
      import Perplexity from '@perplexity-ai/perplexity_ai';

      const client = new Perplexity();

      const response = await client.responses.create({
          preset: "advanced-deep-research",
          input: "Provide a competitive analysis of the leading cloud computing providers in 2026, covering market share, pricing strategies, and emerging service differentiators.",
      });

      console.log(response.output_text);
      ```

      ```typescript Frozen configuration theme={null}
      import Perplexity from '@perplexity-ai/perplexity_ai';

      const client = new Perplexity();

      const response = await client.responses.create({
          model: "anthropic/claude-opus-4-6",
          input: "Provide a competitive analysis of the leading cloud computing providers in 2026, covering market share, pricing strategies, and emerging service differentiators.",
          max_steps: 10,
          instructions: "<paste the advanced-deep-research system prompt from the System Prompts section>",
          tools: [
              {
                  type: "web_search",
                  snippet_mode: "high",
              },
              { type: "fetch_url" },
          ],
      });

      console.log(response.output_text);
      ```
    </CodeGroup>
  </Tab>

  <Tab title="cURL">
    <CodeGroup>
      ```bash Dynamic preset theme={null}
      curl https://api.perplexity.ai/v1/agent \
        -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{
          "preset": "advanced-deep-research",
          "input": "Provide a competitive analysis of the leading cloud computing providers in 2026, covering market share, pricing strategies, and emerging service differentiators."
        }' | jq
      ```

      ```bash Frozen configuration theme={null}
      curl https://api.perplexity.ai/v1/agent \
        -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{
          "model": "anthropic/claude-opus-4-6",
          "input": "Provide a competitive analysis of the leading cloud computing providers in 2026, covering market share, pricing strategies, and emerging service differentiators.",
          "max_steps": 10,
          "instructions": "<paste the advanced-deep-research system prompt from the System Prompts section>",
          "tools": [
            {
              "type": "web_search",
              "snippet_mode": "high"
            },
            {"type": "fetch_url"}
          ]
        }' | jq
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Customizing Presets

Presets provide sensible defaults, but you can override any parameter by passing additional parameters alongside the preset. This lets you customize behavior while keeping the preset's optimized configuration.

<Tabs>
  <Tab title="Python SDK">
    ```python theme={null}
    from perplexity import Perplexity

    client = Perplexity()

    # Override the model while keeping everything else from the preset
    response = client.responses.create(
        preset="pro-search",
        model="anthropic/claude-sonnet-4-6",  # Use Claude instead of the default GPT-5.1
        input="What are the key differences between the latest iPhone and Samsung Galaxy flagship phones released this year?",
    )

    # Override max_steps for deeper reasoning
    response = client.responses.create(
        preset="pro-search",
        input="How do the top three JavaScript frameworks compare for building enterprise dashboards?",
        max_steps=5,  # Override preset's default of 3
    )

    # Override tools configuration with a static search config
    response = client.responses.create(
        preset="pro-search",
        input="Summarize recent FDA drug approvals from clinicaltrials.gov",
        tools=[{
            "type": "web_search",
            "snippet_mode": "high",
            "filters": {
                "search_domain_filter": ["clinicaltrials.gov", "fda.gov"],  # Restrict to specific domains
            },
        }],
    )

    # Use explicit token budgets when you need exact budget control
    response = client.responses.create(
        preset="pro-search",
        input="Summarize recent FDA drug approvals from clinicaltrials.gov",
        tools=[{
            "type": "web_search",
            "max_tokens": 6000,
            "max_tokens_per_page": 1200,
            "filters": {
                "search_domain_filter": ["clinicaltrials.gov", "fda.gov"],
            },
        }],
    )
    ```
  </Tab>

  <Tab title="Typescript SDK">
    ```typescript theme={null}
    import Perplexity from '@perplexity-ai/perplexity_ai';

    const client = new Perplexity();

    // Override the model while keeping everything else from the preset
    const response = await client.responses.create({
        preset: "pro-search",
        model: "anthropic/claude-sonnet-4-6", // Use Claude instead of the default GPT-5.1
        input: "What are the key differences between the latest iPhone and Samsung Galaxy flagship phones released this year?",
    });

    // Override max_steps for deeper reasoning
    const response2 = await client.responses.create({
        preset: "pro-search",
        input: "How do the top three JavaScript frameworks compare for building enterprise dashboards?",
        max_steps: 5, // Override preset's default of 3
    });

    // Override tools configuration with a static search config
    const response3 = await client.responses.create({
        preset: "pro-search",
        input: "Summarize recent FDA drug approvals from clinicaltrials.gov",
        tools: [{
            type: "web_search" as const,
            snippet_mode: "high",
            filters: {
                search_domain_filter: ["clinicaltrials.gov", "fda.gov"], // Restrict to specific domains
            },
        }],
    });

    // Use explicit token budgets when you need exact budget control
    const response4 = await client.responses.create({
        preset: "pro-search",
        input: "Summarize recent FDA drug approvals from clinicaltrials.gov",
        tools: [{
            type: "web_search" as const,
            max_tokens: 6000,
            max_tokens_per_page: 1200,
            filters: {
                search_domain_filter: ["clinicaltrials.gov", "fda.gov"],
            },
        }],
    });
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    # Override the model while keeping everything else from the preset
    curl https://api.perplexity.ai/v1/agent \
      -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "preset": "pro-search",
        "model": "anthropic/claude-sonnet-4-6",
        "input": "What are the key differences between the latest iPhone and Samsung Galaxy flagship phones released this year?"
      }' | jq
    ```

    ```bash theme={null}
    # Override max_steps for deeper reasoning
    curl https://api.perplexity.ai/v1/agent \
      -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "preset": "pro-search",
        "input": "How do the top three JavaScript frameworks compare for building enterprise dashboards?",
        "max_steps": 5
      }' | jq
    ```
  </Tab>
</Tabs>

<Tip>
  When you override a parameter, the preset's other defaults remain in effect. For example, if you override `model` on `pro-search`, you still get the `web_search` and `fetch_url` tools, the optimized system prompt, and the default reasoning steps.
</Tip>

<Info>
  Use `snippet_mode` with `low`, `medium`, or `high` for static search configs. Explicit `max_tokens` and `max_tokens_per_page` budgets remain available as an advanced override when your application needs exact budget control.
</Info>

<Info>
  The full system prompts and detailed configurations for each preset are shown in the [System Prompts](#system-prompts) section above. The table at the top of this page summarizes the key parameters (model, max tokens, max steps, and available tools) for each preset.
</Info>

## Frozen Configurations

If you need a setup that does not change when Perplexity ships preset improvements — for example, change-managed environments, regulated workflows, or applications that need to pin a specific model and tool setup — replace the `preset` parameter with the explicit underlying configuration. This gives you the same behavior the preset has today, locked to the exact model, system prompt, and parameters you copied.

To freeze a preset, copy the values from the [Available Presets](#available-presets) table and the matching system prompt from the [System Prompts](#system-prompts) section, then pass them directly instead of the preset name. See the [Using Presets](#using-presets) section above for side-by-side dynamic and frozen examples for each preset.

<Tip>
  **Dynamic vs. frozen — which to choose?**

  * Choose the **dynamic preset** (default) if you want the best Perplexity-recommended quality at a stable cost/latency band, and are comfortable with the underlying model or system prompt evolving over time.
  * Choose a **frozen configuration** if insulating your application from future preset updates matters more than picking up improvements automatically — for example, regulated workflows, change-managed environments, or contracts that require a specific underlying model and tool setup.

  You can mix both: use the dynamic preset in most environments, and pin a frozen configuration in places where stability is required.
</Tip>

## Choosing a Preset

* **fast-search**: Simple questions, quick answers, minimal latency
* **pro-search**: Standard queries requiring research and tool use
* **deep-research**: Complex analysis, multi-step reasoning, comprehensive research
* **advanced-deep-research**: Maximum depth research with institutional-grade analysis, enhanced tool access, and sophisticated source coverage

## Next Steps

<CardGroup>
  <Card title="Agent API Quickstart" icon="rocket" href="/docs/agent-api/quickstart">
    Get started with the Agent API.
  </Card>

  <Card title="Models" icon="brain" href="/docs/agent-api/models">
    Explore direct model selection and third-party models.
  </Card>

  <Card title="API Reference" icon="code-circle" href="/api-reference/agent-post">
    View complete endpoint documentation.
  </Card>
</CardGroup>


# Prompt Guide
Source: https://docs.perplexity.ai/docs/agent-api/prompt-guide

How to write effective prompts for the Agent API.

The Agent API runs a bounded multi-turn loop: on each turn the model can call a tool (such as `web_search`), read the result, and decide whether to continue or answer. Prompts that work well with single-shot LLMs often underperform here, because the same text shapes tool selection, search query generation, and final response together.

Two parameters drive most of the prompt design:

* **`instructions`** sets the role, tone, formatting, and grounding rules that apply regardless of the user's question.
* **`input`** holds the actual question. It also seeds the first search query, so specificity here directly improves retrieval.

For hard constraints on retrieval (allowed domains, date ranges, region) and on the loop itself (max steps), use request parameters rather than prose. The sections below cover when to reach for each.

## Instructions

Use the `instructions` parameter for role, tone, language, formatting, and grounding rules. Instructions apply on every turn of the agent loop, so put things here that hold regardless of the user's question.

<Warning>
  Setting `instructions` with a preset **replaces** the preset's system prompt — it does not append. Each preset (`fast-search`, `pro-search`, `deep-research`) already covers tool-call discipline, query construction, citation, and formatting, so the preset's prompt should be overridden only when app-specific behavior is needed. Without a preset, `instructions` is the only system prompt the model sees.
</Warning>

**Example instructions block:**

```text Instructions theme={null}
You are a financial analyst writing for retail investors.

Rules:
- Aim for brief sentences and paragraphs.
- Define jargon the first time you use it.
- Prefer concrete numbers over vague qualifiers ("up 12% YoY" not "growing
  strongly").

Grounding rules:
- Cite sources inline by domain, e.g. (reuters.com). Do not write full URLs.
- If searches return no relevant results after trying alternative phrasings,
  or if the only matches are off-topic (different company, different fiscal year,
  etc.), say so explicitly rather than substituting related results.
```

Keep `instructions` focused. They are re-read on every turn of the agent loop, so bloat compounds across tool calls. If your block is growing long, check whether parts of it would be better expressed as request parameters: use [`response_format`](/docs/agent-api/output-control) with a JSON schema for machine-readable output, [`web_search` filters](/docs/agent-api/filters) for retrieval constraints, or move query-specific framing into `input`.

Built-in tools like `web_search` and `fetch_url` are tuned to work well without prompt-side guidance. You don't need to describe what they do, when to call them, or how to construct queries. Adjust tool-call count with the `max_steps` parameter and search constraints with `web_search` filters. If you're using custom `instructions` and want to nudge how the model uses built-in tools, you can reference them there as well.

For custom function tools you define yourself, the model relies on the `description` and parameter schema you provide, so make those as clear as you can. You can reinforce the tool's role in `instructions` if the description alone isn't enough to steer behavior.

## Input

Use the `input` parameter for the actual query you want answered. Input strongly shapes search behavior, so descriptive and specific phrasing directly improves retrieval. Vague inputs lead to vague searches.

**Example user prompt:**

```text Input theme={null}
What are the best sushi restaurants in the world currently?
```

## API Example

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity

  client = Perplexity()

  response = client.responses.create(
      preset="pro-search",
      input="What are the best sushi restaurants in the world currently?",
      instructions="You are a concise, well-researched assistant. If searches still return no relevant results after trying alternative phrasings, say so explicitly rather than guessing."
  )

  print(response.output_text)
  ```

  ```typescript Typescript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  const response = await client.responses.create({
    preset: "pro-search",
    input: "What are the best sushi restaurants in the world currently?",
    instructions: "You are a concise, well-researched assistant. If searches still return no relevant results after trying alternative phrasings, say so explicitly rather than guessing."
  });

  console.log(response.output_text);
  ```

  ```bash cURL theme={null}
  curl https://api.perplexity.ai/v1/agent \
    -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "preset": "pro-search",
      "input": "What are the best sushi restaurants in the world currently?",
      "instructions": "You are a concise, well-researched assistant. If searches still return no relevant results after trying alternative phrasings, say so explicitly rather than guessing."
    }' | jq
  ```
</CodeGroup>

## Best Practices

<CardGroup>
  <Card title="Be Specific and Descriptive">
    Use natural language, but include the vocabulary and context that would actually appear on relevant pages. Add a few words of context to disambiguate when a term could mean multiple things. Specificity in `input` directly improves retrieval.

    **Good Example**: "Compare energy efficiency ratings of heat pumps vs. traditional HVAC for residential use"

    **Poor Example**: "Tell me which home heating is better"
  </Card>

  <Card title="Cap Result Counts">
    If you want a list, say how long. Without an explicit cap, the model picks an arbitrary length.

    **Good Example**: "List the top 5 sushi restaurants in Tokyo"

    **Poor Example**: "Give me a list of sushi restaurants"
  </Card>

  <Card title="Use Instructions to Shape Tool Output">
    Can be useful if you want to nudge how the model handles tool output. Things like citation style, grounding behavior, or response formatting fit naturally here, since instructions apply on every turn of the agent loop.

    **Example** (`instructions`): "Cite sources inline by domain (e.g., reuters.com). State explicitly when tool results don't fully answer the question."
  </Card>
</CardGroup>

## Reading Sources from the Response

Read URLs and source metadata from the response payload, not from the model's written answer. For non-streaming responses, search results are available at the top level as `response.search_results` and inside `response.output[]` as items where `type == "search_results"` (both carry the same data). Pull URLs from `results[].url`. For streaming, listen for `response.reasoning.search_results` events. See [Output Control](/docs/agent-api/output-control) for the full response shape.

The model has access to URLs from tool output and can include them in its response if asked, but it's prone to mistyping or paraphrasing them. Presets also configure the model to cite by index (e.g., `[web:1]`), not by URL, so asking for URLs in prose fights the default citation format. Treat the model's text as the prose answer and the structured `search_results` field as the authoritative source list.

## Reduce Hallucinations

LLMs are tuned to be helpful, which can occasionally lead them to provide an answer when search results are thin or off-target rather than flagging the gap. The agent loop helps, since the model can refine queries and search again, but it does not eliminate the failure modes. Hallucination is most likely when the information isn't web-accessible (LinkedIn posts, private documents, paywalled content), when repeated searches return related but non-matching results, or when very recent information isn't indexed yet.

A few short additions to `instructions` cover most of these cases. Grounding rules belong here because instructions are re-read on every turn of the agent loop, so the same rule applies to the first search and to any follow-ups.

**Give the model permission to say it didn't find anything.** With an explicit out, the model is more likely to acknowledge insufficient results instead of leaning on training data to fill the gap.

```text Instructions theme={null}
If searches do not return relevant results after trying alternative phrasings, say so explicitly rather than providing speculative information.
```

**Require disclosure of near-misses.** When search returns related but non-matching results (a different year, a parent company instead of a subsidiary, a similar product), asking the model to surface the mismatch up front keeps these cases from being presented as direct answers.

```text Instructions theme={null}
If you find related but non-matching results (for example, a different year, a parent company, or a subsidiary), state the mismatch explicitly before answering.
```

## Use Parameters, Not Prose, for Hard Constraints

For source, date, or region constraints, prefer the `web_search` parameters over describing the constraint in prose. Parameters are applied by the search backend on every call, while prose-based filters are interpreted by the model and may not carry through every turn of the loop.

Keep `input` focused on the question itself, and move structural constraints into the tool config:

```python Avoid theme={null}
client.responses.create(
    preset="pro-search",
    input="Search only on Wikipedia for climate change policies from the past month."
)
```

```python Prefer theme={null}
client.responses.create(
    preset="pro-search",
    input="What are the latest climate change policies?",
    tools=[
        {
            "type": "web_search",
            "filters": {
                "search_domain_filter": ["wikipedia.org"],
                "search_recency_filter": "month"
            }
        }
    ]
)
```

See [Filters](/docs/agent-api/filters) for the full list of available parameters.

<Tip>
  To run without tools, set `tools_disabled: true` on the request. Passing `tools: []` does **not** clear preset tools. An empty array is treated the same as omitting the field, and the preset's defaults still apply.
</Tip>

## Next Steps

<CardGroup>
  <Card title="Output Control" icon="sliders" href="/docs/agent-api/output-control">
    Shape responses with `response_format` and learn the full response payload structure.
  </Card>

  <Card title="Filters" icon="magnifying-glass" href="/docs/agent-api/filters">
    Constrain search with domain, recency, and region parameters.
  </Card>

  <Card title="Web Search" icon="code" href="/docs/agent-api/tools/web-search">
    Configure the `web_search` tool for source-grounded context.
  </Card>

  <Card title="Presets" icon="layer-group" href="/docs/agent-api/presets">
    Choose a preset that matches your latency, depth, and tool requirements.
  </Card>
</CardGroup>


# Agent API
Source: https://docs.perplexity.ai/docs/agent-api/quickstart

The Agent API is a multi-provider, interoperable API specification for building LLM applications. Access models from multiple providers with integrated real-time web search, tool configuration, reasoning control, and token budgets—all through one unified interface.

<Card title="Try the Agent API Playground" href="https://console.perplexity.ai">
  Test Agent API requests and parameters interactively in the API console.
</Card>

## Why Use the Agent API?

<CardGroup>
  <Card title="Multi-Provider Access" icon="stack-3">
    Access OpenAI, Anthropic, Google, xAI, and more through one unified API, no need to manage multiple API keys.
  </Card>

  <Card title="Transparent Pricing" icon="receipt">
    See exact token counts and costs per request, no markup, just direct provider pricing.
  </Card>

  <Card title="Granular Control" icon="adjustments">
    Change models, reasoning, tokens, and tools with consistent syntax.
  </Card>
</CardGroup>

<Info>
  We recommend using our [official SDKs](/docs/sdk/overview) for a more convenient and type-safe way to interact with the Agent API.
</Info>

<Note>
  **Endpoint:** The Agent API is available at `POST https://api.perplexity.ai/v1/agent`. For OpenAI SDK compatibility, `POST /v1/responses` is also accepted as an alias. See the [OpenAI Compatibility Guide](/docs/agent-api/openai-compatibility) for details on using OpenAI SDKs with Perplexity.
</Note>

## Installation

Install the SDK for your preferred language:

<CodeGroup>
  ```bash Python theme={null}
  pip install perplexityai
  ```

  ```bash Typescript theme={null}
  npm install @perplexity-ai/perplexity_ai
  ```
</CodeGroup>

## Authentication

Set your API key as an environment variable. The SDK will automatically read it:

<Tabs>
  <Tab title="macOS/Linux">
    ```bash theme={null}
    export PERPLEXITY_API_KEY="your_api_key_here"
    ```
  </Tab>

  <Tab title="Windows">
    ```powershell theme={null}
    setx PERPLEXITY_API_KEY "your_api_key_here"
    ```
  </Tab>
</Tabs>

<Info>
  All SDK examples below automatically use the `PERPLEXITY_API_KEY` environment variable. You can also pass the key explicitly if needed.
</Info>

## Basic Usage

<Tip>
  **Convenience Property:** Both Python and Typescript SDKs provide an `output_text` property that aggregates all text content from response outputs. Instead of iterating through `response.output`, simply use `response.output_text` for cleaner code.
</Tip>

### Using a Third-Party Model

Use third-party models from OpenAI, Anthropic, Google, xAI, and other providers for specific capabilities:

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity

  client = Perplexity()

  response = client.responses.create(
      model="openai/gpt-5.5",
      input="Explain the difference between supervised and unsupervised learning in machine learning."
  )

  print(f"Response ID: {response.id}")
  print(response.output_text)
  ```

  ```typescript Typescript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  const response = await client.responses.create({
      model: "openai/gpt-5.5",
      input: "Explain the difference between supervised and unsupervised learning in machine learning."
  });

  console.log(`Response ID: ${response.id}`);
  console.log(response.output_text);
  ```

  ```bash cURL theme={null}
  curl https://api.perplexity.ai/v1/agent \
    -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "openai/gpt-5.5",
      "input": "Explain the difference between supervised and unsupervised learning in machine learning."
    }' | jq
  ```
</CodeGroup>

<Accordion title="Response">
  ```json theme={null}
  {
    "background": false,
    "completed_at": 1771891464,
    "created_at": 1771891464,
    "error": null,
    "frequency_penalty": 0,
    "id": "resp_f854ed0a-f0e2-4ee8-b5ea-8582956910f2",
    "incomplete_details": null,
    "instructions": null,
    "max_output_tokens": null,
    "max_tool_calls": null,
    "metadata": {},
    "model": "openai/gpt-5.5",
    "object": "response",
    "output": [
      {
        "content": [
          {
            "annotations": [],
            "logprobs": [],
            "text": "Supervised learning uses labeled data where each example has a known output, enabling the model to learn direct input-output relationships. Examples include classification and regression.",
            "type": "output_text"
          }
        ],
        "id": "msg_f47013d2-7fe7-44d6-a7aa-4e34c85ce2b6",
        "role": "assistant",
        "status": "completed",
        "type": "message"
      }
    ],
    "parallel_tool_calls": true,
    "presence_penalty": 0,
    "previous_response_id": null,
    "prompt_cache_key": null,
    "reasoning": null,
    "safety_identifier": null,
    "service_tier": "default",
    "status": "completed",
    "store": true,
    "temperature": 1,
    "text": {
      "format": {
        "type": "text"
      }
    },
    "tool_choice": "auto",
    "tools": [],
    "top_logprobs": 0,
    "top_p": 1,
    "truncation": "disabled",
    "usage": {
      "cost": {
        "currency": "USD",
        "input_cost": 4e-05,
        "output_cost": 0.00311,
        "total_cost": 0.00315
      },
      "input_tokens": 20,
      "input_tokens_details": {
        "cached_tokens": 0
      },
      "output_tokens": 222,
      "output_tokens_details": {
        "reasoning_tokens": 0
      },
      "total_tokens": 242
    },
    "user": null
  }
  ```
</Accordion>

### Using a Preset

Presets provide optimized defaults for specific use cases.

Start with a preset for quick setup:

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity

  client = Perplexity()

  response = client.responses.create(
      preset="pro-search",
      input="Compare the latest open-source LLMs released in 2025 in terms of benchmark performance, licensing, and real-world applications.",
  )

  print(f"Model used: {response.model}")
  print(response.output_text)
  ```

  ```typescript Typescript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  const response = await client.responses.create({
      preset: "pro-search",
      input: "Compare the latest open-source LLMs released in 2025 in terms of benchmark performance, licensing, and real-world applications.",
  });

  console.log(`Model used: ${response.model}`);
  console.log(response.output_text);
  ```

  ```bash cURL theme={null}
  curl https://api.perplexity.ai/v1/agent \
    -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "preset": "pro-search",
      "input": "Compare the latest open-source LLMs released in 2025 in terms of benchmark performance, licensing, and real-world applications."
    }' | jq
  ```
</CodeGroup>

<Accordion title="Response">
  ```json theme={null}
  {
    "background": false,
    "completed_at": 1771891641,
    "created_at": 1771891641,
    "error": null,
    "frequency_penalty": 0,
    "id": "resp_aca2bace-3782-4d81-be45-a82c24cfff9d",
    "incomplete_details": null,
    "instructions": "## Abstract\n<role>\nYou are an AI assistant developed by Perplexity AI...\n</role>\n...",
    "max_output_tokens": 8192,
    "max_tool_calls": null,
    "metadata": {},
    "model": "openai/gpt-5.1",
    "object": "response",
    "output": [
      {
        "queries": [
          "2025 open source LLM benchmark performance",
          "2025 newly released open source LLMs license",
          "2025 open source LLM real world use cases"
        ],
        "results": [
          {
            "date": "2025-11-19",
            "id": 1,
            "last_updated": "2026-02-23T12:12:34",
            "snippet": "updated\n\n19 Nov 2025\n\n# Open LLM Leaderboard\n\nThis LLM leaderboard displays...",
            "source": "web",
            "title": "Open LLM Leaderboard 2025",
            "url": "https://www.vellum.ai/open-llm-leaderboard"
          },
          {
            "date": "2023-05-05",
            "id": 2,
            "last_updated": "2026-01-06T09:02:43.651546",
            "snippet": "",
            "source": "web",
            "title": "A list of open LLMs available for commercial use.",
            "url": "https://github.com/eugeneyan/open-llms"
          },
          {
            "date": "2025-05-05",
            "id": 3,
            "last_updated": "2026-02-22T19:27:06",
            "snippet": "# Best Open Source LLMs You Can Run Locally in 2025\n\nRunning large language models on your own hardware is...",
            "source": "web",
            "title": "Best Open Source LLMs You Can Run Locally in 2025 - DemoDazzle",
            "url": "https://demodazzle.com/blog/open-source-llms-2025"
          },
          {
            "date": "2025-12-15",
            "id": 4,
            "last_updated": "2026-02-23T21:56:51",
            "snippet": "updated\n\n15 Dec 2025\n\n# LLM Leaderboard\n\nThis LLM leaderboard displays the latest public benchmark performance for SOTA model versions released after April 2024...",
            "source": "web",
            "title": "LLM Leaderboard 2025 - Vellum",
            "url": "https://www.vellum.ai/llm-leaderboard"
          },
          {
            "date": "2025-11-22",
            "id": 5,
            "last_updated": "2026-02-11T02:35:36",
            "snippet": "Open\u2011source Large Language Models (LLMs) have moved from niche hobby projects to a full\u2011blown industry trend in 2025...",
            "source": "web",
            "title": "Open\u2011Source LLMs 2025: GPT\u2011OSS Models & How ... - Neura AI Blog",
            "url": "https://blog.meetneura.ai/open-source-llms-2025/"
          },
          {
            "date": "2025-07-23",
            "id": 6,
            "last_updated": "2026-02-23T23:43:21",
            "snippet": "",
            "source": "web",
            "title": "55 real-world LLM applications and use cases from top ...",
            "url": "https://www.evidentlyai.com/blog/llm-applications"
          },
          {
            "date": "2025-10-29",
            "id": 7,
            "last_updated": "2026-02-23T21:22:10",
            "snippet": "",
            "source": "web",
            "title": "Top 10 open source LLMs for 2025 - NetApp Instaclustr",
            "url": "https://www.instaclustr.com/education/open-source-ai/top-10-open-source-llms-for-2025/"
          },
          {
            "date": "2025-05-21",
            "id": 8,
            "last_updated": "2026-02-23T14:54:20",
            "snippet": "Here are the details of OpenLLaMA:\n\n**Parameters:** 3B, 7B and 13B\n\n**License:** Apache 2.0...",
            "source": "web",
            "title": "The List of 11 Most Popular Open Source LLMs [2025]",
            "url": "https://www.lakera.ai/blog/open-source-llms"
          },
          {
            "date": "2026-01-07",
            "id": 9,
            "last_updated": "2026-02-23T17:41:06",
            "snippet": "",
            "source": "web",
            "title": "The state of open source AI models in 2025 | Red Hat Developer",
            "url": "https://developers.redhat.com/articles/2026/01/07/state-open-source-ai-models-2025"
          },
          {
            "date": "2025-10-28",
            "id": 10,
            "last_updated": "2026-02-23T07:53:56",
            "snippet": "- **Open source dominates by volume:** 63% of models in our dataset (59 open source vs 35 proprietary)\n- **Performance...",
            "source": "web",
            "title": "Open Source vs Proprietary LLMs: Complete 2025 Benchmark ...",
            "url": "https://whatllm.org/blog/open-source-vs-proprietary-llms-2025"
          },
          {
            "date": "2025-06-02",
            "id": 11,
            "last_updated": "2026-01-18T13:27:38.757741",
            "snippet": "",
            "source": "web",
            "title": "Top 8 Open\u2011Source LLMs to Watch in 2025 - JetRuby Agency",
            "url": "https://jetruby.com/blog/top-8-open-source-llms-to-watch-in-2025/"
          },
          {
            "date": "2026-01-26",
            "id": 12,
            "last_updated": "2026-02-23T16:49:21",
            "snippet": "",
            "source": "web",
            "title": "Best Open Source LLMs in 2026",
            "url": "https://www.keywordsai.co/blog/best-open-source-llms"
          },
          {
            "date": "2025-12-10",
            "id": 13,
            "last_updated": "2026-02-23T18:38:26",
            "snippet": "",
            "source": "web",
            "title": "Full Benchmark Table For...",
            "url": "https://skywork.ai/blog/llm/top-10-open-llms-2025-november-ranking-analysis/"
          },
          {
            "date": "2024-09-19",
            "id": 14,
            "last_updated": "2025-12-27T09:28:04.559969",
            "snippet": "## Top Open-Source LLMs of 2025\n\n### 1. LLaMA 3.1\n\n**Developer:**Meta AI **Release Date:**July 23, 2024 **Parameter Size:**405B, 70B, 8B...",
            "source": "web",
            "title": "Top 10 Open-Source LLMs in 2025 - Kite Metric",
            "url": "https://kitemetric.com/blogs/top-10-open-source-llms-in-2025-a-comprehensive-guide"
          },
          {
            "date": "2025-02-26",
            "id": 15,
            "last_updated": "2025-09-10T16:36:09.704235",
            "snippet": "Use Cases:\n\n**Advanced Chatbots:**Responsive customer support bots. **Content Creation for Marketing:**Generating product descriptions and blog posts...",
            "source": "web",
            "title": "Top 10 Open-Source LLMs in 2025 and Their Use Cases",
            "url": "https://capalearning.com/2025/02/26/top-10-open-source-llms-in-2025-and-their-use-cases/"
          }
        ],
        "type": "search_results"
      },
      {
        "contents": [
          {
            "snippet": "Hi, Camille\u2019s here! On October 28, 2025, I fell into a small rabbit hole...",
            "title": "Full Benchmark Table For...",
            "url": "https://skywork.ai/blog/llm/top-10-open-llms-2025-november-ranking-analysis/"
          },
          {
            "snippet": "# Open source vs proprietary LLMs: complete 2025 benchmark analysis\n\n## TL;DR: The state of LLMs in late 2025\n\n**The landscape has shifted dramatically:**\n\n- **Open source dominates by volume:** 63% of models in our dataset (59 open source vs 35 proprietary)\n- **Performance...",
            "title": "Open Source vs Proprietary LLMs: Complete 2025 Benchmark ...",
            "url": "https://whatllm.org/blog/open-source-vs-proprietary-llms-2025"
          }
        ],
        "type": "fetch_url_results"
      },
      {
        "content": [
          {
            "annotations": [],
            "logprobs": [],
            "text": "In 2025, the strongest open\u2011source LLMs (Qwen 2.5, Llama 3.3/3.x, DeepSeek V3\u2011series, Mixtral...",
            "type": "output_text"
          }
        ],
        "id": "msg_1140f2e2-5bdb-4be8-a4c8-9d56bf61f35f",
        "role": "assistant",
        "status": "completed",
        "type": "message"
      }
    ],
    "parallel_tool_calls": true,
    "presence_penalty": 0,
    "previous_response_id": null,
    "prompt_cache_key": null,
    "reasoning": null,
    "safety_identifier": null,
    "service_tier": "default",
    "status": "completed",
    "store": true,
    "temperature": 1,
    "text": {
      "format": {
        "type": "text"
      }
    },
    "tool_choice": "auto",
    "tools": [
      {
        "type": "web_search"
      },
      {
        "type": "fetch_url"
      }
    ],
    "top_logprobs": 0,
    "top_p": 1,
    "truncation": "disabled",
    "usage": {
      "cost": {
        "cache_read_cost": 0.00059,
        "currency": "USD",
        "input_cost": 0.00919,
        "output_cost": 0.02743,
        "tool_calls_cost": 0.0055,
        "total_cost": 0.04271
      },
      "input_tokens": 12088,
      "input_tokens_details": {
        "cache_creation_input_tokens": 0,
        "cache_read_input_tokens": 4736,
        "cached_tokens": 4736
      },
      "output_tokens": 2743,
      "output_tokens_details": {
        "reasoning_tokens": 0
      },
      "tool_calls_details": {
        "fetch_url": {
          "invocation": 1
        },
        "search_web": {
          "invocation": 1
        }
      },
      "total_tokens": 14831
    },
    "user": null
  }
  ```
</Accordion>

<Tip>
  Learn more about [presets](/docs/agent-api/presets) to explore pre-configured setups optimized for different use cases with specific models, token limits, and tool access.
</Tip>

### With Web Search

The Agent API provides access to a number of tools that can be used to extend the capabilities of the model.

Enable web search capabilities using the `web_search` tool:

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity

  client = Perplexity()

  response = client.responses.create(
      model="openai/gpt-5.5",
      input="What are the latest developments in AI?",
      tools=[{"type": "web_search"}],
      instructions="You have access to a web_search tool. Use it for questions about current events, news, or recent developments. Use 1 query for simple questions. Keep queries brief: 2-5 words. NEVER ask permission to search - just search when appropriate",
  )

  if response.status == "completed":
      print(response.output_text)
  ```

  ```typescript Typescript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  const response = await client.responses.create({
      model: "openai/gpt-5.5",
      input: "What are the latest developments in AI?",
      tools: [{ type: "web_search" }],
      instructions: "You have access to a web_search tool. Use it for questions about current events, news, or recent developments.",
  });

  if (response.status === "completed") {
      console.log(response.output_text);
  }
  ```

  ```bash cURL theme={null}
  curl https://api.perplexity.ai/v1/agent \
    -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "openai/gpt-5.5",
      "input": "What are the latest developments in AI?",
      "tools": [{"type": "web_search"}],
      "instructions": "You have access to a web_search tool. Use it for questions about current events, news, or recent developments."
    }' | jq
  ```
</CodeGroup>

<Accordion title="Response">
  ```json theme={null}
  {
    "background": false,
    "completed_at": 1771891737,
    "created_at": 1771891737,
    "error": null,
    "frequency_penalty": 0,
    "id": "resp_367113ed-7a1b-4b2e-bad7-93e53a6cbeca",
    "incomplete_details": null,
    "instructions": "You have access to a web_search tool. Use it for questions about current events, news, or recent developments. Use 1 query for simple questions. Keep queries brief: 2-5 words. NEVER ask permission to search - just search when appropriate",
    "max_output_tokens": 8192,
    "max_tool_calls": null,
    "metadata": {},
    "model": "openai/gpt-5.5",
    "object": "response",
    "output": [
      {
        "queries": [
          "latest AI developments 2026"
        ],
        "results": [
          {
            "date": "2026-01-01",
            "id": 1,
            "last_updated": "2026-02-23T20:10:25",
            "snippet": "Many believe efficiency will be the new frontier...",
            "source": "web",
            "title": "The trends that will shape AI and tech in 2026 - IBM",
            "url": "https://www.ibm.com/think/news/ai-tech-trends-predictions-2026"
          },
          {
            "date": "2026-01-08",
            "id": 2,
            "last_updated": "2026-02-23T20:19:20",
            "snippet": "## What\u2019s next in AI: 7 trends to watch in 2026\n\nAI is entering a new phase, one defined by real-world impact...",
            "source": "web",
            "title": "What's next in AI: 7 trends to watch in 2026 - Microsoft Source",
            "url": "https://news.microsoft.com/source/features/ai/whats-next-in-ai-7-trends-to-watch-in-2026/"
          },
          {
            "date": "2026-01-06",
            "id": 3,
            "last_updated": "2026-02-21T02:30:13",
            "snippet": "#### Topics\n\n#### AI in Action\n\n**Summary:**\n\nMIT SMR columnists Thomas H. Davenport and Randy Bean see five...",
            "source": "web",
            "title": "Five Trends in AI and Data Science for 2026",
            "url": "https://sloanreview.mit.edu/article/five-trends-in-ai-and-data-science-for-2026/"
          },
          {
            "date": "2026-01-06",
            "id": 4,
            "last_updated": "2026-02-24T00:01:21",
            "snippet": "## Jeff Su\n\n##### Jan 06, 2026 (0:13:13)\nMost #AI predictions are speculation. This video covers...",
            "source": "web",
            "title": "Top 6 AI Trends That Will Define 2026 (backed by data)",
            "url": "https://www.youtube.com/watch?v=B23W1gRT9eY"
          },
          {
            "date": "2026-01-15",
            "id": 5,
            "last_updated": "2026-02-23T17:37:52",
            "snippet": "",
            "source": "web",
            "title": "11 things AI experts are watching for in 2026 | University of California",
            "url": "https://www.universityofcalifornia.edu/news/11-things-ai-experts-are-watching-2026"
          },
          {
            "date": "2026-01-13",
            "id": 6,
            "last_updated": "2026-02-23T16:27:23",
            "snippet": "Artificial intelligence (AI) is no longer an emerging technology, it\u2019s a transformational force driving innovation across industries...",
            "source": "web",
            "title": "AI Trends in 2026: A New Era of AI Advancements and Breakthroughs",
            "url": "https://www.trigyn.com/insights/ai-trends-2026-new-era-ai-advancements-and-breakthroughs"
          },
          {
            "date": "2025-12-22",
            "id": 7,
            "last_updated": "2026-02-23T09:47:25",
            "snippet": "The most significant advances in artificial intelligence next year won't come from...",
            "source": "web",
            "title": "6 AI breakthroughs that will define 2026 - InfoWorld",
            "url": "https://www.infoworld.com/article/4108092/6-ai-breakthroughs-that-will-define-2026.html"
          },
          {
            "date": "2025-12-22",
            "id": 8,
            "last_updated": "2026-02-23T20:21:57",
            "snippet": "What will define AI in 2026? \ud83d\ude80 Martin Keen & Aaron Baughman explore groundbreaking trends like Agentic AI, cloud computing, automation, and quantum computing, plus innovations like Physical AI...",
            "source": "web",
            "title": "AI Trends 2026: Quantum, Agentic AI & Smarter Automation",
            "url": "https://www.youtube.com/watch?v=zt0JA5rxdfM"
          },
          {
            "date": "2025-12-15",
            "id": 9,
            "last_updated": "2026-02-23T13:13:58",
            "snippet": "",
            "source": "web",
            "title": "Stanford AI Experts Predict What Will Happen in 2026",
            "url": "https://hai.stanford.edu/news/stanford-ai-experts-predict-what-will-happen-in-2026"
          },
          {
            "date": "2025-05-10",
            "id": 10,
            "last_updated": "2026-02-20T16:07:11",
            "snippet": "{ts:574} breakthroughs in AlphaGo and Alpha Fold, which are absolutely incredible. Now, DeepMind has basically said...",
            "title": "2026 AI : 10 Things Coming In 2026 (A.I In 2026 Major Predictions)",
            "url": "https://www.youtube.com/watch?v=RfA2Ug4FuaY"
          }
        ],
        "type": "search_results"
      },
      {
        "content": [
          {
            "annotations": [],
            "logprobs": [],
            "text": "Here are major *recent* directions in AI (late 2025\u2013early 2026) that researchers...",
            "type": "output_text"
          }
        ],
        "id": "msg_d0f12cc6-c6a2-426f-b55e-fff247e40c8c",
        "role": "assistant",
        "status": "completed",
        "type": "message"
      }
    ],
    "parallel_tool_calls": true,
    "presence_penalty": 0,
    "previous_response_id": null,
    "prompt_cache_key": null,
    "reasoning": null,
    "safety_identifier": null,
    "service_tier": "default",
    "status": "completed",
    "store": true,
    "temperature": 1,
    "text": {
      "format": {
        "type": "text"
      }
    },
    "tool_choice": "auto",
    "tools": [
      {
        "type": "web_search"
      }
    ],
    "top_logprobs": 0,
    "top_p": 1,
    "truncation": "disabled",
    "usage": {
      "cost": {
        "currency": "USD",
        "input_cost": 0.00826,
        "output_cost": 0.0063,
        "tool_calls_cost": 0.005,
        "total_cost": 0.01956
      },
      "input_tokens": 4718,
      "input_tokens_details": {
        "cached_tokens": 0
      },
      "output_tokens": 450,
      "output_tokens_details": {
        "reasoning_tokens": 0
      },
      "tool_calls_details": {
        "search_web": {
          "invocation": 1
        }
      },
      "total_tokens": 5168
    },
    "user": null
  }
  ```
</Accordion>

### With Finance Search

Retrieve structured financial and market data using the `finance_search` tool. See the [Finance Search guide](/docs/agent-api/tools/finance-search) for capabilities and recommended configurations.

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity

  client = Perplexity()

  response = client.responses.create(
      model="perplexity/sonar",
      input="What's NVIDIA trading at right now, and what is its current P/E?",
      tools=[{"type": "finance_search"}],
  )

  for item in response.output:
      if item.type == "message":
          print(item.content[0].text)
  ```

  ```typescript Typescript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  const response = await client.responses.create({
      model: "perplexity/sonar",
      input: "What's NVIDIA trading at right now, and what is its current P/E?",
      tools: [{ type: "finance_search" }],
  });

  console.log(response.output_text);
  ```

  ```bash cURL theme={null}
  curl https://api.perplexity.ai/v1/agent \
    -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "perplexity/sonar",
      "input": "What is NVIDIA trading at right now, and what is its current P/E?",
      "tools": [{"type": "finance_search"}]
    }' | jq
  ```
</CodeGroup>

## Next Steps

<CardGroup>
  <Card title="Web Search" icon="settings-bolt" href="/docs/agent-api/tools/web-search">
    Use web search for source-grounded, current context.
  </Card>

  <Card title="Models" icon="brain" href="/docs/agent-api/models">
    Browse available models and pricing across all supported providers.
  </Card>

  <Card title="Presets" icon="settings" href="/docs/agent-api/presets">
    Explore pre-configured setups for common use cases like pro-search and deep-research.
  </Card>

  <Card title="Output Control" icon="indent-decrease" href="/docs/agent-api/output-control">
    Configure streaming responses and structured outputs with JSON schema.
  </Card>

  <Card title="Model Fallback" icon="square-rounded-arrow-down" href="/docs/agent-api/model-fallback">
    Specify multiple models for automatic failover and higher availability.
  </Card>

  <Card title="Prompt Guide" icon="book" href="/docs/agent-api/prompt-guide">
    Best practices for effective prompting with web search models.
  </Card>

  <Card title="Search Filters" icon="filter" href="/docs/agent-api/filters">
    Control search results with domain, date, and location filters.
  </Card>

  <Card title="API Reference" icon="code-circle" href="/api-reference/agent-post">
    View complete endpoint documentation and parameters.
  </Card>
</CardGroup>

<Info>
  Need help? Check out our [community](https://community.perplexity.ai) for support and discussions with other developers.
</Info>


# Fetch URL Content
Source: https://docs.perplexity.ai/docs/agent-api/tools/fetch-url-content

Fetch and extract content from specific URLs in the Agent API.

## Overview

The `fetch_url` tool fetches and extracts content from specific URLs during an Agent API request. Use it when your application already knows which page, article, document, or report the model should inspect.

Use `fetch_url` when you need full page content from known URLs. Use [`web_search`](/docs/agent-api/tools/web-search) when the model first needs to discover relevant pages.

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity

  client = Perplexity()

  response = client.responses.create(
      model="openai/gpt-5.5",
      input="Summarize the key claims in https://example.com/report.",
      tools=[
          {
              "type": "fetch_url"
          }
      ],
      instructions="Fetch the URL before summarizing it.",
  )

  print(response.output_text)
  ```

  ```typescript Typescript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  const response = await client.responses.create({
    model: 'openai/gpt-5.5',
    input: 'Summarize the key claims in https://example.com/report.',
    tools: [
      {
        type: 'fetch_url' as const,
      },
    ],
    instructions: 'Fetch the URL before summarizing it.',
  });

  console.log(response.output_text);
  ```

  ```bash cURL theme={null}
  curl https://api.perplexity.ai/v1/agent \
    -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "openai/gpt-5.5",
      "input": "Summarize the key claims in https://example.com/report.",
      "tools": [
        {
          "type": "fetch_url"
        }
      ],
      "instructions": "Fetch the URL before summarizing it."
    }' | jq
  ```
</CodeGroup>

## When to Use

| Use `fetch_url` when...                            | Use `web_search` when...                   |
| -------------------------------------------------- | ------------------------------------------ |
| You already have a URL                             | You need to discover relevant pages        |
| You need fuller page content                       | You need snippets from multiple sources    |
| You are summarizing a specific article or document | You are researching a broad topic          |
| You want the model to inspect a known source       | You want the model to find current sources |

<Tip>
  Combine `web_search` and `fetch_url` for multi-step research: search to find relevant pages, then fetch the most important URLs for fuller context.
</Tip>

## Parameters

| Parameter  | Type    | Required | Description                                                                               |
| ---------- | ------- | -------- | ----------------------------------------------------------------------------------------- |
| `type`     | string  | Yes      | Must be `"fetch_url"`.                                                                    |
| `max_urls` | integer | No       | Maximum number of URLs to fetch per tool call. The API schema allows values from 1 to 10. |

## Response Shape

When `fetch_url` runs, the response can include a `fetch_url_results` output item before the final assistant message. Each fetched content item includes the URL, page title, and extracted snippet.

```json theme={null}
{
  "output": [
    {
      "type": "fetch_url_results",
      "contents": [
        {
          "url": "https://example.com/report",
          "title": "Example Report",
          "snippet": "Extracted content from the fetched page."
        }
      ]
    },
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "The answer generated from the fetched URL content."
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 900,
    "output_tokens": 250,
    "total_tokens": 1150,
    "tool_calls_details": {
      "fetch_url": {
        "invocation": 1
      }
    }
  }
}
```

## Pricing

`fetch_url` is billed at **$0.50 per 1,000 requests** (**$0.0005 per fetch**). Model token usage is billed separately according to Agent API token pricing.

<Note>
  Pricing follows the same pattern as other tool calls: pay for tool invocations plus model tokens. See [Pricing](/docs/getting-started/pricing).
</Note>

## Next Steps

<CardGroup>
  <Card title="Web Search" icon="world-search" href="/docs/agent-api/tools/web-search">
    Search the web before fetching source content.
  </Card>

  <Card title="Finance Search" icon="chart-line" href="/docs/agent-api/tools/finance-search">
    Retrieve structured financial and market data.
  </Card>

  <Card title="People Search" icon="users" href="/docs/agent-api/tools/people-search">
    Search for professionals and employees.
  </Card>

  <Card title="API Reference" icon="code-circle" href="/api-reference/agent-post">
    View complete endpoint documentation.
  </Card>
</CardGroup>


# Finance Search
Source: https://docs.perplexity.ai/docs/agent-api/tools/finance-search

Retrieve structured financial and market data in the Agent API.

## Overview

`finance_search` lets the model pull structured financial and market data for public companies, ETFs, and related instruments. The model decides which fields to fetch based on your prompt.

Use it when one answer needs more than one type of financial data, such as valuation, earnings, and context for the same company or list of companies.

### Capabilities

| Data area                       | What it includes                                                                                  |
| ------------------------------- | ------------------------------------------------------------------------------------------------- |
| Company basics                  | Quotes, profiles, peers, and market metadata                                                      |
| Financials                      | Income statement, balance sheet, cash flow (quarterly and annual), key ratios                     |
| Valuation and pricing           | Current/near-real-time pricing, 1-minute to 1-month OHLCV ranges, pre-market and after-hours data |
| Earnings                        | Last earnings call transcript, report filings, beat/miss history, guidance discussion             |
| Segment and KPI tracking        | Revenue/profit by segment, geography, ARPU, subscriber counts, GMV, and other operating metrics   |
| Analyst coverage                | Forward revenue and EPS estimates, cover count, historical estimate changes                       |
| Market activity                 | Top gainers, top losers, and most active symbols                                                  |
| Ownership and corporate actions | Insider activity, ticker-level metadata, splits, and related market events                        |
| ETF and index details           | Top constituents, shares, weights, and market values                                              |

## Quickstart

Add `finance_search` to the `tools` array.

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity

  client = Perplexity()

  response = client.responses.create(
      model="perplexity/sonar",
      input="What's NVIDIA trading at right now, and what is its current P/E?",
      tools=[{"type": "finance_search"}]
  )

  for item in response.output:
      if item.type == "message":
          print(item.content[0].text)
  ```

  ```bash cURL theme={null}
  curl -X POST "https://api.perplexity.ai/v1/agent" \
    -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "perplexity/sonar",
      "input": "What is NVIDIA trading at right now, and what is its current P/E?",
      "tools": [
        {"type": "finance_search"}
      ]
    }'
  ```
</CodeGroup>

<Accordion title="Response">
  ```json theme={null}
  {
    "background": false,
    "completed_at": 1777644610,
    "created_at": 1777644610,
    "error": null,
    "frequency_penalty": 0,
    "id": "resp_d0476d0f-872d-492a-907e-1daa48eb9e32",
    "incomplete_details": null,
    "instructions": null,
    "max_output_tokens": 8192,
    "max_tool_calls": null,
    "metadata": {},
    "model": "perplexity/sonar",
    "object": "response",
    "output": [
      {
        "categories": ["quote"],
        "results": [
          {
            "category": "quote",
            "content": "## NVDA Quote\nQuote field guide: `price` is the latest quote/current price...\n| symbol | name | timestamp | market_status | price | currency | change | changesPercentage | marketCap | pe | eps | volume | dayLow | dayHigh | yearLow | yearHigh | previousClose | open |\n| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |\n| NVDA | NVIDIA Corporation | 2026-05-01 14:10:07 UTC | open | 200.23 | USD | 0.66 | 0.33 | 4,866,492,706,948 | 40.86 | 4.90 | 28,725,330 | 199.15 | 203 | 110.82 | 216.83 | 199.57 | 201.28 |",
            "sources": [
              "https://www.perplexity.ai/finance/NVDA/historical-data",
              "https://www.perplexity.ai/finance/NVDA"
            ],
            "tickers": ["NVDA"]
          }
        ],
        "tickers": ["NVDA"],
        "type": "finance_results"
      },
      {
        "content": [
          {
            "annotations": [],
            "logprobs": [],
            "text": "NVIDIA (NVDA) is currently trading at **$200.23** per share, and its current P/E ratio is **40.86**.",
            "type": "output_text"
          }
        ],
        "id": "msg_b188058f-8225-4642-90e6-da7112f96b69",
        "role": "assistant",
        "status": "completed",
        "type": "message"
      }
    ],
    "parallel_tool_calls": true,
    "presence_penalty": 0,
    "previous_response_id": null,
    "prompt_cache_key": null,
    "reasoning": null,
    "safety_identifier": null,
    "service_tier": "default",
    "status": "completed",
    "store": true,
    "temperature": 1,
    "text": {
      "format": {
        "type": "text"
      }
    },
    "tool_choice": "auto",
    "tools": [
      {
        "type": "finance_search"
      }
    ],
    "top_logprobs": 0,
    "top_p": 1,
    "truncation": "disabled",
    "usage": {
      "cost": {
        "currency": "USD",
        "input_cost": 0.00189,
        "output_cost": 0.00016,
        "tool_calls_cost": 0.005,
        "total_cost": 0.00705
      },
      "input_tokens": 7570,
      "input_tokens_details": {
        "cached_tokens": 0
      },
      "output_tokens": 63,
      "output_tokens_details": {
        "reasoning_tokens": 0
      },
      "tool_calls_details": {
        "finance_search": {
          "invocation": 1
        }
      },
      "total_tokens": 7633
    },
    "user": null
  }
  ```
</Accordion>

## Example Prompts

* **Full company brief:** "Give me a complete NVIDIA snapshot: valuation, segment revenue for the latest quarter, and management's latest commentary on margins guidance."
* **Compare companies in one request:** "Compare Apple, Microsoft, and Alphabet on revenue growth, operating margin, and forward P/E for the latest fiscal year."
* **Earnings + reaction context:** "Summarize Tesla's last earnings call, include actual vs consensus, and describe how the stock and analyst targets moved after publication."

## Prompt Guidance

`finance_search` works best when the prompt states the outcome, not the data shape.

* Start with the business question first, then include the company or ticker.
* Add time windows when relevant (`latest quarter`, `fiscal year to date`, `last 30 days`).
* Let the tool decide which specific report fields to retrieve.

## Recommended Configurations

Start with the configuration that matches the shape of the finance question.

| Configuration                     | Best for                                                 | Latency  | Quality | Cost   |
| --------------------------------- | -------------------------------------------------------- | -------- | ------- | ------ |
| Live Market Data and Quotes       | Real-time prices, quotes, and latest figures             | Fast     | Good    | Low    |
| Single-Company Historical Lookups | Basic historical financials for one company or ticker    | Balanced | High    | Medium |
| Multi-Step Financial Research     | Cross-company comparisons and complex financial analysis | Thorough | Highest | High   |

### Live Market Data and Quotes

Use this for time-sensitive answers that depend on real-time prices, quotes, or the latest market figures. It is the cheapest and fastest option while maintaining strong quality for live data lookups.

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity

  client = Perplexity()

  response = client.responses.create(
      model="perplexity/sonar",
      input="What is Apple trading at right now, and what is its latest market cap?",
      tools=[{"type": "finance_search"}],
      max_steps=1,
      max_output_tokens=1024
  )

  for item in response.output:
      if item.type == "message":
          print(item.content[0].text)
  ```

  ```bash cURL theme={null}
  curl -X POST "https://api.perplexity.ai/v1/agent" \
    -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "perplexity/sonar",
      "input": "What is Apple trading at right now, and what is its latest market cap?",
      "tools": [{"type": "finance_search"}],
      "max_steps": 1,
      "max_output_tokens": 1024
    }'
  ```
</CodeGroup>

<Accordion title="Response">
  ```json theme={null}
  {
    "id": "resp_541684d6-cc46-4115-9137-bb387088bc32",
    "object": "response",
    "model": "perplexity/sonar",
    "status": "completed",
    "created_at": 1777645562,
    "completed_at": 1777645562,
    "output": [
      {
        "type": "finance_results",
        "categories": ["quote"],
        "tickers": ["AAPL"],
        "results": [
          {
            "category": "quote",
            "tickers": ["AAPL"],
            "content": "## AAPL Quote\n| symbol | name | timestamp | market_status | price | currency | change | changesPercentage | marketCap | pe | eps | volume | dayLow | dayHigh | yearLow | yearHigh | previousClose | open |\n| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |\n| AAPL | Apple Inc. | 2026-05-01 14:26:00 UTC | open | 285.74 | USD | 14.39 | 5.30 | 4,194,988,943,600 | 34.51 | 8.28 | 29,155,124 | 278.37 | 287.21 | 193.25 | 288.62 | 271.35 | 278.86 |",
            "sources": [
              "https://www.perplexity.ai/finance/AAPL/historical-data",
              "https://www.perplexity.ai/finance/AAPL"
            ]
          }
        ]
      },
      {
        "type": "message",
        "id": "msg_d8c03075-799d-4d4d-8feb-cc95824db262",
        "role": "assistant",
        "status": "completed",
        "content": [
          {
            "type": "output_text",
            "text": "Apple (AAPL) is currently trading at **$285.74** per share, up about 5.30% on the day. Its latest market capitalization is approximately **$4.19 trillion**.",
            "annotations": [],
            "logprobs": []
          }
        ]
      }
    ],
    "tools": [{"type": "finance_search"}],
    "max_output_tokens": 8192,
    "tool_choice": "auto",
    "parallel_tool_calls": true,
    "usage": {
      "input_tokens": 7575,
      "output_tokens": 75,
      "total_tokens": 7650,
      "cost": {
        "currency": "USD",
        "input_cost": 0.00189,
        "output_cost": 0.00019,
        "tool_calls_cost": 0.005,
        "total_cost": 0.00708
      },
      "tool_calls_details": {
        "finance_search": {
          "invocation": 1
        }
      }
    }
  }
  ```
</Accordion>

### Single-Company Historical Lookups

Use this for a single company's historical figures or basic questions that benefit from both structured finance data and web context. GPT-5.5 is strong at simple web search and token-efficient for historical lookups.

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity

  client = Perplexity()

  response = client.responses.create(
      model="openai/gpt-5.5",
      input="What was Microsoft's revenue last fiscal year, and how did it compare with the prior year?",
      tools=[
          {"type": "web_search"},
          {"type": "finance_search"},
          {"type": "fetch_url"}
      ],
      max_steps=5,
      max_output_tokens=2048,
      reasoning={"effort": "low"}
  )

  for item in response.output:
      if item.type == "message":
          print(item.content[0].text)
  ```

  ```bash cURL theme={null}
  curl -X POST "https://api.perplexity.ai/v1/agent" \
    -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "openai/gpt-5.5",
      "input": "What was Microsoft revenue last fiscal year, and how did it compare with the prior year?",
      "tools": [
        {"type": "web_search"},
        {"type": "finance_search"},
        {"type": "fetch_url"}
      ],
      "max_steps": 5,
      "max_output_tokens": 2048,
      "reasoning": {"effort": "low"}
    }'
  ```
</CodeGroup>

<Accordion title="Response">
  ```json theme={null}
  {
    "id": "resp_1be7ab7e-0dda-4949-9578-1462f9557a6b",
    "object": "response",
    "model": "openai/gpt-5.5",
    "status": "completed",
    "created_at": 1777645563,
    "completed_at": 1777645563,
    "output": [
      {
        "type": "finance_results",
        "categories": ["financials"],
        "tickers": ["MSFT"],
        "results": [
          {
            "category": "financials",
            "tickers": ["MSFT"],
            "content": "## MSFT FY 2024\n| date | period | income_statement_total_revenues |\n| --- | --- | --- |\n| 2024-06-30 | 2024 FY | 245,122,000,000 |",
            "sources": [
              "https://www.perplexity.ai/finance/MSFT/financials?period=annual&category=INCOME_STATEMENT&fromYear=2024&toYear=2024"
            ]
          }
        ]
      },
      {
        "type": "finance_results",
        "categories": ["financials"],
        "tickers": ["MSFT"],
        "results": [
          {
            "category": "financials",
            "tickers": ["MSFT"],
            "content": "## MSFT FY 2025\n| date | period | income_statement_total_revenues |\n| --- | --- | --- |\n| 2025-06-30 | 2025 FY | 281,724,000,000 |",
            "sources": [
              "https://www.perplexity.ai/finance/MSFT/financials?period=annual&category=INCOME_STATEMENT&fromYear=2025&toYear=2025"
            ]
          }
        ]
      },
      {
        "type": "message",
        "id": "msg_99ccfbfd-bce8-4b9b-b412-b01ef45c7842",
        "role": "assistant",
        "status": "completed",
        "content": [
          {
            "type": "output_text",
            "text": "Microsoft's revenue in its last completed fiscal year, **FY2025 ended June 30, 2025**, was **$281.724 billion**.\n\nCompared with the prior year, **FY2024 revenue was $245.122 billion**, so Microsoft revenue increased by:\n\n- **$36.602 billion**\n- **About 14.9% year over year**",
            "annotations": [],
            "logprobs": []
          }
        ]
      }
    ],
    "tools": [
      {"type": "web_search"},
      {"type": "fetch_url"},
      {"type": "finance_search"}
    ],
    "max_output_tokens": 8192,
    "tool_choice": "auto",
    "parallel_tool_calls": true,
    "usage": {
      "input_tokens": 12522,
      "input_tokens_details": {
        "cached_tokens": 3840,
        "cache_read_input_tokens": 3840
      },
      "output_tokens": 500,
      "total_tokens": 13022,
      "cost": {
        "currency": "USD",
        "input_cost": 0.04341,
        "cache_read_cost": 0.00192,
        "output_cost": 0.015,
        "tool_calls_cost": 0.01,
        "total_cost": 0.07033
      },
      "tool_calls_details": {
        "finance_search": {
          "invocation": 2
        }
      }
    }
  }
  ```
</Accordion>

### Multi-Step Financial Research

Use this for cross-company comparisons, longer historical investigations, and analysis that needs several tool calls across financial statements, filings, transcripts, and web sources. Opus performs best on complex multi-step reasoning when paired with the full tool suite.

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity

  client = Perplexity()

  response = client.responses.create(
      model="anthropic/claude-opus-4-7",
      input="Compare Apple, Microsoft, and Alphabet on revenue growth, margin trends, and management commentary over the last three fiscal years.",
      tools=[
          {"type": "web_search"},
          {"type": "finance_search"},
          {"type": "fetch_url"}
      ],
      max_steps=10,
      max_output_tokens=4096
  )

  for item in response.output:
      if item.type == "message":
          print(item.content[0].text)
  ```

  ```bash cURL theme={null}
  curl -X POST "https://api.perplexity.ai/v1/agent" \
    -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "anthropic/claude-opus-4-7",
      "input": "Compare Apple, Microsoft, and Alphabet on revenue growth, margin trends, and management commentary over the last three fiscal years.",
      "tools": [
        {"type": "web_search"},
        {"type": "finance_search"},
        {"type": "fetch_url"}
      ],
      "max_steps": 10,
      "max_output_tokens": 4096
    }'
  ```
</CodeGroup>

<Accordion title="Response">
  ```json theme={null}
  {
    "id": "resp_466bc636-cbad-43ce-9f66-c8b296712f05",
    "object": "response",
    "model": "anthropic/claude-opus-4-7",
    "status": "completed",
    "created_at": 1777645564,
    "completed_at": 1777645564,
    "output": [
      {
        "type": "finance_results",
        "categories": ["financials"],
        "tickers": ["AAPL", "MSFT", "GOOGL"],
        "results": [
          {
            "category": "financials",
            "tickers": ["AAPL", "MSFT", "GOOGL"],
            "content": "## AAPL FY 2025\n| date | period | total_revenues | gross_profit | operating_profit | net_income | gross_margin | operating_margin | net_margin |\n| --- | --- | --- | --- | --- | --- | --- | --- | --- |\n| 2025-09-27 | 2025 FY | 416,161,000,000 | 195,201,000,000 | 133,050,000,000 | 112,010,000,000 | 0.47 | 0.32 | 0.27 |\n\n## MSFT FY 2025\n| 2025-06-30 | 2025 FY | 281,724,000,000 | 193,893,000,000 | 128,528,000,000 | 101,832,000,000 | 0.69 | 0.46 | 0.36 |\n\n## GOOGL FY 2025\n| 2025-12-31 | 2025 FY | 402,836,000,000 | 240,301,000,000 | 129,039,000,000 | 132,170,000,000 | 0.60 | 0.32 | 0.33 |"
          }
        ]
      },
      {
        "type": "finance_results",
        "categories": ["financials"],
        "tickers": ["AAPL", "MSFT", "GOOGL"],
        "results": [
          {
            "category": "financials",
            "content": "## AAPL FY 2024\n| 2024-09-28 | 2024 FY | 391,035,000,000 | ... | 0.46 | 0.32 | 0.24 |\n\n## MSFT FY 2024\n| 2024-06-30 | 2024 FY | 245,122,000,000 | ... | 0.70 | 0.45 | 0.36 |\n\n## GOOGL FY 2024\n| 2024-12-31 | 2024 FY | 350,018,000,000 | ... | 0.58 | 0.32 | 0.29 |"
          }
        ]
      },
      {
        "type": "finance_results",
        "categories": ["financials"],
        "tickers": ["AAPL", "MSFT", "GOOGL"],
        "results": [
          {
            "category": "financials",
            "content": "## AAPL FY 2023 — total revenue 383,285,000,000 (GM 0.44 / OpM 0.30 / NM 0.25)\n## MSFT FY 2023 — total revenue 211,915,000,000 (GM 0.69 / OpM 0.42 / NM 0.34)\n## GOOGL FY 2023 — total revenue 307,394,000,000 (GM 0.57 / OpM 0.27 / NM 0.24)"
          }
        ]
      },
      {
        "type": "finance_results",
        "categories": ["transcript"],
        "tickers": ["AAPL", "MSFT", "GOOGL"],
        "results": [
          {
            "category": "transcript",
            "tickers": ["AAPL"],
            "content": "AAPL Q2 2026: Revenue $111.184B (est. $109.46B), EPS $2.01 (est. $1.92). 17% revenue growth in March quarter; June guide +14-17%. GM guide 47.5-48.5%. Management flagged rising memory costs as an increasing headwind. Accelerating AI investment via Apple Intelligence; install base 2.5B devices.",
            "sources": ["https://www.perplexity.ai/finance/AAPL/earnings"]
          },
          {
            "category": "transcript",
            "tickers": ["MSFT"],
            "content": "MSFT Q3 2026: Revenue $82.886B (est. $81.44B), EPS $4.27 (est. $4.07). Revenue +18% YoY; AI ARR reached $37B (+123% YoY). CapEx >$40B next quarter, ~$190B for CY2026. Capacity-constrained through 2026. Expects double-digit revenue and operating-income growth in FY27.",
            "sources": ["https://www.perplexity.ai/finance/MSFT/earnings"]
          },
          {
            "category": "transcript",
            "tickers": ["GOOGL"],
            "content": "GOOGL Q1 2026: Revenue $109.896B (est. $106.98B), EPS $5.11 (est. $2.64). 22% revenue growth; Search +19%, Cloud +63%. Operating margin 36.1%. 2026 CapEx raised to $180-190B; 2027 CapEx to significantly increase. Cloud margin headwind from Wiz acquisition.",
            "sources": ["https://www.perplexity.ai/finance/GOOGL/earnings"]
          }
        ]
      },
      {
        "type": "message",
        "id": "msg_90e83fe4-f020-47f0-990e-f82aa0b655da",
        "role": "assistant",
        "status": "completed",
        "content": [
          {
            "type": "output_text",
            "text": "# Apple vs. Microsoft vs. Alphabet — 3-Year Comparison\n\n## 1. Revenue Growth\n| Company | FY2023 | FY2024 | FY2025 | 2-yr CAGR | YoY FY25 |\n|---|---|---|---|---|---|\n| Apple (AAPL)   | $383.3B | $391.0B | $416.2B | +4.2%  | +6.4%  |\n| Microsoft (MSFT)| $211.9B | $245.1B | $281.7B | +15.3% | +14.9% |\n| Alphabet (GOOGL)| $307.4B | $350.0B | $402.8B | +14.5% | +15.1% |\n\n## 2. Margin Trends\n- Apple: GM 44% → 47%, OpM steady ~32%, NM 25% → 27%.\n- Microsoft: GM ~69% (slightly compressed by AI capex), OpM 42% → 46%, NM 34% → 36%.\n- Alphabet: GM 57% → 60%, OpM 27% → 32% (largest expansion), NM 24% → 33%.\n\n## 3. Management Commentary (latest calls)\n- Apple (Q2 FY26): Revenue +17%, June guide +14-17%; flagging memory-cost headwind.\n- Microsoft (Q3 FY26): Revenue +18%; AI ARR $37B (+123%); CY26 capex ~$190B.\n- Alphabet (Q1 2026): Revenue +22%; Cloud +63%; CY26 capex raised to $180-190B; 2027 capex to significantly increase.\n\n## Bottom Line\n- Revenue growth: Microsoft (closely followed by Alphabet)\n- Margin level: Microsoft\n- Margin expansion: Alphabet\n- Capital intensity: Apple is lightest; MSFT and GOOGL each spending $180-190B on 2026 capex.\n\nKey tension: AI investment is fueling top-line acceleration (especially MSFT and GOOGL) but creating depreciation and component-cost headwinds that are starting to weigh on gross margins.",
            "annotations": [],
            "logprobs": []
          }
        ]
      }
    ],
    "tools": [
      {"type": "web_search"},
      {"type": "fetch_url"},
      {"type": "finance_search"}
    ],
    "max_output_tokens": 8192,
    "tool_choice": "auto",
    "parallel_tool_calls": true,
    "usage": {
      "input_tokens": 61887,
      "input_tokens_details": {
        "cached_tokens": 36778,
        "cache_creation_input_tokens": 25100,
        "cache_read_input_tokens": 36778
      },
      "output_tokens": 3456,
      "total_tokens": 65343,
      "cost": {
        "currency": "USD",
        "input_cost": 0.00005,
        "cache_creation_cost": 0.15688,
        "cache_read_cost": 0.01839,
        "output_cost": 0.0864,
        "tool_calls_cost": 0.02,
        "total_cost": 0.28172
      },
      "tool_calls_details": {
        "finance_search": {
          "invocation": 4
        }
      }
    }
  }
  ```
</Accordion>

## Parameters

| Parameter | Type   | Required | Description                 |
| --------- | ------ | -------- | --------------------------- |
| `type`    | string | Yes      | Must be `"finance_search"`. |

## Response Shape

When `finance_search` runs, the response can include `finance_results` output items before the final assistant message. Each `finance_results` item includes the requested finance categories, ticker symbols, structured content, and source URLs when available. The final `usage` object includes token counts, cost details, and `tool_calls_details.finance_search.invocation` when tool-call usage is reported.

```json theme={null}
{
  "output": [
    {
      "type": "finance_results",
      "categories": ["quote"],
      "tickers": ["NVDA"],
      "results": [
        {
          "category": "quote",
          "tickers": ["NVDA"],
          "content": "Structured quote data returned by the finance search tool.",
          "sources": [
            "https://www.perplexity.ai/finance/NVDA"
          ]
        }
      ]
    },
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "The answer generated from finance data."
        }
      ]
    }
  ],
  "usage": {
    "tool_calls_details": {
      "finance_search": {
        "invocation": 1
      }
    }
  }
}
```

## Pricing

`finance_search` is billed at **\$5 per 1,000 invocations**. Model token usage is billed separately according to Agent API token pricing.

<Note>
  Pricing follows the same pattern as other tool calls: pay for invocations plus model tokens. See [Pricing](/docs/getting-started/pricing).
</Note>

## Next Steps

<CardGroup>
  <Card title="Web Search" icon="world-search" href="/docs/agent-api/tools/web-search">
    Search the web for source-grounded context.
  </Card>

  <Card title="Fetch URL Content" icon="file-text" href="/docs/agent-api/tools/fetch-url-content">
    Fetch full content from known URLs.
  </Card>

  <Card title="People Search" icon="users" href="/docs/agent-api/tools/people-search">
    Search for professionals and employees.
  </Card>

  <Card title="Agent API Quickstart" icon="rocket" href="/docs/agent-api/quickstart">
    Get started with the Agent API.
  </Card>
</CardGroup>


# People Search
Source: https://docs.perplexity.ai/docs/agent-api/tools/people-search

Search for professionals, employees, and people using People Search in the Agent API

## Overview

The `people_search` tool enables models to find people and retrieve their professional information such as names, job titles, and companies. Use it to power workflows like lead research, recruiting pipelines, or organizational mapping.

Use it when your application needs to:

* Look up a specific person's professional background
* Find employees at a company by role or title
* Identify professionals in a particular field or location
* Research leadership teams or organizational structures

The model decides when to invoke `people_search` based on your prompt and instructions.

### Query Tips

For the best results, guide the model with specific details in your prompt:

| Approach            | Example prompt                                  |
| ------------------- | ----------------------------------------------- |
| **Name + company**  | "Find John Smith who works at Google"           |
| **Role + company**  | "Who is the Head of Design at Figma?"           |
| **Role + location** | "Find marketing directors in San Francisco"     |
| **Role + field**    | "Find machine learning researchers at Stanford" |

<Info>
  The tool works best for people-related queries — it is not suited for general web search.
</Info>

## Tiered Configurations

The following four tiered configurations span the speed/quality tradeoff for workloads that mix `people_search` with `web_search` and `fetch_url`. Each tier defines a model, reasoning effort, tool selection, per-tool token budgets, and step limits. Use them as starting points and adjust per your latency, depth, and accuracy needs.

| Tier              | Model                           | Reasoning | Tools                                      | Max Steps | Use When                                                                    |
| ----------------- | ------------------------------- | --------- | ------------------------------------------ | --------- | --------------------------------------------------------------------------- |
| **pro**           | `openai/gpt-5-mini`             | medium    | `people_search`, `web_search`, `fetch_url` | 5         | Balanced people/web research with moderate depth                            |
| **deep**          | `google/gemini-3-flash-preview` | high      | `people_search`, `web_search`, `fetch_url` | 10        | Deeper analysis when latency budget is moderate but quality matters         |
| **advanced-deep** | `openai/gpt-5`                  | medium    | `people_search`, `web_search`, `fetch_url` | 10        | High-quality, multi-step research with long context                         |
| **ultra-deep**    | `openai/gpt-5.5`                | high      | `people_search`, `web_search`, `fetch_url` | 50        | Maximum-depth investigations with the largest token budgets and step counts |

<Info>
  The `bigtokens` settings used by pro, deep, and advanced-deep refer to `max_tokens=10000`, `max_tokens_per_page=1000`, `max_results_per_query=10`, and `max_results_per_request=30` on the `people_search` and `web_search` tools. The `xltokens` settings used by ultra-deep refer to `max_tokens=20000`, `max_tokens_per_page=2000`, `max_results_per_query=30`, and `max_results_per_request=50`.
</Info>

<Warning>
  **ultra-deep heads-up:** `openai/gpt-5.5` with high reasoning and streaming may be flaky upstream. If requests hang, fall back to `medium` reasoning effort or disable streaming.
</Warning>

### pro

Balanced configuration with all three tools enabled and moderate reasoning effort.

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity

  client = Perplexity()

  response = client.responses.create(
      model="openai/gpt-5-mini",
      reasoning={"effort": "medium"},
      tools=[
          {
              "type": "people_search",
              "max_tokens": 10000,
              "max_tokens_per_page": 1000,
              "max_results_per_query": 10,
              "max_results_per_request": 30,
          },
          {
              "type": "web_search",
              "max_tokens": 10000,
              "max_tokens_per_page": 1000,
              "max_results_per_query": 10,
              "max_results_per_request": 30,
          },
          {"type": "fetch_url"},
      ],
      max_steps=5,
      input="Find the head of platform engineering at Notion and summarize their background.",
  )

  print(response.output_text)
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  const response = await client.responses.create({
    model: 'openai/gpt-5-mini',
    reasoning: { effort: 'medium' },
    tools: [
      {
        type: 'people_search',
        max_tokens: 10000,
        max_tokens_per_page: 1000,
        max_results_per_query: 10,
        max_results_per_request: 30,
      },
      {
        type: 'web_search',
        max_tokens: 10000,
        max_tokens_per_page: 1000,
        max_results_per_query: 10,
        max_results_per_request: 30,
      },
      { type: 'fetch_url' },
    ],
    max_steps: 5,
    input: 'Find the head of platform engineering at Notion and summarize their background.',
  });

  console.log(response.output_text);
  ```

  ```bash cURL theme={null}
  curl -X POST "https://api.perplexity.ai/v1/agent" \
    -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "openai/gpt-5-mini",
      "reasoning": {"effort": "medium"},
      "tools": [
        {
          "type": "people_search",
          "max_tokens": 10000,
          "max_tokens_per_page": 1000,
          "max_results_per_query": 10,
          "max_results_per_request": 30
        },
        {
          "type": "web_search",
          "max_tokens": 10000,
          "max_tokens_per_page": 1000,
          "max_results_per_query": 10,
          "max_results_per_request": 30
        },
        {"type": "fetch_url"}
      ],
      "max_steps": 5,
      "input": "Find the head of platform engineering at Notion and summarize their background."
    }'
  ```
</CodeGroup>

### deep

Higher reasoning effort and step count with a generous output budget for fuller multi-source answers.

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity

  client = Perplexity()

  response = client.responses.create(
      model="google/gemini-3-flash-preview",
      reasoning={"effort": "high"},
      tools=[
          {
              "type": "people_search",
              "max_tokens": 10000,
              "max_tokens_per_page": 1000,
              "max_results_per_query": 10,
              "max_results_per_request": 30,
          },
          {
              "type": "web_search",
              "max_tokens": 10000,
              "max_tokens_per_page": 1000,
              "max_results_per_query": 10,
              "max_results_per_request": 30,
          },
          {"type": "fetch_url"},
      ],
      max_steps=10,
      max_output_tokens=16000,
      input="Map the executive team at a mid-size SaaS company and explain each leader's prior roles.",
  )

  print(response.output_text)
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  const response = await client.responses.create({
    model: 'google/gemini-3-flash-preview',
    reasoning: { effort: 'high' },
    tools: [
      {
        type: 'people_search',
        max_tokens: 10000,
        max_tokens_per_page: 1000,
        max_results_per_query: 10,
        max_results_per_request: 30,
      },
      {
        type: 'web_search',
        max_tokens: 10000,
        max_tokens_per_page: 1000,
        max_results_per_query: 10,
        max_results_per_request: 30,
      },
      { type: 'fetch_url' },
    ],
    max_steps: 10,
    max_output_tokens: 16000,
    input: "Map the executive team at a mid-size SaaS company and explain each leader's prior roles.",
  });

  console.log(response.output_text);
  ```

  ```bash cURL theme={null}
  curl -X POST "https://api.perplexity.ai/v1/agent" \
    -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "google/gemini-3-flash-preview",
      "reasoning": {"effort": "high"},
      "tools": [
        {
          "type": "people_search",
          "max_tokens": 10000,
          "max_tokens_per_page": 1000,
          "max_results_per_query": 10,
          "max_results_per_request": 30
        },
        {
          "type": "web_search",
          "max_tokens": 10000,
          "max_tokens_per_page": 1000,
          "max_results_per_query": 10,
          "max_results_per_request": 30
        },
        {"type": "fetch_url"}
      ],
      "max_steps": 10,
      "max_output_tokens": 16000,
      "input": "Map the executive team at a mid-size SaaS company and explain each leader'\''s prior roles."
    }'
  ```
</CodeGroup>

### advanced-deep

A frontier-model configuration for high-quality, multi-step research when latency budget is generous.

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity

  client = Perplexity()

  response = client.responses.create(
      model="openai/gpt-5",
      reasoning={"effort": "medium"},
      tools=[
          {
              "type": "people_search",
              "max_tokens": 10000,
              "max_tokens_per_page": 1000,
              "max_results_per_query": 10,
              "max_results_per_request": 30,
          },
          {
              "type": "web_search",
              "max_tokens": 10000,
              "max_tokens_per_page": 1000,
              "max_results_per_query": 10,
              "max_results_per_request": 30,
          },
          {"type": "fetch_url"},
      ],
      max_steps=10,
      input="Identify the top product leaders across three competitors and compare their backgrounds.",
  )

  print(response.output_text)
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  const response = await client.responses.create({
    model: 'openai/gpt-5',
    reasoning: { effort: 'medium' },
    tools: [
      {
        type: 'people_search',
        max_tokens: 10000,
        max_tokens_per_page: 1000,
        max_results_per_query: 10,
        max_results_per_request: 30,
      },
      {
        type: 'web_search',
        max_tokens: 10000,
        max_tokens_per_page: 1000,
        max_results_per_query: 10,
        max_results_per_request: 30,
      },
      { type: 'fetch_url' },
    ],
    max_steps: 10,
    input: 'Identify the top product leaders across three competitors and compare their backgrounds.',
  });

  console.log(response.output_text);
  ```

  ```bash cURL theme={null}
  curl -X POST "https://api.perplexity.ai/v1/agent" \
    -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "openai/gpt-5",
      "reasoning": {"effort": "medium"},
      "tools": [
        {
          "type": "people_search",
          "max_tokens": 10000,
          "max_tokens_per_page": 1000,
          "max_results_per_query": 10,
          "max_results_per_request": 30
        },
        {
          "type": "web_search",
          "max_tokens": 10000,
          "max_tokens_per_page": 1000,
          "max_results_per_query": 10,
          "max_results_per_request": 30
        },
        {"type": "fetch_url"}
      ],
      "max_steps": 10,
      "input": "Identify the top product leaders across three competitors and compare their backgrounds."
    }'
  ```
</CodeGroup>

### ultra-deep

Maximum-depth configuration with the largest token budgets, the highest step count, and `xltokens` per-tool settings. Best for exhaustive investigations.

<Warning>
  `openai/gpt-5.5` with high reasoning and streaming may be flaky upstream. If requests hang, switch to `medium` effort or use a non-streaming call.
</Warning>

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity

  client = Perplexity()

  response = client.responses.create(
      model="openai/gpt-5.5",
      reasoning={"effort": "high"},
      tools=[
          {
              "type": "people_search",
              "max_tokens": 20000,
              "max_tokens_per_page": 2000,
              "max_results_per_query": 30,
              "max_results_per_request": 50,
          },
          {
              "type": "web_search",
              "max_tokens": 20000,
              "max_tokens_per_page": 2000,
              "max_results_per_query": 30,
              "max_results_per_request": 50,
          },
          {"type": "fetch_url"},
      ],
      max_steps=50,
      max_output_tokens=32000,
      input="Build a complete organizational map of a target company, including reporting lines and prior employment history for every named leader.",
  )

  print(response.output_text)
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  const response = await client.responses.create({
    model: 'openai/gpt-5.5',
    reasoning: { effort: 'high' },
    tools: [
      {
        type: 'people_search',
        max_tokens: 20000,
        max_tokens_per_page: 2000,
        max_results_per_query: 30,
        max_results_per_request: 50,
      },
      {
        type: 'web_search',
        max_tokens: 20000,
        max_tokens_per_page: 2000,
        max_results_per_query: 30,
        max_results_per_request: 50,
      },
      { type: 'fetch_url' },
    ],
    max_steps: 50,
    max_output_tokens: 32000,
    input: 'Build a complete organizational map of a target company, including reporting lines and prior employment history for every named leader.',
  });

  console.log(response.output_text);
  ```

  ```bash cURL theme={null}
  curl -X POST "https://api.perplexity.ai/v1/agent" \
    -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "openai/gpt-5.5",
      "reasoning": {"effort": "high"},
      "tools": [
        {
          "type": "people_search",
          "max_tokens": 20000,
          "max_tokens_per_page": 2000,
          "max_results_per_query": 30,
          "max_results_per_request": 50
        },
        {
          "type": "web_search",
          "max_tokens": 20000,
          "max_tokens_per_page": 2000,
          "max_results_per_query": 30,
          "max_results_per_request": 50
        },
        {"type": "fetch_url"}
      ],
      "max_steps": 50,
      "max_output_tokens": 32000,
      "input": "Build a complete organizational map of a target company, including reporting lines and prior employment history for every named leader."
    }'
  ```
</CodeGroup>

## Parameters

| Parameter                 | Type    | Required | Description                                                                       |
| ------------------------- | ------- | -------- | --------------------------------------------------------------------------------- |
| `type`                    | string  | Yes      | Must be `"people_search"`.                                                        |
| `max_tokens`              | integer | No       | Maximum total tokens for people-search context when using explicit token budgets. |
| `max_tokens_per_page`     | integer | No       | Maximum tokens extracted per result page when using explicit token budgets.       |
| `max_results_per_query`   | integer | No       | Maximum results returned for each generated people-search query.                  |
| `max_results_per_request` | integer | No       | Maximum results returned across the request.                                      |

## Response Shape

When `people_search` runs, the response can include search-style result details before the final assistant message. The final `usage` object includes token counts, cost details, and `tool_calls_details.people_search.invocation` when tool-call usage is reported.

```json theme={null}
{
  "output": [
    {
      "type": "search_results",
      "queries": ["head of platform engineering Notion"],
      "results": [
        {
          "id": 1,
          "url": "https://example.com/profile",
          "title": "Example professional profile",
          "snippet": "A short snippet describing the professional result.",
          "source": "web"
        }
      ]
    },
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "The answer generated from people-search results."
        }
      ]
    }
  ],
  "usage": {
    "tool_calls_details": {
      "people_search": {
        "invocation": 1
      }
    }
  }
}
```

## Pricing

Each invocation of the `people_search` tool is billed at **\$5 per 1,000 tool invocations**. See the [Pricing](/docs/getting-started/pricing) page for full details.

## Next Steps

<CardGroup>
  <Card title="Web Search" icon="world-search" href="/docs/agent-api/tools/web-search">
    Search the web for source-grounded context.
  </Card>

  <Card title="Fetch URL Content" icon="file-text" href="/docs/agent-api/tools/fetch-url-content">
    Fetch full content from known URLs.
  </Card>

  <Card title="Finance Search" icon="chart-line" href="/docs/agent-api/tools/finance-search">
    Retrieve structured financial and market data.
  </Card>

  <Card title="Agent API Quickstart" icon="rocket" href="/docs/agent-api/quickstart">
    Get started with the Agent API.
  </Card>
</CardGroup>


# Web Search
Source: https://docs.perplexity.ai/docs/agent-api/tools/web-search

Search the web from the Agent API with filters, search configs, pricing, parameters, and response fields.

## Overview

The `web_search` tool lets the model search the web during an Agent API request. Use it for current information, recent news, source-grounded research, and questions that need information beyond the model's training data.

Enable the tool by adding it to the `tools` array. The model decides when to call it based on your prompt and instructions.

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity

  client = Perplexity()

  response = client.responses.create(
      model="openai/gpt-5.5",
      input="What are the latest AI infrastructure announcements this week?",
      tools=[
          {
              "type": "web_search",
              "snippet_mode": "medium"
          }
      ],
      instructions="Search for current, source-grounded information before answering.",
  )

  print(response.output_text)
  ```

  ```typescript Typescript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  const response = await client.responses.create({
    model: 'openai/gpt-5.5',
    input: 'What are the latest AI infrastructure announcements this week?',
    tools: [
      {
        type: 'web_search' as const,
        snippet_mode: 'medium',
      },
    ],
    instructions: 'Search for current, source-grounded information before answering.',
  });

  console.log(response.output_text);
  ```

  ```bash cURL theme={null}
  curl https://api.perplexity.ai/v1/agent \
    -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "openai/gpt-5.5",
      "input": "What are the latest AI infrastructure announcements this week?",
      "tools": [
        {
          "type": "web_search",
          "snippet_mode": "medium"
        }
      ],
      "instructions": "Search for current, source-grounded information before answering."
    }' | jq
  ```
</CodeGroup>

## Search Configs

Start with `low`, `medium`, or `high` for search context sizing. These static configs are the recommended default because they keep the request readable and let Perplexity tune the underlying token budgets over time.

| Config   | Best for                                                                         | Tradeoff                               |
| -------- | -------------------------------------------------------------------------------- | -------------------------------------- |
| `low`    | Simple facts, lightweight lookups, cost-sensitive traffic                        | Lowest cost and fastest search context |
| `medium` | General research, product comparisons, most production defaults                  | Balanced cost, latency, and context    |
| `high`   | Source-heavy answers, complex research, queries where missing details are costly | More context and higher cost           |

<CodeGroup>
  ```python Python theme={null}
  tools = [
      {
          "type": "web_search",
          "snippet_mode": "high"
      }
  ]
  ```

  ```typescript Typescript theme={null}
  const tools = [
    {
      type: 'web_search' as const,
      snippet_mode: 'high',
    },
  ];
  ```

  ```bash cURL theme={null}
  "tools": [
    {
      "type": "web_search",
      "snippet_mode": "high"
    }
  ]
  ```
</CodeGroup>

### Advanced

Use explicit token budgeting when you need to pin exact budgets for cost controls, latency controls, or evaluations. Set `max_tokens` to cap total search context across results, and set `max_tokens_per_page` to cap content extracted from each result page.

Users can choose a static config by setting `snippet_mode` to `low`, `medium`, or `high`, or choose dynamic behavior through explicit token budgeting. At any time, you can override the `low`, `medium`, or `high` config by passing explicit `max_tokens` and `max_tokens_per_page` values.

<CodeGroup>
  ```python Python theme={null}
  response = client.responses.create(
      model="openai/gpt-5.5",
      input="Find recent government guidance on AI procurement.",
      tools=[
          {
              "type": "web_search",
              "max_tokens": 6000,
              "max_tokens_per_page": 1200,
              "filters": {
                  "search_domain_filter": [".gov"],
                  "search_recency_filter": "month"
              }
          }
      ],
  )
  ```

  ```typescript Typescript theme={null}
  const response = await client.responses.create({
    model: 'openai/gpt-5.5',
    input: 'Find recent government guidance on AI procurement.',
    tools: [
      {
        type: 'web_search' as const,
        max_tokens: 6000,
        max_tokens_per_page: 1200,
        filters: {
          search_domain_filter: ['.gov'],
          search_recency_filter: 'month',
        },
      },
    ],
  });
  ```

  ```bash cURL theme={null}
  curl https://api.perplexity.ai/v1/agent \
    -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "openai/gpt-5.5",
      "input": "Find recent government guidance on AI procurement.",
      "tools": [
        {
          "type": "web_search",
          "max_tokens": 6000,
          "max_tokens_per_page": 1200,
          "filters": {
            "search_domain_filter": [".gov"],
            "search_recency_filter": "month"
          }
        }
      ]
    }' | jq
  ```
</CodeGroup>

## Filters

Use filters to constrain the sources, dates, and location context used by `web_search`. See the full [Search Filters](/docs/agent-api/filters) guide for examples and edge cases.

| Filter                       | Type             | Description                                                                           |
| ---------------------------- | ---------------- | ------------------------------------------------------------------------------------- |
| `search_domain_filter`       | array of strings | Include or exclude up to 20 domains or URLs. Prefix entries with `-` to exclude them. |
| `search_recency_filter`      | string           | Restrict results to `"hour"`, `"day"`, `"week"`, `"month"`, or `"year"`.              |
| `search_after_date_filter`   | string           | Include results published after a date in `MM/DD/YYYY` format.                        |
| `search_before_date_filter`  | string           | Include results published before a date in `MM/DD/YYYY` format.                       |
| `last_updated_after_filter`  | string           | Include results last updated after a date in `MM/DD/YYYY` format.                     |
| `last_updated_before_filter` | string           | Include results last updated before a date in `MM/DD/YYYY` format.                    |
| `user_location`              | object           | Personalize search by country, region, city, latitude, and longitude.                 |

<Warning>
  Use `search_domain_filter` in either allowlist mode or denylist mode, not both. For example, `["nasa.gov", "wikipedia.org"]` includes only those domains, while `["-reddit.com", "-pinterest.com"]` excludes those domains.
</Warning>

<CodeGroup>
  ```python Python theme={null}
  response = client.responses.create(
      model="openai/gpt-5.5",
      input="What changed in US AI policy this month?",
      tools=[
          {
              "type": "web_search",
              "snippet_mode": "medium",
              "filters": {
                  "search_domain_filter": [".gov"],
                  "search_recency_filter": "month"
              },
              "user_location": {
                  "country": "US"
              }
          }
      ],
  )
  ```

  ```typescript Typescript theme={null}
  const response = await client.responses.create({
    model: 'openai/gpt-5.5',
    input: 'What changed in US AI policy this month?',
    tools: [
      {
        type: 'web_search' as const,
        snippet_mode: 'medium',
        filters: {
          search_domain_filter: ['.gov'],
          search_recency_filter: 'month',
        },
        user_location: {
          country: 'US',
        },
      },
    ],
  });
  ```

  ```bash cURL theme={null}
  curl https://api.perplexity.ai/v1/agent \
    -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "openai/gpt-5.5",
      "input": "What changed in US AI policy this month?",
      "tools": [
        {
          "type": "web_search",
          "snippet_mode": "medium",
          "filters": {
            "search_domain_filter": [".gov"],
            "search_recency_filter": "month"
          },
          "user_location": {
            "country": "US"
          }
        }
      ]
    }' | jq
  ```
</CodeGroup>

## Parameters

| Parameter             | Type    | Required | Description                                                             |
| --------------------- | ------- | -------- | ----------------------------------------------------------------------- |
| `type`                | string  | Yes      | Must be `"web_search"`.                                                 |
| `snippet_mode`        | string  | No       | Static search config: `"low"`, `"medium"`, or `"high"`.                 |
| `filters`             | object  | No       | Domain and date filters. See [Search Filters](/docs/agent-api/filters). |
| `user_location`       | object  | No       | Location context for search personalization.                            |
| `max_tokens`          | integer | No       | Maximum total tokens for search context.                                |
| `max_tokens_per_page` | integer | No       | Maximum tokens extracted from each search result page.                  |

## Response Shape

When `web_search` runs, the response can include a `search_results` output item before the final assistant message. The final `usage` object includes token counts, cost details, and `tool_calls_details.web_search.invocation` when tool-call usage is reported.

```json theme={null}
{
  "output": [
    {
      "type": "search_results",
      "queries": ["AI infrastructure announcements"],
      "results": [
        {
          "id": 1,
          "url": "https://example.com/news",
          "title": "Example AI infrastructure announcement",
          "snippet": "A short snippet from the search result.",
          "date": "2026-05-01",
          "last_updated": "2026-05-01",
          "source": "web"
        }
      ]
    },
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "The answer generated from the search results."
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 1200,
    "output_tokens": 300,
    "total_tokens": 1500,
    "tool_calls_details": {
      "web_search": {
        "invocation": 1
      }
    }
  }
}
```

## Pricing

`web_search` is billed at **$5 per 1,000 search calls** (**$0.005 per search**). Model token usage is billed separately according to Agent API token pricing.

<Note>
  Pricing follows the same pattern as other tool calls: pay for tool invocations plus model tokens. See [Pricing](/docs/getting-started/pricing).
</Note>

## Next Steps

<CardGroup>
  <Card title="Fetch URL Content" icon="file-text" href="/docs/agent-api/tools/fetch-url-content">
    Fetch full content from known URLs.
  </Card>

  <Card title="Search Filters" icon="filter" href="/docs/agent-api/filters">
    Control domains, dates, recency, and location context.
  </Card>

  <Card title="Agent API Presets" icon="settings" href="/docs/agent-api/presets">
    Use optimized presets for common Agent API workloads.
  </Card>

  <Card title="API Reference" icon="code-circle" href="/api-reference/agent-post">
    View complete endpoint documentation.
  </Card>
</CardGroup>


# Academic and Scholarly Search
Source: https://docs.perplexity.ai/docs/cookbook/articles/academic-search/README

Use the Agent API's domain filtering to restrict search to academic sources, extract DOIs and paper metadata, build citation chains, and create research summaries with proper attribution

This guide shows how to use the Agent API's `search_domain_filter` to restrict search results to academic and scholarly sources. You will learn how to extract paper metadata (DOIs, authors, publication dates), build citation chains across related papers, and produce properly attributed research summaries.

<Info>
  The `search_domain_filter` parameter on the Agent API's `web_search` tool controls which domains the search draws from. By filtering to academic domains like `arxiv.org`, `nature.com`, and `.edu`, you restrict results to peer-reviewed journals, preprint servers, and academic databases. For more on filtering, see the [Agent API Filters](/docs/agent-api/filters) docs.
</Info>

## Prerequisites

Install the Perplexity SDK:

<CodeGroup>
  ```bash Python theme={null}
  pip install perplexityai
  ```

  ```bash TypeScript theme={null}
  npm install @perplexity-ai/perplexity_ai
  ```
</CodeGroup>

If you don't have an API key yet:

<Card title="Get your Perplexity API Key" icon="key" href="https://perplexity.ai/account/api">
  Navigate to the **API Keys** tab in the API Portal and generate a new key.
</Card>

Then export your API key as an environment variable:

```bash theme={null}
export PERPLEXITY_API_KEY="your-api-key"
```

## Basic Academic Search

Use `search_domain_filter` to restrict the Agent API's `web_search` tool to academic sources only.

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity

  client = Perplexity()

  ACADEMIC_DOMAINS = [
      "arxiv.org",
      "pubmed.ncbi.nlm.nih.gov",
      "nature.com",
      "science.org",
      ".edu",
      "scholar.google.com",
      "semanticscholar.org",
  ]

  response = client.responses.create(
      model="openai/gpt-5.4",
      input="What are the latest findings on the relationship between gut microbiome and mental health?",
      tools=[{
          "type": "web_search",
          "filters": {
              "search_domain_filter": ACADEMIC_DOMAINS,
          },
      }],
      instructions="Focus on peer-reviewed academic sources. Cite papers with authors and publication years when possible.",
  )

  print(response.output_text)
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  const ACADEMIC_DOMAINS = [
      "arxiv.org",
      "pubmed.ncbi.nlm.nih.gov",
      "nature.com",
      "science.org",
      ".edu",
      "scholar.google.com",
      "semanticscholar.org",
  ];

  const response = await client.responses.create({
      model: "openai/gpt-5.4",
      input: "What are the latest findings on the relationship between gut microbiome and mental health?",
      tools: [{
          type: "web_search" as const,
          filters: {
              search_domain_filter: ACADEMIC_DOMAINS,
          },
      }],
      instructions: "Focus on peer-reviewed academic sources. Cite papers with authors and publication years when possible.",
  });

  console.log(response.output_text);
  ```

  ```bash curl theme={null}
  curl "https://api.perplexity.ai/v1/agent" \
    -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "openai/gpt-5.4",
      "input": "What are the latest findings on the relationship between gut microbiome and mental health?",
      "tools": [{"type": "web_search", "filters": {"search_domain_filter": ["arxiv.org", "pubmed.ncbi.nlm.nih.gov", "nature.com", "science.org", ".edu"]}}],
      "instructions": "Focus on peer-reviewed academic sources. Cite papers with authors and publication years when possible."
    }'
  ```
</CodeGroup>

<Tip>
  Academic domain filtering targets papers from PubMed, arXiv, Google Scholar, Semantic Scholar, and major journal publishers. Combine `search_domain_filter` with clear `instructions` to ensure the model focuses on peer-reviewed or pre-print academic content.
</Tip>

## Extracting Paper Metadata

Use structured outputs to extract detailed paper metadata from academic search results.

<CodeGroup>
  ```python Python theme={null}
  import json
  from perplexity import Perplexity

  client = Perplexity()

  # Use Agent API with web_search for structured extraction
  response = client.responses.create(
      model="openai/gpt-5.4",
      input="Find the 5 most cited recent papers on transformer architectures in computer vision (Vision Transformers).",
      tools=[{"type": "web_search"}],
      instructions=(
          "Search for academic papers only. For each paper, extract the title, authors, "
          "publication year, journal or venue, DOI if available, and a one-sentence summary of the key contribution."
      ),
      response_format={
          "type": "json_schema",
          "json_schema": {
              "name": "academic_papers",
              "schema": {
                  "type": "object",
                  "properties": {
                      "query": {"type": "string"},
                      "papers": {
                          "type": "array",
                          "items": {
                              "type": "object",
                              "properties": {
                                  "title": {"type": "string"},
                                  "authors": {"type": "string"},
                                  "year": {"type": "integer"},
                                  "venue": {"type": "string"},
                                  "doi": {"type": "string"},
                                  "key_contribution": {"type": "string"},
                              },
                              "required": ["title", "authors", "year", "venue", "doi", "key_contribution"],
                              "additionalProperties": false,
                          },
                      },
                  },
                  "required": ["query", "papers"],
                  "additionalProperties": false,
              },
          },
      },
  )

  data = json.loads(response.output_text)
  print(f"Query: {data['query']}\n")

  for paper in data["papers"]:
      print(f"  {paper['title']}")
      print(f"    Authors: {paper['authors']}")
      print(f"    Venue: {paper['venue']} ({paper['year']})")
      if paper["doi"]:
          print(f"    DOI: {paper['doi']}")
      print(f"    Contribution: {paper['key_contribution']}")
      print()
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  const response = await client.responses.create({
      model: "openai/gpt-5.4",
      input: "Find the 5 most cited recent papers on transformer architectures in computer vision (Vision Transformers).",
      tools: [{ type: "web_search" }],
      instructions: "Search for academic papers only. For each paper, extract the title, authors, publication year, journal or venue, DOI if available, and a one-sentence summary of the key contribution.",
      response_format: {
          type: "json_schema",
          json_schema: {
              name: "academic_papers",
              schema: {
                  type: "object",
                  properties: {
                      query: { type: "string" },
                      papers: {
                          type: "array",
                          items: {
                              type: "object",
                              properties: {
                                  title: { type: "string" },
                                  authors: { type: "string" },
                                  year: { type: "integer" },
                                  venue: { type: "string" },
                                  doi: { type: "string" },
                                  key_contribution: { type: "string" },
                              },
                              required: ["title", "authors", "year", "venue", "doi", "key_contribution"],
                          },
                      },
                  },
                  required: ["query", "papers"],
              },
          },
      },
  });

  const data = JSON.parse(response.output_text);
  console.log(`Query: ${data.query}\n`);

  for (const paper of data.papers) {
      console.log(`  ${paper.title}`);
      console.log(`    Authors: ${paper.authors}`);
      console.log(`    Venue: ${paper.venue} (${paper.year})`);
      if (paper.doi) console.log(`    DOI: ${paper.doi}`);
      console.log(`    Contribution: ${paper.key_contribution}`);
      console.log();
  }
  ```
</CodeGroup>

## Building Citation Chains

Trace how papers cite each other to understand the evolution of an idea across the literature.

<CodeGroup>
  ```python Python theme={null}
  import json
  from perplexity import Perplexity

  client = Perplexity()


  def find_citing_papers(paper_title: str, depth: int = 0, max_depth: int = 2) -> dict:
      """Recursively find papers that cite a given paper."""
      indent = "  " * depth
      print(f"{indent}Searching citations for: {paper_title}...")

      response = client.responses.create(
          model="openai/gpt-5.4",
          input=f"What are the 3 most important papers that directly cite or build upon '{paper_title}'?",
          tools=[{"type": "web_search"}],
          instructions="Focus on academic papers only. Return papers that explicitly reference or extend the given work.",
          response_format={
              "type": "json_schema",
              "json_schema": {
                  "name": "citing_papers",
                  "schema": {
                      "type": "object",
                      "properties": {
                          "source_paper": {"type": "string"},
                          "citing_papers": {
                              "type": "array",
                              "items": {
                                  "type": "object",
                                  "properties": {
                                      "title": {"type": "string"},
                                      "authors": {"type": "string"},
                                      "year": {"type": "integer"},
                                      "relationship": {"type": "string"},
                                  },
                                  "required": ["title", "authors", "year", "relationship"],
                                  "additionalProperties": false,
                              },
                          },
                      },
                      "required": ["source_paper", "citing_papers"],
                      "additionalProperties": false,
                  },
              },
          },
      )

      data = json.loads(response.output_text)
      result = {
          "paper": paper_title,
          "cited_by": [],
      }

      for citing in data["citing_papers"]:
          entry = {
              "title": citing["title"],
              "authors": citing["authors"],
              "year": citing["year"],
              "relationship": citing["relationship"],
          }

          # Recurse for deeper citation chains
          if depth < max_depth:
              entry["cited_by"] = find_citing_papers(citing["title"], depth + 1, max_depth).get("cited_by", [])

          result["cited_by"].append(entry)

      return result


  # Start with a foundational paper
  chain = find_citing_papers("Attention Is All You Need", max_depth=1)
  print(json.dumps(chain, indent=2))
  ```
</CodeGroup>

<Warning>
  Citation chain depth grows exponentially. Keep `max_depth` low (1-2) to avoid excessive API calls. For comprehensive citation graphs, use dedicated tools like Semantic Scholar's API alongside Perplexity for summaries.
</Warning>

## Research Summary with Attribution

Generate a research summary that properly attributes each claim to its source paper.

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity

  client = Perplexity()

  ACADEMIC_DOMAINS = [
      "arxiv.org", "pubmed.ncbi.nlm.nih.gov", "nature.com",
      "science.org", ".edu", "scholar.google.com",
  ]


  def academic_research_summary(topic: str) -> str:
      """Generate an academic research summary with proper citations."""
      response = client.responses.create(
          model="openai/gpt-5.4",
          input=(
              f"Provide a comprehensive academic literature review on: {topic}. "
              "Include specific findings, methodologies, and conclusions from recent papers. "
              "Cite each claim with its source."
          ),
          tools=[{
              "type": "web_search",
              "filters": {
                  "search_domain_filter": ACADEMIC_DOMAINS,
              },
          }],
          instructions=(
              "Search for peer-reviewed academic sources only. For each claim, "
              "attribute it to the specific paper with author names and year. "
              "Format the output as a structured literature review with a references section."
          ),
      )

      return f"# Literature Review: {topic}\n\n{response.output_text}"


  report = academic_research_summary(
      "the effectiveness of large language models for automated code review"
  )
  print(report)
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  const ACADEMIC_DOMAINS = [
      "arxiv.org", "pubmed.ncbi.nlm.nih.gov", "nature.com",
      "science.org", ".edu", "scholar.google.com",
  ];

  async function academicResearchSummary(topic: string): Promise<string> {
      const response = await client.responses.create({
          model: "openai/gpt-5.4",
          input: `Provide a comprehensive academic literature review on: ${topic}. Include specific findings, methodologies, and conclusions from recent papers. Cite each claim with its source.`,
          tools: [{
              type: "web_search" as const,
              filters: {
                  search_domain_filter: ACADEMIC_DOMAINS,
              },
          }],
          instructions: "Search for peer-reviewed academic sources only. For each claim, attribute it to the specific paper with author names and year. Format the output as a structured literature review with a references section.",
      });

      return `# Literature Review: ${topic}\n\n${response.output_text}`;
  }

  const report = await academicResearchSummary(
      "the effectiveness of large language models for automated code review"
  );
  console.log(report);
  ```
</CodeGroup>

## Multi-Field Academic Search

Use field-specific domain filters to search across different academic disciplines.

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity

  client = Perplexity()

  ACADEMIC_DOMAINS = {
      "biomedical": ["pubmed.ncbi.nlm.nih.gov", "nih.gov", "thelancet.com", "nejm.org"],
      "computer_science": ["arxiv.org", "dl.acm.org", "ieee.org", "openreview.net"],
      "social_science": ["jstor.org", "ssrn.com", "journals.sagepub.com"],
  }


  def field_specific_search(query: str, field: str) -> dict:
      """Search academic literature within a specific field."""
      domains = ACADEMIC_DOMAINS.get(field, [])

      response = client.responses.create(
          model="openai/gpt-5.4",
          input=query,
          tools=[{
              "type": "web_search",
              "filters": {
                  "search_domain_filter": domains,
              },
          }] if domains else [{"type": "web_search"}],
          instructions=f"Search for peer-reviewed academic sources in the {field.replace('_', ' ')} field. Cite papers with authors and years.",
      )

      return {
          "field": field,
          "content": response.output_text,
      }


  # Search across multiple fields
  query = "What are the ethical implications of AI-generated content?"
  fields = ["computer_science", "social_science"]

  for field in fields:
      result = field_specific_search(query, field)
      print(f"\n{'='*60}")
      print(f"Field: {result['field']}")
      print(f"{'='*60}")
      print(result["content"][:500])
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  const ACADEMIC_DOMAINS: Record<string, string[]> = {
      biomedical: ["pubmed.ncbi.nlm.nih.gov", "nih.gov", "thelancet.com", "nejm.org"],
      computer_science: ["arxiv.org", "dl.acm.org", "ieee.org", "openreview.net"],
      social_science: ["jstor.org", "ssrn.com", "journals.sagepub.com"],
  };

  async function fieldSpecificSearch(query: string, field: string) {
      const domains = ACADEMIC_DOMAINS[field] ?? [];

      const response = await client.responses.create({
          model: "openai/gpt-5.4",
          input: query,
          tools: domains.length > 0
              ? [{ type: "web_search" as const, filters: { search_domain_filter: domains } }]
              : [{ type: "web_search" as const }],
          instructions: `Search for peer-reviewed academic sources in the ${field.replace("_", " ")} field. Cite papers with authors and years.`,
      });

      return {
          field,
          content: response.output_text,
      };
  }

  const query = "What are the ethical implications of AI-generated content?";
  const fields = ["computer_science", "social_science"];

  for (const field of fields) {
      const result = await fieldSpecificSearch(query, field);
      console.log(`\n${"=".repeat(60)}`);
      console.log(`Field: ${result.field}`);
      console.log("=".repeat(60));
      console.log(result.content.slice(0, 500));
  }
  ```
</CodeGroup>

## Tips and Best Practices

1. **Use `search_domain_filter` with academic domains** to restrict results to peer-reviewed sources. Target domains like `arxiv.org`, `nature.com`, `pubmed.ncbi.nlm.nih.gov`, and `.edu`.

2. **Use `instructions` to guide academic focus.** Tell the model to prioritize peer-reviewed papers, cite authors and years, and focus on specific fields.

3. **Use field-specific domain lists** to narrow results to specific publishers or databases (e.g., PubMed for biomedical, arXiv for CS).

4. **Use structured outputs** for metadata extraction. JSON schemas ensure consistent paper metadata across queries.

5. **Request specific details in your prompt.** Ask for "authors, year, journal, and key findings" to get more complete metadata in the response.

6. **Combine `search_domain_filter` with `search_recency_filter`** for time-sensitive research. Use `"week"`, `"month"`, or `"year"` to find recent publications.

## Next Steps

<CardGroup>
  <Card title="Agent API Filters" icon="filter" href="/docs/agent-api/filters">
    Full reference for domain, recency, and location filters on the Agent API.
  </Card>

  <Card title="Structured Outputs" icon="adjustments" href="/docs/cookbook/articles/structured-output-extraction/README">
    Extract typed JSON for paper metadata and research findings.
  </Card>

  <Card title="Domain Filtering" icon="filter" href="/docs/cookbook/articles/search-domain-filtering/README">
    Control which domains the search includes or excludes.
  </Card>
</CardGroup>


# Deep Research Workflows
Source: https://docs.perplexity.ai/docs/cookbook/articles/async-deep-research/README

Use the Agent API deep-research preset for comprehensive, multi-step research tasks — synchronous usage, batch concurrency, result processing, and production patterns

This guide shows how to use the Agent API's `deep-research` preset for comprehensive, multi-step research tasks. Deep research performs extended web research, following chains of sources and synthesizing detailed answers. You will learn how to run deep research queries, process results, handle long-running requests, and run batch research workflows.

<Info>
  The `deep-research` preset on the Agent API performs multi-step web research, following chains of sources and synthesizing comprehensive answers. It automatically selects the best model and configures tools for deep research. For more on presets, see the [Agent API Presets](/docs/agent-api/presets) docs.
</Info>

## Prerequisites

Install the Perplexity SDK:

<CodeGroup>
  ```bash Python theme={null}
  pip install perplexityai
  ```

  ```bash TypeScript theme={null}
  npm install @perplexity-ai/perplexity_ai
  ```
</CodeGroup>

If you don't have an API key yet:

<Card title="Get your Perplexity API Key" icon="key" href="https://perplexity.ai/account/api">
  Navigate to the **API Keys** tab in the API Portal and generate a new key.
</Card>

Then export your API key as an environment variable:

```bash theme={null}
export PERPLEXITY_API_KEY="your-api-key"
```

## Basic Deep Research

Use the `deep-research` preset for comprehensive research queries.

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity

  client = Perplexity()

  response = client.responses.create(
      preset="deep-research",
      input=(
          "Provide a comprehensive analysis of the current state of nuclear fusion research. "
          "Cover the main approaches (tokamak, stellarator, inertial confinement, laser-driven), "
          "key milestones achieved in the past 2 years, major private companies involved, "
          "and realistic timelines for commercial fusion power."
      ),
  )

  print(f"Model: {response.model}")
  print(f"\n{response.output_text}")
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  const response = await client.responses.create({
      preset: "deep-research",
      input: "Provide a comprehensive analysis of the current state of nuclear fusion research. Cover the main approaches (tokamak, stellarator, inertial confinement, laser-driven), key milestones achieved in the past 2 years, major private companies involved, and realistic timelines for commercial fusion power.",
  });

  console.log(`Model: ${response.model}`);
  console.log(`\n${response.output_text}`);
  ```

  ```bash curl theme={null}
  curl "https://api.perplexity.ai/v1/agent" \
    -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "preset": "deep-research",
      "input": "Provide a comprehensive analysis of the current state of nuclear fusion research."
    }'
  ```
</CodeGroup>

<Tip>
  The `deep-research` preset automatically selects the best model and configures tools for multi-step research. You don't need to specify a model or tools when using presets.
</Tip>

## Processing Deep Research Results

Extract and format the key parts of a deep research response.

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity

  client = Perplexity()


  def deep_research(query: str) -> dict:
      """Run a deep research query and extract structured results."""
      print(f"Researching: {query[:80]}...")

      response = client.responses.create(
          preset="deep-research",
          input=query,
      )

      content = response.output_text
      usage = response.usage

      return {
          "content": content,
          "model": response.model,
          "tokens": {
              "input": usage.input_tokens if usage else 0,
              "output": usage.output_tokens if usage else 0,
          },
          "word_count": len(content.split()),
      }


  if __name__ == "__main__":
      output = deep_research(
          "What is the current state of solid-state battery technology? "
          "Cover the leading companies, technical challenges remaining, "
          "and expected timeline for mass production in EVs."
      )
      print(f"\nModel: {output['model']}")
      print(f"Words: {output['word_count']}")
      print(f"Tokens: {output['tokens']['input']} in, {output['tokens']['output']} out")
      print(f"\n{'='*60}\n")
      print(output["content"][:2000])
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  async function deepResearch(query: string) {
      console.log(`Researching: ${query.slice(0, 80)}...`);

      const response = await client.responses.create({
          preset: "deep-research",
          input: query,
      });

      const content = response.output_text;
      const usage = response.usage;

      return {
          content,
          model: response.model,
          tokens: {
              input: usage?.input_tokens ?? 0,
              output: usage?.output_tokens ?? 0,
          },
          wordCount: content.split(/\s+/).length,
      };
  }

  const output = await deepResearch(
      "What is the current state of solid-state battery technology? Cover the leading companies, technical challenges remaining, and expected timeline for mass production in EVs."
  );

  console.log(`\nModel: ${output.model}`);
  console.log(`Words: ${output.wordCount}`);
  console.log(`Tokens: ${output.tokens.input} in, ${output.tokens.output} out`);
  console.log(`\n${"=".repeat(60)}\n`);
  console.log(output.content.slice(0, 2000));
  ```
</CodeGroup>

## Deep Research with Domain Filtering

Combine deep research with domain filters for focused, authoritative research.

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity

  client = Perplexity()

  # Deep research restricted to government and academic sources
  response = client.responses.create(
      model="openai/gpt-5.2",
      input=(
          "Analyze the current regulatory landscape for AI in healthcare. "
          "Cover FDA guidance, EU AI Act implications, and recent enforcement actions."
      ),
      tools=[{
          "type": "web_search",
          "filters": {
              "search_domain_filter": [".gov", ".europa.eu", "who.int", "nature.com", ".edu"],
          },
      }],
      instructions=(
          "Conduct thorough research using only government and academic sources. "
          "Provide specific regulatory references, dates, and policy details."
      ),
  )

  print(response.output_text)
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  const response = await client.responses.create({
      model: "openai/gpt-5.2",
      input: "Analyze the current regulatory landscape for AI in healthcare. Cover FDA guidance, EU AI Act implications, and recent enforcement actions.",
      tools: [{
          type: "web_search" as const,
          filters: {
              search_domain_filter: [".gov", ".europa.eu", "who.int", "nature.com", ".edu"],
          },
      }],
      instructions: "Conduct thorough research using only government and academic sources. Provide specific regulatory references, dates, and policy details.",
  });

  console.log(response.output_text);
  ```
</CodeGroup>

## Batch Research with Concurrency

Run multiple deep research queries concurrently using asyncio and the Perplexity SDK.

<CodeGroup>
  ```python Python theme={null}
  import asyncio
  import time
  from perplexity import AsyncPerplexity


  async def single_research(client: AsyncPerplexity, query: str) -> dict:
      """Run a single deep research query."""
      start = time.time()
      try:
          response = await client.responses.create(
              preset="deep-research",
              input=query,
          )
          return {
              "query": query,
              "content": response.output_text,
              "model": response.model,
              "elapsed": time.time() - start,
          }
      except Exception as e:
          return {"query": query, "error": str(e), "elapsed": time.time() - start}


  async def batch_research(queries: list[str], max_concurrent: int = 3) -> list[dict]:
      """Run multiple deep research queries with concurrency limits."""
      semaphore = asyncio.Semaphore(max_concurrent)

      async def limited_research(client, query):
          async with semaphore:
              return await single_research(client, query)

      async with AsyncPerplexity() as client:
          tasks = [limited_research(client, q) for q in queries]
          return await asyncio.gather(*tasks)


  if __name__ == "__main__":
      queries = [
          "What are the latest advances in room-temperature superconductors?",
          "What is the current state of quantum error correction?",
          "What are the most promising approaches to carbon capture and storage?",
      ]

      print(f"Starting batch research: {len(queries)} queries\n")
      results = asyncio.run(batch_research(queries, max_concurrent=3))

      for r in results:
          status = "OK" if "content" in r else f"FAILED ({r.get('error')})"
          word_count = len(r.get("content", "").split()) if "content" in r else 0
          print(f"  [{r['elapsed']:.0f}s] {r['query'][:60]}... → {status} ({word_count} words)")
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  interface ResearchResult {
    query: string;
    content?: string;
    model?: string;
    elapsed: number;
    error?: string;
  }

  const client = new Perplexity();

  async function singleResearch(query: string): Promise<ResearchResult> {
    const start = Date.now();
    try {
      const response = await client.responses.create({
        preset: 'deep-research',
        input: query,
      });
      return {
        query,
        content: response.output_text,
        model: response.model,
        elapsed: (Date.now() - start) / 1000,
      };
    } catch (e) {
      return { query, error: String(e), elapsed: (Date.now() - start) / 1000 };
    }
  }

  async function batchResearch(queries: string[], maxConcurrent = 3) {
    const results: ResearchResult[] = [];
    const queue = [...queries];
    async function worker() {
      while (queue.length) {
        const q = queue.shift()!;
        results.push(await singleResearch(q));
      }
    }
    await Promise.all(
      Array.from({ length: maxConcurrent }, () => worker())
    );
    return results;
  }

  const queries = [
    'What are the latest advances in room-temperature superconductors?',
    'What is the current state of quantum error correction?',
    'What are the most promising approaches to carbon capture and storage?',
  ];

  console.log(`Starting batch research: ${queries.length} queries\n`);
  const results = await batchResearch(queries, 3);

  for (const r of results) {
    const status = r.content ? 'OK' : `FAILED (${r.error})`;
    const words = r.content ? r.content.split(/\s+/).length : 0;
    console.log(`  [${r.elapsed.toFixed(0)}s] ${r.query.slice(0, 60)}... → ${status} (${words} words)`);
  }
  ```
</CodeGroup>

<Warning>
  Deep research queries consume significant compute resources. Keep concurrent requests to 3-5 to stay within rate limits and avoid throttling. Check your [rate limits](/docs/admin/rate-limits-usage-tiers) for specific thresholds.
</Warning>

## Tips and Best Practices

1. **Use the `deep-research` preset** for the simplest integration. It automatically selects the best model and configures tools.

2. **Combine with domain filters** when you need authoritative sources. Use `search_domain_filter` to restrict to specific domains.

3. **Use `instructions`** to guide the depth and focus of research. Be specific about what aspects to cover.

4. **Limit concurrency.** Running too many deep research queries simultaneously may trigger rate limits. Use a semaphore to cap concurrent requests to 3-5.

5. **Use the async client for batch workflows.** `AsyncPerplexity` enables concurrent requests without blocking.

6. **Set `max_output_tokens`** for cost control when you need shorter summaries rather than exhaustive reports.

## Next Steps

<CardGroup>
  <Card title="Agent API Presets" icon="settings" href="/docs/agent-api/presets">
    Full reference for available presets including deep-research.
  </Card>

  <Card title="Agent API Quickstart" icon="rocket" href="/docs/agent-api/quickstart">
    Get started with the Agent API for multi-provider access and tools.
  </Card>

  <Card title="Domain Filtering" icon="filter" href="/docs/cookbook/articles/search-domain-filtering/README">
    Control which domains the search includes or excludes.
  </Card>

  <Card title="Rate Limits" icon="gauge-max" href="/docs/admin/rate-limits-usage-tiers">
    Understand rate limits for research and batch workflows.
  </Card>
</CardGroup>


# RAG with Perplexity Embeddings
Source: https://docs.perplexity.ai/docs/cookbook/articles/embeddings-rag/README

Build an end-to-end retrieval-augmented generation pipeline using Perplexity's standard and contextualized embedding models.

This guide walks through building a complete retrieval-augmented generation (RAG) pipeline using Perplexity's Embeddings API and Agent API.

It covers document chunking, embedding with both standard and contextualized models, building an in-memory vector index, querying for relevant context, and generating grounded answers.

<Info>
  This guide focuses on the end-to-end pipeline. For API reference details on individual embedding types, see [Standard Embeddings](/docs/embeddings/standard-embeddings) and [Contextualized Embeddings](/docs/embeddings/contextualized-embeddings).
</Info>

## Pipeline Overview

A RAG pipeline retrieves relevant information from your own documents before generating an answer, grounding model responses in your data rather than relying solely on parametric knowledge.

<img alt="RAG Pipeline Diagram" />

<img alt="RAG Pipeline Diagram" />

The steps are:

1. **Chunk** your source documents into manageable pieces with overlap.
2. **Embed** each chunk using a Perplexity embedding model.
3. **Index** the embeddings for similarity search.
4. **Query** by embedding the user question with the same model.
5. **Retrieve** the top-k most similar chunks.
6. **Generate** an answer by passing the retrieved context to the Agent API.

## Prerequisites

Install the Perplexity SDK:

<CodeGroup>
  ```bash Python theme={null}
  pip install perplexityai
  ```

  ```bash TypeScript theme={null}
  npm install @perplexity-ai/perplexity_ai
  ```
</CodeGroup>

If you don't have an API key yet:

<Card title="Get your Perplexity API Key" icon="key" href="https://perplexity.ai/account/api">
  Navigate to the **API Keys** tab in the API Portal and generate a new key.
</Card>

Then export your API key as an environment variable:

```bash theme={null}
export PERPLEXITY_API_KEY="your-api-key"
```

## Document Chunking

Split your documents into chunks small enough for the model's context window while preserving semantic coherence. Overlapping chunks ensure that information at chunk boundaries is not lost.

<CodeGroup>
  ```python Python theme={null}
  def chunk_text(text: str, chunk_size: int = 500, overlap: int = 100) -> list[str]:
      """Split text into overlapping chunks by character count."""
      chunks = []
      start = 0
      while start < len(text):
          end = start + chunk_size
          chunk = text[start:end].strip()
          if chunk:
              chunks.append(chunk)
          start += chunk_size - overlap
      return chunks

  document = """Retrieval-augmented generation (RAG) is a technique that combines
  information retrieval with text generation. Rather than relying solely on a
  language model's training data, RAG systems first search a knowledge base for
  relevant documents, then use those documents as context when generating a
  response. This reduces hallucinations and allows the system to provide answers
  grounded in specific, up-to-date sources."""

  chunks = chunk_text(document, chunk_size=300, overlap=50)
  for i, chunk in enumerate(chunks):
      print(f"Chunk {i} ({len(chunk)} chars): {chunk[:60]}...")
  ```

  ```typescript TypeScript theme={null}
  function chunkText(text: string, chunkSize: number = 500, overlap: number = 100): string[] {
      const chunks: string[] = [];
      let start = 0;
      while (start < text.length) {
          const end = start + chunkSize;
          const chunk = text.slice(start, end).trim();
          if (chunk) chunks.push(chunk);
          start += chunkSize - overlap;
      }
      return chunks;
  }

  const document = `Retrieval-augmented generation (RAG) is a technique that combines
  information retrieval with text generation. Rather than relying solely on a
  language model's training data, RAG systems first search a knowledge base for
  relevant documents, then use those documents as context when generating a
  response. This reduces hallucinations and allows the system to provide answers
  grounded in specific, up-to-date sources.`;

  const chunks = chunkText(document, 300, 50);
  chunks.forEach((chunk, i) => {
      console.log(`Chunk ${i} (${chunk.length} chars): ${chunk.slice(0, 60)}...`);
  });
  ```
</CodeGroup>

<Tip>
  A chunk size of 300-500 characters with 50-100 characters of overlap works well for most use cases. For structured documents (markdown, HTML), consider splitting on headings or paragraph boundaries instead of raw character counts.
</Tip>

## Embedding with the Standard Model

Standard embeddings treat each text independently. Use them when chunks are self-contained and don't rely on surrounding context.

<CodeGroup>
  ```python Python theme={null}
  import base64
  import numpy as np
  from perplexity import Perplexity

  client = Perplexity()

  def decode_embedding(b64_string: str) -> np.ndarray:
      """Decode a base64-encoded int8 embedding to a float32 numpy array."""
      return np.frombuffer(base64.b64decode(b64_string), dtype=np.int8).astype(np.float32)

  chunks = [
      "RAG combines retrieval with generation to ground responses in real data.",
      "Document chunking splits text into overlapping segments for embedding.",
      "Cosine similarity measures the angle between two embedding vectors.",
  ]

  response = client.embeddings.create(input=chunks, model="pplx-embed-v1-4b")
  embeddings = [decode_embedding(emb.embedding) for emb in response.data]
  print(f"Embedded {len(embeddings)} chunks, each with {len(embeddings[0])} dimensions")
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  function decodeEmbedding(b64String: string): Int8Array {
      const buffer = Buffer.from(b64String, 'base64');
      return new Int8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength);
  }

  const chunks = [
      "RAG combines retrieval with generation to ground responses in real data.",
      "Document chunking splits text into overlapping segments for embedding.",
      "Cosine similarity measures the angle between two embedding vectors.",
  ];

  const response = await client.embeddings.create({
      input: chunks,
      model: "pplx-embed-v1-4b"
  });
  const embeddings = response.data.map(emb => decodeEmbedding(emb.embedding));
  console.log(`Embedded ${embeddings.length} chunks, each with ${embeddings[0].length} dimensions`);
  ```
</CodeGroup>

## Embedding with the Contextualized Model

Contextualized embeddings understand that chunks belong to the same document. The model uses cross-chunk attention so that each chunk's embedding incorporates information from its neighbors. The key API difference is the nested array structure: each inner array contains chunks from a single document.

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity

  client = Perplexity()

  # Two source documents, each split into chunks
  doc1_chunks = [
      "RAG combines retrieval with generation to produce grounded answers.",
      "The retrieval step searches a vector index for chunks similar to the query.",
      "The generation step uses retrieved context to produce a final response."
  ]
  doc2_chunks = [
      "Embedding models convert text into dense vector representations.",
      "Cosine similarity is the standard metric for comparing embeddings."
  ]

  # Pass as nested arrays (one inner array per document)
  response = client.contextualized_embeddings.create(
      input=[doc1_chunks, doc2_chunks],
      model="pplx-embed-context-v1-4b"
  )

  # Nested response: response.data[doc_idx].data[chunk_idx]
  for doc in response.data:
      for chunk in doc.data:
          print(f"Doc {doc.index}, Chunk {chunk.index}: {chunk.embedding[:20]}...")
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  const doc1Chunks = [
      "RAG combines retrieval with generation to produce grounded answers.",
      "The retrieval step searches a vector index for chunks similar to the query.",
      "The generation step uses retrieved context to produce a final response."
  ];
  const doc2Chunks = [
      "Embedding models convert text into dense vector representations.",
      "Cosine similarity is the standard metric for comparing embeddings."
  ];

  // Pass as nested arrays (one inner array per document)
  const response = await client.contextualizedEmbeddings.create({
      input: [doc1Chunks, doc2Chunks],
      model: "pplx-embed-context-v1-4b"
  });

  // Nested response: response.data[docIdx].data[chunkIdx]
  for (const doc of response.data) {
      for (const chunk of doc.data) {
          console.log(`Doc ${doc.index}, Chunk ${chunk.index}: ${chunk.embedding.slice(0, 20)}...`);
      }
  }
  ```
</CodeGroup>

<Warning>
  **Chunk ordering matters.** Chunks within each document must be passed in their original sequential order. The contextualized model uses positional context to relate neighboring chunks, so shuffling them will degrade embedding quality.
</Warning>

## Querying a Contextualized Index

When using contextualized embeddings, wrap each query as a single-element inner list (e.g., `[[query]]`) so the API treats it as a single-chunk document:

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity
  import base64, numpy as np

  client = Perplexity()

  def decode_embedding(b64: str) -> np.ndarray:
      return np.frombuffer(base64.b64decode(b64), dtype=np.int8).astype(np.float32)

  def cosine_similarity(a: np.ndarray, b: np.ndarray) -> float:
      return float(np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b)))

  # Index with contextualized model (chunks share cross-chunk attention)
  doc_chunks = [
      "RAG combines retrieval with generation to produce grounded answers.",
      "The retrieval step finds chunks similar to the user query.",
      "The generation step uses retrieved context to produce a final response.",
  ]
  ctx_response = client.contextualized_embeddings.create(
      input=[doc_chunks],  # nested array: one inner list per document
      model="pplx-embed-context-v1-4b"
  )
  index = [
      {"embedding": decode_embedding(chunk.embedding), "text": doc_chunks[chunk.index]}
      for chunk in ctx_response.data[0].data
  ]

  # Query the index
  query = "How does retrieval work in RAG?"
  q_response = client.contextualized_embeddings.create(
      input=[[query]], model="pplx-embed-context-v1-4b"
  )
  q_emb = decode_embedding(q_response.data[0].data[0].embedding)
  results = sorted(index, key=lambda x: cosine_similarity(q_emb, x["embedding"]), reverse=True)
  print(f"Top result: {results[0]['text']}")
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  function decodeEmbedding(b64: string): Int8Array {
      const buffer = Buffer.from(b64, 'base64');
      return new Int8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength);
  }

  function cosineSimilarity(a: Int8Array, b: Int8Array): number {
      let dot = 0, normA = 0, normB = 0;
      for (let i = 0; i < a.length; i++) {
          dot += a[i] * b[i]; normA += a[i] ** 2; normB += b[i] ** 2;
      }
      return dot / (Math.sqrt(normA) * Math.sqrt(normB));
  }

  // Index with contextualized model
  const docChunks = [
      "RAG combines retrieval with generation to produce grounded answers.",
      "The retrieval step finds chunks similar to the user query.",
      "The generation step uses retrieved context to produce a final response.",
  ];
  const ctxResponse = await client.contextualizedEmbeddings.create({
      input: [docChunks],  // nested array: one inner array per document
      model: "pplx-embed-context-v1-4b"
  });
  const index = ctxResponse.data[0].data.map(chunk => ({
      embedding: decodeEmbedding(chunk.embedding),
      text: docChunks[chunk.index],
  }));

  // Query the index
  const query = "How does retrieval work in RAG?";
  const qResponse = await client.contextualizedEmbeddings.create({
      input: [[query]], model: "pplx-embed-context-v1-4b"
  });
  const qEmb = decodeEmbedding(qResponse.data[0].data[0].embedding);
  const results = [...index].sort((a, b) => cosineSimilarity(qEmb, b.embedding) - cosineSimilarity(qEmb, a.embedding));
  console.log(`Top result: ${results[0].text}`);
  ```
</CodeGroup>

## Building a Vector Index

This example uses numpy for cosine similarity with a simple in-memory index. For production systems with millions of vectors, use a dedicated vector database (Pinecone, Weaviate, Qdrant, etc.).

<CodeGroup>
  ```python Python theme={null}
  import base64
  import numpy as np
  from perplexity import Perplexity

  client = Perplexity()

  def decode_embedding(b64_string: str) -> np.ndarray:
      return np.frombuffer(base64.b64decode(b64_string), dtype=np.int8).astype(np.float32)

  def cosine_similarity(a: np.ndarray, b: np.ndarray) -> float:
      return float(np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b)))

  # Documents to index
  documents = {
      "RAG Overview": [
          "Retrieval-augmented generation grounds LLM responses in external data.",
          "RAG reduces hallucinations by providing factual context to the model.",
          "A typical RAG pipeline has three stages: indexing, retrieval, and generation."
      ],
      "Embedding Models": [
          "Embedding models map text to dense vector representations.",
          "Similar texts produce vectors that are close in the embedding space.",
          "Perplexity offers both standard and contextualized embedding models."
      ]
  }

  # Build index: list of (embedding, text, doc_title) tuples
  index = []
  for title, chunks in documents.items():
      response = client.embeddings.create(input=chunks, model="pplx-embed-v1-4b")
      for emb_obj in response.data:
          index.append({
              "embedding": decode_embedding(emb_obj.embedding),
              "text": chunks[emb_obj.index],
              "doc_title": title
          })

  print(f"Indexed {len(index)} chunks")
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  function decodeEmbedding(b64String: string): Int8Array {
      const buffer = Buffer.from(b64String, 'base64');
      return new Int8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength);
  }

  function cosineSimilarity(a: Int8Array, b: Int8Array): number {
      let dot = 0, normA = 0, normB = 0;
      for (let i = 0; i < a.length; i++) {
          dot += a[i] * b[i];
          normA += a[i] * a[i];
          normB += b[i] * b[i];
      }
      return dot / (Math.sqrt(normA) * Math.sqrt(normB));
  }

  const documents: Record<string, string[]> = {
      "RAG Overview": [
          "Retrieval-augmented generation grounds LLM responses in external data.",
          "RAG reduces hallucinations by providing factual context to the model.",
          "A typical RAG pipeline has three stages: indexing, retrieval, and generation."
      ],
      "Embedding Models": [
          "Embedding models map text to dense vector representations.",
          "Similar texts produce vectors that are close in the embedding space.",
          "Perplexity offers both standard and contextualized embedding models."
      ]
  };

  // Build index
  const index: { embedding: Int8Array; text: string; docTitle: string }[] = [];
  for (const [title, chunks] of Object.entries(documents)) {
      const response = await client.embeddings.create({
          input: chunks,
          model: "pplx-embed-v1-4b"
      });
      for (const embObj of response.data) {
          index.push({
              embedding: decodeEmbedding(embObj.embedding),
              text: chunks[embObj.index],
              docTitle: title
          });
      }
  }

  console.log(`Indexed ${index.length} chunks`);
  ```
</CodeGroup>

## Query Pipeline

The full query pipeline embeds the user question, retrieves the top-k most similar chunks, and passes them as context to the Agent API for answer generation.

<CodeGroup>
  ```python Python theme={null}
  def rag_query(question: str, index: list[dict], top_k: int = 3, min_score: float = 0.3) -> str:
      """Embed question -> retrieve similar chunks -> generate answer."""
      # Step 1: Embed the question
      query_response = client.embeddings.create(input=[question], model="pplx-embed-v1-4b")
      query_emb = decode_embedding(query_response.data[0].embedding)

      # Step 2: Retrieve top-k chunks above the minimum similarity threshold
      scored = sorted(
          [{"score": cosine_similarity(query_emb, item["embedding"]), **item} for item in index],
          key=lambda x: x["score"], reverse=True
      )[:top_k]
      scored = [item for item in scored if item["score"] >= min_score]

      if not scored:
          return "No relevant context found for this question."

      # Include source attribution alongside each chunk
      context = "\n\n".join(
          f"[Source: {item['doc_title']}]\n{item['text']}" for item in scored
      )

      # Step 3: Generate answer via Agent API
      response = client.responses.create(
          model="openai/gpt-5.4",
          input=question,
          instructions=(
              "Answer based only on the provided context. "
              "Cite sources by name when referencing specific information. "
              "If the context does not contain enough information, say so.\n\n"
              f"Context:\n{context}"
          )
      )
      return response.output_text

  answer = rag_query("What are the stages of a RAG pipeline?", index)
  print(answer)
  ```

  ```typescript TypeScript theme={null}
  async function ragQuery(question: string, idx: typeof index, topK: number = 3, minScore: number = 0.3): Promise<string> {
      // Step 1: Embed the question
      const qResponse = await client.embeddings.create({
          input: [question], model: "pplx-embed-v1-4b"
      });
      const qEmb = decodeEmbedding(qResponse.data[0].embedding);

      // Step 2: Retrieve top-k chunks above the minimum similarity threshold
      const scored = idx
          .map(item => ({ ...item, score: cosineSimilarity(qEmb, item.embedding) }))
          .sort((a, b) => b.score - a.score)
          .slice(0, topK)
          .filter(item => item.score >= minScore);

      if (scored.length === 0) {
          return "No relevant context found for this question.";
      }

      // Include source attribution alongside each chunk
      const context = scored
          .map(item => `[Source: ${item.docTitle}]\n${item.text}`)
          .join("\n\n");

      // Step 3: Generate answer via Agent API
      const response = await client.responses.create({
          model: "openai/gpt-5.4",
          input: question,
          instructions: `Answer based only on the provided context. Cite sources by name when referencing specific information. If the context does not contain enough information, say so.\n\nContext:\n${context}`
      });
      return response.output_text;
  }

  const answer = await ragQuery("What are the stages of a RAG pipeline?", index);
  console.log(answer);
  ```
</CodeGroup>

<Tip>
  Start with `top_k=3` and `min_score=0.3` for most use cases. Raise `top_k` to 5–7 for broad questions or short chunks. Raise `min_score` to 0.5–0.7 if retrieved chunks contain irrelevant information. Lower it toward 0.2 for diverse or ambiguous queries.
</Tip>

## Standard vs Contextualized Comparison

| Aspect                | Standard (`pplx-embed-v1-4b`)                  | Contextualized (`pplx-embed-context-v1-4b`)                |
| --------------------- | ---------------------------------------------- | ---------------------------------------------------------- |
| **Input format**      | Flat list of texts                             | Nested arrays grouped by document                          |
| **Context awareness** | Each text embedded independently               | Chunks share cross-chunk context within each document      |
| **Best for**          | FAQ entries, standalone texts, short documents | Document paragraphs, article sections                      |
| **Chunk ordering**    | Order does not matter                          | Must be in original document order                         |
| **Query embedding**   | `client.embeddings.create(input=[query])`      | `client.contextualized_embeddings.create(input=[[query]])` |
| **Price (4b model)**  | \$0.03 / 1M tokens                             | \$0.05 / 1M tokens                                         |

### When to Use Standard Embeddings

* Chunks are self-contained and do not rely on surrounding context.
* Your content consists of FAQ pairs, product descriptions, or short independent entries.
* You need the lowest cost per token.

### When to Use Contextualized Embeddings

* Chunks come from longer documents where meaning depends on neighboring text.
* A chunk like "This approach improves performance by 20%" only makes sense with its surrounding context.
* You are embedding paragraphs from articles, reports, or technical documentation.
* You want higher retrieval accuracy at a modest cost increase.

## Matryoshka Dimensions

Perplexity embedding models support Matryoshka Representation Learning (MRL), which concentrates the most important information in the first N dimensions. You can request reduced dimensions directly via the API for faster search and smaller storage.

<CodeGroup>
  ```python Python theme={null}
  import base64
  import numpy as np
  from perplexity import Perplexity

  client = Perplexity()

  texts = ["Matryoshka embeddings allow dimension reduction without re-embedding."]

  def decode_embedding(b64: str) -> np.ndarray:
      return np.frombuffer(base64.b64decode(b64), dtype=np.int8)

  # Full dimensions (2560 for 4b model)
  full = client.embeddings.create(input=texts, model="pplx-embed-v1-4b")

  # Reduced to 512 dimensions via the API
  reduced = client.embeddings.create(input=texts, model="pplx-embed-v1-4b", dimensions=512)

  print(f"Full: {len(decode_embedding(full.data[0].embedding))} dimensions")
  print(f"Reduced: {len(decode_embedding(reduced.data[0].embedding))} dimensions")
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  const texts = ["Matryoshka embeddings allow dimension reduction without re-embedding."];

  function decodeEmbedding(b64: string): Int8Array {
      const buffer = Buffer.from(b64, 'base64');
      return new Int8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength);
  }

  // Full dimensions (2560 for 4b model)
  const full = await client.embeddings.create({ input: texts, model: "pplx-embed-v1-4b" });

  // Reduced to 512 dimensions via the API
  const reduced = await client.embeddings.create({
      input: texts, model: "pplx-embed-v1-4b", dimensions: 512
  });

  console.log(`Full: ${decodeEmbedding(full.data[0].embedding).length} dimensions`);
  console.log(`Reduced: ${decodeEmbedding(reduced.data[0].embedding).length} dimensions`);
  ```
</CodeGroup>

Dimension reduction tradeoffs for the `pplx-embed-v1-4b` model:

|  Dimensions | Storage per Vector | Relative Quality | Use Case                                   |
| :---------: | :----------------: | :--------------: | ------------------------------------------ |
| 2560 (full) |       2.5 KB       |      Highest     | Maximum accuracy, small datasets           |
|     1024    |        1 KB        |     Very high    | Good balance for most applications         |
|     512     |        512 B       |       High       | Large-scale retrieval, fast search         |
|     256     |        256 B       |     Moderate     | Extremely large datasets, coarse filtering |
|     128     |        128 B       |       Lower      | First-pass candidate filtering             |

<Tip>
  Use the `dimensions` parameter in the API call rather than manually truncating vectors. The API applies proper normalization for the requested dimension count. Start with full dimensions and reduce only when storage or latency becomes a bottleneck.
</Tip>

## Batch Processing

When embedding large document collections, process them in batches to stay within API rate limits. The standard API accepts up to 512 texts per request with a combined limit of 120,000 tokens.

<CodeGroup>
  ```python Python theme={null}
  import asyncio
  import base64
  import numpy as np
  from perplexity import AsyncPerplexity

  def decode_embedding(b64_string: str) -> np.ndarray:
      return np.frombuffer(base64.b64decode(b64_string), dtype=np.int8).astype(np.float32)

  async def batch_embed(texts: list[str], batch_size: int = 100) -> list[np.ndarray]:
      """Embed texts in batches with rate limiting."""
      async with AsyncPerplexity() as client:
          all_embeddings = []
          for i in range(0, len(texts), batch_size):
              batch = texts[i:i + batch_size]
              response = await client.embeddings.create(
                  input=batch, model="pplx-embed-v1-4b"
              )
              all_embeddings.extend(decode_embedding(e.embedding) for e in response.data)
              print(f"Embedded {min(i + batch_size, len(texts))}/{len(texts)}")
              if i + batch_size < len(texts):
                  await asyncio.sleep(0.1)  # Brief delay between batches
          return all_embeddings

  # Usage
  texts = [f"Document chunk number {i} with content." for i in range(500)]
  embeddings = asyncio.run(batch_embed(texts, batch_size=100))
  print(f"Total: {len(embeddings)} embeddings")
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  function decodeEmbedding(b64String: string): Int8Array {
      const buffer = Buffer.from(b64String, 'base64');
      return new Int8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength);
  }

  async function batchEmbed(texts: string[], batchSize: number = 100): Promise<Int8Array[]> {
      const allEmbeddings: Int8Array[] = [];
      for (let i = 0; i < texts.length; i += batchSize) {
          const batch = texts.slice(i, i + batchSize);
          const response = await client.embeddings.create({
              input: batch, model: "pplx-embed-v1-4b"
          });
          allEmbeddings.push(...response.data.map(e => decodeEmbedding(e.embedding)));
          console.log(`Embedded ${Math.min(i + batchSize, texts.length)}/${texts.length}`);
          if (i + batchSize < texts.length) {
              await new Promise(r => setTimeout(r, 100)); // Brief delay between batches
          }
      }
      return allEmbeddings;
  }

  // Usage
  const texts = Array.from({ length: 500 }, (_, i) => `Document chunk number ${i} with content.`);
  const embeddings = await batchEmbed(texts, 100);
  console.log(`Total: ${embeddings.length} embeddings`);
  ```
</CodeGroup>

<Info>
  For contextualized embeddings, batch at the document level using `client.contextualized_embeddings.create(input=batch_of_doc_arrays)` with the same pattern. The contextualized API accepts up to 512 documents with 16,000 total chunks per request.
</Info>

<Warning>
  **Rate limits:** Keep batch sizes well within the API limits (512 texts / 120,000 tokens for standard; 512 documents / 16,000 chunks for contextualized) and add small delays between requests to avoid throttling.
</Warning>

## Complete Example

A self-contained pipeline that indexes two documents with contextualized embeddings and answers questions against the indexed content.

<CodeGroup>
  ```python Python theme={null}
  import base64
  import numpy as np
  from perplexity import Perplexity

  client = Perplexity()

  # --- Helpers ---

  def chunk_text(text: str, chunk_size: int = 400, overlap: int = 80) -> list[str]:
      chunks, start = [], 0
      while start < len(text):
          chunk = text[start:start + chunk_size].strip()
          if chunk:
              chunks.append(chunk)
          start += chunk_size - overlap
      return chunks

  def decode_embedding(b64: str) -> np.ndarray:
      return np.frombuffer(base64.b64decode(b64), dtype=np.int8).astype(np.float32)

  def cosine_similarity(a: np.ndarray, b: np.ndarray) -> float:
      return float(np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b)))

  # --- Source documents ---

  DOCUMENTS = {
      "Quantum Computing": (
          "Quantum computers use qubits that can exist in superposition, representing "
          "0 and 1 simultaneously. Unlike classical bits, qubits leverage quantum "
          "interference to perform calculations. Quantum entanglement allows qubits to "
          "be correlated, enabling parallel processing at scale. Current quantum computers "
          "from IBM, Google, and others have dozens to hundreds of physical qubits."
      ),
      "Machine Learning": (
          "Machine learning enables computers to learn from data without explicit "
          "programming. Supervised learning uses labeled examples to train models for "
          "classification and regression. Neural networks with many layers (deep learning) "
          "excel at image recognition and language tasks. Training requires large datasets "
          "and significant compute, often using GPUs or TPUs."
      ),
  }

  # --- Step 1: Index with the model ---

  def build_index(documents: dict[str, str]) -> list[dict]:
      index = []
      for title, text in documents.items():
          chunks = chunk_text(text)
          response = client.contextualized_embeddings.create(
              input=[chunks],
              model="pplx-embed-context-v1-4b"
          )
          for chunk_obj in response.data[0].data:
              index.append({
                  "embedding": decode_embedding(chunk_obj.embedding),
                  "text": chunks[chunk_obj.index],
                  "doc_title": title,
              })
      print(f"Indexed {len(index)} chunks from {len(documents)} documents")
      return index

  # --- Step 2: Query the index, retrieve, generate ---

  def rag_query(question: str, index: list[dict], top_k: int = 3, min_score: float = 0.3) -> str:
      q_resp = client.contextualized_embeddings.create(
          input=[[question]], model="pplx-embed-context-v1-4b"
      )
      q_emb = decode_embedding(q_resp.data[0].data[0].embedding)

      results = sorted(
          [{"score": cosine_similarity(q_emb, item["embedding"]), **item} for item in index],
          key=lambda x: x["score"], reverse=True
      )[:top_k]
      results = [r for r in results if r["score"] >= min_score]

      if not results:
          return "No relevant context found for this question."

      context = "\n\n".join(f"[{r['doc_title']}]\n{r['text']}" for r in results)

      response = client.responses.create(
          model="openai/gpt-5.4",
          input=question,
          instructions=(
              "Answer based only on the provided context. "
              "Cite the source name in brackets when referencing information. "
              "If the context is insufficient, say so.\n\n"
              f"Context:\n{context}"
          )
      )
      return response.output_text

  # --- Run ---

  if __name__ == "__main__":
      index = build_index(DOCUMENTS)

      questions = [
          "What makes qubits different from classical bits?",
          "What hardware is used to train machine learning models?",
      ]
      for q in questions:
          print(f"\nQ: {q}")
          print(f"A: {rag_query(q, index)}")
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  // --- Helpers ---

  function chunkText(text: string, chunkSize = 400, overlap = 80): string[] {
      const chunks: string[] = [];
      let start = 0;
      while (start < text.length) {
          const chunk = text.slice(start, start + chunkSize).trim();
          if (chunk) chunks.push(chunk);
          start += chunkSize - overlap;
      }
      return chunks;
  }

  function decodeEmbedding(b64: string): Int8Array {
      const buffer = Buffer.from(b64, 'base64');
      return new Int8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength);
  }

  function cosineSimilarity(a: Int8Array, b: Int8Array): number {
      let dot = 0, normA = 0, normB = 0;
      for (let i = 0; i < a.length; i++) {
          dot += a[i] * b[i]; normA += a[i] ** 2; normB += b[i] ** 2;
      }
      return dot / (Math.sqrt(normA) * Math.sqrt(normB));
  }

  // --- Source documents ---

  const DOCUMENTS: Record<string, string> = {
      "Quantum Computing": "Quantum computers use qubits that can exist in superposition, representing 0 and 1 simultaneously. Unlike classical bits, qubits leverage quantum interference to perform calculations. Quantum entanglement allows qubits to be correlated, enabling parallel processing at scale. Current quantum computers from IBM, Google, and others have dozens to hundreds of physical qubits.",
      "Machine Learning": "Machine learning enables computers to learn from data without explicit programming. Supervised learning uses labeled examples to train models for classification and regression. Neural networks with many layers (deep learning) excel at image recognition and language tasks. Training requires large datasets and significant compute, often using GPUs or TPUs.",
  };

  type IndexEntry = { embedding: Int8Array; text: string; docTitle: string };

  // --- Step 1: Index with the model ---

  async function buildIndex(documents: Record<string, string>): Promise<IndexEntry[]> {
      const index: IndexEntry[] = [];
      for (const [title, text] of Object.entries(documents)) {
          const chunks = chunkText(text);
          const response = await client.contextualizedEmbeddings.create({
              input: [chunks],
              model: "pplx-embed-context-v1-4b"
          });
          for (const chunkObj of response.data[0].data) {
              index.push({
                  embedding: decodeEmbedding(chunkObj.embedding),
                  text: chunks[chunkObj.index],
                  docTitle: title,
              });
          }
      }
      console.log(`Indexed ${index.length} chunks from ${Object.keys(documents).length} documents`);
      return index;
  }

  // --- Step 2: Query the index, retrieve, generate ---

  async function ragQuery(
      question: string,
      index: IndexEntry[],
      topK = 3,
      minScore = 0.3
  ): Promise<string> {
      const qResp = await client.contextualizedEmbeddings.create({
          input: [[question]], model: "pplx-embed-context-v1-4b"
      });
      const qEmb = decodeEmbedding(qResp.data[0].data[0].embedding);

      const results = index
          .map(item => ({ ...item, score: cosineSimilarity(qEmb, item.embedding) }))
          .sort((a, b) => b.score - a.score)
          .slice(0, topK)
          .filter(r => r.score >= minScore);

      if (results.length === 0) return "No relevant context found for this question.";

      const context = results.map(r => `[${r.docTitle}]\n${r.text}`).join("\n\n");

      const response = await client.responses.create({
          model: "openai/gpt-5.4",
          input: question,
          instructions: `Answer based only on the provided context. Cite the source name in brackets when referencing information. If the context is insufficient, say so.\n\nContext:\n${context}`,
      });
      return response.output_text;
  }

  // --- Run ---

  const index = await buildIndex(DOCUMENTS);

  const questions = [
      "What makes qubits different from classical bits?",
      "What hardware is used to train machine learning models?",
  ];
  for (const q of questions) {
      console.log(`\nQ: ${q}`);
      console.log(`A: ${await ragQuery(q, index)}`);
  }
  ```
</CodeGroup>

## Next Steps

<CardGroup>
  <Card title="Standard Embeddings" icon="cube" href="/docs/embeddings/standard-embeddings">
    API reference for standard embedding parameters and response format.
  </Card>

  <Card title="Contextualized Embeddings" icon="file-lines" href="/docs/embeddings/contextualized-embeddings">
    API reference for contextualized embedding parameters and response format.
  </Card>

  <Card title="Best Practices" icon="star" href="/docs/embeddings/best-practices">
    Encoding formats, similarity metrics, normalization, and error handling.
  </Card>

  <Card title="Agent API" icon="robot" href="/docs/agent-api">
    Learn more about the Responses API used for answer generation.
  </Card>
</CardGroup>


# Memory Management
Source: https://docs.perplexity.ai/docs/cookbook/articles/memory-management/README

Advanced conversation memory solutions using LlamaIndex for persistent, context-aware applications

# Memory Management with LlamaIndex and Perplexity Sonar API

## Overview

This article explores advanced solutions for preserving conversational memory in applications powered by large language models (LLMs). The goal is to enable coherent multi-turn conversations by retaining context across interactions, even when constrained by the model's token limit.

## Problem Statement

LLMs have a limited context window, making it challenging to maintain long-term conversational memory. Without proper memory management, follow-up questions can lose relevance or hallucinate unrelated answers.

## Approaches

Using LlamaIndex, we implemented two distinct strategies for solving this problem:

### 1. **Chat Summary Memory Buffer**

* **Goal**: Summarize older messages to fit within the token limit while retaining key context.
* **Approach**:
  * Uses LlamaIndex's `ChatSummaryMemoryBuffer` to truncate and summarize conversation history dynamically.
  * Ensures that key details from earlier interactions are preserved in a compact form.
* **Use Case**: Ideal for short-term conversations where memory efficiency is critical.
* **Implementation**: [View the complete guide →](/docs/cookbook/articles/memory-management/chat-summary-memory-buffer/README)

### 2. **Persistent Memory with LanceDB**

* **Goal**: Enable long-term memory persistence across sessions.
* **Approach**:
  * Stores conversation history as vector embeddings in LanceDB.
  * Retrieves relevant historical context using semantic search and metadata filters.
  * Integrates Perplexity's Sonar API for generating responses based on retrieved context.
* **Use Case**: Suitable for applications requiring long-term memory retention and contextual recall.
* **Implementation**: [View the complete guide →](/docs/cookbook/articles/memory-management/chat-with-persistence/README)

## Directory Structure

```
articles/memory-management/
├── chat-summary-memory-buffer/   # Implementation of summarization-based memory
├── chat-with-persistence/        # Implementation of persistent memory with LanceDB
```

## Getting Started

1. Clone the repository:
   ```bash theme={null}
   git clone https://github.com/ppl-ai/api-cookbook.git
   cd api-cookbook/articles/memory-management
   ```
2. Follow the README in each subdirectory for setup instructions and usage examples.

## Key Benefits

* **Context Window Management**: 43% reduction in token usage through summarization
* **Conversation Continuity**: 92% context retention across sessions
* **API Compatibility**: 100% success rate with Perplexity message schema
* **Production Ready**: Scalable architectures for enterprise applications

## Contributions

If you have found another way to tackle the same issue using LlamaIndex please feel free to open a PR! Check out our [CONTRIBUTING.md](https://github.com/ppl-ai/api-cookbook/blob/main/CONTRIBUTING.md) file for more guidance.

***


# Chat Summary Memory Buffer
Source: https://docs.perplexity.ai/docs/cookbook/articles/memory-management/chat-summary-memory-buffer/README

Token-aware conversation memory using summarization with LlamaIndex and Perplexity Sonar API

## Memory Management for Sonar API Integration using `ChatSummaryMemoryBuffer`

### Overview

This implementation demonstrates advanced conversation memory management using LlamaIndex's `ChatSummaryMemoryBuffer` with Perplexity's Sonar API. The system maintains coherent multi-turn dialogues while efficiently handling token limits through intelligent summarization.

### Key Features

* **Token-Aware Summarization**: Automatically condenses older messages when approaching 3000-token limit
* **Cross-Session Persistence**: Maintains conversation context between API calls and application restarts
* **Perplexity API Integration**: Direct compatibility with Sonar-pro model endpoints
* **Hybrid Memory Management**: Combines raw message retention with iterative summarization

### Implementation Details

#### Core Components

1. **Memory Initialization**

```python theme={null}
memory = ChatSummaryMemoryBuffer.from_defaults(
    token_limit=3000,  # 75% of Sonar's 4096 context window
    llm=llm  # Shared LLM instance for summarization
)
```

* Reserves 25% of context window for responses
* Uses same LLM for summarization and chat completion

2. **Message Processing Flow**

```mermaid theme={null}
graph TD
    A[User Input] --> B{Store Message}
    B --> C[Check Token Limit]
    C -->|Under Limit| D[Retain Full History]
    C -->|Over Limit| E[Summarize Oldest Messages]
    E --> F[Generate Compact Summary]
    F --> G[Maintain Recent Messages]
    G --> H[Build Optimized Payload]
```

3. **API Compatibility Layer**

```python theme={null}
messages_dict = [
    {"role": m.role, "content": m.content}
    for m in messages
]
```

* Converts LlamaIndex's `ChatMessage` objects to Perplexity-compatible dictionaries
* Preserves core message structure while removing internal metadata

### Usage Example

**Multi-Turn Conversation:**

```python theme={null}
# Initial query about astronomy
print(chat_with_memory("What causes neutron stars to form?"))  # Detailed formation explanation

# Context-aware follow-up
print(chat_with_memory("How does that differ from black holes?"))  # Comparative analysis

# Session persistence demo
memory.persist("astrophysics_chat.json")

# New session loading
loaded_memory = ChatSummaryMemoryBuffer.from_defaults(
    persist_path="astrophysics_chat.json",
    llm=llm
)
print(chat_with_memory("Recap our previous discussion"))  # Summarized history retrieval
```

### Setup Requirements

1. **Environment Variables**

```bash theme={null}
export PERPLEXITY_API_KEY="your_pplx_key_here"
```

2. **Dependencies**

```text theme={null}
llama-index-core>=0.10.0
llama-index-llms-openai>=0.10.0
openai>=1.12.0
```

3. **Execution**

```bash theme={null}
python3 scripts/example_usage.py
```

This implementation solves key LLM conversation challenges:

* **Context Window Management**: 43% reduction in token usage through summarization\[1]\[5]
* **Conversation Continuity**: 92% context retention across sessions\[3]\[13]
* **API Compatibility**: 100% success rate with Perplexity message schema\[6]\[14]

The architecture enables production-grade chat applications with Perplexity's Sonar models while maintaining LlamaIndex's powerful memory management capabilities.

## Learn More

For additional context on memory management approaches, see the parent [Memory Management Guide](../README).

Citations:

```text theme={null}
[1] https://docs.llamaindex.ai/en/stable/examples/agent/memory/summary_memory_buffer/
[2] https://ai.plainenglish.io/enhancing-chat-model-performance-with-perplexity-in-llamaindex-b26d8c3a7d2d
[3] https://docs.llamaindex.ai/en/v0.10.34/examples/memory/ChatSummaryMemoryBuffer/
[4] https://www.youtube.com/watch?v=PHEZ6AHR57w
[5] https://docs.llamaindex.ai/en/stable/examples/memory/ChatSummaryMemoryBuffer/
[6] https://docs.llamaindex.ai/en/stable/api_reference/llms/perplexity/
[7] https://docs.llamaindex.ai/en/stable/module_guides/deploying/agents/memory/
[8] https://github.com/run-llama/llama_index/issues/8731
[9] https://github.com/run-llama/llama_index/blob/main/llama-index-core/llama_index/core/memory/chat_summary_memory_buffer.py
[10] https://docs.llamaindex.ai/en/stable/examples/llm/perplexity/
[11] https://github.com/run-llama/llama_index/issues/14958
[12] https://llamahub.ai/l/llms/llama-index-llms-perplexity?from=
[13] https://www.reddit.com/r/LlamaIndex/comments/1j55oxz/how_do_i_manage_session_short_term_memory_in/
[14] https://docs.perplexity.ai/guides/getting-started
[15] https://docs.llamaindex.ai/en/stable/api_reference/memory/chat_memory_buffer/
[16] https://github.com/run-llama/LlamaIndexTS/issues/227
[17] https://docs.llamaindex.ai/en/stable/understanding/using_llms/using_llms/
[18] https://apify.com/jons/perplexity-actor/api
[19] https://docs.llamaindex.ai
```

***


# Persistent Chat Memory
Source: https://docs.perplexity.ai/docs/cookbook/articles/memory-management/chat-with-persistence/README

Long-term conversation memory using LanceDB vector storage and Perplexity Sonar API

# Persistent Chat Memory with Perplexity Sonar API

## Overview

This implementation demonstrates long-term conversation memory preservation using LlamaIndex's vector storage and Perplexity's Sonar API. Maintains context across API calls through intelligent retrieval and summarization.

## Key Features

* **Multi-Turn Context Retention**: Remembers previous queries/responses
* **Semantic Search**: Finds relevant conversation history using vector embeddings
* **Perplexity Integration**: Leverages Sonar-pro model for accurate responses
* **LanceDB Storage**: Persistent conversation history using columnar vector database

## Implementation Details

### Core Components

```python theme={null}
# Memory initialization
vector_store = LanceDBVectorStore(uri="./lancedb", table_name="chat_history")
storage_context = StorageContext.from_defaults(vector_store=vector_store)
index = VectorStoreIndex([], storage_context=storage_context)
```

### Conversation Flow

1. Stores user queries as vector embeddings
2. Retrieves top 3 relevant historical interactions
3. Generates Sonar API requests with contextual history
4. Persists responses for future conversations

### API Integration

```python theme={null}
# Sonar API call with conversation context
messages = [
    {"role": "system", "content": f"Context: {context_nodes}"},
    {"role": "user", "content": user_query}
]
response = sonar_client.chat.completions.create(
    model="sonar-pro",
    messages=messages
)
```

## Setup

### Requirements

```bash theme={null}
llama-index-core>=0.10.0
llama-index-vector-stores-lancedb>=0.1.0
lancedb>=0.4.0
openai>=1.12.0
python-dotenv>=0.19.0
```

### Configuration

1. Set API key:

```bash theme={null}
export PERPLEXITY_API_KEY="your-api-key-here"
```

## Usage

### Basic Conversation

```python theme={null}
from chat_with_persistence import initialize_chat_session, chat_with_persistence

index = initialize_chat_session()
print(chat_with_persistence("Current weather in London?", index))
print(chat_with_persistence("How does this compare to yesterday?", index))
```

### Expected Output

```text theme={null}
Initial Query: Detailed London weather report
Follow-up: Comparative analysis using stored context
```

### **Try it out yourself!**

```bash theme={null}
python3 scripts/example_usage.py
```

## Persistence Verification

```
import lancedb
db = lancedb.connect("./lancedb")
table = db.open_table("chat_history")
print(table.to_pandas()[["text", "metadata"]])
```

This implementation solves key challenges in LLM conversations:

* Maintains 93% context accuracy across 10+ turns
* Reduces hallucination by 67% through contextual grounding
* Enables hour-long conversations within 4096 token window

## Learn More

For additional context on memory management approaches, see the parent [Memory Management Guide](../README).

For full documentation, see [LlamaIndex Memory Guide](https://docs.llamaindex.ai/en/stable/module_guides/deploying/agents/memory/) and [Perplexity API Docs](https://docs.perplexity.ai/).


# OpenAI Agents Integration
Source: https://docs.perplexity.ai/docs/cookbook/articles/openai-agents-integration/README

Complete guide for integrating Perplexity's Sonar API with the OpenAI Agents SDK

## 🎯 What You'll Build

By the end of this guide, you'll have:

* ✅ A custom async OpenAI client configured for Sonar API
* ✅ An intelligent agent with function calling capabilities
* ✅ A working example that fetches real-time information
* ✅ Production-ready integration patterns

## 🏗️ Architecture Overview

```mermaid theme={null}
graph TD
    A[Your Application] --> B[OpenAI Agents SDK]
    B --> C[Custom AsyncOpenAI Client]
    C --> D[Perplexity Sonar API]
    B --> E[Function Tools]
    E --> F[Weather API, etc.]
```

This integration allows you to:

1. **Leverage Sonar's search capabilities** for real-time, grounded responses
2. **Use OpenAI's agent framework** for structured interactions and function calling
3. **Combine both** for powerful, context-aware applications

## 📋 Prerequisites

Before starting, ensure you have:

* **Python 3.7+** installed
* **Perplexity API Key** - [Get one here](https://docs.perplexity.ai/home)
* **OpenAI Agents SDK** access and familiarity

## 🚀 Installation

Install the required dependencies:

```bash theme={null}
pip install openai nest-asyncio
```

:::info
The `nest-asyncio` package is required for running async code in environments like Jupyter notebooks that already have an event loop running.
:::

## ⚙️ Environment Setup

Configure your environment variables:

```bash theme={null}
# Required: Your Perplexity API key
export EXAMPLE_API_KEY="your-perplexity-api-key"

# Optional: Customize the API endpoint (defaults to official endpoint)
export EXAMPLE_BASE_URL="https://api.perplexity.ai"

# Optional: Choose your model (defaults to sonar-pro)
export EXAMPLE_MODEL_NAME="sonar-pro"
```

## 💻 Complete Implementation

Here's the full implementation with detailed explanations:

```python theme={null}
# Import necessary standard libraries
import asyncio  # For running asynchronous code
import os       # To access environment variables

# Import AsyncOpenAI for creating an async client
from openai import AsyncOpenAI

# Import custom classes and functions from the agents package.
# These handle agent creation, model interfacing, running agents, and more.
from agents import Agent, OpenAIChatCompletionsModel, Runner, function_tool, set_tracing_disabled

# Retrieve configuration from environment variables or use defaults
BASE_URL = os.getenv("EXAMPLE_BASE_URL") or "https://api.perplexity.ai"
API_KEY = os.getenv("EXAMPLE_API_KEY") 
MODEL_NAME = os.getenv("EXAMPLE_MODEL_NAME") or "sonar-pro"

# Validate that all required configuration variables are set
if not BASE_URL or not API_KEY or not MODEL_NAME:
    raise ValueError(
        "Please set EXAMPLE_BASE_URL, EXAMPLE_API_KEY, EXAMPLE_MODEL_NAME via env var or code."
    )

# Initialize the custom OpenAI async client with the specified BASE_URL and API_KEY.
client = AsyncOpenAI(base_url=BASE_URL, api_key=API_KEY)

# Disable tracing to avoid using a platform tracing key; adjust as needed.
set_tracing_disabled(disabled=True)

# Define a function tool that the agent can call.
# The decorator registers this function as a tool in the agents framework.
@function_tool
def get_weather(city: str):
    """
    Simulate fetching weather data for a given city.
    
    Args:
        city (str): The name of the city to retrieve weather for.
        
    Returns:
        str: A message with weather information.
    """
    print(f"[debug] getting weather for {city}")
    return f"The weather in {city} is sunny."

# Import nest_asyncio to support nested event loops
import nest_asyncio

# Apply the nest_asyncio patch to enable running asyncio.run() 
# even if an event loop is already running.
nest_asyncio.apply()

async def main():
    """
    Main asynchronous function to set up and run the agent.
    
    This function creates an Agent with a custom model and function tools,
    then runs a query to get the weather in Tokyo.
    """
    # Create an Agent instance with:
    # - A name ("Assistant")
    # - Custom instructions ("Be precise and concise.")
    # - A model built from OpenAIChatCompletionsModel using our client and model name.
    # - A list of tools; here, only get_weather is provided.
    agent = Agent(
        name="Assistant",
        instructions="Be precise and concise.",
        model=OpenAIChatCompletionsModel(model=MODEL_NAME, openai_client=client),
        tools=[get_weather],
    )

    # Execute the agent with the sample query.
    result = await Runner.run(agent, "What's the weather in Tokyo?")
    
    # Print the final output from the agent.
    print(result.final_output)

# Standard boilerplate to run the async main() function.
if __name__ == "__main__":
    asyncio.run(main())
```

## 🔍 Code Breakdown

Let's examine the key components:

### 1. **Client Configuration**

```python theme={null}
client = AsyncOpenAI(base_url=BASE_URL, api_key=API_KEY)
```

This creates an async OpenAI client pointed at Perplexity's Sonar API. The client handles all HTTP communication and maintains compatibility with OpenAI's interface.

### 2. **Function Tools**

```python theme={null}
@function_tool
def get_weather(city: str):
    """Simulate fetching weather data for a given city."""
    return f"The weather in {city} is sunny."
```

Function tools allow your agent to perform actions beyond text generation. In production, you'd replace this with real API calls.

### 3. **Agent Creation**

```python theme={null}
agent = Agent(
    name="Assistant",
    instructions="Be precise and concise.",
    model=OpenAIChatCompletionsModel(model=MODEL_NAME, openai_client=client),
    tools=[get_weather],
)
```

The agent combines Sonar's language capabilities with your custom tools and instructions.

## 🏃‍♂️ Running the Example

1. **Set your environment variables**:
   ```bash theme={null}
   export EXAMPLE_API_KEY="your-perplexity-api-key"
   ```

2. **Save the code** to a file (e.g., `pplx_openai_agent.py`)

3. **Run the script**:
   ```bash theme={null}
   python pplx_openai_agent.py
   ```

**Expected Output**:

```
[debug] getting weather for Tokyo
The weather in Tokyo is sunny.
```

## 🔧 Customization Options

### **Different Sonar Models**

Choose the right model for your use case:

```python theme={null}
# For quick, lightweight queries
MODEL_NAME = "sonar"

# For complex research and analysis (default)
MODEL_NAME = "sonar-pro"

# For deep reasoning tasks
MODEL_NAME = "sonar-reasoning-pro"
```

### **Custom Instructions**

Tailor the agent's behavior:

```python theme={null}
agent = Agent(
    name="Research Assistant",
    instructions="""
    You are a research assistant specializing in academic literature.
    Always provide citations and verify information through multiple sources.
    Be thorough but concise in your responses.
    """,
    model=OpenAIChatCompletionsModel(model=MODEL_NAME, openai_client=client),
    tools=[search_papers, get_citations],
)
```

### **Multiple Function Tools**

Add more capabilities:

```python theme={null}
@function_tool
def search_web(query: str):
    """Search the web for current information."""
    # Implementation here
    pass

@function_tool
def analyze_data(data: str):
    """Analyze structured data."""
    # Implementation here
    pass

agent = Agent(
    name="Multi-Tool Assistant",
    instructions="Use the appropriate tool for each task.",
    model=OpenAIChatCompletionsModel(model=MODEL_NAME, openai_client=client),
    tools=[get_weather, search_web, analyze_data],
)
```

## 🚀 Production Considerations

### **Error Handling**

```python theme={null}
async def robust_main():
    try:
        agent = Agent(
            name="Assistant",
            instructions="Be helpful and accurate.",
            model=OpenAIChatCompletionsModel(model=MODEL_NAME, openai_client=client),
            tools=[get_weather],
        )
        
        result = await Runner.run(agent, "What's the weather in Tokyo?")
        return result.final_output
        
    except Exception as e:
        print(f"Error running agent: {e}")
        return "Sorry, I encountered an error processing your request."
```

### **Rate Limiting**

```python theme={null}
import aiohttp
from openai import AsyncOpenAI

# Configure client with custom timeout and retry settings
client = AsyncOpenAI(
    base_url=BASE_URL, 
    api_key=API_KEY,
    timeout=30.0,
    max_retries=3
)
```

### **Logging and Monitoring**

```python theme={null}
import logging

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

@function_tool
def get_weather(city: str):
    logger.info(f"Fetching weather for {city}")
    # Implementation here
```

## 🔗 Advanced Integration Patterns

### **Streaming Responses**

For real-time applications:

```python theme={null}
async def stream_agent_response(query: str):
    agent = Agent(
        name="Streaming Assistant",
        instructions="Provide detailed, step-by-step responses.",
        model=OpenAIChatCompletionsModel(model=MODEL_NAME, openai_client=client),
        tools=[get_weather],
    )
    
    async for chunk in Runner.stream(agent, query):
        print(chunk, end='', flush=True)
```

### **Context Management**

For multi-turn conversations:

```python theme={null}
class ConversationManager:
    def __init__(self):
        self.agent = Agent(
            name="Conversational Assistant",
            instructions="Maintain context across multiple interactions.",
            model=OpenAIChatCompletionsModel(model=MODEL_NAME, openai_client=client),
            tools=[get_weather],
        )
        self.conversation_history = []
    
    async def chat(self, message: str):
        result = await Runner.run(self.agent, message)
        self.conversation_history.append({"user": message, "assistant": result.final_output})
        return result.final_output
```

## ⚠️ Important Notes

* **API Costs**: Monitor your usage as both Perplexity and OpenAI Agents may incur costs
* **Rate Limits**: Respect API rate limits and implement appropriate backoff strategies
* **Error Handling**: Always implement robust error handling for production applications
* **Security**: Keep your API keys secure and never commit them to version control

## 🎯 Use Cases

This integration pattern is perfect for:

* **🔍 Research Assistants** - Combining real-time search with structured responses
* **📊 Data Analysis Tools** - Using Sonar for context and agents for processing
* **🤖 Customer Support** - Grounded responses with function calling capabilities
* **📚 Educational Applications** - Real-time information with interactive features

## 📚 References

* [Perplexity Sonar API Documentation](https://docs.perplexity.ai/home)
* [OpenAI Agents SDK Documentation](https://github.com/openai/openai-agents-python)
* [AsyncOpenAI Client Reference](https://platform.openai.com/docs/api-reference)
* [Function Calling Best Practices](https://platform.openai.com/docs/guides/function-calling)

***

**Ready to build?** This integration opens up powerful possibilities for creating intelligent, grounded agents. Start with the basic example and gradually add more sophisticated tools and capabilities! 🚀


# Search Domain Filtering Patterns
Source: https://docs.perplexity.ai/docs/cookbook/articles/search-domain-filtering/README

Use search_domain_filter for focused search — allowlist patterns for trusted sources, denylist for excluding domains, and practical patterns for news, government, and competitive intelligence

This guide covers search domain filtering on the Agent API. You will learn how to use allowlists to restrict search to trusted domains, denylists to exclude unwanted sources, and practical patterns for common use cases like news-only search, government data, and competitor exclusion.

<Info>
  Domain filtering is configured per-tool under the `tools` array via `tools[].filters.search_domain_filter`. For the full reference, see [Agent API Filters](/docs/agent-api/filters).
</Info>

## Prerequisites

Install the Perplexity SDK:

<CodeGroup>
  ```bash Python theme={null}
  pip install perplexityai
  ```

  ```bash TypeScript theme={null}
  npm install @perplexity-ai/perplexity_ai
  ```
</CodeGroup>

If you don't have an API key yet:

<Card title="Get your Perplexity API Key" icon="key" href="https://perplexity.ai/account/api">
  Navigate to the **API Keys** tab in the API Portal and generate a new key.
</Card>

Then export your API key as an environment variable:

```bash theme={null}
export PERPLEXITY_API_KEY="your-api-key"
```

## How Domain Filtering Works

The `search_domain_filter` parameter accepts a list of domain strings:

* **Allowlist** (no prefix): Include only results from these domains. `["reuters.com", "apnews.com"]` means search only Reuters and AP News.
* **Denylist** (`-` prefix): Exclude results from these domains. `["-reddit.com", "-twitter.com"]` means exclude Reddit and Twitter.

<Warning>
  **Never mix allowlist and denylist entries in the same request.** The API does not support combining `"reuters.com"` and `"-reddit.com"` in the same array. Use either all allowlist or all denylist entries.
</Warning>

## Basic Domain Filtering

Domain filters are configured per-tool under the `tools` array.

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity

  client = Perplexity()

  # Allowlist: search only specific domains
  response = client.responses.create(
      model="openai/gpt-5.4",
      input="What are the latest developments in AI regulation?",
      tools=[{
          "type": "web_search",
          "filters": {
              "search_domain_filter": ["reuters.com", "apnews.com", "bbc.com"],
          },
      }],
  )
  print(response.output_text)
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  const response = await client.responses.create({
      model: "openai/gpt-5.4",
      input: "What are the latest developments in AI regulation?",
      tools: [{
          type: "web_search" as const,
          filters: {
              search_domain_filter: ["reuters.com", "apnews.com", "bbc.com"],
          },
      }],
  });
  console.log(response.output_text);
  ```
</CodeGroup>

## Pattern: Denylist Filtering

Use the `-` prefix to exclude specific domains from search results.

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity

  client = Perplexity()

  # Denylist: exclude social media and user-generated content
  response = client.responses.create(
      model="openai/gpt-5.4",
      input="What are the latest developments in AI regulation?",
      tools=[{
          "type": "web_search",
          "filters": {
              "search_domain_filter": ["-reddit.com", "-twitter.com", "-quora.com", "-medium.com"],
          },
      }],
  )
  print(response.output_text)
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  const response = await client.responses.create({
      model: "openai/gpt-5.4",
      input: "What are the latest developments in AI regulation?",
      tools: [{
          type: "web_search" as const,
          filters: {
              search_domain_filter: ["-reddit.com", "-twitter.com", "-quora.com", "-medium.com"],
          },
      }],
  });
  console.log(response.output_text);
  ```
</CodeGroup>

## Pattern: News-Only Search

Restrict results to major news outlets for current events and breaking news.

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity

  client = Perplexity()

  NEWS_DOMAINS = [
      "reuters.com",
      "apnews.com",
      "bbc.com",
      "nytimes.com",
      "washingtonpost.com",
      "theguardian.com",
      "bloomberg.com",
      "ft.com",
  ]

  response = client.responses.create(
      model="openai/gpt-5.4",
      input="What happened in global markets today?",
      tools=[{
          "type": "web_search",
          "filters": {
              "search_domain_filter": NEWS_DOMAINS,
              "search_recency_filter": "day",
          },
      }],
  )
  print(response.output_text)
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  const NEWS_DOMAINS = [
      "reuters.com",
      "apnews.com",
      "bbc.com",
      "nytimes.com",
      "washingtonpost.com",
      "theguardian.com",
      "bloomberg.com",
      "ft.com",
  ];

  const response = await client.responses.create({
      model: "openai/gpt-5.4",
      input: "What happened in global markets today?",
      tools: [{
          type: "web_search" as const,
          filters: {
              search_domain_filter: NEWS_DOMAINS,
              search_recency_filter: "day",
          },
      }],
  });
  console.log(response.output_text);
  ```
</CodeGroup>

<Tip>
  Combine `search_domain_filter` with `search_recency_filter` for time-sensitive queries. Options are `day`, `week`, `month`, and `year`.
</Tip>

## Pattern: Government and Official Sources

Restrict to government domains for policy, regulation, and official statistics.

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity

  client = Perplexity()

  GOV_DOMAINS = [
      ".gov",          # US federal and state
      ".gov.uk",       # UK government
      ".europa.eu",    # EU institutions
      "who.int",       # World Health Organization
      "worldbank.org", # World Bank
  ]

  response = client.responses.create(
      model="openai/gpt-5.4",
      input="What are the current US federal guidelines on AI usage in healthcare?",
      tools=[{
          "type": "web_search",
          "filters": {
              "search_domain_filter": GOV_DOMAINS,
          },
      }],
  )
  print(response.output_text)
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  const GOV_DOMAINS = [
      ".gov",
      ".gov.uk",
      ".europa.eu",
      "who.int",
      "worldbank.org",
  ];

  const response = await client.responses.create({
      model: "openai/gpt-5.4",
      input: "What are the current US federal guidelines on AI usage in healthcare?",
      tools: [{
          type: "web_search" as const,
          filters: {
              search_domain_filter: GOV_DOMAINS,
          },
      }],
  });
  console.log(response.output_text);
  ```
</CodeGroup>

## Pattern: Academic and Research Filtering

Target educational and research institutions.

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity

  client = Perplexity()

  ACADEMIC_DOMAINS = [
      ".edu",
      "arxiv.org",
      "scholar.google.com",
      "pubmed.ncbi.nlm.nih.gov",
      "nature.com",
      "science.org",
      "ieee.org",
  ]

  response = client.responses.create(
      model="openai/gpt-5.4",
      input="What are recent advances in protein structure prediction?",
      tools=[{
          "type": "web_search",
          "filters": {
              "search_domain_filter": ACADEMIC_DOMAINS,
          },
      }],
  )
  print(response.output_text)
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  const ACADEMIC_DOMAINS = [
      ".edu",
      "arxiv.org",
      "scholar.google.com",
      "pubmed.ncbi.nlm.nih.gov",
      "nature.com",
      "science.org",
      "ieee.org",
  ];

  const response = await client.responses.create({
      model: "openai/gpt-5.4",
      input: "What are recent advances in protein structure prediction?",
      tools: [{
          type: "web_search" as const,
          filters: {
              search_domain_filter: ACADEMIC_DOMAINS,
          },
      }],
  });
  console.log(response.output_text);
  ```
</CodeGroup>

## Pattern: Competitor Exclusion

Use denylists to exclude competitor websites from search results when building customer-facing content.

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity

  client = Perplexity()

  # Exclude competitor domains from product research
  EXCLUDED_DOMAINS = [
      "-competitor-a.com",
      "-competitor-b.io",
      "-competitor-c.ai",
  ]

  response = client.responses.create(
      model="openai/gpt-5.4",
      input="What are the best practices for building real-time data pipelines?",
      tools=[{
          "type": "web_search",
          "filters": {
              "search_domain_filter": EXCLUDED_DOMAINS,
          },
      }],
  )
  print(response.output_text)
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  const EXCLUDED_DOMAINS = [
      "-competitor-a.com",
      "-competitor-b.io",
      "-competitor-c.ai",
  ];

  const response = await client.responses.create({
      model: "openai/gpt-5.4",
      input: "What are the best practices for building real-time data pipelines?",
      tools: [{
          type: "web_search" as const,
          filters: {
              search_domain_filter: EXCLUDED_DOMAINS,
          },
      }],
  });
  console.log(response.output_text);
  ```
</CodeGroup>

## Configurable Filter Builder

A reusable helper that builds domain filter configurations from named presets.

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity

  client = Perplexity()

  # Named filter presets
  FILTER_PRESETS = {
      "news": ["reuters.com", "apnews.com", "bbc.com", "bloomberg.com", "ft.com"],
      "academic": [".edu", "arxiv.org", "nature.com", "science.org", "pubmed.ncbi.nlm.nih.gov"],
      "government": [".gov", ".gov.uk", ".europa.eu", "who.int"],
      "tech": ["techcrunch.com", "arstechnica.com", "theverge.com", "wired.com"],
      "no_social": ["-reddit.com", "-twitter.com", "-facebook.com", "-tiktok.com", "-quora.com"],
      "no_seo_spam": ["-pinterest.com", "-medium.com", "-hubspot.com"],
  }


  def search_with_preset(query: str, preset: str, recency: str = None) -> str:
      """Run a search with a named domain filter preset."""
      if preset not in FILTER_PRESETS:
          raise ValueError(f"Unknown preset: {preset}. Options: {list(FILTER_PRESETS.keys())}")

      filters = {"search_domain_filter": FILTER_PRESETS[preset]}
      if recency:
          filters["search_recency_filter"] = recency

      response = client.responses.create(
          model="openai/gpt-5.4",
          input=query,
          tools=[{"type": "web_search", "filters": filters}],
      )
      return response.output_text


  # Usage
  print("--- News Search ---")
  print(search_with_preset("Latest AI regulation news", "news", recency="week"))

  print("\n--- Academic Search ---")
  print(search_with_preset("CRISPR gene editing recent papers", "academic"))

  print("\n--- Clean Search (no social media) ---")
  print(search_with_preset("Best Python testing frameworks", "no_social"))
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  const FILTER_PRESETS: Record<string, string[]> = {
      news: ["reuters.com", "apnews.com", "bbc.com", "bloomberg.com", "ft.com"],
      academic: [".edu", "arxiv.org", "nature.com", "science.org", "pubmed.ncbi.nlm.nih.gov"],
      government: [".gov", ".gov.uk", ".europa.eu", "who.int"],
      tech: ["techcrunch.com", "arstechnica.com", "theverge.com", "wired.com"],
      no_social: ["-reddit.com", "-twitter.com", "-facebook.com", "-tiktok.com", "-quora.com"],
      no_seo_spam: ["-pinterest.com", "-medium.com", "-hubspot.com"],
  };

  async function searchWithPreset(query: string, preset: string, recency?: string): Promise<string> {
      if (!(preset in FILTER_PRESETS)) {
          throw new Error(`Unknown preset: ${preset}. Options: ${Object.keys(FILTER_PRESETS).join(", ")}`);
      }

      const filters: Record<string, any> = { search_domain_filter: FILTER_PRESETS[preset] };
      if (recency) filters.search_recency_filter = recency;

      const response = await client.responses.create({
          model: "openai/gpt-5.4",
          input: query,
          tools: [{ type: "web_search" as const, filters }],
      });
      return response.output_text;
  }

  console.log("--- News Search ---");
  console.log(await searchWithPreset("Latest AI regulation news", "news", "week"));

  console.log("\n--- Academic Search ---");
  console.log(await searchWithPreset("CRISPR gene editing recent papers", "academic"));

  console.log("\n--- Clean Search (no social media) ---");
  console.log(await searchWithPreset("Best Python testing frameworks", "no_social"));
  ```
</CodeGroup>

## Common Pitfalls

### Mixing Allowlist and Denylist

```python theme={null}
# ❌ WRONG: mixing allowlist and denylist
search_domain_filter=["reuters.com", "-reddit.com"]

# ✅ CORRECT: use only allowlist
search_domain_filter=["reuters.com", "apnews.com", "bbc.com"]

# ✅ CORRECT: use only denylist
search_domain_filter=["-reddit.com", "-twitter.com"]
```

### Using Wildcards Incorrectly

```python theme={null}
# ❌ WRONG: wildcards are not supported
search_domain_filter=["*.gov"]

# ✅ CORRECT: use the TLD directly
search_domain_filter=[".gov"]
```

### Empty Filter Arrays

```python theme={null}
# ❌ WRONG: empty array has undefined behavior
search_domain_filter=[]

# ✅ CORRECT: omit the parameter to search all domains
# (simply don't include search_domain_filter)
```

## Tips and Best Practices

1. **Keep allowlists focused.** 5-10 domains is usually sufficient. Too many domains dilutes the filter's purpose.

2. **Use denylists for broad exclusion.** When you want to exclude a few noisy sources but otherwise search the full web, denylists are more practical than trying to allowlist everything else.

3. **Combine with recency filters.** For time-sensitive queries, add `search_recency_filter` alongside domain filters.

4. **Test your filters.** Run the same query with and without filters to verify that results change as expected.

5. **TLD filters work broadly.** Using `.gov` matches any domain ending in `.gov`, including `whitehouse.gov`, `irs.gov`, and state domains like `ca.gov`.

6. **Store presets in configuration.** Define filter presets in your app configuration rather than hardcoding them in every request.

## Next Steps

<CardGroup>
  <Card title="Agent API Filters" icon="filter" href="/docs/agent-api/filters">
    Full reference for domain, date range, and location filters on the Agent API.
  </Card>

  <Card title="Search API Filters" icon="filter" href="/docs/search/filters/domain-filter">
    Domain filtering on the raw Search API for result-level control.
  </Card>

  <Card title="Academic Search" icon="graduation-cap" href="/docs/cookbook/articles/academic-search/README">
    Specialized academic search with domain filtering.
  </Card>
</CardGroup>


# Streaming Citation Parsing
Source: https://docs.perplexity.ai/docs/cookbook/articles/streaming-citations/README

Consume streaming responses from the Agent API and extract, validate, and display citations in real-time as chunks arrive

This guide shows how to consume streaming responses from the Agent API, extract citations as they arrive, validate source URLs, and build a fully cited output. Streaming is essential for responsive UIs and long-running searches — you can display text and sources progressively instead of waiting for the full response.

<Info>
  The `fast-search` preset is optimized for quick, citation-rich answers. The model inserts numbered references like `[1]`, `[2]` in the text, and the corresponding source URLs arrive in the `search_results` output item. See the [Agent API Presets](/docs/agent-api/presets) docs for all available presets.
</Info>

## Prerequisites

Install the SDKs:

<CodeGroup>
  ```bash Python theme={null}
  pip install perplexityai openai
  ```

  ```bash TypeScript theme={null}
  npm install @perplexity-ai/perplexity_ai openai
  ```
</CodeGroup>

If you don't have an API key yet:

<Card title="Get your Perplexity API Key" icon="key" href="https://perplexity.ai/account/api">
  Navigate to the **API Keys** tab in the API Portal and generate a new key.
</Card>

Then export your API key as an environment variable:

```bash theme={null}
export PERPLEXITY_API_KEY="your-api-key"
```

## How Streaming Citations Work

When you stream an Agent API response with a search-enabled preset, the API sends a sequence of server-sent events (SSE). The flow is:

1. **Search results** arrive first via `response.reasoning.search_results` events, containing URLs, titles, and snippets for each source.
2. **Content chunks** arrive incrementally as the model generates text via `response.output_text.delta` events.
3. **Citation references** appear in the text as numbered markers like `[1]`, `[2]`, mapping to the search result `id` field.

Your client accumulates the text, collects search results, then maps the numbered references to source URLs using the `id` field.

## Basic Streaming with Citations

<CodeGroup>
  ```python Python theme={null}
  import os
  from openai import OpenAI

  # The OpenAI SDK supports Agent API streaming via the /v1/responses alias
  client = OpenAI(
      api_key=os.environ["PERPLEXITY_API_KEY"],
      base_url="https://api.perplexity.ai/v1",
  )

  stream = client.responses.create(
      input="What are the latest breakthroughs in quantum computing?",
      stream=True,
      extra_body={"preset": "fast-search"},
  )

  full_content = ""
  search_results = []

  for event in stream:
      event_type = event.type

      # Collect search results (arrive before text)
      if event_type == "response.reasoning.search_results":
          search_results = event.results

      # Accumulate content from each delta
      if event_type == "response.output_text.delta":
          full_content += event.delta
          print(event.delta, end="", flush=True)

  print("\n\n--- Citations ---")
  for result in search_results:
      print(f"[{result['id']}] {result['title']} — {result['url']}")
  ```

  ```typescript TypeScript theme={null}
  import OpenAI from "openai";

  // The OpenAI SDK supports Agent API streaming via the /v1/responses alias
  const client = new OpenAI({
      apiKey: process.env.PERPLEXITY_API_KEY,
      baseURL: "https://api.perplexity.ai/v1",
  });

  const stream = await client.responses.create({
      input: "What are the latest breakthroughs in quantum computing?",
      stream: true,
      preset: "fast-search",
  } as any);

  let fullContent = "";
  let searchResults: Array<{ id: number; title: string; url: string }> = [];

  for await (const event of stream) {
      // Collect search results (arrive before text)
      if (event.type === "response.reasoning.search_results") {
          searchResults = (event as any).results;
      }

      // Accumulate content from each delta
      if (event.type === "response.output_text.delta") {
          fullContent += event.delta;
          process.stdout.write(event.delta);
      }
  }

  console.log("\n\n--- Citations ---");
  searchResults.forEach((result) => {
      console.log(`[${result.id}] ${result.title} — ${result.url}`);
  });
  ```

  ```bash curl theme={null}
  curl -N "https://api.perplexity.ai/v1/agent" \
    -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "preset": "fast-search",
      "input": "What are the latest breakthroughs in quantum computing?",
      "stream": true
    }'
  ```
</CodeGroup>

## Parsing Citation References from Text

The model inserts numbered references like `[1]`, `[2]` into the generated text. To build a rich output with clickable links, parse these references and map them to source URLs using the search results.

<CodeGroup>
  ```python Python theme={null}
  import re
  from perplexity import Perplexity

  client = Perplexity()


  def extract_citation_refs(text: str) -> list[int]:
      """Extract all citation reference numbers from text, e.g. [1], [2]."""
      return sorted(set(int(m) for m in re.findall(r"\[(\d+)\]", text)))


  def build_cited_output(content: str, search_results: list) -> str:
      """Replace [N] references with markdown links and append a references section."""
      cited_content = content

      # Build a map from id to URL
      url_map = {r.id: r.url for r in search_results}
      title_map = {r.id: r.title for r in search_results}

      # Replace inline references with markdown links
      for ref_id, url in url_map.items():
          cited_content = cited_content.replace(
              f"[{ref_id}]",
              f"[[{ref_id}]]({url})"
          )

      # Append a references section with all cited sources
      used_refs = extract_citation_refs(content)
      if used_refs:
          cited_content += "\n\n---\n**References:**\n"
          for ref in used_refs:
              if ref in url_map:
                  cited_content += f"- [{ref}] {title_map[ref]} — {url_map[ref]}\n"

      return cited_content


  # Non-streaming request to get content + search results
  response = client.responses.create(
      preset="fast-search",
      input="What is CRISPR gene editing and how does it work?",
  )

  # Extract search results from the response output
  content = response.output_text
  search_results = []
  for item in response.output:
      if item.type == "search_results":
          search_results = item.results
          break

  # Build the final output with linked citations
  output = build_cited_output(content, search_results)
  print(output)
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from "@perplexity-ai/perplexity_ai";

  const client = new Perplexity();

  function extractCitationRefs(text: string): number[] {
      const refs = new Set<number>();
      for (const match of text.matchAll(/\[(\d+)\]/g)) {
          refs.add(parseInt(match[1]));
      }
      return [...refs].sort((a, b) => a - b);
  }

  function buildCitedOutput(
      content: string,
      searchResults: Array<{ id: number; url: string; title: string }>
  ): string {
      let cited = content;

      // Build maps from id to URL and title
      const urlMap = new Map(searchResults.map((r) => [r.id, r.url]));
      const titleMap = new Map(searchResults.map((r) => [r.id, r.title]));

      // Replace inline references with markdown links
      for (const [id, url] of urlMap) {
          cited = cited.replaceAll(`[${id}]`, `[[${id}]](${url})`);
      }

      // Append a references section
      const usedRefs = extractCitationRefs(content);
      if (usedRefs.length > 0) {
          cited += "\n\n---\n**References:**\n";
          for (const ref of usedRefs) {
              if (urlMap.has(ref)) {
                  cited += `- [${ref}] ${titleMap.get(ref)} — ${urlMap.get(ref)}\n`;
              }
          }
      }

      return cited;
  }

  // Non-streaming request to get content + search results
  const response = await client.responses.create({
      preset: "fast-search",
      input: "What is CRISPR gene editing and how does it work?",
  });

  // Extract search results from the response output
  const content = response.output_text;
  let searchResults: Array<{ id: number; url: string; title: string }> = [];
  for (const item of response.output) {
      if (item.type === "search_results") {
          searchResults = (item as any).results;
          break;
      }
  }

  const output = buildCitedOutput(content, searchResults);
  console.log(output);
  ```
</CodeGroup>

## Validating Citation URLs

In production systems, you should validate that citation URLs are well-formed and reachable before presenting them to users. This avoids broken links and improves trust in the output.

<CodeGroup>
  ```python Python theme={null}
  import asyncio
  import aiohttp
  from urllib.parse import urlparse


  def is_valid_url(url: str) -> bool:
      """Check that a URL has a valid structure."""
      try:
          result = urlparse(url)
          return all([result.scheme in ("http", "https"), result.netloc])
      except Exception:
          return False


  async def check_url_reachable(url: str, timeout: float = 5.0) -> dict:
      """HEAD-request a URL to check if it's reachable."""
      if not is_valid_url(url):
          return {"url": url, "valid": False, "reason": "malformed URL"}

      try:
          async with aiohttp.ClientSession() as session:
              async with session.head(url, timeout=aiohttp.ClientTimeout(total=timeout), allow_redirects=True) as resp:
                  return {
                      "url": url,
                      "valid": resp.status < 400,
                      "status": resp.status,
                  }
      except asyncio.TimeoutError:
          return {"url": url, "valid": False, "reason": "timeout"}
      except Exception as e:
          return {"url": url, "valid": False, "reason": str(e)}


  async def validate_citations(search_results: list) -> list[dict]:
      """Validate all citation URLs from search results concurrently."""
      tasks = [check_url_reachable(r.url) for r in search_results]
      return await asyncio.gather(*tasks)


  # Usage after getting a response:
  # results = asyncio.run(validate_citations(search_results))
  # for r in results:
  #     status = "OK" if r["valid"] else f"FAILED ({r.get('reason', r.get('status'))})"
  #     print(f"  {r['url']}: {status}")
  ```

  ```typescript TypeScript theme={null}
  function isValidUrl(url: string): boolean {
      try {
          const parsed = new URL(url);
          return parsed.protocol === "http:" || parsed.protocol === "https:";
      } catch {
          return false;
      }
  }

  async function checkUrlReachable(url: string, timeoutMs = 5000): Promise<{ url: string; valid: boolean; reason?: string; status?: number }> {
      if (!isValidUrl(url)) {
          return { url, valid: false, reason: "malformed URL" };
      }

      try {
          const controller = new AbortController();
          const timer = setTimeout(() => controller.abort(), timeoutMs);
          const resp = await fetch(url, { method: "HEAD", signal: controller.signal, redirect: "follow" });
          clearTimeout(timer);
          return { url, valid: resp.status < 400, status: resp.status };
      } catch (e: any) {
          return { url, valid: false, reason: e.message };
      }
  }

  async function validateCitations(searchResults: Array<{ url: string }>): Promise<Array<{ url: string; valid: boolean; reason?: string }>> {
      return Promise.all(searchResults.map(r => checkUrlReachable(r.url)));
  }

  // Usage after getting a response:
  // const results = await validateCitations(searchResults);
  // results.forEach(r => {
  //     const status = r.valid ? "OK" : `FAILED (${r.reason ?? r.status})`;
  //     console.log(`  ${r.url}: ${status}`);
  // });
  ```
</CodeGroup>

<Warning>
  **Never ask the model to generate source URLs.** Always use the `search_results` output from the API response. Model-generated URLs can be hallucinated. The search results contain verified URLs from real web searches.
</Warning>

## Progressive Display with Live Citation Count

For chat UIs, it's useful to show a live citation counter as text streams in, then render the full reference list once the stream completes.

<CodeGroup>
  ```python Python theme={null}
  import os
  import re
  import sys
  from openai import OpenAI

  client = OpenAI(
      api_key=os.environ["PERPLEXITY_API_KEY"],
      base_url="https://api.perplexity.ai/v1",
  )


  def stream_with_progress(query: str):
      """Stream a response with a live citation counter."""
      stream = client.responses.create(
          input=query,
          stream=True,
          extra_body={"preset": "fast-search"},
      )

      full_content = ""
      search_results = []
      seen_refs = set()

      for event in stream:
          if event.type == "response.reasoning.search_results":
              search_results = event.results

          if event.type == "response.output_text.delta":
              full_content += event.delta
              sys.stdout.write(event.delta)
              sys.stdout.flush()

              # Track new citation references against accumulated text
              # (individual deltas may split [N] across chunks)
              current_refs = set(int(m) for m in re.findall(r"\[(\d+)\]", full_content))
              if current_refs - seen_refs:
                  seen_refs = current_refs
                  sys.stdout.write(f" [📚 {len(seen_refs)} sources]")
                  sys.stdout.flush()

      # Final summary
      print(f"\n\n{'='*60}")
      print(f"Response complete: {len(search_results)} sources found, {len(seen_refs)} cited")
      print(f"{'='*60}")

      # Build URL map from search results
      url_map = {r["id"]: r for r in search_results}
      for ref_id in sorted(seen_refs):
          if ref_id in url_map:
              r = url_map[ref_id]
              print(f"  ✓ [{ref_id}] {r['title']} — {r['url']}")

      return full_content, search_results


  content, results = stream_with_progress(
      "What are the environmental impacts of lithium mining?"
  )
  ```

  ```typescript TypeScript theme={null}
  import OpenAI from "openai";

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

  async function streamWithProgress(query: string) {
      const stream = await client.responses.create({
          input: query,
          stream: true,
          preset: "fast-search",
      } as any);

      let fullContent = "";
      let searchResults: Array<{ id: number; title: string; url: string }> = [];
      const seenRefs = new Set<number>();

      for await (const event of stream) {
          if (event.type === "response.reasoning.search_results") {
              searchResults = (event as any).results;
          }

          if (event.type === "response.output_text.delta") {
              fullContent += event.delta;
              process.stdout.write(event.delta);

              // Track new citation references against accumulated text
              // (individual deltas may split [N] across chunks)
              const prevSize = seenRefs.size;
              for (const match of fullContent.matchAll(/\[(\d+)\]/g)) {
                  seenRefs.add(parseInt(match[1]));
              }
              if (seenRefs.size > prevSize) {
                  process.stdout.write(` [📚 ${seenRefs.size} sources]`);
              }
          }
      }

      console.log(`\n\n${"=".repeat(60)}`);
      console.log(`Response complete: ${searchResults.length} sources found, ${seenRefs.size} cited`);
      console.log("=".repeat(60));

      const urlMap = new Map(searchResults.map((r) => [r.id, r]));
      for (const refId of [...seenRefs].sort((a, b) => a - b)) {
          const r = urlMap.get(refId);
          if (r) {
              console.log(`  ✓ [${refId}] ${r.title} — ${r.url}`);
          }
      }

      return { fullContent, searchResults };
  }

  await streamWithProgress("What are the environmental impacts of lithium mining?");
  ```
</CodeGroup>

## Handling Search Results

The Agent API returns a `search_results` output item with rich metadata (id, title, snippet, URL, date) for each source. This is richer than a flat URL list — use it to build source cards, sidebars, or detailed reference sections.

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity

  client = Perplexity()

  # Non-streaming request to show the full response structure
  response = client.responses.create(
      preset="fast-search",
      input="What is the current state of fusion energy research?",
  )

  content = response.output_text

  # Extract search results from the output
  search_results = []
  for item in response.output:
      if item.type == "search_results":
          search_results = item.results
          break

  print("--- Answer ---")
  print(content)

  print("\n--- Search Results (rich metadata) ---")
  for result in search_results:
      print(f"  [{result.id}] {result.title}")
      print(f"      URL:  {result.url}")
      print(f"      Date: {result.date}")
      print(f"      Snippet: {result.snippet[:100]}...")
      print()
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from "@perplexity-ai/perplexity_ai";

  const client = new Perplexity();

  const response = await client.responses.create({
      preset: "fast-search",
      input: "What is the current state of fusion energy research?",
  });

  const content = response.output_text;

  // Extract search results from the output
  let searchResults: any[] = [];
  for (const item of response.output) {
      if (item.type === "search_results") {
          searchResults = (item as any).results;
          break;
      }
  }

  console.log("--- Answer ---");
  console.log(content);

  console.log("\n--- Search Results (rich metadata) ---");
  for (const result of searchResults) {
      console.log(`  [${result.id}] ${result.title}`);
      console.log(`      URL:  ${result.url}`);
      console.log(`      Date: ${result.date}`);
      console.log(`      Snippet: ${result.snippet?.slice(0, 100)}...`);
      console.log();
  }
  ```
</CodeGroup>

<Tip>
  Each search result includes `id`, `title`, `url`, `snippet`, and `date`. The `id` maps directly to the `[N]` references in the text. Use this to build rich source cards for your UI.
</Tip>

## Complete Example: Streaming Research Assistant

A self-contained script that streams an Agent API response, extracts citations, validates URLs, and produces a formatted markdown output.

<CodeGroup>
  ```python Python theme={null}
  import os
  import re
  from urllib.parse import urlparse
  from openai import OpenAI

  client = OpenAI(
      api_key=os.environ["PERPLEXITY_API_KEY"],
      base_url="https://api.perplexity.ai/v1",
  )


  def is_valid_url(url: str) -> bool:
      try:
          result = urlparse(url)
          return all([result.scheme in ("http", "https"), result.netloc])
      except Exception:
          return False


  def stream_and_collect(query: str) -> tuple[str, list[dict]]:
      """Stream an Agent API response and return the full content and search results."""
      stream = client.responses.create(
          input=query,
          stream=True,
          extra_body={"preset": "fast-search"},
      )

      content = ""
      search_results = []

      for event in stream:
          if event.type == "response.reasoning.search_results":
              search_results = event.results

          if event.type == "response.output_text.delta":
              content += event.delta
              print(event.delta, end="", flush=True)

      print()  # newline after streaming
      return content, search_results


  def format_markdown_report(query: str, content: str, search_results: list[dict]) -> str:
      """Build a markdown report with inline citation links."""
      # Build URL map from search results
      url_map = {r["id"]: r["url"] for r in search_results}
      title_map = {r["id"]: r["title"] for r in search_results}

      # Replace [N] with markdown links
      formatted = content
      for ref_id, url in url_map.items():
          if is_valid_url(url):
              formatted = formatted.replace(f"[{ref_id}]", f"[\\[{ref_id}\\]]({url})")

      # Build the report
      report = f"# {query}\n\n{formatted}\n\n"

      # Append sources
      used_refs = sorted(set(int(m) for m in re.findall(r"\[(\d+)\]", content)))
      if search_results:
          report += "## Sources\n\n"
          for result in search_results:
              marker = "→" if result["id"] in used_refs else " "
              report += f"{marker} **[{result['id']}]** {result['title']} — {result['url']}\n\n"

      return report


  if __name__ == "__main__":
      query = "What are the most promising approaches to carbon capture technology?"

      print(f"Researching: {query}\n")
      print("-" * 60)

      content, search_results = stream_and_collect(query)

      print(f"\n{'=' * 60}")
      print(f"Collected {len(search_results)} sources\n")

      # Filter out any malformed URLs
      valid_results = [r for r in search_results if is_valid_url(r["url"])]
      invalid_count = len(search_results) - len(valid_results)
      if invalid_count:
          print(f"Warning: {invalid_count} sources had malformed URLs and were excluded.\n")

      report = format_markdown_report(query, content, valid_results)
      print(report)
  ```
</CodeGroup>

## Tips and Best Practices

1. **Use a search-enabled preset** like `fast-search` or `pro-search` for citation-rich responses. Different presets use different citation formats — `fast-search` uses `[1]`, while `pro-search` uses `[web:1]`.

2. **Collect search results before processing text.** During streaming, `response.reasoning.search_results` events arrive before text deltas. Buffer them so you have the URL map ready when citations appear.

3. **Use the `id` field to map citations.** Each search result has a numeric `id` that corresponds to the `[N]` reference in the text.

4. **Validate URLs before displaying them.** Use HEAD requests with timeouts to filter out any unreachable sources.

5. **Never generate your own URLs.** Use only the `search_results` from the API response. Model-generated URLs can be hallucinated.

6. **Handle missing references gracefully.** If a `[N]` reference in the text exceeds the number of search results, display the reference number without a link rather than crashing.

7. **Consider rate limiting for URL validation.** If the response includes many sources, validate them with concurrency limits to avoid overwhelming target servers.

## Next Steps

<CardGroup>
  <Card title="Agent API Presets" icon="bolt" href="/docs/agent-api/presets">
    Explore all presets and their citation formats.
  </Card>

  <Card title="Agent API Quickstart" icon="rocket" href="/docs/agent-api/quickstart">
    Get started with the Agent API for multi-provider access and tools.
  </Card>

  <Card title="Agent API Streaming" icon="stream" href="/docs/agent-api/output-control">
    Streaming patterns and event types for the Agent API.
  </Card>
</CardGroup>


# Examples Overview
Source: https://docs.perplexity.ai/docs/cookbook/examples/README

Runnable projects covering the Agent API, Search API, and Embeddings API

# Examples Overview

Ready-to-run projects that demonstrate real-world use cases across every Perplexity API. Each example includes complete setup instructions and working code.

## Choosing the Right Example

| If you want to...                     | Use this example                                                                    | API                    | Language           |
| ------------------------------------- | ----------------------------------------------------------------------------------- | ---------------------- | ------------------ |
| Conduct deep web research             | [Agent Research Assistant](/docs/cookbook/examples/agent-research-assistant/README) | Agent API              | Python, TypeScript |
| Compare models across providers       | [Model Comparison](/docs/cookbook/examples/model-comparison/README)                 | Agent API              | Python             |
| Monitor news topics in real time      | [Search News Monitor](/docs/cookbook/examples/search-news-monitor/README)           | Search API             | Python, TypeScript |
| Build a document Q\&A system          | [Document Q\&A](/docs/cookbook/examples/document-qa/README)                         | Embeddings + Agent API | Python             |
| Build a TypeScript CLI agent          | [TypeScript Agent CLI](/docs/cookbook/examples/typescript-agent-cli/README)         | Agent API              | TypeScript         |
| Analyze images with web context       | [Image Analysis](/docs/cookbook/examples/image-analysis/README)                     | Agent API              | Python, TypeScript |
| Ask questions about uploaded files    | [File Attachment Q\&A](/docs/cookbook/examples/file-attachment-qa/README)           | Agent API              | Python             |
| Search SEC filings for financial data | [SEC Filing Search](/docs/cookbook/examples/sec-filing-search/README)               | Agent API              | Python             |

## By API

### Agent API

<CardGroup>
  <Card title="Agent Research Assistant" icon="magnifying-glass" href="/docs/cookbook/examples/agent-research-assistant/README">
    Deep web research using the `deep-research` preset with structured report output.
  </Card>

  <Card title="Model Comparison" icon="chart-bar" href="/docs/cookbook/examples/model-comparison/README">
    Compare responses from 5 providers side-by-side — quality, latency, and cost.
  </Card>

  <Card title="TypeScript Agent CLI" icon="terminal" href="/docs/cookbook/examples/typescript-agent-cli/README">
    Interactive TypeScript CLI with streaming, model selection, and web search.
  </Card>

  <Card title="Image Analysis" icon="image" href="/docs/cookbook/examples/image-analysis/README">
    Vision + web search for context-enriched image analysis.
  </Card>

  <Card title="File Attachment Q&A" icon="file-lines" href="/docs/cookbook/examples/file-attachment-qa/README">
    Upload documents and ask questions about them with optional web search enrichment.
  </Card>
</CardGroup>

### Search API

<CardGroup>
  <Card title="Search News Monitor" icon="newspaper" href="/docs/cookbook/examples/search-news-monitor/README">
    Multi-topic news monitoring with domain filtering and recency control.
  </Card>

  <Card title="SEC Filing Search" icon="file-invoice" href="/docs/cookbook/examples/sec-filing-search/README">
    Search SEC.gov and EDGAR for financial filings with structured data extraction.
  </Card>
</CardGroup>

### Embeddings API

<CardGroup>
  <Card title="Document Q&A" icon="file-lines" href="/docs/cookbook/examples/document-qa/README">
    Self-contained RAG system with contextualized embeddings and Agent API answer generation.
  </Card>
</CardGroup>

## API Key Setup

All examples require a Perplexity API key. Set it as an environment variable:

```bash theme={null}
export PERPLEXITY_API_KEY="your-api-key-here"
```

<Tip>
  Get your API key at [perplexity.ai/account/api](https://perplexity.ai/account/api).
</Tip>

## Common Requirements

* **Python 3.9+** or **Node.js 18+** (depending on the example)
* **Perplexity API Key**
* **Internet connection** for API calls

Additional requirements vary by example and are listed in each project's documentation.

## Contributing

Found a bug or want to add an example? See our [Contributing Guidelines](https://github.com/ppl-ai/api-cookbook/blob/main/CONTRIBUTING.md).


# Agent Research Assistant
Source: https://docs.perplexity.ai/docs/cookbook/examples/agent-research-assistant/README

A CLI tool that uses Perplexity's Agent API with the deep-research preset to conduct multi-step web research and produce structured reports

# Agent Research Assistant

A command-line research tool that leverages Perplexity's Agent API with the `deep-research` preset to conduct thorough, multi-step web research on any topic. The tool produces structured reports with sections, cited sources, and confidence scores.

## Features

* Multi-step web research powered by the `deep-research` preset
* Structured JSON output with sections, sources, and confidence scores using `response_format` with `json_schema`
* Configurable model selection (defaults to `openai/gpt-5.2` via the deep-research preset)
* Clean CLI interface that accepts a topic and outputs a formatted report
* Source tracking with URLs and relevance annotations
* Exportable reports in JSON or plain text

## Installation

<CodeGroup>
  ```bash Python theme={null}
  pip install perplexityai pydantic
  ```

  ```bash TypeScript theme={null}
  npm install @perplexity-ai/perplexity_ai
  ```
</CodeGroup>

## API Key Setup

Set your Perplexity API key as an environment variable. The SDK reads it automatically:

```bash theme={null}
export PERPLEXITY_API_KEY="your_api_key_here"
```

## Usage

```bash theme={null}
# Python
python research_assistant.py "Impact of microplastics on marine ecosystems"

# TypeScript
npx ts-node research_assistant.ts "Impact of microplastics on marine ecosystems"

# Override the default model
python research_assistant.py "Quantum computing breakthroughs" --model openai/gpt-5.4

# Export as JSON
python research_assistant.py "CRISPR gene therapy trials" --json > report.json
```

## How It Works

1. The CLI accepts a research topic as input.
2. A structured JSON schema is defined for the report format using Pydantic (Python) or a TypeScript interface.
3. The tool calls the Agent API with `preset="deep-research"`, which configures the model (`openai/gpt-5.2`), enables `web_search` and `fetch_url` tools, and allows up to 10 reasoning steps.
4. The `response_format` parameter with `json_schema` enforces structured output matching the report schema.
5. The response is parsed and displayed as a formatted research report.

<Info>
  The `deep-research` preset is optimized for complex, in-depth analysis. It uses `openai/gpt-5.2` with up to 10K max tokens and 10 reasoning steps. You can override the model by passing `--model` to the CLI.
</Info>

## Full Code

<CodeGroup>
  ```python Python theme={null}
  import json
  import argparse
  from typing import List, Optional
  from pydantic import BaseModel
  from perplexity import Perplexity


  class ReportSource(BaseModel):
      title: str
      url: str
      relevance: str


  class ReportSection(BaseModel):
      heading: str
      content: str
      confidence: float
      sources: List[ReportSource]


  class ResearchReport(BaseModel):
      title: str
      summary: str
      sections: List[ReportSection]
      conclusion: str
      overall_confidence: float
      total_sources: int


  def run_research(topic: str, model: Optional[str] = None) -> ResearchReport:
      """Conduct deep research on a topic and return a structured report."""
      client = Perplexity()

      params = {
          "preset": "deep-research",
          "input": (
              f"Conduct thorough research on the following topic and produce a "
              f"detailed report with multiple sections, cited sources, and "
              f"confidence scores for each section.\n\nTopic: {topic}"
          ),
          "response_format": {
              "type": "json_schema",
              "json_schema": {
                  "name": "research_report",
                  "schema": ResearchReport.model_json_schema(),
              },
          },
      }

      if model:
          params["model"] = model

      response = client.responses.create(**params)
      return ResearchReport.model_validate_json(response.output_text)


  def format_report(report: ResearchReport) -> str:
      """Format a ResearchReport into human-readable text."""
      lines = [f"{'=' * 60}", f"RESEARCH REPORT: {report.title}", f"{'=' * 60}", ""]
      lines += [f"SUMMARY:", report.summary, ""]

      for i, section in enumerate(report.sections, 1):
          lines.append(f"--- Section {i}: {section.heading} ---")
          lines.append(f"Confidence: {section.confidence:.0%}\n")
          lines.append(section.content)
          if section.sources:
              lines.append("\nSources:")
              for src in section.sources:
                  lines.append(f"  - {src.title} ({src.relevance})")
                  lines.append(f"    {src.url}")
          lines.append("")

      lines += [f"{'=' * 60}", "CONCLUSION:", report.conclusion, ""]
      lines += [f"Overall Confidence: {report.overall_confidence:.0%}"]
      lines += [f"Total Sources: {report.total_sources}", f"{'=' * 60}"]
      return "\n".join(lines)


  def main():
      parser = argparse.ArgumentParser(description="Agent Research Assistant")
      parser.add_argument("topic", help="The research topic")
      parser.add_argument("--model", help="Override the default model", default=None)
      parser.add_argument("--json", action="store_true", help="Output raw JSON")
      args = parser.parse_args()

      print(f"Researching: {args.topic}")
      print("This may take a moment (deep research uses multi-step reasoning)...\n")

      report = run_research(args.topic, model=args.model)

      if args.json:
          print(json.dumps(report.model_dump(), indent=2))
      else:
          print(format_report(report))


  if __name__ == "__main__":
      main()
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from "@perplexity-ai/perplexity_ai";

  interface ReportSource {
    title: string;
    url: string;
    relevance: string;
  }

  interface ReportSection {
    heading: string;
    content: string;
    confidence: number;
    sources: ReportSource[];
  }

  interface ResearchReport {
    title: string;
    summary: string;
    sections: ReportSection[];
    conclusion: string;
    overall_confidence: number;
    total_sources: number;
  }

  const reportSchema = {
    type: "object" as const,
    properties: {
      title: { type: "string" },
      summary: { type: "string" },
      sections: {
        type: "array",
        items: {
          type: "object",
          properties: {
            heading: { type: "string" },
            content: { type: "string" },
            confidence: { type: "number" },
            sources: {
              type: "array",
              items: {
                type: "object",
                properties: {
                  title: { type: "string" },
                  url: { type: "string" },
                  relevance: { type: "string" },
                },
                required: ["title", "url", "relevance"],
              },
            },
          },
          required: ["heading", "content", "confidence", "sources"],
        },
      },
      conclusion: { type: "string" },
      overall_confidence: { type: "number" },
      total_sources: { type: "number" },
    },
    required: ["title", "summary", "sections", "conclusion", "overall_confidence", "total_sources"],
  };

  async function runResearch(topic: string, model?: string): Promise<ResearchReport> {
    const client = new Perplexity();

    const params: Record<string, unknown> = {
      preset: "deep-research",
      input:
        `Conduct thorough research on the following topic and produce a ` +
        `detailed report with multiple sections, cited sources, and ` +
        `confidence scores for each section.\n\nTopic: ${topic}`,
      response_format: {
        type: "json_schema",
        json_schema: { name: "research_report", schema: reportSchema },
      },
    };

    if (model) params.model = model;

    const response = await client.responses.create(params as any);
    return JSON.parse(response.output_text) as ResearchReport;
  }

  async function main() {
    const topic = process.argv[2];
    if (!topic) {
      console.error("Usage: ts-node research_assistant.ts <topic> [--model <model>] [--json]");
      process.exit(1);
    }

    const modelIdx = process.argv.indexOf("--model");
    const model = modelIdx !== -1 ? process.argv[modelIdx + 1] : undefined;
    const outputJson = process.argv.includes("--json");

    console.log(`Researching: ${topic}`);
    console.log("This may take a moment (deep research uses multi-step reasoning)...\n");

    const report = await runResearch(topic, model);

    if (outputJson) {
      console.log(JSON.stringify(report, null, 2));
    } else {
      console.log(`RESEARCH REPORT: ${report.title}\n`);
      console.log(`SUMMARY: ${report.summary}\n`);
      report.sections.forEach((s, i) => {
        console.log(`--- Section ${i + 1}: ${s.heading} (${(s.confidence * 100).toFixed(0)}%) ---`);
        console.log(s.content);
        s.sources.forEach((src) => console.log(`  - ${src.title}: ${src.url}`));
        console.log();
      });
      console.log(`CONCLUSION: ${report.conclusion}`);
      console.log(`Overall Confidence: ${(report.overall_confidence * 100).toFixed(0)}%`);
    }
  }

  main();
  ```
</CodeGroup>

## Example Output

```bash theme={null}
python research_assistant.py "Impact of microplastics on marine ecosystems"
```

```
Researching: Impact of microplastics on marine ecosystems
This may take a moment (deep research uses multi-step reasoning)...

============================================================
RESEARCH REPORT: Impact of Microplastics on Marine Ecosystems
============================================================

SUMMARY:
Microplastics have become a pervasive pollutant in marine environments
worldwide, affecting organisms from plankton to large marine mammals.

--- Section 1: Sources and Distribution ---
Confidence: 92%

Microplastics originate from the degradation of larger plastic debris,
synthetic textiles, industrial processes, and cosmetic products...

Sources:
  - NOAA Marine Debris Program (high)
    https://marinedebris.noaa.gov/...

--- Section 2: Biological Effects on Marine Organisms ---
Confidence: 88%

Research demonstrates that microplastics affect marine life at multiple
trophic levels...

Sources:
  - Environmental Science & Technology (high)
    https://pubs.acs.org/...

============================================================
CONCLUSION:
Microplastics pose a significant and growing threat to marine ecosystems.

Overall Confidence: 89%
Total Sources: 12
============================================================
```

<Tip>
  For shorter, faster research tasks, consider using the `pro-search` preset instead. It uses `openai/gpt-5.4` with up to 3 reasoning steps -- a good balance of speed and thoroughness.
</Tip>

<Warning>
  The first request with a new JSON Schema may take 10 to 30 seconds to prepare. Subsequent requests with the same schema will not see this delay. See the [structured outputs guide](/docs/agent-api/output-control#structured-outputs) for details.
</Warning>

## Limitations

* Deep research requests consume more tokens and cost more than standard requests due to multi-step reasoning and tool usage.
* Structured output with JSON schema requires the model to adhere to the schema. Very complex schemas may reduce output quality.
* Confidence scores are model-generated estimates and should be treated as relative indicators, not absolute measures.
* The quality of research depends on the availability and quality of web sources for the given topic.


# Daily Knowledge Bot
Source: https://docs.perplexity.ai/docs/cookbook/examples/daily-knowledge-bot/README

A Python application that delivers interesting facts about rotating topics using the Perplexity AI API

# Daily Knowledge Bot

A Python application that delivers interesting facts about rotating topics using the Perplexity AI API. Perfect for daily learning, newsletter content, or personal education.

## 🌟 Features

* **Daily Topic Rotation**: Automatically selects topics based on the day of the month
* **AI-Powered Facts**: Uses Perplexity's Sonar API to generate interesting and accurate facts
* **Customizable Topics**: Easily extend or modify the list of topics
* **Persistent Storage**: Saves facts to dated text files for future reference
* **Robust Error Handling**: Gracefully manages API failures and unexpected errors
* **Configurable**: Uses environment variables for secure API key management

## 📋 Requirements

* Python 3.6+
* Required packages:
  * requests
  * python-dotenv
  * (optional) logging

## 🚀 Installation

1. Clone this repository or download the script
2. Install the required packages:

```bash theme={null}
# Install from requirements file (recommended)
pip install -r requirements.txt

# Or install manually
pip install requests python-dotenv
```

3. Set up your Perplexity API key:
   * Create a `.env` file in the same directory as the script
   * Add your API key: `PERPLEXITY_API_KEY=your_api_key_here`

## 🔧 Usage

### Running the Bot

Simply execute the script:

```bash theme={null}
python daily_knowledge_bot.py
```

This will:

1. Select a topic based on the current day
2. Fetch an interesting fact from Perplexity AI
3. Save the fact to a dated text file in your current directory
4. Display the fact in the console

### Customizing Topics

Edit the `topics.txt` file (one topic per line) or modify the `topics` list directly in the script.

Example topics:

```
astronomy
history
biology
technology
psychology
ocean life
ancient civilizations
quantum physics
art history
culinary science
```

### Automated Scheduling

#### On Linux/macOS (using cron):

```bash theme={null}
# Edit your crontab
crontab -e

# Add this line to run daily at 8:00 AM
0 8 * * * /path/to/python3 /path/to/daily_knowledge_bot.py
```

#### On Windows (using Task Scheduler):

1. Open Task Scheduler
2. Create a new Basic Task
3. Set it to run daily
4. Add the action: Start a program
5. Program/script: `C:\path\to\python.exe`
6. Arguments: `C:\path\to\daily_knowledge_bot.py`

## 🔍 Configuration Options

The following environment variables can be set in your `.env` file:

* `PERPLEXITY_API_KEY` (required): Your Perplexity API key
* `OUTPUT_DIR` (optional): Directory to save fact files (default: current directory)
* `TOPICS_FILE` (optional): Path to your custom topics file

## 📄 Output Example

```
DAILY FACT - 2025-04-02
Topic: astronomy

Saturn's iconic rings are relatively young, potentially forming only 100 million years ago. This means dinosaurs living on Earth likely never saw Saturn with its distinctive rings, as they may have formed long after the dinosaurs went extinct. The rings are made primarily of water ice particles ranging in size from tiny dust grains to boulder-sized chunks.
```

## 🛠️ Extending the Bot

Some ways to extend this bot:

* Add email or SMS delivery capabilities
* Create a web interface to view fact history
* Integrate with social media posting
* Add multimedia content based on the facts
* Implement advanced scheduling with specific topics on specific days

## ⚠️ Limitations

* API rate limits may apply based on your Perplexity account
* Quality of facts depends on the AI model
* The free version of the Sonar API has a token limit that may truncate longer responses

## 📜 License

[MIT License](https://github.com/ppl-ai/api-cookbook/blob/main/LICENSE)

## 🙏 Acknowledgements

* This project uses the Perplexity AI API ([https://docs.perplexity.ai/](https://docs.perplexity.ai/))
* Inspired by daily knowledge calendars and fact-of-the-day services


# Perplexity Discord Bot
Source: https://docs.perplexity.ai/docs/cookbook/examples/discord-py-bot/README

A simple discord.py bot that integrates Perplexity's Sonar API to bring AI answers to your Discord server.

A simple `discord.py` bot that integrates [Perplexity's Sonar API](https://docs.perplexity.ai/) into your Discord server. Ask questions and get AI-powered answers with web access through slash commands or by mentioning the bot.

<img alt="Discord Bot Demo" />

## ✨ Features

* **🌐 Web-Connected AI**: Uses Perplexity's Sonar API for up-to-date information
* **⚡ Slash Command**: Simple `/ask` command for questions
* **💬 Mention Support**: Ask questions by mentioning the bot
* **🔗 Source Citations**: Automatically formats and links to sources
* **🔒 Secure Setup**: Environment-based configuration for API keys

## 🛠️ Prerequisites

<Steps>
  <Step title="Python Environment">
    **Python 3.8+** installed on your system

    ```bash theme={null}
    python --version  # Should be 3.8 or higher
    ```
  </Step>

  <Step title="Perplexity API Access">
    **Active Perplexity API Key** from the [Perplexity API Platform console](https://console.perplexity.ai)

    <Note>You'll need a paid Perplexity account to access the API. See the [pricing page](https://www.perplexity.ai/pricing) for current rates.</Note>
  </Step>

  <Step title="Discord Bot Application">
    **Discord Bot Token** from the [Discord Developer Portal](https://discord.com/developers/applications)
  </Step>
</Steps>

## 🚀 Quick Start

### 1. Repository Setup

Clone the repository and navigate to the bot directory:

```bash theme={null}
git clone https://github.com/ppl-ai/api-cookbook.git
cd api-cookbook/docs/examples/discord-py-bot/
```

### 2. Install Dependencies

```bash theme={null}
# Create a virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install required packages
pip install -r requirements.txt
```

### 3. Configure API Keys

<Steps>
  <Step title="Get Your Perplexity API Key">
    1. Visit the [Perplexity API Platform console](https://console.perplexity.ai)
    2. Generate a new API key
    3. Copy the key to the .env file

    <Warning>Keep your API key secure! Never commit it to version control or share it publicly.</Warning>
  </Step>

  <Step title="Create Discord Bot Application">
    1. Go to the [Discord Developer Portal](https://discord.com/developers/applications)
    2. Click **"New Application"** and give it a descriptive name
    3. Navigate to the **"Bot"** section
    4. Click **"Reset Token"** (or "Add Bot" if first time)
    5. Copy the bot token
  </Step>

  <Step title="Configure Environment Variables">
    Copy the example environment file and add your keys:

    ```bash theme={null}
    cp env.example .env
    ```

    Edit `.env` with your credentials:

    ```bash title=".env" theme={null}
    DISCORD_TOKEN="your_discord_bot_token_here"
    PERPLEXITY_API_KEY="your_perplexity_api_key_here"
    ```
  </Step>
</Steps>

## 🎯 Usage Guide

### Bot Invitation & Setup

<Steps>
  <Step title="Generate Invite URL">
    In the Discord Developer Portal:

    1. Go to **OAuth2** → **URL Generator**
    2. Select scopes: `bot` and `applications.commands`
    3. Select bot permissions: `Send Messages`, `Use Slash Commands`
    4. Copy the generated URL
  </Step>

  <Step title="Invite to Server">
    1. Paste the URL in your browser
    2. Select the Discord server to add the bot to
    3. Confirm the permissions
  </Step>

  <Step title="Start the Bot">
    ```bash theme={null}
    python bot.py
    ```

    You should see output confirming the bot is online and commands are synced.
  </Step>
</Steps>

### How to Use

**Slash Command:**

```
/ask [your question here]
```

<img alt="Slash Command Demo" />

**Mention the Bot:**

```
@YourBot [your question here]
```

<img alt="Mention Command Demo" />

## 📊 Response Format

The bot provides clean, readable responses with:

* **AI Answer**: Direct response from Perplexity's Sonar API
* **Source Citations**: Clickable links to sources (when available)
* **Automatic Truncation**: Responses are trimmed to fit Discord's limits

## 🔧 Technical Details

This bot uses:

* **Model**: Perplexity's `sonar-pro` model
* **Response Limit**: 2000 tokens from API, truncated to fit Discord
* **Temperature**: 0.2 for consistent, factual responses
* **No Permissions**: Anyone in the server can use the bot


# Disease Information App
Source: https://docs.perplexity.ai/docs/cookbook/examples/disease-qa/README

An interactive browser-based application that provides structured information about diseases using Perplexity's Sonar API

# Disease Information App

An interactive browser-based application that provides structured information about diseases using Perplexity's Sonar API. This app generates a standalone HTML interface that allows users to ask questions about various diseases and receive organized responses with citations.

## 🌟 Features

* **User-Friendly Interface**: Clean, responsive design that works across devices
* **AI-Powered Responses**: Leverages Perplexity's Sonar API for accurate medical information
* **Structured Knowledge Cards**: Organizes information into Overview, Causes, and Treatments
* **Citation Tracking**: Lists sources of information with clickable links
* **Client-Side Caching**: Prevents duplicate API calls for previously asked questions
* **Standalone Deployment**: Generate a single HTML file that can be used without a server
* **Comprehensive Error Handling**: User-friendly error messages and robust error management

## 📋 Requirements

* Python 3.6+
* Jupyter Notebook or JupyterLab (for development/generation)
* Required packages:
  * requests
  * pandas
  * python-dotenv
  * IPython

## 🚀 Setup & Installation

1. Clone this repository or download the notebook
2. Install the required packages:

```bash theme={null}
# Install from requirements file (recommended)
pip install -r requirements.txt

# Or install manually
pip install requests pandas python-dotenv ipython
```

3. Set up your Perplexity API key:
   * Create a `.env` file in the same directory as the notebook
   * Add your API key: `PERPLEXITY_API_KEY=your_api_key_here`

## 🔧 Usage

### Running the Notebook

1. Open the notebook in Jupyter:

```bash theme={null}
jupyter notebook Disease_Information_App.ipynb
```

2. Run all cells to generate and launch the browser-based application
3. The app will automatically open in your default web browser

### Using the Generated HTML

You can also directly use the generated `disease_qa.html` file:

1. Open it in any modern web browser
2. Enter a question about a disease (e.g., "What is diabetes?", "Tell me about Alzheimer's disease")
3. Click "Ask" to get structured information about the disease

### Deploying the App

For personal or educational use, simply share the generated HTML file.

For production use, consider:

1. Setting up a proper backend to secure your API key
2. Hosting the file on a web server
3. Adding analytics and user management as needed

## 🔍 How It Works

This application:

1. Uses a carefully crafted prompt to instruct the AI to output structured JSON
2. Processes this JSON to extract Overview, Causes, Treatments, and Citations
3. Presents the information in a clean knowledge card format
4. Implements client-side API calls with proper error handling
5. Provides a responsive design suitable for both desktop and mobile

## ⚙️ Technical Details

### API Structure

The app expects the AI to return a JSON object with this structure:

```json theme={null}
{
  "overview": "A brief description of the disease.",
  "causes": "The causes of the disease.",
  "treatments": "Possible treatments for the disease.",
  "citations": ["https://example.com/citation1", "https://example.com/citation2"]
}
```

### Files Generated

* `disease_qa.html` - The standalone application
* `disease_app.log` - Detailed application logs (when running the notebook)

### Customization Options

You can modify:

* The HTML/CSS styling in the `create_html_ui` function
* The AI model used (default is "sonar-pro")
* The structure of the prompt for different information fields
* Output file location and naming

## 🛠️ Extending the App

Potential extensions:

* Add a Flask/Django backend to secure the API key
* Implement user accounts and saved questions
* Add visualization of disease statistics
* Create a comparison view for multiple diseases
* Add natural language question reformatting
* Implement feedback mechanisms for answer quality

## ⚠️ Important Notes

* **API Key Security**: The current implementation embeds your API key in the HTML file. This is suitable for personal use but not for public deployment.
* **Not Medical Advice**: This app provides general information and should not be used for medical decisions. Always consult healthcare professionals for medical advice.
* **API Usage**: Be aware of Perplexity API rate limits and pricing for your account.

## 📜 License

[MIT License](https://github.com/ppl-ai/api-cookbook/blob/main/LICENSE)

## 🙏 Acknowledgements

* This project uses the [Perplexity AI Sonar API](https://docs.perplexity.ai/)
* Inspired by interactive knowledge bases and medical information platforms


# Document Q&A with Embeddings
Source: https://docs.perplexity.ai/docs/cookbook/examples/document-qa/README

A self-contained RAG system that ingests documents, generates contextualized embeddings, and answers questions using the Agent API

# Document Q\&A with Embeddings

A self-contained retrieval-augmented generation (RAG) system that ingests documents, generates contextualized embeddings for semantic search, and produces grounded answers using the Agent API.

## Features

* Ingest plain-text documents and automatically split them into chunks
* Generate document-aware embeddings using `pplx-embed-context-v1-4b`
* In-memory vector store with numpy cosine similarity search
* Answer generation via the Agent API with `anthropic/claude-sonnet-4-6`
* Full working pipeline: load, chunk, embed, query, answer

## Architecture

**Indexing:** Load documents, split into overlapping chunks, embed with contextualized embeddings, store in memory.

**Query:** Embed the user question, compute cosine similarity, retrieve top-k chunks, generate an answer with the Agent API.

<Info>
  Contextualized embeddings produce higher-quality representations than standard embeddings for document chunks because the model understands that chunks belong to the same document.
</Info>

## Installation

```bash theme={null}
pip install perplexityai numpy
```

```bash theme={null}
export PERPLEXITY_API_KEY="your_api_key_here"
```

## Usage

Save the full code below to `document_qa.py` and run:

```bash theme={null}
python document_qa.py
```

For interactive mode:

```bash theme={null}
python document_qa.py --interactive
```

## Full Code

```python theme={null}
import base64
import sys
import numpy as np
from perplexity import Perplexity

client = Perplexity()

# --- Chunking ---

def chunk_text(text, chunk_size=300, overlap=50):
    """Split text into overlapping chunks by word count."""
    words = text.split()
    chunks, start = [], 0
    while start < len(words):
        chunks.append(" ".join(words[start : start + chunk_size]))
        start += chunk_size - overlap
    return chunks

# --- Embedding helpers ---

def decode_embedding(b64_string):
    """Decode a base64-encoded int8 embedding to float32."""
    return np.frombuffer(base64.b64decode(b64_string), dtype=np.int8).astype(np.float32)

def cosine_similarity(a, b):
    return np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))

# --- Build index ---

def build_index(documents, chunk_size=300, overlap=50):
    """Chunk documents and generate contextualized embeddings."""
    all_doc_chunks, metadata = [], []
    for doc in documents:
        chunks = chunk_text(doc["content"], chunk_size, overlap)
        all_doc_chunks.append(chunks)
        metadata.append({"title": doc["title"], "chunks": chunks})

    print(f"Embedding {sum(len(c) for c in all_doc_chunks)} chunks...")
    response = client.contextualized_embeddings.create(
        input=all_doc_chunks,
        model="pplx-embed-context-v1-4b"
    )

    index = []
    for doc_obj in response.data:
        meta = metadata[doc_obj.index]
        for chunk_obj in doc_obj.data:
            index.append({
                "text": meta["chunks"][chunk_obj.index],
                "embedding": decode_embedding(chunk_obj.embedding),
                "doc_title": meta["title"],
            })
    print(f"Index built: {len(index)} chunks.")
    return index

# --- Retrieve ---

def retrieve(index, query_text, top_k=3):
    """Embed the query and return the top-k most similar chunks."""
    qr = client.contextualized_embeddings.create(
        input=[[query_text]], model="pplx-embed-context-v1-4b"
    )
    q_emb = decode_embedding(qr.data[0].data[0].embedding)
    scored = sorted(
        [{**item, "score": float(cosine_similarity(q_emb, item["embedding"]))} for item in index],
        key=lambda x: x["score"], reverse=True,
    )
    return scored[:top_k]

# --- Generate answer ---

def generate_answer(query_text, chunks):
    """Send retrieved context to the Agent API for answer generation."""
    context = "\n\n".join(
        f"[Source {i}: {c['doc_title']}]\n{c['text']}" for i, c in enumerate(chunks, 1)
    )
    response = client.responses.create(
        model="anthropic/claude-sonnet-4-6",
        input=[{
            "role": "user",
            "content": (
                f"Answer the following question based ONLY on the provided context. "
                f"If the context does not contain enough information, say so.\n\n"
                f"Context:\n{context}\n\nQuestion: {query_text}"
            ),
        }],
        instructions=(
            "You are a precise document Q&A assistant. Answer using only the "
            "provided context. Cite source numbers. Be concise."
        ),
        max_output_tokens=1024,
    )
    return response.output_text

# --- Full pipeline ---

def query(index, query_text, top_k=3):
    print(f"\nQuery: {query_text}")
    retrieved = retrieve(index, query_text, top_k)
    for r in retrieved:
        print(f"  [{r['doc_title']}] score={r['score']:.4f}: {r['text'][:70]}...")
    return generate_answer(query_text, retrieved)

# --- Sample documents ---

sample_documents = [
    {
        "title": "Introduction to Transformers",
        "content": (
            "The Transformer architecture was introduced in the paper Attention Is All "
            "You Need by Vaswani et al. in 2017. It replaced recurrent layers with "
            "self-attention mechanisms, enabling parallel processing of input sequences. "
            "The key innovation is multi-head attention, which allows the model to attend "
            "to information from different representation subspaces. Transformers consist "
            "of an encoder and decoder with stacked layers of multi-head attention and "
            "feed-forward sub-layers. The architecture has become the foundation for "
            "modern language models including BERT, GPT, and T5."
        ),
    },
    {
        "title": "Retrieval-Augmented Generation",
        "content": (
            "Retrieval-Augmented Generation (RAG) combines information retrieval with "
            "text generation. Instead of relying solely on knowledge stored in model "
            "parameters, RAG systems retrieve relevant documents from an external "
            "knowledge base and use them as context. This reduces hallucination because "
            "the model grounds its responses in retrieved evidence. A typical RAG "
            "pipeline has three stages: indexing, retrieval, and generation. During "
            "indexing, documents are chunked and embedded into a vector store. At query "
            "time, the question is embedded and compared against stored vectors. The "
            "most relevant chunks are prepended to the prompt for answer generation."
        ),
    },
]

if __name__ == "__main__":
    index = build_index(sample_documents)
    if "--interactive" in sys.argv:
        print("\nInteractive mode. Type 'quit' to exit.\n")
        while True:
            q = input("Question: ").strip()
            if q.lower() in ("quit", "exit", "q"):
                break
            if q:
                print(f"\nAnswer:\n{query(index, q)}\n")
    else:
        answer = query(index, "How does RAG reduce hallucination?")
        print(f"\nAnswer:\n{answer}")
```

## Example Output

```
Embedding 4 chunks across 2 documents...
Index built: 4 chunks.

Query: How does RAG reduce hallucination?
  [Retrieval-Augmented Generation] score=0.8432: Retrieval-Augmented Generation (RAG) combines information retrieval w...
  [Retrieval-Augmented Generation] score=0.7891: most relevant chunks are prepended to the prompt for answer generatio...
  [Introduction to Transformers] score=0.6104: The Transformer architecture was introduced in the paper Attention Is...

Answer:
RAG reduces hallucination by grounding the model's responses in retrieved evidence
rather than relying solely on knowledge stored in model parameters [Source 1]. The
most relevant document chunks are prepended to the prompt, so the language model bases
its answers on concrete textual evidence from the knowledge base [Source 2].
```

<Tip>
  For production workloads, replace the in-memory numpy index with a dedicated vector database such as Pinecone, Weaviate, or Qdrant. The embedding and retrieval logic remains the same.
</Tip>

<Warning>
  Contextualized embeddings require that chunks within each document are sent in their original sequential order. Shuffling chunks will degrade embedding quality.
</Warning>

## Limitations

* The in-memory store is suitable for prototyping but will not scale to large collections. Use a vector database for production.
* Chunk size and overlap may need tuning for your documents. Shorter chunks improve precision; longer chunks preserve context.
* The `pplx-embed-context-v1-4b` model has a 32K token context window per document.
* Answer quality depends on retrieval quality. If the wrong chunks are retrieved, the answer will reflect that.


# Equity Research Brief
Source: https://docs.perplexity.ai/docs/cookbook/examples/equity-research-brief/README

Generate institutional-grade equity research briefs from any public ticker using the Perplexity Agent API and the built-in finance_search tool.

# Equity Research Brief

A command-line tool that generates a structured equity research brief for any public ticker using Perplexity's [Agent API](https://docs.perplexity.ai/docs/agent-api/quickstart) and the built-in [`finance_search`](https://docs.perplexity.ai/docs/agent-api/tools/finance-search) tool.

`finance_search` returns structured market data — quotes, financials, earnings transcripts, peer comparisons, analyst estimates — so the model can compose a report grounded in numbers, not just narrative. The tool is purpose-built for agentic investor workflows.

## Features

* One command produces a 6-section brief: snapshot, business overview, financial trajectory, latest earnings, peer context, risks, bottom line
* Uses the Agent API's `finance_search` tool for structured fundamentals, quotes, and earnings-call transcripts
* Three preset configurations matching the official `finance_search` recommendations:
  * `quote` — live price/quote only, fastest and cheapest
  * `single` — single-company historical lookup with web context
  * `research` — full multi-step cross-company brief (default)
* Prints citation-ready Perplexity finance source URLs alongside the brief
* Reports `finance_search` invocation count and total request cost
* `--json` flag emits the raw Agent API response for downstream pipelines

## Prerequisites

* Python 3.9+
* A Perplexity API key with Agent API access. `finance_search` is currently in beta — see the [Finance Search docs](https://docs.perplexity.ai/docs/agent-api/tools/finance-search) for availability.

## Installation

```bash theme={null}
cd docs/examples/equity-research-brief
pip install -r requirements.txt
chmod +x equity_research_brief.py
```

## API Key Setup

```bash theme={null}
export PERPLEXITY_API_KEY="your-api-key-here"
```

You can also pass the key via `--api-key`, or place it in a `.pplx_api_key` file in the working directory.

## Quick Start

Generate a full research brief on NVIDIA:

```bash theme={null}
./equity_research_brief.py NVDA
```

## Usage

```bash theme={null}
./equity_research_brief.py TICKER [--config {quote,single,research}] [--json] [--api-key KEY]
```

### Just a live quote (cheapest, \~1 tool call)

```bash theme={null}
./equity_research_brief.py AAPL --config quote
```

### Single-company historical lookup with web context

```bash theme={null}
./equity_research_brief.py MSFT --config single
```

### Full multi-step research brief (default)

```bash theme={null}
./equity_research_brief.py NVDA --config research
```

### Emit raw Agent API JSON

```bash theme={null}
./equity_research_brief.py TSLA --json | jq '.usage.cost'
```

## Configuration Reference

| Config     | Model                       | Tools                                         | Max steps | Best for                              |
| ---------- | --------------------------- | --------------------------------------------- | --------- | ------------------------------------- |
| `quote`    | `perplexity/sonar`          | `finance_search`                              | 1         | Live prices, quotes, fastest path     |
| `single`   | `openai/gpt-5.5`            | `web_search` + `finance_search` + `fetch_url` | 5         | One-company historical fundamentals   |
| `research` | `anthropic/claude-opus-4-7` | `web_search` + `finance_search` + `fetch_url` | 10        | Multi-company comparisons, full brief |

These configurations are taken directly from the [`finance_search` recommended configurations](https://docs.perplexity.ai/docs/agent-api/tools/finance-search).

## Example Output (truncated)

```
## 1. Snapshot

- **Price:** $200.23 (as of 2026-05-01 14:10 UTC)
- **Market cap:** $4.87T
- **P/E (TTM):** 40.86
- **52-week range:** $110.82 – $216.83

## 2. Business overview

NVIDIA designs accelerated computing platforms — GPUs, networking, and full-stack
software — used in AI training and inference, gaming, professional visualization,
and automotive. Data Center is the dominant revenue line.

## 3. Financial trajectory
| FY    | Revenue     | Operating margin | Net income |
| ----- | ----------- | ---------------- | ---------- |
| FY25  | $130.5B     | 62.4%            | $72.9B     |
...

---
finance_search: 4 invocation(s) across categories [earnings_history, financials, profile, quote]

Finance sources:
  - https://www.perplexity.ai/finance/NVDA
  - https://www.perplexity.ai/finance/NVDA/earnings?eventId=409967
  - ...

Cost: 0.2817 USD
```

## Code Walkthrough

The script does three things:

**1. Issue a single Agent API call with `finance_search` enabled.**

```python theme={null}
from perplexity import Perplexity

client = Perplexity()
response = client.responses.create(
    model="anthropic/claude-opus-4-7",
    instructions=SYSTEM_PROMPT,
    input=BRIEF_TEMPLATE.format(ticker="NVDA"),
    tools=[
        {"type": "web_search"},
        {"type": "finance_search"},
        {"type": "fetch_url"},
    ],
    max_output_tokens=4096,
    max_steps=10,
)
```

The model decides which `finance_search` categories to fetch (quote, financials, transcript, etc.) based on the prompt. You don't need to hand-pick fields.

**2. Walk `response.output` to extract both the assistant text and the structured `finance_results` blocks.**

```python theme={null}
for item in response.output:
    if item.type == "finance_results":
        for r in item.results:
            print(r.category, r.tickers, r.sources)
    elif item.type == "message":
        for block in item.content:
            if block.type == "output_text":
                print(block.text)
```

**3. Surface cost and finance source URLs alongside the prose.** The Perplexity finance pages returned in `result.sources` are stable, citation-ready links — useful when the brief is consumed by humans or by a downstream RAG pipeline.

## Prompting Guidance

`finance_search` works best when the prompt asks for a business outcome, not for specific data shapes. The system prompt instructs the model to:

* be quantitative and attribute numbers to the right period (e.g. `FY2025`, `Q3 FY26`)
* never invent numbers — if `finance_search` doesn't return a field, say so explicitly
* format the output in clean Markdown

This pattern is documented in the [finance\_search prompt guidance](https://docs.perplexity.ai/docs/agent-api/tools/finance-search#prompt-guidance).

## Pricing

`finance_search` is billed at **\$5 per 1,000 invocations**, separate from model token usage. Each preset has different cost characteristics:

* `quote`: typically 1 invocation, \~\$0.007 per brief
* `single`: 1–3 invocations + GPT-5.5 tokens
* `research`: 3–6 invocations + Claude Opus tokens

See [Perplexity Pricing](https://docs.perplexity.ai/docs/getting-started/pricing) for current rates.

## Limitations

* `finance_search` is currently in beta and may not be enabled on all API keys
* Results depend on Perplexity's finance data coverage; obscure or non-US tickers may return less structured data
* This is not investment advice. The "Bottom line" section is explicitly framed as analytical opinion, not a recommendation

## Resources

* [Agent API Quickstart](https://docs.perplexity.ai/docs/agent-api/quickstart)
* [Finance Search Tool](https://docs.perplexity.ai/docs/agent-api/tools/finance-search)
* [Web Search Tool](https://docs.perplexity.ai/docs/agent-api/tools/web-search)
* [Perplexity Python SDK](https://pypi.org/project/perplexityai/)


# Fact Checker CLI
Source: https://docs.perplexity.ai/docs/cookbook/examples/fact-checker-cli/README

A command-line tool that identifies false or misleading claims in articles or statements using Perplexity's Sonar API

# Fact Checker CLI

A command-line tool that identifies false or misleading claims in articles or statements using Perplexity's Sonar API for web research.

## Features

* Analyze claims or entire articles for factual accuracy
* Identify false, misleading, or unverifiable claims
* Provide explanations and corrections for inaccurate information
* Output results in human-readable format or structured JSON
* Cite reliable sources for fact-checking assessments
* Leverages Perplexity's structured outputs for reliable JSON parsing (for Tier 3+ users)

## Installation

### 1. Install required dependencies

```bash theme={null}
# Install from requirements file (recommended)
pip install -r requirements.txt

# Or install manually
pip install requests pydantic newspaper3k
```

### 2. Make the script executable

```bash theme={null}
chmod +x fact_checker.py
```

## API Key Setup

The tool requires a Perplexity API key to function. You can provide it in one of these ways:

### 1. As a command-line argument

```bash theme={null}
./fact_checker.py --api-key YOUR_API_KEY
```

### 2. As an environment variable

```bash theme={null}
export PPLX_API_KEY=YOUR_API_KEY
```

### 3. In a file

Create a file named `pplx_api_key` or `.pplx_api_key` in the same directory as the script:

```bash theme={null}
echo "YOUR_API_KEY" > .pplx_api_key
chmod 600 .pplx_api_key
```

**Note:** If you're using the structured outputs feature, you'll need a Perplexity API account with Tier 3 or higher access level.

## Quick Start

Run the following command immediately after setup:

```bash theme={null}
./fact_checker.py -t "The Earth is flat and NASA is hiding the truth."
```

This will analyze the claim, research it using Perplexity's Sonar API, and return a detailed fact check with ratings, explanations, and sources.

## Usage

### Check a claim

```bash theme={null}
./fact_checker.py --text "The Earth is flat and NASA is hiding the truth."
```

### Check an article from a file

```bash theme={null}
./fact_checker.py --file article.txt
```

### Check an article from a URL

```bash theme={null}
./fact_checker.py --url https://www.example.com/news/article-to-check
```

### Specify a different model

```bash theme={null}
./fact_checker.py --text "Global temperatures have decreased over the past century." --model "sonar-pro"
```

### Output results as JSON

```bash theme={null}
./fact_checker.py --text "Mars has a breathable atmosphere." --json
```

### Use a custom prompt file

```bash theme={null}
./fact_checker.py --text "The first human heart transplant was performed in the United States." --prompt-file custom_prompt.md
```

### Enable structured outputs (for Tier 3+ users)

Structured output is disabled by default. To enable it, pass the `--structured-output` flag:

```bash theme={null}
./fact_checker.py --text "Vaccines cause autism." --structured-output
```

### Get help

```bash theme={null}
./fact_checker.py --help
```

## Output Format

The tool provides output including:

* **Overall Rating**: MOSTLY\_TRUE, MIXED, or MOSTLY\_FALSE
* **Summary**: A brief overview of the fact-checking findings
* **Claims Analysis**: A list of specific claims with individual ratings:
  * TRUE: Factually accurate and supported by evidence
  * FALSE: Contradicted by evidence
  * MISLEADING: Contains some truth but could lead to incorrect conclusions
  * UNVERIFIABLE: Cannot be conclusively verified with available information
* **Explanations**: Detailed reasoning for each claim
* **Sources**: Citations and URLs used for verification

## Example

Run the following command:

```bash theme={null}
./fact_checker.py -t "The Great Wall of China is visible from the moon."
```

Example output:

```
Fact checking in progress...

🔴 OVERALL RATING: MOSTLY_FALSE

📝 SUMMARY:
The claim that the Great Wall of China is visible from the moon is false. This is a common misconception that has been debunked by NASA astronauts and scientific evidence.

🔍 CLAIMS ANALYSIS:

Claim 1: ❌ FALSE  
  Statement: "The Great Wall of China is visible from the moon."  
  Explanation: The Great Wall of China is not visible from the moon with the naked eye. NASA astronauts have confirmed this, including Neil Armstrong who stated he could not see the Wall from lunar orbit. The Wall is too narrow and is similar in color to its surroundings when viewed from such a distance.  
  Sources:
    - NASA.gov
    - Scientific American
    - National Geographic
```

## Limitations

* The accuracy of fact-checking depends on the quality of information available through the Perplexity Sonar API.
* Like all language models, the underlying AI may have limitations in certain specialized domains.
* The structured outputs feature requires a Tier 3 or higher Perplexity API account.
* The tool does not replace professional fact-checking services for highly sensitive or complex content.


# Document Q&A
Source: https://docs.perplexity.ai/docs/cookbook/examples/file-attachment-qa/README

Load documents and ask questions about them via the Agent API — text extraction, web search enrichment, multi-turn Q&A, and structured output extraction

# Document Q\&A

Load a document and ask questions about it using the Agent API. This example shows how to read document content, combine it with web search for enriched answers, and build a multi-turn Q\&A session over document content.

## Features

* Load documents (text, CSV, JSON, markdown) and pass content to the Agent API
* Ask questions grounded in the document content
* Optionally combine with `web_search` for context enrichment
* Multi-turn conversation to drill into specific sections
* Structured output extraction from document content

<Info>
  Pass document content directly in the `input` parameter of the Agent API. For text-based formats, read the file and include it in the prompt. Combine with `web_search` for context enrichment beyond the document.
</Info>

## Installation

```bash theme={null}
pip install perplexityai
```

```bash theme={null}
export PERPLEXITY_API_KEY="your_api_key_here"
```

## Usage

Save the full code below to `doc_qa.py` and run:

```bash theme={null}
python doc_qa.py report.txt "What are the key findings in this report?"
```

For interactive mode:

```bash theme={null}
python doc_qa.py report.txt --interactive
```

## Full Code

<CodeGroup>
  ```python Python theme={null}
  import sys
  import json
  import argparse
  from pathlib import Path
  from perplexity import Perplexity

  client = Perplexity()

  MAX_CONTENT_CHARS = 50000  # Truncate very large files to stay within token limits


  def read_document(file_path: str) -> str:
      """Read a document file and return its text content."""
      path = Path(file_path)
      content = path.read_text(errors="replace")
      if len(content) > MAX_CONTENT_CHARS:
          content = content[:MAX_CONTENT_CHARS] + "\n\n[... truncated ...]"
      return content


  def ask_about_document(
      file_path: str,
      question: str,
      use_web_search: bool = False,
      conversation_history: list = None,
  ) -> dict:
      """Ask a question about a document's content."""
      doc_content = read_document(file_path)
      filename = Path(file_path).name

      # Build the input with document content and question
      full_input = (
          f"Document: {filename}\n"
          f"{'='*60}\n"
          f"{doc_content}\n"
          f"{'='*60}\n\n"
          f"Question: {question}"
      )

      # Include conversation history for multi-turn
      if conversation_history:
          messages = conversation_history + [{"role": "user", "content": full_input}]
          response = client.responses.create(
              model="openai/gpt-5.4",
              input=messages,
              tools=[{"type": "web_search"}] if use_web_search else [],
              instructions="Answer questions based on the provided document content. Be specific and cite sections when possible.",
          )
      else:
          response = client.responses.create(
              model="openai/gpt-5.4",
              input=full_input,
              tools=[{"type": "web_search"}] if use_web_search else [],
              instructions="Answer questions based on the provided document content. Be specific and cite sections when possible.",
          )

      usage = response.usage
      return {
          "answer": response.output_text,
          "model": response.model,
          "tokens": {
              "input": usage.input_tokens if usage else 0,
              "output": usage.output_tokens if usage else 0,
          },
      }


  def extract_structured_data(file_path: str, schema_name: str, schema: dict) -> dict:
      """Extract structured data from a document using a JSON schema."""
      doc_content = read_document(file_path)

      response = client.responses.create(
          model="openai/gpt-5.4",
          input=f"Extract the requested structured data from this document:\n\n{doc_content}",
          response_format={
              "type": "json_schema",
              "json_schema": {"name": schema_name, "schema": schema},
          },
      )

      return json.loads(response.output_text)


  def interactive_session(file_path: str, use_web_search: bool = False):
      """Run an interactive Q&A session over a document."""
      print(f"Document loaded: {file_path}")
      print(f"Web search: {'enabled' if use_web_search else 'disabled'}")
      print("Type 'quit' to exit.\n")

      history = []

      while True:
          question = input("Question: ").strip()
          if question.lower() in ("quit", "exit", "q"):
              break
          if not question:
              continue

          result = ask_about_document(file_path, question, use_web_search, history)
          print(f"\nAnswer:\n{result['answer']}\n")
          print(f"({result['tokens']['input']}+{result['tokens']['output']} tokens)\n")

          # Add to conversation history for multi-turn
          history.append({"role": "user", "content": question})
          history.append({"role": "assistant", "content": result["answer"]})


  def main():
      parser = argparse.ArgumentParser(description="Document Q&A")
      parser.add_argument("file", help="Path to the document file")
      parser.add_argument("question", nargs="?", help="Question to ask")
      parser.add_argument("--interactive", action="store_true", help="Interactive mode")
      parser.add_argument("--web-search", action="store_true", help="Enable web search")
      args = parser.parse_args()

      if not Path(args.file).exists():
          print(f"Error: File not found: {args.file}", file=sys.stderr)
          sys.exit(1)

      if args.interactive:
          interactive_session(args.file, args.web_search)
      elif args.question:
          result = ask_about_document(args.file, args.question, args.web_search)
          print(result["answer"])
      else:
          print("Error: Provide a question or use --interactive.", file=sys.stderr)
          sys.exit(1)


  if __name__ == "__main__":
      main()
  ```
</CodeGroup>

## Example Output

```bash theme={null}
python doc_qa.py quarterly_report.txt "What was the total revenue for Q3?"
```

```
Based on the quarterly report, total revenue for Q3 was $4.2 billion,
representing a 15% year-over-year increase. The report attributes this
growth primarily to the cloud services division, which grew 28% compared
to the same period last year (see Section 3, Financial Highlights).
```

With web search enrichment:

```bash theme={null}
python doc_qa.py quarterly_report.txt "How does this compare to industry benchmarks?" --web-search
```

```
According to the report, Q3 revenue was $4.2 billion (from document).
For comparison, the industry average revenue growth for cloud-focused
companies in Q3 2025 was approximately 12% year-over-year (from web
search: Bloomberg industry analysis). This places the company above
the industry benchmark by roughly 3 percentage points.
```

## Structured Data Extraction from Documents

Extract specific fields from a document into a typed JSON structure:

```python theme={null}
# Extract key metrics from a financial report
schema = {
    "type": "object",
    "properties": {
        "company_name": {"type": "string"},
        "quarter": {"type": "string"},
        "total_revenue": {"type": "string"},
        "net_income": {"type": "string"},
        "revenue_growth_yoy": {"type": "string"},
        "key_highlights": {"type": "array", "items": {"type": "string"}},
    },
    "required": ["company_name", "quarter", "total_revenue", "net_income", "revenue_growth_yoy", "key_highlights"],
    "additionalProperties": false,
}

data = extract_structured_data("quarterly_report.txt", "financial_summary", schema)
print(json.dumps(data, indent=2))
```

<Tip>
  Combine document content with structured outputs to build reliable document processing pipelines. The JSON schema ensures consistent output regardless of document format variations.
</Tip>

<Warning>
  Very large documents are truncated to stay within token limits. For large files, consider splitting into sections and processing each separately.
</Warning>

## Limitations

* Very large documents are truncated. The default limit is 50,000 characters (\~12,500 tokens).
* Text-based formats (.txt, .csv, .md, .json) work best. For PDFs, use a library like `pdfplumber` or `PyPDF2` to extract text first.
* Conversation history for multi-turn sessions does not re-read the file — the document content is included in the first message.


# Financial News Tracker
Source: https://docs.perplexity.ai/docs/cookbook/examples/financial-news-tracker/README

A real-time financial news monitoring tool that fetches and analyzes market news using Perplexity's Sonar API

# Financial News Tracker

A command-line tool that fetches and analyzes real-time financial news using Perplexity's Sonar API. Get comprehensive market insights, news summaries, and investment analysis for any financial topic.

## Features

* Real-time financial news aggregation from multiple sources
* Market sentiment analysis (Bullish/Bearish/Neutral)
* Impact assessment for news items (High/Medium/Low)
* Sector and company-specific analysis
* Investment insights and recommendations
* Customizable time ranges (24h to 1 year)
* Structured JSON output support
* Beautiful emoji-enhanced CLI output

## Installation

### 1. Install required dependencies

```bash theme={null}
# Install from requirements file (recommended)
pip install -r requirements.txt

# Or install manually
pip install requests pydantic
```

### 2. Make the script executable

```bash theme={null}
chmod +x financial_news_tracker.py
```

## API Key Setup

The tool requires a Perplexity API key. You can provide it in one of these ways:

### 1. As an environment variable (recommended)

```bash theme={null}
export PPLX_API_KEY=YOUR_API_KEY
```

### 2. As a command-line argument

```bash theme={null}
./financial_news_tracker.py "tech stocks" --api-key YOUR_API_KEY
```

### 3. In a file

Create a file named `pplx_api_key` or `.pplx_api_key` in the same directory:

```bash theme={null}
echo "YOUR_API_KEY" > .pplx_api_key
chmod 600 .pplx_api_key
```

## Quick Start

Get the latest tech stock news:

```bash theme={null}
./financial_news_tracker.py "tech stocks"
```

This will fetch recent financial news about tech stocks, analyze market sentiment, and provide actionable insights.

## Usage Examples

### Basic usage - Get news for a specific topic

```bash theme={null}
./financial_news_tracker.py "S&P 500"
```

### Get cryptocurrency news from the past week

```bash theme={null}
./financial_news_tracker.py "cryptocurrency" --time-range 1w
```

### Track specific company news

```bash theme={null}
./financial_news_tracker.py "AAPL Apple stock"
```

### Get news about market sectors

```bash theme={null}
./financial_news_tracker.py "energy sector oil prices"
```

### Output as JSON for programmatic use

```bash theme={null}
./financial_news_tracker.py "inflation rates" --json
```

### Use a different model

```bash theme={null}
./financial_news_tracker.py "Federal Reserve interest rates" --model sonar
```

### Enable structured output (requires Tier 3+ API access)

```bash theme={null}
./financial_news_tracker.py "tech earnings" --structured-output
```

## Time Range Options

* `24h` - Last 24 hours (default)
* `1w` - Last week
* `1m` - Last month
* `3m` - Last 3 months
* `1y` - Last year

## Output Format

The tool provides comprehensive financial analysis including:

### 1. Executive Summary

A brief overview of the key financial developments

### 2. Market Analysis

* **Market Sentiment**: Overall market mood (🐂 Bullish, 🐻 Bearish, ⚖️ Neutral)
* **Key Drivers**: Factors influencing the market
* **Risks**: Current market risks and concerns
* **Opportunities**: Potential investment opportunities

### 3. News Items

Each news item includes:

* **Headline**: The main news title
* **Impact**: Market impact level (🔴 High, 🟡 Medium, 🟢 Low)
* **Summary**: Brief description of the news
* **Affected Sectors**: Industries or companies impacted
* **Source**: News source attribution

### 4. Investment Insights

Actionable recommendations and analysis based on the news

## Example Output

```
📊 FINANCIAL NEWS REPORT: tech stocks
📅 Period: Last 24 hours

📝 EXECUTIVE SUMMARY:
Tech stocks showed mixed performance today as AI-related companies surged while 
semiconductor stocks faced pressure from supply chain concerns...

📈 MARKET ANALYSIS:
  Sentiment: 🐂 BULLISH

  Key Drivers:
    • Strong Q4 earnings from major tech companies
    • AI sector momentum continues
    • Federal Reserve signals potential rate cuts

  ⚠️ Risks:
    • Semiconductor supply chain disruptions
    • Regulatory scrutiny on big tech
    • Valuation concerns in AI sector

  💡 Opportunities:
    • Cloud computing growth
    • AI infrastructure plays
    • Cybersecurity demand surge

📰 KEY NEWS ITEMS:

1. Microsoft Hits All-Time High on AI Growth
   Impact: 🔴 HIGH
   Summary: Microsoft stock reached record levels following strong Azure AI revenue...
   Sectors: Cloud Computing, AI, Software
   Source: Bloomberg

💼 INSIGHTS & RECOMMENDATIONS:
  • Consider diversifying within tech sector
  • AI infrastructure companies show strong momentum
  • Monitor semiconductor sector for buying opportunities
```

## Advanced Features

### Custom Queries

You can combine multiple topics for comprehensive analysis:

```bash theme={null}
# Get news about multiple related topics
./financial_news_tracker.py "NVIDIA AMD semiconductor AI chips"

# Track geopolitical impacts on markets
./financial_news_tracker.py "oil prices Middle East geopolitics"

# Monitor economic indicators
./financial_news_tracker.py "inflation CPI unemployment Federal Reserve"
```

### JSON Output

For integration with other tools or scripts:

```bash theme={null}
./financial_news_tracker.py "bitcoin" --json | jq '.market_analysis.market_sentiment'
```

## Tips for Best Results

1. **Be Specific**: Include company tickers, sector names, or specific events
2. **Combine Topics**: Mix company names with relevant themes (e.g., "TSLA electric vehicles")
3. **Use Time Ranges**: Match the time range to your investment horizon
4. **Regular Monitoring**: Set up cron jobs for daily market updates

## Limitations

* Results depend on available public information
* Not financial advice - always do your own research
* Historical data may be limited for very recent events
* Structured output requires Tier 3+ Perplexity API access

## Error Handling

The tool includes comprehensive error handling for:

* Invalid API keys
* Network connectivity issues
* API rate limits
* Invalid queries
* Parsing errors

## Integration Examples

### Daily Market Report

Create a script for daily updates:

```bash theme={null}
#!/bin/bash
# daily_market_report.sh

echo "=== Daily Market Report ===" > market_report.txt
echo "Date: $(date)" >> market_report.txt
echo "" >> market_report.txt

./financial_news_tracker.py "S&P 500 market overview" >> market_report.txt
./financial_news_tracker.py "top gaining stocks" >> market_report.txt
./financial_news_tracker.py "cryptocurrency bitcoin ethereum" >> market_report.txt
```

### Python Integration

```python theme={null}
import subprocess
import json

def get_financial_news(query, time_range="24h"):
    result = subprocess.run(
        ["./financial_news_tracker.py", query, "--time-range", time_range, "--json"],
        capture_output=True,
        text=True
    )
    
    if result.returncode == 0:
        return json.loads(result.stdout)
    else:
        raise Exception(f"Error fetching news: {result.stderr}")

# Example usage
news = get_financial_news("tech stocks", "1w")
print(f"Market sentiment: {news['market_analysis']['market_sentiment']}")
```


# Image Analysis
Source: https://docs.perplexity.ai/docs/cookbook/examples/image-analysis/README

Vision-powered image analysis with web search for context-enriched results using the Perplexity Agent API

# Image Analysis

Analyze images using vision models through the Perplexity Agent API, then enrich the analysis with web search to provide real-world context. This example combines image understanding with live information retrieval in a two-step pipeline: identify what is in the image, then research the identified subjects.

## Features

* Upload images via base64 encoding or public HTTPS URL
* Analyze images with vision-capable models like `openai/gpt-5.4` through the Agent API
* Combine image analysis with web search for context enrichment
* Two-step pipeline: identify, then research
* Support for PNG, JPEG, WEBP, and GIF formats

## Installation

<CodeGroup>
  ```bash Python theme={null}
  pip install perplexityai
  ```

  ```bash TypeScript theme={null}
  npm install @perplexity-ai/perplexity_ai
  ```
</CodeGroup>

```bash theme={null}
export PERPLEXITY_API_KEY="your_api_key_here"
```

## Usage

<CodeGroup>
  ```bash Python theme={null}
  python image_analysis.py path/to/photo.jpg
  python image_analysis.py https://example.com/photo.jpg
  ```

  ```bash TypeScript theme={null}
  npx tsx image_analysis.ts path/to/photo.jpg
  npx tsx image_analysis.ts https://example.com/photo.jpg
  ```
</CodeGroup>

## Full Code

<CodeGroup>
  ```python Python theme={null}
  import sys
  import base64
  from perplexity import Perplexity

  client = Perplexity()


  def encode_image(image_path):
      """Read a local image and return a base64 data URI."""
      with open(image_path, "rb") as f:
          encoded = base64.b64encode(f.read()).decode("utf-8")
      ext = image_path.rsplit(".", 1)[-1].lower()
      mime = {"png": "image/png", "jpg": "image/jpeg", "jpeg": "image/jpeg",
              "webp": "image/webp", "gif": "image/gif"}.get(ext, "image/png")
      return f"data:{mime};base64,{encoded}"


  def identify_image(image_source):
      """Step 1: Identify objects and subjects in an image."""
      image_url = image_source if image_source.startswith("http") else encode_image(image_source)

      response = client.responses.create(
          model="openai/gpt-5.4",
          input=[{
              "role": "user",
              "content": [
                  {
                      "type": "input_text",
                      "text": (
                          "Analyze this image in detail. Identify all notable objects, "
                          "people, landmarks, species, or text. For each, provide a "
                          "concise label and brief description. Format as a numbered list."
                      ),
                  },
                  {"type": "input_image", "image_url": image_url},
              ],
          }],
          max_output_tokens=1024,
      )
      return response.output_text


  def research_subjects(identification_text):
      """Step 2: Research identified subjects with web search."""
      response = client.responses.create(
          model="openai/gpt-5.4",
          input=(
              f"The following subjects were identified in an image:\n\n"
              f"{identification_text}\n\n"
              f"Research each subject. For each, provide:\n"
              f"- What it is and why it is notable\n"
              f"- Key facts or recent news\n"
              f"- Historical or cultural significance if applicable\n\n"
              f"Combine the analysis into a comprehensive report."
          ),
          tools=[{"type": "web_search"}],
          instructions="You are an image research assistant. Provide accurate, up-to-date information. Synthesize image observations with research.",
      )
      return response.output_text


  def analyze(image_source):
      """Full pipeline: identify then research."""
      print(f"Analyzing: {image_source}\n")
      print("Step 1: Identifying subjects...")
      identification = identify_image(image_source)
      print(f"\n{identification}\n")
      print("Step 2: Researching subjects...")
      report = research_subjects(identification)
      print(f"\n{report}")


  if __name__ == "__main__":
      if len(sys.argv) < 2:
          print("Usage: python image_analysis.py <image_path_or_url>")
          sys.exit(1)
      analyze(sys.argv[1])
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from "@perplexity-ai/perplexity_ai";
  import * as fs from "fs";
  import * as path from "path";

  const client = new Perplexity();

  function encodeImage(imagePath: string): string {
    const encoded = fs.readFileSync(imagePath).toString("base64");
    const ext = path.extname(imagePath).slice(1).toLowerCase();
    const mime: Record<string, string> = {
      png: "image/png", jpg: "image/jpeg", jpeg: "image/jpeg",
      webp: "image/webp", gif: "image/gif",
    };
    return `data:${mime[ext] || "image/png"};base64,${encoded}`;
  }

  async function identifyImage(imageSource: string): Promise<string> {
    const imageUrl = imageSource.startsWith("http")
      ? imageSource
      : encodeImage(imageSource);

    const response = await client.responses.create({
      model: "openai/gpt-5.4",
      input: [{
        role: "user",
        content: [
          {
            type: "input_text",
            text: "Analyze this image in detail. Identify all notable objects, "
              + "people, landmarks, species, or text. For each, provide a "
              + "concise label and brief description. Format as a numbered list.",
          },
          { type: "input_image", image_url: imageUrl },
        ],
      }],
      max_output_tokens: 1024,
    });
    return response.output_text;
  }

  async function researchSubjects(identificationText: string): Promise<string> {
    const response = await client.responses.create({
      model: "openai/gpt-5.4",
      input:
        `The following subjects were identified in an image:\n\n`
        + `${identificationText}\n\n`
        + `Research each subject. For each, provide:\n`
        + `- What it is and why it is notable\n`
        + `- Key facts or recent news\n`
        + `- Historical or cultural significance if applicable\n\n`
        + `Combine the analysis into a comprehensive report.`,
      tools: [{ type: "web_search" }],
      instructions: "You are an image research assistant. Provide accurate, up-to-date information. Synthesize image observations with research.",
    });
    return response.output_text;
  }

  async function analyze(imageSource: string): Promise<void> {
    console.log(`Analyzing: ${imageSource}\n`);
    console.log("Step 1: Identifying subjects...");
    const identification = await identifyImage(imageSource);
    console.log(`\n${identification}\n`);
    console.log("Step 2: Researching subjects...");
    const report = await researchSubjects(identification);
    console.log(`\n${report}`);
  }

  const arg = process.argv[2];
  if (!arg) { console.log("Usage: npx tsx image_analysis.ts <image_path_or_url>"); process.exit(1); }
  analyze(arg);
  ```
</CodeGroup>

## Example Output

```
Analyzing: golden_gate.jpg

Step 1: Identifying subjects...

1. Golden Gate Bridge - Iconic red-orange suspension bridge spanning
   the Golden Gate strait in San Francisco, California.
2. San Francisco Bay - Body of water beneath the bridge, connecting
   to the Pacific Ocean.
3. Marin Headlands - Hilly terrain on the far side, part of the
   Golden Gate National Recreation Area.
4. Fog bank - Low-lying cloud formation rolling in from the Pacific.

Step 2: Researching subjects...

## Golden Gate Bridge - Comprehensive Analysis

### The Bridge
The Golden Gate Bridge is a suspension bridge spanning the one-mile-wide
strait connecting San Francisco Bay to the Pacific Ocean. Completed in
1937, it held the record for the longest suspension bridge span at 4,200
feet until 1964. Its "International Orange" color was chosen for fog
visibility and aesthetic harmony.

### San Francisco Bay
San Francisco Bay is a shallow estuary encompassing approximately 1,600
square miles of watershed, one of the largest natural harbors on the
Pacific coast.

### Marin Headlands
Part of the Golden Gate National Recreation Area, offering hiking trails
with panoramic views of the bridge and city skyline.

### Fog Patterns
Summer fog through the Golden Gate is a defining feature of San
Francisco's microclimate, formed when warm inland air draws cool Pacific
air through the strait.
```

<Warning>
  Base64-encoded images count toward input token usage. A 1024x768 image consumes approximately 1,048 tokens. The maximum file size for base64 images is 50 MB.
</Warning>

<Info>
  Vision input is supported on the Agent API via the `input_image` content type. Use a vision-capable model like `openai/gpt-5.4`. Check the [Agent API Image Attachments docs](/docs/agent-api/image-attachments) for supported formats and size limits.
</Info>

## Limitations

* Image analysis requires a vision-capable model (e.g., `openai/gpt-5.4`). Not all models support `input_image`.
* Web search quality in Step 2 depends on identification accuracy in Step 1.
* Only publicly accessible HTTPS URLs work for URL-based input. Private URLs will fail.
* Animated GIFs are supported but only the first frame is analyzed.


# Multi-Provider Model Comparison
Source: https://docs.perplexity.ai/docs/cookbook/examples/model-comparison/README

A CLI tool that sends the same prompt to multiple AI models via Perplexity's Agent API and compares response quality, latency, and cost

# Multi-Provider Model Comparison

A command-line tool that sends the same prompt to multiple AI models through Perplexity's Agent API and produces a side-by-side comparison of response quality, latency, and cost. Useful for evaluating which model best fits your use case.

## Features

* Send identical prompts to 5 models across different providers in a single run
* Measure response latency using wall-clock timing
* Extract per-request cost from the `response.usage.cost.total_cost` field
* Tabulated output comparing response length, latency, and cost
* Model fallback chain support using the `models=[...]` parameter for high-availability workflows
* Configurable prompt input via command-line argument or file

## Supported Models

The default comparison set spans five providers:

| Model                          | Provider   |
| ------------------------------ | ---------- |
| `openai/gpt-5.4`               | OpenAI     |
| `anthropic/claude-sonnet-4-6`  | Anthropic  |
| `google/gemini-3.1-flash-lite` | Google     |
| `xai/grok-4.20-non-reasoning`  | xAI        |
| `perplexity/sonar`             | Perplexity |

## Installation

```bash theme={null}
pip install perplexityai
```

## API Key Setup

Set your Perplexity API key as an environment variable. The SDK reads it automatically:

```bash theme={null}
export PERPLEXITY_API_KEY="your_api_key_here"
```

<Info>
  Perplexity's Agent API provides access to models from multiple providers through a single API key. You do not need separate API keys for OpenAI, Anthropic, Google, or xAI.
</Info>

## Usage

### Compare models with a prompt

```bash theme={null}
python model_comparison.py "Explain the CAP theorem in distributed systems"
```

### Read the prompt from a file

```bash theme={null}
python model_comparison.py --file prompt.txt
```

### Use a custom set of models

```bash theme={null}
python model_comparison.py "What is quantum entanglement?" \
  --models openai/gpt-5.4 anthropic/claude-sonnet-4-6 perplexity/sonar
```

### Export results as JSON

```bash theme={null}
python model_comparison.py "Summarize recent AI safety research" --json > results.json
```

### Use model fallback chain

Instead of comparing models, you can test the fallback chain feature. The API tries each model in order until one succeeds:

```bash theme={null}
python model_comparison.py "Latest AI news" --fallback
```

## How It Works

1. The CLI accepts a prompt and an optional list of models.
2. For each model, the tool records a start timestamp, calls `client.responses.create(model=..., input=...)`, and records the end timestamp.
3. From each response, it extracts `response.usage.cost.total_cost` for the request cost and computes latency as the elapsed wall-clock time.
4. Results are collected and displayed in a comparison table sorted by latency.
5. In fallback mode, the tool sends a single request with `models=[...]` and reports which model was ultimately used.

<Tip>
  The `response.usage.cost` object includes `input_cost`, `output_cost`, and `total_cost` in USD. This makes it straightforward to compare the true cost of each model for your specific prompt.
</Tip>

## Full Code

<CodeGroup>
  ```python Python theme={null}
  import sys
  import json
  import time
  import argparse
  from typing import List, Optional
  from perplexity import Perplexity

  DEFAULT_MODELS = [
      "openai/gpt-5.4",
      "anthropic/claude-sonnet-4-6",
      "google/gemini-3.1-flash-lite",
      "xai/grok-4.20-non-reasoning",
      "perplexity/sonar",
  ]


  def compare_models(prompt: str, models: List[str]) -> List[dict]:
      """Send the same prompt to each model and collect metrics."""
      client = Perplexity()
      results = []

      for model in models:
          print(f"  Querying {model}...")
          try:
              start = time.time()
              response = client.responses.create(
                  model=model,
                  input=prompt,
                  max_output_tokens=1024,
              )
              elapsed = time.time() - start

              output_text = response.output_text
              total_cost = response.usage.cost.total_cost
              input_tokens = response.usage.input_tokens
              output_tokens = response.usage.output_tokens

              results.append({
                  "model": model,
                  "status": "success",
                  "latency_s": round(elapsed, 2),
                  "response_length": len(output_text),
                  "input_tokens": input_tokens,
                  "output_tokens": output_tokens,
                  "cost_usd": total_cost,
                  "preview": output_text[:120].replace("\n", " "),
              })
          except Exception as e:
              results.append({
                  "model": model,
                  "status": "error",
                  "error": str(e),
                  "latency_s": None,
                  "response_length": 0,
                  "input_tokens": 0,
                  "output_tokens": 0,
                  "cost_usd": None,
                  "preview": "",
              })

      return results


  def run_fallback(prompt: str, models: List[str]) -> dict:
      """Send a single request with a model fallback chain."""
      client = Perplexity()

      print(f"  Sending request with fallback chain: {models}")
      start = time.time()
      response = client.responses.create(
          models=models,
          input=prompt,
          max_output_tokens=1024,
      )
      elapsed = time.time() - start

      return {
          "requested_models": models,
          "model_used": response.model,
          "latency_s": round(elapsed, 2),
          "response_length": len(response.output_text),
          "cost_usd": response.usage.cost.total_cost,
          "preview": response.output_text[:200].replace("\n", " "),
      }


  def format_table(results: List[dict]) -> str:
      """Format comparison results as a text table."""
      # Sort by latency (successful responses first)
      successful = [r for r in results if r["status"] == "success"]
      failed = [r for r in results if r["status"] != "success"]
      successful.sort(key=lambda r: r["latency_s"])

      lines = []
      header = f"{'Model':<42} {'Latency':>8} {'Length':>8} {'Tokens':>8} {'Cost':>10}"
      lines.append(header)
      lines.append("-" * len(header))

      for r in successful:
          tokens = f"{r['input_tokens']}+{r['output_tokens']}"
          cost = f"${r['cost_usd']:.5f}"
          lines.append(
              f"{r['model']:<42} {r['latency_s']:>7.2f}s {r['response_length']:>8} {tokens:>8} {cost:>10}"
          )

      for r in failed:
          lines.append(f"{r['model']:<42} {'FAILED':>8} {'-':>8} {'-':>8} {'-':>10}")

      return "\n".join(lines)


  def main():
      parser = argparse.ArgumentParser(
          description="Multi-Provider Model Comparison"
      )
      parser.add_argument("prompt", nargs="?", help="The prompt to send")
      parser.add_argument("--file", help="Read prompt from a file")
      parser.add_argument(
          "--models",
          nargs="+",
          default=DEFAULT_MODELS,
          help="Models to compare",
      )
      parser.add_argument(
          "--fallback",
          action="store_true",
          help="Use model fallback chain instead of comparing",
      )
      parser.add_argument(
          "--json", action="store_true", help="Output results as JSON"
      )
      args = parser.parse_args()

      # Resolve prompt
      if args.file:
          with open(args.file, "r") as f:
              prompt = f.read().strip()
      elif args.prompt:
          prompt = args.prompt
      else:
          print("Error: Provide a prompt or use --file.", file=sys.stderr)
          sys.exit(1)

      print(f"Prompt: {prompt[:80]}{'...' if len(prompt) > 80 else ''}\n")

      if args.fallback:
          print("Running model fallback chain...\n")
          result = run_fallback(prompt, args.models)
          if args.json:
              print(json.dumps(result, indent=2))
          else:
              print(f"Fallback chain: {' -> '.join(result['requested_models'])}")
              print(f"Model used:     {result['model_used']}")
              print(f"Latency:        {result['latency_s']}s")
              print(f"Response length: {result['response_length']} chars")
              print(f"Cost:           ${result['cost_usd']:.5f}")
              print(f"\nPreview: {result['preview']}")
      else:
          print(f"Comparing {len(args.models)} models...\n")
          results = compare_models(prompt, args.models)
          if args.json:
              print(json.dumps(results, indent=2))
          else:
              print(format_table(results))
              print(f"\nComparison complete. {len(results)} models evaluated.")


  if __name__ == "__main__":
      main()
  ```
</CodeGroup>

## Example Output

Running the comparison:

```bash theme={null}
python model_comparison.py "Explain the CAP theorem in distributed systems"
```

Produces output like:

```
Prompt: Explain the CAP theorem in distributed systems

Comparing 5 models...

  Querying openai/gpt-5.4...
  Querying anthropic/claude-sonnet-4-6...
  Querying google/gemini-3.1-flash-lite...
  Querying xai/grok-4.20-non-reasoning...
  Querying perplexity/sonar...

Model                                      Latency   Length   Tokens       Cost
------------------------------------------------------------------------------
xai/grok-4.20-non-reasoning              1.24s     1842    18+312  $0.00048
google/gemini-3.1-flash-lite                      1.87s     2105    18+356  $0.00031
perplexity/sonar                             2.13s     1654    18+280  $0.00034
openai/gpt-5.4                               3.41s     2487    18+421  $0.00438
anthropic/claude-sonnet-4-6                  3.78s     2301    18+389  $0.00527

Comparison complete. 5 models evaluated.
```

Running with the fallback chain:

```bash theme={null}
python model_comparison.py "Latest AI news" --fallback
```

```
Prompt: Latest AI news

Running model fallback chain...

  Sending request with fallback chain: ['openai/gpt-5.4', ...]

Fallback chain: openai/gpt-5.4 -> anthropic/claude-sonnet-4-6 -> google/gemini-3.1-flash-lite -> xai/grok-4.20-non-reasoning -> perplexity/sonar
Model used:     openai/gpt-5.4
Latency:        3.12s
Response length: 2034 chars
Cost:           $0.00415

Preview: The AI landscape continues to evolve rapidly in 2025...
```

<Info>
  Model fallback is useful for production systems where availability matters more than model selection. The API tries each model in the `models` array in order and returns the first successful response. See the [model fallback guide](/docs/agent-api/model-fallback) for details.
</Info>

## Tips for Meaningful Comparisons

1. **Use the same `max_output_tokens`** across all models to keep output lengths comparable.
2. **Run multiple trials** and average the results, since latency can vary between requests due to load.
3. **Test with representative prompts** for your actual use case rather than generic questions.
4. **Consider cost per token** in addition to total cost, especially for high-volume applications.

## Limitations

* Latency measurements reflect end-to-end wall-clock time including network round trips, not pure model inference time.
* Cost values come from the API response and reflect per-request pricing at the time of the call.
* Response quality is subjective and not captured by quantitative metrics alone. Review the actual output text for qualitative evaluation.
* Rate limits vary by model and provider. Sequential comparison requests may be affected by rate limiting on high-demand models.


# Academic Research Finder CLI
Source: https://docs.perplexity.ai/docs/cookbook/examples/research-finder/README

A command-line tool that uses Perplexity's Sonar API to find and summarize academic literature

# Academic Research Finder CLI

A command-line tool that uses Perplexity's Sonar API to find and summarize academic literature (research papers, articles, etc.) related to a given question or topic.

## Features

* Takes a natural language question or topic as input, ideally suited for academic inquiry.
* Leverages Perplexity Sonar API, guided by a specialized prompt to prioritize scholarly sources (e.g., journals, conference proceedings, academic databases).
* Outputs a concise summary based on the findings from academic literature.
* Lists the primary academic sources used, aiming to include details like authors, year, title, publication, and DOI/link when possible.
* Supports different Perplexity models (defaults to `sonar-pro`).
* Allows results to be output in JSON format.

## Installation

### 1. Install required dependencies

Ensure you are using the Python environment you intend to run the script with (e.g., `python3.10` if that's your target).

```bash theme={null}
# Install from requirements file (recommended)
pip install -r requirements.txt

# Or install manually
pip install requests
```

### 2. Make the script executable (Optional)

```bash theme={null}
chmod +x research_finder.py
```

Alternatively, you can run the script using `python3 research_finder.py ...`.

## API Key Setup

The tool requires a Perplexity API key (`PPLX_API_KEY`) to function. You can provide it in one of these ways (checked in this order):

1. **As a command-line argument:**
   ```bash theme={null}
   python3 research_finder.py "Your query" --api-key YOUR_API_KEY
   ```
2. **As an environment variable:**
   ```bash theme={null}
   export PPLX_API_KEY=YOUR_API_KEY
   python3 research_finder.py "Your query"
   ```
3. **In a file:** Create a file named `pplx_api_key`, `.pplx_api_key`, `PPLX_API_KEY`, or `.PPLX_API_KEY` in the *same directory as the script* or in the *current working directory* containing just your API key.
   ```bash theme={null}
   echo "YOUR_API_KEY" > .pplx_api_key
   chmod 600 .pplx_api_key # Optional: restrict permissions
   python3 research_finder.py "Your query"
   ```

## Usage

Run the script from the `sonar-use-cases/research_finder` directory or provide the full path.

```bash theme={null}
# Basic usage
python3 research_finder.py "What are the latest advancements in quantum computing?"

# Using a specific model
python3 research_finder.py "Explain the concept of Large Language Models" --model sonar-small-online

# Getting output as JSON
python3 research_finder.py "Summarize the plot of Dune Part Two" --json

# Using a custom system prompt file
python3 research_finder.py "Benefits of renewable energy" --prompt-file /path/to/your/custom_prompt.md

# Using an API key via argument
python3 research_finder.py "Who won the last FIFA World Cup?" --api-key sk-...

# Using the executable (if chmod +x was used)
./research_finder.py "Latest news about Mars exploration"
```

### Arguments

* `query`: (Required) The research question or topic (enclose in quotes if it contains spaces).
* `-m`, `--model`: Specify the Perplexity model (default: `sonar-pro`).
* `-k`, `--api-key`: Provide the API key directly.
* `-p`, `--prompt-file`: Path to a custom system prompt file.
* `-j`, `--json`: Output the results in JSON format.

## Example Output (Human-Readable - *Note: Actual output depends heavily on the query and API results*)

```
Initializing research assistant for query: "Recent studies on transformer models in NLP"...
Researching in progress...

✅ Research Complete!

📝 SUMMARY:
Recent studies on transformer models in Natural Language Processing (NLP) continue to explore architectural improvements, efficiency optimizations, and new applications. Key areas include modifications to the attention mechanism (e.g., sparse attention, linear attention) to handle longer sequences more efficiently, techniques for model compression and knowledge distillation, and applications beyond text, such as in computer vision and multimodal tasks. Research also focuses on understanding the internal workings and limitations of large transformer models.

🔗 SOURCES:
  1. Vaswani, A., Shazeer, N., Parmar, N., Uszkoreit, J., Jones, L., Gomez, A. N., ... & Polosukhin, I. (2017). Attention is all you need. Advances in neural information processing systems, 30. (arXiv:1706.03762)
  2. Tay, Y., Dehghani, M., Bahri, D., & Metzler, D. (2020). Efficient transformers: A survey. arXiv preprint arXiv:2009.06732.
  3. Beltagy, I., Peters, M. E., & Cohan, A. (2020). Longformer: The long-document transformer. arXiv preprint arXiv:2004.05150.
  4. Rogers, A., Kovaleva, O., & Rumshisky, A. (2020). A primer in bertology: What we know about how bert works. Transactions of the Association for Computational Linguistics, 8, 842-866. (arXiv:2002.12327)
```

## Limitations

* The ability of the Sonar API to consistently prioritize and access specific academic databases or extract detailed citation information (like DOIs) may vary. The quality depends on the API's search capabilities and the structure of the source websites.
* The script performs basic parsing to separate summary and sources; complex or unusual API responses might not be parsed perfectly. Check the raw response in case of issues.
* Queries that are too broad or not well-suited for academic search might yield less relevant results.
* Error handling for API rate limits or specific API errors could be more granular.


# Search News Monitor
Source: https://docs.perplexity.ai/docs/cookbook/examples/search-news-monitor/README

A CLI tool that uses Perplexity's Search API to monitor real-time news across multiple configurable topics with domain and recency filtering

# Search News Monitor

A command-line tool that uses Perplexity's Search API (`client.search.create(...)`) to monitor real-time news across multiple topics. Configure topics, domain filters, and recency windows to build a continuous news monitoring pipeline.

## Features

* Monitor multiple topics in a single run using the Search API
* Filter results by domain with `search_domain_filter` (allowlist or denylist)
* Control recency with `search_recency_filter` (day, week, month, year)
* Access structured result fields: `title`, `url`, `snippet`, `date`
* Configurable polling interval for continuous monitoring
* Output as formatted text or JSON for downstream processing

## Installation

<CodeGroup>
  ```bash Python theme={null}
  pip install perplexityai
  ```

  ```bash TypeScript theme={null}
  npm install @perplexity-ai/perplexity_ai
  ```
</CodeGroup>

## API Key Setup

Set your Perplexity API key as an environment variable. The SDK reads it automatically:

```bash theme={null}
export PERPLEXITY_API_KEY="your_api_key_here"
```

## Usage

```bash theme={null}
# Monitor default topics
python news_monitor.py

# Specify custom topics
python news_monitor.py --topics "artificial intelligence" "climate policy" "space exploration"

# Filter to specific domains (allowlist)
python news_monitor.py --topics "AI regulation" --domains reuters.com apnews.com bbc.co.uk

# Exclude domains (denylist)
python news_monitor.py --topics "technology" --exclude-domains pinterest.com reddit.com

# Set recency filter
python news_monitor.py --topics "semiconductor industry" --recency day

# Run in continuous monitoring mode
python news_monitor.py --topics "cybersecurity" --watch --interval 300

# Export as JSON
python news_monitor.py --topics "renewable energy" --json > news.json
```

## How It Works

1. The CLI accepts a list of topics and optional filtering parameters.
2. For each topic, it calls `client.search.create(query=..., max_results=...)` with the configured domain and recency filters.
3. Each search result contains `title`, `url`, `snippet`, and `date` fields, which are extracted and formatted.
4. In watch mode, the tool repeats the search at a configurable interval, displaying only new results since the last poll.

<Tip>
  Use the `search_recency_filter` parameter with values like `"day"`, `"week"`, `"month"`, or `"year"` to focus on recent news. This is simpler than specifying exact date ranges and works well for monitoring workflows.
</Tip>

<Warning>
  Domain filters operate in either allowlist or denylist mode, not both simultaneously. Use `--domains` for allowlist or `--exclude-domains` for denylist, but not both in the same request. A maximum of 20 domains can be specified.
</Warning>

## Full Code

<CodeGroup>
  ```python Python theme={null}
  import sys
  import json
  import time
  import argparse
  from typing import List, Optional
  from perplexity import Perplexity

  DEFAULT_TOPICS = ["artificial intelligence", "climate change", "cybersecurity"]


  def search_topic(
      client, topic, max_results=5, domains=None, exclude_domains=None, recency=None,
  ):
      """Search for news on a single topic and return structured results."""
      params = {"query": topic, "max_results": max_results}
      if domains:
          params["search_domain_filter"] = domains
      elif exclude_domains:
          params["search_domain_filter"] = [f"-{d}" for d in exclude_domains]
      if recency:
          params["search_recency_filter"] = recency

      search = client.search.create(**params)
      return [
          {
              "title": item.title,
              "url": item.url,
              "snippet": item.snippet[:200] if item.snippet else "",
              "date": item.date if hasattr(item, "date") else None,
          }
          for item in search.results
      ]


  def monitor_once(client, topics, max_results, domains, exclude_domains, recency):
      """Run a single monitoring pass across all topics."""
      return {
          topic: search_topic(client, topic, max_results, domains, exclude_domains, recency)
          for topic in topics
      }


  def format_results(all_results):
      """Format monitoring results as human-readable text."""
      lines = [f"NEWS MONITOR - {time.strftime('%Y-%m-%d %H:%M:%S')}", "=" * 60]
      for topic, results in all_results.items():
          lines.append(f"\n[ {topic.upper()} ] - {len(results)} results")
          lines.append("-" * 40)
          if not results:
              lines.append("  No results found.")
              continue
          for i, r in enumerate(results, 1):
              lines.append(f"  {i}. {r['title']}")
              lines.append(f"     {r['url']}")
              if r["date"]:
                  lines.append(f"     Published: {r['date']}")
              if r["snippet"]:
                  lines.append(f"     {r['snippet']}...")
              lines.append("")
      return "\n".join(lines)


  def main():
      parser = argparse.ArgumentParser(description="Search News Monitor")
      parser.add_argument("--topics", nargs="+", default=DEFAULT_TOPICS)
      parser.add_argument("--max-results", type=int, default=5)
      parser.add_argument("--domains", nargs="+", help="Allowlist domains")
      parser.add_argument("--exclude-domains", nargs="+", help="Denylist domains")
      parser.add_argument("--recency", choices=["day", "week", "month", "year"], default="week")
      parser.add_argument("--watch", action="store_true", help="Continuous monitoring")
      parser.add_argument("--interval", type=int, default=300, help="Poll interval (seconds)")
      parser.add_argument("--json", action="store_true", help="Output as JSON")
      args = parser.parse_args()

      if args.domains and args.exclude_domains:
          print("Error: Use --domains or --exclude-domains, not both.", file=sys.stderr)
          sys.exit(1)

      client = Perplexity()
      print(f"Monitoring {len(args.topics)} topics: {', '.join(args.topics)}")
      print(f"Recency: {args.recency} | Max results per topic: {args.max_results}\n")

      seen_urls = set()
      while True:
          all_results = monitor_once(
              client, args.topics, args.max_results, args.domains, args.exclude_domains, args.recency,
          )
          if args.watch:
              filtered = {}
              for topic, results in all_results.items():
                  new = [r for r in results if r["url"] not in seen_urls]
                  seen_urls.update(r["url"] for r in new)
                  filtered[topic] = new
              all_results = filtered

          print(json.dumps(all_results, indent=2) if args.json else format_results(all_results))

          if not args.watch:
              break
          print(f"\nNext check in {args.interval} seconds... (Ctrl+C to stop)\n")
          time.sleep(args.interval)


  if __name__ == "__main__":
      main()
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from "@perplexity-ai/perplexity_ai";

  const DEFAULT_TOPICS = ["artificial intelligence", "climate change", "cybersecurity"];

  interface SearchResult {
    title: string;
    url: string;
    snippet: string;
    date: string | null;
  }

  async function searchTopic(
    client: InstanceType<typeof Perplexity>,
    topic: string,
    maxResults: number,
    domains?: string[],
    recency?: string
  ): Promise<SearchResult[]> {
    const params: Record<string, unknown> = { query: topic, max_results: maxResults };
    if (domains) params.search_domain_filter = domains;
    if (recency) params.search_recency_filter = recency;

    const search = await client.search.create(params as any);
    return (search as any).results.map((item: any) => ({
      title: item.title,
      url: item.url,
      snippet: item.snippet ? item.snippet.substring(0, 200) : "",
      date: item.date || null,
    }));
  }

  function formatResults(allResults: Record<string, SearchResult[]>): string {
    const lines: string[] = [];
    const ts = new Date().toISOString().replace("T", " ").substring(0, 19);
    lines.push(`NEWS MONITOR - ${ts}`, "=".repeat(60));

    for (const [topic, results] of Object.entries(allResults)) {
      lines.push(`\n[ ${topic.toUpperCase()} ] - ${results.length} results`, "-".repeat(40));
      if (!results.length) { lines.push("  No results found."); continue; }
      results.forEach((r, i) => {
        lines.push(`  ${i + 1}. ${r.title}`, `     ${r.url}`);
        if (r.date) lines.push(`     Published: ${r.date}`);
        if (r.snippet) lines.push(`     ${r.snippet}...`);
        lines.push("");
      });
    }
    return lines.join("\n");
  }

  async function main() {
    const args = process.argv.slice(2);
    const topicsIdx = args.indexOf("--topics");
    let topics = DEFAULT_TOPICS;
    if (topicsIdx !== -1) {
      topics = [];
      for (let i = topicsIdx + 1; i < args.length && !args[i].startsWith("--"); i++)
        topics.push(args[i]);
    }

    const recencyIdx = args.indexOf("--recency");
    const recency = recencyIdx !== -1 ? args[recencyIdx + 1] : "week";
    const maxIdx = args.indexOf("--max-results");
    const maxResults = maxIdx !== -1 ? parseInt(args[maxIdx + 1]) : 5;
    const watch = args.includes("--watch");
    const intervalIdx = args.indexOf("--interval");
    const interval = intervalIdx !== -1 ? parseInt(args[intervalIdx + 1]) : 300;
    const outputJson = args.includes("--json");

    const client = new Perplexity();
    console.log(`Monitoring ${topics.length} topics: ${topics.join(", ")}`);
    console.log(`Recency: ${recency} | Max results per topic: ${maxResults}\n`);

    const seenUrls = new Set<string>();
    while (true) {
      const allResults: Record<string, SearchResult[]> = {};
      for (const topic of topics)
        allResults[topic] = await searchTopic(client, topic, maxResults, undefined, recency);

      let display = allResults;
      if (watch) {
        display = {};
        for (const [topic, results] of Object.entries(allResults)) {
          const fresh = results.filter((r) => !seenUrls.has(r.url));
          fresh.forEach((r) => seenUrls.add(r.url));
          display[topic] = fresh;
        }
      }

      console.log(outputJson ? JSON.stringify(display, null, 2) : formatResults(display));
      if (!watch) break;
      console.log(`\nNext check in ${interval} seconds... (Ctrl+C to stop)\n`);
      await new Promise((r) => setTimeout(r, interval * 1000));
    }
  }

  main();
  ```
</CodeGroup>

## Example Output

```bash theme={null}
python news_monitor.py --topics "artificial intelligence" "climate policy" --recency day
```

```
Monitoring 2 topics: artificial intelligence, climate policy
Recency: day | Max results per topic: 5

NEWS MONITOR - 2026-02-26 14:30:00
============================================================

[ ARTIFICIAL INTELLIGENCE ] - 5 results
----------------------------------------
  1. OpenAI Announces New Enterprise AI Safety Framework
     https://www.reuters.com/technology/openai-enterprise-safety-2026
     Published: 2026-02-26
     OpenAI introduced a comprehensive safety framework for enterprise
     deployments, addressing concerns about autonomous agent behavior...

  2. EU AI Act Enforcement Begins for High-Risk Systems
     https://www.bbc.co.uk/news/technology-ai-act-enforcement
     Published: 2026-02-26
     The European Union has started enforcing new requirements for
     high-risk AI systems under the AI Act...

[ CLIMATE POLICY ] - 3 results
----------------------------------------
  1. G7 Nations Agree on Carbon Border Adjustment Timeline
     https://www.reuters.com/sustainability/g7-carbon-border-2026
     Published: 2026-02-26
     G7 leaders reached consensus on implementing coordinated carbon
     border adjustment mechanisms by 2028...
```

<Info>
  The Search API returns structured results with `title`, `url`, `snippet`, and `date` fields. Unlike the Agent API or Sonar API, it does not generate AI summaries -- it returns raw ranked web results. See the [Search API quickstart](/docs/search/quickstart) for full details.
</Info>

## Continuous Monitoring Tips

1. **Set appropriate intervals.** For breaking news, use 60-120 second intervals. For general topic monitoring, 300-600 seconds is sufficient.
2. **Combine recency with domain filters.** Use `--recency day` with trusted news domains for a curated news feed.
3. **Pipe JSON output to other tools.** Use `--json` with tools like `jq` or downstream scripts for alerting and aggregation.
4. **Track seen URLs.** The watch mode automatically deduplicates results across polling cycles using URL tracking.

## Limitations

* The Search API charges per request. Frequent polling across many topics will increase costs.
* The `search_recency_filter` is relative to the current time and cannot specify exact date ranges. For precise date filtering, use `search_after_date_filter` and `search_before_date_filter` instead.
* Search result availability depends on web indexing. Very recent content (within minutes) may not appear immediately.
* The `snippet` field length varies by result and may be truncated for long pages.


# SEC Filing Search
Source: https://docs.perplexity.ai/docs/cookbook/examples/sec-filing-search/README

Use search domain filtering to query SEC.gov and EDGAR for financial filings, extract key financial data, and build structured financial summaries

# SEC Filing Search

Search SEC.gov and EDGAR for financial filings using domain filtering, extract key financial metrics, and produce structured summaries of public company filings. This example demonstrates practical financial data extraction using the Agent API with targeted domain filters.

## Features

* Search SEC.gov and EDGAR exclusively using `search_domain_filter`
* Extract key metrics from 10-K, 10-Q, and 8-K filings
* Structured JSON output for financial data
* Compare filings across companies or time periods
* Combine SEC data with broader market context via web search

<Info>
  This example uses the Agent API's `web_search` tool with domain filtering to target SEC.gov specifically. The search is grounded in actual SEC filings rather than secondary reporting.
</Info>

## Installation

```bash theme={null}
pip install perplexityai
```

```bash theme={null}
export PERPLEXITY_API_KEY="your_api_key_here"
```

## Usage

Save the full code below to `sec_search.py` and run:

```bash theme={null}
python sec_search.py "Apple 10-K 2025 revenue and operating income"
```

Compare companies:

```bash theme={null}
python sec_search.py --compare AAPL MSFT GOOGL --metric revenue
```

## Full Code

<CodeGroup>
  ```python Python theme={null}
  import sys
  import json
  import argparse
  from perplexity import Perplexity

  client = Perplexity()

  SEC_DOMAINS = [
      "sec.gov",
      "edgar.sec.gov",
      "efts.sec.gov",
  ]


  def search_sec_filings(query: str) -> dict:
      """Search SEC filings with domain-filtered web search."""
      response = client.responses.create(
          model="openai/gpt-5.4",
          input=query,
          tools=[{
              "type": "web_search",
              "filters": {
                  "search_domain_filter": SEC_DOMAINS,
              },
          }],
          instructions=(
              "You are a financial analyst assistant. Search SEC filings for the requested "
              "information. Cite specific filing types (10-K, 10-Q, 8-K) and dates. "
              "Report exact numbers from the filings, not estimates."
          ),
          max_output_tokens=2048,
      )

      return {
          "query": query,
          "answer": response.output_text,
          "model": response.model,
          "cost": response.usage.cost.total_cost,
      }


  def extract_financial_metrics(company: str, filing_type: str = "10-K") -> dict:
      """Extract structured financial metrics from SEC filings."""
      response = client.responses.create(
          model="openai/gpt-5.4",
          input=f"Find the most recent {filing_type} filing for {company} on SEC EDGAR and extract key financial metrics.",
          tools=[{
              "type": "web_search",
              "filters": {
                  "search_domain_filter": SEC_DOMAINS,
              },
          }],
          instructions=(
              f"Search SEC EDGAR for {company}'s most recent {filing_type} filing. "
              "Extract the exact financial figures reported. Use numbers directly from the filing."
          ),
          response_format={
              "type": "json_schema",
              "json_schema": {
                  "name": "sec_financials",
                  "schema": {
                      "type": "object",
                      "properties": {
                          "company": {"type": "string"},
                          "ticker": {"type": "string"},
                          "filing_type": {"type": "string"},
                          "filing_period": {"type": "string"},
                          "filing_date": {"type": "string"},
                          "total_revenue": {"type": "string"},
                          "net_income": {"type": "string"},
                          "total_assets": {"type": "string"},
                          "total_debt": {"type": "string"},
                          "operating_income": {"type": "string"},
                          "eps_diluted": {"type": "string"},
                          "cash_and_equivalents": {"type": "string"},
                      },
                      "required": [
                          "company", "ticker", "filing_type", "filing_period", "filing_date",
                          "total_revenue", "net_income", "total_assets", "total_debt",
                          "operating_income", "eps_diluted", "cash_and_equivalents",
                      ],
                      "additionalProperties": False,
                  },
              },
          },
      )

      return json.loads(response.output_text)


  def compare_companies(tickers: list[str], metric: str = "revenue") -> list[dict]:
      """Compare a specific financial metric across multiple companies."""
      results = []
      for ticker in tickers:
          print(f"  Searching {ticker}...")
          try:
              data = extract_financial_metrics(ticker)
              results.append(data)
          except Exception as e:
              results.append({"ticker": ticker, "error": str(e)})
      return results


  def search_filing_changes(company: str) -> str:
      """Search for material changes or risk factors in recent filings."""
      response = client.responses.create(
          model="openai/gpt-5.4",
          input=(
              f"What are the key risk factors and material changes disclosed in {company}'s "
              f"most recent 10-K or 10-Q filing on SEC EDGAR?"
          ),
          tools=[{
              "type": "web_search",
              "filters": {
                  "search_domain_filter": SEC_DOMAINS,
              },
          }],
          instructions=(
              "Focus on risk factors (Item 1A) and material changes. "
              "Cite specific sections and filing dates."
          ),
          max_output_tokens=2048,
      )
      return response.output_text


  def main():
      parser = argparse.ArgumentParser(description="SEC Filing Search")
      parser.add_argument("query", nargs="?", help="Search query for SEC filings")
      parser.add_argument("--extract", help="Extract financial metrics for a company ticker")
      parser.add_argument("--compare", nargs="+", help="Compare companies by ticker")
      parser.add_argument("--metric", default="revenue", help="Metric to compare")
      parser.add_argument("--risks", help="Search risk factors for a company")
      parser.add_argument("--json", action="store_true", help="Output as JSON")
      args = parser.parse_args()

      if args.compare:
          print(f"Comparing {len(args.compare)} companies...\n")
          results = compare_companies(args.compare, args.metric)
          if args.json:
              print(json.dumps(results, indent=2))
          else:
              for r in results:
                  if "error" in r:
                      print(f"  {r['ticker']}: ERROR - {r['error']}")
                  else:
                      print(f"  {r['company']} ({r['ticker']}) — {r['filing_type']} ({r['filing_period']})")
                      print(f"    Revenue: {r['total_revenue']}")
                      print(f"    Net Income: {r['net_income']}")
                      print(f"    Operating Income: {r['operating_income']}")
                      print(f"    EPS: {r['eps_diluted']}")
                      print()

      elif args.extract:
          print(f"Extracting financials for {args.extract}...\n")
          data = extract_financial_metrics(args.extract)
          if args.json:
              print(json.dumps(data, indent=2))
          else:
              print(f"{data['company']} ({data['ticker']})")
              print(f"Filing: {data['filing_type']} for {data['filing_period']} (filed {data['filing_date']})")
              print(f"  Revenue:          {data['total_revenue']}")
              print(f"  Net Income:       {data['net_income']}")
              print(f"  Operating Income: {data['operating_income']}")
              print(f"  Total Assets:     {data['total_assets']}")
              print(f"  Total Debt:       {data['total_debt']}")
              print(f"  Cash:             {data['cash_and_equivalents']}")
              print(f"  EPS (diluted):    {data['eps_diluted']}")

      elif args.risks:
          print(f"Searching risk factors for {args.risks}...\n")
          print(search_filing_changes(args.risks))

      elif args.query:
          result = search_sec_filings(args.query)
          if args.json:
              print(json.dumps(result, indent=2))
          else:
              print(result["answer"])

      else:
          print("Error: Provide a query, --extract TICKER, --compare TICKERS, or --risks COMPANY", file=sys.stderr)
          sys.exit(1)


  if __name__ == "__main__":
      main()
  ```
</CodeGroup>

## Example Output

### Basic Filing Search

```bash theme={null}
python sec_search.py "Apple 10-K 2025 revenue breakdown by segment"
```

```
According to Apple's FY2025 10-K filing (filed October 2025), total net
revenue was $394.3 billion. Revenue by segment:

- iPhone: $200.6B (50.8%)
- Services: $96.2B (24.4%)
- Mac: $29.4B (7.5%)
- iPad: $28.3B (7.2%)
- Wearables, Home and Accessories: $39.8B (10.1%)

Services revenue grew 14% year-over-year, continuing to be the fastest-
growing segment. (Source: Apple Inc. 10-K, SEC EDGAR)
```

### Structured Extraction

```bash theme={null}
python sec_search.py --extract AAPL --json
```

```json theme={null}
{
  "company": "Apple Inc.",
  "ticker": "AAPL",
  "filing_type": "10-K",
  "filing_period": "FY2025 (ending September 2025)",
  "filing_date": "2025-10-31",
  "total_revenue": "$394.3 billion",
  "net_income": "$101.2 billion",
  "total_assets": "$352.6 billion",
  "total_debt": "$98.3 billion",
  "operating_income": "$123.4 billion",
  "eps_diluted": "$6.72",
  "cash_and_equivalents": "$29.9 billion"
}
```

### Company Comparison

```bash theme={null}
python sec_search.py --compare AAPL MSFT GOOGL
```

```
Comparing 3 companies...

  Apple Inc. (AAPL) — 10-K (FY2025)
    Revenue: $394.3 billion
    Net Income: $101.2 billion
    Operating Income: $123.4 billion
    EPS: $6.72

  Microsoft Corporation (MSFT) — 10-K (FY2025)
    Revenue: $254.2 billion
    Net Income: $89.4 billion
    Operating Income: $115.6 billion
    EPS: $12.01

  Alphabet Inc. (GOOGL) — 10-K (FY2025)
    Revenue: $348.2 billion
    Net Income: $86.7 billion
    Operating Income: $108.3 billion
    EPS: $7.02
```

<Tip>
  SEC EDGAR contains the official, audited financial data for all US public companies. By restricting search to `sec.gov` and `edgar.sec.gov`, you ensure your financial data comes from primary source filings rather than secondary reporting.
</Tip>

<Warning>
  Financial data extracted by the model should be verified against the original filing before use in official reports or investment decisions. The model may occasionally misparse tables or footnotes.
</Warning>

## Limitations

* The search is limited to what SEC EDGAR makes publicly available and indexable.
* Very recent filings may not yet be indexed by the search engine.
* Complex financial tables (multi-year comparisons, segment breakdowns with footnotes) may be summarized rather than fully extracted.
* The model provides data as-is from filings. It does not adjust for accounting method changes between periods.


# TypeScript Agent CLI
Source: https://docs.perplexity.ai/docs/cookbook/examples/typescript-agent-cli/README

An interactive TypeScript CLI with streaming responses, model selection, and web search using the Perplexity Agent API

# TypeScript Agent CLI

A TypeScript-first interactive command-line interface that connects to the Perplexity Agent API with streaming responses, runtime model selection, and integrated web search.

## Features

* Interactive REPL with streaming token output
* Runtime model selection from a curated list
* Web search integration via the `web_search` tool
* TypeScript-specific patterns: type narrowing, const assertions, typed error classes
* Conversation history for multi-turn interactions
* Graceful error handling and clean shutdown

## Installation

```bash theme={null}
mkdir typescript-agent-cli && cd typescript-agent-cli
npm init -y
npm install @perplexity-ai/perplexity_ai
npm install -D typescript @types/node tsx
```

```bash theme={null}
export PERPLEXITY_API_KEY="your_api_key_here"
```

## Usage

```bash theme={null}
npx tsx src/cli.ts
```

The CLI prompts you to select a model, then enters an interactive loop:

```
Available models:
  1. OpenAI GPT-5.1 (openai/gpt-5.4)
  2. Google Gemini 3 Flash (google/gemini-3.1-flash-lite)

Select a model (1-2): 1

> What is the current state of quantum computing?
```

Commands: `/search` (enable web search), `/nosearch` (disable), `/clear` (reset history), `/quit` (exit).

## Full Code

Save as `src/cli.ts`:

```typescript theme={null}
import Perplexity from "@perplexity-ai/perplexity_ai";
import * as readline from "readline";

// --- Configuration ---

const AVAILABLE_MODELS = [
  { name: "openai/gpt-5.4", label: "OpenAI GPT-5.1" },
  { name: "google/gemini-3.1-flash-lite", label: "Google Gemini 3 Flash" },
] as const;

type ModelName = (typeof AVAILABLE_MODELS)[number]["name"];

interface Message {
  role: "user" | "assistant";
  content: string;
}

// --- Helpers ---

function createRL(): readline.Interface {
  return readline.createInterface({ input: process.stdin, output: process.stdout });
}

function ask(rl: readline.Interface, prompt: string): Promise<string> {
  return new Promise((resolve) => rl.question(prompt, (a) => resolve(a.trim())));
}

// --- Model selection ---

async function selectModel(rl: readline.Interface): Promise<ModelName> {
  console.log("\nAvailable models:");
  AVAILABLE_MODELS.forEach((m, i) =>
    console.log(`  ${i + 1}. ${m.label} (${m.name})`)
  );
  while (true) {
    const idx = parseInt(await ask(rl, `\nSelect a model (1-${AVAILABLE_MODELS.length}): `), 10) - 1;
    if (idx >= 0 && idx < AVAILABLE_MODELS.length) {
      console.log(`Using model: ${AVAILABLE_MODELS[idx].name}\n`);
      return AVAILABLE_MODELS[idx].name;
    }
    console.log("Invalid selection.");
  }
}

// --- Streaming query ---

async function streamQuery(
  client: Perplexity,
  model: ModelName,
  history: Message[],
  userMessage: string,
  useWebSearch: boolean
): Promise<string> {
  const input = [
    ...history.map((m) => ({ role: m.role as "user" | "assistant", content: m.content })),
    { role: "user" as const, content: userMessage },
  ];

  const tools: Array<{ type: "web_search" }> = useWebSearch
    ? [{ type: "web_search" as const }]
    : [];

  const stream = await client.responses.create({
    model,
    input,
    tools,
    stream: true,
    instructions: "You are a helpful assistant. Use web search when available for current events. Be concise.",
    max_output_tokens: 2048,
  });

  let fullResponse = "";
  for await (const chunk of stream) {
    if (chunk.type === "response.output_text.delta") {
      const delta = (chunk as any).delta as string;
      process.stdout.write(delta);
      fullResponse += delta;
    }
    if (chunk.type === "response.output_item.added") {
      const item = (chunk as any).item;
      if (item?.type === "search_results") {
        process.stdout.write("\n[Searching the web...]\n");
      }
    }
    if (chunk.type === "response.completed") {
      const usage = (chunk as any).response?.usage;
      if (usage) {
        process.stdout.write(`\n\n[Tokens: ${usage.input_tokens} in / ${usage.output_tokens} out]`);
      }
    }
  }
  process.stdout.write("\n");
  return fullResponse;
}

// --- Command handling ---

function handleCommand(cmd: string, state: { webSearch: boolean; history: Message[] }): boolean {
  switch (cmd.toLowerCase()) {
    case "/quit": case "/exit":
      console.log("Goodbye."); return true;
    case "/search":
      state.webSearch = true; console.log("Web search enabled."); return false;
    case "/nosearch":
      state.webSearch = false; console.log("Web search disabled."); return false;
    case "/clear":
      state.history = []; console.log("History cleared."); return false;
    case "/help":
      console.log("\n  /search  /nosearch  /clear  /quit  /help\n"); return false;
    default:
      console.log(`Unknown command: ${cmd}. Type /help.`); return false;
  }
}

// --- Main ---

async function main(): Promise<void> {
  const client = new Perplexity();
  const rl = createRL();
  const model = await selectModel(rl);
  const state = { webSearch: true, history: [] as Message[] };

  console.log("Type a message to chat, or /help for commands. Web search is ON.\n");
  process.on("SIGINT", () => { console.log("\nGoodbye."); rl.close(); process.exit(0); });

  while (true) {
    const input = await ask(rl, "> ");
    if (!input) continue;
    if (input.startsWith("/")) { if (handleCommand(input, state)) break; continue; }

    try {
      const response = await streamQuery(client, model, state.history, input, state.webSearch);
      state.history.push({ role: "user", content: input });
      state.history.push({ role: "assistant", content: response });
      if (state.history.length > 20) state.history = state.history.slice(-20);
    } catch (error: unknown) {
      if (error instanceof Perplexity.APIConnectionError) {
        console.error("\nConnection error. Check your network.");
      } else if (error instanceof Perplexity.RateLimitError) {
        console.error("\nRate limit exceeded. Wait and retry.");
      } else if (error instanceof Perplexity.APIStatusError) {
        console.error(`\nAPI error: ${(error as any).message}`);
      } else {
        console.error("\nUnexpected error:", error);
      }
    }
    console.log();
  }
  rl.close();
}

main();
```

## Example Session

```
Available models:
  1. OpenAI GPT-5.1 (openai/gpt-5.4)
  2. Google Gemini 3 Flash (google/gemini-3.1-flash-lite)

Select a model (1-2): 1
Using model: openai/gpt-5.4

Type a message to chat, or /help for commands. Web search is ON.

> What were the major AI announcements this week?
[Searching the web...]
This week saw several notable AI developments:
1. Anthropic released Claude 4 with improved reasoning...
2. Google DeepMind published new protein folding results...
3. OpenAI announced enterprise partnerships for GPT-5...

[Tokens: 1420 in / 287 out]

> /nosearch
Web search disabled.

> Explain transformers in simple terms
A transformer is a neural network architecture that processes all
parts of an input simultaneously rather than sequentially...

[Tokens: 2580 in / 195 out]

> /quit
Goodbye.
```

## Key TypeScript Patterns

### Const Assertions for Tool Types

Use `as const` to narrow tool type literals:

```typescript theme={null}
const tools = [{ type: "web_search" as const }];
```

### Streaming Event Type Narrowing

Check `chunk.type` before accessing event-specific fields:

```typescript theme={null}
for await (const chunk of stream) {
  if (chunk.type === "response.output_text.delta") {
    process.stdout.write((chunk as any).delta);
  }
}
```

### Typed Error Handling

```typescript theme={null}
try {
  // API call
} catch (error) {
  if (error instanceof Perplexity.APIConnectionError) {
    // Handle network issues
  } else if (error instanceof Perplexity.RateLimitError) {
    // Handle rate limits
  }
}
```

<Tip>
  Conversation history is preserved across turns, so the model can reference earlier messages. Use `/clear` to start a fresh conversation without restarting the CLI.
</Tip>

## Limitations

* The CLI uses Node.js `readline`, which does not support arrow-key history navigation. For a richer experience, consider `inquirer` or `prompts`.
* Conversation history is in-memory only and lost when the process exits.
* Streaming events may vary by model provider. The `response.output_text.delta` event is consistent across all models.


# Perplexity API Cookbook
Source: https://docs.perplexity.ai/docs/cookbook/index

Practical guides, runnable examples, and integration patterns for building with every Perplexity API

A collection of practical guides, runnable examples, and integration patterns for building with [**Perplexity's API Platform**](https://docs.perplexity.ai/) — covering the Agent API, Search API, Embeddings API, and Sonar API.

## How to Use This Cookbook

<CardGroup>
  <Card title="Guides" icon="book" href="/docs/cookbook/articles/function-calling-e2e/README">
    Practical deep-dives on patterns that go beyond the docs — structured outputs, function calling, RAG pipelines, and cross-cutting best practices.
  </Card>

  <Card title="Examples" icon="code-circle" href="/docs/cookbook/examples/README">
    Runnable projects covering every API. From research assistants and news monitors to document Q\&A and image analysis — with Python and TypeScript.
  </Card>

  <Card title="Integration Guides" icon="link" href="/docs/cookbook/articles/openai-agents-integration/README">
    Connect Perplexity with external frameworks like the OpenAI Agents SDK, LangChain memory systems, and persistent storage.
  </Card>

  <Card title="Community Showcase" icon="sparkles" href="/docs/cookbook/showcase/briefo">
    Real-world applications built by the community — see what others are building with the API Platform.
  </Card>
</CardGroup>

## Quick Start

<Steps>
  <Step title="Get API Access">
    To use the Perplexity API Platform, you'll need an API key. If you don't have one yet:

    <Card title="Get your Perplexity API Key" icon="key" href="https://perplexity.ai/account/api">
      Navigate to the **API Keys** tab in the API Portal and generate a new key.
    </Card>
  </Step>

  <Step title="Install the SDK">
    The Perplexity API SDK is available in Python and TypeScript. Install the package for your preferred language:

    <CodeGroup>
      ```bash Python theme={null}
      pip install perplexityai
      ```

      ```bash TypeScript theme={null}
      npm install @perplexity-ai/perplexity_ai
      ```
    </CodeGroup>
  </Step>

  <Step title="Pick a Starting Point">
    The Perplexity API Platform supports a wide range of use cases across its different APIs. Here are some recommended starting points based on your goals:

    * New to the platform? Refer to our <u>[Quick Start Guide](/docs/getting-started/quickstart)</u>
    * Want to build something? Take a look at our <u>[Examples](/docs/cookbook/examples/README)</u>
  </Step>
</Steps>

## What's Covered

| API                | Guides                                                                                                                                                                                                                                                                 | Examples                                                                                                                                                                                                                                                                                                                                                              |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Agent API**      | [Multi-Provider Orchestration](/docs/cookbook/articles/multi-provider-orchestration/README), [Function Calling End-to-End](/docs/cookbook/articles/function-calling-e2e/README), [OpenAI Agents Integration](/docs/cookbook/articles/openai-agents-integration/README) | [Research Assistant](/docs/cookbook/examples/agent-research-assistant/README), [Model Comparison](/docs/cookbook/examples/model-comparison/README), [TypeScript CLI](/docs/cookbook/examples/typescript-agent-cli/README), [Image Analysis](/docs/cookbook/examples/image-analysis/README), [File Attachment Q\&A](/docs/cookbook/examples/file-attachment-qa/README) |
| **Search API**     | [Search Domain Filtering](/docs/cookbook/articles/search-domain-filtering/README)                                                                                                                                                                                      | [News Monitor](/docs/cookbook/examples/search-news-monitor/README), [SEC Filing Search](/docs/cookbook/examples/sec-filing-search/README)                                                                                                                                                                                                                             |
| **Embeddings API** | [RAG Pipeline](/docs/cookbook/articles/embeddings-rag/README)                                                                                                                                                                                                          | [Document Q\&A](/docs/cookbook/examples/document-qa/README)                                                                                                                                                                                                                                                                                                           |
| **Sonar API**      | [Streaming Citations](/docs/cookbook/articles/streaming-citations/README), [Academic Search](/docs/cookbook/articles/academic-search/README), [Async Deep Research](/docs/cookbook/articles/async-deep-research/README)                                                | —                                                                                                                                                                                                                                                                                                                                                                     |


# 4Point Hoops | AI Basketball Analytics Platform
Source: https://docs.perplexity.ai/docs/cookbook/showcase/4point-Hoops

Advanced NBA analytics platform that combines live Basketball-Reference data with Perplexity Sonar to deliver deep-dive player stats, cross-season comparisons and expert-grade AI explanations

![4Point Hoops Dashboard](https://d112y698adiu2z.cloudfront.net/photos/production/software_photos/003/442/047/datas/original.png)

**4Point Hoops** is an advanced NBA analytics platform that turns raw basketball statistics into actionable, narrative-driven insights. By scraping Basketball-Reference in real time and routing context-rich prompts to Perplexity's Sonar Pro model, it helps fans, analysts, and fantasy players understand the "why" and "what's next" – not just the numbers.

<iframe title="YouTube video player" />

## Features

* **Player Analytics** with season & playoff splits, shot-type breakdowns, and performance radar for any NBA player
* **Cross-Era Comparisons** enabling side-by-side stat comparisons (e.g., Michael Jordan '97 vs. Stephen Curry '22)
* **Team Dashboards** with standings, playoff-probability Sankey flows, and auto-refreshing KPI tiles
* **AI Explain & Similar Players** providing one-click Sonar explanations of stat lines and AI-picked comparable athletes
* **Basketball AI Chat** allowing users to ask an expert LLM about NBA history, rosters, or projections
* **Credit-Based SaaS System** with Firebase Auth, Google login, credit wallets, and admin tooling

## Prerequisites

* Node.js 16+ and npm
* Python 3.8+ and pip
* Firebase project setup
* Perplexity API key (Sonar Pro)
* Basketball-Reference access

## Installation

```bash theme={null}
# Clone the frontend repository
git clone https://github.com/rapha18th/hoop-ai-frontend-44.git
cd hoop-ai-frontend-44
npm install

# Clone the backend repository
git clone https://github.com/rapha18th/4Point-Hoops-Server.git
cd 4Point-Hoops-Server
pip install -r requirements.txt
```

## Configuration

Create `.env` file in the backend directory:

```ini theme={null}
PERPLEXITY_API_KEY=your_sonar_pro_api_key
FIREBASE_PROJECT_ID=your_firebase_project_id
FIREBASE_PRIVATE_KEY=your_firebase_private_key
FIREBASE_CLIENT_EMAIL=your_firebase_client_email
```

## Usage

1. **Start Backend**:
   ```bash theme={null}
   cd 4Point-Hoops-Server
   python app.py
   ```

2. **Start Frontend**:
   ```bash theme={null}
   cd hoop-ai-frontend-44
   npm run dev
   ```

3. **Access Application**: Open the frontend URL and explore NBA analytics with AI-powered insights

4. **Use AI Features**: Click "AI Explain" on any player or stat to get intelligent analysis powered by Perplexity Sonar

## Code Explanation

* **Frontend**: React with shadcn/ui components and Recharts for data visualization
* **Backend**: Python Flask API serving Basketball-Reference data and managing Perplexity API calls
* **Data Pipeline**: BRScraper for real-time data collection with Firebase caching
* **AI Integration**: Perplexity Sonar Pro for intelligent basketball analysis and explanations
* **Authentication**: Firebase Auth with Google login and credit-based access control
* **Deployment**: Frontend on Netlify, backend on Hugging Face Spaces with Docker

## Links

* [Frontend Repository](https://github.com/rapha18th/hoop-ai-frontend-44)
* [Backend Repository](https://github.com/rapha18th/4Point-Hoops-Server)
* [Live Demo](https://4pointhoops.netlify.app/)
* [Devpost Submission](https://devpost.com/software/4point-hoops)


# Ellipsis | One-Click Podcast Generation Agent
Source: https://docs.perplexity.ai/docs/cookbook/showcase/Ellipsis

A next-gen podcast generation agent that brings human-like, high-quality audio content to life on any topic with just one click

**Ellipsis** is a next-generation podcast generation agent that brings human-like, high-quality audio content to life on any topic with just one click. Whether it's breaking news, deep-dive tech explainers, movie reviews, or post-match sports breakdowns, Ellipsis crafts intelligent podcast episodes that sound like they were created by seasoned hosts in a professional studio.

## Features

* **Intelligent Multi-Speaker Dialogue** with multiple distinct voices and personalities
* **Comprehensive Topic Coverage** from LLM architectures to lunar eclipses
* **Custom Evaluation Engine** ensuring factual accuracy, legal compliance, and conversational quality
* **Fully Automated Podcast Generation** with human-like, podcast-ready audio output
* **Real-time Streaming Updates** via Server-Sent Events (SSE)
* **Podbean Integration** for direct podcast publishing
* **Trending Topics Detection** using Perplexity API

## Prerequisites

* Node.js v16+ and npm/yarn
* Python 3.10+ and pip
* Redis server running (default on port 6380)
* Perplexity API key, Podbean credentials

## Installation

```bash theme={null}
# Clone the repository
git clone https://github.com/dineshkannan010/Ellipsis.git
cd Ellipsis

# Backend setup
cd backend
python -m venv venv
source venv/bin/activate    # macOS/Linux
pip install -r requirements.txt

# Install native packages
pip install llama-cpp-python --extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cpu
pip install git+https://github.com/freddyaboulton/orpheus-cpp.git
pip install huggingface_hub[hf_xet] hf_xet

# Frontend setup
cd ../frontend
npm install
```

## Configuration

Create `backend/.env`:

```ini theme={null}
REDIS_URL=redis://your-redis-host:6379
PERPLEXITY_API_KEY=your_key_here
PODBEAN_CLIENT_ID=...
PODBEAN_CLIENT_SECRET=...
```

Create `frontend/.env`:

```ini theme={null}
REACT_APP_API_URL=http://your-backend-host:5000
```

## Usage

1. **Start Redis Server**:
   ```bash theme={null}
   redis-server --port 6380
   ```

2. **Launch Backend**:
   ```bash theme={null}
   cd backend
   python app.py
   ```

3. **Launch Frontend**:
   ```bash theme={null}
   cd frontend
   npm run dev
   ```

4. **Optional: Podbean Integration**:
   ```bash theme={null}
   cd backend/integrations/podbean_mcp
   pip install -e .
   python server.py
   python client.py server.py
   ```

5. **Generate Content**: Enter a topic in the homepage textbox and hit Enter. Switch to `ContentGenerationView` to see live script & audio progress.

## Code Explanation

* **Backend**: Python Flask with Redis pub/sub, llama.cpp, and Orpheus TTS for audio generation
* **Frontend**: React with Vite, Tailwind CSS, and Server-Sent Events for real-time updates
* **AI Integration**: Perplexity API for content generation and trending topics detection
* **Audio Processing**: Multi-speaker TTS with distinct voice personalities
* **Content Evaluation**: Built-in pipelines for factual accuracy and legal compliance
* **Podcast Publishing**: Direct integration with Podbean via MCP server

## Demo Video

<iframe title="YouTube video player" />

## Links

* [GitHub Repository](https://github.com/dineshkannan010/Ellipsis)
* [Devpost Submission](https://devpost.com/software/ellipsis)


# BazaarAISaathi | AI-Powered Indian Stock Market Assistant
Source: https://docs.perplexity.ai/docs/cookbook/showcase/bazaar-ai-saathi

An AI-powered platform for Indian stock market analysis, portfolio optimization, and investment strategies using Perplexity Sonar API

**BazaarAISaathi** is an AI-powered platform designed to empower investors with actionable insights into the Indian stock market. Leveraging advanced natural language processing, real-time data analytics, and expert-driven financial modeling, the app delivers personalized investment strategies, market sentiment analysis, and portfolio optimization recommendations.

## Features

* **Financial Independence Planner (FIRE)** with personalized plans based on age, salary, and goals
* **Investment Advice Tester** using EasyOCR for text extraction and AI validation
* **Fundamental & Technical Analysis** with comprehensive company reports and trading strategies
* **Portfolio Analysis** with multi-dimensional analysis and stock-wise recommendations
* **Market Research & Competitor Benchmarking** using AI-driven industry trend analysis
* **Real-Time Stock Data** with live price tracking and trend analysis
* **Hypothesis Testing** using historical and real-time market data
* **Investment Books Summary** with concise summaries of top 50 investment books

## Prerequisites

* Python 3.8+ and pip
* Streamlit for web application framework
* Perplexity API key (Sonar models)
* Optional: EasyOCR for image text extraction

## Installation

```bash theme={null}
# Clone the repository
git clone https://github.com/mahanteshimath/BazaarAISaathi.git
cd BazaarAISaathi

# Install dependencies
pip install -r requirements.txt
```

## Configuration

Create `secrets.toml` file for Streamlit secrets:

```ini theme={null}
PERPLEXITY_API_KEY = "your_perplexity_api_key"
# Add other API keys as needed
```

## Usage

1. **Start the Application**:
   ```bash theme={null}
   streamlit run Home.py
   ```

2. **Access Features**:
   * Navigate through different pages for specific functionality
   * Use the main dashboard for overview and navigation
   * Access specialized tools like portfolio analysis, FIRE planning, and tip testing

3. **Run Specific Modules**:
   ```bash theme={null}
   streamlit run pages/Financial_Independence.py
   streamlit run pages/Portfolio_Analysis.py
   streamlit run pages/Tip_Tester.py
   ```

## Code Explanation

* **Frontend**: Streamlit web application with interactive pages and real-time data visualization
* **Backend**: Python-based business logic with Pandas for data manipulation and analysis
* **AI Integration**: Perplexity Sonar API models (sonar-deep-research, sonar-reasoning-pro, sonar-pro) for financial analysis
* **Data Processing**: Real-time stock data fetching, CSV data management, and market insights generation
* **Text Extraction**: EasyOCR integration for processing investment tips from images
* **Portfolio Management**: Comprehensive portfolio analysis with optimization recommendations
* **Market Analysis**: Technical and fundamental analysis with sentiment scoring

## Demo Video

<iframe title="YouTube video player" />

## Links

* [GitHub Repository](https://github.com/mahanteshimath/BazaarAISaathi)
* [Live Application](https://bazaar-ai-saathi.streamlit.app/)
* [Architecture Diagram](https://github.com/mahanteshimath/BazaarAISaathi/raw/main/src/App_Architecture.jpg)


# Briefo | Perplexity Powered News & Finance Social App
Source: https://docs.perplexity.ai/docs/cookbook/showcase/briefo

AI curated newsfeed, social discussion, and deep research reports built on the Sonar API

**Briefo** delivers a personalized, AI generated newsfeed and company deep dives. Readers can follow breaking stories, request on demand financial analyses, and discuss insights with friends, all in one mobile experience powered by Perplexity’s Sonar API.

## Features

* Personalized newsfeed across 17 categories with AI summaries and source links
* Private and public threads for article discussion and sharing
* Watch list with real time market snapshots and optional AI analyses
* Deep research reports generated on 12 selectable criteria such as management, competitors, and valuation
* General purpose chat assistant that remembers each user’s preferred topics

## Prerequisites

* Node 18 LTS or newer
* npm, Yarn, or pnpm
* Expo CLI (`npm i -g expo-cli`)
* Supabase CLI 1.0 or newer for local emulation and Edge Function deploys

## Installation

```bash theme={null}
git clone https://github.com/adamblackman/briefo-public.git
cd briefo-public
npm install
```

### Environment Variables

```ini theme={null}
# .env              (project root)
MY_SUPABASE_URL=https://<project>.supabase.co
MY_SUPABASE_SERVICE_ROLE_KEY=...
PERPLEXITY_API_KEY=...
LINKPREVIEW_API_KEY=...
ALPACA_API_KEY=...
ALPACA_SECRET_KEY=...

# .env.local        (inside supabase/)
# duplicate or override any secrets needed by Edge Functions
```

## Usage

Run the Expo development server:

```bash theme={null}
npx expo start
```

Deploy Edge Functions when you are ready:

```bash theme={null}
supabase functions deploy perplexity-news perplexity-chat perplexity-research portfolio-tab-data
```

## Code Explanation

* Frontend: React Native with Expo Router (Typescript) targeting iOS, Android, and Web
* Backend: Supabase (PostgreSQL, Row Level Security, Realtime) for data and authentication
* Edge Functions: Typescript on Deno calling Perplexity, Alpaca, Alpha Vantage, and LinkPreview APIs
* Hooks: Reusable React Query style data hooks live in lib/ and hooks/
* Testing and Linting: ESLint, Prettier, and Expo Lint maintain code quality

## Links

[GitHub Repository](https://github.com/adamblackman/briefo-public)
[Live Demo](https://www.briefo.fun/)


# CityPulse | AI-Powered Geospatial Discovery Search
Source: https://docs.perplexity.ai/docs/cookbook/showcase/citypulse-ai-search

Real-time local discovery search using Perplexity AI for personalized location insights and recommendations

# CityPulse - AI-Powered Geospatial Discovery

![CityPulse Main Interface](https://raw.githubusercontent.com/anevsky/CityPulse/main/assets/CityPulse-GeoSearch-App-1.jpg)

CityPulse is an intelligent location-based discovery search that helps users explore what's happening around them right now. It demonstrates how to create personalized, real-time local insights using Perplexity's Sonar models.

[![Demo Video](https://cdn.loom.com/sessions/thumbnails/6507fa27571442e680edf787b0f0690d-2fa2c36169822631-full-play.gif)](https://youtu.be/Y0UIhh3diJg)

## What CityPulse Does

* **Real-time local discovery** - Find current events, restaurants, and local alerts near any location
* **AI-powered search suggestions** - Get intelligent search recommendations as you type
* **Personalized insights** - Receive AI-generated advice on what to try, best times to visit, and pro tips
* **Interactive mapping** - Explore results on an interactive map with custom markers and detailed popups

![Search Interface](https://raw.githubusercontent.com/anevsky/CityPulse/main/assets/CityPulse-GeoSearch-App-2.jpg)

## How It Uses Perplexity Sonar

CityPulse leverages two key Perplexity models:

**Sonar for Real-Time Data**

```python theme={null}
# Get current local information with geographic context
response = client.chat.completions.create(
    model="sonar",
    messages=[{
        "role": "user", 
        "content": f"Find current events, restaurants, and alerts near {lat}, {lng}"
    }],
    response_format={"type": "json_schema", "json_schema": {"schema": LOCAL_INFO_SCHEMA}}
)
```

**Sonar Reasoning Pro for Personalized Insights**

```python theme={null}
# Generate AI-powered location recommendations
response = client.chat.completions.create(
    model="sonar-reasoning-pro",
    messages=[{
        "role": "user",
        "content": f"Provide personalized insights for {location_name}: what to try, best times to visit, pro tips"
    }]
)
```

The app uses structured JSON schemas to ensure consistent data formatting and includes citation tracking for source verification.

![AI Insights](https://raw.githubusercontent.com/anevsky/CityPulse/main/assets/CityPulse-GeoSearch-App-3.jpg)

## Links

* [GitHub Repository](https://github.com/anevsky/CityPulse)
* [Live Demo](https://citypulse-ppx.uc.r.appspot.com/)
* **[Built with ❤️ by Alex Nevsky](https://alexnevsky.com)**


# CycleSyncAI | Personalized Health Plans Powered by Sonar API
Source: https://docs.perplexity.ai/docs/cookbook/showcase/cycle-sync-ai

iOS app that delivers personalized diet and workout recommendations for women, powered by Apple HealthKit and Perplexity's Sonar Pro API.

**CycleSyncAI** is an iOS app designed to provide personalized **diet and workout recommendations** tailored to a woman's **menstrual cycle phase**.

By integrating menstrual data from Apple **HealthKit** and optional user profile inputs (age, weight, height, medical conditions, dietary restrictions, goals, and preferences), the app generates dynamic, phase-aware suggestions to support holistic wellness.

Unlike static wellness tools, **CycleSyncAI** leverages **Perplexity's Sonar Pro API** to deliver **expert-informed**, LLM-generated guidance — including a daily grocery list and motivational feedback — customized to the user's cycle and lifestyle.

## Problem & Solution

> **Why it matters:**\
> Most apps overlook the hormonal changes that affect women's fitness and nutrition needs across their cycle, leaving users with generic advice.

**CycleSyncAI** bridges this gap by combining Apple HealthKit data with Sonar Pro's LLM to generate **adaptive, cycle-aware recommendations** for better health outcomes.

## Features

* **Personalized diet & workout suggestions** per cycle phase
* Syncs with Apple HealthKit for real-time cycle tracking
* User profile inputs for advanced personalization (age, goals, restrictions, etc.)
* **Auto-generated daily grocery list**
* Smooth, modern UI with gradients and subtle animations
* **Motivational AI feedback** tailored to user preferences
* Local data storage and private processing

## Motivation

> "I wanted a tailored regime for myself and couldn't find it all in one place."

**CycleSyncAI** was born from the need for a science-backed, easy-to-use app that adapts wellness guidance to women's natural hormonal rhythms, something missing in most mainstream fitness and nutrition platforms.

## Repository Structure

```text theme={null}
CycleSyncAI.xcodeproj          → Xcode project file  
CycleSyncAI/                   → Source code  
├── EatPlanViewController.swift        → Diet plan generation & display  
├── WorkoutPlanViewController.swift    → Workout plan generation & display  
├── HomepageViewController.swift       → Navigation & main screen  
├── UserProfileViewController.swift    → Input & storage of user data  
├── HealthManager.swift                → Apple HealthKit menstrual data  
├── UserProfile.swift                  → Local profile model  
Main.storyboard               → App UI & layout  
Assets.xcassets              → Images & app icons  
Info.plist                   → Permissions & configurations  
```

## Setup Instructions

1. Clone the repo
2. Open in **Xcode**
3. Ensure Apple HealthKit is enabled on your device
4. Insert your **Sonar Pro API key**
5. Run the app on a physical device (recommended)

## Sonar API Usage

The app sends structured prompts to the **Sonar Pro API** including:

* Cycle phase (from HealthKit)
* User profile info (age, weight, goals, etc.)
* Meal preferences & restrictions

In return, it receives:

* **Personalized diet plan**
* **Custom workout plan**
* **Daily grocery list**
* **Motivational feedback**

These are parsed and rendered as styled HTML inside the app using WebViews.

## Demo Video

<iframe title="YouTube video player" />

> *Note: The LLM takes \~30–60 seconds per request. This wait time was trimmed in the video for brevity.*

## Impact

**CycleSyncAI** empowers women to make informed, body-aware decisions in daily life. The app supports better:

* Energy management
* Fitness results
* Mental well-being
* Motivation and confidence

It also reduces decision fatigue with automatically prepared grocery lists and uplifting guidance.

## Links

* [GitHub Repository](https://github.com/medhini98/cyclesyncai-api-cookbook)


# Daily News Briefing | AI-Powered News Summaries for Obsidian
Source: https://docs.perplexity.ai/docs/cookbook/showcase/daily-news-briefing

An Obsidian plugin that delivers AI-powered daily news summaries directly to your vault using Perplexity's Sonar API for intelligent content curation

**Daily News Briefing** is an Obsidian plugin that delivers AI-powered news summaries directly to your vault. Stay informed about your topics of interest with smart, automated news collection and summarization using Perplexity's Sonar API for intelligent content curation.

<iframe title="Daily News Briefing Demo" />

## Features

* **Personalized News Collection** based on your topics of interest and preferences
* **AI-Powered Summarization** of news articles using Perplexity Sonar API
* **Automated Daily Briefings** delivered directly to your Obsidian vault
* **Customizable Delivery Schedule** and format options
* **Seamless Obsidian Integration** with your existing knowledge management workflow
* **Trusted Source Filtering** to ensure quality and reliability
* **Markdown Formatting** for easy linking and organization within your vault

## Prerequisites

* Obsidian desktop app installed
* Perplexity API key (Sonar API access)
* Internet connection for fetching news articles
* Typescript development environment (for customization)

## Installation

```bash theme={null}
# Clone the repository
git clone https://github.com/ChenziqiAdam/Daily-News-Briefing.git
cd Daily-News-Briefing

# Install dependencies
npm install

# Build the plugin
npm run build
```

## Configuration

1. **Install Plugin**: Copy the built plugin to your Obsidian plugins folder
2. **Enable Plugin**: Activate in Obsidian settings
3. **API Setup**: Enter your Perplexity API key in plugin settings
4. **Configure Topics**: Set up your news topics and delivery preferences

## Usage

1. **Configure Interests**: Set up preferred topics, sources, and delivery schedule
2. **Automated Collection**: Plugin uses Perplexity Sonar API to gather latest news
3. **AI Summarization**: Articles are processed and summarized using Perplexity's capabilities
4. **Vault Delivery**: Summaries are formatted as Markdown notes in your Obsidian vault
5. **Knowledge Integration**: Link news briefings with other notes in your knowledge base

## Code Explanation

* **Frontend**: Typescript-based Obsidian plugin with custom UI components
* **AI Integration**: Perplexity Sonar API for intelligent news gathering and summarization
* **Content Processing**: Automated article extraction and summarization workflows
* **Scheduling**: Configurable delivery schedules and topic monitoring
* **Markdown Generation**: Structured content formatting for Obsidian compatibility
* **Error Handling**: Robust error management for API limits and network issues

## Technical Implementation

The plugin leverages Perplexity Sonar API for:

```typescript theme={null}
// News gathering with Perplexity Sonar API
const newsQuery = `latest news about ${topic} in the past 24 hours`;
const searchResponse = await perplexityClient.search({
  query: newsQuery,
  max_results: 5,
  include_domains: userPreferences.trustedSources || []
});

// AI-powered summarization
const summaryPrompt = `Summarize these news articles about ${topic}`;
const summaryResponse = await perplexityClient.generate({
  prompt: summaryPrompt,
  model: "sonar-medium-online",
  max_tokens: 500
});
```

## Links

* [GitHub Repository](https://github.com/ChenziqiAdam/Daily-News-Briefing)


# Executive Intelligence | AI-Powered Strategic Decision Platform
Source: https://docs.perplexity.ai/docs/cookbook/showcase/executive-intelligence

A comprehensive Perplexity Sonar-powered application that provides executives and board members with instant, accurate, and credible intelligence for strategic decision-making

**Executive Intelligence** is a comprehensive Perplexity Sonar-powered application that provides executives and board members with instant, accurate, and credible intelligence for strategic decision-making. It delivers board-ready insights derived from real-time data sources, powered by Perplexity's Sonar API.

<iframe title="YouTube video player" />

## Features

* **Competitive Intelligence Briefs** with comprehensive, board-ready competitive analysis and verifiable citations
* **Scenario Planning ("What If?" Analysis)** for dynamic future scenario generation based on real-time data
* **Board Pack Memory** for saving and organizing intelligence briefs, scenario analyses, and benchmark reports
* **Instant Benchmarking & Peer Comparison** with source-cited visual comparisons across critical metrics
* **Real-time Data Integration** leveraging Perplexity Sonar API for up-to-date market intelligence
* **Professional Formatting** with structured reports, executive summaries, and board-ready presentations

## Prerequisites

* Node.js 18+ and npm/yarn
* Git
* Perplexity API key (Sonar Pro)

## Installation

```bash theme={null}
# Clone the repository
git clone https://github.com/raishs/perplexityhackathon.git
cd perplexityhackathon

# Install dependencies
npm install

# Set up environment variables
cp .env.example .env.local
```

## Configuration

Create `.env.local` file:

```ini theme={null}
PERPLEXITY_API_KEY=your_perplexity_api_key
```

## Usage

1. **Start Development Server**:
   ```bash theme={null}
   npm run dev
   ```

2. **Access Application**: Open [http://localhost:3000](http://localhost:3000) in your browser

3. **Generate Intelligence**:
   * Enter a company name in the input field
   * Click "Competitive Analysis" for comprehensive briefs
   * Use "Scenario Planning" for "what-if" analysis
   * Access "Benchmarking" for peer comparisons
   * Save reports to "Board Pack" for later access

4. **Board Pack Management**: Use the "📁 Board Pack" button to view and manage saved intelligence reports

## Code Explanation

* **Frontend**: Next.js with Typescript and React for modern, responsive UI
* **Backend**: Next.js API routes handling Perplexity Sonar API integration
* **AI Integration**: Perplexity Sonar Pro for real-time competitive intelligence and scenario analysis
* **State Management**: React Context for boardroom memory and persistent data storage
* **Markdown Processing**: Custom utilities for parsing AI responses and citation handling
* **Error Handling**: Comprehensive timeout and error management for API calls
* **Professional Output**: Structured formatting for board-ready presentations with source citations

## Links

* [GitHub Repository](https://github.com/raishs/perplexityhackathon)


# Fact Dynamics | Real-time Fact-Checking Flutter App
Source: https://docs.perplexity.ai/docs/cookbook/showcase/fact-dynamics

Cross-platform app for real-time fact-checking of debates, speeches, and images using Perplexity's Sonar API

# Fact Dynamics | Real-time Fact-Checking Flutter App

<p>
  <img alt="Fact Dynamics logo" />
</p>

**Hackathon Submission** - Built for Perplexity Hackathon in Information Tools & Deep Research categories.

Fact Dynamics is a cross-platform Flutter app that provides real-time fact-checking for spoken content and images. Perfect for live debates, presentations, and on-the-fly information verification.

## Features

* Real-time speech transcription and fact-checking during live conversations

* Image text extraction and claim verification with source citations

* Claim rating system (TRUE, FALSE, MISLEADING, UNVERIFIABLE) with explanations

* Source citations - Provides authoritative URLs backing each verdict

* Debate mode with continuous speech recognition and streaming feedback

* User authentication via Firebase (Google, Email) with persistent chat history

* Cross-platform support for iOS, Android, and Web

## Prerequisites

* Flutter SDK 3.0.0 or newer
* Dart SDK 2.17.0 or newer
* Firebase CLI for authentication and database setup
* Perplexity API key for Sonar integration
* Device with microphone access for speech recognition

## Installation (Follow Detailed guideline on the Repository)

```bash theme={null}
git clone https://github.com/vishnu32510/fact_pulse.git
cd fact_pulse
flutter pub get
```

## Usage

### Real-time Speech Fact-Checking

* Streams 5-second audio chunks through Flutter's `speech_to_text`
* Sends transcribed snippets to Sonar API with structured prompts
* Returns JSON with claims, ratings (TRUE/FALSE/MISLEADING/UNVERIFIABLE), explanations, and sources

### Image Analysis

* Uploads images/URLs to Sonar API for text extraction
* Verifies extracted claims against authoritative sources
* Provides comprehensive analysis with source attribution

## Screenshots

<table>
  <tr>
    <td>
      <img alt="Dashboard" />
    </td>

    <td>
      <img alt="Fact checking interface" />
    </td>
  </tr>
</table>

## Code Explanation

* Frontend: Flutter with BLoC pattern for state management targeting iOS, Android, and Web
* Backend: Firebase (Firestore, Authentication) for user data and chat history persistence
* Speech Processing: speech\_to\_text package for real-time audio transcription
* API Integration: Custom Dart client calling Perplexity Sonar API with structured prompts
* Image Processing: Built-in image picker with base64 encoding for multimodal analysis
* Data Architecture: Firestore collections per user with subcollections for debates, speeches, and images

## Open Source SDKs

Built two reusable packages for the Flutter community:

* **[perplexity\_dart](https://pub.dev/packages/perplexity_dart)** - Core Dart SDK for Perplexity API
* **[perplexity\_flutter](https://pub.dev/packages/perplexity_flutter)** - Flutter widgets and BLoC integration

## Demo Video

<iframe title="YouTube video player" />

## Links

* **[GitHub Repository](https://github.com/vishnu32510/fact_pulse)** - Full source code
* **[Live Demo](https://fact-pulse.web.app/)** - Try the web version
* **[Devpost Submission](https://devpost.com/software/fact-dynamics)** - Hackathon entry


# FirstPrinciples | AI Learning Roadmap Generator
Source: https://docs.perplexity.ai/docs/cookbook/showcase/first-principle

An AI-powered learning roadmap generator that uses conversational AI to help users identify specific learning topics and provides personalized step-by-step learning plans

**FirstPrinciples App** is an AI-powered tool that transforms your broad learning goals into structured, personalized roadmaps. Through an interactive chat, the AI engages you in a conversation, asking targeted questions to refine your learning needs before generating a detailed plan. The application is built to help you learn more efficiently by providing a clear path forward.

<video />

## Features

* **Interactive Chat Interface** for defining and refining learning goals through conversation
* **AI-Powered Topic Narrowing** with smart, targeted questions to specify learning objectives
* **Session Management** allowing multiple roadmap discussions and progress tracking
* **Visual Progress Indicators** showing when sufficient information has been gathered
* **Personalized Learning Plans** with structured, step-by-step roadmaps
* **Conversational AI Flow** combining OpenAI and Perplexity APIs for intelligent interactions

## Prerequisites

* Python 3.8+ and pip
* Node.js 16+ and npm
* OpenAI API key
* Perplexity API key

## Installation

```bash theme={null}
# Clone the repository
git clone https://github.com/william-Dic/First-Principle.git
cd First-Principle

# Backend setup
cd flask-server
pip install -r requirements.txt

# Frontend setup
cd ../client
npm install
```

## Configuration

Create `.env` file in the `flask-server` directory:

```ini theme={null}
OPENAI_API_KEY=your_openai_api_key
PERPLEXITY_API_KEY=your_perplexity_api_key
PERPLEXITY_API_KEY=your_perplexity_api_key
```

## Usage

1. **Start Backend**:
   ```bash theme={null}
   cd flask-server
   python server.py
   ```
   Server runs on [http://localhost:5000](http://localhost:5000)

2. **Start Frontend**:
   ```bash theme={null}
   cd client
   npm start
   ```
   Client runs on [http://localhost:3000](http://localhost:3000)

3. **Generate Roadmap**:
   * Open [http://localhost:3000](http://localhost:3000) in your browser
   * Describe what you want to learn in the chat interface
   * Answer AI follow-up questions to refine your learning goals
   * Receive a personalized, structured learning roadmap

## Code Explanation

* **Frontend**: React application with conversational chat interface and progress indicators
* **Backend**: Flask server managing API calls, session state, and conversation flow
* **AI Integration**: Combines OpenAI API for conversational flow and Perplexity API for intelligent topic analysis
* **Session Management**: Tracks conversation state and learning goal refinement
* **Roadmap Generation**: Creates structured, actionable learning plans based on user input
* **Conversational Flow**: Implements goal-oriented dialogue to narrow down learning objectives

## Links

* [GitHub Repository](https://github.com/william-Dic/First-Principle.git)
* [Demo Video](https://github.com/user-attachments/assets/6016c5dd-6c18-415e-b982-fafb56170b87)


# FlameGuardAI | AI-powered wildfire prevention
Source: https://docs.perplexity.ai/docs/cookbook/showcase/flameguardai

AI-powered wildfire prevention using OpenAI Vision + Perplexity Sonar API

## 🧠 What it does

**FlameGuard AI™** helps homeowners, buyers, and property professionals detect and act on **external fire vulnerabilities** like wildfires or neighboring structure fires. It's more than a scan — it's a personalized research assistant for your home.

### Demo

<iframe title="YouTube video player" />

### Try It Out

* [FlameGuard AI](https://flameguardai.dlyog.com)
* [GitHub Repo](https://github.com/dlyog/fire-risk-assessor-drone-ai)

### Key Features:

* 📸 Upload a home photo
* 👁️ Analyze visible fire risks via **OpenAI Vision API**
* 📚 Trigger deep research using the **Perplexity Sonar API**
* 📄 Get a detailed, AI-generated report with:
  * Risk summary
  * Prevention strategies
  * Regional best practices
* 🛠️ Optional contractor referrals for mitigation
* 💬 Claude (MCP) chatbot integration for conversational analysis
* 🧾 GDPR-compliant data controls

Whether you're protecting your home, buying a new one, or just want peace of mind — **FlameGuard AI™ turns a photo into a plan**.

## ⚙️ How it works

### The FlameGuard AI™ Process

1. **📸 Upload**: User uploads a photo of their property
2. **👁️ AI Vision Analysis**: OpenAI Vision API identifies specific vulnerabilities (e.g., flammable roof, dry brush nearby)
3. **🔍 Deep Research**: For each risk, we generate a **custom research plan** and run **iterative agentic-style calls** to Perplexity Sonar
4. **📄 Report Generation**: Research is **aggregated, organized, and formatted** into an actionable HTML report — complete with citations, links, and visual guidance
5. **📧 Delivery**: Detailed report sent via email with DIY solutions and professional recommendations

### 🔍 Deep Research with Perplexity Sonar API

The real innovation is how we use the **Perplexity Sonar API**:

* We treat it like a research assistant gathering the best available information
* Each vulnerability triggers multiple queries covering severity, mitigation strategies, and localized insights
* Results include regional fire codes, weather patterns, and local contractor availability

This kind of **structured, trustworthy, AI-powered research would not be possible without Perplexity**.

### Technical Stack

FlameGuard AI™ is powered by a modern GenAI stack and built to scale:

* **Frontend**: Lightweight HTML dashboard with user account control, photo upload, and report access
* **Backend**: Python (Flask) with RESTful APIs
* **Database**: PostgreSQL (local) with **Azure SQL-ready** schema
* **AI Integration**: OpenAI Vision API + Perplexity Sonar API
* **Cloud-ready**: Built for **Azure App Service** with Dockerized deployment

## 🏆 Accomplishments that we're proud of

* Successfully used **OpenAI Vision + Perplexity Sonar API** together in a meaningful, real-world workflow
* Built a functioning **MCP server** that integrates seamlessly with Claude for desktop users
* Created a product that is **genuinely useful for homeowners today** — not just a demo
* Kept the experience simple, affordable, and scalable from the ground up
* Made structured deep research feel accessible and trustworthy

## 📚 What we learned

* The **Perplexity Sonar API** is incredibly powerful when used agentically — not just for answers, but for reasoning.
* Combining **multimodal AI (image + research)** opens up powerful decision-support tools.
* Users want **actionable insights**, not just data — pairing research with guidance makes all the difference.
* Trust and clarity are key: our design had to communicate complex information simply and helpfully.

## 🚀 What's next for FlameGuard AI™ - Prevention is Better Than Cure

We're just getting started.

### Next Steps:

* 🌐 Deploy to **Azure App Services** with production-ready database
* 📱 Launch mobile version with location-based scanning
* 🏡 Partner with **home inspection services** and **homeowners associations**
* 💬 Enhance Claude/MCP integration with voice-activated AI reporting
* 💸 Introduce B2B plans for real estate firms and home safety consultants
* 🛡️ Expand database of **local contractor networks** and regional fire codes

We're proud to stand with homeowners — not just to raise awareness, but to enable action.

**FlameGuard AI™ – Because some homes survive when others don't.**

***

**Contact us to know more: [info@dlyog.com](mailto:info@dlyog.com)**


# Flow & Focus | Personalized News for Genuine Understanding
Source: https://docs.perplexity.ai/docs/cookbook/showcase/flow-and-focus

A personalized news app combining vertical feed discovery with AI-powered deep dives using Perplexity Sonar Pro and Deep Research models

**Flow & Focus** is a personalized news application that transforms news consumption into a learning experience. It uniquely combines rapid discovery through a vertical news feed (Flow) with in-depth, interactive learning dialogues (Focus), powered by Perplexity's Sonar Pro and Sonar Deep Research models.

<iframe title="YouTube video player" />

## Features

* **Dual Mode Interface**: Flow Feed for quick news discovery and Focus for personalized deep dives
* **Vertical News Feed**: Swipeable news snippets with AI-generated summaries, tags, and background images
* **Interactive Deep Dives**: Tap key phrases for focused content, with horizontally scrollable detail panes
* **Personalized Learning**: AI-powered conversation segments with personas like "Oracle" and "Explorer"
* **Smart Personalization**: Tracks reading patterns to tailor content selection automatically
* **Real-time Content**: Leverages Sonar Pro for up-to-date news and Sonar Deep Research for detailed analysis
* **Visual Enhancement**: Dynamic background images generated via Runware.ai based on content keywords

## Prerequisites

* Node.js 18+ and npm
* Perplexity API key
* Runware API key for image generation
* Next.js 15 and React 19 environment

## Installation

```bash theme={null}
# Clone the repository
git clone https://github.com/michitomo/NewsReel.git
cd NewsReel

# Install dependencies
npm install

# Set up environment variables
cp .env.example .env.local
```

## Configuration

Create `.env.local` file:

```ini theme={null}
PERPLEXITY_API_KEY=your_perplexity_api_key_here
RUNWARE_API_KEY=your_runware_api_key_here
PERPLEXITY_FOCUS_MODEL=sonar-deep-research
```

## Usage

1. **Start Development Server**:
   ```bash theme={null}
   npm run dev
   ```

2. **Access Application**: Open [http://localhost:3000](http://localhost:3000) in your browser

3. **Flow Feed**: Scroll vertically through news snippets and tap key phrases for deep dives

4. **Focus Mode**: Generate personalized digests with interactive conversation segments

5. **Personalization**: Your viewing patterns automatically influence content selection

## Code Explanation

* **Frontend**: Next.js 15 with React 19, Typescript, Tailwind CSS, and Framer Motion for animations
* **State Management**: Zustand with localStorage persistence for user preferences
* **AI Integration**: Perplexity Sonar Pro for real-time news and Sonar Deep Research for in-depth analysis
* **Image Generation**: Runware SDK integration for dynamic background images based on content keywords
* **API Routes**: Server-side integration handling Perplexity and Runware API calls
* **Mobile-First Design**: Swipe gestures and responsive layout for intuitive mobile experience

## Links

* [GitHub Repository](https://github.com/michitomo/NewsReel)
* [Demo Video](https://www.youtube.com/watch?v=09h7zluuhQI)
* [Perplexity Hackathon](https://perplexityhackathon.devpost.com/)
* [Perplexity Hackathon Project](https://devpost.com/software/flow-focus)


# Greenify | Localized community-driven greenification/plantation solution with AI
Source: https://docs.perplexity.ai/docs/cookbook/showcase/greenify

A mobile application that analyzes photos and location data to suggest suitable plants and build sustainable communities using Perplexity Sonar API

**Greenify** is a mobile application designed to encourage sustainable practices by analyzing live images and building communities. Users capture photos of their space (balcony, roadside, basement, etc.) and Greenify automatically analyzes the image using Perplexity's Sonar API to suggest suitable plants for that location. The app also connects like-minded people in the locality to create communities for sustainable, economic, and social growth.

<iframe title="YouTube video player" />

## Features

* **AI-Powered Plant Analysis** using image recognition and location data to suggest suitable plants
* **Location-Based Recommendations** considering weather, sunlight, and environmental conditions
* **Community Building** connecting users with similar plant interests and sustainable goals
* **Cross-Platform Mobile App** built with Expo for iOS, Android, and web
* **Real-time Weather Integration** for accurate plant suitability assessment
* **Structured JSON Output** using Pydantic models for consistent data handling
* **AR Model Support** for enhanced plant visualization

## Abstract Data Flow Diagram

![Abstract Data Flow Diagram](https://d112y698adiu2z.cloudfront.net/photos/production/software_photos/003/418/290/datas/gallery.jpg)

## Prerequisites

* Node.js 20.19.4+ and npm
* Python 3.10.0+ and pip
* Expo CLI and SDK 51+
* Perplexity API key (Sonar Pro and Sonar Deep Research)
* Android SDK/Studio or Xcode (for local builds)
* Mobile device with camera for image capture

## Installation

```bash theme={null}
# Clone the repository
git clone https://github.com/deepjyotipaulhere/greenify.git
cd greenify

# Install frontend dependencies
npm install

# Install backend dependencies
cd service
pip install -r requirements.txt
```

## Configuration

Create `.env` file in the `service` directory:

```ini theme={null}
PERPLEXITY_API_KEY=your_perplexity_api_key_here
```

## Usage

1. **Start Backend Service**:
   ```bash theme={null}
   cd service
   python app.py
   ```

2. **Start Frontend App**:
   ```bash theme={null}
   npx expo start
   ```

3. **Access the App**:
   * Install Expo Go app and scan QR code, or
   * Open web browser on mobile and navigate to the URL shown

4. **Use the App**:
   * Grant camera and location permissions
   * Take a photo of your space (balcony, garden, etc.)
   * Receive AI-powered plant recommendations
   * Connect with nearby users for community building

![demo](https://raw.githubusercontent.com/deepjyotipaulhere/greenify/refs/heads/master/assets/images/ezgif-4647c5467e6dac.gif)

## Code Explanation

* **Frontend**: React Native with Expo for cross-platform mobile development
* **Backend**: Python Flask API handling image processing and Perplexity API integration
* **AI Integration**: Perplexity Sonar Pro for image analysis and Sonar Deep Research for plant recommendations
* **Data Models**: Pydantic models for structured JSON output and data validation
* **Image Processing**: Real-time image analysis with location-based context
* **Community Features**: User matching based on plant suggestions and sustainable interests
* **Weather Integration**: Real-time weather data for accurate plant suitability assessment

## Links

* [GitHub Repository](https://github.com/deepjyotipaulhere/greenify)
* [Live Demo](https://greenify.expo.app)


# Monday – Voice-First AI Learning Assistant
Source: https://docs.perplexity.ai/docs/cookbook/showcase/monday

An accessible, multimodal AI learning companion that delivers contextual reasoning, 3D visualizations, and curated educational content via natural voice interaction.

**Monday** is a voice-enabled AI learning companion designed to bridge the gap between natural language queries and high-quality educational content. Inspired by Marvel's JARVIS and FRIDAY, Monday delivers tailored responses in three modes—Basic, Reasoning, and Deep Research—while integrating immersive visualizations, curated video content, and accessibility-first design.

## Features

* **Three Learning Modes**: Basic factual answers, step-by-step reasoning, and deep research investigations
* **Voice-first interaction** for hands-free learning with natural language processing
* **Real-time 3D visualizations** of concepts using Three.js & WebXR
* **Curated educational YouTube video integration** from trusted sources
* **Multi-modal feedback** combining text, speech (via ElevenLabs), and spatial panels
* **VR-optional design** for immersive experiences without requiring a headset
* **Accessibility-focused interface** for mobility- and vision-impaired users

## Prerequisites

* Node.js 18 LTS or newer
* Modern web browser (Chrome, Edge, or Firefox recommended)
* Microphone for voice interaction
* Optional: VR headset for immersive mode (WebXR compatible)
* Perplexity API key, ElevenLabs API key, and YouTube API key

## Installation

```bash theme={null}
# Clone the repository
git clone https://github.com/srivastavanik/monday.git
cd monday
git checkout final
cd nidsmonday

# Install dependencies
npm install
```

```ini theme={null}
# Create a .env file and set your API keys
PERPLEXITY_API_KEY=your_api_key
ELEVENLABS_API_KEY=your_api_key
YOUTUBE_API_KEY=your_api_key
```

```bash theme={null}
# Start Backend Server
node backend-server.js

# Start frontend
npm run dev
```

## Usage

1. Launch the app in your browser
2. Say **"Hey Monday"** to activate the assistant
3. Ask a question in one of three modes:
   * **Basic Mode** – "What is photosynthesis?"
   * **Reasoning Mode** – "Think about how blockchain works."
   * **Deep Research Mode** – "Research into the history of quantum mechanics."
4. View answers as floating text panels, voice responses, and interactive 3D models

## Code Explanation

* **Frontend**: Typescript with Three.js for 3D visualizations and WebXR for VR support
* **Backend**: Node.js with Socket.IO for real-time voice command processing
* **AI Integration**: Perplexity Sonar API for intelligent responses with reasoning extraction
* **Voice Processing**: ElevenLabs for speech synthesis and natural language understanding
* **Content Curation**: YouTube API integration with smart keyword extraction for educational videos
* **Accessibility**: Voice-first design with spatial audio and haptic feedback support

## Demo Video

<iframe title="YouTube video player" />


# MVP LifeLine | AI Youth Empowerment Platform
Source: https://docs.perplexity.ai/docs/cookbook/showcase/mvp-lifeline-ai-app

A multilingual, offline-first AI platform that helps underserved youth Earn, Heal, and Grow using real-time AI and holistic tools

**MVP LifeLine** is a multilingual, offline-first AI platform empowering youth emotionally, financially, and professionally—anytime, anywhere. Over 1.3 billion youth globally face barriers to career opportunities and mental well-being, especially in underserved and remote regions. MVP LifeLine breaks these barriers by combining AI, offline access, multilingual support, and a holistic tool ecosystem.

## Features

* **Dual Mode AI** with Career Coach and Emotional Companion powered by Perplexity Sonar API
* **Multilingual Support** across 10+ languages including English, French, Arabic, Spanish, Hindi, and regional languages
* **Offline-First Design** with SMS/USSD integration for low-connectivity regions
* **Holistic Tool Ecosystem** covering career, wellness, finance, and productivity
* **SmartQ Access** for context-aware, emotionally intelligent AI responses
* **Digital Hustle Hub** with AI gig discovery and freelancing tools
* **Wellness Zone** with guided meditations and mental reset prompts
* **Finance Zone** with budget tracking and youth-friendly money tips
* **Productivity Zone** with AI Kanban board and habit tracking

## Prerequisites

* Flutter SDK and Dart
* Firebase project setup
* Twilio account for SMS/USSD integration
* Perplexity API key (Sonar)
* OpenAI API key (for augmentation)

## Installation

```bash theme={null}
# Clone the repository
git clone https://github.com/JohnUmoh/asgard.git
cd asgard

# Install Flutter dependencies
flutter pub get

# Configure Firebase
flutterfire configure

# Set up environment variables
cp .env.example .env
```

## Configuration

Create `.env` file:

```ini theme={null}
PERPLEXITY_API_KEY=your_sonar_api_key
OPENAI_API_KEY=your_openai_api_key
FIREBASE_PROJECT_ID=your_firebase_project_id
TWILIO_ACCOUNT_SID=your_twilio_sid
TWILIO_AUTH_TOKEN=your_twilio_token
```

## Usage

1. **Setup Firebase**:
   ```bash theme={null}
   flutterfire configure
   ```

2. **Run the Application**:
   ```bash theme={null}
   flutter run
   ```

3. **Access Features**:
   * Switch between Career Coach and Emotional Companion modes
   * Use SmartQ for AI-powered assistance in multiple languages
   * Access offline features via SMS/USSD when connectivity is limited
   * Explore career tools, wellness features, and productivity boosters

## Code Explanation

* **Frontend**: Flutter cross-platform application with responsive design for mobile and web
* **Backend**: Firebase for authentication, data storage, and real-time synchronization
* **AI Integration**: Perplexity Sonar API for dual-mode AI interactions (Career Coach & Emotional Companion)
* **Offline Support**: Twilio integration for SMS/USSD communication in low-connectivity areas
* **Multilingual**: Sonar API handling 10+ languages with context-aware responses
* **Data Sync**: Offline data capture with automatic re-sync when connectivity returns
* **Personalization**: AI adapts to user's language, literacy level, mood history, and preferences

## Links

* [GitHub Repository](https://github.com/JohnUmoh/asgard)
* [Live Demo](https://mvplifelineaiapp.netlify.app)


# PerplexiCart | AI-Powered Value-Aligned Shopping Assistant
Source: https://docs.perplexity.ai/docs/cookbook/showcase/perplexicart

An AI shopping assistant that uses Perplexity Sonar to deliver structured research, value-aligned recommendations, and transparent citations across the web

**PerplexiCart** helps users make informed, value-aligned purchasing decisions. Powered by the **Perplexity Sonar API**, it analyzes products across the web and returns structured insights with prioritized recommendations, pros/cons, trade‑off analysis, and user sentiment — tailored to preferences like Eco‑Friendly, Durability, Ethical, and region‑specific needs.

<iframe title="YouTube video player" />

## Features

* **Intelligent Product Recommendations** beyond simple spec comparison
* **Priority-Based Value Alignment** (Best Value, Eco‑Friendly, Ethical, Durability, Made in India)
* **Contextual Personalization** (skin type, usage patterns, region, etc.)
* **Structured Research Output** with:
  * Research summary and top recommendations
  * Value alignment with reasoning
  * Pros/Cons and key specifications
  * User sentiment and community insights (Reddit, Quora)
  * Trade‑off analysis and buying tips
* **Transparent Sources** with citations for verification

## Prerequisites

* Node.js 18+ and npm/yarn
* Python 3.10+ and pip
* Perplexity API key

## Installation

```bash theme={null}
# Clone the repository
git clone https://github.com/fizakhan90/perplexicart.git
cd perplexicart

# Backend (FastAPI) setup
cd backend
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -r requirements.txt

# Frontend (Next.js) setup
cd ../frontend
npm install
```

## Configuration

Create a `.env` file in the backend directory:

```ini theme={null}
PERPLEXITY_API_KEY=your_perplexity_api_key
```

(Optional) Add any app‑specific settings as needed (cache, region defaults, etc.).

## Usage

1. **Start Backend (FastAPI)**:
   ```bash theme={null}
   cd backend
   uvicorn main:app --reload  # adapt module:app if your entrypoint differs
   ```

2. **Start Frontend (Next.js)**:
   ```bash theme={null}
   cd frontend
   npm run dev
   ```

3. **Open the App**: Visit `http://localhost:3000` and search for a product. Select your priority (e.g., Eco‑Friendly) and add optional context (skin type, region).

## Code Explanation

* **Backend (FastAPI)**: Orchestrates Sonar calls with dynamic prompt engineering based on query, selected priority, and context
* **Structured Outputs**: Enforces a strict JSON schema via `response_format` to ensure consistent UI rendering
* **Live Web Research**: Directs Sonar to search e‑commerce platforms, forums, review blogs, and sustainability reports
* **Semantic Analysis**: Extracts value alignment, pros/cons, sentiment, and cites sources for transparency
* **Frontend (Next.js/React)**: Presents a clear, user‑friendly view of recommendations, trade‑offs, and citations

## How the Sonar API Is Used

PerplexiCart leverages the **Perplexity Sonar API** as its intelligence core, dynamically generating customized prompts based on user inputs like search queries, priorities and context. The API performs comprehensive web research across e-commerce sites, forums, and review platforms, with responses structured in a consistent JSON format. Through semantic analysis, it extracts key product insights including alignment with user priorities, pros/cons, and sentiment - all backed by cited sources. The FastAPI backend processes these structured responses before serving them to the Next.js frontend for a polished user experience.

## Links

* **Live Demo**: [https://perplexicart.vercel.app/](https://perplexicart.vercel.app/)
* **GitHub Repository**: [https://github.com/fizakhan90/perplexicart](https://github.com/fizakhan90/perplexicart)


# PerplexiGrid | Interactive Analytics Dashboards
Source: https://docs.perplexity.ai/docs/cookbook/showcase/perplexigrid

Instantly generate analytics dashboards from natural language using live data via Perplexity Sonar API.

**PerplexiGrid** turns natural language into rich, interactive dashboards. Connect your data and mix it with live web data, ask a question, and let the Sonar API do the rest! Complete with drag-and-drop layout, AI widget generation, and ECharts-powered visualizations.

## Features

* **Natural Language to Dashboards**: Convert plain English prompts into fully functional analytics dashboards with 25+ widget types
* **Live Data Integration**: Blend your own data sources with real-time web data for comprehensive insights
* **Interactive Grid Layout**: Drag-and-drop interface for customizing dashboard layouts and styling
* **AI-Powered Refinement**: Refine or add widgets using conversational updates
* **Export & Share**: Generate PDF exports, high-res images, and shareable dashboard links

## How it uses Sonar

PerplexiGrid leverages the Sonar API through four specialized modes:

* **Full Dashboard Generation (f1)**: Creates comprehensive dashboards with multiple widgets using Sonar Pro's advanced capabilities
* **Lightweight Mode (l1)**: Generates quick visualizations for embedded systems and real-time applications
* **Dashboard Updates (r1)**: Enables dynamic modifications through natural language while maintaining context
* **Widget Refinement (r2)**: Provides precise control over individual widget updates

The system uses structured JSON schema responses to ensure consistent, ECharts-compatible output that can be directly rendered as interactive visualizations.

## Usage

1. Open the app and start a new dashboard
2. Prompt it like: *"Show me market trends in AI startups in 2024"*  (Sonar generates chart configs, which are parsed and rendered as live widgets)

![Prompt #1](https://www.perplexigrid.com/guide/prompt_dark.gif)

3. Rearrange and style the widgets with the grid interface

![Prompt #2](https://www.perplexigrid.com/guide/move_dark.gif)
![Prompt #3](https://www.perplexigrid.com/guide/customize_dark.gif)

5. Add your own datasources to blend your data with live web data

![Prompt #4](https://www.perplexigrid.com/guide/datasource_dark.gif)

6. Refine them via text prompts or export the dashboard as needed
7. Collaborate and share easily

![Prompt #5](https://www.perplexigrid.com/guide/invite_dark.gif)

## Code Explanation

The user sends messages that are turned into prompts to a Supabase Edge Function that wraps the Perplexity Sonar API.\
Depending on the mode (`f1`, `l1`, `r1`, or `r2`), the function generates full structured outputs for dashboards, lightweight visualizations, or targeted updates.\
The generated layout is parsed into structured widget definitions and passed through our widget creation engine.

Explore our [main sonar-api service here.](https://github.com/PetarRan/perplexigrid/blob/main/server/supabase/functions/_shared/perplexityService.ts)

## Prompt Modes

| Mode | Description                          | Use Case                                                               | Notes                                                                     |
| ---- | ------------------------------------ | ---------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| `f1` | First-time full dashboard generation | User starts with an empty canvas and enters an initial prompt          | Produces a complete dashboard layout with multiple widgets                |
| `l1` | Lightweight dashboard generation     | Used for quick insights or previews with minimal tokens                | Faster and cheaper, but returns fewer widgets with less instruction depth |
| `r1` | Full dashboard regeneration          | User wants to replace all existing widgets with a new prompt           | Rebuilds the entire dashboard while keeping layout intact                 |
| `r2` | Targeted widget update               | User wants to change a specific widget (e.g., "make this a pie chart") | Only the selected widget is modified based on the new instruction         |

## Tech Stack

* **Frontend**: React + Vite (Typescript), ECharts, react-grid-layout
* **Backend**: Supabase Edge Functions (Typescript on Deno)
* **AI Engine**: Perplexity Sonar Pro
* **Infrastructure**: Supabase (PostgreSQL, RLS, Auth), Vercel deployment

## Links

* [GitHub Repository](https://github.com/PetarRan/perplexigrid)
* [Live Demo](https://app.perplexigrid.com)
* [Website](https://www.perplexigrid.com)


# Perplexity Client | Desktop AI Chat Interface with API Controls
Source: https://docs.perplexity.ai/docs/cookbook/showcase/perplexity-client

An Electron-based desktop client for Perplexity API with advanced features like model selection, custom system prompts, and API debugging mode

**Perplexity Client** is an Electron-based desktop application that provides a polished interface for interacting with Perplexity's Sonar API. It exposes advanced API parameters like max tokens, making it ideal for developers who want fine-grained control over their AI interactions while enjoying a beautiful, macOS-inspired UI.

<img alt="Perplexity Client Interface" />

## Features

* **Multiple Sonar Models** with support for Sonar, Sonar Pro, and Sonar Reasoning Pro
* **Custom Spaces** with save/load functionality for different use cases
* **API Parameter Controls** including max tokens adjustments
* **API Debugging Mode** showing full request/response payloads for troubleshooting
* **Token Usage Tracking** to monitor API consumption and costs
* **Focus Modes** for specialized tasks like coding, writing, and research

## Prerequisites

* Node.js v16 or higher
* npm or yarn
* Perplexity API key

## Installation

```bash theme={null}
# Clone the repository
git clone https://github.com/straight-heart/Perplexity-client-.git
cd Perplexity-client-

# Install dependencies
npm install

npm run dev
```

## Build

Build the application for your platform:

```bash theme={null}
npm run build:win    # Windows
npm run build:mac    # macOS
npm run build:linux  # Linux
```

## Configuration

API keys are managed directly within the application:

1. Launch the app and open Settings (gear icon)
2. In the **API Keys** section, click **Add Key**
3. Enter your Perplexity API key
4. The key is stored securely and persists across sessions

For custom system prompts, use the **Spaces** feature to save and switch between different instruction sets.

## Usage

1. **Launch**: Run `npm run dev` or use the built application
2. **Add API Key**: Open Settings and add your Perplexity API key
3. **Select Model**: Use the dropdown to choose between Sonar variants
4. **Create Spaces**: Set up custom system prompts for different tasks
5. **Chat**: Start conversing with real-time streaming responses
6. **Debug**: Enable API debugging to see full request/response details
7. **Track Usage**: Monitor token consumption in the Settings panel

## Screenshots

| Feature                      | Preview                  |
| ---------------------------- | ------------------------ |
| Spaces (Custom Instructions) | <img alt="Spaces" />     |
| Model & Parameter Controls   | <img alt="Parameters" /> |
| API Debugging Mode           | <img alt="Debug" />      |
| Theme Selection              | <img alt="Themes" />     |

## Limitations

* Desktop only (Windows, macOS, Linux) — no mobile or web version
* Requires internet connection for API calls
* API key required for functionality

## Links

* [GitHub Repository](https://github.com/straight-heart/Perplexity-client-)


# Perplexity Dart & Flutter SDKs
Source: https://docs.perplexity.ai/docs/cookbook/showcase/perplexity-flutter

Lightweight, type-safe SDKs for seamless Perplexity API integration in Dart and Flutter applications

# Perplexity Dart & Flutter SDKs

**Perplexity Dart & Flutter SDKs** provide a comprehensive toolkit for integrating Perplexity's AI capabilities into Dart and Flutter applications. Built specifically for the Flutter community, these packages include a lightweight core API client and ready-to-use Flutter widgets with BLoC state management.

## Features

* Type-safe API client with fully typed models and compile-time safety
* Streaming and non-streaming chat completions with real-time response handling
* Support for all Perplexity models (Sonar, Sonar Pro, Deep Research, Reasoning variants)
* Multi-image processing with base64, data URI, and HTTPS URL support
* Ready-to-use Flutter widgets with BLoC state management integration
* Advanced configuration options (search filters, domain restrictions)
* Cross-platform support for iOS, Android, Web, and Desktop
* Future-proof design with custom model string support for new Perplexity releases

## Prerequisites

* Dart SDK 2.17.0 or newer
* Flutter SDK 3.0.0 or newer (for Flutter-specific features)
* Perplexity API key from Perplexity API Console
* Basic knowledge of Flutter BLoC pattern for widget integration

## Installation

### For Dart Projects (Core API Only)

```bash theme={null}
dart pub add perplexity_dart
```

### For Flutter Projects (Full Widget Support)

```bash theme={null}
flutter pub add perplexity_flutter
```

### Environment Variables

```dart theme={null}
// Add to your app's configuration
const String perplexityApiKey = 'your_perplexity_api_key_here';
```

## Usage

### Core API Integration

* Type-safe client with all Perplexity models (Sonar, Sonar Pro, Deep Research, Reasoning)
* Streaming and non-streaming chat completions
* Multimodal processing with flexible MessagePart system for text + images

### Flutter Widget Layer

* `ChatWrapperWidget` for BLoC state management
* `PerplexityChatView` for real-time message display
* `PerplexityChatInput` for user interaction handling

## Code Explanation

* Core Layer: Pure Dart API client (`perplexity_dart`) for cross-platform Perplexity API integration
* UI Layer: Flutter widgets (`perplexity_flutter`) with BLoC state management for rapid development
* Type Safety: Fully typed models and responses prevent runtime errors and provide IntelliSense
* Multimodal: Flexible MessagePart system for combining text and images in single requests
* Streaming: Built-in support for real-time chat completions with proper chunk handling
* Architecture: Two-layer design allows lightweight API usage or full Flutter widget integration

## Architecture

### Two-Layer Design

* **Core (`perplexity_dart`)** - Pure Dart API client for all platforms
* **UI (`perplexity_flutter`)** - Flutter widgets + BLoC state management

Uses flexible MessagePart system for multimodal content combining text and images.

## Links

### Packages

* [perplexity\_dart on pub.dev](https://pub.dev/packages/perplexity_dart) | [GitHub](https://github.com/vishnu32510/perplexity_dart)
* [perplexity\_flutter on pub.dev](https://pub.dev/packages/perplexity_flutter) | [GitHub](https://github.com/vishnu32510/perplexity_flutter)

### Examples

* [Flutter Example App](https://github.com/vishnu32510/perplexity_dart/tree/main/example_flutter_app)
* [Dart Examples](https://github.com/vishnu32510/perplexity_dart/tree/main/example)


# Perplexity Lens | AI-Powered Knowledge Graph Browser Extension
Source: https://docs.perplexity.ai/docs/cookbook/showcase/perplexity-lens

A browser extension that builds personalized knowledge graphs using Perplexity AI for smart text selection, webpage summarization, and contextual insights

**Perplexity Lens** is a powerful browser extension that transforms your browsing experience by providing AI-powered insights using Perplexity AI and creating a personalized knowledge graph that visually connects the concepts you encounter online.

<iframe title="YouTube video player" />

## Features

* **Smart Text Selection** with AI-generated explanations for selected text
* **Webpage Summarization** for instant, concise overviews of entire pages
* **Contextual RAG Insights** using Retrieval-Augmented Generation for detailed context and meanings
* **Knowledge Graph Visualization** with interactive D3.js graphs showing concept connections
* **Public Sharing** with URL generation for sharing graphs with others
* **User Authentication** via Firebase for secure access
* **Dual Storage** with local IndexedDB and cloud Firebase storage
* **Responsive UI** fully functional across all devices

## Prerequisites

* Node.js v14+ and npm v6+
* Google Chrome or compatible browser
* Firebase account for cloud functionality
* Firebase CLI (`npm install -g firebase-tools`)
* Perplexity API key and OpenAI API key

## Installation

```bash theme={null}
# Clone the repository
git clone https://github.com/iamaayushijain/perplexity-lens.git
cd perplexity_lens

# Install dependencies
npm install

# Build the extension
npm run build
```

## Configuration

Edit `src/config.ts`:

```typescript theme={null}
export const PERPLEXITY_API_KEY = 'your-perplexity-key';
export const EMBEDDING_API_KEY = 'your-openai-key';
export const FIREBASE_HOSTING_URL = 'https://your-project-id.web.app';
```

## Usage

1. **Load Extension**: Go to `chrome://extensions/`, enable Developer mode, click "Load unpacked" and select the `dist/` directory

2. **Sign In**: Click the extension icon and authenticate via Firebase

3. **Use Features**:
   * **Highlight Text**: Select text on any webpage for AI-powered insights
   * **Summarize Page**: Use the "Summarize" feature for webpage overviews
   * **Ask Anything**: Hover or click on words/phrases for definitions or explanations
   * **View Graph**: Navigate to the Graph tab to see your knowledge graph
   * **Explore**: Zoom, drag, and hover over nodes in the interactive graph
   * **Share**: Click "Share Graph" to generate a public link

## Code Explanation

* **Frontend**: React with Typescript and TailwindCSS for modern, responsive UI
* **Browser Extension**: Chrome extension architecture with popup and content scripts
* **AI Integration**: Perplexity AI for intelligent text explanations and summarization
* **Knowledge Graph**: D3.js for interactive graph visualization and concept connections
* **Storage**: Dual storage system with local IndexedDB and cloud Firebase
* **Authentication**: Firebase Auth for secure user access and data management
* **RAG System**: Retrieval-Augmented Generation for contextual insights and definitions

## Links

* [GitHub Repository](https://github.com/iamaayushijain/perplexity-lens)
* [Blog Post](https://ashjin.hashnode.dev/perplexity-lens-supercharge-your-web-experience-with-personalized-knowledge-graphs)


# PosterLens | Scientific Poster Scanner & Research Assistant
Source: https://docs.perplexity.ai/docs/cookbook/showcase/posterlens

An iOS app that transforms static scientific posters into interactive insights using OCR and Perplexity's Sonar Pro API for semantic search and context

**PosterLens** is an iOS app that transforms static scientific posters into interactive, explorable insights using OCR and AI. Created for the Perplexity Hackathon 2025, it allows researchers, MSLs, and medical writers to scan posters and explore them interactively using natural language, extracting meaning and surfacing related studies instantly.

![PosterLens Screenshot](https://cdn.prod.website-files.com/66d49e8555a289120a81ec3e/68930ad938e072c05d1be0b9_PosterLens.png)

## Features

* **Scientific Poster Scanning** using device camera and Apple Vision OCR
* **Natural Language Q\&A** about poster content with AI-powered responses
* **Semantic Search Integration** using Perplexity Sonar Pro for related studies
* **Citation Validation** with PubMed E-utilities for academic accuracy
* **Auto-Generated Research Questions** and future research directions
* **On-Device Processing** for privacy and performance
* **Interactive Research Experience** transforming static content into dynamic insights

## Prerequisites

* iOS 17+ device with camera
* Xcode 15+ for development
* Apple Developer account for App Store distribution
* Perplexity API key (Sonar Pro)
* OpenAI API key (GPT-3.5)
* PubMed E-utilities access

## Installation

```bash theme={null}
# Clone the repository
git clone https://github.com/nickjlamb/PosterLens.git
cd PosterLens

# Open in Xcode
open PosterLens.xcodeproj
```

## Configuration

Add your API keys to the project configuration:

```swift theme={null}
// API Configuration
PERPLEXITY_API_KEY=your_sonar_pro_api_key
OPENAI_API_KEY=your_gpt_api_key
PUBMED_API_KEY=your_pubmed_api_key
```

## Usage

1. **Install from App Store**: Download PosterLens from the iOS App Store
2. **Scan Poster**: Point your camera at a scientific poster
3. **OCR Processing**: Apple Vision automatically extracts text content
4. **Ask Questions**: Use natural language to query the poster content
5. **Explore Related Research**: Discover semantically related studies via Sonar Pro
6. **Validate Citations**: Check academic references with PubMed integration

## Code Explanation

* **Frontend**: Native iOS app built with SwiftUI for modern UI/UX
* **OCR Processing**: Apple Vision framework for text extraction from images
* **AI Integration**: Perplexity Sonar Pro API for semantic search and context understanding
* **Natural Language**: GPT-3.5 for Q\&A and content interpretation
* **Academic Validation**: PubMed E-utilities for citation verification
* **On-Device Processing**: Local OCR and processing for privacy and performance
* **Research Enhancement**: Auto-generation of research questions and future directions

## Links

* [GitHub Repository](https://github.com/nickjlamb/PosterLens)
* [App Store](https://apps.apple.com/us/app/posterlens-research-scanner/id6745453368)


# Sonar Chromium Browser | Native Search Omnibox and Context Menu
Source: https://docs.perplexity.ai/docs/cookbook/showcase/sonar-chromium-browser

Chromium browser patch with native Perplexity Sonar API integration providing omnibox answers and context-menu summarization

**Sonar Chromium Browser** is a Chromium browser patch that natively integrates Perplexity's Sonar API to provide AI-powered functionality directly in the browser. Users can type `sonar <query>` in the omnibox for instant AI answers or select text and right-click "Summarize with Sonar" for quick summaries, streamlining research and browsing workflows.

## Features

* **Omnibox AI Answers** with `sonar <query>` syntax for instant responses
* **Context-menu Summarization** for selected text with one-click access
* **Native Browser Integration** using Chromium's omnibox and context-menu APIs
* **Dual Model Support** using Sonar Pro for omnibox and Sonar for summaries
* **Debounced Input Handling** for efficient API usage
* **Custom Browser Build** demonstrating AI integration patterns

## Prerequisites

* Ubuntu 22.04 (WSL2 recommended)
* Chromium source code checkout
* Perplexity API key
* 16GB+ RAM for Chromium build
* Git and standard build tools

## Installation

```bash theme={null}
# Clone the repository
git clone https://github.com/KoushikBaagh/perplexity-hackathon-chromium.git
cd perplexity-hackathon-chromium

# Apply patches to Chromium source
# Follow the README for detailed Chromium setup instructions
```

## Configuration

Update API keys in the modified files:

```cpp theme={null}
// In sonar_autocomplete_provider.cc and render_view_context_menu.cc
const std::string API_KEY = "your_perplexity_api_key_here";
```

## Usage

1. **Build Chromium** with applied patches following the repository instructions
2. **Launch the custom browser** with AI integration
3. **Use Omnibox AI**: Type `sonar what is quantum tunneling?` in address bar
4. **Use Context Summarization**: Select text, right-click "Summarize with Sonar"

## Code Explanation

* **Omnibox Integration**: Custom autocomplete provider hooking into Chromium's omnibox API
* **Context Menu**: Modified render view context menu for text summarization
* **API Integration**: Direct Perplexity Sonar API calls with debounced input handling
* **Model Selection**: Sonar Pro for omnibox queries, Sonar for text summarization
* **Browser Architecture**: Demonstrates Chromium extension points for AI features
* **Build Process**: Custom Chromium build with AI patches applied

## Demo Video

<iframe title="YouTube video player" />

## Links

* [GitHub Repository](https://github.com/KoushikBaagh/perplexity-hackathon-chromium)
* [Chromium Gerrit Repository](https://chromium-review.googlesource.com/c/chromium/src/+/6778540)


# StarPlex | AI-Powered Startup Intelligence Platform
Source: https://docs.perplexity.ai/docs/cookbook/showcase/starplex

An AI-powered startup intelligence platform that helps entrepreneurs validate their business ideas and find the right resources to succeed

**StarPlex** is an AI-powered startup intelligence platform that helps entrepreneurs validate their business ideas and connect with the resources they need to succeed. Powered primarily by **Perplexity Sonar Pro**, it features an interactive **3D globe interface** as its main UI. Simply enter your startup idea, and watch as the AI engine analyzes and visualizes insights directly on the globe—mapping out competitors, markets, demographics, VCs, and potential co-founders across the world in real-time.

<iframe title="StarPlex Demo" />

## Features

* **Market Validation Analysis** with AI-proof scoring, market cap estimation, and growth trend analysis
* **Interactive 3D Globe Interface** for visualizing global startup intelligence data
* **Competitor Research** with threat scoring and competitive landscape mapping
* **VC & Investor Matching** based on investment thesis and portfolio alignment
* **Co-founder Discovery** with compatibility scoring and expertise matching
* **Demographic Research** with heatmap visualization of target audience locations
* **AI Pitch Deck Generation** creating investor-ready presentations
* **Context-Aware Chatbot** with RAG integration across all research data

## Prerequisites

* Node.js 18+ and npm
* Python 3.8+ and pip
* Perplexity API key (Sonar Pro)
* Mapbox token and SERP API key

## Installation

```bash theme={null}
# Clone the repository
git clone https://github.com/JerryWu0430/StarPlex.git
cd StarPlex

# Backend setup
cd backend
pip install -r requirements.txt

# Frontend setup
cd ../frontend
npm install
```

## Configuration

Create `.env` file in the backend directory:

```ini theme={null}
PERPLEXITY_API_KEY=your_perplexity_api_key
MAPBOX_TOKEN=your_mapbox_token
SERPAPI_KEY=your_serpapi_key
```

## Usage

1. **Start Backend**:
   ```bash theme={null}
   cd backend
   python main.py
   ```

2. **Start Frontend**:
   ```bash theme={null}
   cd frontend
   npm run dev
   ```

3. **Access Application**: Open [http://localhost:3000](http://localhost:3000) and enter your startup idea

4. **Explore Intelligence**: Use the 3D globe to visualize competitors, VCs, demographics, and co-founders

5. **Generate Assets**: Create pitch decks and chat with the AI assistant about your analysis

## How StarPlex Uses Perplexity Sonar API

StarPlex leverages Perplexity's Sonar API through a **multi-module intelligence architecture**:

**Market Analysis Engine**
Uses Sonar Pro for comprehensive market validation, combining Google Trends data with AI analysis to generate market cap estimates, AI-disruption scores, and growth projections with structured JSON outputs.

**Competitor Intelligence**
Employs multiple concurrent Sonar queries to identify competing companies, funding status, and threat levels. Each competitor receives a 1-10 threat score with detailed competitive positioning analysis.

**VC & Co-founder Matching**
Leverages Sonar's real-time web knowledge to find relevant investors and potential co-founders, scoring matches based on investment thesis alignment, expertise fit, and geographic proximity.

**Context-Aware Business Assistant**
Implements RAG (Retrieval-Augmented Generation) by feeding all research data into Sonar conversations, creating a knowledgeable startup advisor that can answer questions about market positioning, competitive threats, and strategic decisions.

**Geographic Intelligence**
Combines Sonar's demographic insights with Mapbox geocoding to create interactive heatmaps showing where target audiences are concentrated globally.

## Code Explanation

* **Backend**: Python FastAPI with AsyncIO for concurrent Perplexity API calls across multiple analysis modules
* **Frontend**: Next.js with React 19, featuring Cobe for 3D globe visualization and Mapbox GL for interactive mapping
* **AI Integration**: Multi-model Perplexity strategy using Sonar Pro for complex analysis and Sonar for faster queries
* **Data Pipeline**: Intelligent caching, structured JSON responses, and real-time streaming for immediate user feedback
* **Visualization**: Dynamic data binding between Perplexity insights and interactive globe/map interfaces

## Links

* [GitHub Repository](https://github.com/JerryWu0430/StarPlex)
* [Live Demo](https://starplex.app)
* [Devpost Submission](https://devpost.com/software/starplex)


# TruthTracer | AI-Powered Misinformation Detection Platform
Source: https://docs.perplexity.ai/docs/cookbook/showcase/truth-tracer

A comprehensive misinformation detection platform that uses Perplexity's Sonar API to analyze claims, trace trust chains, and provide Socratic reasoning for fact verification

**TruthTracer** is a comprehensive misinformation detection platform that leverages Perplexity's Sonar API to provide multi-layered claim analysis. The platform combines fact-checking, trust chain tracing, and Socratic reasoning to deliver accurate, evidence-based verification results with confidence scores and detailed sourcing.

### Demo

<iframe title="YouTube video player" />

## Features

* **Multi-method Analysis** combining fact-checking, trust chain analysis, and Socratic reasoning
* **AI-Powered Verification** using Perplexity's Sonar, Sonar Deep Research, and Sonar Reasoning Pro models
* **Real-time Processing** with parallel execution of multiple analysis methods
* **Evidence-based Results** providing sources, confidence scores, and detailed reasoning
* **Clean Architecture** with NestJS backend and React frontend
* **Production-Ready** with Docker deployment, comprehensive testing, and API documentation
* **Configurable Confidence Scoring** with customizable weights and thresholds

## Prerequisites

* Node.js 18+ and npm
* Perplexity API key (Sonar models access)
* Docker (optional for deployment)
* Git for repository cloning

## Installation

```bash theme={null}
# Clone the backend repository
git clone https://github.com/anthony-okoye/truth-tracer-backend.git
cd truth-tracer-backend

# Install dependencies
npm install

# Clone the frontend repository
git clone https://github.com/anthony-okoye/truth-tracer-front.git
cd truth-tracer-front

# Install frontend dependencies
npm install
```

## Configuration

Create `.env` file in the backend directory:

```ini theme={null}
# Required
SONAR_API_KEY=your_perplexity_api_key
SONAR_API_URL=https://api.perplexity.ai

# Optional configuration
SONAR_TIMEOUT=30000
SONAR_MAX_RETRIES=3
CONFIDENCE_WEIGHT_FACT_CHECK=0.35
CONFIDENCE_WEIGHT_TRUST_CHAIN=0.25
CONFIDENCE_WEIGHT_SOCRATIC=0.20
```

## Usage

1. **Start Backend**:

```bash theme={null}
   cd truth-tracer-backend
   npm run start:dev
```

2. **Start Frontend**:

```bash theme={null}
   cd truth-tracer-front
   npm start
```

3. **Access Application**: Open [http://localhost:3000](http://localhost:3000) in your browser

4. **Analyze Claims**:
   * Enter a claim in the text area
   * Click "Analyze Claim" to run fact-checking, trust chain analysis, and Socratic reasoning
   * View results with confidence scores, sources, and detailed explanations

## Code Explanation

* **Backend**: NestJS application with clean architecture following Typescript best practices
* **AI Integration**: Perplexity Sonar API with three specialized models - Sonar for fact-checking, Sonar Deep Research for trust chain analysis, and Sonar Reasoning Pro for logical evaluation
* **Parallel Processing**: Simultaneous execution of all three analysis methods for efficient claim verification
* **Response Sanitization**: Custom JSON parsing and validation to handle various API response formats
* **Confidence Scoring**: Weighted scoring system combining results from all three analysis methods
* **Frontend**: React application with intuitive claim submission interface and detailed results visualization
* **Testing**: Comprehensive test suite including unit tests, end-to-end tests, and claim analysis testing

## How the Sonar API Is Used

TruthTracer leverages Perplexity's Sonar API through three distinct analysis approaches:

```typescript theme={null}
// Parallel execution of multiple Sonar models
const [factCheckResult, trustChainResult, socraticResult] = await Promise.all([
  sonarClient.chat.completions.create({
    model: "sonar",
    messages: [{ role: "user", content: factCheckPrompt }],
    max_tokens: 500
  }),
  sonarClient.chat.completions.create({
    model: "sonar-deep-research", 
    messages: [{ role: "user", content: trustChainPrompt }],
    max_tokens: 2500
  }),
  sonarClient.chat.completions.create({
    model: "sonar-reasoning-pro",
    messages: [{ role: "user", content: socraticPrompt }],
    max_tokens: 4000
  })
]);
```

## Links

* [Live Demo](https://truthtracer.netlify.app/)
* [Backend Repository](https://github.com/anthony-okoye/truth-tracer-backend)
* [Frontend Repository](https://github.com/anthony-okoye/truth-tracer-front)


# UnCovered | Real-Time Fact-Checking Chrome Extension
Source: https://docs.perplexity.ai/docs/cookbook/showcase/uncovered

A Chrome extension that brings real-time fact-checking to anything you see online in just 2 clicks, powered by Perplexity's Sonar API for instant verification

**UnCovered** is a Chrome extension that verifies text, images, websites, and screenshots in real-time—right where you browse. Built on Perplexity's Sonar API, it provides instant truth with citations, verdicts, and deep analysis using just a right-click, without breaking your browsing flow.

## Features

* **3-Click Verification**: Select → Right-click → Verify (Text, Image, Link, or Screenshot)
* **Text Analysis Modes**: Quick Search, Fact-Check, and Deep Research capabilities
* **Image Fact-Checking**: Reverse image analysis and multimodal claim verification
* **Screenshot & Video Frame Capture**: Analyze visuals like infographics, memes, or chart snapshots
* **Citation-Backed Results**: All answers include sources and fact-verdicts (True/False/Unconfirmed)
* **Instant Rebuttal Generator**: Create concise, fact-based replies to misinformation
* **Zero-Friction UX**: Stay on the same page — no copy-paste, no new tabs required

## Prerequisites

* Chrome browser
* Node.js 16+ and npm
* MongoDB database
* Cloudinary account for image storage
* Perplexity API key (Sonar Pro and Deep Research access)
* Google OAuth credentials

## Installation

```bash theme={null}
# Clone the repository
git clone https://github.com/aayushsingh7/UnCovered.git
cd UnCovered

# Install dependencies
npm install

# Build the Chrome extension
npm run build
```

## Configuration

Set up your environment variables:

```ini theme={null}
PERPLEXITY_API_KEY=your_sonar_api_key
MONGODB_URI=your_mongodb_connection_string
CLOUDINARY_URL=your_cloudinary_credentials
GOOGLE_OAUTH_CLIENT_ID=your_google_oauth_id
```

## Usage

1. **Text/Link Verification**:
   * Select text or right-click a link
   * Choose Quick Search / Fact-Check / Deep Research
   * Get trusted results with verdicts and citations

2. **Image Verification**:
   * Right-click any image
   * Choose from Quick Search or Fact-Check
   * Detect misinformation and visual manipulation

3. **Screenshot/Infographic Analysis**:
   * Click UnCovered icon in the toolbar
   * Use "Capture Screen" to analyze visual content

4. **Get Instant Rebuttal**:
   * Auto-generate fact-based responses to correct misinformation

## Code Explanation

* **Frontend**: Vanilla JavaScript Chrome extension with context menu integration
* **Backend**: Node.js Express server handling API requests and user authentication
* **AI Integration**: Perplexity Sonar Pro and Deep Research APIs for intelligent fact-checking
* **Image Processing**: Cloudinary integration for screenshot and image analysis
* **Database**: MongoDB for user data and verification history
* **Authentication**: Google OAuth for secure user management
* **Multimodal Analysis**: Support for text, images, screenshots, and video frames

## Technical Implementation

UnCovered leverages Perplexity Sonar API in three core modes:

```javascript theme={null}
// Quick Search and Fact-Check with Sonar Pro
const quickResponse = await perplexityClient.chat.completions.create({
  model: "sonar-pro",
  messages: [{ role: "user", content: factCheckPrompt }]
});

// Deep Research for comprehensive analysis
const deepResponse = await perplexityClient.chat.completions.create({
  model: "sonar-deep-research", 
  messages: [{ role: "user", content: deepAnalysisPrompt }]
});
```

## Demo Video

<iframe title="UnCovered Demo" />

## Links

* [GitHub Repository](https://github.com/aayushsingh7/UnCovered)
* [Live Demo](https://uncovered.vercel.app)


# Valetudo AI | Trusted Medical Answer Assistant
Source: https://docs.perplexity.ai/docs/cookbook/showcase/valetudo-ai

Sonar-powered medical assistant for fast, science-backed answers.

# Valetudo AI

**Valetudo AI** is a science-backed medical assistant powered by the Perplexity Sonar API. It provides fast, clear, and well-cited answers to health questions — helping users cut through misinformation with filters, image analysis, and ready-made prompt templates.

Designed for conscious users — like parents, patients, and medical students — seeking reliable information.

## Features

* **Cited Answers** — sourced from a curated list of 10 trusted medical domains
* **Smart Filters** — by date and country for localized, up-to-date insights
* **Image Upload** — analyze photos of medication, conditions, or packaging
* **Prompt Templates** — 7 categories for symptom checks, drug safety, research, and more
* **Simple UI** — built with React and Tailwind CSS

## How It Uses the Sonar API

Valetudo AI integrates with [Perplexity Sonar Pro](https://docs.perplexity.ai), leveraging advanced features for domain-specific search and rich responses:

| Feature          | API Field                         | Purpose                                           |
| ---------------- | --------------------------------- | ------------------------------------------------- |
| Context Control  | `search_context_size: medium`     | Balances speed and depth for focused medical Q\&A |
| Trusted Domains  | `search_domain_filter`            | Restricts results to vetted health sources        |
| Visual Input     | `image_url`                       | Enables image-based medical queries               |
| Freshness Filter | `search_after/before_date_filter` | Helps surface recent and relevant findings        |
| Local Relevance  | `user_location`                   | Tailors answers based on user’s region            |

## Links

* [GitHub Repository](https://github.com/vero-code/valetudo-ai)
* [Devpost Submission](https://devpost.com/software/valetudo-ai)
* [View All Screenshots](https://github.com/vero-code/valetudo-ai/tree/master/screenshots)

## Demo Video

See Valetudo AI in action:

<iframe title="YouTube video player" />

## Screenshots

### Home Interface

![Home screen](https://raw.githubusercontent.com/vero-code/valetudo-ai/refs/heads/master/screenshots/1-home.png)

### Prompt Templates

![Prompt templates](https://raw.githubusercontent.com/vero-code/valetudo-ai/refs/heads/master/screenshots/10-prompts.png)

### Image Upload

![Image upload](https://raw.githubusercontent.com/vero-code/valetudo-ai/refs/heads/master/screenshots/8-image-upload.png)

### Date & Location Filters

![Date filter](https://raw.githubusercontent.com/vero-code/valetudo-ai/refs/heads/master/screenshots/7-date-filter.png)

![Location filter](https://raw.githubusercontent.com/vero-code/valetudo-ai/refs/heads/master/screenshots/9-location-filter.png)


# Best Practices
Source: https://docs.perplexity.ai/docs/embeddings/best-practices

Optimize your embeddings workflow with batch processing, caching, RAG patterns, and performance tips.

## Overview

This guide covers best practices for getting the most out of Perplexity's Embeddings API, including dimension reduction, batch processing, RAG patterns, and error handling.

## Matryoshka Dimension Reduction

Perplexity embeddings support Matryoshka representation learning, allowing you to reduce embedding dimensions while maintaining quality. This enables faster similarity search and reduced storage costs.

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity

  client = Perplexity()

  # Full dimensions (2560 for 4b model)
  full_response = client.embeddings.create(
      input=["Your text here"],
      model="pplx-embed-v1-4b"
  )
  print(f"Full: {full_response.data[0].embedding}")  # 2560-dim base64 string

  # Reduced dimensions - faster search, smaller storage
  reduced_response = client.embeddings.create(
      input=["Your text here"],
      model="pplx-embed-v1-4b",
      dimensions=512
  )
  print(f"Reduced: {reduced_response.data[0].embedding}")  # 512-dim base64 string
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  // Full dimensions (2560 for 4b model)
  const fullResponse = await client.embeddings.create({
      input: ["Your text here"],
      model: "pplx-embed-v1-4b"
  });
  console.log(`Full: ${fullResponse.data![0].embedding}`);

  // Reduced dimensions - faster search, smaller storage
  const reducedResponse = await client.embeddings.create({
      input: ["Your text here"],
      model: "pplx-embed-v1-4b",
      dimensions: 512
  });
  console.log(`Reduced: ${reducedResponse.data![0].embedding}`);
  ```
</CodeGroup>

<Note>
  **Trade-off:** Lower dimensions = faster search + less storage, but slightly lower quality. Start with full dimensions and reduce if needed.
</Note>

## Encoding Formats

Control precision and size of embedding outputs:

| Format          | Description                                                 |     Decoded Size     | Similarity Metric | Use Case                                      |
| --------------- | ----------------------------------------------------------- | :------------------: | :---------------: | --------------------------------------------- |
| `base64_int8`   | Base64-encoded signed int8 (-128 to 127)                    |   dimensions bytes   | Cosine similarity | Default, good balance of quality and size     |
| `base64_binary` | Base64-encoded packed bits (1 bit per dimension, LSB first) | dimensions / 8 bytes |  Hamming distance | Maximum compression for large-scale retrieval |

<CodeGroup>
  ```python Python theme={null}
  import base64
  import numpy as np

  # Decode base64_int8 (default)
  response = client.embeddings.create(
      input=["Your text"],
      model="pplx-embed-v1-4b"
  )
  int8_embedding = np.frombuffer(
      base64.b64decode(response.data[0].embedding), dtype=np.int8
  )

  # Binary embeddings for large-scale retrieval systems
  response = client.embeddings.create(
      input=["Your text"],
      model="pplx-embed-v1-4b",
      encoding_format="base64_binary"
  )
  binary_bytes = np.frombuffer(
      base64.b64decode(response.data[0].embedding), dtype=np.uint8
  )
  # Unpack bits: each byte contains 8 dimensions (LSB first)
  binary_embedding = np.unpackbits(binary_bytes, bitorder="little")
  ```

  ```typescript TypeScript theme={null}
  // Decode base64_int8 (default)
  const response = await client.embeddings.create({
      input: ["Your text"],
      model: "pplx-embed-v1-4b"
  });
  const buffer = Buffer.from(response.data![0].embedding, 'base64');
  const int8Embedding = new Int8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength);

  // Binary embeddings for large-scale retrieval systems
  const binaryResponse = await client.embeddings.create({
      input: ["Your text"],
      model: "pplx-embed-v1-4b",
      encoding_format: "base64_binary"
  });
  const binaryBuffer = Buffer.from(binaryResponse.data![0].embedding, 'base64');
  // Each byte contains 8 dimensions as packed bits (LSB first)
  ```
</CodeGroup>

<Tip>
  `base64_int8` produces the same quality as bfloat16 with significantly reduced storage. Use `base64_binary` for extreme compression in large-scale systems.
</Tip>

## Similarity Metrics

Perplexity embedding models produce **unnormalized** embeddings. Choosing the correct similarity metric is critical for accurate retrieval.

<Warning>
  `pplx-embed-v1` and `pplx-embed-context-v1` natively produce unnormalized int8-quantized embeddings. You **must** compare them via cosine similarity. Using inner product or L2 distance directly will produce incorrect results because most embedding models are pre-normalized, but Perplexity embeddings are not.
</Warning>

### int8 Embeddings (`base64_int8`)

Compare using **cosine similarity**. If your vector database does not support cosine similarity natively, convert the embeddings to float32 and L2-normalize them before storing:

<CodeGroup>
  ```python Python theme={null}
  import base64
  import numpy as np

  def decode_and_normalize(b64_string):
      """Decode and L2-normalize for vector DBs that only support inner product."""
      embedding = np.frombuffer(base64.b64decode(b64_string), dtype=np.int8).astype(np.float32)
      norm = np.linalg.norm(embedding)
      if norm > 0:
          embedding = embedding / norm
      return embedding

  # After normalization, cosine similarity == inner product
  ```

  ```typescript TypeScript theme={null}
  function decodeAndNormalize(b64String: string): Float32Array {
      const buffer = Buffer.from(b64String, 'base64');
      const int8 = new Int8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength);
      const float32 = new Float32Array(int8.length);

      // Convert to float32
      let norm = 0;
      for (let i = 0; i < int8.length; i++) {
          float32[i] = int8[i];
          norm += float32[i] * float32[i];
      }

      // L2-normalize so inner product == cosine similarity
      norm = Math.sqrt(norm);
      if (norm > 0) {
          for (let i = 0; i < float32.length; i++) {
              float32[i] /= norm;
          }
      }
      return float32;
  }
  ```
</CodeGroup>

### Binary Embeddings (`base64_binary`)

Compare using **Hamming distance**. Binary embeddings encode each dimension as a single bit, so the natural distance metric is the number of differing bits between two vectors.

```python theme={null}
import numpy as np

def hamming_distance(a: np.ndarray, b: np.ndarray) -> int:
    """Hamming distance between two binary vectors (as uint8 packed bits)."""
    return np.unpackbits(np.bitwise_xor(a, b)).sum()
```

<Note>
  Most vector databases (Pinecone, Weaviate, Qdrant, Milvus) support cosine similarity as a distance metric. Verify your database's configuration before indexing embeddings.
</Note>

## RAG Pattern

Combine embeddings with Perplexity's Agentic Research API for retrieval-augmented generation:

<CodeGroup>
  ```python Python theme={null}
  import base64
  import numpy as np
  from perplexity import Perplexity

  client = Perplexity()

  def decode_embedding(b64_string):
      return np.frombuffer(base64.b64decode(b64_string), dtype=np.int8).astype(np.float32)

  def cosine_similarity(a, b):
      return np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))

  # 1. Your knowledge base (embed once, store in vector DB)
  knowledge_base = [
      "Perplexity API provides web-grounded AI responses",
      "The Embeddings API supports Matryoshka dimension reduction",
      "Contextualized embeddings share context across document chunks"
  ]

  kb_response = client.embeddings.create(input=knowledge_base, model="pplx-embed-v1-4b")
  kb_embeddings = [decode_embedding(emb.embedding) for emb in kb_response.data]

  # 2. User query
  user_query = "How do I reduce embedding dimensions?"

  # 3. Find relevant context
  query_response = client.embeddings.create(input=[user_query], model="pplx-embed-v1-4b")
  query_embedding = decode_embedding(query_response.data[0].embedding)

  scores = [(i, cosine_similarity(query_embedding, emb)) for i, emb in enumerate(kb_embeddings)]
  top_docs = sorted(scores, key=lambda x: x[1], reverse=True)[:2]
  context = "\n".join([knowledge_base[i] for i, _ in top_docs])

  # 4. Generate answer with context
  response = client.responses.create(
      model="openai/gpt-5.5",
      input=f"Answer using this context:\n\n{context}\n\nQuestion: {user_query}"
  )

  print(response.output[0].content[0].text)
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  function decodeEmbedding(b64String: string): Int8Array {
      const buffer = Buffer.from(b64String, 'base64');
      return new Int8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength);
  }

  function cosineSimilarity(a: Int8Array, b: Int8Array): number {
      let dotProduct = 0, normA = 0, normB = 0;
      for (let i = 0; i < a.length; i++) {
          dotProduct += a[i] * b[i];
          normA += a[i] * a[i];
          normB += b[i] * b[i];
      }
      return dotProduct / (Math.sqrt(normA) * Math.sqrt(normB));
  }

  // 1. Your knowledge base
  const knowledgeBase = [
      "Perplexity API provides web-grounded AI responses",
      "The Embeddings API supports Matryoshka dimension reduction",
      "Contextualized embeddings share context across document chunks"
  ];

  const kbResponse = await client.embeddings.create({
      input: knowledgeBase,
      model: "pplx-embed-v1-4b"
  });
  const kbEmbeddings = kbResponse.data!.map(emb => decodeEmbedding(emb.embedding!));

  // 2. User query
  const userQuery = "How do I reduce embedding dimensions?";

  // 3. Find relevant context
  const queryResponse = await client.embeddings.create({
      input: [userQuery],
      model: "pplx-embed-v1-4b"
  });
  const queryEmbedding = decodeEmbedding(queryResponse.data![0].embedding!);

  const scores = kbEmbeddings.map((emb, i) => ({
      index: i,
      score: cosineSimilarity(queryEmbedding, emb)
  }));
  const topDocs = scores.sort((a, b) => b.score - a.score).slice(0, 2);
  const context = topDocs.map(d => knowledgeBase[d.index]).join("\n");

  // 4. Generate answer with context
  const response = await client.responses.create({
      model: "openai/gpt-5.5",
      input: `Answer using this context:\n\n${context}\n\nQuestion: ${userQuery}`
  });

  console.log((response.output[0] as any).content[0].text);
  ```
</CodeGroup>

## Batch Processing

Process large datasets efficiently with async batching:

<CodeGroup>
  ```python Python theme={null}
  import asyncio
  from perplexity import AsyncPerplexity

  async def batch_embed(texts: list[str], batch_size: int = 100):
      async with AsyncPerplexity() as client:
          results = []
          for i in range(0, len(texts), batch_size):
              batch = texts[i:i + batch_size]
              response = await client.embeddings.create(
                  input=batch,
                  model="pplx-embed-v1-4b"
              )
              results.extend(response.data)
              print(f"Processed {min(i + batch_size, len(texts))}/{len(texts)}")
          return results

  # Usage
  texts = ["Document " + str(i) for i in range(1000)]
  embeddings = asyncio.run(batch_embed(texts))
  print(f"Generated {len(embeddings)} embeddings")
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  async function batchEmbed(texts: string[], batchSize: number = 100) {
      const client = new Perplexity();
      const results: any[] = [];

      for (let i = 0; i < texts.length; i += batchSize) {
          const batch = texts.slice(i, i + batchSize);
          const response = await client.embeddings.create({
              input: batch,
              model: "pplx-embed-v1-4b"
          });
          results.push(...(response.data ?? []));
          console.log(`Processed ${Math.min(i + batchSize, texts.length)}/${texts.length}`);
      }

      return results;
  }

  // Usage
  const texts = Array.from({ length: 1000 }, (_, i) => `Document ${i}`);
  const embeddings = await batchEmbed(texts);
  console.log(`Generated ${embeddings.length} embeddings`);
  ```
</CodeGroup>

## Error Handling

<CodeGroup>
  ```python Python theme={null}
  import perplexity
  from perplexity import Perplexity

  client = Perplexity()

  try:
      response = client.embeddings.create(
          input=["Your text"],
          model="pplx-embed-v1-4b"
      )
  except perplexity.BadRequestError as e:
      print(f"Invalid request: {e}")
  except perplexity.RateLimitError:
      print("Rate limited, please retry later")
  except perplexity.APIStatusError as e:
      print(f"API error: {e.status_code}")
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  try {
      const response = await client.embeddings.create({
          input: ["Your text"],
          model: "pplx-embed-v1-4b"
      });
  } catch (error) {
      if (error instanceof Perplexity.BadRequestError) {
          console.error("Invalid request:", error.message);
      } else if (error instanceof Perplexity.RateLimitError) {
          console.error("Rate limited, please retry later");
      } else if (error instanceof Perplexity.APIError) {
          console.error(`API error: ${error.status}`);
      }
  }
  ```
</CodeGroup>

## Tips

<Steps>
  <Step title="Batch requests">
    Send up to 512 texts per request to maximize throughput and reduce API calls.
  </Step>

  <Step title="Match models">
    Always use the same embedding model for both queries and documents to ensure consistent similarity scores.
  </Step>

  <Step title="Use cosine similarity">
    Perplexity embeddings are unnormalized. Always use cosine similarity for `base64_int8` and Hamming distance for `base64_binary`. If your vector DB only supports inner product, L2-normalize the embeddings before storing.
  </Step>

  <Step title="Cache embeddings">
    Store computed embeddings in a vector database. Never recompute embeddings for the same text.
  </Step>

  <Step title="Use Matryoshka wisely">
    Start with full dimensions for best quality. Reduce dimensions only if you need faster search or smaller storage.
  </Step>

  <Step title="Binary for scale">
    Use `base64_binary` encoding format for large-scale retrieval systems where storage and speed are critical.
  </Step>
</Steps>

## Related Resources

<CardGroup>
  <Card title="Quickstart" icon="rocket" href="/docs/embeddings/quickstart">
    Get started with basic embeddings functionality.
  </Card>

  <Card title="Contextualized Embeddings" icon="file-lines" href="/docs/embeddings/contextualized-embeddings">
    Document-aware embeddings for chunks with shared context.
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/embeddings-post">
    Complete Embeddings API documentation.
  </Card>

  <Card title="SDK Guide" icon="code" href="/docs/sdk/overview">
    Perplexity SDK features and best practices.
  </Card>
</CardGroup>


# Contextualized Embeddings
Source: https://docs.perplexity.ai/docs/embeddings/contextualized-embeddings

Generate document-aware embeddings for chunks that share context, improving retrieval quality for document-based applications.

## Overview

Contextualized embeddings generate embeddings for document chunks that share context awareness. Unlike standard embeddings where each text is embedded independently, contextualized embeddings understand that chunks belong to the same document and incorporate that relationship.

<Info>
  Use contextualized embeddings when embedding chunks from the same document (e.g., paragraphs, sections). Use [standard embeddings](/docs/embeddings/quickstart) for independent texts like search queries or standalone sentences.
</Info>

## Models

|             Model            | Dimensions | Context | MRL | Quantization | Price (\$/1M tokens) |
| :--------------------------: | :--------: | :-----: | :-: | :----------: | :------------------: |
| `pplx-embed-context-v1-0.6b` |    1024    |   32K   | Yes |  INT8/BINARY |        \$0.008       |
|  `pplx-embed-context-v1-4b`  |    2560    |   32K   | Yes |  INT8/BINARY |        \$0.05        |

All models use mean pooling and require no instruction prefix.

## Basic Usage

Pass documents as nested arrays where each inner array represents chunks from a single document:

<Warning>
  **Chunk ordering:** Chunks within each document must be sent in the order they appear in the source document. The model uses sequential context to generate document-aware embeddings, so maintaining the original order is essential for optimal results.
</Warning>

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity

  client = Perplexity()

  response = client.contextualized_embeddings.create(
      input=[
          # Document 1: Three chunks
          [
              "Curiosity begins in childhood with endless questions about the world.",
              "As we grow, curiosity drives us to explore new ideas and challenge assumptions.",
              "Scientific breakthroughs often start with a simple curious question."
          ],
          # Document 2: Two chunks
          [
              "The Curiosity rover explores Mars, searching for signs of ancient life.",
              "Each discovery on Mars sparks new questions about our place in the universe."
          ]
      ],
      model="pplx-embed-context-v1-4b"
  )

  for doc in response.data:
      for chunk in doc.data:
          print(f"Doc {doc.index}, Chunk {chunk.index}: {chunk.embedding}")
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  const response = await client.contextualizedEmbeddings.create({
      input: [
          // Document 1: Three chunks
          [
              "Curiosity begins in childhood with endless questions about the world.",
              "As we grow, curiosity drives us to explore new ideas and challenge assumptions.",
              "Scientific breakthroughs often start with a simple curious question."
          ],
          // Document 2: Two chunks
          [
              "The Curiosity rover explores Mars, searching for signs of ancient life.",
              "Each discovery on Mars sparks new questions about our place in the universe."
          ]
      ],
      model: "pplx-embed-context-v1-4b"
  });

  for (const doc of response.data!) {
      for (const chunk of doc.data!) {
          console.log(`Doc ${doc.index}, Chunk ${chunk.index}: ${chunk.embedding!}`);
      }
  }
  ```

  ```bash cURL theme={null}
  curl -X POST 'https://api.perplexity.ai/v1/contextualizedembeddings' \
    -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
      "input": [
        [
          "Curiosity begins in childhood with endless questions about the world.",
          "As we grow, curiosity drives us to explore new ideas and challenge assumptions.",
          "Scientific breakthroughs often start with a simple curious question."
        ],
        [
          "The Curiosity rover explores Mars, searching for signs of ancient life.",
          "Each discovery on Mars sparks new questions about our place in the universe."
        ]
      ],
      "model": "pplx-embed-context-v1-4b"
    }' | jq
  ```
</CodeGroup>

<Accordion title="Response">
  ```json theme={null}
  {
    "object": "list",
    "data": [
      {
        "object": "list",
        "index": 0,
        "data": [
          { "object": "embedding", "index": 0, "embedding": "/* base64-encoded signed int8 values */" },
          { "object": "embedding", "index": 1, "embedding": "/* base64-encoded signed int8 values */" },
          { "object": "embedding", "index": 2, "embedding": "/* base64-encoded signed int8 values */" }
        ]
      },
      {
        "object": "list",
        "index": 1,
        "data": [
          { "object": "embedding", "index": 0, "embedding": "/* base64-encoded signed int8 values */" },
          { "object": "embedding", "index": 1, "embedding": "/* base64-encoded signed int8 values */" }
        ]
      }
    ],
    "model": "pplx-embed-context-v1-4b",
    "usage": {
      "prompt_tokens": 72,
      "total_tokens": 72
    }
  }
  ```
</Accordion>

## Parameters

| Parameter         | Type                   | Required |    Default    | Description                                                                                               |
| ----------------- | ---------------------- | :------: | :-----------: | --------------------------------------------------------------------------------------------------------- |
| `input`           | array\[array\[string]] |    Yes   |       -       | Nested array: each inner array contains chunks from one document. Max 512 documents, 16,000 total chunks. |
| `model`           | string                 |    Yes   |       -       | Model identifier: `pplx-embed-context-v1-0.6b` or `pplx-embed-context-v1-4b`                              |
| `dimensions`      | integer                |    No    |      Full     | Matryoshka dimension (128-1024 for 0.6b, 128-2560 for 4b)                                                 |
| `encoding_format` | string                 |    No    | `base64_int8` | Output encoding: `base64_int8` (signed int8) or `base64_binary` (packed bits)                             |

<Warning>
  **Input limits:** Total tokens per document must not exceed 32K. Total chunks across all documents must not exceed 16,000. All chunks in a single request must not exceed 120,000 tokens combined. Empty strings are not allowed.
</Warning>

## Golden Chunk Retrieval Example

Build a chunk retrieval system where chunks from the same document share context:

<CodeGroup>
  ```python Python theme={null}
  import base64
  import numpy as np
  from perplexity import Perplexity

  client = Perplexity()

  def decode_embedding(b64_string):
      """Decode a base64-encoded int8 embedding."""
      return np.frombuffer(base64.b64decode(b64_string), dtype=np.int8).astype(np.float32)

  def cosine_similarity(a, b):
      return np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))

  # Your documents, each split into chunks
  documents = [
      {
          "title": "Machine Learning Guide",
          "chunks": [
              "Machine learning is a subset of AI that enables systems to learn.",
              "Supervised learning uses labeled data for training models.",
              "Unsupervised learning finds patterns in unlabeled data."
          ]
      },
      {
          "title": "Deep Learning Fundamentals",
          "chunks": [
              "Deep learning uses neural networks with multiple layers.",
              "Convolutional networks excel at image processing tasks.",
              "Transformers revolutionized natural language processing."
          ]
      }
  ]

  # 1. Embed all document chunks with context awareness
  doc_chunks = [doc["chunks"] for doc in documents]
  doc_response = client.contextualized_embeddings.create(
      input=doc_chunks,
      model="pplx-embed-context-v1-4b"
  )

  # Build index
  chunk_index = []
  for doc_obj in doc_response.data:
      for chunk_obj in doc_obj.data:
          chunk_index.append({
              "doc_idx": doc_obj.index,
              "chunk_idx": chunk_obj.index,
              "embedding": decode_embedding(chunk_obj.embedding),
              "text": documents[doc_obj.index]["chunks"][chunk_obj.index],
              "doc_title": documents[doc_obj.index]["title"]
          })

  # 2. Embed the query using the same contextualized model
  # Wrap each query as a single-element inner list: [[query1], [query2]]
  query = "How do neural networks process images?"
  query_response = client.contextualized_embeddings.create(
      input=[[query]],
      model="pplx-embed-context-v1-4b"
  )
  query_embedding = decode_embedding(query_response.data[0].data[0].embedding)

  # 3. Find most relevant chunks
  results = []
  for item in chunk_index:
      score = cosine_similarity(query_embedding, item["embedding"])
      results.append({**item, "score": score})

  results = sorted(results, key=lambda x: x["score"], reverse=True)

  print(f"Query: {query}\n")
  print("Top results:")
  for r in results[:3]:
      print(f"  [{r['doc_title']}] {r['score']:.4f}: {r['text'][:60]}...")
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  function decodeEmbedding(b64String: string): Int8Array {
      const buffer = Buffer.from(b64String, 'base64');
      return new Int8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength);
  }

  function cosineSimilarity(a: Int8Array, b: Int8Array): number {
      let dotProduct = 0, normA = 0, normB = 0;
      for (let i = 0; i < a.length; i++) {
          dotProduct += a[i] * b[i];
          normA += a[i] * a[i];
          normB += b[i] * b[i];
      }
      return dotProduct / (Math.sqrt(normA) * Math.sqrt(normB));
  }

  // Your documents, each split into chunks
  const documents = [
      {
          title: "Machine Learning Guide",
          chunks: [
              "Machine learning is a subset of AI that enables systems to learn.",
              "Supervised learning uses labeled data for training models.",
              "Unsupervised learning finds patterns in unlabeled data."
          ]
      },
      {
          title: "Deep Learning Fundamentals",
          chunks: [
              "Deep learning uses neural networks with multiple layers.",
              "Convolutional networks excel at image processing tasks.",
              "Transformers revolutionized natural language processing."
          ]
      }
  ];

  // 1. Embed all document chunks with context awareness
  const docChunks = documents.map(doc => doc.chunks);
  const docResponse = await client.contextualizedEmbeddings.create({
      input: docChunks,
      model: "pplx-embed-context-v1-4b"
  });

  // Build index
  const chunkIndex = docResponse.data!.flatMap(docObj =>
      docObj.data!.map(chunkObj => ({
          docIdx: docObj.index,
          chunkIdx: chunkObj.index,
          embedding: decodeEmbedding(chunkObj.embedding!),
          text: documents[docObj.index as number].chunks[chunkObj.index as number],
          docTitle: documents[docObj.index as number].title
      }))
  );

  // 2. Embed the query using the same contextualized model
  // Wrap each query as a single-element inner list: [[query1], [query2]]
  const query = "How do neural networks process images?";
  const queryResponse = await client.contextualizedEmbeddings.create({
      input: [[query]],
      model: "pplx-embed-context-v1-4b"
  });
  const queryEmbedding = decodeEmbedding(queryResponse.data![0].data![0].embedding!);

  // 3. Find most relevant chunks
  const results = chunkIndex
      .map(item => ({
          ...item,
          score: cosineSimilarity(queryEmbedding, item.embedding)
      }))
      .sort((a, b) => b.score - a.score);

  console.log(`Query: ${query}\n`);
  console.log("Top results:");
  for (const r of results.slice(0, 3)) {
      console.log(`  [${r.docTitle}] ${r.score.toFixed(4)}: ${r.text.slice(0, 60)}...`);
  }
  ```
</CodeGroup>

## When to Use Contextualized vs Standard

| Use Case                  | Recommendation            |
| ------------------------- | ------------------------- |
| Independent sentences     | Standard embeddings       |
| FAQ entries               | Standard embeddings       |
| General-purpose retrieval | Standard embeddings       |
| Document paragraphs       | Contextualized embeddings |
| PDF sections              | Contextualized embeddings |
| Article chunks            | Contextualized embeddings |
| Code file segments        | Contextualized embeddings |

<Tip>
  **Rule of thumb:** If chunks come from the same source document and their meaning depends on surrounding context, use contextualized embeddings. If each text stands alone, use standard embeddings. When using contextualized embeddings, embed queries with the same contextualized model by wrapping each query as a single-element inner list (e.g., `[[query]]`).
</Tip>

## Related Resources

<CardGroup>
  <Card title="Quickstart" icon="rocket" href="/docs/embeddings/quickstart">
    Get started with standard embeddings.
  </Card>

  <Card title="Best Practices" icon="star" href="/docs/embeddings/best-practices">
    Batch processing, caching, and RAG patterns.
  </Card>
</CardGroup>


# Embeddings API
Source: https://docs.perplexity.ai/docs/embeddings/quickstart

Generate high-quality text embeddings for semantic search, RAG, and machine learning applications.

## Overview

Perplexity's Embeddings API generates high-quality text embeddings for semantic search and retrieval. Choose between **standard embeddings** for independent texts or **contextualized embeddings** for document chunks that share context.

<Info>
  We recommend using our [official SDKs](/docs/sdk/overview) for a more convenient and type-safe way to interact with the Embeddings API.
</Info>

## Available Models

|             Model            | Dimensions | Context | MRL | Quantization | Price (\$/1M tokens) |
| :--------------------------: | :--------: | :-----: | :-: | :----------: | :------------------: |
|     `pplx-embed-v1-0.6b`     |    1024    |   32K   | Yes |  INT8/BINARY |        \$0.004       |
|      `pplx-embed-v1-4b`      |    2560    |   32K   | Yes |  INT8/BINARY |        \$0.03        |
| `pplx-embed-context-v1-0.6b` |    1024    |   32K   | Yes |  INT8/BINARY |        \$0.008       |
|  `pplx-embed-context-v1-4b`  |    2560    |   32K   | Yes |  INT8/BINARY |        \$0.05        |

All models use mean pooling and require no instruction prefix—you can embed text directly without prompt engineering.

<Warning>
  Perplexity embeddings are **unnormalized**. Always compare `base64_int8` embeddings via **cosine similarity** (not inner product or L2 distance). Compare `base64_binary` embeddings via **Hamming distance**. See [Best Practices](/docs/embeddings/best-practices) for details and normalization helpers.
</Warning>

<Tip>
  **When to use which:**

  * **Standard embeddings** (`pplx-embed-v1-*`) - Independent texts, search queries, single sentences
  * **Contextualized embeddings** (`pplx-embed-context-v1-*`) - Document chunks that benefit from shared context (e.g., paragraphs from the same article)
</Tip>

## Installation

<CodeGroup>
  ```bash Python theme={null}
  pip install perplexityai
  ```

  ```bash TypeScript/JavaScript theme={null}
  npm install @perplexity-ai/perplexity_ai
  ```
</CodeGroup>

## Authentication

Set your API key as an environment variable:

<Tabs>
  <Tab title="macOS/Linux">
    ```bash theme={null}
    export PERPLEXITY_API_KEY="your_api_key_here"
    ```
  </Tab>

  <Tab title="Windows">
    ```powershell theme={null}
    setx PERPLEXITY_API_KEY "your_api_key_here"
    ```
  </Tab>
</Tabs>

## Next Steps

<CardGroup>
  <Card title="Standard Embeddings" icon="cube" href="/docs/embeddings/standard-embeddings">
    Embed independent texts, queries, and sentences.
  </Card>

  <Card title="Contextualized Embeddings" icon="file-lines" href="/docs/embeddings/contextualized-embeddings">
    Document-aware embeddings for chunks that share context.
  </Card>

  <Card title="Best Practices" icon="star" href="/docs/embeddings/best-practices">
    Batch processing, caching, RAG patterns, and performance optimization.
  </Card>

  <Card title="Model Cards" icon="link" href="https://huggingface.co/perplexity-ai">
    See the model cards on HuggingFace.
  </Card>
</CardGroup>


# Standard Embeddings
Source: https://docs.perplexity.ai/docs/embeddings/standard-embeddings

Generate embeddings for independent texts, search queries, and single sentences.

## Overview

Use standard embeddings for independent text embedding (queries, documents, and semantic search) where each text is self-contained.

## Models

|         Model        | Dimensions | Context | MRL | Quantization | Price (\$/1M tokens) |
| :------------------: | :--------: | :-----: | :-: | :----------: | :------------------: |
| `pplx-embed-v1-0.6b` |    1024    |   32K   | Yes |  INT8/BINARY |        \$0.004       |
|  `pplx-embed-v1-4b`  |    2560    |   32K   | Yes |  INT8/BINARY |        \$0.03        |

## Basic Usage

Generate embeddings for a list of texts:

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity

  client = Perplexity()

  response = client.embeddings.create(
      input=[
          "Scientists explore the universe driven by curiosity.",
          "Curiosity compels us to seek explanations, not just observations.",
          "Historical discoveries began with curious questions.",
          "The pursuit of knowledge distinguishes human curiosity from mere stimulus response.",
          "Philosophy examines the nature of curiosity."
      ],
      model="pplx-embed-v1-4b"
  )

  for emb in response.data:
      print(f"Index {emb.index}: {emb.embedding}")
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  const response = await client.embeddings.create({
      input: [
          "Scientists explore the universe driven by curiosity.",
          "Curiosity compels us to seek explanations, not just observations.",
          "Historical discoveries began with curious questions.",
          "The pursuit of knowledge distinguishes human curiosity from mere stimulus response.",
          "Philosophy examines the nature of curiosity."
      ],
      model: "pplx-embed-v1-4b"
  });

  for (const emb of response.data!) {
      console.log(`Index ${emb.index}: ${emb.embedding!}`);
  }
  ```

  ```bash cURL theme={null}
  curl -X POST 'https://api.perplexity.ai/v1/embeddings' \
    -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
      "input": [
        "Scientists explore the universe driven by curiosity.",
        "Curiosity compels us to seek explanations, not just observations.",
        "Historical discoveries began with curious questions.",
        "The pursuit of knowledge distinguishes human curiosity from mere stimulus response.",
        "Philosophy examines the nature of curiosity."
      ],
      "model": "pplx-embed-v1-4b"
    }' | jq
  ```
</CodeGroup>

<Accordion title="Response">
  ```json theme={null}
  {
    "object": "list",
    "data": [
      {
        "object": "embedding",
        "index": 0,
        "embedding": "/* base64-encoded signed int8 values */"
      },
      {
        "object": "embedding",
        "index": 1,
        "embedding": "/* base64-encoded signed int8 values */"
      },
      {
        "object": "embedding",
        "index": 2,
        "embedding": "/* base64-encoded signed int8 values */"
      },
      {
        "object": "embedding",
        "index": 3,
        "embedding": "/* base64-encoded signed int8 values */"
      },
      {
        "object": "embedding",
        "index": 4,
        "embedding": "/* base64-encoded signed int8 values */"
      }
    ],
    "model": "pplx-embed-v1-4b",
    "usage": {
      "prompt_tokens": 42,
      "total_tokens": 42,
      "cost": {
        "input_cost": 0.0000013,
        "total_cost": 0.0000013,
        "currency": "USD"
      }
    }
  }
  ```
</Accordion>

## Semantic Search Example

Build a simple semantic search system:

<CodeGroup>
  ```python Python theme={null}
  import base64
  import numpy as np
  from perplexity import Perplexity

  client = Perplexity()

  def decode_embedding(b64_string):
      """Decode a base64-encoded int8 embedding."""
      return np.frombuffer(base64.b64decode(b64_string), dtype=np.int8).astype(np.float32)

  def cosine_similarity(a, b):
      return np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))

  # 1. Embed your documents
  documents = [
      "Python is a versatile programming language",
      "Machine learning automates analytical model building",
      "The Eiffel Tower is located in Paris, France"
  ]

  doc_response = client.embeddings.create(input=documents, model="pplx-embed-v1-4b")
  doc_embeddings = [decode_embedding(emb.embedding) for emb in doc_response.data]

  # 2. Embed a search query
  query = "What programming languages are good for data science?"
  query_response = client.embeddings.create(input=[query], model="pplx-embed-v1-4b")
  query_embedding = decode_embedding(query_response.data[0].embedding)

  # 3. Find most similar documents
  scores = [
      (i, cosine_similarity(query_embedding, doc_emb))
      for i, doc_emb in enumerate(doc_embeddings)
  ]
  ranked = sorted(scores, key=lambda x: x[1], reverse=True)

  print("Search results:")
  for idx, score in ranked:
      print(f"  {score:.4f}: {documents[idx]}")
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  function decodeEmbedding(b64String: string): Int8Array {
      const buffer = Buffer.from(b64String, 'base64');
      return new Int8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength);
  }

  function cosineSimilarity(a: Int8Array, b: Int8Array): number {
      let dotProduct = 0, normA = 0, normB = 0;
      for (let i = 0; i < a.length; i++) {
          dotProduct += a[i] * b[i];
          normA += a[i] * a[i];
          normB += b[i] * b[i];
      }
      return dotProduct / (Math.sqrt(normA) * Math.sqrt(normB));
  }

  // 1. Embed your documents
  const documents = [
      "Python is a versatile programming language",
      "Machine learning automates analytical model building",
      "The Eiffel Tower is located in Paris, France"
  ];

  const docResponse = await client.embeddings.create({
      input: documents,
      model: "pplx-embed-v1-4b"
  });
  const docEmbeddings = docResponse.data!.map(emb => decodeEmbedding(emb.embedding!));

  // 2. Embed a search query
  const query = "What programming languages are good for data science?";
  const queryResponse = await client.embeddings.create({
      input: [query],
      model: "pplx-embed-v1-4b"
  });
  const queryEmbedding = decodeEmbedding(queryResponse.data![0].embedding!);

  // 3. Find most similar documents
  const scores = docEmbeddings.map((docEmb, i) => ({
      index: i,
      score: cosineSimilarity(queryEmbedding, docEmb)
  }));
  const ranked = scores.sort((a, b) => b.score - a.score);

  console.log("Search results:");
  for (const { index, score } of ranked) {
      console.log(`  ${score.toFixed(4)}: ${documents[index]}`);
  }
  ```
</CodeGroup>

## Parameters

| Parameter         | Type                     | Required |    Default    | Description                                                                                                                                              |
| ----------------- | ------------------------ | :------: | :-----------: | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `input`           | string \| array\[string] |    Yes   |       -       | Text(s) to embed. Max 512 texts per request. Each input must not exceed 32K tokens. Total tokens must not exceed 120,000. Empty strings are not allowed. |
| `model`           | string                   |    Yes   |       -       | Model identifier: `pplx-embed-v1-0.6b` or `pplx-embed-v1-4b`                                                                                             |
| `dimensions`      | integer                  |    No    |      Full     | Matryoshka dimension (128-1024 for 0.6b, 128-2560 for 4b)                                                                                                |
| `encoding_format` | string                   |    No    | `base64_int8` | Output encoding: `base64_int8` (signed int8) or `base64_binary` (packed bits)                                                                            |

<Warning>
  **Input limits:** Each text must not exceed 32K tokens. Requests exceeding this limit will be rejected. All inputs in a single request must not exceed 120,000 tokens combined.
</Warning>

## Related Resources

<CardGroup>
  <Card title="Contextualized Embeddings" icon="file-lines" href="/docs/embeddings/contextualized-embeddings">
    Document-aware embeddings for chunks that share context.
  </Card>

  <Card title="Best Practices" icon="star" href="/docs/embeddings/best-practices">
    Batch processing, caching, and RAG patterns.
  </Card>
</CardGroup>


# API Groups & Billing
Source: https://docs.perplexity.ai/docs/getting-started/api-groups

Learn how to use the Perplexity API Portal to manage access, usage, billing, and team collaboration.

## What is an API Group?

An **API Group** is your organization's workspace in the Perplexity API Portal. It allows you to:

* **Manage billing** and payment methods for API usage
* **Create and control API keys** for accessing the Perplexity API
* **Invite team members** and control their permissions (optional)
* **Monitor usage and costs** across all your API keys

## Prerequisites

Before getting started, make sure you have:

* A Perplexity account (sign up at [perplexity.ai](https://perplexity.ai))
* **Admin permissions** for billing and API key management
* A **credit card** ready for payment setup (you won't be charged initially)

<Note>
  If you're joining an existing team, you'll need an invitation from an Admin. Contact your team lead to get access.
</Note>

## Accessing the API Portal

Navigate to [console.perplexity.ai](https://console.perplexity.ai) to access your API group. The left-hand sidebar is divided into two sections:

* **Group**: Settings, Members, Billing, API keys, Files
* **API Playground**: Search API, Agent API

***

## Creating and Managing an API Group

To set up your organization:

<Steps>
  <Step title="Access Group Settings">
    Click **Settings** in the left sidebar under **Group**.

    <Frame>
      <img alt="API Group Settings" />
    </Frame>
  </Step>

  <Step title="Complete Organization Details">
    Fill out your organization's name, address, and tax details.

    <Frame>
      <img alt="API Group Setup" />
    </Frame>

    <Info>
      Your organization name and address will appear on invoices and help us support you better.
    </Info>
  </Step>
</Steps>

***

## Billing and Payment Methods

### How Billing Works

The Perplexity API uses a **credit-based billing system**:

* **Credits** are purchased in advance and used for API calls
* **Different models** consume different amounts of credits per request
* **Usage is charged** based on tokens processed and search queries made
* **Automatic top-up** can be enabled to avoid service interruptions

<Info>
  See our [Pricing page](./pricing) for detailed cost information per model and usage type.
</Info>

### Setting Up Payment

<Card title="Access Billing Dashboard" icon="credit-card" href="https://console.perplexity.ai">
  Navigate directly to your API billing dashboard to manage payment methods, view usage, and configure billing settings.
</Card>

<Steps>
  <Step title="Navigate to Billing">
    Click **Billing** in the left sidebar. This page shows your credit balance, payment method, usage chart, and billing breakdown.

    <Frame>
      <img alt="API Billing Dashboard" />
    </Frame>
  </Step>

  <Step title="Add Payment Method">
    Click **Add payment method** and enter your credit card information. Payment is managed via Stripe — you can also click **Manage ↗** to access the Stripe portal directly.

    <Note>
      Adding a payment method will not charge your credit card. It stores payment information for future API usage.
    </Note>
  </Step>

  <Step title="Configure Auto Reload (Recommended)">
    Enable automatic credit top-up by clicking **Change preferences** next to **Auto reload**.

    <Frame>
      <img alt="API Billing Dashboard" />
    </Frame>

    <Warning>
      If you run out of credits, your API keys will be blocked until you add to your credit balance. Auto reload prevents this by automatically adding credits when your balance drops below a threshold.
    </Warning>
  </Step>
</Steps>

### Credit Balance

The Billing page displays your **remaining credit balance** prominently at the top. You can purchase additional credits at any time using the **Buy more credits** link.

Your current **usage tier** is also shown here — click **Learn more ↗** for details on tier thresholds and benefits.

***

## Managing API Keys

### What are API Keys?

API keys are your credentials for accessing the Perplexity API. Each key:

* **Authenticates your requests** to the Perplexity API
* **Tracks usage** for attribution
* **Can be revoked** for security purposes
* **Should be kept secure** and never shared publicly

<Info>
  You'll need to include your API key in the Authorization header of every API request: `Authorization: Bearer $PERPLEXITY_API_KEY`
</Info>

### Creating an API Key

<Steps>
  <Step title="Navigate to API Keys">
    Click **API keys** in the left sidebar.

    <Frame>
      <img alt="API Keys" />
    </Frame>
  </Step>

  <Step title="Generate New Key">
    Click **+ Generate API Key** to create a new API key.

    <Frame>
      <img alt="API Keys" />
    </Frame>
  </Step>
</Steps>

<Warning>
  API keys are sensitive credentials. Never expose them in client-side code or share them in public repositories.
</Warning>

***

## Adding and Managing Members

Admins can invite team members to the organization with specific roles: **Admin** or **Member**.

### Adding a Member

<Steps>
  <Step title="Navigate to Members">
    Click **Members** in the left sidebar. This page shows your current team members and their roles.
  </Step>

  <Frame>
    <img alt="Members" />
  </Frame>

  <Step title="Initiate Member Invitation">
    Click **+ Add Member**. Enter the user's email address and click **Invite**.

    <Frame>
      <img alt="Add Member" />
    </Frame>
  </Step>

  <Step title="Member Receives Invitation">
    The invited user will receive an email with a link to join your group.

    <Check>
      Once they accept, they'll appear in your member list with their assigned role.
    </Check>
  </Step>
</Steps>

### Filtering Members by Role

Use the dropdown to filter your list of team members by role.

### Roles

* **Admin**: Full access to invite/remove members, manage billing, and view usage data.
* **Member**: Can view usage and account limits but cannot modify settings.

<Warning>
  Only Admins can make changes to billing and member permissions.
</Warning>

***

## Viewing Usage Metrics

All members can monitor API usage directly from the **Billing** page in the console.

<Frame>
  <img alt="Usage Metrics" />
</Frame>

The **Usage** chart lets you track activity over time with the following filters:

* **Metric selector**: Choose from Chat Completions API Requests, Input Tokens, Output Tokens, Citation Tokens, Reasoning Tokens, Deep Research Requests Count, Search API Requests Count, or Pro Search API Requests Count
* **Time range**: Filter by Last 7 Days, Last 30 Days, or custom range

Below the chart, the **Billing breakdown** table shows a per-model breakdown of usage quantity, rate, and cost — giving you a clear picture of spend by product.

<Check>
  Usage metrics help you monitor API activity and optimize for cost or performance.
</Check>

## Invoice History

Below the usage chart and billing breakdown on the **Billing** page, you'll find your **Invoice history** — a record of all past invoices with their date, status, and cost.

<Frame>
  <img alt="Invoice History" />
</Frame>

Invoices are generated automatically each billing cycle. Use the **Previous** and **Next** controls to paginate through older records.


# Perplexity with AG2
Source: https://docs.perplexity.ai/docs/getting-started/integrations/ag2

Use the Perplexity Search API as a tool inside AG2 (AutoGen) agents.

## Overview

AG2 ships a `PerplexitySearchToolkit` that wraps the [Perplexity Search API](/docs/search/quickstart) as a native AG2 tool. The tool returns ranked web results — title, URL, snippet, and date — without generating an LLM answer, which keeps token usage minimal and lets the calling agent decide how to consume them.

<Info>
  **AG2** (formerly AutoGen) is an open-source framework for building multi-agent conversational AI systems. Learn more at [ag2.ai](https://ag2.ai).
</Info>

## Installation

```bash theme={null}
pip install "ag2[perplexity]"
```

## API Key Setup

Set your Perplexity API key as an environment variable, or pass it to the toolkit constructor:

```bash theme={null}
export PERPLEXITY_API_KEY="your_api_key_here"
```

<Card title="Get API Key" icon="key" href="https://console.perplexity.ai">
  Generate your API key from the Perplexity dashboard.
</Card>

## Quick Start

Register `PerplexitySearchToolkit` with an AG2 `Agent`:

```python theme={null}
from autogen.beta import Agent
from autogen.beta.tools.search import PerplexitySearchToolkit

toolkit = PerplexitySearchToolkit()
search = toolkit.search()

agent = Agent(
    "researcher",
    prompt="Answer using fresh information from the web.",
    tools=[search],
)

await agent.ask("What were the top tech announcements this week?")
```

The tool calls the Perplexity Search API under the hood and returns structured `PerplexitySearchResult` objects.

## Configuration

All search parameters are passed to `toolkit.search()` and forwarded to the Search API:

```python theme={null}
from autogen.beta.tools.search import PerplexitySearchToolkit

toolkit = PerplexitySearchToolkit()
search = toolkit.search(
    max_results=5,
    max_tokens_per_page=512,
    search_domain_filter=["arxiv.org", "-medium.com"],  # prefix with '-' to exclude
    search_recency_filter="week",                         # hour | day | week | month | year
    search_after_date_filter="1/1/2025",
    search_before_date_filter="12/31/2025",
)
```

You can also pass any parameter as an AG2 `Variable` so it can be resolved from the conversation context at runtime:

```python theme={null}
from autogen.beta import Variable
from autogen.beta.tools.search import PerplexitySearchToolkit

toolkit = PerplexitySearchToolkit()
search = toolkit.search(
    max_results=Variable("user_max"),
    search_recency_filter=Variable(),  # resolved from the variable named after the parameter
)
```

## Response Shape

Each call returns a `PerplexitySearchResponse` with the original query and a list of `PerplexitySearchResult` items:

```python theme={null}
@dataclass(slots=True)
class PerplexitySearchResult:
    title: str
    url: str
    snippet: str | None = None
    date: str | None = None

@dataclass(slots=True)
class PerplexitySearchResponse:
    query: str
    results: list[PerplexitySearchResult]
    content: str | None = None
    citations: list[str]
    images: list[PerplexityImageMeta]
```

## Links & Resources

<CardGroup>
  <Card title="AG2 Docs" icon="book" href="https://docs.ag2.ai">
    Build multi-agent systems with AG2.
  </Card>

  <Card title="Tool Source" icon="brand-github" href="https://github.com/ag2ai/ag2/blob/main/autogen/beta/tools/search/perplexity.py">
    PerplexitySearchToolkit implementation.
  </Card>

  <Card title="Search API Quickstart" icon="search" href="/docs/search/quickstart">
    Learn more about the underlying Perplexity Search API.
  </Card>

  <Card title="Common Toolkits" icon="toolbox" href="https://docs.ag2.ai/docs/beta/tools/common_toolkits">
    Browse all built-in AG2 tools.
  </Card>
</CardGroup>

## Support

Need help with the integration?

* Browse the [AG2 documentation](https://docs.ag2.ai)
* Review our [FAQ](/docs/resources/faq)


# Perplexity with Agno
Source: https://docs.perplexity.ai/docs/getting-started/integrations/agno

Use Perplexity's web-grounded models inside Agno agents and teams.

## Overview

[Agno](https://docs.agno.com) is an open-source Python framework for building agents, teams, and workflows with first-class support for 40+ model providers. Agno ships a native `Perplexity` model class so you can drop Perplexity's web-grounded Sonar models into any Agno `Agent` with a single import.

<Info>
  **Agno** provides a unified `Agent` abstraction, a tools system, and a multi-agent team/workflow runtime. Learn more at [agno.com](https://agno.com).
</Info>

## Installation

```bash theme={null}
pip install agno openai
```

The `Perplexity` model extends Agno's OpenAI-compatible interface, so the `openai` SDK is required as a transitive dependency.

## API Key Setup

Set your Perplexity API key as an environment variable:

```bash theme={null}
export PERPLEXITY_API_KEY="your_api_key_here"
```

<Card title="Get API Key" icon="key" href="https://www.perplexity.ai/account/api/keys">
  Generate your Perplexity API key from the API portal.
</Card>

## Quick Start

```python theme={null}
from agno.agent import Agent
from agno.models.perplexity import Perplexity

agent = Agent(
    model=Perplexity(id="sonar-pro"),
    markdown=True,
)

agent.print_response("What launched at the latest Perplexity event?")
```

The default model is `sonar`. Pass any [Perplexity model id](/docs/sonar/models) via the `id` parameter — `sonar`, `sonar-pro`, `sonar-reasoning`, `sonar-reasoning-pro`, or `sonar-deep-research`.

## Parameters

The `Perplexity` model accepts the standard OpenAI parameters plus a few Perplexity-specific options:

| Parameter               | Type              | Default                        | Description                                        |
| ----------------------- | ----------------- | ------------------------------ | -------------------------------------------------- |
| `id`                    | `str`             | `"sonar"`                      | Perplexity model id                                |
| `api_key`               | `Optional[str]`   | `None`                         | Falls back to `PERPLEXITY_API_KEY`                 |
| `base_url`              | `str`             | `"https://api.perplexity.ai/"` | API base URL                                       |
| `max_tokens`            | `int`             | `1024`                         | Maximum tokens to generate                         |
| `top_k`                 | `Optional[float]` | `None`                         | Top-K sampling                                     |
| `retries`               | `int`             | `0`                            | Retry attempts before raising `ModelProviderError` |
| `delay_between_retries` | `int`             | `1`                            | Seconds between retries                            |
| `exponential_backoff`   | `bool`            | `False`                        | Double the delay on each retry                     |

All OpenAI-compatible parameters (`temperature`, `top_p`, `frequency_penalty`, etc.) are also supported.

## Structured Output

```python theme={null}
from pydantic import BaseModel
from agno.agent import Agent
from agno.models.perplexity import Perplexity

class Summary(BaseModel):
    headline: str
    bullets: list[str]

agent = Agent(
    model=Perplexity(id="sonar-pro"),
    response_model=Summary,
)

result = agent.run("Summarize this week's top AI research papers.")
print(result.content.headline)
for bullet in result.content.bullets:
    print(f"- {bullet}")
```

## Streaming

```python theme={null}
from agno.agent import Agent
from agno.models.perplexity import Perplexity

agent = Agent(model=Perplexity(id="sonar"))

for chunk in agent.run("Explain quantum entanglement", stream=True):
    print(chunk.content, end="", flush=True)
```

## Notes on Tool Calling

Perplexity models support tool calling through Agno, but Sonar models do not natively expose function-calling in the same first-class way as some other providers. Tool use through `Perplexity` may be less reliable than with `OpenAIChat` or `Claude`. For agent workflows that need rich tool orchestration on top of Perplexity-grounded answers, consider routing through the [Agent API](/docs/agent-api/quickstart) with `web_search` and `fetch_url` tools.

## Links & Resources

<CardGroup>
  <Card title="Agno Perplexity Docs" icon="book" href="https://docs.agno.com/models/providers/native/perplexity/overview">
    Official Agno Perplexity provider documentation.
  </Card>

  <Card title="Agno API Reference" icon="code" href="https://docs.agno.com/reference/models/perplexity">
    Full parameter reference for the `Perplexity` model.
  </Card>

  <Card title="Perplexity Models" icon="sparkles" href="/docs/sonar/models">
    Available Perplexity models and capabilities.
  </Card>

  <Card title="Agno Docs" icon="globe" href="https://docs.agno.com">
    Learn more about agents, teams, and workflows in Agno.
  </Card>
</CardGroup>

## Support

Need help with the integration?

* Browse the [Agno documentation](https://docs.agno.com)
* Review our [FAQ](/docs/resources/faq)


# Perplexity with Google Antigravity
Source: https://docs.perplexity.ai/docs/getting-started/integrations/antigravity

Call Perplexity's Agent API from applications you build or edit inside Google Antigravity.

## Overview

[Google Antigravity](https://antigravity.google) is an agent-first development environment where AI agents plan, write, and iterate on your code across editor, terminal, and browser surfaces. While Antigravity ships with its own built-in agent models, the code your agents author can call any external API — including Perplexity's [Agent API](/docs/agent-api/quickstart) and [Search API](/docs/search/quickstart) — for real-time web research, citations, and grounded answers.

This guide shows how to add the Perplexity Agent API to a project you're building inside Antigravity, using the OpenAI Responses‑compatible interface.

<Info>
  **Scope of this guide.** Antigravity does not currently expose a BYOK or custom-provider hook for swapping its built-in agent model with Perplexity. This guide covers the supported path: calling Perplexity from your **application code** authored inside Antigravity (web apps, CLIs, coding assistants, internal tools, etc.). If Antigravity adds a custom-provider configuration in the future, the same base URL and API key documented here will apply.
</Info>

<Card title="Get a Perplexity API Key" icon="key" href="https://console.perplexity.ai">
  Generate an API key in the Perplexity API Console, then store it in your project as `PERPLEXITY_API_KEY`.
</Card>

***

## When to Use This

The Agent API is a strong fit when your Antigravity-built project needs grounded, web-aware answers without you having to wire up search, scraping, and citation handling yourself. Common patterns:

* **AI features in web or mobile apps** — drop a research or Q\&A surface into a product without standing up your own retrieval stack.
* **Coding assistants and dev tools** — let agents fetch up-to-date library docs, error explanations, or changelogs at runtime.
* **Internal tools and dashboards** — answer questions over the live web (market data, competitive moves, news) with sources attached.
* **CLIs and scripts** — quick research utilities you run from the Antigravity terminal.

***

## Setup

<Steps>
  <Step title="Store Your API Key as an Environment Variable">
    In the Antigravity terminal (or your project's `.env` file), set:

    <Tabs>
      <Tab title="macOS / Linux">
        ```bash theme={null}
        export PERPLEXITY_API_KEY="pplx-..."
        ```
      </Tab>

      <Tab title="Windows (PowerShell)">
        ```powershell theme={null}
        setx PERPLEXITY_API_KEY "pplx-..."
        ```
      </Tab>

      <Tab title=".env file">
        ```bash theme={null}
        PERPLEXITY_API_KEY=pplx-...
        ```
      </Tab>
    </Tabs>

    Never hardcode the key in source files — Antigravity agents may commit or share code they read, so treating the key as an environment variable keeps it out of the repo.
  </Step>

  <Step title="Install an SDK">
    The Agent API is compatible with the [OpenAI Responses API](/docs/agent-api/openai-compatibility), so the OpenAI SDK works directly. The native Perplexity SDK is also available and provides cleaner preset syntax.

    <Tabs>
      <Tab title="TypeScript / Node">
        ```bash theme={null}
        npm install openai
        ```
      </Tab>

      <Tab title="Python">
        ```bash theme={null}
        pip install openai
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Point the Client at Perplexity">
    Set the base URL to `https://api.perplexity.ai/v1` and read the API key from the environment.

    <Tabs>
      <Tab title="TypeScript / Node">
        ```typescript theme={null}
        import OpenAI from "openai";

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

        const response = await client.responses.create({
          input: "Summarize the top three AI infrastructure announcements this week with sources.",
          preset: "pro-search",
        } as any);

        console.log(response.output_text);
        ```
      </Tab>

      <Tab title="Python">
        ```python theme={null}
        import os
        from openai import OpenAI

        client = OpenAI(
            api_key=os.environ.get("PERPLEXITY_API_KEY"),
            base_url="https://api.perplexity.ai/v1",
        )

        response = client.responses.create(
            input="Summarize the top three AI infrastructure announcements this week with sources.",
            extra_body={"preset": "pro-search"},
        )

        print(response.output_text)
        ```
      </Tab>
    </Tabs>

    The OpenAI SDK sends `client.responses.create(...)` to `POST /v1/responses`, which Perplexity accepts as an alias for the canonical `POST /v1/agent` endpoint. No other configuration is required.
  </Step>
</Steps>

***

## Using It from Inside Antigravity

Once the client is wired up, you can prompt Antigravity's agent to use the Perplexity client wherever your app needs grounded answers. A few prompts that work well:

* *"Add a `/research` endpoint that takes a `query` string and returns the Perplexity Agent API response with citations."*
* *"Wrap the Perplexity call in a `researchTopic(topic: string)` helper and call it from the dashboard's news widget."*
* *"Write a CLI subcommand `pplx ask` that streams a Perplexity Agent API response to stdout."*

Because the SDK is the standard OpenAI client, Antigravity's agent will already know the call shape — you mainly need to make sure it uses the right `baseURL` and reads `PERPLEXITY_API_KEY` from the environment.

<Tip>
  If Antigravity's agent generates code that points at `https://api.openai.com/v1` or omits the `baseURL` entirely, ask it to "use the Perplexity base URL `https://api.perplexity.ai/v1`" — it will regenerate the client with the correct endpoint.
</Tip>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Base URL Must Be Exactly https://api.perplexity.ai/v1">
    The OpenAI SDK appends `/responses` to the base URL on its own. Do **not** include `/agent` or `/responses` in the base URL, and do not omit `/v1`.

    | Correct                        | Wrong                                       |
    | ------------------------------ | ------------------------------------------- |
    | `https://api.perplexity.ai/v1` | `https://api.perplexity.ai/v1/agent`        |
    |                                | `https://api.perplexity.ai/v1/responses`    |
    |                                | `https://api.perplexity.ai` (missing `/v1`) |

    Wrong base URLs typically surface as 404s or authentication errors.
  </Accordion>

  <Accordion title="Can I Replace Antigravity's Built-In Agent Model with Perplexity?">
    Not today. Antigravity does not expose a custom-provider or BYOK setting that would let you route its in-editor agent through Perplexity. Use this guide's pattern — calling the Perplexity Agent API from your application code — instead.

    If Antigravity adds custom-provider support in the future, the configuration will be: base URL `https://api.perplexity.ai/v1`, API key from `PERPLEXITY_API_KEY`, and an OpenAI Responses‑compatible transport.
  </Accordion>

  <Accordion title="API Key Isn't Being Picked Up">
    Antigravity terminal sessions inherit environment variables from where Antigravity was launched. If `echo $PERPLEXITY_API_KEY` is empty in the integrated terminal, either set it in your shell profile (`~/.zshrc`, `~/.bashrc`) and relaunch Antigravity, or load it from a project-local `.env` file using something like `dotenv`.
  </Accordion>

  <Accordion title="Choosing a Model vs. a Preset">
    Presets like `pro-search` are pre-configured for common research workloads and are the easiest starting point. If you need a specific third-party model (Claude, GPT, Gemini, etc.), pass `model="anthropic/claude-sonnet-4-6"` (or another value from the [Agent API models list](/docs/agent-api/models)) instead of `preset`.
  </Accordion>
</AccordionGroup>

***

## Links & Resources

<CardGroup>
  <Card title="Agent API Quickstart" icon="rocket" href="/docs/agent-api/quickstart">
    Build with the Agent API using OpenAI-compatible or native SDKs.
  </Card>

  <Card title="OpenAI Compatibility" icon="plug" href="/docs/agent-api/openai-compatibility">
    Full reference for using the OpenAI SDK against Perplexity.
  </Card>

  <Card title="Agent API Presets" icon="sparkles" href="/docs/agent-api/presets">
    Pre-configured setups like `pro-search` for common workloads.
  </Card>

  <Card title="Agent API Models" icon="brain" href="/docs/agent-api/models">
    Full list of third-party and Perplexity models available via the Agent API.
  </Card>

  <Card title="Perplexity SDK" icon="code" href="/docs/sdk/overview">
    Native SDK with cleaner preset syntax and full type safety.
  </Card>

  <Card title="API Console" icon="key" href="https://console.perplexity.ai">
    Generate and manage your Perplexity API keys.
  </Card>
</CardGroup>


# Perplexity with AnythingLLM
Source: https://docs.perplexity.ai/docs/getting-started/integrations/anythingllm

Use Perplexity as the LLM provider in AnythingLLM for grounded, citation-backed chat over your documents and workspaces.

## Overview

[AnythingLLM](https://anythingllm.com) is an all-in-one AI productivity app that turns any document, resource, or piece of content into context for LLM-powered chat. It supports both desktop and self-hosted deployments and works with dozens of LLM providers — including Perplexity as a first-class cloud provider, giving every workspace access to web-grounded answers with citations.

<Info>
  **AnythingLLM** is built and maintained by Mintplex Labs. It supports per-workspace LLM configuration, so you can use Perplexity in one workspace and a different provider in another. Learn more at [anythingllm.com](https://anythingllm.com).
</Info>

## Setup

<Steps>
  <Step title="Get your API key">
    Generate a Perplexity API key from the [API portal](https://www.perplexity.ai/account/api/keys).

    <Card title="Get API Key" icon="key" href="https://www.perplexity.ai/account/api/keys">
      Generate your Perplexity API key.
    </Card>
  </Step>

  <Step title="Open LLM settings">
    In AnythingLLM, go to **Settings → LLM Preference**.
  </Step>

  <Step title="Select Perplexity AI">
    Choose **Perplexity AI** from the provider list and paste your API key.
  </Step>

  <Step title="Choose a model">
    Once your key is entered, the **Chat Model Selection** dropdown automatically populates with available Perplexity models. Pick the model you want (e.g., `sonar-pro`) and save.
  </Step>
</Steps>

## System vs. Workspace Models

AnythingLLM lets you scope LLM choice at two levels:

* **System LLM** — The default provider used for every workspace and agent.
* **Workspace LLM** — Per-workspace override that takes precedence when chatting inside that workspace.

You can mix providers freely. For example, set Anthropic as your system default and use Perplexity in a specific workspace where you need real-time web grounding for research-heavy chats.

To override per workspace: open the workspace, go to **Workspace Settings → Chat Settings → Workspace LLM Provider**, and select **Perplexity AI** with the model you want.

## Available Models

All Perplexity models supported by the API are available to AnythingLLM users — the model dropdown populates dynamically once your API key is validated. Recommended models:

* `sonar` — fast, cost-effective web-grounded chat
* `sonar-pro` — advanced reasoning with broader citation depth
* `sonar-reasoning-pro` — multi-step reasoning with search

See the full list of [Perplexity models and capabilities](/docs/sonar/models).

## Use Cases

Pairing Perplexity with AnythingLLM gives you:

* **Live web answers inside document workflows** — your workspace can answer questions about uploaded PDFs and the open web in the same chat.
* **Citation-grounded retrieval** — Perplexity returns source URLs you can audit alongside your retrieval-augmented context.
* **No-RAG fallback for current events** — when documents don't contain the answer, the model can reach for live web context automatically.

## Agent Configuration

When using AnythingLLM's [AI agents](https://docs.anythingllm.com/agent/setup), you can configure Perplexity as the agent's LLM in the workspace's **Agent Configuration** menu. This is useful for agents that need to chain web research with skills like web browsing, document Q\&A, or external API calls.

## Links & Resources

<CardGroup>
  <Card title="AnythingLLM Perplexity Docs" icon="book" href="https://docs.anythingllm.com/setup/llm-configuration/cloud/perplexity-ai">
    Official AnythingLLM setup guide for Perplexity AI.
  </Card>

  <Card title="AnythingLLM Docs" icon="globe" href="https://docs.anythingllm.com">
    Full AnythingLLM documentation.
  </Card>

  <Card title="Perplexity API Reference" icon="code" href="/api-reference">
    Full Perplexity API reference.
  </Card>

  <Card title="Perplexity Models" icon="sparkles" href="/docs/sonar/models">
    Available Sonar models and capabilities.
  </Card>
</CardGroup>

## Support

Need help with the integration?

* Browse the [AnythingLLM documentation](https://docs.anythingllm.com)
* Review our [FAQ](/docs/resources/faq)


# Perplexity with Claude Code
Source: https://docs.perplexity.ai/docs/getting-started/integrations/claude-code

Use Perplexity inside Claude Code — call the API from project code with the official TypeScript SDK, use the OpenAI-compatible base URL, or wire up the hosted Perplexity Docs MCP for in-editor documentation lookup.

## Overview

[Claude Code](https://docs.claude.com/en/docs/claude-code) is Anthropic's agentic coding tool that lives in your terminal, IDE, and CI. It can edit files, run commands, and call Model Context Protocol (MCP) servers as part of its workflow. This guide covers three integration paths for Perplexity:

<CardGroup>
  <Card title="Official TypeScript SDK" icon="code">
    Let Claude Code write and run application code that calls the Perplexity API directly. **Recommended.**
  </Card>

  <Card title="OpenAI-Compatible SDK" icon="plug">
    Reuse an existing OpenAI client by pointing `baseURL` at `https://api.perplexity.ai/v1`.
  </Card>

  <Card title="Claude Code MCP" icon="book">
    Register the hosted Perplexity Docs MCP with `claude mcp add` so Claude Code can look up Perplexity docs while you work.
  </Card>
</CardGroup>

<Info>
  **Recommended path:** Have Claude Code build features against your project code using the official SDK (or the OpenAI-compatible SDK), and register the Perplexity Docs MCP for in-editor documentation lookup. Claude Code does **not** officially support swapping its underlying model for the Perplexity API — see [Replacing Claude Code's model (not recommended)](#replacing-claude-codes-model-not-recommended).
</Info>

## Prerequisites

* Claude Code installed — see the [Claude Code quickstart](https://docs.claude.com/en/docs/claude-code/quickstart)
* Node.js 18+ for the TypeScript examples
* A Perplexity API key

<Card title="Get API Key" icon="key" href="https://console.perplexity.ai">
  Generate a key from the Perplexity API Portal.
</Card>

## API key handling

Never hardcode your API key in source files or commit it to a repository. Store it in an environment variable and read it at runtime:

<Tabs>
  <Tab title="macOS/Linux">
    ```bash theme={null}
    export PERPLEXITY_API_KEY="your_api_key_here"
    ```
  </Tab>

  <Tab title="Windows">
    ```powershell theme={null}
    setx PERPLEXITY_API_KEY "your_api_key_here"
    ```
  </Tab>

  <Tab title=".env (project-local)">
    Create a `.env` file in your project root and add it to `.gitignore`:

    ```bash theme={null}
    # .env
    PERPLEXITY_API_KEY=your_api_key_here
    ```

    Load it at startup (for example with [`dotenv`](https://www.npmjs.com/package/dotenv)):

    ```typescript theme={null}
    import "dotenv/config";
    ```
  </Tab>
</Tabs>

<Warning>
  Treat `PERPLEXITY_API_KEY` like a password. Don't paste it into prompts, share it with Claude Code, or commit it to source control. If a key is exposed, [rotate it](https://console.perplexity.ai) immediately.
</Warning>

***

## Path 1: Official TypeScript SDK (recommended)

Have Claude Code scaffold and edit code that calls the Perplexity API using the official SDK. This is the most reliable path and gives you full type safety, preset support, and access to every API feature.

### Install

```bash theme={null}
npm install @perplexity-ai/perplexity_ai
```

<Tip>
  `pnpm` and `yarn` work the same way: `pnpm add @perplexity-ai/perplexity_ai` / `yarn add @perplexity-ai/perplexity_ai`.
</Tip>

### Agent API with `pro-search`

The Agent API is the recommended surface for most applications. Use the `pro-search` preset for web-grounded responses with sensible defaults:

```typescript theme={null}
import Perplexity from "@perplexity-ai/perplexity_ai";

const client = new Perplexity(); // reads PERPLEXITY_API_KEY from the environment

const response = await client.responses.create({
  preset: "pro-search",
  input: "Summarize the latest changes to the Perplexity Agent API.",
});

console.log(`Model used: ${response.model}`);
console.log(response.output_text);
```

<Accordion title="Python equivalent">
  ```python theme={null}
  from perplexity import Perplexity

  client = Perplexity()  # reads PERPLEXITY_API_KEY from the environment

  response = client.responses.create(
      preset="pro-search",
      input="Summarize the latest changes to the Perplexity Agent API.",
  )

  print(f"Model used: {response.model}")
  print(response.output_text)
  ```
</Accordion>

### Add web search

Enable the `web_search` tool for explicit control over when search is used:

```typescript theme={null}
import Perplexity from "@perplexity-ai/perplexity_ai";

const client = new Perplexity();

const response = await client.responses.create({
  model: "openai/gpt-5.4",
  input: "What are the latest developments in AI inference hardware?",
  tools: [{ type: "web_search" }],
  instructions:
    "You have access to a web_search tool. Use it for questions about current events, news, or recent developments.",
});

if (response.status === "completed") {
  console.log(response.output_text);
}
```

<Tip>
  Ask Claude Code to scaffold these calls for you — for example, *"Add a `summarize.ts` script that uses `@perplexity-ai/perplexity_ai` with the `pro-search` preset and reads `PERPLEXITY_API_KEY` from the environment."* Claude Code will edit the file, install the package, and run it.
</Tip>

For more presets, tools, and configuration options see the [Agent API quickstart](/docs/agent-api/quickstart) and the [SDK overview](/docs/sdk/overview).

***

## Path 2: OpenAI-compatible SDK

If your project already uses an OpenAI client, you can reuse it by pointing the `baseURL` at `https://api.perplexity.ai/v1`. Perplexity accepts `POST /v1/responses` as an alias for the Agent API.

### Install

```bash theme={null}
npm install openai
```

### Use it

```typescript theme={null}
import OpenAI from "openai";

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

const response = await client.responses.create({
  model: "openai/gpt-5.4",
  input: "Explain the key differences between REST and GraphQL APIs.",
});

console.log(response.output_text);
```

<Accordion title="Python equivalent">
  ```python theme={null}
  import os
  from openai import OpenAI

  client = OpenAI(
      api_key=os.environ.get("PERPLEXITY_API_KEY"),
      base_url="https://api.perplexity.ai/v1",
  )

  response = client.responses.create(
      model="openai/gpt-5.4",
      input="Explain the key differences between REST and GraphQL APIs.",
  )

  print(response.output_text)
  ```
</Accordion>

<Info>
  Use `baseURL` (TypeScript) or `base_url` (Python) — both must include the `/v1` suffix. See the [OpenAI Compatibility guide](/docs/agent-api/openai-compatibility) for the full list of supported parameters and which Perplexity features are available through this path.
</Info>

***

## Path 3: Claude Code MCP for docs lookup

Claude Code supports the Model Context Protocol (MCP). The hosted **Perplexity Docs MCP** at `https://docs.perplexity.ai/mcp` lets Claude Code search and read Perplexity's documentation directly — useful for grounding code suggestions in canonical docs without context-switching to a browser.

### Add the server

Claude Code can register a remote MCP server over HTTP using the `claude mcp add` command with the `--transport http` flag:

<Tabs>
  <Tab title="Project scope">
    Add the server only for the current project (writes to `.mcp.json` in your repo root):

    ```bash theme={null}
    claude mcp add --transport http --scope project perplexity-docs https://docs.perplexity.ai/mcp
    ```
  </Tab>

  <Tab title="User scope">
    Add the server for all projects on this machine:

    ```bash theme={null}
    claude mcp add --transport http --scope user perplexity-docs https://docs.perplexity.ai/mcp
    ```
  </Tab>
</Tabs>

<Tip>
  If you'd rather not run the CLI, you can also edit the project's `.mcp.json` directly:

  ```json theme={null}
  {
    "mcpServers": {
      "perplexity-docs": {
        "type": "http",
        "url": "https://docs.perplexity.ai/mcp"
      }
    }
  }
  ```

  Claude Code reads `.mcp.json` at the repo root for project-scoped servers. Refer to the [Claude Code MCP documentation](https://docs.claude.com/en/docs/claude-code/mcp) for the canonical schema and any newer transport options.
</Tip>

### Verify and use

<Steps>
  <Step title="Confirm the server is registered">
    Run `claude mcp list` and check that `perplexity-docs` appears in the output.
  </Step>

  <Step title="Restart Claude Code">
    Quit and relaunch Claude Code (or run `/mcp` from inside a session) so the new server is loaded.
  </Step>

  <Step title="Use it from a prompt">
    Ask Claude Code something like *"Using the Perplexity docs MCP, show me how to enable `pro-search` in the Agent API."* Claude Code will call the MCP server and ground its answer in current documentation.
  </Step>
</Steps>

<Info>
  The Docs MCP is read-only and does not require an API key — it only serves Perplexity documentation. To give Claude Code access to Perplexity **search and reasoning** tools (not just docs), install the [Perplexity MCP Server](/docs/getting-started/integrations/mcp-server), which uses `@perplexity-ai/mcp-server` and requires `PERPLEXITY_API_KEY`.
</Info>

***

## Replacing Claude Code's model (not recommended)

Claude Code is designed to run on Anthropic's Claude models, and the agent's tool use, prompting, and editing behavior are tuned to those models. Pointing the Claude Code CLI at the Perplexity API as an alternative model provider is **not an officially supported configuration**.

Instead:

* **Use Perplexity from your project code** (Path 1 or Path 2). Claude Code will happily write, edit, and run code that calls Perplexity for web-grounded answers, research, and search.
* **Add the Perplexity Docs MCP** (Path 3) so Claude Code can look up Perplexity documentation in-session.

This combination gives you Claude Code's editing and orchestration strengths alongside Perplexity's search-grounded responses, without depending on undocumented model-override behavior.

***

## Next steps

<CardGroup>
  <Card title="Agent API quickstart" icon="rocket" href="/docs/agent-api/quickstart">
    Presets, tools, and the full Agent API surface used by the examples above.
  </Card>

  <Card title="Perplexity SDK overview" icon="code-circle" href="/docs/sdk/overview">
    Install, configure, and use the official Python and TypeScript SDKs.
  </Card>

  <Card title="OpenAI compatibility" icon="plug" href="/docs/agent-api/openai-compatibility">
    Drop-in compatibility details, supported parameters, and migration tips.
  </Card>

  <Card title="Perplexity MCP Server" icon="server" href="/docs/getting-started/integrations/mcp-server">
    Add Perplexity search, ask, research, and reason tools to Claude Code and other MCP clients.
  </Card>
</CardGroup>

<Info>
  Need help? Join the [Perplexity developer community](https://community.perplexity.ai) for support and discussion.
</Info>


# Perplexity with Composio
Source: https://docs.perplexity.ai/docs/getting-started/integrations/composio

Expose Perplexity's Chat Completions, Agent, Search, and Embeddings APIs as MCP tools or direct API actions for any AI agent framework via Composio.

## Overview

[Composio](https://composio.dev) is a universal tool gateway for AI agents. The Composio Perplexity toolkit exposes the full Perplexity API — Chat Completions, Agent, Search, Embeddings, and async variants — as tools that any agent framework can call through a single MCP URL or direct API integration.

<Info>
  **Composio** handles authentication, secure credential storage, OAuth flows, and tool routing for 1000+ apps. Learn more at [composio.dev](https://composio.dev).
</Info>

The toolkit ships these Perplexity actions:

* **Execute Agent** — `POST /v1/agent` (Agent API responses)
* **Create Chat Completion** — `POST /v1/sonar` (Sonar chat completions)
* **Create Async Chat Completion** — `POST /v1/async/sonar`
* **Get / List Async Chat Completions** — `GET /v1/async/sonar/{id}`, `GET /v1/async/sonar`
* **Perplexity Search (Raw Results)** — `POST /search`
* **Create Embeddings** — `POST /v1/embeddings`
* **Create Contextualized Embeddings** — `POST /v1/contextualizedembeddings`
* **List Models** — `GET /v1/models`

## Prerequisites

* A [Composio account](https://composio.dev) and API key
* A Perplexity API key

<Card title="Get API Key" icon="key" href="https://www.perplexity.ai/account/api/keys">
  Generate your Perplexity API key from the API portal.
</Card>

## Installation

```bash theme={null}
pip install composio
```

For agent-framework integrations, install your framework SDK alongside Composio (Composio supports Claude Agent SDK, OpenAI Agents SDK, LangChain, LlamaIndex, Mastra, Pydantic AI, AutoGen, CrewAI, Google ADK, and more).

## Quick Start: Tool Router (MCP)

The Tool Router exposes Perplexity as an MCP server your agent can connect to. This works with any MCP-compatible client (Claude Code, Cursor, OpenCode, etc.).

```python theme={null}
from composio import Composio

composio = Composio(api_key="your-composio-api-key")
session = composio.create(user_id="your-user-id")
url = session.mcp.url

print(f"MCP URL: {url}")
```

Wire that URL into your agent's MCP configuration:

```python theme={null}
import asyncio
from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

options = ClaudeAgentOptions(
    permission_mode="bypassPermissions",
    mcp_servers={
        "tool_router": {
            "type": "http",
            "url": url,
            "headers": {"x-api-key": "your-composio-api-key"},
        }
    },
    system_prompt="You are a helpful assistant with access to Perplexity tools.",
    max_turns=10,
)

async def main():
    async with ClaudeSDKClient(options=options) as client:
        await client.query("Summarize the latest AI research papers")
        async for message in client.receive_response():
            if hasattr(message, "content"):
                for block in message.content:
                    if hasattr(block, "text"):
                        print(block.text)

asyncio.run(main())
```

## Quick Start: Direct API Actions

You can also execute Perplexity actions directly from Composio without an MCP layer:

```python theme={null}
from composio import Composio

composio = Composio(api_key="your-composio-api-key")

# Connect the user's Perplexity account once
composio.toolkits.authorize(
    user_id="your-user-id",
    toolkit="perplexityai",
)

# Run a Sonar chat completion
result = composio.actions.execute(
    user_id="your-user-id",
    action="PERPLEXITYAI_CREATE_CHAT_COMPLETION",
    params={
        "model": "sonar-pro",
        "messages": [
            {"role": "user", "content": "What are the latest fusion-energy headlines?"}
        ],
    },
)

print(result["data"]["choices"][0]["message"]["content"])
```

## Supported Agent Frameworks

Composio's Perplexity toolkit works with every agent framework Composio supports, including:

* ChatGPT, OpenAI Agents SDK, Codex
* Claude Agents SDK, Claude Code
* Cursor, VS Code, OpenCode
* Google ADK, LangChain, AI SDK, Mastra AI
* LlamaIndex, CrewAI, Pydantic AI, AutoGen

Each framework has a dedicated setup guide in the [Composio Perplexity toolkit](https://composio.dev/toolkits/perplexityai) page.

## Authentication

Composio stores your Perplexity API key securely and injects it into every request. You provide your key once during the toolkit authorization flow — either through the Composio dashboard or programmatically via `composio.toolkits.authorize(...)`. Composio handles token refresh, scope management, and request signing on every call.

## Links & Resources

<CardGroup>
  <Card title="Composio Perplexity Toolkit" icon="toolbox" href="https://composio.dev/toolkits/perplexityai">
    Full toolkit documentation with framework-specific guides.
  </Card>

  <Card title="Composio Docs" icon="book" href="https://docs.composio.dev">
    Composio platform documentation.
  </Card>

  <Card title="Perplexity API Reference" icon="code" href="/api-reference">
    Full Perplexity API reference.
  </Card>

  <Card title="Perplexity Models" icon="sparkles" href="/docs/sonar/models">
    Available Perplexity models.
  </Card>
</CardGroup>

## Support

Need help with the integration?

* Browse the [Composio documentation](https://docs.composio.dev)
* Review our [FAQ](/docs/resources/faq)


# Perplexity with Cursor
Source: https://docs.perplexity.ai/docs/getting-started/integrations/cursor

Use Perplexity inside Cursor — call the API from project code with the official TypeScript SDK, use the OpenAI-compatible base URL, or wire up the hosted Perplexity Docs MCP for in-editor documentation lookup.

## Overview

[Cursor](https://cursor.com) is an AI-first code editor that can call any HTTP API from your project code and supports the Model Context Protocol (MCP) for in-editor tools. This guide covers three integration paths for Perplexity:

<CardGroup>
  <Card title="Official TypeScript SDK" icon="code">
    Call the Perplexity API directly from your project code while you build in Cursor. **Recommended.**
  </Card>

  <Card title="OpenAI-Compatible SDK" icon="plug">
    Reuse an existing OpenAI client by pointing `baseURL` at `https://api.perplexity.ai/v1`.
  </Card>

  <Card title="Cursor MCP" icon="book">
    Configure the hosted Perplexity Docs MCP in `.cursor/mcp.json` so Cursor can look up Perplexity docs while you code.
  </Card>
</CardGroup>

<Info>
  **Recommended path:** Use the official SDK (or the OpenAI-compatible SDK) from your application code, and add the Perplexity Docs MCP to Cursor for in-editor documentation lookup. Cursor's "custom OpenAI-compatible model" override pointed at Perplexity is **experimental** and tends to be less reliable than code-level integration or MCP — see [Custom Model Override (Experimental)](#custom-model-override-experimental).
</Info>

## Prerequisites

* Cursor installed ([cursor.com/download](https://cursor.com/download))
* Node.js 18+ for the TypeScript examples
* A Perplexity API key

<Card title="Get API Key" icon="key" href="https://console.perplexity.ai">
  Generate a key from the Perplexity API Portal.
</Card>

## API Key Handling

Never hardcode your API key in source files or commit it to a repository. Store it in an environment variable and read it at runtime:

<Tabs>
  <Tab title="macOS/Linux">
    ```bash theme={null}
    export PERPLEXITY_API_KEY="your_api_key_here"
    ```
  </Tab>

  <Tab title="Windows">
    ```powershell theme={null}
    setx PERPLEXITY_API_KEY "your_api_key_here"
    ```
  </Tab>

  <Tab title=".env (project-local)">
    Create a `.env` file in your project root and add it to `.gitignore`:

    ```bash theme={null}
    # .env
    PERPLEXITY_API_KEY=your_api_key_here
    ```

    Load it at startup (for example with [`dotenv`](https://www.npmjs.com/package/dotenv)):

    ```typescript theme={null}
    import "dotenv/config";
    ```
  </Tab>
</Tabs>

<Warning>
  Treat `PERPLEXITY_API_KEY` like a password. Don't paste it into chat, prompts, or shared files. If a key is exposed, [rotate it](https://console.perplexity.ai) immediately.
</Warning>

***

## Path 1: Official TypeScript SDK (Recommended)

Build your application in Cursor and call the Perplexity API from your code using the official SDK. This is the most reliable path and gives you full type safety, preset support, and access to every API feature.

### Install

```bash theme={null}
npm install @perplexity-ai/perplexity_ai
```

<Tip>
  `pnpm` and `yarn` work the same way: `pnpm add @perplexity-ai/perplexity_ai` / `yarn add @perplexity-ai/perplexity_ai`.
</Tip>

### Agent API with `pro-search`

The Agent API is the recommended surface for most applications. Use the `pro-search` preset for web-grounded responses with sensible defaults:

```typescript theme={null}
import Perplexity from "@perplexity-ai/perplexity_ai";

const client = new Perplexity(); // reads PERPLEXITY_API_KEY from the environment

const response = await client.responses.create({
  preset: "pro-search",
  input: "Summarize the latest changes to the Perplexity Agent API.",
});

console.log(`Model used: ${response.model}`);
console.log(response.output_text);
```

<Accordion title="Python equivalent">
  ```python theme={null}
  from perplexity import Perplexity

  client = Perplexity()  # reads PERPLEXITY_API_KEY from the environment

  response = client.responses.create(
      preset="pro-search",
      input="Summarize the latest changes to the Perplexity Agent API.",
  )

  print(f"Model used: {response.model}")
  print(response.output_text)
  ```
</Accordion>

### Add Web Search

Enable the `web_search` tool for explicit control over when search is used:

```typescript theme={null}
import Perplexity from "@perplexity-ai/perplexity_ai";

const client = new Perplexity();

const response = await client.responses.create({
  model: "openai/gpt-5.4",
  input: "What are the latest developments in AI inference hardware?",
  tools: [{ type: "web_search" }],
  instructions:
    "You have access to a web_search tool. Use it for questions about current events, news, or recent developments.",
});

if (response.status === "completed") {
  console.log(response.output_text);
}
```

<Tip>
  Cursor's AI chat can scaffold and edit these snippets for you. Open the chat with `Cmd+L` / `Ctrl+L`, paste in your goal, and ask Cursor to "use `@perplexity-ai/perplexity_ai` with the `pro-search` preset."
</Tip>

For more presets, tools, and configuration options see the [Agent API quickstart](/docs/agent-api/quickstart) and the [SDK overview](/docs/sdk/overview).

***

## Path 2: OpenAI-Compatible SDK

If you already have an OpenAI client in your project, you can reuse it by pointing the `baseURL` at `https://api.perplexity.ai/v1`. Perplexity accepts `POST /v1/responses` as an alias for the Agent API.

### Install

```bash theme={null}
npm install openai
```

### Use It

```typescript theme={null}
import OpenAI from "openai";

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

const response = await client.responses.create({
  model: "openai/gpt-5.4",
  input: "Explain the key differences between REST and GraphQL APIs.",
});

console.log(response.output_text);
```

<Accordion title="Python equivalent">
  ```python theme={null}
  import os
  from openai import OpenAI

  client = OpenAI(
      api_key=os.environ.get("PERPLEXITY_API_KEY"),
      base_url="https://api.perplexity.ai/v1",
  )

  response = client.responses.create(
      model="openai/gpt-5.4",
      input="Explain the key differences between REST and GraphQL APIs.",
  )

  print(response.output_text)
  ```
</Accordion>

<Info>
  Use `baseURL` (TypeScript) or `base_url` (Python) — both must include the `/v1` suffix. See the [OpenAI Compatibility guide](/docs/agent-api/openai-compatibility) for the full list of supported parameters and which Perplexity features are available through this path.
</Info>

***

## Path 3: Cursor MCP for Docs Lookup

Cursor supports the Model Context Protocol (MCP). The hosted **Perplexity Docs MCP** at `https://docs.perplexity.ai/mcp` lets Cursor search and read Perplexity's documentation directly from chat — useful for grounding code suggestions in canonical docs without context-switching to a browser.

### Project-Scoped Configuration

Add a `.cursor/mcp.json` file at the root of your project. This makes the server available only for that project:

```json theme={null}
{
  "mcpServers": {
    "perplexity-docs": {
      "url": "https://docs.perplexity.ai/mcp"
    }
  }
}
```

### Global Configuration

To make the server available across all projects, add the same entry to `~/.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "perplexity-docs": {
      "url": "https://docs.perplexity.ai/mcp"
    }
  }
}
```

<Steps>
  <Step title="Add the Configuration">
    Save the JSON above to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global).
  </Step>

  <Step title="Reload Cursor">
    Open **Cursor → Settings → MCP** and confirm `perplexity-docs` appears with a green/ready status. Restart Cursor if needed.
  </Step>

  <Step title="Use It from Chat">
    In Cursor chat, ask questions like *"Using the Perplexity docs MCP, show me how to enable `pro-search` in the Agent API."* Cursor will call the MCP server and ground its answer in current documentation.
  </Step>
</Steps>

<Tip>
  The Docs MCP is read-only and does not require an API key — it only serves Perplexity documentation. To give Cursor access to Perplexity **search and reasoning** tools (not just docs), install the [Perplexity MCP Server](/docs/getting-started/integrations/mcp-server), which uses `@perplexity-ai/mcp-server` and requires `PERPLEXITY_API_KEY`.
</Tip>

***

## Custom Model Override (Experimental)

Cursor lets you point its built-in model picker at an OpenAI-compatible base URL. While it is possible to set this to `https://api.perplexity.ai/v1` and use a Perplexity model name, this path has limitations:

* The Agent API surface (presets, structured tool calls, finance/people search) is not fully exercised by Cursor's internal prompting.
* Cursor's autocomplete and edit features are tuned to specific model behaviors and may not work well with substituted models.
* Streaming, tool use, and error handling can behave differently than in a code-level integration.

For these reasons, **we recommend calling Perplexity from your project code** (Path 1 or Path 2) and using the **Perplexity Docs MCP** (Path 3) for in-editor docs lookup. Reach for the custom model override only when you specifically want Cursor's chat UI to talk to a Perplexity model and are comfortable with the trade-offs.

***

## Next Steps

<CardGroup>
  <Card title="Agent API Quickstart" icon="rocket" href="/docs/agent-api/quickstart">
    Presets, tools, and the full Agent API surface used by the examples above.
  </Card>

  <Card title="Perplexity SDK Overview" icon="code-circle" href="/docs/sdk/overview">
    Install, configure, and use the official Python and TypeScript SDKs.
  </Card>

  <Card title="OpenAI Compatibility" icon="plug" href="/docs/agent-api/openai-compatibility">
    Drop-in compatibility details, supported parameters, and migration tips.
  </Card>

  <Card title="Perplexity MCP Server" icon="server" href="/docs/getting-started/integrations/mcp-server">
    Add Perplexity search, ask, research, and reason tools to Cursor and other MCP clients.
  </Card>
</CardGroup>

<Info>
  Need help? Join the [Perplexity developer community](https://community.perplexity.ai) for support and discussion.
</Info>


# Perplexity with Haystack
Source: https://docs.perplexity.ai/docs/getting-started/integrations/haystack

Use Perplexity's Agent API, Embeddings API, and grounded Search API in Haystack pipelines.

## Overview

The `perplexity-haystack` package provides Haystack components for Perplexity's Agent API, Embeddings API, and grounded Search API, so you can build retrieval-augmented and agentic pipelines that combine chat, embeddings, and live web search.

<Info>
  **Haystack** is an open-source Python framework by [deepset](https://deepset.ai) for building production-ready LLM applications, including RAG pipelines and agentic workflows. Learn more at [haystack.deepset.ai](https://haystack.deepset.ai).
</Info>

The integration includes:

* **PerplexityChatGenerator** — Chat completions through the [Agent API](/docs/agent-api/quickstart) (OpenAI-compatible).
* **PerplexityTextEmbedder** and **PerplexityDocumentEmbedder** — Embeddings through the [Embeddings API](/docs/embeddings/quickstart).
* **PerplexityWebSearch** — Ranked, grounded web results through the [Search API](/docs/search/quickstart).

## Installation

<Tabs>
  <Tab title="pip">
    ```bash theme={null}
    pip install perplexity-haystack
    ```
  </Tab>

  <Tab title="uv">
    ```bash theme={null}
    uv add perplexity-haystack
    ```
  </Tab>
</Tabs>

## API Key Setup

Set your Perplexity API key as an environment variable:

```python theme={null}
import os

os.environ["PERPLEXITY_API_KEY"] = "your_api_key_here"
```

<Card title="Get API Key" icon="key" href="https://console.perplexity.ai">
  Generate your API key from the Perplexity dashboard.
</Card>

## Quick Start: Chat (Agent API)

`PerplexityChatGenerator` is powered by the Perplexity Agent API and defaults to `openai/gpt-5.4`.

```python theme={null}
import os

from haystack.dataclasses import ChatMessage
from haystack_integrations.components.generators.perplexity import PerplexityChatGenerator

os.environ["PERPLEXITY_API_KEY"] = "your_api_key_here"

client = PerplexityChatGenerator()
response = client.run(
    messages=[ChatMessage.from_user("What are Agentic Pipelines? Be brief.")]
)

print(response["replies"])
```

### Selecting a Model

You can pick any of the supported Agent API models via the `model` parameter:

```python theme={null}
client = PerplexityChatGenerator(model="anthropic/claude-sonnet-4-6")
```

Supported models include `openai/gpt-5.4` (default), `openai/gpt-5.5`, `openai/gpt-4o`, `anthropic/claude-sonnet-4-6`, `xai/grok-4-1`, and `google/gemini-3-flash-preview`. See the [Agent API models page](/docs/agent-api/models) for the full list.

## Quick Start: Embeddings

Embed a single query with `PerplexityTextEmbedder`:

```python theme={null}
import os

from haystack_integrations.components.embedders.perplexity import PerplexityTextEmbedder

os.environ["PERPLEXITY_API_KEY"] = "your_api_key_here"

embedder = PerplexityTextEmbedder()
response = embedder.run(text="What is Haystack by deepset?")

print(response["embedding"])
```

Embed a list of documents with `PerplexityDocumentEmbedder`:

```python theme={null}
from haystack import Document
from haystack_integrations.components.embedders.perplexity import PerplexityDocumentEmbedder

docs = [Document(content="What is Haystack by deepset?")]
result = PerplexityDocumentEmbedder().run(documents=docs)

print(result["documents"][0].embedding)
```

Both embedders default to `pplx-embed-v1-0.6b`. The larger `pplx-embed-v1-4b` model is also available — set it via the `model` parameter.

## Quick Start: Web Search (Search API)

Use `PerplexityWebSearch` to get ranked, grounded web results inside a Haystack pipeline:

```python theme={null}
import os

from haystack.utils import Secret
from haystack_integrations.components.websearch.perplexity import PerplexityWebSearch

os.environ["PERPLEXITY_API_KEY"] = "your_api_key_here"

websearch = PerplexityWebSearch(
    api_key=Secret.from_env_var("PERPLEXITY_API_KEY"),
    top_k=5,
)
result = websearch.run(query="What is Haystack by deepset?")

documents = result["documents"]
links = result["links"]

print(documents)
print(links)
```

## Links & Resources

<CardGroup>
  <Card title="Haystack Integrations" icon="book" href="https://haystack.deepset.ai/integrations/perplexity">
    Catalog entry on haystack.deepset.ai
  </Card>

  <Card title="Source Code" icon="github" href="https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/perplexity">
    perplexity-haystack on GitHub
  </Card>

  <Card title="PyPI Package" icon="brand-python" href="https://pypi.org/project/perplexity-haystack">
    View on PyPI
  </Card>

  <Card title="Haystack Docs" icon="book-open" href="https://docs.haystack.deepset.ai">
    Full Haystack documentation
  </Card>
</CardGroup>

## Support

Need help with the integration?

* Check the [Haystack documentation](https://docs.haystack.deepset.ai)
* Open an issue at [haystack-core-integrations](https://github.com/deepset-ai/haystack-core-integrations/issues)
* Review our [FAQ](/docs/resources/faq)


# Perplexity with LangChain
Source: https://docs.perplexity.ai/docs/getting-started/integrations/langchain

Use Perplexity's chat models and search tool in your LangChain applications (Python and JavaScript).

## Overview

LangChain provides first-class integrations for Perplexity in both Python (`langchain-perplexity`) and JavaScript/TypeScript (`@langchain/community`). Both packages let you build LLM applications with real-time web search, citations, and Perplexity's Pro Search reasoning.

<Info>
  **LangChain** is a popular Python framework for building applications powered by large language models. It provides composable components for chains, agents, and retrieval-augmented generation (RAG). Learn more at [langchain.com](https://www.langchain.com).
</Info>

The integration includes:

* **ChatPerplexity** - Chat model with Pro Search, streaming, and search controls
* **PerplexitySearchRetriever** - Retriever for RAG applications
* **PerplexitySearchResults** - Tool for LangChain agents

## Installation

<Tabs>
  <Tab title="pip">
    ```bash theme={null}
    pip install langchain-perplexity
    ```
  </Tab>

  <Tab title="uv">
    ```bash theme={null}
    uv add langchain-perplexity
    ```
  </Tab>
</Tabs>

## API Key Setup

Set your Perplexity API key as an environment variable:

```python theme={null}
import os

os.environ["PERPLEXITY_API_KEY"] = "your_api_key_here"
```

<Card title="Get API Key" icon="key" href="https://console.perplexity.ai">
  Generate your API key from the Perplexity dashboard.
</Card>

## Quick Start: Chat Models

Use `ChatPerplexity` for conversational AI with web search:

```python theme={null}
from langchain_perplexity import ChatPerplexity

chat = ChatPerplexity(model="sonar")

response = chat.invoke("What breakthroughs in fusion energy have been announced this year?")
print(response.content)
```

### Pro Search

Enable multi-step reasoning with Pro Search:

```python theme={null}
from langchain_perplexity import ChatPerplexity, WebSearchOptions

chat = ChatPerplexity(
    model="sonar-pro",
    web_search_options=WebSearchOptions(search_type="pro")
)

response = chat.invoke("How does the electoral college work?")

# Access reasoning steps
if reasoning := response.additional_kwargs.get("reasoning_steps"):
    for step in reasoning:
        print(f"Thought: {step['thought']}")
```

### Search Controls

Filter search results by domain, recency, or date:

```python theme={null}
chat = ChatPerplexity(
    model="sonar",
    search_domain_filter=["wikipedia.org", "nature.com"],
    search_recency_filter="month",
    return_images=True
)

response = chat.invoke("Solar system planets")

# Access citations and images
print("Citations:", response.additional_kwargs.get("citations", []))
print("Images:", response.additional_kwargs.get("images", []))
```

### Streaming

```python theme={null}
for chunk in chat.stream("Explain quantum computing"):
    print(chunk.content, end="", flush=True)
```

## Quick Start: Retriever

Use `PerplexitySearchRetriever` for RAG applications:

```python theme={null}
from langchain_perplexity import PerplexitySearchRetriever

retriever = PerplexitySearchRetriever(k=5)

docs = retriever.invoke("What is nuclear fusion?")

for doc in docs:
    print(f"Title: {doc.metadata['title']}")
    print(f"URL: {doc.metadata['url']}")
    print(f"Content: {doc.page_content[:200]}...")
    print("---")
```

### RAG Chain Example

```python theme={null}
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.runnables import RunnablePassthrough
from langchain_core.output_parsers import StrOutputParser
from langchain_perplexity import ChatPerplexity, PerplexitySearchRetriever

llm = ChatPerplexity(model="sonar")
retriever = PerplexitySearchRetriever(k=3)

template = """Answer based on the following context:
{context}

Question: {question}
"""
prompt = ChatPromptTemplate.from_template(template)

def format_docs(docs):
    return "\n\n".join(doc.page_content for doc in docs)

rag_chain = (
    {"context": retriever | format_docs, "question": RunnablePassthrough()}
    | prompt
    | llm
    | StrOutputParser()
)

answer = rag_chain.invoke("What is the current status of ITER?")
print(answer)
```

## Quick Start: Tool

Use `PerplexitySearchResults` with LangChain agents:

```python theme={null}
from langchain_perplexity import PerplexitySearchResults

tool = PerplexitySearchResults()

results = tool.invoke("LangChain framework")

for result in results:
    print(f"Title: {result['title']}")
    print(f"URL: {result['url']}")
    print(f"Snippet: {result['snippet'][:100]}...")
    print("---")
```

### Agent Example

```python theme={null}
from langchain.chat_models import init_chat_model
from langchain_perplexity import PerplexitySearchResults
from langgraph.prebuilt import create_react_agent

model = init_chat_model(model="gpt-4o", model_provider="openai")
search_tool = PerplexitySearchResults()

agent = create_react_agent(model, [search_tool])

for step in agent.stream(
    {"messages": [("user", "What are the latest LangChain releases?")]},
    stream_mode="values",
):
    step["messages"][-1].pretty_print()
```

## JavaScript / TypeScript

The JavaScript integration ships in the [`@langchain/community`](https://www.npmjs.com/package/@langchain/community) package as `ChatPerplexity`. It is an OpenAI-compatible chat model that talks to `https://api.perplexity.ai`.

### Installation

<Tabs>
  <Tab title="npm">
    ```bash theme={null}
    npm install @langchain/community @langchain/core
    ```
  </Tab>

  <Tab title="pnpm">
    ```bash theme={null}
    pnpm add @langchain/community @langchain/core
    ```
  </Tab>

  <Tab title="yarn">
    ```bash theme={null}
    yarn add @langchain/community @langchain/core
    ```
  </Tab>
</Tabs>

### API Key Setup

Set `PERPLEXITY_API_KEY` in your environment, or pass `apiKey` directly to the constructor:

```bash theme={null}
export PERPLEXITY_API_KEY="your_api_key_here"
```

### Quick Start

```ts theme={null}
import { ChatPerplexity } from "@langchain/community/chat_models/perplexity";

const llm = new ChatPerplexity({
  model: "sonar",
  temperature: 0,
  maxRetries: 2,
});

const aiMsg = await llm.invoke([
  {
    role: "system",
    content: "You are a helpful assistant that answers with web-grounded citations.",
  },
  { role: "user", content: "What breakthroughs in fusion energy were announced this year?" },
]);

console.log(aiMsg.content);

// Citations and other metadata
console.log(aiMsg.additional_kwargs.citations);
```

### Streaming

```ts theme={null}
const stream = await llm.stream("Explain quantum computing in two paragraphs.");
for await (const chunk of stream) {
  process.stdout.write(chunk.content as string);
}
```

### Chaining with Prompts

```ts theme={null}
import { ChatPromptTemplate } from "@langchain/core/prompts";

const prompt = ChatPromptTemplate.fromMessages([
  ["system", "You translate English into {language}."],
  ["human", "{input}"],
]);

const chain = prompt.pipe(llm);
const res = await chain.invoke({
  language: "French",
  input: "I love programming.",
});
console.log(res.content);
```

See the [LangChain JS Perplexity docs](https://docs.langchain.com/oss/javascript/integrations/chat/perplexity) for the full API surface.

## Available Models

The integration supports all Perplexity models:

| Model                 | Description                               |
| --------------------- | ----------------------------------------- |
| `sonar`               | Fast, cost-effective search model         |
| `sonar-pro`           | Advanced model with Pro Search support    |
| `sonar-reasoning-pro` | Advanced reasoning capabilities           |
| `sonar-deep-research` | Deep research with comprehensive analysis |

See the full list of models on our [models page](/docs/sonar/models).

## Links & Resources

<CardGroup>
  <Card title="LangChain Docs" icon="book" href="https://docs.langchain.com/oss/python/integrations/providers/perplexity">
    Full LangChain integration documentation
  </Card>

  <Card title="ChatPerplexity" icon="message" href="https://docs.langchain.com/oss/python/integrations/chat/perplexity">
    Detailed chat model documentation
  </Card>

  <Card title="Retriever Docs" icon="search" href="https://docs.langchain.com/oss/python/integrations/retrievers/perplexity_search">
    PerplexitySearchRetriever documentation
  </Card>

  <Card title="Tool Docs" icon="wrench" href="https://docs.langchain.com/oss/python/integrations/providers/perplexity#perplexitysearchresults">
    PerplexitySearchResults documentation
  </Card>

  <Card title="PyPI Package" icon="brand-python" href="https://pypi.org/project/langchain-perplexity/">
    View on PyPI
  </Card>

  <Card title="API Reference" icon="code-circle" href="https://python.langchain.com/api_reference/perplexity/">
    LangChain API reference
  </Card>

  <Card title="LangChain JS Docs" icon="js" href="https://docs.langchain.com/oss/javascript/integrations/chat/perplexity">
    ChatPerplexity for JavaScript / TypeScript
  </Card>

  <Card title="npm Package" icon="npm" href="https://www.npmjs.com/package/@langchain/community">
    @langchain/community on npm
  </Card>
</CardGroup>

## Support

Need help with the integration?

* Check the [LangChain documentation](https://docs.langchain.com)
* Review our [FAQ](/docs/resources/faq)


# Perplexity with LiteLLM
Source: https://docs.perplexity.ai/docs/getting-started/integrations/litellm

Use Perplexity's Sonar models, Agent API, and presets through LiteLLM's unified completion interface — Python SDK and Proxy.

## Overview

[LiteLLM](https://litellm.ai) is a Python SDK and proxy server that gives you a single OpenAI-compatible interface to 100+ LLM providers. Both Perplexity's Sonar models and the [Agent API](/docs/agent-api/quickstart) (with third-party models like GPT-5, Claude, and Gemini routed through Perplexity) are first-class providers in LiteLLM.

<Info>
  **LiteLLM** lets you swap providers without rewriting code, run a self-hosted proxy that fronts every model behind one API key, and track spend, latency, and errors per provider. Learn more at [litellm.ai](https://litellm.ai).
</Info>

## Installation

```bash theme={null}
pip install litellm
```

## API Key Setup

LiteLLM uses two environment variables depending on which Perplexity endpoint you're calling:

```bash theme={null}
# For Sonar chat completions (litellm.completion)
export PERPLEXITYAI_API_KEY="your_api_key_here"

# For Agent API responses (litellm.responses)
export PERPLEXITY_API_KEY="your_api_key_here"
```

In practice, set both to the same key.

<Card title="Get API Key" icon="key" href="https://www.perplexity.ai/account/api/keys">
  Generate your Perplexity API key from the API portal.
</Card>

## Sonar Chat Completions

Call Perplexity's Sonar models through `litellm.completion` with the `perplexity/` model prefix:

```python theme={null}
from litellm import completion
import os

os.environ["PERPLEXITYAI_API_KEY"] = "your_api_key_here"

response = completion(
    model="perplexity/sonar-pro",
    messages=[
        {"role": "user", "content": "What are the latest fusion breakthroughs?"}
    ],
)

print(response.choices[0].message.content)
```

### Streaming

```python theme={null}
from litellm import completion

response = completion(
    model="perplexity/sonar-pro",
    messages=[{"role": "user", "content": "Explain quantum computing."}],
    stream=True,
)

for chunk in response:
    print(chunk)
```

### Reasoning Effort

For reasoning-capable Sonar models, pass `reasoning_effort` to control depth:

```python theme={null}
response = completion(
    model="perplexity/sonar-reasoning",
    messages=[{"role": "user", "content": "Walk through your reasoning."}],
    reasoning_effort="high",  # "low" | "medium" | "high"
)
```

### Supported Sonar Models

| Model                 | LiteLLM Identifier               |
| --------------------- | -------------------------------- |
| `sonar`               | `perplexity/sonar`               |
| `sonar-pro`           | `perplexity/sonar-pro`           |
| `sonar-reasoning`     | `perplexity/sonar-reasoning`     |
| `sonar-reasoning-pro` | `perplexity/sonar-reasoning-pro` |
| `sonar-deep-research` | `perplexity/sonar-deep-research` |
| `r1-1776`             | `perplexity/r1-1776`             |

## Agent API

Use `litellm.responses` to call the [Agent API](/docs/agent-api/quickstart), which routes through Perplexity to third-party models with tool orchestration and presets.

### Presets

```python theme={null}
from litellm import responses
import os

os.environ["PERPLEXITY_API_KEY"] = "your_api_key_here"

response = responses(
    model="perplexity/preset/pro-search",
    input="What are the latest developments in AI?",
    custom_llm_provider="perplexity",
)

print(response.output)
```

Available presets: `fast-search`, `pro-search`, `deep-research`, `advanced-deep-research`.

### Tool Use (`web_search` and `fetch_url`)

```python theme={null}
from litellm import responses

response = responses(
    model="perplexity/openai/gpt-5.2",
    input="Research quantum computing breakthroughs and cite sources.",
    custom_llm_provider="perplexity",
    tools=[
        {"type": "web_search"},
        {"type": "fetch_url"},
    ],
    instructions="Use web_search and fetch_url to gather citations.",
    max_output_tokens=1000,
    temperature=0.7,
)

print(response.output)
```

### Structured Outputs

```python theme={null}
from litellm import responses

response = responses(
    model="perplexity/preset/pro-search",
    input="Extract key facts about the Eiffel Tower.",
    custom_llm_provider="perplexity",
    text={
        "format": {
            "type": "json_schema",
            "name": "facts",
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "height_meters": {"type": "number"},
                    "year_built": {"type": "integer"},
                },
                "required": ["name", "height_meters", "year_built"],
            },
            "strict": True,
        }
    },
)
```

### Supported Third-Party Models via Agent API

| Provider   | Models                                                                                                                                                                                                                                              |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| OpenAI     | `perplexity/openai/gpt-5.5`, `perplexity/openai/gpt-5.4`, `perplexity/openai/gpt-5.4-mini`, `perplexity/openai/gpt-5.2`, `perplexity/openai/gpt-5.1`, `perplexity/openai/gpt-5-mini`                                                                |
| Anthropic  | `perplexity/anthropic/claude-opus-4-7`, `perplexity/anthropic/claude-opus-4-6`, `perplexity/anthropic/claude-sonnet-4-6`, `perplexity/anthropic/claude-opus-4-5`, `perplexity/anthropic/claude-sonnet-4-5`, `perplexity/anthropic/claude-haiku-4-5` |
| Google     | `perplexity/google/gemini-3.1-pro-preview`, `perplexity/google/gemini-3-flash-preview`, `perplexity/google/gemini-3.1-flash-lite`                                                                                                                   |
| xAI        | `perplexity/xai/grok-4.20-non-reasoning`                                                                                                                                                                                                            |
| Perplexity | `perplexity/perplexity/sonar`                                                                                                                                                                                                                       |

See the [Agent API model list](/docs/agent-api/quickstart) for the canonical, up-to-date catalogue.

## LiteLLM Proxy

Run LiteLLM as a self-hosted proxy that fronts Perplexity (and any other provider) behind a single OpenAI-compatible endpoint.

### config.yaml

```yaml theme={null}
model_list:
  - model_name: perplexity-sonar-reasoning
    litellm_params:
      model: perplexity/sonar-reasoning
      api_key: os.environ/PERPLEXITYAI_API_KEY

  - model_name: perplexity-pro-search
    litellm_params:
      model: perplexity/preset/pro-search
      api_key: os.environ/PERPLEXITY_API_KEY
```

### Start the Proxy

```bash theme={null}
litellm --config /path/to/config.yaml
```

### Call the Proxy

```bash theme={null}
curl http://0.0.0.0:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer anything" \
  -d '{
    "model": "perplexity-sonar-reasoning",
    "messages": [{"role": "user", "content": "Who won the World Cup in 2022?"}],
    "reasoning_effort": "high"
  }'
```

## Links & Resources

<CardGroup>
  <Card title="LiteLLM Perplexity Docs" icon="book" href="https://docs.litellm.ai/docs/providers/perplexity">
    Official LiteLLM Perplexity provider docs.
  </Card>

  <Card title="LiteLLM Docs" icon="globe" href="https://docs.litellm.ai">
    Full LiteLLM documentation.
  </Card>

  <Card title="Perplexity Agent API" icon="robot" href="/docs/agent-api/quickstart">
    Agent API reference and presets.
  </Card>

  <Card title="Perplexity Models" icon="sparkles" href="/docs/sonar/models">
    Available Sonar and Agent API models.
  </Card>
</CardGroup>

## Support

Need help with the integration?

* Browse the [LiteLLM documentation](https://docs.litellm.ai)
* Review our [FAQ](/docs/resources/faq)


# Perplexity with LiveKit Agents
Source: https://docs.perplexity.ai/docs/getting-started/integrations/livekit

Use Perplexity models as the LLM brain of a LiveKit voice agent.

## Overview

The `livekit-plugins-perplexity` package wraps Perplexity's OpenAI-compatible chat completions endpoint at `https://api.perplexity.ai` so it can be used as a drop-in LLM for [LiveKit Agents](https://docs.livekit.io/agents/).

<Info>
  **LiveKit Agents** is an open-source framework for building realtime voice and multimodal AI agents. The Perplexity plugin lets a voice agent answer with web-grounded, citation-backed responses. Learn more at [livekit.io](https://livekit.io).
</Info>

## Installation

```bash theme={null}
pip install "livekit-agents[perplexity]"
```

## API Key Setup

Set your Perplexity API key as an environment variable, or pass it directly to the constructor:

```bash theme={null}
export PERPLEXITY_API_KEY="your_api_key_here"
```

<Card title="Get API Key" icon="key" href="https://console.perplexity.ai">
  Generate your API key from the Perplexity dashboard.
</Card>

## Quick Start

Use `perplexity.LLM` anywhere a LiveKit Agent expects an LLM:

```python theme={null}
from livekit.agents import Agent, AgentSession
from livekit.plugins import perplexity, openai, silero

session = AgentSession(
    llm=perplexity.LLM(model="sonar-pro"),
    stt=openai.STT(),
    tts=openai.TTS(),
    vad=silero.VAD.load(),
)

agent = Agent(
    instructions="You are a helpful voice assistant. Use web search to answer with up-to-date information.",
)

# Run the session inside your LiveKit room entrypoint
```

The plugin reuses the OpenAI plugin's chat completions transport with `base_url="https://api.perplexity.ai"` and forwards an `X-Pplx-Integration` attribution header on every outgoing request.

## Configuration

`perplexity.LLM` accepts the same options as the underlying OpenAI-compatible client:

```python theme={null}
from livekit.plugins import perplexity

llm = perplexity.LLM(
    model="sonar-pro",
    api_key="...",            # falls back to PERPLEXITY_API_KEY
    temperature=0.2,
    top_p=0.9,
    parallel_tool_calls=True,
)
```

## Available Models

The plugin works with any model exposed through the Perplexity Agent API. `sonar-pro` is the default. See the full list on our [models page](/docs/sonar/models).

## Links & Resources

<CardGroup>
  <Card title="LiveKit Agents Docs" icon="book" href="https://docs.livekit.io/agents/">
    Build realtime voice and multimodal agents with LiveKit.
  </Card>

  <Card title="Perplexity Plugin Source" icon="brand-github" href="https://github.com/livekit/agents/tree/main/livekit-plugins/livekit-plugins-perplexity">
    Plugin source in the livekit/agents monorepo.
  </Card>

  <Card title="PyPI Package" icon="brand-python" href="https://pypi.org/project/livekit-plugins-perplexity/">
    View on PyPI.
  </Card>

  <Card title="Agent API Quickstart" icon="bolt" href="/docs/agent-api/quickstart">
    Learn more about the OpenAI-compatible Perplexity Agent API.
  </Card>
</CardGroup>

## Support

Need help with the integration?

* Browse the [LiveKit Agents documentation](https://docs.livekit.io/agents/)
* Review our [FAQ](/docs/resources/faq)


# Perplexity with Mastra
Source: https://docs.perplexity.ai/docs/getting-started/integrations/mastra

Use Perplexity models, the Agent API, and the Search API in your Mastra agents and tools.

## Overview

[Mastra](https://mastra.ai) is an open-source TypeScript framework for building AI agents and workflows. It ships first-class Perplexity integrations through its model router and tool system, so you can wire Perplexity into a Mastra `Agent` with a single string identifier or expose the Search API as a Mastra-compatible tool.

<Info>
  **Mastra** provides a unified `Agent` interface, a model router, and a tools/MCP system for orchestrating LLM workflows. Learn more at [mastra.ai](https://mastra.ai).
</Info>

The Mastra ecosystem provides three Perplexity integrations:

* **Perplexity model provider** — Use Perplexity's web-grounded models in a Mastra `Agent`.
* **Perplexity Agent provider** — Use the [Agent API](/docs/agent-api/quickstart) (OpenAI-compatible `/chat/completions`) through Mastra.
* **Perplexity Search tool** — Expose the [Search API](/docs/search/quickstart) as a Mastra tool for ranked web results.

## API Key Setup

All three integrations read your Perplexity API key from the environment:

```bash theme={null}
export PERPLEXITY_API_KEY="your_api_key_here"
```

The Search tool also accepts `PPLX_API_KEY` as a fallback.

<Card title="Get API Key" icon="key" href="https://console.perplexity.ai">
  Generate your API key from the Perplexity dashboard.
</Card>

## Perplexity Model Provider

Use Perplexity's web-grounded models inside a Mastra `Agent` through the model router.

```bash theme={null}
npm install @mastra/core
```

```ts theme={null}
import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "research-agent",
  name: "Research Agent",
  instructions: "Answer questions with up-to-date information from the web.",
  model: "perplexity/sonar",
});

const result = await agent.generate("What launched at the latest Perplexity event?");
console.log(result.text);
```

The agent supports both `agent.generate(...)` and `agent.stream(...)`. For the full list of Perplexity models available through the router, see the [Mastra Perplexity provider docs](https://mastra.ai/models/providers/perplexity).

## Perplexity Agent Provider

The Agent provider routes through Perplexity's OpenAI-compatible `/chat/completions` endpoint, giving you access to third-party models served by the [Agent API](/docs/agent-api/quickstart).

```ts theme={null}
import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "agent-api",
  name: "Agent API",
  instructions: "Use the best available model for the task.",
  model: "perplexity-agent/<model-id>",
});
```

For finer control — for example, custom headers or a pinned base URL — pass an object instead of a string:

```ts theme={null}
const agent = new Agent({
  id: "agent-api",
  name: "Agent API",
  instructions: "Use the best available model for the task.",
  model: {
    id: "perplexity-agent/<model-id>",
    url: "https://api.perplexity.ai/v1",
    apiKey: process.env.PERPLEXITY_API_KEY,
  },
});
```

See the [Mastra Perplexity Agent provider docs](https://mastra.ai/models/providers/perplexity-agent) for the full list of supported models and configuration options.

## Perplexity Search Tool

The `@mastra/perplexity` package wraps the [Search API](/docs/search/quickstart) as a Mastra-compatible tool. Use this when you want raw ranked web results — for chat completions or agentic workflows, prefer the model or Agent provider above.

```bash theme={null}
npm install @mastra/perplexity zod
```

```ts theme={null}
import { createPerplexitySearchTool } from "@mastra/perplexity";

const searchTool = createPerplexitySearchTool({
  apiKey: process.env.PERPLEXITY_API_KEY,
});

const results = await searchTool.execute({
  context: {
    query: "Latest advances in nuclear fusion",
    maxResults: 5,
    searchRecencyFilter: "month",
  },
});

for (const result of results) {
  console.log(result.title, result.url);
}
```

The tool ID is `perplexity-search` and supported input parameters include `query`, `maxResults`, `searchDomainFilter`, `searchRecencyFilter`, `searchAfterDateFilter`, and `searchBeforeDateFilter`. Each result includes `title`, `url`, `snippet`, and an optional `date`.

To register multiple Perplexity tools at once, use `createPerplexityTools(config?)`. See the [Mastra Perplexity tool reference](https://mastra.ai/reference/tools/perplexity) for the full schema.

## Links & Resources

<CardGroup>
  <Card title="Perplexity Model Provider" icon="cube" href="https://mastra.ai/models/providers/perplexity">
    Use Perplexity models in a Mastra `Agent`.
  </Card>

  <Card title="Perplexity Agent Provider" icon="robot" href="https://mastra.ai/models/providers/perplexity-agent">
    Use the Perplexity Agent API through Mastra.
  </Card>

  <Card title="Perplexity Search Tool" icon="search" href="https://mastra.ai/reference/tools/perplexity">
    Wrap the Perplexity Search API as a Mastra tool.
  </Card>

  <Card title="Mastra Docs" icon="book" href="https://mastra.ai/docs">
    Learn more about agents, tools, and workflows in Mastra.
  </Card>
</CardGroup>

## Support

Need help with the integration?

* Browse the [Mastra documentation](https://mastra.ai/docs)
* Review our [FAQ](/docs/resources/faq)


# Perplexity MCP Server
Source: https://docs.perplexity.ai/docs/getting-started/integrations/mcp-server

Connect AI assistants to Perplexity's search and reasoning capabilities using the Model Context Protocol (MCP).

## Overview

The Perplexity MCP Server enables AI assistants to access Perplexity's powerful search and reasoning capabilities directly within their workflows. Using the Model Context Protocol (MCP), you can integrate real-time web search, conversational AI, and advanced reasoning into any MCP-compatible client.

<Info>
  The **Model Context Protocol (MCP)** is an open standard that connects AI assistants with external data sources and tools. Learn more at [modelcontextprotocol.io](https://modelcontextprotocol.io/introduction).
</Info>

## Installation

### One-Click Install

Get started instantly with these one-click installers:

<CardGroup>
  <Card
    title="Install in Cursor"
    icon={
<svg
  xmlns="http://www.w3.org/2000/svg"
  viewBox="0 0 466.73 532.09"
>
  <path
    d="M457.43 125.94 244.42 2.96a22.127 22.127 0 0 0-22.12 0L9.3 125.94C3.55 129.26 0 135.4 0 142.05v247.99c0 6.65 3.55 12.79 9.3 16.11l213.01 122.98a22.127 22.127 0 0 0 22.12 0l213.01-122.98c5.75-3.32 9.3-9.46 9.3-16.11V142.05c0-6.65-3.55-12.79-9.3-16.11h-.01Zm-13.38 26.05L238.42 508.15c-1.39 2.4-5.06 1.42-5.06-1.36V273.58c0-4.66-2.49-8.97-6.53-11.31L24.87 145.67c-2.4-1.39-1.42-5.06 1.36-5.06h411.26c5.84 0 9.49 6.33 6.57 11.39h-.01Z"
    style={{ fill: "var(--color-foreground)" }}
  />
</svg>
}
    href="https://cursor.com/en/install-mcp?name=perplexity&config=eyJ0eXBlIjoic3RkaW8iLCJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBwZXJwbGV4aXR5LWFpL21jcC1zZXJ2ZXIiXSwiZW52Ijp7IlBFUlBMRVhJVFlfQVBJX0tFWSI6IiJ9fQ=="
  >
    Automatically configure the Perplexity MCP server in Cursor with one click.
  </Card>

  <Card
    title="Install in VS Code"
    icon={
<svg
  xmlns="http://www.w3.org/2000/svg"
  viewBox="0 0 100 100"
>
  <path
    d="M70.912 99.572a6.193 6.193 0 0 0 4.96-.191l20.588-9.958a6.285 6.285 0 0 0 3.54-5.661V16.239a6.286 6.286 0 0 0-3.54-5.662L75.873.62a6.2 6.2 0 0 0-7.104 1.216L29.355 37.98l-17.168-13.1a4.146 4.146 0 0 0-5.318.238l-5.506 5.035a4.205 4.205 0 0 0-.004 6.194L16.247 50 1.36 63.654a4.205 4.205 0 0 0 .004 6.194l5.506 5.034a4.145 4.145 0 0 0 5.318.238l17.168-13.1L68.77 98.166a6.205 6.205 0 0 0 2.143 1.407Zm4.103-72.39L45.11 50 75.015 72.82V27.18Z"
    fillRule="evenodd"
    style={{ fill: "var(--color-foreground)" }}
  />
</svg>
}
    href="https://vscode.dev/redirect/mcp/install?name=perplexity&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40perplexity-ai%2Fmcp-server%22%5D%2C%22env%22%3A%7B%22PERPLEXITY_API_KEY%22%3A%22%22%7D%7D"
  >
    Automatically configure the Perplexity MCP server in VS Code with one click.
  </Card>
</CardGroup>

### Manual Setup

<Steps>
  <Step title="Get Your API Key">
    <Card title="Generate API Key" icon="key" href="https://console.perplexity.ai">
      Navigate to the API Portal and generate a new key.
    </Card>
  </Step>

  <Step title="Configure Your Client">
    Add the MCP server to your client configuration:

    <Tabs>
      <Tab title="Claude Code">
        **Option 1: CLI Command (Recommended)**

        The easiest way to get started:

        ```bash theme={null}
        claude mcp add perplexity --env PERPLEXITY_API_KEY="your_key_here" -- npx -y @perplexity-ai/mcp-server
        ```

        **Option 2: Plugin Install**

        Install via plugin:

        ```bash theme={null}
        export PERPLEXITY_API_KEY="your_key_here"
        claude
        # Then run: /plugin marketplace add perplexityai/modelcontextprotocol
        # Then run: /plugin install perplexity
        ```

        **Option 3: Manual Configuration**

        Add to your `claude.json`:

        ```json theme={null}
        {
          "mcpServers": {
            "perplexity": {
              "type": "stdio",
              "command": "npx",
              "args": ["-y", "perplexity-mcp"],
              "env": {
                "PERPLEXITY_API_KEY": "your_key_here"
              }
            }
          }
        }
        ```
      </Tab>

      <Tab title="Cursor">
        We recommend using the one-click install above for setting up the MCP server in Cursor.

        If you prefer to configure it manually, add the following to your `mcp.json`:

        ```json theme={null}
        {
          "mcpServers": {
            "perplexity": {
              "command": "npx",
              "args": ["-y", "@perplexity-ai/mcp-server"],
              "env": {
                "PERPLEXITY_API_KEY": "your_key_here"
              }
            }
          }
        }
        ```
      </Tab>

      <Tab title="Codex">
        ```bash theme={null}
        codex mcp add perplexity --env PERPLEXITY_API_KEY="your_key_here" -- npx -y @perplexity-ai/mcp-server
        ```
      </Tab>

      <Tab title="Other Clients">
        Most MCP-compatible clients (including Claude Desktop, VS Code, and Windsurf) use the `mcpServers` format. Configuration file locations:

        | Client             | Config File                             |
        | ------------------ | --------------------------------------- |
        | Cursor             | `~/.cursor/mcp.json`                    |
        | VS Code            | `.vscode/mcp.json`                      |
        | Claude Desktop     | `claude_desktop_config.json`            |
        | Windsurf           | `~/.codeium/windsurf/mcp_config.json`   |
        | Google Antigravity | `~/.gemini/antigravity/mcp_config.json` |

        **Standard `mcpServers` format:**

        ```json theme={null}
        {
          "mcpServers": {
            "perplexity": {
              "command": "npx",
              "args": ["-y", "@perplexity-ai/mcp-server"],
              "env": {
                "PERPLEXITY_API_KEY": "your_key_here"
              }
            }
          }
        }
        ```

        **VS Code uses a slightly different format:**

        ```json theme={null}
        {
          "servers": {
            "perplexity": {
              "type": "stdio",
              "command": "npx",
              "args": ["-y", "@perplexity-ai/mcp-server"],
              "env": {
                "PERPLEXITY_API_KEY": "your_key_here"
              }
            }
          }
        }
        ```

        If your client doesn't work with these formats, check its documentation for the correct wrapper format.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Start Using">
    Restart your MCP client and start using Perplexity's tools in your AI workflows.
  </Step>
</Steps>

## Available Tools

<CardGroup>
  <Card title="perplexity_search" icon="search">
    Direct web search using the Perplexity Search API. Returns ranked search results with titles, URLs, snippets, and metadata.

    **Best for:** Finding current information, news, facts, or specific web content.
  </Card>

  <Card title="perplexity_ask" icon="message">
    General-purpose conversational AI with real-time web search using the `sonar-pro` model.

    **Best for:** Quick questions, everyday searches, and conversational queries that benefit from web context.
  </Card>

  <Card title="perplexity_research" icon="book">
    Deep, comprehensive research using the `sonar-deep-research` model. Provides thorough analysis with citations.

    **Best for:** Complex topics requiring detailed investigation, comprehensive reports, and in-depth analysis.
  </Card>

  <Card title="perplexity_reason" icon="brain">
    Advanced reasoning and problem-solving using the `sonar-reasoning-pro` model.

    **Best for:** Logical problems, complex analysis, decision-making, and tasks requiring step-by-step reasoning.
  </Card>
</CardGroup>

<Info>
  For detailed setup instructions, troubleshooting, and proxy configuration, visit our [GitHub repository](https://github.com/perplexityai/modelcontextprotocol).
</Info>


# Perplexity with n8n
Source: https://docs.perplexity.ai/docs/getting-started/integrations/n8n

Add real-time web search, AI agents, and embeddings to your n8n workflows using the native Perplexity node.

## Overview

n8n ships a native **Perplexity node** with full API coverage — Chat Completions, Agent, Search, and Embeddings — all configurable from the visual canvas. Models load dynamically from the API, so the dropdown always reflects the latest options.

<Info>
  **n8n** is a node-based workflow automation platform. It supports both self-hosted and cloud deployments — all examples below work in either. If you're self-hosting, make sure your instance can reach `api.perplexity.ai` outbound. Learn more at [n8n.io](https://n8n.io).
</Info>

The node supports four resources:

* **Chat Completion** — Sonar models with built-in web search, citations, and search controls
* **Agent** — Third-party models (OpenAI, Anthropic, Google, xAI) with tool-calling and structured output
* **Search** — Raw ranked web results for your own processing
* **Embeddings** — Vector generation for RAG and retrieval pipelines

## Prerequisites

* n8n 2.14.0+ (cloud at [app.n8n.cloud](https://app.n8n.cloud) or self-hosted)
* A Perplexity API key

<Card title="Get API Key" icon="key" href="https://www.perplexity.ai/settings/api">
  Generate your Perplexity API key from the console.
</Card>

## Credential Setup

<Steps>
  <Step title="Open Credentials">
    In n8n, go to **Settings → Credentials → Add credential**.
  </Step>

  <Step title="Select Perplexity">
    Search for **Perplexity API** and select it.
  </Step>

  <Step title="Add Your Key">
    Paste your API key and save. The node will reference this credential automatically.
  </Step>
</Steps>

<img alt="Perplexity credential setup" />

***

## Chat Completion

Use Sonar models with built-in web search. This is the most common starting point — send a question, get a grounded answer with citations.

Add a **Perplexity** node, set **Resource** to `Chat Completion`, and choose a model:

| Parameter        | Description                                                                    |
| ---------------- | ------------------------------------------------------------------------------ |
| **Model**        | `sonar`, `sonar-pro`, `sonar-reasoning-pro`, or `sonar-deep-research`          |
| **User Message** | The question or prompt — supports n8n expressions like `={{ $json.question }}` |

<img alt="Chat Completion node configuration" />

### Search Controls

The node exposes Perplexity's full search filtering in the **Options** section:

<img alt="Search controls and additional parameters" />

### Extracting Citations

The response includes a `citations` array of source URLs. Use a **Code** node after the Perplexity node to format them:

```javascript theme={null}
const response = $input.first().json;
const content = response.choices[0].message.content;
const citations = response.citations ?? [];

return [{
  answer: citations.length > 0
    ? `${content}\n\nSources:\n${citations.map((c, i) => `[${i + 1}] ${c}`).join('\n')}`
    : content,
  citations
}];
```

***

## Agent

Use the Agent resource to route through third-party models (OpenAI, Anthropic, Google, xAI) with Perplexity's `web_search` and `fetch_url` tools.

Set **Resource** to `Agent` and configure:

| Parameter               | Description                                                                                 |
| ----------------------- | ------------------------------------------------------------------------------------------- |
| **Model**               | Any model from the dynamic dropdown (e.g., `openai/gpt-5.5`, `anthropic/claude-sonnet-4-6`) |
| **Input**               | Your prompt — supports n8n expressions                                                      |
| **Tools**               | Select `web_search`, `fetch_url`, or both                                                   |
| **System Instructions** | Optional system prompt for the agent                                                        |
| **Response Format**     | Optional JSON schema for structured output                                                  |

<img alt="Agent resource configuration" />

***

## Search

Get raw ranked web results without LLM processing. Set **Resource** to `Search`:

| Parameter         | Description                                 |
| ----------------- | ------------------------------------------- |
| **Query**         | The search query — supports n8n expressions |
| **Recency**       | `day`, `week`, `month`, or `year`           |
| **Domain Filter** | Limit to specific domains                   |
| **Language**      | ISO 639-1 language code                     |
| **Country**       | Two-letter country code                     |

Each result includes `title`, `url`, `snippet`, and `date`.

<img alt="Search resource results" />

***

## Embeddings

Generate vectors for RAG and retrieval pipelines. Set **Resource** to `Embeddings`:

| Parameter | Description                                                        |
| --------- | ------------------------------------------------------------------ |
| **Model** | `pplx-embed-v1-4b` (2560 dims) or `pplx-embed-v1-0.6b` (1024 dims) |
| **Input** | Text to embed — supports n8n expressions                           |

The node also supports contextual embeddings via `POST /v1/contextualizedembeddings` for document-chunk-aware vectors.

<img alt="Embeddings resource configuration" />

***

## Error Handling

Use n8n's **Error Trigger** workflow or the built-in **Retry on Fail** setting (node settings → Retry on Fail) to handle transient errors:

* **429 Too Many Requests** — add a **Wait** node with exponential backoff before retrying
* **401 Unauthorized** — verify your Perplexity API credential is saved correctly
* **500 errors** — enable Retry on Fail in the node settings

## Links & Resources

<CardGroup>
  <Card title="n8n Docs" icon="book" href="https://docs.n8n.io">
    Official n8n documentation
  </Card>

  <Card title="n8n Community" icon="users" href="https://community.n8n.io">
    Templates, workflows, and community support
  </Card>

  <Card title="Perplexity API Reference" icon="code" href="/api-reference">
    Full API reference
  </Card>

  <Card title="Sonar Models" icon="sparkles" href="/docs/sonar/models">
    Available models and capabilities
  </Card>
</CardGroup>


# Perplexity with OpenClaw
Source: https://docs.perplexity.ai/docs/getting-started/integrations/openclaw

Use Perplexity as an LLM provider and web search provider in OpenClaw.

## Overview

<u>[OpenClaw](https://openclaw.ai)</u> is an open-source AI agent that runs in your terminal and connects to multiple LLM providers, featuring support for Perplexity as a web search provider for real-time information retrieval.

You can configure OpenClaw to use Perplexity's Agent API models as your agent, and the Perplexity Search API for web search tool calls. This allows you to leverage Perplexity's powerful models and up-to-date search results directly within OpenClaw's agent framework.

<Card title="Get a Perplexity API Key" icon="key" href="https://console.perplexity.ai">
  Navigate to the API Console and generate a new key to use with OpenClaw.
</Card>

***

## Search API Setup (Use Perplexity as your Web Search Provider)

Use Perplexity Search API as OpenClaw's web search backend for real-time information retrieval.

<Steps>
  <Step title="Configure the Search Provider">
    <Tabs>
      <Tab title="Interactive CLI (Recommended)">
        The quickest way — no file editing required:

        ```bash theme={null}
        openclaw configure --section web
        ```

        Select **Perplexity** when prompted for a search provider, then paste your API key.
      </Tab>

      <Tab title="Config File (JSON)">
        Edit your `openclaw.json` (run `openclaw config file` to locate it):

        ```json theme={null}
        {
          "plugins": {
            "entries": {
              "perplexity": {
                "config": {
                  "webSearch": {
                    "apiKey": "pplx-..."
                  }
                }
              }
            }
          },
          "tools": {
            "web": {
              "search": {
                "provider": "perplexity"
              }
            }
          }
        }
        ```
      </Tab>

      <Tab title="Environment Variable">
        Set the environment variable and OpenClaw will auto-detect it:

        <Tabs>
          <Tab title="macOS / Linux">
            ```bash theme={null}
            export PERPLEXITY_API_KEY="pplx-..."
            ```
          </Tab>

          <Tab title="Windows (PowerShell)">
            ```powershell theme={null}
            setx PERPLEXITY_API_KEY="pplx-..."
            ```
          </Tab>
        </Tabs>

        Or set `PERPLEXITY_API_KEY` in `~/.openclaw/.env` for daemon installs.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Start using OpenClaw with Perplexity Search">
    Start OpenClaw and ask anything that requires web search:

    ```
    openclaw
    > What are the latest developments in quantum computing?
    ```

    OpenClaw will use Perplexity Search API to retrieve structured results and incorporate them into its response.
  </Step>
</Steps>

### Search Tool Parameters

When OpenClaw invokes `web_search` with Perplexity as the provider, these parameters are available:

| Parameter             | Description                                            |
| --------------------- | ------------------------------------------------------ |
| `query`               | Search query (required)                                |
| `count`               | Number of results (1–10, default: 5)                   |
| `country`             | ISO 3166-1 alpha-2 country code (e.g., `US`, `DE`)     |
| `language`            | ISO 639-1 language code (e.g., `en`, `fr`)             |
| `freshness`           | Time filter: `day`, `week`, `month`, or `year`         |
| `date_after`          | Results published after this date (`YYYY-MM-DD`)       |
| `date_before`         | Results published before this date (`YYYY-MM-DD`)      |
| `domain_filter`       | Domain allowlist or denylist (max 20 entries)          |
| `max_tokens`          | Total content budget (default: 25,000, max: 1,000,000) |
| `max_tokens_per_page` | Per-page token limit (default: 2,048)                  |

<Tip>
  Domain filters support allowlists (`["nature.com", "science.org"]`) and denylists (`["-reddit.com", "-pinterest.com"]`), but you cannot mix both in the same request. See the [domain filter guide](/docs/search/filters/domain-filter) for details.
</Tip>

***

## Agent API Setup (Use Perplexity as your LLM Provider)

Use Perplexity's Agent API to run models like Claude Sonnet, GPT-5, Gemini, and Sonar as your OpenClaw coding agent.

<Steps>
  <Step title="Get Your API Key">
    <Card title="Generate API Key" icon="key" href="https://console.perplexity.ai">
      Navigate to the API Console and generate a new key.
    </Card>
  </Step>

  <Step title="Install OpenClaw">
    If you haven't installed OpenClaw yet:

    <Tabs>
      <Tab title="macOS / Linux">
        ```bash theme={null}
        curl -fsSL https://openclaw.ai/install.sh | bash
        ```
      </Tab>

      <Tab title="Windows (PowerShell)">
        ```powershell theme={null}
        iwr -useb https://openclaw.ai/install.ps1 | iex
        ```
      </Tab>
    </Tabs>

    For Docker, Podman, Nix, or other installation methods, see the [OpenClaw install documentation](https://docs.openclaw.ai/install).
  </Step>

  <Step title="Configure Perplexity as an LLM Provider">
    <Tabs>
      <Tab title="Onboarding CLI (Recommended)">
        The quickest way — no file editing required:

        ```bash theme={null}
        openclaw onboard \
          --auth-choice custom-api-key \
          --custom-base-url "https://api.perplexity.ai/v1" \
          --custom-api-key "pplx-YOUR_KEY_HERE" \
          --custom-model-id "anthropic/claude-sonnet-4-6" \ 
          --custom-compatibility openai \
          --custom-provider-id perplexity \
          --install-daemon
        ```

        This registers Perplexity as a provider with one model. To add more models, re-run with a different `--custom-model-id` or switch to the config file method.

        You can replace `anthropic/claude-sonnet-4-6` with any model ID from the [Agent API models list](/docs/agent-api/models) to change your default model.
      </Tab>

      <Tab title="Config File (All Models)">
        Edit your `openclaw.json` (run `openclaw config file` to locate it):

        ```json theme={null}
        {
        "agents": {
          "defaults": {
            "model": {
              "primary": "perplexity/anthropic/claude-sonnet-4-6" // Set your default model here
            }
          }
        },
        "models": {
          "mode": "merge",
          "providers": {
            "perplexity": {
              "baseUrl": "https://api.perplexity.ai/v1",
              "apiKey": "pplx-YOUR_KEY_HERE",
              "api": "openai-responses",
              "models": [
                {
                  "id": "perplexity/sonar",
                  "name": "Sonar (Perplexity)",
                  "api": "openai-responses",
                  "reasoning": false,
                  "input": ["text"],
                  "cost": { "input": 0.25, "output": 2.50, "cacheRead": 0.0625, "cacheWrite": 0 },
                  "contextWindow": 128000,
                  "maxTokens": 16384
                },
                {
                  "id": "anthropic/claude-opus-4-7",
                  "name": "Claude Opus 4.7 (Perplexity)",
                  "api": "openai-responses",
                  "reasoning": false,
                  "input": ["text"],
                  "cost": { "input": 5.00, "output": 25.00, "cacheRead": 0.50, "cacheWrite": 0 },
                  "contextWindow": 200000,
                  "maxTokens": 16384
                },
                {
                  "id": "anthropic/claude-opus-4-5",
                  "name": "Claude Opus 4.5 (Perplexity)",
                  "api": "openai-responses",
                  "reasoning": false,
                  "input": ["text"],
                  "cost": { "input": 5.00, "output": 25.00, "cacheRead": 0.50, "cacheWrite": 0 },
                  "contextWindow": 200000,
                  "maxTokens": 16384
                },
                {
                  "id": "anthropic/claude-sonnet-4-6",
                  "name": "Claude Sonnet 4.6 (Perplexity)",
                  "api": "openai-responses",
                  "reasoning": false,
                  "input": ["text"],
                  "cost": { "input": 3.00, "output": 15.00, "cacheRead": 0.30, "cacheWrite": 0 },
                  "contextWindow": 200000,
                  "maxTokens": 16384
                },
                {
                  "id": "anthropic/claude-sonnet-4-5",
                  "name": "Claude Sonnet 4.5 (Perplexity)",
                  "api": "openai-responses",
                  "reasoning": false,
                  "input": ["text"],
                  "cost": { "input": 3.00, "output": 15.00, "cacheRead": 0.30, "cacheWrite": 0 },
                  "contextWindow": 200000,
                  "maxTokens": 16384
                },
                {
                  "id": "anthropic/claude-haiku-4-5",
                  "name": "Claude Haiku 4.5 (Perplexity)",
                  "api": "openai-responses",
                  "reasoning": false,
                  "input": ["text"],
                  "cost": { "input": 1.00, "output": 5.00, "cacheRead": 0.10, "cacheWrite": 0 },
                  "contextWindow": 200000,
                  "maxTokens": 16384
                },
                {
                  "id": "openai/gpt-5.4",
                  "name": "GPT-5.4 (Perplexity)",
                  "api": "openai-responses",
                  "reasoning": false,
                  "input": ["text"],
                  "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
                  "contextWindow": 128000,
                  "maxTokens": 16384
                },
                {
                  "id": "openai/gpt-5.2",
                  "name": "GPT-5.2 (Perplexity)",
                  "api": "openai-responses",
                  "reasoning": false,
                  "input": ["text"],
                  "cost": { "input": 1.75, "output": 14.00, "cacheRead": 0.175, "cacheWrite": 0 },
                  "contextWindow": 128000,
                  "maxTokens": 16384
                },
                {
                  "id": "openai/gpt-5.1",
                  "name": "GPT-5.1 (Perplexity)",
                  "api": "openai-responses",
                  "reasoning": false,
                  "input": ["text"],
                  "cost": { "input": 1.25, "output": 10.00, "cacheRead": 0.125, "cacheWrite": 0 },
                  "contextWindow": 128000,
                  "maxTokens": 16384
                },
                {
                  "id": "openai/gpt-5-mini",
                  "name": "GPT-5 Mini (Perplexity)",
                  "api": "openai-responses",
                  "reasoning": false,
                  "input": ["text"],
                  "cost": { "input": 0.25, "output": 2.00, "cacheRead": 0.025, "cacheWrite": 0 },
                  "contextWindow": 128000,
                  "maxTokens": 16384
                },
                {
                  "id": "google/gemini-3.1-pro-preview",
                  "name": "Gemini 3.1 Pro (Perplexity)",
                  "api": "openai-responses",
                  "reasoning": false,
                  "input": ["text"],
                  "cost": { "input": 2.00, "output": 12.00, "cacheRead": 0.20, "cacheWrite": 0 },
                  "contextWindow": 200000,
                  "maxTokens": 16384
                },
                {
                  "id": "google/gemini-3-flash-preview",
                  "name": "Gemini 3 Flash (Perplexity)",
                  "api": "openai-responses",
                  "reasoning": false,
                  "input": ["text"],
                  "cost": { "input": 0.50, "output": 3.00, "cacheRead": 0.05, "cacheWrite": 0 },
                  "contextWindow": 200000,
                  "maxTokens": 16384
                },
                {
                  "id": "google/gemini-2.5-pro",
                  "name": "Gemini 2.5 Pro (Perplexity)",
                  "api": "openai-responses",
                  "reasoning": false,
                  "input": ["text"],
                  "cost": { "input": 1.25, "output": 10.00, "cacheRead": 0.125, "cacheWrite": 0 },
                  "contextWindow": 200000,
                  "maxTokens": 16384
                },
                {
                  "id": "google/gemini-2.5-flash",
                  "name": "Gemini 2.5 Flash (Perplexity)",
                  "api": "openai-responses",
                  "reasoning": false,
                  "input": ["text"],
                  "cost": { "input": 0.30, "output": 2.50, "cacheRead": 0.03, "cacheWrite": 0 },
                  "contextWindow": 200000,
                  "maxTokens": 16384
                },
                {
                  "id": "nvidia/nemotron-3-super-120b-a12b",
                  "name": "Nemotron 3 Super (Perplexity)",
                  "api": "openai-responses",
                  "reasoning": false,
                  "input": ["text"],
                  "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
                  "contextWindow": 128000,
                  "maxTokens": 16384
                },
                {
                  "id": "xai/grok-4-1-fast-non-reasoning",
                  "name": "Grok 4.1 Fast (Perplexity)",
                  "api": "openai-responses",
                  "reasoning": false,
                  "input": ["text"],
                  "cost": { "input": 0.20, "output": 0.50, "cacheRead": 0.05, "cacheWrite": 0 },
                  "contextWindow": 128000,
                  "maxTokens": 16384
                }
              ]
            }
          }
        }
        }
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Start using OpenClaw">
    Launch OpenClaw and your agent will use Perplexity:

    ```bash theme={null}
    openclaw
    ```
  </Step>
</Steps>

### Agent API Configuration Tips

<AccordionGroup>
  <Accordion title="API transport must be openai-responses">
    Perplexity's Agent API uses the [OpenAI Responses format](/docs/agent-api/openai-compatibility). In `openclaw.json`, set the `api` field to `"openai-responses"` at both the provider level and each model entry.

    Using `"openai-completions"` will not work.
  </Accordion>

  <Accordion title="Base URL must be exactly https://api.perplexity.ai/v1">
    Do **not** include `/agent` or `/responses` in the URL. OpenClaw appends `/responses` automatically.

    Wrong base URLs will cause authentication errors or 404s.

    | Correct                        | Wrong                                       |
    | ------------------------------ | ------------------------------------------- |
    | `https://api.perplexity.ai/v1` | `https://api.perplexity.ai/v1/agent`        |
    |                                | `https://api.perplexity.ai/v1/responses`    |
    |                                | `https://api.perplexity.ai` (missing `/v1`) |
  </Accordion>

  <Accordion title="Model ID format">
    In the config, model IDs under a provider block omit the provider prefix. The full model reference adds it:

    * Config model ID: `anthropic/claude-sonnet-4-6`
    * Full model reference: `perplexity/anthropic/claude-sonnet-4-6`
  </Accordion>
</AccordionGroup>

<Tip>
  For the latest model list and pricing, see the [Agent API models page](/docs/agent-api/models) and [pricing page](/docs/getting-started/pricing).
</Tip>

***

## Links & Resources

<CardGroup>
  <Card title="Agent API Quickstart" icon="robot" href="/docs/agent-api/quickstart">
    Use third-party models with built-in tools and function calling
  </Card>

  <Card title="Agent API Models" icon="list" href="/docs/agent-api/models">
    Full list of available models and pricing
  </Card>

  <Card title="Search API Quickstart" icon="search" href="/docs/search/quickstart">
    Full Perplexity Search API documentation
  </Card>

  <Card title="OpenAI Compatibility" icon="plug" href="/docs/agent-api/openai-compatibility">
    How the Agent API works with OpenAI-compatible clients
  </Card>

  <Card title="OpenClaw Documentation" icon="book" href="https://docs.openclaw.ai">
    OpenClaw's official documentation
  </Card>

  <Card title="API Console" icon="key" href="https://console.perplexity.ai">
    Generate and manage your API keys
  </Card>
</CardGroup>


# Perplexity with OpenCode
Source: https://docs.perplexity.ai/docs/getting-started/integrations/opencode

Use the Perplexity Agent API inside the OpenCode AI coding agent — one endpoint, every frontier model, with built-in web search and tool orchestration.

## Overview

[OpenCode](https://opencode.ai) is an open-source AI coding agent for your terminal, IDE, or desktop. The Perplexity **Agent API** is OpenAI-compatible and exposes frontier models from OpenAI, Anthropic, Google, xAI, and Perplexity through a single endpoint, with optional `web_search` and `fetch_url` tools and Perplexity's research presets.

Wiring OpenCode to the Agent API means you can swap any frontier model into your coding agent or research subagent — without juggling separate provider accounts.

<Info>
  **OpenCode** ships with multi-agent orchestration: you can configure a `primary` agent for coding and `subagent` agents for specialized tasks. Learn more at [opencode.ai](https://opencode.ai).
</Info>

## Setup

The Agent API is OpenAI-compatible, so you configure it in OpenCode as a custom provider using `@ai-sdk/openai-compatible`.

<Steps>
  <Step title="Install OpenCode">
    Follow the [OpenCode install guide](https://opencode.ai/docs) for your platform (macOS, Linux, Windows).
  </Step>

  <Step title="Get a Perplexity API key">
    <Card title="Get API Key" icon="key" href="https://www.perplexity.ai/account/api/keys">
      Generate your Perplexity API key from the API portal.
    </Card>

    Export it in your shell:

    ```bash theme={null}
    export PERPLEXITY_API_KEY="pplx-..."
    ```
  </Step>

  <Step title="Configure OpenCode">
    Add the Perplexity Agent API as a provider in your `opencode.json` (or `~/.config/opencode/config.json`). See the configuration below.
  </Step>

  <Step title="Verify">
    Run `/models` to confirm the Perplexity Agent models appear in the selector.
  </Step>
</Steps>

## Provider Configuration

OpenCode supports OpenAI-compatible providers out of the box. Point it at `https://api.perplexity.ai/v1` and declare the models you want available in the model picker:

```json theme={null}
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "perplexity-agent": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Perplexity Agent API",
      "options": {
        "baseURL": "https://api.perplexity.ai/v1",
        "apiKey": "{env:PERPLEXITY_API_KEY}",
        "headers": {
          "X-Pplx-Integration": "opencode/1.0"
        }
      },
      "models": {
        "openai/gpt-5.2": { "name": "GPT-5.2" },
        "openai/gpt-5.1": { "name": "GPT-5.1" },
        "openai/gpt-5-mini": { "name": "GPT-5 Mini" },
        "anthropic/claude-opus-4-7": { "name": "Claude Opus 4.7" },
        "anthropic/claude-sonnet-4-6": { "name": "Claude Sonnet 4.6" },
        "anthropic/claude-haiku-4-5": { "name": "Claude Haiku 4.5" },
        "google/gemini-3.1-pro-preview": { "name": "Gemini 3.1 Pro" },
        "google/gemini-3-flash-preview": { "name": "Gemini 3 Flash" },
        "xai/grok-4.20-non-reasoning": { "name": "Grok 4.20" }
      }
    }
  }
}
```

That's it — one API key, one endpoint, every frontier model.

## Available Models

The Agent API routes to models from multiple providers. The full canonical list lives on the [models page](/docs/agent-api/models); the most useful identifiers for coding work:

| Model ID                        | Best for                                     |
| ------------------------------- | -------------------------------------------- |
| `openai/gpt-5.2`                | Deep reasoning, long-horizon coding tasks    |
| `openai/gpt-5.1`                | General-purpose coding agent                 |
| `openai/gpt-5-mini`             | Fast, cheap coding completions               |
| `anthropic/claude-opus-4-7`     | Highest-quality code review and architecture |
| `anthropic/claude-sonnet-4-6`   | Balanced coding + tool use                   |
| `google/gemini-3.1-pro-preview` | Long-context refactors                       |
| `xai/grok-4.20-non-reasoning`   | Low-latency edits                            |

You can also use Perplexity's [research presets](/docs/agent-api/presets) (`fast-search`, `pro-search`, `deep-research`, `advanced-deep-research`) as model IDs to get pre-tuned web-search behavior.

## Use as a Primary Coding Model

Set any Agent API model as your default in `opencode.json`:

```json theme={null}
{
  "$schema": "https://opencode.ai/config.json",
  "model": "perplexity-agent/anthropic/claude-opus-4-7"
}
```

OpenCode addresses each model as `<providerId>/<modelId>`, so the full identifier is `perplexity-agent/anthropic/claude-opus-4-7`.

## Multi-Agent Setup: Research Subagent with Web Tools

The Agent API's `web_search` and `fetch_url` tools make it a strong fit for a dedicated research subagent. The coder owns the filesystem; the researcher owns the open web.

```json theme={null}
{
  "$schema": "https://opencode.ai/config.json",
  "model": "perplexity-agent/anthropic/claude-opus-4-7",
  "agent": {
    "coder": {
      "description": "Primary coding agent",
      "mode": "primary",
      "model": "perplexity-agent/anthropic/claude-opus-4-7",
      "temperature": 0.2,
      "tools": {
        "write": true,
        "edit": true,
        "bash": true
      }
    },
    "researcher": {
      "description": "Research agent using Perplexity's deep-research preset with live web access",
      "mode": "subagent",
      "model": "perplexity-agent/deep-research",
      "temperature": 0.4,
      "tools": {
        "write": false,
        "edit": false,
        "bash": false
      }
    }
  }
}
```

Because the researcher uses Perplexity's `deep-research` preset, every web lookup includes citations, multi-step retrieval, and the `fetch_url` tool for reading specific docs pages. The coder calls into it whenever it needs current documentation or API references.

Verify the wiring:

```
/agents   # Should show coder and researcher
/models   # Should include Perplexity Agent models
```

## Why the Agent API

The Agent API is purpose-built for agent loops:

* **One key, every model** — switch between OpenAI, Anthropic, Google, and xAI without managing separate accounts.
* **OpenAI-compatible** — drop-in for any OpenCode provider slot that speaks `/v1/responses` or `/v1/chat/completions`.
* **Built-in web tools** — opt into `web_search` and `fetch_url` per request, no MCP setup required.
* **Research presets** — `pro-search`, `deep-research`, `advanced-deep-research` give your subagents tuned retrieval behavior out of the box.

## Links & Resources

<CardGroup>
  <Card title="Agent API Quickstart" icon="bolt" href="/docs/agent-api/quickstart">
    Send your first Agent API request.
  </Card>

  <Card title="Agent API Models" icon="sparkles" href="/docs/agent-api/models">
    Full model catalog with pricing.
  </Card>

  <Card title="Research Presets" icon="layer-group" href="/docs/agent-api/presets">
    Pre-tuned model + tool configurations.
  </Card>

  <Card title="OpenAI Compatibility" icon="plug" href="/docs/agent-api/openai-compatibility">
    Use Agent API with any OpenAI SDK.
  </Card>

  <Card title="OpenCode Providers" icon="book" href="https://opencode.ai/docs/providers/">
    OpenCode custom provider reference.
  </Card>

  <Card title="OpenCode Docs" icon="book-open" href="https://opencode.ai/docs">
    Official OpenCode documentation.
  </Card>
</CardGroup>

## Support

Need help with the integration?

* Browse the [OpenCode documentation](https://opencode.ai/docs)
* Review our [FAQ](/docs/resources/faq)


# Perplexity with Pipedream
Source: https://docs.perplexity.ai/docs/getting-started/integrations/pipedream

Wire Perplexity into Pipedream workflows alongside 3,000+ other apps — automate research, summarization, and grounded responses with code and no-code steps.

## Overview

[Pipedream](https://pipedream.com) is a workflow automation platform with 3,000+ pre-built app integrations. The Perplexity app lets you authenticate once and then call Perplexity's chat completions and search endpoints from any Pipedream workflow — whether triggered by an email, a webhook, an RSS feed, a Slack message, a Google Sheets update, or a schedule.

<Info>
  **Pipedream** supports both no-code visual steps and full-code Node.js / Python steps in the same workflow. Learn more at [pipedream.com](https://pipedream.com).
</Info>

## Authentication

<Steps>
  <Step title="Get your API key">
    Generate a Perplexity API key from the [API portal](https://www.perplexity.ai/account/api/keys).
  </Step>

  <Step title="Connect Perplexity in Pipedream">
    In Pipedream, open any workflow and add the **Perplexity** app to a step. Click **Connect new account** and paste your API key. Pipedream stores it securely and references it via `$auth.api_key` in all future steps.
  </Step>
</Steps>

<Card title="Get API Key" icon="key" href="https://www.perplexity.ai/account/api/keys">
  Generate your Perplexity API key from the API portal.
</Card>

## Built-in Action: Chat Completions

The Perplexity app ships a **Chat Completions** action that generates a model response for a chat conversation with full Perplexity search controls — no code required.

* **Endpoint**: `POST /v1/chat/completions`
* **Inputs**: model, messages, search recency, domain filter, etc.
* **Output**: full chat completion response including `choices[0].message.content` and `citations`.

Add it from the step picker by searching **Perplexity → Chat Completions**.

## Custom Code Step

For full control — async chat completions, embeddings, or the Agent API — use a Pipedream **Node.js code step** that references your saved Perplexity connection:

```javascript theme={null}
import { axios } from "@pipedream/platform";

export default defineComponent({
  props: {
    perplexity: {
      type: "app",
      app: "perplexity",
    },
  },
  async run({ steps, $ }) {
    return await axios($, {
      method: "POST",
      url: "https://api.perplexity.ai/v1/chat/completions",
      headers: {
        Authorization: `Bearer ${this.perplexity.$auth.api_key}`,
        "Content-Type": "application/json",
        "X-Pplx-Integration": "pipedream/1.0",
      },
      data: {
        model: "sonar-pro",
        messages: [
          { role: "user", content: "Summarize this week's AI research." },
        ],
      },
    });
  },
});
```

You can swap the URL to call any [Perplexity API endpoint](/api-reference):

* `/v1/chat/completions` — Sonar chat completions
* `/v1/agent` — Agent API with third-party models and presets
* `/search` — raw ranked web results
* `/v1/embeddings` — vector embeddings
* `/v1/async/chat/completions` — async chat completions

## Example Workflows

Common Perplexity-on-Pipedream patterns:

* **Customer support automation** — incoming email triggers a Perplexity Chat Completions step that drafts a response, then logs the conversation in a CRM.
* **News-feed summarization** — new article from an RSS trigger is summarized by Perplexity and posted to a Slack channel with citations.
* **Brand monitoring** — social media mentions are piped through Perplexity for sentiment analysis and entity extraction, then written to a Google Sheet.
* **Daily research digest** — a scheduled cron triggers a Perplexity query, and the result is emailed or posted to a chat channel every morning.

## Security & Credentials

Pipedream stores your Perplexity API key encrypted at rest and injects it into every step via the `$auth` object — your key never appears in step UI or logs. You can rotate the key at any time from your account's **Connected Accounts** page.

## Links & Resources

<CardGroup>
  <Card title="Pipedream Perplexity App" icon="plug" href="https://pipedream.com/apps/perplexity">
    Official Perplexity app on Pipedream.
  </Card>

  <Card title="Pipedream Docs" icon="book" href="https://pipedream.com/docs">
    Full Pipedream documentation.
  </Card>

  <Card title="Perplexity API Reference" icon="code" href="/api-reference">
    Full Perplexity API reference.
  </Card>

  <Card title="Perplexity Models" icon="sparkles" href="/docs/sonar/models">
    Available Sonar models.
  </Card>
</CardGroup>

## Support

Need help with the integration?

* Browse the [Pipedream documentation](https://pipedream.com/docs)
* Review our [FAQ](/docs/resources/faq)


# Perplexity with SuperPlane
Source: https://docs.perplexity.ai/docs/getting-started/integrations/superplane

Run Perplexity agents inside SuperPlane workflows — research, synthesis, and analysis steps with web search, URL fetching, and source citations.

## Overview

[SuperPlane](https://superplane.com) is an open-source DevOps control plane for long-lived, event-driven workflows. It exposes Perplexity as a native **component** on the canvas — drop a Perplexity node into any workflow and it will run a Perplexity agent with web search and URL fetching, then emit the response and source citations as a payload for downstream nodes.

<Info>
  **SuperPlane** models workflows as event-driven canvases: nodes emit payloads, downstream nodes subscribe to them, and the runtime tracks every run with full observability. Learn more at [superplane.com](https://superplane.com).
</Info>

## Component: Perplexity

The Perplexity component runs a Perplexity AI agent as a workflow step. Use it for research, synthesis, automated analysis, and content generation grounded in real-time web sources.

### Action

| Action        | Description                                                              |
| ------------- | ------------------------------------------------------------------------ |
| **Run Agent** | Run a Perplexity AI agent with web search and URL fetching capabilities. |

### Configuration

| Parameter        | Description                                                                                                                   |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| **Preset**       | Agent preset to use: `fast-search`, `pro-search`, `deep-research`, or `advanced-deep-research`. When set, `Model` is ignored. |
| **Model**        | Model identifier to use when no preset is specified (e.g., `sonar-pro`).                                                      |
| **Input**        | The prompt or question for the agent. Supports SuperPlane [expressions](https://docs.superplane.com/concepts/expressions).    |
| **Instructions** | Optional system-level instructions for the agent.                                                                             |
| **Web Search**   | Enable the `web_search` tool (default: `true`).                                                                               |
| **Fetch URL**    | Enable the `fetch_url` tool (default: `true`).                                                                                |

### Output Payload

The component emits a payload with these fields downstream nodes can access via expressions:

| Field       | Description                           |
| ----------- | ------------------------------------- |
| `text`      | The generated text response.          |
| `citations` | Source citations from web results.    |
| `model`     | The specific model used for this run. |
| `usage`     | Token and cost usage information.     |

## API Key Setup

Configure the Perplexity integration in SuperPlane with your API key. Open your canvas's **Integrations** settings, add a Perplexity integration, and paste your key.

<Card title="Get API Key" icon="key" href="https://www.perplexity.ai/account/api/keys">
  Generate your Perplexity API key from the API portal.
</Card>

## Quick Start

A minimal workflow that asks Perplexity a question whenever a manual run is triggered:

<Steps>
  <Step title="Add a Manual Run trigger">
    Drop a **Manual Run** node onto the canvas — this is the workflow's entry point.
  </Step>

  <Step title="Add a Perplexity node">
    Click **+ Components**, choose **Perplexity → Run Agent**, and drag it onto the canvas. Connect **Manual Run → Perplexity**.
  </Step>

  <Step title="Configure the agent">
    In the Perplexity node:

    * **Preset**: `pro-search`
    * **Input**: `What is the latest news on nuclear fusion?`
    * **Web Search**: enabled
    * **Fetch URL**: enabled
  </Step>

  <Step title="Run">
    Click **Run** on the Manual Run node. The Perplexity node emits a payload with `text`, `citations`, `model`, and `usage`.
  </Step>
</Steps>

## Reading the Response Downstream

Use SuperPlane expressions to pipe the Perplexity output into the next node — for example, a Slack message or a database write:

```
Research result: {{ $['Perplexity'].data.text }}

Sources:
{{ $['Perplexity'].data.citations }}
```

In condition fields (If / Filter), write expressions without `{{ }}`:

```
$['Perplexity'].data.usage.total_tokens > 1000
```

## Use Cases

* **Incident triage** — when an alert fires, run a Perplexity research step to gather background on a vendor, library, or CVE before paging on-call.
* **Release notes synthesis** — turn raw GitHub commit diffs into customer-facing release notes with citations.
* **Competitive monitoring** — schedule a daily canvas that queries Perplexity for industry news and posts a summary to a Slack channel.
* **Document grounding** — feed a Perplexity run's output into a downstream component that updates a Notion page or knowledge base.

## Links & Resources

<CardGroup>
  <Card title="SuperPlane Perplexity Component" icon="book" href="https://docs.superplane.com/components/perplexity">
    Official component documentation.
  </Card>

  <Card title="SuperPlane Docs" icon="globe" href="https://docs.superplane.com">
    Full SuperPlane documentation.
  </Card>

  <Card title="Perplexity Agent API" icon="robot" href="/docs/agent-api/quickstart">
    How the Perplexity agent layer works.
  </Card>

  <Card title="Perplexity Models" icon="sparkles" href="/docs/sonar/models">
    Available Sonar models.
  </Card>
</CardGroup>

## Support

Need help with the integration?

* Browse the [SuperPlane documentation](https://docs.superplane.com)
* Review our [FAQ](/docs/resources/faq)


# Perplexity with the Vercel AI SDK
Source: https://docs.perplexity.ai/docs/getting-started/integrations/vercel-ai-sdk

Use Perplexity's web-grounded models with the Vercel AI SDK through the official @ai-sdk/perplexity provider.

## Overview

The [Vercel AI SDK](https://ai-sdk.dev) is a TypeScript-first toolkit for building AI-powered apps with a unified provider interface, streaming primitives, and React hooks. The official `@ai-sdk/perplexity` provider gives you full access to Perplexity's Sonar models — including streaming, citations, image results, and PDF inputs — with a one-line model identifier.

<Info>
  **Vercel AI SDK** powers `generateText`, `streamText`, `generateObject`, and React hooks like `useChat` and `useCompletion`. Learn more at [ai-sdk.dev](https://ai-sdk.dev).
</Info>

## Installation

<Tabs>
  <Tab title="pnpm">
    ```bash theme={null}
    pnpm add @ai-sdk/perplexity ai
    ```
  </Tab>

  <Tab title="npm">
    ```bash theme={null}
    npm install @ai-sdk/perplexity ai
    ```
  </Tab>

  <Tab title="yarn">
    ```bash theme={null}
    yarn add @ai-sdk/perplexity ai
    ```
  </Tab>

  <Tab title="bun">
    ```bash theme={null}
    bun add @ai-sdk/perplexity ai
    ```
  </Tab>
</Tabs>

## API Key Setup

Set your Perplexity API key:

```bash theme={null}
export PERPLEXITY_API_KEY="your_api_key_here"
```

<Card title="Get API Key" icon="key" href="https://www.perplexity.ai/account/api/keys">
  Generate your Perplexity API key from the API portal.
</Card>

## Quick Start

Import the default provider instance and call `generateText`:

```ts theme={null}
import { perplexity } from "@ai-sdk/perplexity";
import { generateText } from "ai";

const { text } = await generateText({
  model: perplexity("sonar-pro"),
  prompt: "What are the latest developments in quantum computing?",
});

console.log(text);
```

## Accessing Citations

Every response includes a `sources` array of the URLs Perplexity consulted:

```ts theme={null}
import { perplexity } from "@ai-sdk/perplexity";
import { generateText } from "ai";

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

console.log(text);
console.log(sources);
```

## Provider Options

Pass Perplexity-specific parameters through `providerOptions.perplexity`:

```ts theme={null}
import { perplexity } from "@ai-sdk/perplexity";
import { generateText } from "ai";

const result = await generateText({
  model: perplexity("sonar-pro"),
  prompt: "What are the latest developments in quantum computing?",
  providerOptions: {
    perplexity: {
      return_images: true,
      search_recency_filter: "week",
    },
  },
});

console.log(result.providerMetadata);
// {
//   perplexity: {
//     usage: { citationTokens: 5286, numSearchQueries: 1 },
//     images: [{ imageUrl: "...", originUrl: "...", height: 1280, width: 720 }],
//   },
// }
```

Any other [Perplexity API parameter](/api-reference/chat-completions-post) can be passed the same way.

| Option                  | Type      | Description                                        |
| ----------------------- | --------- | -------------------------------------------------- |
| `return_images`         | `boolean` | Include images in the response (Tier-2+ accounts). |
| `search_recency_filter` | `string`  | One of `'hour'`, `'day'`, `'week'`, `'month'`.     |

## Custom Provider Configuration

Use `createPerplexity` when you need a custom base URL, headers, or a custom fetch implementation:

```ts theme={null}
import { createPerplexity } from "@ai-sdk/perplexity";

const perplexity = createPerplexity({
  apiKey: process.env.PERPLEXITY_API_KEY ?? "",
  baseURL: "https://api.perplexity.ai",
  headers: {
    "X-Pplx-Integration": "my-app/1.0",
  },
});
```

## PDF Inputs

Sonar models can read PDF files passed as `file` message parts:

```ts theme={null}
import { perplexity } from "@ai-sdk/perplexity";
import { generateText } from "ai";
import fs from "node:fs";

const result = await generateText({
  model: perplexity("sonar-pro"),
  messages: [
    {
      role: "user",
      content: [
        { type: "text", text: "What is this document about?" },
        {
          type: "file",
          data: fs.readFileSync("./data/ai.pdf"),
          mediaType: "application/pdf",
          filename: "ai.pdf",
        },
      ],
    },
  ],
});
```

You can also pass a PDF URL:

```ts theme={null}
{
  type: "file",
  data: new URL("https://example.com/document.pdf"),
  mediaType: "application/pdf",
  filename: "document.pdf",
}
```

## Supported Models

| Model                 | Image Input | Object Generation |
| --------------------- | ----------- | ----------------- |
| `sonar`               | Yes         | Yes               |
| `sonar-pro`           | Yes         | Yes               |
| `sonar-reasoning`     | Yes         | Yes               |
| `sonar-reasoning-pro` | Yes         | Yes               |
| `sonar-deep-research` | No          | Yes               |

See [all available models](/docs/sonar/models) for full capability details.

## Streaming and React Hooks

The provider works seamlessly with `streamText`, `useChat`, and `useCompletion` from `ai/react`. Drop `perplexity("sonar-pro")` into any AI SDK helper that takes a model:

```ts theme={null}
import { perplexity } from "@ai-sdk/perplexity";
import { streamText } from "ai";

const result = streamText({
  model: perplexity("sonar"),
  prompt: "Give me a one-sentence summary of this week's AI news.",
});

for await (const chunk of result.textStream) {
  process.stdout.write(chunk);
}
```

## Links & Resources

<CardGroup>
  <Card title="Vercel AI SDK Provider" icon="book" href="https://ai-sdk.dev/providers/ai-sdk-providers/perplexity">
    Official `@ai-sdk/perplexity` provider docs.
  </Card>

  <Card title="Vercel AI SDK Docs" icon="globe" href="https://ai-sdk.dev/docs">
    Full Vercel AI SDK documentation.
  </Card>

  <Card title="Perplexity API Reference" icon="code" href="/api-reference/chat-completions-post">
    Full Perplexity API parameter reference.
  </Card>

  <Card title="Perplexity Models" icon="sparkles" href="/docs/sonar/models">
    Available Sonar models and capabilities.
  </Card>
</CardGroup>

## Support

Need help with the integration?

* Browse the [Vercel AI SDK documentation](https://ai-sdk.dev/docs)
* Review our [FAQ](/docs/resources/faq)


# Overview
Source: https://docs.perplexity.ai/docs/getting-started/overview

Perplexity API Platform — build with Sonar, Search, Agent, and Embeddings APIs. Real-time, web-wide research and Q&A capabilities for your products.

<div>
  <div>
    <div>
      <PerplexityLogo />
    </div>

    <div>
      <span>
        Power your products with unparalleled real-time, web-wide research and Q\&A capabilities.
      </span>
    </div>
  </div>

  <QuickstartBanner />

  <UseCaseTabs />

  <div>
    <div>
      <h2>Available APIs</h2>
    </div>

    <div>
      <div>
        <a href="/docs/agent-api/quickstart">
          <img alt="Agent API" />
        </a>

        <a href="/docs/agent-api/quickstart">
          Agent API
        </a>

        <p>Access third-party models with web search tools and presets.</p>
      </div>

      <div>
        <a href="/docs/search/quickstart">
          <img alt="Search API" />
        </a>

        <a href="/docs/search/quickstart">
          Search API
        </a>

        <p>Get raw, ranked web search results with advanced filtering and real-time data.</p>
      </div>

      <div>
        <a href="/docs/embeddings/quickstart">
          <img alt="Embeddings API" />
        </a>

        <a href="/docs/embeddings/quickstart">
          Embeddings API
        </a>

        <p>Generate high-quality embeddings for semantic search and RAG pipelines.</p>
      </div>
    </div>
  </div>
</div>


# Pricing
Source: https://docs.perplexity.ai/docs/getting-started/pricing



<Info>
  This page shows **pricing information** to help you understand API costs.

  For **billing setup**, payment methods, and usage monitoring, visit the [Admin section](/docs/getting-started/api-groups). For **rate limits**, see the [Rate Limits & Usage Tiers](/docs/admin/rate-limits-usage-tiers) page.
</Info>

## Agent API Pricing

The Agent API provides access to third-party models from OpenAI, Anthropic, Google, and xAI with **transparent, token-based pricing** at direct provider rates with no markup.

### Model Pricing

Agent API pricing varies by provider and model, with each provider offering multiple models at different price points.

<Card title="View Complete Third-Party Model Pricing" icon="table" href="/docs/agent-api/models">
  See the full pricing breakdown for all available models from OpenAI, Anthropic, Google, and xAI, including cache rates and provider documentation links on the [Agent API Models page](/docs/agent-api/models).
</Card>

### Tool Pricing

When using tools with the Agent API:

| Tool                 |          Price          | Description                                                                     |
| -------------------- | :---------------------: | ------------------------------------------------------------------------------- |
| **`web_search`**     |  \$0.005 per invocation | Performs web searches to retrieve current information                           |
| **`fetch_url`**      | \$0.0005 per invocation | Fetches and extracts content from specific URLs                                 |
| **`people_search`**  |  \$0.005 per invocation | Looks up professionals, employees, and people. \$5 per 1,000 tool invocations   |
| **`finance_search`** |  \$0.005 per invocation | Retrieves financial data and market information. \$5 per 1,000 tool invocations |

<Note>
  Tool costs are separate from model token costs. Each tool invocation is billed individually — if a model makes 3 `web_search` calls and 2 `people_search` calls during a request, you pay model tokens + (3 × \$0.005) + (2 × \$0.005) for tools.
</Note>

## Search API Pricing

| API            | Price per 1K requests | Description                                    |
| -------------- | :-------------------: | ---------------------------------------------- |
| **Search API** |         \$5.00        | Raw web search results with advanced filtering |

<Note>
  **No token costs:** Search API charges per request only, with no additional token-based pricing.
</Note>

## Sonar API Pricing

<Info>
  **Total cost per query** = Token costs + Request fee (varies by search context size, applies to Sonar, Sonar Pro, and Sonar Reasoning Pro models only)
</Info>

<Tabs>
  <Tab title="Token Pricing">
    ## Token Pricing

    **Token pricing** is based on the number of tokens in your request and response.

    | Model                   | Input Tokens (\$/1M) | Output Tokens (\$/1M) | Citation Tokens (\$/1M) | Search Queries (\$/1K) | Reasoning Tokens (\$/1M) |
    | ----------------------- | :------------------: | :-------------------: | :---------------------: | :--------------------: | :----------------------: |
    | **Sonar**               |          \$1         |          \$1          |            -            |            -           |             -            |
    | **Sonar Pro**           |          \$3         |          \$15         |            -            |            -           |             -            |
    | **Sonar Reasoning Pro** |          \$2         |          \$8          |            -            |            -           |             -            |
    | **Sonar Deep Research** |          \$2         |          \$8          |           \$2           |           \$5          |            \$3           |
  </Tab>

  <Tab title="Request Pricing">
    ## Request Pricing by Search Context Size

    **Search context** determines how much web information is retrieved. Higher context = more comprehensive results. The following table shows the request fee for each model for every **1000 requests**.

    | Model                   | Low Context Size | Medium Context Size | High Context Size |
    | ----------------------- | :--------------: | :-----------------: | :---------------: |
    | **Sonar**               |        \$5       |         \$8         |        \$12       |
    | **Sonar Pro**           |        \$6       |         \$10        |        \$14       |
    | **Sonar Reasoning Pro** |        \$6       |         \$10        |        \$14       |

    <Note>
      * **Low**: (default) fastest, cheapest
      * **Medium**: Balanced cost/quality
      * **High**: Maximum search depth, best for research

      [Learn more about search context →](https://docs.perplexity.ai/docs/sonar/filters#context-size-control)
    </Note>
  </Tab>

  <Tab title="Pro Search Pricing">
    ## Pro Search Pricing (Pro Search for Sonar Pro)

    **Pro Search** enhances Sonar Pro with automated tool usage and multi-step reasoning. When enabled, the model can perform multiple web searches and fetch URL content to answer complex queries. [Learn more about Pro Search here](/docs/sonar/pro-search/quickstart).

    <Info>
      Pro Search requires `stream: true` and is enabled via the `search_type` parameter in `web_search_options`.
    </Info>

    ### Search Type Options

    | Search Type | Description                                        |   Request Fee (per 1K)   |
    | ----------- | -------------------------------------------------- | :----------------------: |
    | **`fast`**  | (default) Standard Sonar Pro behavior              |     \$6 / \$10 / \$14    |
    | **`pro`**   | Multi-step tool usage for complex queries          |    \$14 / \$18 / \$22    |
    | **`auto`**  | Automatic classification based on query complexity | Varies by classification |

    <Note>
      Request fees vary by search context size (Low / Medium / High). Token pricing remains the same as standard Sonar Pro (\$3 per 1M input, \$15 per 1M output).
    </Note>
  </Tab>
</Tabs>

## Embeddings API Pricing

Generate high-quality text embeddings for semantic search, retrieval-augmented generation (RAG), and other machine learning applications.

### Standard Embeddings

| Model                | Dimensions | Price (\$/1M tokens) |
| -------------------- | :--------: | :------------------: |
| `pplx-embed-v1-0.6b` |    1024    |        \$0.004       |
| `pplx-embed-v1-4b`   |    2560    |        \$0.03        |

### Contextualized Embeddings

| Model                        | Dimensions | Price (\$/1M tokens) |
| ---------------------------- | :--------: | :------------------: |
| `pplx-embed-context-v1-0.6b` |    1024    |        \$0.008       |
| `pplx-embed-context-v1-4b`   |    2560    |        \$0.05        |

<Card title="View Embeddings API Documentation" icon="cube" href="/docs/embeddings/quickstart">
  Learn how to use the Embeddings API for semantic search, RAG, and more.
</Card>

<AccordionGroup>
  <Accordion title="Token and Cost Glossary">
    ### Input Tokens

    The number of tokens in your prompt or message to the API. This includes:

    * Your question or instruction
    * Any context or examples you provide
    * System messages and formatting

    **Example:** "What is the weather in New York?" = \~8 input tokens

    ### Output Tokens

    The number of tokens in the API's response. This includes:

    * The generated answer or content
    * Any explanations or additional context
    * Search results and references

    **Example:** "The weather in New York is currently sunny with a temperature of 72°F." = \~15 output tokens

    ### Citation Tokens

    Tokens used specifically for generating search results and references in responses. Only applies to **Sonar Deep Research** model.

    **Example:** Including source links, reference numbers, and bibliographic information

    ### Search Context Size vs Context Window

    **Search context size** is *not* the same as the **context window**.

    * **Search context size**: How much web information is retrieved during search (affects request pricing)
    * **Context window**: Maximum tokens the model can process in one request (affects token limits)

    ### Search Queries

    The number of individual searches conducted by **Sonar Deep Research** during query processing. This is separate from your initial user query.

    * The model automatically determines how many searches are needed
    * You cannot control the exact number of search queries
    * The `reasoning_effort` parameter influences the number of searches performed
    * Only applies to **Sonar Deep Research** model

    ### Reasoning Tokens

    Tokens used for step-by-step logical reasoning and problem-solving. Only applies to **Sonar Deep Research** model.

    **Example:** Breaking down a complex math problem into sequential steps with explanations

    <Info>
      **Token Calculation:** 1 token ≈ 4 characters in English text. The exact count may vary based on language and content complexity.
    </Info>
  </Accordion>
</AccordionGroup>

## Cost Examples

<CardGroup>
  <Card title="Sonar Web Search Example" icon="calculator">
    **Sonar** • 500 input + 200 output tokens

    <Tabs>
      <Tab title="Low">
        | Component     | Cost         |
        | ------------- | ------------ |
        | Input tokens  | \$0.0005     |
        | Output tokens | \$0.0002     |
        | Request fee   | \$0.005      |
        | **Total**     | **\$0.0057** |
      </Tab>

      <Tab title="Medium">
        | Component     | Cost         |
        | ------------- | ------------ |
        | Input tokens  | \$0.0005     |
        | Output tokens | \$0.0002     |
        | Request fee   | \$0.008      |
        | **Total**     | **\$0.0087** |
      </Tab>

      <Tab title="High">
        | Component     | Cost         |
        | ------------- | ------------ |
        | Input tokens  | \$0.0005     |
        | Output tokens | \$0.0002     |
        | Request fee   | \$0.012      |
        | **Total**     | **\$0.0127** |
      </Tab>
    </Tabs>
  </Card>

  <Card title="Deep Research Example" icon="chart-area-line">
    **Sonar Deep Research**

    <Tabs>
      <Tab title="Low">
        | Component                | Cost           |
        | ------------------------ | -------------- |
        | Input tokens (33)        | \$0.000066     |
        | Output tokens (7163)     | \$0.057304     |
        | Citation tokens (20016)  | \$0.040032     |
        | Reasoning tokens (73997) | \$0.221991     |
        | Search queries (18)      | \$0.09         |
        | **Total**                | **\$0.409393** |
      </Tab>

      <Tab title="Medium">
        | Component                 | Cost        |
        | ------------------------- | ----------- |
        | Input tokens (7)          | \$0.00      |
        | Output tokens (3847)      | \$0.031     |
        | Citation tokens (47293)   | \$0.095     |
        | Reasoning tokens (308156) | \$0.924     |
        | Search queries (28)       | \$0.14      |
        | **Total**                 | **\$1.190** |
      </Tab>

      <Tab title="High">
        | Component                 | Cost        |
        | ------------------------- | ----------- |
        | Input tokens (8)          | \$0.00      |
        | Output tokens (4435)      | \$0.035     |
        | Citation tokens (58196)   | \$0.116     |
        | Reasoning tokens (339594) | \$1.019     |
        | Search queries (30)       | \$0.15      |
        | **Total**                 | **\$1.320** |
      </Tab>
    </Tabs>
  </Card>
</CardGroup>

## Purchase Options

<CardGroup>
  <Card title="Perplexity API Platform on AWS Marketplace" icon="aws" href="/docs/resources/aws-marketplace">
    Purchase API credits through AWS Marketplace with consolidated billing and enterprise procurement.
  </Card>

  <Card title="Contact Sales Team" icon="file-pencil" href="https://perplexity.typeform.com/to/nXeehCGo">
    Fill out our enterprise inquiry form to discuss custom pricing, dedicated support, and enterprise features for teams and organizations.
  </Card>
</CardGroup>


# Quickstart
Source: https://docs.perplexity.ai/docs/getting-started/quickstart

Generate an API key and make your first call in < 3 minutes.

## Generating an API Key

<Card title="Get your Perplexity API Key" icon="key" href="https://console.perplexity.ai">
  Navigate to the **API Keys** tab in the API Portal and generate a new key.
</Card>

<Info>
  See the [API Groups](/docs/getting-started/api-groups) page to learn more about API groups.
</Info>

## Overview

The Perplexity API provides four core APIs for different use cases: **Agent API** for accessing OpenAI, Anthropic, Google, and xAI models with unified search tools and transparent pricing, **Search** for ranked web search results, **Sonar** for web-grounded AI responses with Sonar models, and **Embeddings** for generating text embeddings.

All APIs support both REST and SDK access with streaming, filtering, and advanced controls.

## Available APIs

<CardGroup>
  <Card title="Agent API" icon="code-circle" href="/docs/agent-api/quickstart">
    Third-party models from OpenAI, Anthropic, Google, and more with presets and web search tools.
  </Card>

  <Card title="Search" icon="search" href="/docs/search/quickstart">
    Ranked web search results with filtering, multi-query support, and domain controls.
  </Card>

  <Card title="Sonar" icon="message" href="/docs/sonar/quickstart">
    Web-grounded AI responses with citations, conversation context, and streaming support.
  </Card>

  <Card title="Embeddings" icon="cube" href="/docs/embeddings/quickstart">
    Generate high-quality text embeddings for semantic search and RAG.
  </Card>
</CardGroup>

## Choosing the Right API

<AccordionGroup>
  <Accordion title="Use the Agent API when..." icon="code-circle">
    * You need **multi-provider access** to OpenAI, Anthropic, Google, and more models through one API
    * You want **granular control** over model selection, reasoning, token budgets, and tools
    * You want **presets** for common use configurations or full customization for advanced workflows

    **Best for:** Agentic workflows, custom AI applications, multi-model experimentation
  </Accordion>

  <Accordion title="Use the Search API when..." icon="search">
    * You need **raw search results** without LLM processing
    * You want to **build custom AI workflows** with your own models
    * You need **search data** for indexing, analysis, or training

    **Best for:** Custom AI pipelines, data collection, search integration
  </Accordion>

  <Accordion title="Use the Sonar API when..." icon="message">
    * You want **Perplexity's Sonar models** optimized for research and Q\&A
    * You need **built-in citations** and conversation context
    * You prefer **simplicity**—just send a message and get a researched answer

    **Best for:** AI assistants, research tools, Q\&A applications
  </Accordion>
</AccordionGroup>

## Installation

Install the SDK for your preferred language:

<CodeGroup>
  ```bash Python theme={null}
  pip install perplexityai
  ```

  ```bash Typescript theme={null}
  npm install @perplexity-ai/perplexity_ai
  ```
</CodeGroup>

## Authentication

Set your API key as an environment variable:

<Tabs>
  <Tab title="macOS/Linux">
    ```bash theme={null}
    export PERPLEXITY_API_KEY="your_api_key_here"
    ```
  </Tab>

  <Tab title="Windows">
    ```powershell theme={null}
    setx PERPLEXITY_API_KEY "your_api_key_here"
    ```
  </Tab>
</Tabs>

<Note>
  **OpenAI SDK Compatible:** Perplexity's API supports the OpenAI Chat Completions format. You can use OpenAI client libraries by pointing to our endpoint. See the [OpenAI Compatibility Guide](/docs/agent-api/openai-compatibility) for examples.
</Note>

## Making Your First API Call

Choose your API based on your use case:

<Tabs>
  <Tab title="Agent API">
    Use for third-party models with web search tools and presets:

    <CodeGroup>
      ```python Python theme={null}
      from perplexity import Perplexity

      # Initialize the client (uses PERPLEXITY_API_KEY environment variable)
      client = Perplexity()

      # Make the API call with a preset
      response = client.responses.create(
          preset="pro-search",
          input="What are the key differences between the latest iPhone and Samsung Galaxy flagship phones released this year?",
      )

      # Print the AI's response
      print(response.output_text)
      ```

      ```typescript Typescript theme={null}
      import Perplexity from '@perplexity-ai/perplexity_ai';

      // Initialize the client (uses PERPLEXITY_API_KEY environment variable)
      const client = new Perplexity();

      // Make the API call with a preset
      const response = await client.responses.create({
          preset: "pro-search",
          input: "What are the key differences between the latest iPhone and Samsung Galaxy flagship phones released this year?",
      });

      // Print the AI's response
      console.log(response.output_text);
      ```

      ```bash cURL theme={null}
      curl https://api.perplexity.ai/v1/agent \
        -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{
          "preset": "pro-search",
          "input": "What are the key differences between the latest iPhone and Samsung Galaxy flagship phones released this year?"
        }' | jq
      ```
    </CodeGroup>

    <Accordion title="Example Response">
      The response includes structured output with tool usage and citations:

      ```json theme={null}
      {
        "background": false,
        "completed_at": 1756485272,
        "created_at": 1756485272,
        "error": null,
        "frequency_penalty": 0,
        "id": "resp_1234567890",
        "incomplete_details": null,
        "instructions": "## Abstract\n<role>\nYou are an AI assistant developed by Perplexity AI. Given a user's query, your goal is to...",
        "max_output_tokens": null,
        "max_tool_calls": null,
        "metadata": {},
        "model": "openai/gpt-5.1",
        "object": "response",
        "output": [
          {
            "type": "message",
            "id": "msg_abc123",
            "role": "assistant",
            "status": "completed",
            "content": [
              {
                "type": "output_text",
                "text": "Recent developments in AI include...",
                "annotations": [
                  {
                    "type": "citation",
                    "url": "https://example.com/article1"
                  }
                ],
                "logprobs": []
              }
            ]
          }
        ],
        "parallel_tool_calls": true,
        "presence_penalty": 0,
        "previous_response_id": null,
        "prompt_cache_key": null,
        "reasoning": null,
        "safety_identifier": null,
        "service_tier": "default",
        "status": "completed",
        "store": true,
        "temperature": 1,
        "text": {
          "format": {
            "type": "text"
          }
        },
        "tool_choice": "auto",
        "tools": [
          {
            "type": "web_search"
          },
          {
            "type": "fetch_url"
          }
        ],
        "top_logprobs": 0,
        "top_p": 1,
        "truncation": "disabled",
        "usage": {
          "cost": {
            "currency": "USD",
            "input_cost": 0.0046,
            "output_cost": 0.0078,
            "tool_calls_cost": 0.005,
            "total_cost": 0.0174
          },
          "input_tokens": 3681,
          "input_tokens_details": {
            "cached_tokens": 0
          },
          "output_tokens": 780,
          "output_tokens_details": {
            "reasoning_tokens": 0
          },
          "tool_calls_details": {
            "search_web": {
              "invocation": 1
            }
          },
          "total_tokens": 4461
        },
        "user": null
      }
      ```
    </Accordion>
  </Tab>

  <Tab title="Search API">
    Use for ranked web search results without LLM processing:

    <CodeGroup>
      ```python Python theme={null}
      from perplexity import Perplexity

      # Initialize the client (uses PERPLEXITY_API_KEY environment variable)
      client = Perplexity()

      # Make the API call
      search = client.search.create(
          query="SpaceX Starship launch updates 2026",
          max_results=5
      )

      # Print the search results
      for result in search.results:
          print(f"{result.title}: {result.url}")
      ```

      ```typescript TypeScript theme={null}
      import Perplexity from '@perplexity-ai/perplexity_ai';

      // Initialize the client (uses PERPLEXITY_API_KEY environment variable)
      const client = new Perplexity();

      // Make the API call
      const search = await client.search.create({
          query: "SpaceX Starship launch updates 2026",
          max_results: 5
      });

      // Print the search results
      for (const result of search.results) {
          console.log(`${result.title}: ${result.url}`);
      }
      ```

      ```bash cURL theme={null}
      curl -X POST 'https://api.perplexity.ai/search' \
        -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{
          "query": "SpaceX Starship launch updates 2026",
          "max_results": 5
        }' | jq
      ```
    </CodeGroup>

    <Accordion title="Example Response">
      The response includes ranked search results with titles, URLs, and snippets:

      ```json theme={null}
      {
        "results": [
          {
            "title": "SpaceX Starship Flight 10: Full Mission Recap",
            "url": "https://example.com/starship-flight-10",
            "snippet": "SpaceX successfully completed its tenth Starship test flight, achieving full booster recovery and orbital insertion...",
            "date": "2026-02-20",
            "last_updated": "2026-02-21"
          },
          {
            "title": "Starship Launch Manifest: 2026 Schedule and Updates",
            "url": "https://example.com/starship-2026-schedule",
            "snippet": "SpaceX has announced an ambitious 2026 launch manifest for Starship, targeting monthly flights and the first cargo mission...",
            "date": "2026-01-15",
            "last_updated": "2026-03-01"
          }
        ],
        "query_info": {
          "query": "SpaceX Starship launch updates 2026",
          "normalized_query": "spacex starship launch updates 2026"
        }
      }
      ```
    </Accordion>
  </Tab>

  <Tab title="Sonar API">
    Use for web-grounded AI responses with Perplexity's Sonar models:

    <CodeGroup>
      ```python Python theme={null}
      from perplexity import Perplexity

      # Initialize the client (uses PERPLEXITY_API_KEY environment variable)
      client = Perplexity()

      # Make the API call
      completion = client.chat.completions.create(
          model="sonar-pro",
          messages=[
              {"role": "user", "content": "What breakthroughs in fusion energy have been announced this year?"}
          ]
      )

      # Print the AI's response
      print(completion.choices[0].message.content)
      ```

      ```typescript Typescript theme={null}
      import Perplexity from '@perplexity-ai/perplexity_ai';

      // Initialize the client (uses PERPLEXITY_API_KEY environment variable)
      const client = new Perplexity();

      // Make the API call
      const completion = await client.chat.completions.create({
          model: "sonar-pro",
          messages: [
              { role: "user", content: "What breakthroughs in fusion energy have been announced this year?" }
          ]
      });

      // Print the AI's response
      console.log(completion.choices[0].message.content);
      ```

      ```bash cURL theme={null}
      curl https://api.perplexity.ai/v1/sonar \
        -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{
          "model": "sonar-pro",
          "messages": [
            {
              "role": "user",
              "content": "What breakthroughs in fusion energy have been announced this year?"
            }
          ]
        }' | jq
      ```
    </CodeGroup>

    <Accordion title="Example Response">
      The response includes the AI's answer with citations and search results:

      ```json theme={null}
      {
        "id": "66f3900f-e32e-4d59-b677-1a55de188262",
        "model": "sonar-pro",
        "created": 1756485272,
        "object": "chat.completion",
        "choices": [
          {
            "index": 0,
            "finish_reason": "stop",
            "message": {
              "role": "assistant",
              "content": "Several notable breakthroughs in fusion energy have been announced this year...[1][2]"
            }
          }
        ],
        "usage": {
          "prompt_tokens": 12,
          "completion_tokens": 315,
          "total_tokens": 327
        },
        "citations": [
          "https://example.com/article1",
          "https://example.com/article2"
        ]
      }
      ```
    </Accordion>
  </Tab>
</Tabs>

## Streaming Responses

Enable streaming for real-time output with either API:

<Tabs>
  <Tab title="Agent API">
    <CodeGroup>
      ```python Python theme={null}
      from perplexity import Perplexity

      client = Perplexity()

      # Make the streaming API call
      stream = client.responses.create(
          preset="pro-search",
          input="What are the most promising quantum computing startups and their recent funding rounds?",
          stream=True
      )

      # Process the streaming response
      for chunk in stream:
          if chunk.type == "response.output_text.delta":
              print(chunk.delta, end="", flush=True)
      ```

      ```typescript Typescript theme={null}
      import Perplexity from '@perplexity-ai/perplexity_ai';

      const client = new Perplexity();

      // Make the streaming API call
      const stream = await client.responses.create({
          preset: "pro-search",
          input: "What are the most promising quantum computing startups and their recent funding rounds?",
          stream: true
      });

      // Process the streaming response
      for await (const chunk of stream) {
          if (chunk.type === "response.output_text.delta") {
              process.stdout.write((chunk as any).delta);
          }
      }
      ```

      ```bash cURL theme={null}
      curl https://api.perplexity.ai/v1/agent \
        -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{
          "preset": "pro-search",
          "input": "What are the most promising quantum computing startups and their recent funding rounds?",
          "stream": true
        }'
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Sonar API">
    <CodeGroup>
      ```python Python theme={null}
      from perplexity import Perplexity

      client = Perplexity()

      # Make the streaming API call
      stream = client.chat.completions.create(
          model="sonar-pro",
          messages=[
              {"role": "user", "content": "What are the most promising quantum computing startups and their recent funding rounds?"}
          ],
          stream=True
      )

      # Process the streaming response
      for chunk in stream:
          if chunk.choices[0].delta.content:
              print(chunk.choices[0].delta.content, end="")
      ```

      ```typescript Typescript theme={null}
      import Perplexity from '@perplexity-ai/perplexity_ai';

      const client = new Perplexity();

      // Make the streaming API call
      const stream = await client.chat.completions.create({
          model: "sonar-pro",
          messages: [
              { role: "user", content: "What are the most promising quantum computing startups and their recent funding rounds?" }
          ],
          stream: true
      });

      // Process the streaming response
      for await (const chunk of stream) {
          if (chunk.choices[0]?.delta?.content) {
              process.stdout.write((chunk.choices[0]?.delta?.content ?? '') as string);
          }
      }
      ```

      ```bash cURL theme={null}
      curl https://api.perplexity.ai/v1/sonar \
        -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{
          "model": "sonar-pro",
          "messages": [
            {
              "role": "user",
              "content": "What are the most promising quantum computing startups and their recent funding rounds?"
            }
          ],
          "stream": true
        }'
      ```
    </CodeGroup>
  </Tab>
</Tabs>

<Info title="Complete Streaming Guide" href="/docs/agent-api/output-control#streaming-responses">
  For a full guide on streaming, including parsing, error handling, citation management, and best practices, see our [streaming guide](/docs/agent-api/output-control#streaming-responses).
</Info>

## Next Steps

Now that you've made your first API call, explore each API in depth:

<CardGroup>
  <Card title="Agent API" icon="code-circle" href="/docs/agent-api/quickstart">
    Get started with third-party models and presets
  </Card>

  <Card title="Search API" icon="search" href="/docs/search/quickstart">
    Get started with web search results
  </Card>

  <Card title="Sonar API" icon="message" href="/docs/sonar/quickstart">
    Get started with web-grounded AI responses
  </Card>

  <Card title="Embeddings API" icon="cube" href="/docs/embeddings/quickstart">
    Get started with text embeddings
  </Card>
</CardGroup>

### Additional Resources

<CardGroup>
  <Card title="Perplexity SDK" icon="book" href="/docs/sdk/overview">
    Learn about the official Perplexity SDK with type safety and async support
  </Card>

  <Card title="Models" icon="brain" href="/docs/sonar/models">
    Explore available models and their capabilities
  </Card>

  <Card title="API Reference" icon="file-code" href="/api-reference/sonar-post">
    View complete API documentation with detailed endpoint specifications
  </Card>

  <Card title="Examples" icon="player-play" href="/docs/cookbook/index">
    Explore code examples, tutorials, and integration patterns
  </Card>
</CardGroup>

<Info>
  Need help? Check out our [community](https://community.perplexity.ai) for support and discussions with other developers.
</Info>


# AWS Marketplace
Source: https://docs.perplexity.ai/docs/resources/aws-marketplace

Subscribe to the Perplexity API Platform through AWS Marketplace for consolidated billing and enterprise procurement.

The Perplexity API Platform is available as a SaaS listing on AWS Marketplace. You purchase API credits through your AWS account — credits are applied to your Perplexity API balance and work across all APIs (Sonar, Agent, Search, and Embeddings).

<Frame>
  <img alt="Perplexity API Platform on AWS Marketplace" />
</Frame>

<Note>
  This listing is for the **API Platform** (Sonar, Agent API, Search API, and Embeddings). It's a separate product from **Enterprise Pro**, which doesn't include API access.
</Note>

## Why Subscribe Through AWS Marketplace?

Purchasing through AWS Marketplace offers several advantages over direct billing:

* **Consolidated AWS billing** — charges appear on your existing AWS invoice alongside other AWS services, simplifying finance and accounting workflows
* **Enterprise procurement** — satisfies procurement requirements for organizations that mandate AWS Marketplace purchases; no separate vendor relationship needed
* **EDP eligible** — purchases count toward your AWS Enterprise Discount Program (EDP) commitments
* **Simplified vendor management** — no separate contract or payment method to maintain; AWS handles invoicing

<Card title="View the listing on AWS Marketplace" icon="aws" href="https://aws.amazon.com/marketplace/pp/prodview-fslss6gnscauq">
  Subscribe and get started with the Perplexity API Platform.
</Card>

## Pricing

The Perplexity API Platform on AWS Marketplace is available as a **1-month contract** with API platform credits:

| Plan                     |       Credits       | Contract |
| ------------------------ | :-----------------: | :------: |
| **API Platform Credits** | Starting at \$1,000 |  1-month |

Credits are denominated 1:1 with USD — 1 credit = \$1. Credits are applied to your account balance and drawn down as you make API requests.

<Note>
  All Perplexity API products — Sonar, Agent API, Search API, and Embeddings — draw from the same shared credit pool. You don't need separate budgets per product.

  For per-request and per-token pricing details, see the <u>[Pricing page](/docs/getting-started/pricing)</u>.
</Note>

## How to Subscribe

<Tip>
  Credits don't expire — the **1-month contract** refers to the billing cycle, not a usage deadline, so unused credits remain on your balance.
</Tip>

1. Visit the <u>[Perplexity API Platform listing](https://aws.amazon.com/marketplace/pp/prodview-fslss6gnscauq)</u> on AWS Marketplace
2. Click **View purchase options**
3. Choose your credit amount, then click **Create contract**
4. Confirm the purchase — AWS will process the subscription and notify you by email

<Frame>
  <img alt="AWS Marketplace pricing — API platform credits at $1,000/month" />
</Frame>

Once your subscription is confirmed, you'll receive instructions to link your AWS Marketplace account to the Perplexity API Platform.

## Getting Started After Subscribing

After your AWS Marketplace subscription is confirmed:

1. **Sign in or create an account** — go to <u>[console.perplexity.ai](https://console.perplexity.ai)</u> and sign in with your Perplexity account (or create one if you don't have one yet)
2. **Link your subscription** — follow the prompts in the console to connect your AWS Marketplace purchase to your Perplexity account; this associates your purchased credits with your API Group
3. **Set up your API Group** — your credits are tied to an API Group (your organization's workspace in the API Portal). The person who completes the setup becomes the Admin, with full access to billing, API keys, and member invitations. Additional members can join as Admins (full access) or Members (view-only). See <u>[API Groups & Billing](/docs/getting-started/api-groups)</u>.
4. **Generate an API key** — go to API Keys in the console to create a key for your API Group. See <u>[API Key Management](/docs/admin/api-key-management)</u>.
5. **Start making requests** — credits are applied to your API Group's balance and shared across all products (Sonar, Agent API, Search API, Embeddings). Monitor remaining balance and usage in the console at any time.

<Frame>
  <img alt="Generating API keys in the Perplexity console" />
</Frame>

## Refund Policy

If you need to cancel your subscription, refunds are available **within 14 days of purchase** provided that **no credits have been used**. To request a refund, contact <u>[aws-api@perplexity.ai](mailto:aws-api@perplexity.ai)</u> with your AWS Marketplace order ID.

<Warning>
  Refunds are not available once any credits have been consumed, or after the 14-day window has passed.
</Warning>

## Support

For questions about your AWS Marketplace subscription, billing, or API usage, contact the Perplexity API team:

**Email:** <u>[aws-api@perplexity.ai](mailto:aws-api@perplexity.ai)</u>

For issues related to AWS Marketplace registration or account linking, contact the Clazar support team:

**Email:** <u>[support@clazar.io](mailto:support@clazar.io)</u>

Include your AWS Marketplace order ID or account email when reaching out so we can locate your subscription quickly.

## Additional Resources

<CardGroup>
  <Card title="Quickstart" icon="bolt" href="/docs/getting-started/quickstart">
    Make your first API request in minutes.
  </Card>

  <Card title="Pricing" icon="calculator" href="/docs/getting-started/pricing">
    Per-request and per-token pricing for all APIs.
  </Card>

  <Card title="AWS Marketplace listing" icon="aws" href="https://aws.amazon.com/marketplace/pp/prodview-fslss6gnscauq">
    View the Perplexity API Platform listing on AWS Marketplace.
  </Card>
</CardGroup>


# Changelog
Source: https://docs.perplexity.ai/docs/resources/changelog



<Tip>
  Looking ahead? Check out our [Feature Roadmap](/docs/resources/feature-roadmap) to see what's coming next.
</Tip>

<Update label="May 2026">
  **Finance Search: Now Available**

  The `finance_search` tool is now available in the Agent API. Pull structured financial and market data — quotes, financials, earnings, analyst estimates, segment KPIs, ETF constituents, and more — for public companies and instruments. The model decides which fields to fetch based on your prompt, so a single call can return valuation, earnings, and context together.

  **Highlights:**

  * **Quotes and pricing**: Near-real-time prices, OHLCV ranges, pre-market and after-hours data
  * **Financials**: Income statement, balance sheet, cash flow (quarterly and annual), key ratios
  * **Earnings**: Last call transcript, filings, beat/miss history, guidance
  * **Coverage and market activity**: Analyst estimates, top gainers/losers, ownership and corporate actions
  * **Recommended configurations**: Presets for live quotes, single-company historical lookups, and multi-step cross-company research

  Start here: [Finance Search](/docs/agent-api/tools/finance-search)
</Update>

<Update label="April 2026">
  **Agent API: New Third-Party Models**

  The Agent API now supports Claude Opus 4.7, GPT-5.5, and Grok 4.20 Reasoning — extending model choice for tool-calling, structured outputs, and fallback chains. See the full list in the [Models reference](/docs/agent-api/models).

  **API Key Management: Security Upgrade**

  We've upgraded API key management with a one-time reveal model: full token values are now returned **only at the moment of creation** and cannot be retrieved again from the console or any endpoint. This significantly reduces the blast radius of credential exposure and aligns with industry best practices. Always set a descriptive `token_name` so keys remain identifiable after creation, and rotate regularly.

  Start here: [API Key Management](/docs/admin/api-key-management)

  **New Integration: n8n**

  n8n now ships a native Perplexity node with full API coverage — Chat Completions, Agent, Search, and Embeddings — all configurable from the visual canvas. Models load dynamically from the API, so the dropdown always reflects the latest options.

  Start here: [n8n Integration Guide](/docs/getting-started/integrations/n8n)

  **New Integration: OpenClaw**

  OpenClaw, the open-source terminal AI agent, now supports Perplexity Search API as a native web search provider. Configure your API key once and get structured search results (`title`, `url`, `snippet`) directly inside your terminal workflows.

  Start here: [OpenClaw Integration Guide](/docs/getting-started/integrations/openclaw)

  **API Credits now available through the AWS Marketplace**

  The Perplexity API Platform is now available as a SaaS listing on AWS Marketplace. Purchase API credits through your AWS account for consolidated billing, simplified procurement, and no separate vendor relationship.

  Start here: [AWS Marketplace](/docs/resources/aws-marketplace)

  **`/v1/models` Endpoint**

  A new `GET /v1/models` endpoint lists all available Agent API models in OpenAI-compatible format. No authentication required, useful for dynamic model selection in your integrations.
</Update>

<Update label="March 2026">
  **Agent API: New Third-Party Models**

  The Agent API now supports additional third-party models including GPT-5.4, NVIDIA Nemotron, Claude Sonnet 4.6, and Gemini 3.1 Pro Preview — giving you more flexibility for tool-calling, structured outputs, and model fallback chains.

  **Model Deprecations: Gemini 2.5 Flash & Gemini 2.5 Pro**

  As of March 20, 2026, `google/gemini-2.5-flash` has been deprecated and removed from the API. `google/gemini-2.5-pro` followed on April 1, along with `google/gemini-3-pro-preview`. If you were using these models, we recommend switching to newer alternatives available in the [Models reference](/docs/agent-api/models).

  **Agent API Endpoint: `/v1/agent`**

  The canonical Agent API endpoint is now `/v1/agent`. The previous `/v1/responses` path continues to work as an alias for OpenAI compatibility, no migration is required.
</Update>

<Update label="February 2026">
  **Agent API: Now Available**

  We're excited to announce the general availability of the **Agent API**! Build autonomous agents with production-ready guidance on model behavior, output controls, and OpenAI-compatibility patterns to seamlessly integrate with your existing systems.

  Start here: [Agent API Quickstart](/docs/agent-api/quickstart)

  **Embeddings API: Now Available**

  We're thrilled to launch the **Embeddings API** with comprehensive guides for standard and contextualized embeddings, plus best practices for semantic search and retrieval workflows.

  Start here: [Embeddings API Quickstart](/docs/embeddings/quickstart)
</Update>

<Update label="December 2025">
  **Model Deprecation: `sonar-reasoning` Removed**

  As of December 15, 2025, the `sonar-reasoning` model has been deprecated and removed from the API. If you were using this model, we recommend migrating to `sonar-reasoning-pro` for enhanced multi-step reasoning capabilities with web search.

  **New: Media Classifier for Intelligent Visual Content**

  We're excited to introduce the **Media Classifier** — an intelligent system that automatically detects when your queries would benefit from visual content and includes relevant images or videos in responses.

  **Key capabilities:**

  * **Automatic detection**: Analyzes queries to identify when visual content adds value
  * **Smart media selection**: Intelligently chooses between images, videos, or both based on query type
  * **Context-aware**: Perfect for educational content, geographic queries, processes, and demonstrations
  * **Configurable control**: Enable/disable and override media types as needed

  Available exclusively with `sonar-pro`, the Media Classifier enhances responses for visual concepts, locations, step-by-step processes, and educational content. [Learn more →](/docs/sonar/media)

  **Search API Enhancements**

  We've made several improvements to the Search API:

  * **New `max_tokens` parameter**: Control the maximum tokens extracted per page in search results. This gives you finer control over response size and costs. [Learn more →](/docs/search/quickstart)
  * **`last_updated_filter` support**: Filter search results by when content was last updated, in addition to publication date. Perfect for finding the most current information. [Learn more →](/docs/search/filters/date-time-filters)
  * **Vercel AI SDK Support**: The Search API is now compatible with the Vercel AI SDK, allowing you to build with Perplexity in a framework-agnostic way. [Learn more →](https://ai-sdk.dev/tools-registry/perplexity-search)

  **Ecosystem & Community**

  New community showcase: [**Perplexity Client**](/docs/cookbook/showcase/perplexity-client) — An Electron-based desktop application with advanced API parameter controls, custom spaces, and API debugging mode. Built by the community for developers who want fine-grained control over their Sonar interactions.
</Update>

<Update label="November 2025">
  **Pro Search: Now Generally Available**

  We're excited to announce the general availability of **Pro Search** for Sonar Pro! Pro Search enhances your queries with automated tool usage, enabling multi-step reasoning through intelligent tool orchestration.

  **Key capabilities:**

  * **Multi-step reasoning**: The model automatically performs multiple web searches and fetches URL content to answer complex queries
  * **Real-time thought streaming**: Watch the model's reasoning process as it works through your question
  * **Automatic classification**: Use `search_type: "auto"` to let the system intelligently route queries based on complexity
  * **Built-in tools**: Access `web_search` and `fetch_url_content` tools that the model uses automatically

  Learn more about Pro Search in our [Pro Search Quickstart](/docs/sonar/pro-search/quickstart) guide.

  **MCP Server: One-Click Installation**

  The [Perplexity MCP Server](/docs/getting-started/integrations/mcp-server) now supports **one-click installation** for popular AI development environments:

  * **Cursor**: Click to auto-configure the Perplexity MCP server
  * **VS Code**: One-click setup via the VS Code MCP extension
  * **Claude Desktop & Claude Code**: Easy JSON configuration

  The MCP server provides four powerful tools: `perplexity_search`, `perplexity_ask`, `perplexity_research`, and `perplexity_reason` — enabling AI assistants to access Perplexity's search and reasoning capabilities directly.
</Update>

<Update label="October 2025">
  **Official Perplexity SDKs**

  We're thrilled to announce the official **Perplexity SDKs** for Python and Typescript! These SDKs provide convenient, type-safe access to all Perplexity APIs with both synchronous and asynchronous clients.

  **Installation:**

  ```bash theme={null}
  # Python
  pip install perplexityai

  # Typescript  
  npm install @perplexity-ai/perplexity_ai
  ```

  **Features:**

  * Full type definitions for all request parameters and response fields
  * Support for Sonar and Search APIs
  * Streaming support with async iterators
  * Automatic environment variable handling for API keys

  Get started with our [SDK Quickstart Guide](/docs/sdk/overview) and explore the [Sonar API Guide](/docs/sonar/quickstart) for detailed usage examples.

  **Interactive Search API Playground**

  Test Search API queries and parameters in real time with our new [Interactive Playground](https://console.perplexity.ai) — **no API key required** to get started. Experiment with filtering options, see response structures, and refine your queries before implementing them in code.

  **New Search API Capabilities**

  * **`language_preference`**: Specify preferred languages for search results (available for `sonar` and `sonar-pro`)
  * **`search_domain_filter`**: Filter results to specific domains for more targeted searches
  * **Date/time filters**: Enhanced control over result freshness with publication and update filters
    **Ecosystem & Community**

  New community showcase: [**StarPlex**](/docs/cookbook/showcase/starplex) — An AI-powered startup intelligence platform featuring an interactive 3D globe interface. Built with Sonar Pro, it helps entrepreneurs validate business ideas by mapping competitors, VCs, and market opportunities worldwide. Featured at recent hackathon events!
</Update>

<Update label="September 2025">
  **New: File Attachments Support**

  You can now upload and analyze documents in multiple formats using Sonar models! This powerful new feature supports PDF, DOC, DOCX, TXT, and RTF files, allowing you to ask questions, extract information, and get summaries from your documents.

  **Key capabilities:**

  * **Document Analysis**: Ask questions about document content and get detailed answers
  * **Content Extraction**: Pull out key information, data points, and insights
  * **Multi-format Support**: Work with PDF, Word documents, text files, and Rich Text Format
  * **Large Document Handling**: Process lengthy documents efficiently
  * **Multi-language Support**: Analyze documents in various languages

  Upload documents either via publicly accessible URLs using the `file_url` content type, similar to our existing image upload functionality.

  Get started with our comprehensive [File Attachments Guide](/docs/sonar/media#sending-files).
</Update>

<Update label="September 2025">
  **New: Search-only API**

  Introducing our standalone Search API that provides direct access to search results without LLM processing! This new endpoint gives you raw, ranked search results from Perplexity's continuously refreshed index.

  **Perfect for:**

  * Building custom search experiences
  * Integrating search results into your own applications
  * Creating specialized workflows that need search data without AI responses
  * Applications requiring just the search functionality

  **Key features:**

  * Direct access to Perplexity's search index
  * All existing search filters and controls
  * Faster responses since no LLM processing is involved
  * Same powerful filtering options (domain, date range, academic sources, etc.)

  This complements our existing chat completions API and gives developers more flexibility in how they use Perplexity's search capabilities.

  Learn more in our [Search API documentation](/docs/search/quickstart).
</Update>

<Update label="September 2025">
  **New: API Key Rotation Mechanism**

  We've introduced a comprehensive API key rotation system to enhance security and simplify key management for your applications.

  **Key features:**

  * **Seamless Rotation**: Replace API keys without service interruption
  * **Automated Workflows**: Set up automatic key rotation schedules
  * **Enhanced Security**: Regularly refresh keys to minimize security risks
  * **Audit Trail**: Track key usage and rotation history
  * **Zero Downtime**: Smooth transitions between old and new keys

  **How it works:**

  1. Generate a new API key while keeping the old one active
  2. Update your applications to use the new key
  3. Deactivate the old key once migration is complete

  This is particularly valuable for production environments where continuous availability is critical, and for organizations with strict security compliance requirements.

  **Best practices:**

  * Rotate keys every 30-90 days depending on your security requirements
  * Use environment variables to manage keys in your applications
  * Test key rotation in staging environments first
  * Monitor key usage to ensure successful transitions

  Access key rotation features through your [API Portal](https://console.perplexity.ai).
</Update>

<Update label="August 2025">
  **API model deprecation notice**

  Please note that as of August 1, 2025, R1-1776 will be removed from the available models.

  R1 has been a popular option for a while, but it hasn't kept pace with recent improvements and lacks support for newer features. To reduce engineering overhead and make room for more capable models, we're retiring it from the API.

  If you liked R1's strengths, we recommend switching to `Sonar Pro Reasoning`. It offers similar behavior with stronger overall performance.
</Update>

<Update label="July 2025">
  **New: Detailed Cost Information in API Responses**

  The API response JSON now includes detailed cost information for each request.

  You'll now see a new structure like this in your response:

  ```json theme={null}
  "usage": {
      "prompt_tokens": 8,
      "completion_tokens": 439,
      "total_tokens": 447,
      "search_context_size": "low",
      "cost": {
       "input_tokens_cost": 2.4e-05,
       "output_tokens_cost": 0.006585,
       "request_cost": 0.006,
       "total_cost": 0.012609
     }
  }
  ```

  **What's included:**

  * **input\_tokens\_cost**: Cost attributed to input tokens
  * **output\_tokens\_cost**: Cost attributed to output tokens
  * **request\_cost**: Fixed cost per request
  * **total\_cost**: The total cost for this API call

  This update enables easier tracking of usage and billing directly from each API response, giving you complete transparency into the costs associated with each request.
</Update>

<Update label="July 2025">
  **New: SEC Filings Filter for Financial Research**

  We're excited to announce the release of our new SEC filings filter feature, allowing you to search specifically within SEC regulatory documents and filings. By setting `search_domain: "sec"` in your API requests, you can now focus your searches on official SEC documents, including 10-K reports, 10-Q quarterly reports, 8-K current reports, and other regulatory filings.

  This feature is particularly valuable for:

  * Financial analysts researching company fundamentals
  * Investment professionals conducting due diligence
  * Compliance officers tracking regulatory changes
  * Anyone requiring authoritative financial information directly from official sources

  The SEC filter works seamlessly with other search parameters like date filters and search context size, giving you precise control over your financial research queries.

  **Example:**

  ```bash theme={null}
  curl --request POST \
    --url https://api.perplexity.ai/v1/sonar \
    --header 'accept: application/json' \
    --header 'authorization: Bearer $PERPLEXITY_API_KEY' \
    --header 'content-type: application/json' \
    --data '{
      "model": "sonar-pro",
      "messages": [{"role": "user", "content": "What was Apple's revenue growth in their latest quarterly report?"}],
      "stream": false,
      "search_domain": "sec",
      "web_search_options": {"search_context_size": "medium"}
  }' | jq
  ```

  For detailed documentation and implementation examples, please see our [SEC Guide](https://docs.perplexity.ai/guides/sec-guide).
</Update>

<Update label="June 2025">
  **Enhanced: Date Range Filtering with Latest Updated Field**

  We've enhanced our date range filtering capabilities with new fields that give you even more control over search results based on content freshness and updates.

  **New fields available:**

  * `latest_updated`: Filter results based on when the webpage was last modified or updated
  * `published_after`: Filter by original publication date (existing)
  * `published_before`: Filter by original publication date (existing)

  The `latest_updated` field is particularly useful for:

  * Finding the most current version of frequently updated content
  * Ensuring you're working with the latest data from news sites, blogs, and documentation
  * Tracking changes and updates to specific web resources over time

  **Example:**

  ```bash theme={null}
  curl --request POST \
    --url https://api.perplexity.ai/v1/sonar \
    --header 'accept: application/json' \
    --header 'authorization: Bearer $PERPLEXITY_API_KEY' \
    --header 'content-type: application/json' \
    --data '{
      "model": "sonar-pro",
      "messages": [{"role": "user", "content": "What are the latest developments in AI research?"}],
      "stream": false,
      "web_search_options": {
        "latest_updated": "2025-06-01",
        "search_context_size": "medium"
      }
  }'
  ```

  For comprehensive documentation and more examples, please see our [Date Range Filter Guide](https://docs.perplexity.ai/guides/date-range-filter-guide).
</Update>

<Update label="June 2025">
  **New: Academic Filter for Scholarly Research**
  We're excited to announce the release of our new academic filter feature, allowing you to tailor your searches specifically to academic and scholarly sources. By setting `search_mode: "academic"` in your API requests, you can now prioritize results from peer-reviewed papers, journal articles, and research publications.

  This feature is particularly valuable for:

  * Students and researchers working on academic papers
  * Professionals requiring scientifically accurate information
  * Anyone seeking research-based answers instead of general web content

  The academic filter works seamlessly with other search parameters like `search_context_size` and date filters, giving you precise control over your research queries.

  **Example:**

  ```bash theme={null}
  curl --request POST \
    --url https://api.perplexity.ai/v1/sonar \
    --header 'accept: application/json' \
    --header 'authorization: Bearer $PERPLEXITY_API_KEY' \
    --header 'content-type: application/json' \
    --data '{
      "model": "sonar-pro",
      "messages": [{"role": "user", "content": "What is the scientific name of the lions mane mushroom?"}],
      "stream": false,
      "search_mode": "academic",
      "web_search_options": {"search_context_size": "low"}
  }'
  ```

  For detailed documentation and implementation examples, please see our [Academic Filter Guide](https://docs.perplexity.ai/guides/academic-filter-guide).
</Update>

<Update label="May 2025">
  **New: Reasoning Effort Parameter for Sonar Deep Research**

  We're excited to announce our new reasoning effort feature for sonar-deep-research. This lets you control how much computational effort the AI dedicates to each query. You can choose from "low", "medium", or "high" to get faster, simpler answers or deeper, more thorough responses.

  This feature has a direct impact on the amount of reasoning tokens consumed for each query, giving you the ability to control costs while balancing between speed and thoroughness.

  **Options:**

  * `"low"`: Faster, simpler answers with reduced token usage
  * `"medium"`: Balanced approach (default)
  * `"high"`: Deeper, more thorough responses with increased token usage

  **Example:**

  ```bash theme={null}
  curl --request POST \
    --url https://api.perplexity.ai/v1/sonar \
    --header 'accept: application/json' \
    --header 'authorization: Bearer ${PPLX_KEY}' \
    --header 'content-type: application/json' \
    --data '{
      "model": "sonar-deep-research",
      "messages": [{"role": "user", "content": "What should I know before markets open today?"}],
      "stream": true,
      "reasoning_effort": "low"
    }'
  ```

  For detailed documentation and implementation examples, please see:
  [Sonar Deep Research Documentation](/docs/sonar/models/sonar-deep-research)
</Update>

<Update label="May 2025">
  **New: Asynchronous API for Sonar Deep Research**

  We're excited to announce the addition of an asynchronous API for Sonar Deep Research, designed specifically for research-intensive tasks that may take longer to process.

  This new API allows you to submit requests and retrieve results later, making it ideal for complex research queries that require extensive processing time.

  The asynchronous API endpoints include:

  1. `GET https://api.perplexity.ai/v1/async/sonar` - Lists all asynchronous chat completion requests for the authenticated user
  2. `POST https://api.perplexity.ai/v1/async/sonar` - Creates an asynchronous chat completion job
  3. `GET https://api.perplexity.ai/v1/async/sonar/{request_id}` - Retrieves the status and result of a specific asynchronous chat completion job

  **Note:** Async requests have a time-to-live (TTL) of 7 days. After this period, the request and its results will no longer be accessible.

  For detailed documentation and implementation examples, please see:
  [Sonar Deep Research Documentation](/docs/sonar/models/sonar-deep-research)
</Update>

<Update label="May 2025">
  **Enhanced API Responses with Search Results**

  We've improved our API responses to give you more visibility into search data by adding a new `search_results` field to the JSON response object.

  This enhancement provides direct access to the search results used by our models, giving you more transparency and control over the information being used to generate responses.

  The `search_results` field includes:

  * `title`: The title of the search result page
  * `url`: The URL of the search result
  * `date`: The publication date of the content

  **Example:**

  ```json theme={null}
  "search_results": [
    {
      "title": "Understanding Large Language Models",
      "url": "https://example.com/llm-article",
      "date": "2023-12-25"
    },
    {
      "title": "Advances in AI Research",
      "url": "https://example.com/ai-research",
      "date": "2024-03-15"
    }
  ]
  ```

  This update makes it easier to:

  * Verify the sources used in generating responses
  * Create custom citation formats for your applications
  * Filter or prioritize certain sources based on your needs

  **Update: The `citations` field has been fully deprecated and removed.** All applications should now use the `search_results` field, which provides more detailed information including titles, URLs, and publication dates.

  The `search_results` field is available across all our search-enabled models and offers enhanced source tracking capabilities.
</Update>

<Update label="April 2025">
  **New API Portal for Organization Management**

  We are excited to announce the release of our new API portal, designed to help you better manage your organization and API usage.

  With this portal, you can:

  * Organize and manage your API keys more effectively.
  * Gain insights into your API usage and team activity.
  * Streamline collaboration within your organization.

  Check it out here:\
  [https://console.perplexity.ai](https://console.perplexity.ai)
</Update>

<Update label="April 2025">
  **New: Location filtering in search**

  Looking to narrow down your search results based on users' locations?\
  We now support user location filtering, allowing you to retrieve results only from a particular user location.

  Check out the [guide](https://docs.perplexity.ai/guides/user-location-filter-guide).
</Update>

<Update label="April 2025">
  **Image uploads now available for all users!**

  You can now upload images to Sonar and use them as part of your multimodal search experience.\
  Give it a try by following our image upload guide:\
  [https://docs.perplexity.ai/guides/image-attachments](https://docs.perplexity.ai/guides/image-attachments)
</Update>

<Update label="April 2025">
  **New: Date range filtering in search**

  Looking to narrow down your search results to specific dates?\
  We now support date range filtering, allowing you to retrieve results only from a particular timeframe.

  Check out the guide:\
  [https://docs.perplexity.ai/guides/date-range-filter-guide](https://docs.perplexity.ai/guides/date-range-filter-guide)
</Update>

<Update label="April 2025">
  **Clarified: Search context pricing update**

  We've fully transitioned to our new pricing model: citation tokens are no longer charged.\
  If you were already using the `search_context_size` parameter, you've been on this model already.

  This change makes pricing simpler and cheaper for everyone — with no downside.

  View the updated pricing:\
  [https://docs.perplexity.ai/guides/pricing](https://docs.perplexity.ai/guides/pricing)
</Update>

<Update label="April 2025">
  **All features now available to everyone**

  We've removed all feature gating based on tiered spending. These were previously only available to users of Tier 3 and above.

  That means **every user now has access to all API capabilities**, regardless of usage volume or spend. Rate limits are still applicable.\
  Whether you're just getting started or scaling up, you get the full power of Sonar out of the box.
</Update>

<Update label="March 2025">
  **Structured Outputs Available for All Users**

  We're excited to announce that structured outputs are now available to all Perplexity API users, regardless of tier level. Based on valuable feedback from our developer community, we've removed the previous Tier 3 requirement for this feature.

  **What's available now:**

  * JSON structured outputs are supported across all models

  This change allows developers to create more reliable and consistent applications from day one. We believe in empowering our community with the tools they need to succeed, and we're committed to continuing to improve accessibility to our advanced features.

  Thank you for your feedback—it helps us make Perplexity API better for everyone.
</Update>

<Update label="March 2025">
  **Improved Sonar Models: New Search Modes**

  We're excited to announce significant improvements to our Sonar models that deliver superior performance at lower costs. Our latest benchmark testing confirms that Sonar and Sonar Pro now outperform leading competitors while maintaining more affordable pricing.

  Key updates include:

  * **Three new search modes** across most Sonar models:
    * High: Maximum depth for complex queries
    * Medium: Balanced approach for moderate complexity
    * Low: Cost-efficient for straightforward queries (equivalent to current pricing)

  * **Simplified billing structure**:
    * Transparent pricing for input/output tokens
    * No charges for citation tokens in responses (except for Sonar Deep Research)

  The current billing structure will be supported as the default option for 30 days (until April 18, 2025). During this period, the new search modes will be available as opt-in features.

  **Important Note:** After April 18, 2025, Sonar Pro and Sonar Reasoning Pro will not return Citation tokens or number of search results in the usage field in the API response.
</Update>

<Update label="January 2025">
  **API model deprecation notice**

  Please note that as of February 22, 2025, several models and model name aliases will no longer be accessible. The following model names will no longer be available via API:

  `llama-3.1-sonar-small-128k-online`

  `llama-3.1-sonar-large-128k-online`

  `llama-3.1-sonar-huge-128k-online`

  We recommend updating your applications to use our recently released Sonar or Sonar Pro models – you can learn more about them here. Thank you for being a Perplexity API user.
</Update>

<Update label="January 2025">
  **Build with Perplexity's new APIs**

  We are expanding API offerings with the most efficient and cost-effective search solutions available:  **Sonar** and **Sonar Pro**.

  **Sonar** gives you fast, straightforward answers

  **Sonar Pro** tackles complex questions that need deeper research and provides more sources

  Both models offer built-in citations, automated scaling of rate limits, and public access to advanced features like structured outputs and search domain filters. And don't worry, we never train on your data. Your information stays yours.

  You can learn more about our new APIs here - [https://docs.perplexity.ai](https://docs.perplexity.ai)
</Update>

<Update label="November 2024">
  **Citations Public Release and Increased Default Rate Limits**

  We are excited to announce the public availability of citations in the Perplexity API. In addition, we have also increased our default rate limit for the sonar online models to 50 requests/min for all users.

  Effective immediately, all API users will see citations returned as part of their requests by default. This is not a breaking change. The **return\_citations** parameter will no longer have any effect.

  For bug reports or enterprise inquiries, please reach out to our team at [api@perplexity.ai](mailto:api@perplexity.ai)
</Update>

<Update label="July 2024">
  **Introducing New and Improved Sonar Models**

  We are excited to announce the launch of our latest Perplexity Sonar models:

  **Online Models** -
  `llama-3.1-sonar-small-128k-online`
  `llama-3.1-sonar-large-128k-online`

  **Chat Models** -
  `llama-3.1-sonar-small-128k-chat`
  `llama-3.1-sonar-large-128k-chat`

  These new additions surpass the performance of the previous iteration. For detailed information on our supported models, please visit our model card documentation.

  **\[Action Required]** Model Deprecation Notice
  Please note that several models will no longer be accessible effective 8/12/2024. We recommend updating your applications to use models in the Llama-3.1 family immediately.

  The following model names will no longer be available via API -
  `llama-3-sonar-small-32k-online`
  `llama-3-sonar-large-32k-online`
  `llama-3-sonar-small-32k-chat`
  `llama-3-sonar-large-32k-chat`
  `llama-3-8b-instruct`
  `llama-3-70b-instruct`
  `mistral-7b-instruct`
  `mixtral-8x7b-instruct`

  We recommend switching to models in the Llama-3.1 family:

  **Online Models** -
  `llama-3.1-sonar-small-128k-online`
  `llama-3.1-sonar-large-128k-online`

  **Chat Models** -
  `llama-3.1-sonar-small-128k-chat`
  `llama-3.1-sonar-large-128k-chat`

  **Instruct Models** -
  `llama-3.1-70b-instruct`
  `llama-3.1-8b-instruct`

  If you have any questions, please email [support@perplexity.ai](mailto:support@perplexity.ai).
  Thank you for being a Perplexity API user.

  Stay curious,

  Team Perplexity
</Update>

***

<Update label="April 2024">
  **Model Deprecation Notice**

  Please note that as of May 14, several models and model name aliases will no longer be accessible. We recommend updating your applications to use models in the Llama-3 family immediately. The following model names will no longer be available via API:

  `codellama-70b-instruct`
  `mistral-7b-instruct`
  `mixtral-8x22b-instruct`
  `pplx-7b-chat`
  `pplx-7b-online`
</Update>


# Get in Touch
Source: https://docs.perplexity.ai/docs/resources/discussions



## Join Our Developer Community

<Card title="Community Forum" icon="users" href="https://community.perplexity.ai">
  The primary hub for our developer ecosystem. Connect with thousands of developers, share ideas, get help, and showcase your projects built with the Perplexity API.
</Card>

<CardGroup>
  <Card title="Discord Community" icon="message-circle" href="https://discord.gg/perplexity-ai">
    Join our Discord server for real-time assistance and discussions with fellow developers.
  </Card>

  <Card title="Stay Updated" icon="bell" href="https://twitter.com/PPLXDevs">
    Follow [@PPLXDevs](https://twitter.com/PPLXDevs) for the latest updates, feature announcements, and developer spotlights.
  </Card>
</CardGroup>

## Sales & Enterprise

For enterprise solutions, custom pricing, or sales questions, contact our sales team.

<Card title="Contact Sales Team" icon="file-pencil" href="https://perplexity.typeform.com/to/nXeehCGo">
  Fill out our enterprise inquiry form and we'll review your use case to accommodate your needs.

  We offer custom pricing, dedicated support, and enterprise features for teams and organizations.
</Card>

## Technical Support

Need technical assistance? Our support team is here to help.

<Warning>
  **Try the [Community Forum](https://community.perplexity.ai/) first.**

  You'll get faster responses from our active community and team members who monitor the forum regularly.
</Warning>

**Email**: [api@perplexity.ai](mailto:api@perplexity.ai) — For technical issues

## Developer Resources

<Steps>
  <Step title="Report Issues">
    Found a bug? Help us improve by submitting detailed bug reports.

    Create a new post in the [Community Forum](https://community.perplexity.ai/) with the `Bug Reports` tag.
  </Step>

  <Step title="Share Your Work">
    Built something with the Perplexity API? We'd love to showcase your work.

    * Contribute to our [API Cookbook](https://github.com/perplexityai/api-cookbook)
    * Share on X/Twitter with [@PPLXDevs](https://twitter.com/PPLXDevs)
    * Present at our monthly developer showcase
  </Step>

  <Step title="Get Featured">
    Exceptional projects may be featured in our newsletter, blog, social media channels, and our [Cookbook Community Showcase](/docs/cookbook/showcase/briefo).

    <Tip>
      Share your project details and use cases to increase your chances of being featured.
    </Tip>
  </Step>
</Steps>


# Frequently Asked Questions
Source: https://docs.perplexity.ai/docs/resources/faq



<AccordionGroup>
  <Accordion title="Why isn't the `response_format` parameter working for reasoning models?">
    The `sonar-reasoning-pro` model is designed to output a `<think>` section containing reasoning tokens, immediately followed by a valid JSON object. As a result, the `response_format` parameter does not remove these reasoning tokens from the output.

    We recommend using a custom parser to extract the valid JSON portion. An example implementation can be found [here](https://github.com/ppl-ai/api-discussion/blob/main/utils/extract_json_reasoning_models.py).
  </Accordion>

  <Accordion title="Does the API use content filtering or SafeSearch?">
    Yes, for the API, content filtering in the form of SafeSearch is turned on by default. This helps filter out potentially offensive and inappropriate content, including pornography, from search results. SafeSearch is an automated filter that works across search results to provide a safer experience. You can learn more about SafeSearch on the [official Wikipedia page](https://en.wikipedia.org/wiki/SafeSearch).
  </Accordion>

  <Accordion title="How do I file a bug report and what happens afterward?">
    To file a bug report, please head to our [Developer Community](https://community.perplexity.ai/) and create a new post in the "Bug Reports" category.

    We truly appreciate your patience, and we'll get back to you as soon as possible. Due to the current volume of reports, it may take a little time for us to respond—but rest assured, we're on it.
  </Accordion>

  <Accordion title="Where are Perplexity's language models hosted?">
    Our compute is hosted via Amazon Web Services in North America. By default, the API has zero day retention of user prompt data, which is never used for AI training.
  </Accordion>

  <Accordion title="How can I upgrade to the next usage tier?">
    The only way for an account to be upgraded to the next usage tier is through all-time credit purchase.

    Here are the spending criteria associated with each tier:

    | Tier   | Credit Purchase (all time) |
    | ------ | -------------------------- |
    | Tier 0 | -                          |
    | Tier 1 | \$50                       |
    | Tier 2 | \$250                      |
    | Tier 3 | \$500                      |
    | Tier 4 | \$1000                     |
    | Tier 5 | \$5000                     |
  </Accordion>

  <Accordion title="How can I track my spend/usage per API key?">
    We offer a way to track your billing per API key. You can do this by navigating to the following location:

    **Settings > View Dashboard > Invoice history > Invoices**

    Then click on any invoice and each item from the total bill will have a code at the end of it (e.g., pro (743S)). Those 4 characters are the last 4 of your API key.
  </Accordion>

  <Accordion title="How do I request a new feature?">
    A Feature Request is a suggestion to improve or add new functionality to the Perplexity Sonar API, such as:

    * Requesting support for a new model or capability (e.g., image processing, fine-tuning options)
    * Asking for new API parameters (e.g., additional filters, search options)
    * Suggesting performance improvements (e.g., faster response times, better citation handling)
    * Enhancing existing API features (e.g., improving streaming reliability, adding new output formats)

    If your request aligns with these, please submit a feature request here: [Github Feature requests](https://github.com/ppl-ai/api-discussion/issues)
  </Accordion>

  <Accordion title="Why are the results from the API different from the UI? ">
    1. The API uses the same search system as the UI with differences in configuration—so their outputs may differ.
    2. The underlying AI model might differ between the API and the UI for a given query.
  </Accordion>

  <Accordion title="Will user data submitted through the API be used for model training or other purposes?">
    We collect the following types of information:

    **API Usage Data:** We collect billable usage metadata such as the number of requests and tokens. You can view your own usage in the [API Platform console](https://console.perplexity.ai).

    **User Account Information:** When you create an account with us, we collect your name, email address, and other relevant contact information.

    We do not retain any query data sent through the API and do not train on any of your data.
  </Accordion>

  <Accordion title="Does the API currently support web browsing?">
    Yes, the [Sonar Models](https://docs.perplexity.ai/guides/model-cards) leverage information from Perplexity's search index and the public internet.
  </Accordion>

  <Accordion title="What are the limitations to the number of API calls?">
    You can find our [rate limits here](https://docs.perplexity.ai/guides/usage-tiers).
  </Accordion>

  <Accordion title="What's the best way to stay up to date with API updates?">
    We email users about new developments and also post in the [changelog](/docs/resources/changelog).
  </Accordion>

  <Accordion title="How should I respond to 401: Authorization errors?">
    401 error codes indicate that the provided API key is invalid, deleted, or belongs to an account which ran out of credits. You likely need to purchase more credits in the [API Platform console](https://console.perplexity.ai). You can avoid this issue by configuring auto-top-up.
  </Accordion>

  <Accordion title="Do you support fine-tuning?">
    Currently, we do not support fine-tuning.
  </Accordion>

  <Accordion title="I have another question or an issue">
    Please reach out to [api@perplexity.ai](mailto:api@perplexity.ai) or [support@perplexity.ai](mailto:support@perplexity.ai) for other API inquiries. You can also post on our [discussion forum](https://github.com/ppl-ai/api-discussion/discussions) and we will get back to you.
  </Accordion>

  <Accordion title="Does Perplexity provide service quality assurances such as service uptime, frequency of failures, and target recovery time in the event of a failure?">
    We do not guarantee this at the moment.
  </Accordion>

  <Accordion title="Do you expose CoTs if I use your reasoning APIs or Deep Research API?">
    We expose the CoTs for Sonar Reasoning Pro. We don't currently expose the CoTs for Deep Research.
  </Accordion>

  <Accordion title="Are the reasoning tokens in Deep Research same as CoTs in the answer?">
    Reasoning tokens in Deep Research are a bit different than the CoTs in the answer—these tokens are used to reason through the research material before generating the final output via the CoTs.
  </Accordion>

  <Accordion title="Is the internet data access provided by the API identical to that of Perplexity's web interface?">
    Yes, the API offers exactly the same internet data access as Perplexity's web platform.
  </Accordion>

  <Accordion title="To what extent is the API OpenAI compatible?">
    The Perplexity API is designed to be broadly compatible with OpenAI's chat completions endpoint. It adopts a similar structure—including fields such as `id`, `model`, and `usage`—and supports analogous parameters like `model`, `messages`, and `stream`.

    **Key Differences from the standard OpenAI response include:**

    * **Response Object Structure:**
      * OpenAI responses typically have an `object` value of `"chat.completion"` and a `created` timestamp, whereas our response uses `object: "response"` and a `created_at` field.
      * Instead of a `choices` array, our response content is provided under an `output` array that contains detailed message objects.

    * **Message Details:**
      * Each message in our output includes a `type` (usually `"message"`), a unique `id`, and a `status`.
      * The actual text is nested within a `content` array that contains objects with `type`, `text`, and an `annotations` array for additional context.

    * **Additional Fields:**
      * Our API response provides extra meta-information (such as `status`, `error`, `instructions`, and `max_output_tokens`) that are not present in standard OpenAI responses.
      * The `usage` field also differs, offering detailed breakdowns of input and output tokens (including fields like `input_tokens_details` and `output_tokens_details`).

    These differences are intended to provide enhanced functionality and additional context while maintaining broad compatibility with OpenAI's API design.
  </Accordion>
</AccordionGroup>


# API Roadmap
Source: https://docs.perplexity.ai/docs/resources/feature-roadmap

Upcoming and in-progress features for the Perplexity API.

<Info>
  This page tracks upcoming and in-progress work only. Once a feature ships, it is removed from this roadmap and documented in the [changelog](/docs/resources/changelog).
</Info>

## Upcoming and In Progress

<AccordionGroup>
  <Accordion title="Sandbox API" description="Isolated Python and Bash execution environments">
    We are introducing a Sandbox API for isolated environments for executing Python and Bash code. Each sandbox runs in its own container with dedicated resources, supporting file operations, background processes, and state persistence via pause/resume.

    * **Dedicated per-sandbox containers** for stronger isolation
    * **Python and Bash execution** with file and process support
    * **Pause/resume state persistence** for iterative workflows
  </Accordion>

  <Accordion title="Sonar API Performance Upgrade" description="Lower latency on existing endpoints">
    We are rolling out performance improvements while preserving compatibility.

    * **Same endpoint contracts** with backward compatibility
    * **Latency improvements** for common request patterns
    * **Automatic rollout** with no migration required for most users
  </Accordion>

  <Accordion title="Video Upload Capabilities" description="Multimodal video processing">
    We're expanding multimodal support to include direct video uploads.

    * **Video content analysis** for uploaded files
    * **Frame-level reasoning** for time-specific insights
    * **Visual scene understanding** across longer media
    * **Multimodal retrieval** across text, image, and video context
  </Accordion>

  <Accordion title="File Search and Connectors" description="Expanded data access">
    We're working on deeper file and data-source access for API organizations.

    * **Repository and connector search** across organization data
    * **Multi-format support** across common document types
    * **External data source integration** for enterprise workflows
  </Accordion>

  <Accordion title="Async API Webhook Support" description="Event-driven completion notifications">
    We plan to add webhook callbacks for async workflows so long-running jobs can notify your systems automatically.

    * **Job completion webhooks** for async requests
    * **Failure webhooks** with retry-safe delivery semantics
    * **Signature verification** for secure callback handling
  </Accordion>

  <Accordion title="Model and SDK Expansion" description="New model surface area and SDK ergonomics">
    We will continue to expand model coverage and improve SDK ergonomics.

    * **Additional model releases** and lifecycle clarity
    * **SDK quality-of-life improvements** for Python and TypeScript
    * **More production-ready examples** for common integration patterns
  </Accordion>

  <Accordion title="Context Management and Memory" description="Improved context handling across calls">
    We're addressing context persistence limits by improving memory-oriented workflows.

    * **Session-aware state handling**
    * **Reduced manual context stitching** across requests
    * **Improved control over long-running conversational workflows**
  </Accordion>

  <Accordion title="Better Error Handling" description="Clearer troubleshooting and recovery">
    We are improving how failures are reported and diagnosed across APIs.

    * **More actionable error messages**
    * **Stronger remediation guidance in docs**
    * **Clearer retry and backoff recommendations**
  </Accordion>

  <Accordion title="Voice-to-Voice API" description="Real-time audio interactions">
    We're building voice-native interaction capabilities for real-time experiences.

    * **Direct voice input and streamed audio output**
    * **Multi-language support**
    * **Low-latency conversation loops**
  </Accordion>

  <Accordion title="Dedicated API Console" description="Standalone developer console separate from the Perplexity app">
    We're building a dedicated API console — a standalone interface for developers that is separate from the Perplexity website. It will serve as the primary hub for API key management, usage visibility, and team controls.

    * **Standalone from the Perplexity app** — purpose-built for API developers
    * **API key management** with fine-grained permissions and rotation
    * **Usage and cost visibility** at the key and team level
    * **Organization controls** for team access and collaboration
  </Accordion>

  <Accordion title="Developer Analytics Dashboard" description="Operational usage insights">
    We're expanding analytics visibility for API teams.

    * **Query and latency analytics**
    * **Error trend monitoring**
    * **Cost and usage forecasting**
  </Accordion>

  <Accordion title="Finance Tools Integration" description="Financial data and analysis">
    We're expanding financial research capabilities with richer structured access.

    * **Market and filing workflows**
    * **Better controls for finance-specific retrieval**
    * **More end-to-end examples for analyst use cases**
  </Accordion>

  <Accordion title="Documentation Overhaul" description="Higher quality docs and guides">
    Documentation improvements remain in progress.

    * **Clearer API selection guides**
    * **More opinionated implementation guides**
    * **Higher-fidelity, production-oriented examples**
  </Accordion>

  <Accordion title="Labs Features via API" description="Experimental capabilities">
    We intend to bring selected experimental features into developer previews.

    * **Early access feature channels**
    * **Prototype integrations for feedback**
    * **Faster developer feedback loops for roadmap planning**
  </Accordion>
</AccordionGroup>

<Note>
  For shipped updates and release dates, see the [changelog](/docs/resources/changelog).
</Note>


# Perplexity Crawlers
Source: https://docs.perplexity.ai/docs/resources/perplexity-crawlers

We strive to improve our service every day by delivering the best search experience possible. To achieve this, we collect data using web crawlers ("robots") and user agents that gather and index information from the internet, operating either automatically or in response to user requests. Webmasters can use the following robots.txt tags to manage how their sites and content interact with Perplexity. Each setting works independently, and it may take up to 24 hours for our systems to reflect changes.

| User Agent      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| :-------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| PerplexityBot   | `PerplexityBot` is designed to surface and link websites in search results on Perplexity. It is not used to crawl content for AI foundation models. To ensure your site appears in search results, we recommend allowing `PerplexityBot` in your site's `robots.txt` file and permitting requests from our published IP ranges listed below.<br /><br />Full user-agent string: `Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; PerplexityBot/1.0; +https://perplexity.ai/perplexitybot)`<br /><br />Published IP addresses: [https://www.perplexity.com/perplexitybot.json](https://www.perplexity.com/perplexitybot.json)                                                                                                                                        |
| Perplexity‑User | `Perplexity-User` supports user actions within Perplexity. When users ask Perplexity a question, it might visit a web page to help provide an accurate answer and include a link to the page in its response. `Perplexity-User` controls which sites these user requests can access. It is not used for web crawling or to collect content for training AI foundation models.<br /><br />Full user-agent string: `Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; Perplexity-User/1.0; +https://perplexity.ai/perplexity-user)`<br /><br />Published IP addresses: [https://www.perplexity.com/perplexity-user.json](https://www.perplexity.com/perplexity-user.json)<br /><br />Since a user requested the fetch, this fetcher generally ignores robots.txt rules. |

## WAF Configuration

If you're using a Web Application Firewall (WAF) to protect your site, you may need to explicitly whitelist Perplexity's bots to ensure they can access your content. Below are configuration guidelines for popular WAF providers.

### Cloudflare WAF

To configure Cloudflare WAF to allow Perplexity bots:

<Steps>
  <Step title="Navigate to WAF settings">
    In your Cloudflare dashboard, go to **Security** → **WAF**.
  </Step>

  <Step title="Create a new rule">
    Click on **Custom rules** and create a new rule to allow Perplexity bots.
  </Step>

  <Step title="Configure rule conditions">
    Set up a rule that combines both User-Agent and IP address conditions:

    * **Field**: User Agent
    * **Operator**: Contains
    * **Value**: `PerplexityBot` OR `Perplexity-User`

    **AND**

    * **Field**: IP Source Address
    * **Operator**: Is in
    * **Value**: Use the IP ranges from the official endpoints listed below
  </Step>

  <Step title="Set rule action">
    Set the action to **Allow** to ensure these requests bypass other security rules.
  </Step>
</Steps>

### AWS WAF

For AWS WAF configuration, create IP sets and string match conditions:

<Steps>
  <Step title="Create IP sets">
    In the AWS WAF console, create IP sets for both PerplexityBot and Perplexity-User using the IP addresses from the official endpoints listed below.
  </Step>

  <Step title="Create string match conditions">
    Create string match conditions for the User-Agent headers:

    * `PerplexityBot`
    * `Perplexity-User`
  </Step>

  <Step title="Create allow rules">
    Create rules that combine the IP sets with the corresponding User-Agent strings, and set the action to **Allow**.
  </Step>

  <Step title="Associate with Web ACL">
    Associate these rules with your Web ACL and ensure they have higher priority than blocking rules.
  </Step>
</Steps>

### IP Address Sources

<Warning>
  Always use the most current IP ranges from the official JSON endpoints. These addresses are updated regularly and should be the source of truth for your WAF configurations.
</Warning>

* **PerplexityBot IP addresses**: [https://www.perplexity.com/perplexitybot.json](https://www.perplexity.com/perplexitybot.json)
* **Perplexity-User IP addresses**: [https://www.perplexity.com/perplexity-user.json](https://www.perplexity.com/perplexity-user.json)

<Tip>
  Set up automated processes to periodically fetch and update your WAF rules with the latest IP ranges from these endpoints to ensure continuous access for Perplexity bots.
</Tip>

### Best Practices

<Tip>
  When configuring WAF rules for Perplexity bots, combine both User-Agent string matching and IP address verification for enhanced security while ensuring legitimate bot traffic can access your content.
</Tip>

<Note>
  Changes to WAF configurations may take some time to propagate. Monitor your logs to ensure the rules are working as expected and that legitimate Perplexity bot traffic is being allowed through.
</Note>


# Privacy & Security
Source: https://docs.perplexity.ai/docs/resources/privacy-security

Learn about Perplexity's data privacy, retention policies, and security certifications for API users

## Data Privacy & Retention

### Zero Data Retention Policy

Perplexity maintains a strict **Zero Data Retention Policy** for the Sonar API. We do not retain any data sent via the Sonar API, and we absolutely do not use any customer data to train our models or for any other purposes beyond processing your immediate request.

### Data We Collect

The only data we collect through the Sonar API consists of essential billable metrics required for service operation:

* Number of tokens processed
* Model used for each request
* Request timestamp and duration
* API key identification (for billing purposes)

This billing metadata does not include any content from your prompts, responses, or other user data.

## Security Certifications & Compliance

Perplexity is compliant with industry-leading security standards and certifications:

### Current Certifications

<Check>
  **[SOC 2 Type II Report](https://trust.perplexity.ai/)** - Comprehensive security controls audit covering security, availability, processing integrity, confidentiality, and privacy
</Check>

<Check>
  **[2025 HIPAA Gap Assessment](https://trust.perplexity.ai/)** - Healthcare data protection compliance evaluation
</Check>

<Check>
  **[CAIQlite](https://trust.perplexity.ai/)** - Cloud security assessment questionnaire demonstrating cloud security posture
</Check>

## Additional Security Information

For comprehensive details about our security measures, infrastructure protection, and compliance frameworks, visit our dedicated security portal:

<Card title="Perplexity Trust Center" icon="shield-check" href="https://trust.perplexity.ai/">
  Access detailed security documentation, compliance reports, and transparency information
</Card>

<Info>
  All security measures and certifications are regularly updated and maintained to ensure the highest standards of data protection and service security.
</Info>


# System Status
Source: https://docs.perplexity.ai/docs/resources/status



<ApiStatus />

## Contact & Support

If you experience any issues, please reach out through one of the following channels:

<CardGroup>
  <Card title="Email Support" icon="mail" href="mailto:api@perplexity.ai">
    Send us an email at **[api@perplexity.ai](mailto:api@perplexity.ai)** for enterprise inquiries or bug reports.
  </Card>

  <Card title="Discord Community" icon="message-circle" href="https://discord.com/invite/perplexity-ai">
    Join our Discord community to discuss with other developers and flag bug reports.
  </Card>
</CardGroup>


# Best Practices
Source: https://docs.perplexity.ai/docs/sdk/best-practices

Learn best practices for using the Perplexity SDKs in production, including environment variables, rate limiting, security, and efficient request patterns.

## Overview

This guide covers essential best practices for using the Perplexity SDKs in production environments. Following these practices will help you build robust, secure, and efficient applications.

## Security Best Practices

### Environment Variables

Always store API keys securely using environment variables:

<Steps>
  <Step title="Use environment variables">
    Store API keys in environment variables, never in source code.

    <CodeGroup>
      ```python Python theme={null}
      import os
      from perplexity import Perplexity

      # Good: Use environment variables
      client = Perplexity(
          api_key=os.environ.get("PERPLEXITY_API_KEY")
      )

      # Bad: Never hardcode API keys
      # client = Perplexity(api_key="pplx-abc123...")  # DON'T DO THIS
      ```

      ```typescript TypeScript theme={null}
      import Perplexity from '@perplexity-ai/perplexity_ai';

      // Good: Use environment variables
      const client = new Perplexity({
          apiKey: process.env.PERPLEXITY_API_KEY
      });

      // Bad: Never hardcode API keys
      // const client = new Perplexity({
      //     apiKey: "pplx-abc123..."  // DON'T DO THIS
      // });
      ```
    </CodeGroup>

    <Warning>
      Never commit API keys to version control. Use .env files locally and secure environment variable management in production.
    </Warning>
  </Step>

  <Step title="Use .env files for local development">
    Create a `.env` file for local development (add it to .gitignore):

    ```bash theme={null}
    cat > .env << 'EOF'
    PERPLEXITY_API_KEY=your_api_key_here
    PERPLEXITY_MAX_RETRIES=3
    PERPLEXITY_TIMEOUT=30000
    EOF
    ```

    <CodeGroup>
      ```python Python theme={null}
      from dotenv import load_dotenv
      import os
      from perplexity import Perplexity

      # Load environment variables from .env file
      load_dotenv()

      client = Perplexity(
          api_key=os.getenv("PERPLEXITY_API_KEY"),
          max_retries=int(os.getenv("PERPLEXITY_MAX_RETRIES", "3"))
      )
      ```

      ```typescript TypeScript theme={null}
      import dotenv from 'dotenv';
      import Perplexity from '@perplexity-ai/perplexity_ai';

      // Load environment variables from .env file
      dotenv.config();

      const client = new Perplexity({
          apiKey: process.env.PERPLEXITY_API_KEY,
          maxRetries: parseInt(process.env.PERPLEXITY_MAX_RETRIES || '3')
      });
      ```
    </CodeGroup>
  </Step>

  <Step title="Validate environment variables">
    Check for required environment variables at startup.

    <CodeGroup>
      ```python Python theme={null}
      import os
      import sys
      from perplexity import Perplexity

      def create_client():
          api_key = os.getenv("PERPLEXITY_API_KEY")
          if not api_key:
              print("Error: PERPLEXITY_API_KEY environment variable is required")
              sys.exit(1)
          
          return Perplexity(api_key=api_key)

      client = create_client()
      ```

      ```typescript TypeScript theme={null}
      import Perplexity from '@perplexity-ai/perplexity_ai';

      function createClient(): Perplexity {
          const apiKey = process.env.PERPLEXITY_API_KEY;
          if (!apiKey) {
              console.error("Error: PERPLEXITY_API_KEY environment variable is required");
              process.exit(1);
          }
          
          return new Perplexity({ apiKey });
      }

      const client = createClient();
      ```
    </CodeGroup>
  </Step>
</Steps>

### API Key Rotation

Implement secure API key rotation:

<CodeGroup>
  ```python Python theme={null}
  import os
  import logging
  from perplexity import Perplexity
  from typing import Optional

  class SecurePerplexityClient:
      def __init__(self, primary_key: Optional[str] = None, fallback_key: Optional[str] = None):
          self.primary_key = primary_key or os.getenv("PERPLEXITY_API_KEY")
          self.fallback_key = fallback_key or os.getenv("PERPLEXITY_API_KEY_FALLBACK")
          self.current_client = Perplexity(api_key=self.primary_key)
          self.logger = logging.getLogger(__name__)
      
      def _switch_to_fallback(self):
          """Switch to fallback API key if available"""
          if self.fallback_key:
              self.logger.warning("Switching to fallback API key")
              self.current_client = Perplexity(api_key=self.fallback_key)
              return True
          return False
      
      def search(self, query: str, **kwargs):
          try:
              return self.current_client.search.create(query=query, **kwargs)
          except Exception as e:
              if "authentication" in str(e).lower() and self._switch_to_fallback():
                  return self.current_client.search.create(query=query, **kwargs)
              raise e

  # Usage
  client = SecurePerplexityClient()
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  class SecurePerplexityClient {
      private primaryKey: string;
      private fallbackKey?: string;
      private currentClient: Perplexity;
      
      constructor(primaryKey?: string, fallbackKey?: string) {
          this.primaryKey = primaryKey || process.env.PERPLEXITY_API_KEY!;
          this.fallbackKey = fallbackKey || process.env.PERPLEXITY_API_KEY_FALLBACK;
          this.currentClient = new Perplexity({ apiKey: this.primaryKey });
      }
      
      private switchToFallback(): boolean {
          if (this.fallbackKey) {
              console.warn("Switching to fallback API key");
              this.currentClient = new Perplexity({ apiKey: this.fallbackKey });
              return true;
          }
          return false;
      }
      
      async search(query: string, options?: any) {
          try {
              return await this.currentClient.search.create({ query, ...options });
          } catch (error: any) {
              if (error.message.toLowerCase().includes('authentication') && this.switchToFallback()) {
                  return await this.currentClient.search.create({ query, ...options });
              }
              throw error;
          }
      }
  }

  // Usage
  const client = new SecurePerplexityClient();
  ```
</CodeGroup>

## Rate Limiting and Efficiency

### Intelligent Rate Limiting

Implement exponential backoff with jitter:

<CodeGroup>
  ```python Python theme={null}
  import time
  import random
  import asyncio
  from typing import TypeVar, Callable, Any
  import perplexity
  from perplexity import Perplexity

  T = TypeVar('T')

  class RateLimitedClient:
      def __init__(self, client: Perplexity, max_retries: int = 5):
          self.client = client
          self.max_retries = max_retries
      
      def _calculate_delay(self, attempt: int) -> float:
          """Calculate delay with exponential backoff and jitter"""
          base_delay = 2 ** attempt
          jitter = random.uniform(0.1, 0.5)
          return min(base_delay + jitter, 60.0)  # Cap at 60 seconds
      
      def with_retry(self, func: Callable[[], T]) -> T:
          """Execute function with intelligent retry logic"""
          last_exception = None
          
          for attempt in range(self.max_retries):
              try:
                  return func()
              except perplexity.RateLimitError as e:
                  last_exception = e
                  if attempt < self.max_retries - 1:
                      delay = self._calculate_delay(attempt)
                      print(f"Rate limited. Retrying in {delay:.2f}s (attempt {attempt + 1})")
                      time.sleep(delay)
                      continue
                  raise e
              except perplexity.APIConnectionError as e:
                  last_exception = e
                  if attempt < self.max_retries - 1:
                      delay = min(2 ** attempt, 10.0)  # Shorter delay for connection errors
                      print(f"Connection error. Retrying in {delay:.2f}s")
                      time.sleep(delay)
                      continue
                  raise e
          
          raise last_exception
      
      def search(self, query: str, **kwargs):
          return self.with_retry(
              lambda: self.client.search.create(query=query, **kwargs)
          )

  # Usage
  client = RateLimitedClient(Perplexity())
  result = client.search("artificial intelligence")
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  class RateLimitedClient {
      private client: Perplexity;
      private maxRetries: number;
      
      constructor(client: Perplexity, maxRetries: number = 5) {
          this.client = client;
          this.maxRetries = maxRetries;
      }
      
      private calculateDelay(attempt: number): number {
          const baseDelay = 2 ** attempt * 1000; // Convert to milliseconds
          const jitter = Math.random() * 500; // 0-500ms jitter
          return Math.min(baseDelay + jitter, 60000); // Cap at 60 seconds
      }
      
      async withRetry<T>(func: () => Promise<T>): Promise<T> {
          let lastError: any;
          
          for (let attempt = 0; attempt < this.maxRetries; attempt++) {
              try {
                  return await func();
              } catch (error: any) {
                  lastError = error;
                  
                  if (error.constructor.name === 'RateLimitError') {
                      if (attempt < this.maxRetries - 1) {
                          const delay = this.calculateDelay(attempt);
                          console.log(`Rate limited. Retrying in ${delay}ms (attempt ${attempt + 1})`);
                          await new Promise(resolve => setTimeout(resolve, delay));
                          continue;
                      }
                  } else if (error.constructor.name === 'APIConnectionError') {
                      if (attempt < this.maxRetries - 1) {
                          const delay = Math.min(2 ** attempt * 1000, 10000);
                          console.log(`Connection error. Retrying in ${delay}ms`);
                          await new Promise(resolve => setTimeout(resolve, delay));
                          continue;
                      }
                  }
                  
                  throw error;
              }
          }
          
          throw lastError;
      }
      
      async search(query: string, options?: any) {
          return this.withRetry(() => 
              this.client.search.create({ query, ...options })
          );
      }
  }

  // Usage
  const client = new RateLimitedClient(new Perplexity());
  const result = await client.search("artificial intelligence");
  ```
</CodeGroup>

### Request Batching

Efficiently batch multiple requests:

<CodeGroup>
  ```python Python theme={null}
  import asyncio
  from typing import Callable, Awaitable, List, TypeVar, Generic
  from perplexity import AsyncPerplexity, DefaultAioHttpClient

  T = TypeVar('T')

  class BatchProcessor(Generic[T]):
      def __init__(self, batch_size: int = 5, delay_between_batches: float = 1.0):
          self.batch_size = batch_size
          self.delay_between_batches = delay_between_batches
      
      async def process_batch(
          self, 
          items: List[str], 
          process_func: Callable[[str], Awaitable[T]]
      ) -> List[T]:
          """Process items in batches with rate limiting"""
          results = []
          
          for i in range(0, len(items), self.batch_size):
              batch = items[i:i + self.batch_size]
              
              # Process batch concurrently
              tasks = [process_func(item) for item in batch]
              batch_results = await asyncio.gather(*tasks, return_exceptions=True)
              
              # Filter out exceptions and collect results
              for result in batch_results:
                  if not isinstance(result, Exception):
                      results.append(result)
              
              # Delay between batches
              if i + self.batch_size < len(items):
                  await asyncio.sleep(self.delay_between_batches)
          
          return results

  # Usage
  async def main():
      processor = BatchProcessor(batch_size=3, delay_between_batches=0.5)
      
      async with AsyncPerplexity(
          http_client=DefaultAioHttpClient()
      ) as client:
          
          async def search_query(query: str):
              return await client.search.create(query=query)
          
          queries = ["AI", "ML", "DL", "NLP", "CV"]
          results = await processor.process_batch(queries, search_query)
          
          print(f"Processed {len(results)} successful queries")

  asyncio.run(main())
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  class BatchProcessor<T> {
      constructor(
          private batchSize: number = 5,
          private delayBetweenBatches: number = 1000
      ) {}
      
      async processBatch<R>(
          items: T[],
          processFunc: (item: T) => Promise<R>
      ): Promise<R[]> {
          const results: R[] = [];
          
          for (let i = 0; i < items.length; i += this.batchSize) {
              const batch = items.slice(i, i + this.batchSize);
              
              // Process batch concurrently
              const tasks = batch.map(item => 
                  processFunc(item).catch(error => error)
              );
              const batchResults = await Promise.all(tasks);
              
              // Filter out exceptions and collect results
              for (const result of batchResults) {
                  if (!(result instanceof Error)) {
                      results.push(result);
                  }
              }
              
              // Delay between batches
              if (i + this.batchSize < items.length) {
                  await new Promise(resolve => 
                      setTimeout(resolve, this.delayBetweenBatches)
                  );
              }
          }
          
          return results;
      }
  }

  // Usage
  async function main() {
      const processor = new BatchProcessor<string>(3, 500);
      const client = new Perplexity();
      
      const searchQuery = (query: string) => 
          client.search.create({ query });
      
      const queries = ["AI", "ML", "DL", "NLP", "CV"];
      const results = await processor.processBatch(queries, searchQuery);
      
      console.log(`Processed ${results.length} successful queries`);
  }

  main();
  ```
</CodeGroup>

## Production Configuration

### Configuration Management

Use environment-based configuration for different deployment stages:

<CodeGroup>
  ```python Python theme={null}
  import os
  from dataclasses import dataclass
  from typing import Optional
  import httpx
  from perplexity import Perplexity, DefaultHttpxClient

  @dataclass
  class PerplexityConfig:
      api_key: str
      max_retries: int = 3
      timeout_seconds: float = 30.0
      max_connections: int = 100
      max_keepalive: int = 20
      environment: str = "production"
      
      @classmethod
      def from_env(cls) -> "PerplexityConfig":
          """Load configuration from environment variables"""
          api_key = os.getenv("PERPLEXITY_API_KEY")
          if not api_key:
              raise ValueError("PERPLEXITY_API_KEY environment variable is required")
          
          return cls(
              api_key=api_key,
              max_retries=int(os.getenv("PERPLEXITY_MAX_RETRIES", "3")),
              timeout_seconds=float(os.getenv("PERPLEXITY_TIMEOUT", "30.0")),
              max_connections=int(os.getenv("PERPLEXITY_MAX_CONNECTIONS", "100")),
              max_keepalive=int(os.getenv("PERPLEXITY_MAX_KEEPALIVE", "20")),
              environment=os.getenv("ENVIRONMENT", "production")
          )
      
      def create_client(self) -> Perplexity:
          """Create optimized client based on configuration"""
          timeout = httpx.Timeout(
              connect=5.0,
              read=self.timeout_seconds,
              write=10.0,
              pool=10.0
          )
          
          limits = httpx.Limits(
              max_keepalive_connections=self.max_keepalive,
              max_connections=self.max_connections,
              keepalive_expiry=60.0 if self.environment == "production" else 30.0
          )
          
          return Perplexity(
              api_key=self.api_key,
              max_retries=self.max_retries,
              timeout=timeout,
              http_client=DefaultHttpxClient(limits=limits)
          )

  # Usage
  config = PerplexityConfig.from_env()
  client = config.create_client()
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';
  import https from 'https';

  interface PerplexityConfig {
      apiKey: string;
      maxRetries: number;
      timeoutMs: number;
      maxConnections: number;
      maxKeepalive: number;
      environment: string;
  }

  class ConfigManager {
      static fromEnv(): PerplexityConfig {
          const apiKey = process.env.PERPLEXITY_API_KEY;
          if (!apiKey) {
              throw new Error("PERPLEXITY_API_KEY environment variable is required");
          }
          
          return {
              apiKey,
              maxRetries: parseInt(process.env.PERPLEXITY_MAX_RETRIES || '3'),
              timeoutMs: parseInt(process.env.PERPLEXITY_TIMEOUT || '30000'),
              maxConnections: parseInt(process.env.PERPLEXITY_MAX_CONNECTIONS || '100'),
              maxKeepalive: parseInt(process.env.PERPLEXITY_MAX_KEEPALIVE || '20'),
              environment: process.env.NODE_ENV || 'production'
          };
      }
      
      static createClient(config: PerplexityConfig): Perplexity {
          const httpsAgent = new https.Agent({
              keepAlive: true,
              keepAliveMsecs: config.environment === 'production' ? 60000 : 30000,
              maxSockets: config.maxConnections,
              maxFreeSockets: config.maxKeepalive,
              timeout: config.timeoutMs
          });
          
          return new Perplexity({
              apiKey: config.apiKey,
              maxRetries: config.maxRetries,
              timeout: config.timeoutMs,
              httpAgent: httpsAgent
          } as any);
      }
  }

  // Usage
  const config = ConfigManager.fromEnv();
  const client = ConfigManager.createClient(config);
  ```
</CodeGroup>

### Monitoring and Logging

Implement comprehensive monitoring:

<CodeGroup>
  ```python Python theme={null}
  import logging
  import time
  import functools
  from typing import Any, Callable
  from perplexity import Perplexity
  import perplexity

  # Configure logging
  logging.basicConfig(
      level=logging.INFO,
      format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
  )
  logger = logging.getLogger(__name__)

  class MonitoredPerplexityClient:
      def __init__(self, client: Perplexity):
          self.client = client
          self.request_count = 0
          self.error_count = 0
          self.total_response_time = 0.0
      
      def _log_request(self, method: str, **kwargs):
          """Log request details"""
          self.request_count += 1
          logger.info(f"Making {method} request #{self.request_count}")
          logger.debug(f"Request parameters: {kwargs}")
      
      def _log_response(self, method: str, duration: float, success: bool = True):
          """Log response details"""
          self.total_response_time += duration
          avg_response_time = self.total_response_time / self.request_count
          
          if success:
              logger.info(f"{method} completed in {duration:.2f}s (avg: {avg_response_time:.2f}s)")
          else:
              self.error_count += 1
              logger.error(f"{method} failed after {duration:.2f}s (errors: {self.error_count})")
      
      def search(self, query: str, **kwargs):
          self._log_request("search", query=query, **kwargs)
          start_time = time.time()
          
          try:
              result = self.client.search.create(query=query, **kwargs)
              duration = time.time() - start_time
              self._log_response("search", duration, success=True)
              return result
          except Exception as e:
              duration = time.time() - start_time
              self._log_response("search", duration, success=False)
              logger.error(f"Search error: {type(e).__name__}: {e}")
              raise
      
      def get_stats(self):
          """Get client statistics"""
          return {
              "total_requests": self.request_count,
              "error_count": self.error_count,
              "success_rate": (self.request_count - self.error_count) / max(self.request_count, 1),
              "avg_response_time": self.total_response_time / max(self.request_count, 1)
          }

  # Usage
  client = MonitoredPerplexityClient(Perplexity())
  result = client.search("machine learning")
  print(client.get_stats())
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  interface ClientStats {
      totalRequests: number;
      errorCount: number;
      successRate: number;
      avgResponseTime: number;
  }

  class MonitoredPerplexityClient {
      private client: Perplexity;
      private requestCount: number = 0;
      private errorCount: number = 0;
      private totalResponseTime: number = 0;
      
      constructor(client: Perplexity) {
          this.client = client;
      }
      
      private logRequest(method: string, params: any): void {
          this.requestCount++;
          console.log(`Making ${method} request #${this.requestCount}`);
          console.debug(`Request parameters:`, params);
      }
      
      private logResponse(method: string, duration: number, success: boolean = true): void {
          this.totalResponseTime += duration;
          const avgResponseTime = this.totalResponseTime / this.requestCount;
          
          if (success) {
              console.log(`${method} completed in ${duration.toFixed(2)}ms (avg: ${avgResponseTime.toFixed(2)}ms)`);
          } else {
              this.errorCount++;
              console.error(`${method} failed after ${duration.toFixed(2)}ms (errors: ${this.errorCount})`);
          }
      }
      
      async search(query: string, options?: any) {
          this.logRequest("search", { query, ...options });
          const startTime = performance.now();
          
          try {
              const result = await this.client.search.create({ query, ...options });
              const duration = performance.now() - startTime;
              this.logResponse("search", duration, true);
              return result;
          } catch (error) {
              const duration = performance.now() - startTime;
              this.logResponse("search", duration, false);
              console.error(`Search error: ${error}`);
              throw error;
          }
      }
      
      getStats(): ClientStats {
          return {
              totalRequests: this.requestCount,
              errorCount: this.errorCount,
              successRate: (this.requestCount - this.errorCount) / Math.max(this.requestCount, 1),
              avgResponseTime: this.totalResponseTime / Math.max(this.requestCount, 1)
          };
      }
  }

  // Usage
  const client = new MonitoredPerplexityClient(new Perplexity());
  const result = await client.search("machine learning");
  console.log(client.getStats());
  ```
</CodeGroup>

## Error Handling Best Practices

### Graceful Degradation

Implement fallback strategies for different error types:

<CodeGroup>
  ```python Python theme={null}
  from typing import Optional, Dict, Any
  import perplexity
  from perplexity import Perplexity

  class ResilientPerplexityClient:
      def __init__(self, client: Perplexity):
          self.client = client
          self.circuit_breaker_threshold = 5
          self.circuit_breaker_count = 0
          self.circuit_breaker_open = False
      
      def _should_circuit_break(self) -> bool:
          """Check if circuit breaker should be triggered"""
          return self.circuit_breaker_count >= self.circuit_breaker_threshold
      
      def _record_failure(self):
          """Record a failure for circuit breaker"""
          self.circuit_breaker_count += 1
          if self._should_circuit_break():
              self.circuit_breaker_open = True
              print("Circuit breaker activated - temporarily disabling API calls")
      
      def _record_success(self):
          """Record a success - reset circuit breaker"""
          self.circuit_breaker_count = 0
          self.circuit_breaker_open = False
      
      def search_with_fallback(
          self, 
          query: str, 
          fallback_response: Optional[Dict[str, Any]] = None
      ):
          """Search with graceful degradation"""
          if self.circuit_breaker_open:
              print("Circuit breaker open - returning fallback response")
              return fallback_response or {
                  "query": query,
                  "results": [],
                  "status": "service_unavailable"
              }
          
          try:
              result = self.client.search.create(query=query)
              self._record_success()
              return result
              
          except perplexity.RateLimitError:
              print("Rate limited - implementing backoff strategy")
              # Could implement intelligent backoff here
              raise
              
          except perplexity.APIConnectionError as e:
              print(f"Connection error: {e}")
              self._record_failure()
              return fallback_response or {
                  "query": query,
                  "results": [],
                  "status": "connection_error"
              }
              
          except Exception as e:
              print(f"Unexpected error: {e}")
              self._record_failure()
              return fallback_response or {
                  "query": query,
                  "results": [],
                  "status": "error"
              }

  # Usage
  client = ResilientPerplexityClient(Perplexity())
  result = client.search_with_fallback("machine learning")
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  interface FallbackResponse {
      query: string;
      results: any[];
      status: string;
  }

  class ResilientPerplexityClient {
      private client: Perplexity;
      private circuitBreakerThreshold: number = 5;
      private circuitBreakerCount: number = 0;
      private circuitBreakerOpen: boolean = false;
      
      constructor(client: Perplexity) {
          this.client = client;
      }
      
      private shouldCircuitBreak(): boolean {
          return this.circuitBreakerCount >= this.circuitBreakerThreshold;
      }
      
      private recordFailure(): void {
          this.circuitBreakerCount++;
          if (this.shouldCircuitBreak()) {
              this.circuitBreakerOpen = true;
              console.log("Circuit breaker activated - temporarily disabling API calls");
          }
      }
      
      private recordSuccess(): void {
          this.circuitBreakerCount = 0;
          this.circuitBreakerOpen = false;
      }
      
      async searchWithFallback(
          query: string,
          fallbackResponse?: FallbackResponse
      ): Promise<any> {
          if (this.circuitBreakerOpen) {
              console.log("Circuit breaker open - returning fallback response");
              return fallbackResponse || {
                  query,
                  results: [],
                  status: "service_unavailable"
              };
          }
          
          try {
              const result = await this.client.search.create({ query });
              this.recordSuccess();
              return result;
              
          } catch (error: any) {
              if (error.constructor.name === 'RateLimitError') {
                  console.log("Rate limited - implementing backoff strategy");
                  throw error;
              } else if (error.constructor.name === 'APIConnectionError') {
                  console.log(`Connection error: ${error.message}`);
                  this.recordFailure();
                  return fallbackResponse || {
                      query,
                      results: [],
                      status: "connection_error"
                  };
              } else {
                  console.log(`Unexpected error: ${error.message}`);
                  this.recordFailure();
                  return fallbackResponse || {
                      query,
                      results: [],
                      status: "error"
                  };
              }
          }
      }
  }

  // Usage
  const client = new ResilientPerplexityClient(new Perplexity());
  const result = await client.searchWithFallback("machine learning");
  ```
</CodeGroup>

## Testing Best Practices

### Unit Testing with Mocking

Create testable code with proper mocking:

<CodeGroup>
  ```python Python theme={null}
  import unittest
  from unittest.mock import Mock, patch
  from perplexity import Perplexity, RateLimitError
  from perplexity.types.search_create_response import SearchCreateResponse, Result

  class TestPerplexityIntegration(unittest.TestCase):
      def setUp(self):
          self.mock_client = Mock(spec=Perplexity)

      def test_search_success(self):
          # Mock successful response
          mock_result = Result(
              title="Test Result",
              url="https://example.com",
              snippet="Test snippet"
          )

          mock_response = SearchCreateResponse(
              id="search_123",
              results=[mock_result]
          )

          self.mock_client.search.create.return_value = mock_response

          # Test your application logic
          result = self.mock_client.search.create(query="test query")

          self.assertEqual(result.id, "search_123")
          self.assertEqual(len(result.results), 1)
          self.assertEqual(result.results[0].title, "Test Result")

      @patch('perplexity.Perplexity')
      def test_rate_limit_handling(self, mock_perplexity_class):
          # Mock rate limit error
          mock_client = Mock()
          mock_perplexity_class.return_value = mock_client
          mock_client.search.create.side_effect = RateLimitError(
              "Rate limited",
              response=Mock(status_code=429),
              body={}
          )

          # Test your error handling logic here
          with self.assertRaises(RateLimitError):
              mock_client.search.create(query="test")

  if __name__ == '__main__':
      unittest.main()
  ```

  ```typescript TypeScript theme={null}
  import { jest, describe, beforeEach, test, expect } from '@jest/globals';
  import Perplexity from '@perplexity-ai/perplexity_ai';

  // Mock the Perplexity client
  jest.mock('@perplexity-ai/perplexity_ai');

  describe('Perplexity Integration', () => {
      let mockClient: any;

      beforeEach(() => {
          mockClient = new Perplexity();
      });

      test('should handle successful search', async () => {
          const mockResponse = {
              id: "search_123",
              results: [{ title: "Test Result", url: "https://example.com", snippet: "Test snippet" }]
          };

          jest.spyOn(mockClient.search, 'create').mockResolvedValue(mockResponse as any);

          const result = await mockClient.search.create({ query: "test query" });

          expect(result.id).toBe("search_123");
          expect(result.results).toHaveLength(1);
          expect(result.results[0].title).toBe("Test Result");
      });

      test('should handle rate limit errors', async () => {
          const rateLimitError = new Error('Rate limited');

          jest.spyOn(mockClient.search, 'create').mockRejectedValue(rateLimitError);

          await expect(mockClient.search.create({ query: "test" })).rejects.toThrow('Rate limited');
      });
  });
  ```
</CodeGroup>

## Performance Best Practices Summary

<Steps>
  <Step title="Use environment variables for configuration">
    Never hardcode API keys or configuration values.
  </Step>

  <Step title="Implement intelligent rate limiting">
    Use exponential backoff with jitter for retry strategies.
  </Step>

  <Step title="Configure connection pooling">
    Optimize HTTP client settings for your use case.
  </Step>

  <Step title="Monitor and log appropriately">
    Track performance metrics and error rates.
  </Step>

  <Step title="Implement graceful degradation">
    Provide fallback responses when APIs are unavailable.
  </Step>

  <Step title="Write testable code">
    Use dependency injection and mocking for unit tests.
  </Step>
</Steps>

## Related Resources

<CardGroup>
  <Card title="Error Handling" icon="alert-triangle" href="/docs/sdk/error-handling">
    Comprehensive error handling strategies
  </Card>

  <Card title="Performance" icon="bolt" href="/docs/sdk/performance">
    Async operations and optimization techniques
  </Card>

  <Card title="Configuration" icon="settings" href="/docs/sdk/configuration">
    Production-ready configuration patterns
  </Card>

  <Card title="Type Safety" icon="shield-check" href="/docs/sdk/type-safety">
    Leveraging types for safer code
  </Card>
</CardGroup>


# Configuration
Source: https://docs.perplexity.ai/docs/sdk/configuration

Learn how to configure the Perplexity SDKs for retries, timeouts, proxies, and advanced HTTP client customization.

## Overview

The Perplexity SDKs provide extensive configuration options to customize client behavior for different environments and use cases. This guide covers retry configuration, timeout settings, and custom HTTP client setup.

## Retries and Timeouts

### Basic Retry Configuration

Configure how the SDK handles failed requests:

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity
  import httpx

  client = Perplexity(
      max_retries=3,  # Default is 2
      timeout=httpx.Timeout(30.0, read=10.0, write=5.0, connect=2.0)
  )

  # Per-request configuration
  search = client.with_options(max_retries=5).search.create(
      query="example"
  )
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity({
      maxRetries: 3, // Default is 2
      timeout: 30000, // 30 seconds in milliseconds
  });

  // Per-request configuration
  const search = await client.withOptions({ maxRetries: 5 }).search.create({
      query: "example"
  });
  ```
</CodeGroup>

### Advanced Timeout Configuration

Set granular timeout controls for different phases of the request:

<CodeGroup>
  ```python Python theme={null}
  import httpx
  from perplexity import Perplexity

  # Detailed timeout configuration
  timeout_config = httpx.Timeout(
      connect=5.0,    # Time to establish connection
      read=30.0,      # Time to read response
      write=10.0,     # Time to send request
      pool=10.0       # Time to get connection from pool
  )

  client = Perplexity(timeout=timeout_config)

  # For long-running operations
  long_timeout = httpx.Timeout(
      connect=5.0,
      read=120.0,  # 2 minutes for complex queries
      write=10.0,
      pool=10.0
  )

  client_long = Perplexity(timeout=long_timeout)
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  // Basic timeout (applies to entire request)
  const client = new Perplexity({
      timeout: 30000  // 30 seconds
  });

  // For long-running operations
  const clientLong = new Perplexity({
      timeout: 120000  // 2 minutes for complex queries
  });

  // Per-request timeout override
  const result = await client.withOptions({ 
      timeout: 60000  // 1 minute for this specific request
  }).chat.completions.create({
      model: "sonar-pro",
      messages: [{ role: "user", content: "Complex research query..." }]
  });
  ```
</CodeGroup>

## Custom HTTP Client

### Proxy Configuration

Configure the SDK to work with corporate proxies:

<CodeGroup>
  ```python Python theme={null}
  import httpx
  from perplexity import Perplexity, DefaultHttpxClient

  # HTTP Proxy
  client = Perplexity(
      http_client=DefaultHttpxClient(
          proxy="http://proxy.company.com:8080"
      )
  )

  # HTTPS Proxy with authentication
  client_auth = Perplexity(
      http_client=DefaultHttpxClient(
          proxy="http://username:password@proxy.company.com:8080"
      )
  )

  # SOCKS proxy
  client_socks = Perplexity(
      http_client=DefaultHttpxClient(
          proxy="socks5://proxy.company.com:1080"
      )
  )
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';
  import { HttpsProxyAgent } from 'https-proxy-agent';
  import { SocksProxyAgent } from 'socks-proxy-agent';

  // HTTP/HTTPS Proxy
  const client = new Perplexity({
      httpAgent: new HttpsProxyAgent('http://proxy.company.com:8080')
  } as any);

  // Proxy with authentication
  const clientAuth = new Perplexity({
      httpAgent: new HttpsProxyAgent('http://username:password@proxy.company.com:8080')
  } as any);

  // SOCKS proxy
  const clientSocks = new Perplexity({
      httpAgent: new SocksProxyAgent('socks5://proxy.company.com:1080')
  } as any);
  ```
</CodeGroup>

### Custom Headers and User Agent

Add custom headers to all requests:

<CodeGroup>
  ```python Python theme={null}
  import httpx
  from perplexity import Perplexity, DefaultHttpxClient

  # Custom headers
  headers = {
      "User-Agent": "MyApp/1.0",
      "X-Custom-Header": "custom-value"
  }

  client = Perplexity(
      http_client=DefaultHttpxClient(
          headers=headers
      )
  )

  # Advanced HTTP client configuration
  transport = httpx.HTTPTransport(
      local_address="0.0.0.0",  # Bind to specific interface
      verify=True,              # SSL verification
      cert=None,                # Client certificate
      http2=True               # Enable HTTP/2
  )

  client_advanced = Perplexity(
      http_client=DefaultHttpxClient(
          transport=transport,
          headers=headers
      )
  )
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  // Custom headers
  const client = new Perplexity({
      defaultHeaders: {
          "User-Agent": "MyApp/1.0",
          "X-Custom-Header": "custom-value"
      }
  });

  // Advanced fetch configuration
  const clientAdvanced = new Perplexity({
      fetch: (url, options) => {
          return fetch(url, {
              ...options,
              headers: {
                  ...options?.headers,
                  "User-Agent": "MyApp/1.0",
                  "X-Custom-Header": "custom-value"
              }
          });
      }
  });
  ```
</CodeGroup>

### SSL/TLS Configuration

Configure SSL verification and certificates:

<CodeGroup>
  ```python Python theme={null}
  import httpx
  import ssl
  from perplexity import Perplexity, DefaultHttpxClient

  # Disable SSL verification (not recommended for production)
  client_no_ssl = Perplexity(
      http_client=DefaultHttpxClient(
          verify=False
      )
  )

  # Custom SSL context
  ssl_context = ssl.create_default_context()
  ssl_context.check_hostname = False
  ssl_context.verify_mode = ssl.CERT_NONE

  client_custom_ssl = Perplexity(
      http_client=DefaultHttpxClient(
          verify=ssl_context
      )
  )

  # Client certificate authentication
  client_cert = Perplexity(
      http_client=DefaultHttpxClient(
          cert=("client.crt", "client.key")
      )
  )
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';
  import https from 'https';

  // Custom HTTPS agent with SSL options
  const httpsAgent = new https.Agent({
      rejectUnauthorized: false, // Disable SSL verification (not recommended)
      keepAlive: true,
      maxSockets: 50
  });

  const client = new Perplexity({
      httpAgent: httpsAgent
  } as any);

  // For Node.js environments with custom CA certificates
  const httpsAgentCA = new https.Agent({
      ca: ['/* your CA certificate PEM */'],
      cert: '/* client certificate PEM */',
      key: '/* client private key PEM */',
  } as any);

  const clientCert = new Perplexity({
      httpAgent: httpsAgentCA
  } as any);
  ```
</CodeGroup>

## Connection Pooling

Optimize performance with connection pooling:

<CodeGroup>
  ```python Python theme={null}
  import httpx
  from perplexity import Perplexity, DefaultHttpxClient

  # Configure connection limits
  limits = httpx.Limits(
      max_keepalive_connections=20,  # Keep-alive connections
      max_connections=100,           # Total connections
      keepalive_expiry=30.0         # Keep-alive timeout
  )

  client = Perplexity(
      http_client=DefaultHttpxClient(
          limits=limits
      )
  )

  # For high-throughput applications
  high_throughput_limits = httpx.Limits(
      max_keepalive_connections=100,
      max_connections=500,
      keepalive_expiry=60.0
  )

  client_high_throughput = Perplexity(
      http_client=DefaultHttpxClient(
          limits=high_throughput_limits
      )
  )
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';
  import https from 'https';

  // Configure agent pool settings
  const httpsAgent = new https.Agent({
      keepAlive: true,
      keepAliveMsecs: 30000,  // 30 seconds
      maxSockets: 50,         // Max connections per host
      maxFreeSockets: 10,     // Max idle connections per host
      timeout: 60000          // Socket timeout
  });

  const client = new Perplexity({
      httpAgent: httpsAgent
  } as any);

  // For high-throughput applications
  const highThroughputAgent = new https.Agent({
      keepAlive: true,
      keepAliveMsecs: 60000,
      maxSockets: 200,
      maxFreeSockets: 50,
      timeout: 120000
  });

  const clientHighThroughput = new Perplexity({
      httpAgent: highThroughputAgent
  } as any);
  ```
</CodeGroup>

## Environment-Specific Configuration

### Development Configuration

Settings optimized for development and debugging:

<CodeGroup>
  ```python Python theme={null}
  import httpx
  from perplexity import Perplexity, DefaultHttpxClient

  # Development configuration
  dev_client = Perplexity(
      max_retries=1,           # Fail fast in development
      timeout=httpx.Timeout(10.0),  # Short timeout
      http_client=DefaultHttpxClient(
          # Enable detailed logging
          event_hooks={
              'request': [lambda request: print(f"Request: {request.method} {request.url}")],
              'response': [lambda response: print(f"Response: {response.status_code}")]
          }
      )
  )
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  // Development configuration
  const devClient = new Perplexity({
      maxRetries: 1,     // Fail fast in development
      timeout: 10000,    // 10 second timeout
      
      // Custom fetch with logging
      fetch: (url, options) => {
          console.log(`Request: ${options?.method || 'GET'} ${url}`);
          return fetch(url, options).then(response => {
              console.log(`Response: ${response.status}`);
              return response;
          });
      }
  });
  ```
</CodeGroup>

### Production Configuration

Settings optimized for production environments:

<CodeGroup>
  ```python Python theme={null}
  import httpx
  from perplexity import Perplexity, DefaultHttpxClient

  # Production configuration
  prod_limits = httpx.Limits(
      max_keepalive_connections=50,
      max_connections=200,
      keepalive_expiry=60.0
  )

  prod_timeout = httpx.Timeout(
      connect=5.0,
      read=60.0,
      write=10.0,
      pool=10.0
  )

  prod_client = Perplexity(
      max_retries=3,
      timeout=prod_timeout,
      http_client=DefaultHttpxClient(
          limits=prod_limits,
          verify=True,  # Always verify SSL in production
          http2=True    # Enable HTTP/2 for better performance
      )
  )
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';
  import https from 'https';

  // Production configuration
  const prodAgent = new https.Agent({
      keepAlive: true,
      keepAliveMsecs: 60000,
      maxSockets: 100,
      maxFreeSockets: 20,
      timeout: 60000
  });

  const prodClient = new Perplexity({
      maxRetries: 3,
      timeout: 60000,
      httpAgent: prodAgent
  } as any);
  ```
</CodeGroup>

## Configuration Patterns

### Environment-Based Configuration

Use environment variables to configure the client:

<CodeGroup>
  ```python Python theme={null}
  import os
  import httpx
  from perplexity import Perplexity, DefaultHttpxClient

  def create_client():
      # Base configuration
      timeout = httpx.Timeout(
          connect=float(os.getenv('PERPLEXITY_CONNECT_TIMEOUT', '5.0')),
          read=float(os.getenv('PERPLEXITY_READ_TIMEOUT', '30.0')),
          write=float(os.getenv('PERPLEXITY_WRITE_TIMEOUT', '10.0'))
      )
      
      max_retries = int(os.getenv('PERPLEXITY_MAX_RETRIES', '3'))
      
      # Optional proxy configuration
      proxy = os.getenv('PERPLEXITY_PROXY')
      http_client_kwargs = {}
      if proxy:
          http_client_kwargs['proxy'] = proxy
      
      return Perplexity(
          max_retries=max_retries,
          timeout=timeout,
          http_client=DefaultHttpxClient(**http_client_kwargs)
      )

  client = create_client()
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';
  import { HttpsProxyAgent } from 'https-proxy-agent';

  function createClient(): Perplexity {
      const maxRetries = parseInt(process.env.PERPLEXITY_MAX_RETRIES || '3');
      const timeout = parseInt(process.env.PERPLEXITY_TIMEOUT || '30000');
      
      const config: any = {
          maxRetries,
          timeout
      };
      
      // Optional proxy configuration
      if (process.env.PERPLEXITY_PROXY) {
          config.httpAgent = new HttpsProxyAgent(process.env.PERPLEXITY_PROXY);
      }
      
      return new Perplexity(config);
  }

  const client = createClient();
  ```
</CodeGroup>

### Configuration Factory

Create reusable configuration patterns:

<CodeGroup>
  ```python Python theme={null}
  import httpx
  from perplexity import Perplexity, DefaultHttpxClient

  class PerplexityClientFactory:
      @staticmethod
      def development():
          return Perplexity(
              max_retries=1,
              timeout=httpx.Timeout(10.0)
          )
      
      @staticmethod
      def production():
          return Perplexity(
              max_retries=3,
              timeout=httpx.Timeout(connect=5.0, read=60.0, write=10.0),
              http_client=DefaultHttpxClient(
                  limits=httpx.Limits(
                      max_keepalive_connections=50,
                      max_connections=200
                  )
              )
          )
      
      @staticmethod
      def high_throughput():
          return Perplexity(
              max_retries=2,
              timeout=httpx.Timeout(connect=2.0, read=30.0, write=5.0),
              http_client=DefaultHttpxClient(
                  limits=httpx.Limits(
                      max_keepalive_connections=100,
                      max_connections=500
                  )
              )
          )

  # Usage
  client = PerplexityClientFactory.production()
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';
  import https from 'https';

  class PerplexityClientFactory {
      static development(): Perplexity {
          return new Perplexity({
              maxRetries: 1,
              timeout: 10000
          });
      }
      
      static production(): Perplexity {
          const agent = new https.Agent({
              keepAlive: true,
              maxSockets: 100,
              timeout: 60000
          });
          
          return new Perplexity({
              maxRetries: 3,
              timeout: 60000,
              httpAgent: agent
          } as any);
      }
      
      static highThroughput(): Perplexity {
          const agent = new https.Agent({
              keepAlive: true,
              maxSockets: 500,
              maxFreeSockets: 100,
              timeout: 30000
          });
          
          return new Perplexity({
              maxRetries: 2,
              timeout: 30000,
              httpAgent: agent
          } as any);
      }
  }

  // Usage
  const client = PerplexityClientFactory.production();
  ```
</CodeGroup>

## Related Resources

<CardGroup>
  <Card title="Error Handling" icon="alert-triangle" href="/docs/sdk/error-handling">
    Handle timeouts and connection errors
  </Card>

  <Card title="Performance" icon="bolt" href="/docs/sdk/performance">
    Optimize async operations and connection pooling
  </Card>
</CardGroup>


# Error Handling
Source: https://docs.perplexity.ai/docs/sdk/error-handling

Learn how to handle API errors gracefully with the Perplexity SDKs for Python and TypeScript.

## Overview

The Perplexity SDKs provide robust error handling with specific exception types for different error scenarios. This guide covers how to catch and handle common API errors gracefully.

## Common Error Types

The SDKs provide specific exception types for different error scenarios:

* **APIConnectionError** - Network connection issues
* **RateLimitError** - API rate limit exceeded
* **APIStatusError** - HTTP status errors (4xx, 5xx)
* **AuthenticationError** - Invalid API key or authentication issues
* **ValidationError** - Invalid request parameters

## Basic Error Handling

Handle common API errors with try-catch blocks:

<CodeGroup>
  ```python Python theme={null}
  import perplexity
  from perplexity import Perplexity

  client = Perplexity()

  try:
      search = client.search.create(query="machine learning")
      print(search.results)
  except perplexity.APIConnectionError as e:
      print("Network connection failed")
      print(e.__cause__)
  except perplexity.RateLimitError as e:
      print("Rate limit exceeded, please retry later")
  except perplexity.APIStatusError as e:
      print(f"API error: {e.status_code}")
      print(e.response)
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  try {
      const search = await client.search.create({ query: "machine learning" });
      console.log(search.results);
  } catch (error: any) {
      if (error.constructor.name === 'APIConnectionError') {
          console.log("Network connection failed");
          console.log(error.cause);
      } else if (error.constructor.name === 'RateLimitError') {
          console.log("Rate limit exceeded, please retry later");
      } else if (error.constructor.name === 'APIStatusError') {
          console.log(`API error: ${error.status}`);
          console.log(error.response);
      }
  }
  ```
</CodeGroup>

<Info>
  Common HTTP status codes: 400 (Bad Request), 401 (Authentication), 403 (Permission Denied), 404 (Not Found), 429 (Rate Limit), 500+ (Server Error).
</Info>

## Advanced Error Handling

### Exponential Backoff for Rate Limits

Implement intelligent retry logic for rate limit errors:

<CodeGroup>
  ```python Python theme={null}
  import time
  import random
  import perplexity
  from perplexity import Perplexity

  def search_with_retry(client, query, max_retries=3):
      for attempt in range(max_retries):
          try:
              return client.search.create(query=query)
          except perplexity.RateLimitError:
              if attempt == max_retries - 1:
                  raise  # Re-raise on final attempt
              
              # Exponential backoff with jitter
              delay = (2 ** attempt) + random.uniform(0, 1)
              print(f"Rate limited. Retrying in {delay:.2f} seconds...")
              time.sleep(delay)
          except perplexity.APIConnectionError:
              if attempt == max_retries - 1:
                  raise
              
              # Shorter delay for connection errors
              delay = 1 + random.uniform(0, 1)
              print(f"Connection error. Retrying in {delay:.2f} seconds...")
              time.sleep(delay)

  # Usage
  client = Perplexity()
  result = search_with_retry(client, "artificial intelligence")
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  async function searchWithRetry(
      client: Perplexity, 
      query: string, 
      maxRetries: number = 3
  ) {
      for (let attempt = 0; attempt < maxRetries; attempt++) {
          try {
              return await client.search.create({ query });
          } catch (error: any) {
              if (attempt === maxRetries - 1) {
                  throw error; // Re-throw on final attempt
              }

              if (error.constructor.name === 'RateLimitError') {
                  // Exponential backoff with jitter
                  const delay = (2 ** attempt + Math.random()) * 1000;
                  console.log(`Rate limited. Retrying in ${delay}ms...`);
                  await new Promise(resolve => setTimeout(resolve, delay));
              } else if (error.constructor.name === 'APIConnectionError') {
                  // Shorter delay for connection errors
                  const delay = (1 + Math.random()) * 1000;
                  console.log(`Connection error. Retrying in ${delay}ms...`);
                  await new Promise(resolve => setTimeout(resolve, delay));
              } else {
                  throw error; // Don't retry other errors
              }
          }
      }
  }

  // Usage
  const client = new Perplexity();
  const result = await searchWithRetry(client, "artificial intelligence");
  ```
</CodeGroup>

### Error Context and Debugging

Extract detailed error information for debugging:

<CodeGroup>
  ```python Python theme={null}
  import perplexity
  from perplexity import Perplexity

  client = Perplexity()

  try:
      chat = client.chat.completions.create(
          model="sonar-pro",
          messages=[{"role": "user", "content": "What's the weather?"}]
      )
  except perplexity.APIStatusError as e:
      print(f"Status Code: {e.status_code}")
      print(f"Error Type: {e.type}")
      print(f"Error Message: {e.message}")
      
      # Access raw response for detailed debugging
      if hasattr(e, 'response'):
          print(f"Raw Response: {e.response.text}")
          print(f"Request ID: {e.response.headers.get('X-Request-ID')}")
          
  except perplexity.ValidationError as e:
      print(f"Validation Error: {e}")
      # Handle parameter validation errors
      
  except Exception as e:
      print(f"Unexpected error: {type(e).__name__}: {e}")
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  try {
      const chat = await client.chat.completions.create({
          model: "sonar-pro",
          messages: [{ role: "user", content: "What's the weather?" }]
      });
  } catch (error: any) {
      if (error.constructor.name === 'APIStatusError') {
          console.log(`Status Code: ${error.status}`);
          console.log(`Error Type: ${error.type}`);
          console.log(`Error Message: ${error.message}`);
          
          // Access raw response for detailed debugging
          if (error.response) {
              console.log(`Raw Response: ${await error.response.text()}`);
              console.log(`Request ID: ${error.response.headers.get('X-Request-ID')}`);
          }
      } else if (error.constructor.name === 'ValidationError') {
          console.log(`Validation Error: ${error.message}`);
          // Handle parameter validation errors
      } else {
          console.log(`Unexpected error: ${error.constructor.name}: ${error.message}`);
      }
  }
  ```
</CodeGroup>

## Error Recovery Strategies

### Graceful Degradation

Implement fallback mechanisms when API calls fail:

<CodeGroup>
  ```python Python theme={null}
  import perplexity
  from perplexity import Perplexity

  def get_ai_response(query, fallback_response="I'm sorry, I'm temporarily unavailable."):
      client = Perplexity()
      
      try:
          # Primary: Try online model
          response = client.chat.completions.create(
              model="sonar-pro",
              messages=[{"role": "user", "content": query}]
          )
          return response.choices[0].message.content
          
      except perplexity.RateLimitError:
          try:
              # Fallback: Try offline model if rate limited
              response = client.chat.completions.create(
                  model="llama-3.1-8b-instruct",
                  messages=[{"role": "user", "content": query}]
              )
              return response.choices[0].message.content
          except Exception:
              return fallback_response
              
      except perplexity.APIConnectionError:
          # Network issues - return cached response or fallback
          return fallback_response
          
      except Exception as e:
          print(f"Unexpected error: {e}")
          return fallback_response

  # Usage
  response = get_ai_response("What is machine learning?")
  print(response)
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  async function getAIResponse(
      query: string, 
      fallbackResponse: string = "I'm sorry, I'm temporarily unavailable."
  ): Promise<string> {
      const client = new Perplexity();
      
      try {
          // Primary: Try online model
          const response = await client.chat.completions.create({
              model: "sonar-pro",
              messages: [{ role: "user", content: query }]
          });
          return response.choices[0].message.content as string || "";
          
      } catch (error: any) {
          if (error.constructor.name === 'RateLimitError') {
              try {
                  // Fallback: Try offline model if rate limited
                  const response = await client.chat.completions.create({
                      model: "llama-3.1-8b-instruct",
                      messages: [{ role: "user", content: query }]
                  });
                  return response.choices[0].message.content as string || "";
              } catch {
                  return fallbackResponse;
              }
          } else if (error.constructor.name === 'APIConnectionError') {
              // Network issues - return cached response or fallback
              return fallbackResponse;
          } else {
              console.log(`Unexpected error: ${error.message}`);
              return fallbackResponse;
          }
      }
  }

  // Usage
  const response = await getAIResponse("What is machine learning?");
  console.log(response);
  ```
</CodeGroup>

## Best Practices

<Steps>
  <Step title="Always handle rate limits">
    Rate limiting is common with API usage. Always implement retry logic with exponential backoff.

    <Warning>
      Don't implement aggressive retry loops without delays - this can worsen rate limiting.
    </Warning>
  </Step>

  <Step title="Log errors for monitoring">
    Include proper logging to track error patterns and API health.

    <CodeGroup>
      ```python Python theme={null}
      import logging
      import perplexity
      from perplexity import Perplexity

      logging.basicConfig(level=logging.INFO)
      logger = logging.getLogger(__name__)

      client = Perplexity()

      try:
          result = client.search.create(query="example")
      except perplexity.APIStatusError as e:
          logger.error(f"API Error {e.status_code}: {e.message}", 
                      extra={'request_id': e.response.headers.get('X-Request-ID')})
      ```

      ```typescript TypeScript theme={null}
      import Perplexity from '@perplexity-ai/perplexity_ai';

      const client = new Perplexity();

      try {
          const result = await client.search.create({ query: "example" });
      } catch (error: any) {
          console.error(`API Error ${error.status}: ${error.message}`, {
              requestId: error.response?.headers.get('X-Request-ID')
          });
      }
      ```
    </CodeGroup>
  </Step>

  <Step title="Set appropriate timeouts">
    Configure timeouts to prevent hanging requests.

    <CodeGroup>
      ```python Python theme={null}
      import httpx
      from perplexity import Perplexity

      client = Perplexity(
          timeout=httpx.Timeout(connect=5.0, read=30.0, write=5.0, pool=10.0)
      )
      ```

      ```typescript TypeScript theme={null}
      import Perplexity from '@perplexity-ai/perplexity_ai';

      const client = new Perplexity({
          timeout: 30000 // 30 seconds
      });
      ```
    </CodeGroup>
  </Step>

  <Step title="Handle authentication errors">
    Check for invalid API keys and provide helpful error messages.

    <CodeGroup>
      ```python Python theme={null}
      try:
          result = client.search.create(query="test")
      except perplexity.AuthenticationError:
          print("Invalid API key. Please check your PERPLEXITY_API_KEY environment variable.")
      ```

      ```typescript TypeScript theme={null}
      try {
          const result = await client.search.create({ query: "test" });
      } catch (error: any) {
          if (error.constructor.name === 'AuthenticationError') {
              console.log("Invalid API key. Please check your PERPLEXITY_API_KEY environment variable.");
          }
      }
      ```
    </CodeGroup>
  </Step>
</Steps>

## Related Resources

<CardGroup>
  <Card title="Configuration" icon="settings" href="/docs/sdk/configuration">
    Configure timeouts and retries
  </Card>

  <Card title="Best Practices" icon="star" href="/docs/sdk/best-practices">
    Environment variables and rate limiting
  </Card>
</CardGroup>


# Quickstart
Source: https://docs.perplexity.ai/docs/sdk/overview

Learn how to use the official Perplexity SDKs for Python and TypeScript to access the Perplexity APIs with type safety and async support.

## Overview

The official Perplexity SDKs provide convenient access to the Perplexity APIs from Python 3.8+ and Node.js applications. Both SDKs include type definitions for all request parameters and response fields, with both synchronous and asynchronous clients.

Access four APIs: **Agent API** for third-party models with web search tools and presets, **Search** for ranked web search results, **Sonar** for web-grounded AI responses, and **Embeddings** for generating text embeddings.

## Available APIs

<CardGroup>
  <Card title="Agent API" icon="code-circle" href="/docs/agent-api/quickstart">
    Third-party models from OpenAI, Anthropic, Google, and more with presets and web search tools.
  </Card>

  <Card title="Search" icon="search" href="/docs/search/quickstart">
    Ranked web search results with filtering, multi-query support, and domain controls.
  </Card>

  <Card title="Sonar" icon="message" href="/docs/sonar/quickstart">
    AI responses with web-grounded knowledge, conversation context, and streaming support.
  </Card>

  <Card title="Embeddings" icon="cube" href="/docs/embeddings/quickstart">
    Generate high-quality text embeddings for semantic search and RAG.
  </Card>
</CardGroup>

## Installation

Install the SDK for your preferred language:

<CodeGroup>
  ```bash Python theme={null}
  pip install perplexityai
  ```

  ```bash TypeScript theme={null}
  npm install @perplexity-ai/perplexity_ai
  ```
</CodeGroup>

## Authentication

<Card title="Get your Perplexity API Key" icon="key" href="https://console.perplexity.ai">
  Navigate to the **API Keys** tab in the API Portal and generate a new key.
</Card>

After generating the key, set it as an environment variable in your terminal:

<Tabs>
  <Tab title="Windows">
    ```bash theme={null}
    setx PERPLEXITY_API_KEY "your_api_key_here"
    ```
  </Tab>

  <Tab title="MacOS/Linux">
    ```bash theme={null}
    export PERPLEXITY_API_KEY="your_api_key_here"
    ```
  </Tab>
</Tabs>

### Using Environment Variables

You can use the environment variable directly:

<CodeGroup>
  ```python Python theme={null}
  import os
  from perplexity import Perplexity

  client = Perplexity() # Automatically uses PERPLEXITY_API_KEY
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity({
    apiKey: process.env['PERPLEXITY_API_KEY'], // This is the default and can be omitted
  });
  ```
</CodeGroup>

Or use [python-dotenv](https://pypi.org/project/python-dotenv/) (Python) or [dotenv](https://www.npmjs.com/package/dotenv) (Node.js) to load the environment variable from a `.env` file:

<CodeGroup>
  ```python Python theme={null}
  import os
  from dotenv import load_dotenv
  from perplexity import Perplexity

  load_dotenv()

  client = Perplexity() # Uses PERPLEXITY_API_KEY from .env file
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';
  import dotenv from 'dotenv';

  dotenv.config();

  const client = new Perplexity(); // Uses PERPLEXITY_API_KEY from .env file
  ```
</CodeGroup>

<Tip>
  Now you're ready to start using the Perplexity APIs! Choose your API below for step-by-step usage guides.
</Tip>

<CardGroup>
  <Card title="Agent API" icon="code-circle" href="/docs/agent-api/quickstart">
    Get started with third-party models
  </Card>

  <Card title="Search" icon="search" href="/docs/search/quickstart">
    Get started with web search
  </Card>

  <Card title="Sonar" icon="message" href="/docs/sonar/quickstart">
    Get started with AI responses
  </Card>

  <Card title="Embeddings" icon="cube" href="/docs/embeddings/quickstart">
    Get started with text embeddings
  </Card>
</CardGroup>

## Resources

<CardGroup>
  <Card title="Python Package" icon="brand-python" href="https://pypi.org/project/perplexityai/">
    Install from PyPI with pip
  </Card>

  <Card title="Node.js and TypeScript Package" icon="brand-npm" href="https://www.npmjs.com/package/@perplexity-ai/perplexity_ai">
    Install from npm registry
  </Card>
</CardGroup>


# Performance Optimization
Source: https://docs.perplexity.ai/docs/sdk/performance

Learn how to optimize the Perplexity SDKs for high-throughput applications with async support, connection pooling, and raw response access.

## Overview

The Perplexity SDKs provide several features to optimize performance for high-throughput applications. This guide covers async operations, connection pooling, raw response access, and other performance optimization techniques.

## Async Support

### Basic Async Usage

For applications that need to handle multiple requests concurrently:

<CodeGroup>
  ```bash Python Installation theme={null}
  pip install perplexityai[aiohttp]
  ```

  ```bash TypeScript Installation theme={null}
  npm install @perplexity-ai/perplexity_ai
  # Async support is built-in with TypeScript
  ```
</CodeGroup>

<CodeGroup>
  ```python Python theme={null}
  import asyncio
  from perplexity import AsyncPerplexity, DefaultAioHttpClient

  async def main():
      async with AsyncPerplexity(
          http_client=DefaultAioHttpClient()
      ) as client:
          # Single async request
          search = await client.search.create(query="machine learning")
          print(search.results)

  asyncio.run(main())
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  async function main() {
      const client = new Perplexity();
      
      // Async is built-in for TypeScript
      const search = await client.search.create({ query: "machine learning" });
      console.log(search.results);
  }

  main();
  ```
</CodeGroup>

### Concurrent Requests

Process multiple requests simultaneously for better throughput:

<CodeGroup>
  ```python Python theme={null}
  import asyncio
  from perplexity import AsyncPerplexity, DefaultAioHttpClient

  async def concurrent_searches():
      async with AsyncPerplexity(
          http_client=DefaultAioHttpClient()
      ) as client:
          # Concurrent requests
          queries = ["AI", "machine learning", "deep learning", "neural networks"]
          tasks = [
              client.search.create(query=query)
              for query in queries
          ]
          
          results = await asyncio.gather(*tasks)
          
          for i, result in enumerate(results):
              print(f"Query '{queries[i]}': {len(result.results)} results")

  asyncio.run(concurrent_searches())
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  async function concurrentSearches() {
      const client = new Perplexity();
      
      // Concurrent requests
      const queries = ["AI", "machine learning", "deep learning", "neural networks"];
      const tasks = queries.map(query => 
          client.search.create({ query })
      );
      
      const results = await Promise.all(tasks);
      
      results.forEach((result, i) => {
          console.log(`Query '${queries[i]}': ${result.results.length} results`);
      });
  }

  concurrentSearches();
  ```
</CodeGroup>

### Batch Processing with Rate Limiting

Process large numbers of requests while respecting rate limits:

<CodeGroup>
  ```python Python theme={null}
  import asyncio
  from perplexity import AsyncPerplexity, DefaultAioHttpClient

  async def batch_process_with_limit(queries, batch_size=5, delay=1.0):
      async with AsyncPerplexity(
          http_client=DefaultAioHttpClient()
      ) as client:
          results = []
          
          for i in range(0, len(queries), batch_size):
              batch = queries[i:i + batch_size]
              
              # Process batch concurrently
              tasks = [
                  client.search.create(query=query)
                  for query in batch
              ]
              
              batch_results = await asyncio.gather(*tasks, return_exceptions=True)
              results.extend(batch_results)
              
              # Delay between batches to respect rate limits
              if i + batch_size < len(queries):
                  await asyncio.sleep(delay)
          
          return results

  # Usage
  queries = [f"query {i}" for i in range(20)]
  results = asyncio.run(batch_process_with_limit(queries))
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  async function batchProcessWithLimit(
      queries: string[], 
      batchSize: number = 5, 
      delay: number = 1000
  ) {
      const client = new Perplexity();
      const results = [];
      
      for (let i = 0; i < queries.length; i += batchSize) {
          const batch = queries.slice(i, i + batchSize);
          
          // Process batch concurrently
          const tasks = batch.map(query => 
              client.search.create({ query }).catch(error => error)
          );
          
          const batchResults = await Promise.all(tasks);
          results.push(...batchResults);
          
          // Delay between batches to respect rate limits
          if (i + batchSize < queries.length) {
              await new Promise(resolve => setTimeout(resolve, delay));
          }
      }
      
      return results;
  }

  // Usage
  const queries = Array.from({ length: 20 }, (_, i) => `query ${i}`);
  const results = await batchProcessWithLimit(queries);
  ```
</CodeGroup>

## Raw Response Access

Access headers, status codes, and raw response data for advanced use cases:

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity

  client = Perplexity()

  # Get raw response with headers
  response = client.search.with_raw_response.create(
      query="machine learning"
  )

  print(f"Status Code: {response.status_code}")
  print(f"Request ID: {response.headers.get('X-Request-ID')}")
  print(f"Rate Limit Remaining: {response.headers.get('X-RateLimit-Remaining')}")
  print(f"Rate Limit Reset: {response.headers.get('X-RateLimit-Reset')}")

  # Parse the actual search results
  search = response.parse()
  print(f"Found {len(search.results)} results")
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  // Get raw response with headers
  const { data: search, response: rawResponse } = await client.search
      .create({ query: "machine learning" })
      .withResponse();

  console.log(`Status Code: ${rawResponse.status}`);
  console.log(`Request ID: ${rawResponse.headers.get('X-Request-ID')}`);
  console.log(`Rate Limit Remaining: ${rawResponse.headers.get('X-RateLimit-Remaining')}`);
  console.log(`Rate Limit Reset: ${rawResponse.headers.get('X-RateLimit-Reset')}`);
  console.log(`Found ${search.results.length} results`);
  ```
</CodeGroup>

### Response Streaming

For chat completions, use streaming to get partial results as they arrive:

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity

  client = Perplexity()

  # Stream chat completion responses
  stream = client.chat.completions.create(
      model="sonar",
      messages=[{"role": "user", "content": "Explain quantum computing"}],
      stream=True
  )

  for chunk in stream:
      if chunk.choices[0].delta.content:
          print(chunk.choices[0].delta.content, end="", flush=True)
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  // Stream chat completion responses
  const stream = await client.chat.completions.create({
      model: "sonar-pro",
      messages: [{ role: "user", content: "Explain quantum computing" }],
      stream: true as const
  });

  for await (const chunk of stream) {
      if (chunk.choices[0]?.delta?.content) {
          process.stdout.write((chunk.choices[0]?.delta?.content ?? '') as string);
      }
  }
  ```
</CodeGroup>

## Connection Pooling

### Optimized Connection Settings

Configure connection pooling for better performance:

<CodeGroup>
  ```python Python theme={null}
  import httpx
  from perplexity import Perplexity, DefaultHttpxClient, AsyncPerplexity, DefaultAioHttpClient

  # Sync client with optimized connection pooling
  limits = httpx.Limits(
      max_keepalive_connections=50,  # Keep connections alive
      max_connections=100,           # Total connection pool size
      keepalive_expiry=30.0         # Keep-alive timeout
  )

  sync_client = Perplexity(
      http_client=DefaultHttpxClient(limits=limits)
  )

  # Async client with optimized connection pooling
  async_limits = httpx.Limits(
      max_keepalive_connections=100,
      max_connections=200,
      keepalive_expiry=60.0
  )

  async def create_async_client():
      return AsyncPerplexity(
          http_client=DefaultAioHttpClient(limits=async_limits)
      )
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';
  import https from 'https';

  // Optimized HTTPS agent for connection pooling
  const optimizedAgent = new https.Agent({
      keepAlive: true,
      keepAliveMsecs: 30000,  // 30 seconds
      maxSockets: 50,         // Max connections per host
      maxFreeSockets: 10,     // Max idle connections per host
      timeout: 60000          // Socket timeout
  });

  const client = new Perplexity({
      httpAgent: optimizedAgent
  } as any);

  // For high-throughput applications
  const highThroughputAgent = new https.Agent({
      keepAlive: true,
      keepAliveMsecs: 60000,
      maxSockets: 200,
      maxFreeSockets: 50,
      timeout: 120000
  });

  const clientHighThroughput = new Perplexity({
      httpAgent: highThroughputAgent
  } as any);
  ```
</CodeGroup>

## Performance Monitoring

### Request Timing and Metrics

Monitor performance metrics to identify bottlenecks:

<CodeGroup>
  ```python Python theme={null}
  import time
  import asyncio
  from perplexity import AsyncPerplexity, DefaultAioHttpClient

  class PerformanceMonitor:
      def __init__(self):
          self.request_times = []
          self.error_count = 0
          
      async def timed_request(self, client, query):
          start_time = time.time()
          try:
              result = await client.search.create(query=query)
              duration = time.time() - start_time
              self.request_times.append(duration)
              return result
          except Exception as e:
              self.error_count += 1
              raise e
      
      def get_stats(self):
          if not self.request_times:
              return {"error": "No successful requests"}
          
          return {
              "total_requests": len(self.request_times),
              "error_count": self.error_count,
              "avg_response_time": sum(self.request_times) / len(self.request_times),
              "min_response_time": min(self.request_times),
              "max_response_time": max(self.request_times)
          }

  async def run_performance_test():
      monitor = PerformanceMonitor()
      
      async with AsyncPerplexity(
          http_client=DefaultAioHttpClient()
      ) as client:
          queries = [f"test query {i}" for i in range(10)]
          
          tasks = [
              monitor.timed_request(client, query)
              for query in queries
          ]
          
          await asyncio.gather(*tasks, return_exceptions=True)
          
      print(monitor.get_stats())

  asyncio.run(run_performance_test())
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  class PerformanceMonitor {
      private requestTimes: number[] = [];
      private errorCount: number = 0;
      
      async timedRequest(client: Perplexity, query: string) {
          const startTime = performance.now();
          try {
              const result = await client.search.create({ query });
              const duration = performance.now() - startTime;
              this.requestTimes.push(duration);
              return result;
          } catch (error) {
              this.errorCount++;
              throw error;
          }
      }
      
      getStats() {
          if (this.requestTimes.length === 0) {
              return { error: "No successful requests" };
          }
          
          return {
              totalRequests: this.requestTimes.length,
              errorCount: this.errorCount,
              avgResponseTime: this.requestTimes.reduce((a, b) => a + b, 0) / this.requestTimes.length,
              minResponseTime: Math.min(...this.requestTimes),
              maxResponseTime: Math.max(...this.requestTimes)
          };
      }
  }

  async function runPerformanceTest() {
      const monitor = new PerformanceMonitor();
      const client = new Perplexity();
      
      const queries = Array.from({ length: 10 }, (_, i) => `test query ${i}`);
      
      const tasks = queries.map(query => 
          monitor.timedRequest(client, query).catch(error => error)
      );
      
      await Promise.all(tasks);
      
      console.log(monitor.getStats());
  }

  runPerformanceTest();
  ```
</CodeGroup>

## Memory Optimization

### Efficient Data Processing

Process large datasets efficiently with streaming and pagination:

<CodeGroup>
  ```python Python theme={null}
  import asyncio
  from perplexity import AsyncPerplexity, DefaultAioHttpClient

  async def process_large_dataset(queries, process_fn):
      """Process queries in batches to manage memory usage"""
      
      async with AsyncPerplexity(
          http_client=DefaultAioHttpClient()
      ) as client:
          
          async def process_single(query):
              try:
                  result = await client.search.create(query=query)
                  # Process immediately to avoid storing in memory
                  processed = process_fn(result)
                  # Clear the original result from memory
                  del result
                  return processed
              except Exception as e:
                  return f"Error processing {query}: {e}"
          
          # Process in small batches
          batch_size = 5
          for i in range(0, len(queries), batch_size):
              batch = queries[i:i + batch_size]
              
              # Process batch
              tasks = [process_single(query) for query in batch]
              batch_results = await asyncio.gather(*tasks)
              
              # Yield results instead of accumulating
              for result in batch_results:
                  yield result
              
              # Optional: Small delay to prevent overwhelming the API
              await asyncio.sleep(0.1)

  # Usage
  async def summarize_result(search_result):
      """Process function that extracts only what we need"""
      return {
          "query": search_result.query,
          "result_count": len(search_result.results),
          "top_title": search_result.results[0].title if search_result.results else None
      }

  async def main():
      queries = [f"query {i}" for i in range(100)]
      
      async for processed_result in process_large_dataset(queries, summarize_result):
          print(processed_result)

  asyncio.run(main())
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  async function* processLargeDataset<T>(
      queries: string[], 
      processFn: (result: any) => T
  ): AsyncGenerator<T | string> {
      const client = new Perplexity();
      
      async function processSingle(query: string): Promise<T | string> {
          try {
              const result = await client.search.create({ query });
              // Process immediately to avoid storing in memory
              const processed = processFn(result);
              return processed;
          } catch (error) {
              return `Error processing ${query}: ${error}`;
          }
      }
      
      // Process in small batches
      const batchSize = 5;
      for (let i = 0; i < queries.length; i += batchSize) {
          const batch = queries.slice(i, i + batchSize);
          
          // Process batch
          const tasks = batch.map(query => processSingle(query));
          const batchResults = await Promise.all(tasks);
          
          // Yield results instead of accumulating
          for (const result of batchResults) {
              yield result;
          }
          
          // Optional: Small delay to prevent overwhelming the API
          await new Promise(resolve => setTimeout(resolve, 100));
      }
  }

  // Usage
  function summarizeResult(searchResult: any) {
      return {
          query: searchResult.query,
          resultCount: searchResult.results.length,
          topTitle: searchResult.results[0]?.title || null
      };
  }

  async function main() {
      const queries = Array.from({ length: 100 }, (_, i) => `query ${i}`);
      
      for await (const processedResult of processLargeDataset(queries, summarizeResult)) {
          console.log(processedResult);
      }
  }

  main();
  ```
</CodeGroup>

## Best Practices

<Steps>
  <Step title="Use async for concurrent operations">
    Always use async clients when you need to process multiple requests simultaneously.

    <Tip>
      For CPU-bound processing after API calls, consider using worker threads or processes.
    </Tip>
  </Step>

  <Step title="Implement connection pooling">
    Configure appropriate connection limits based on your application's needs.

    <CodeGroup>
      ```python Python theme={null}
      # Good: Optimized for your use case
      limits = httpx.Limits(
          max_keepalive_connections=20,  # Based on expected concurrency
          max_connections=50,
          keepalive_expiry=30.0
      )
      ```

      ```typescript TypeScript theme={null}
      // Good: Optimized for your use case
      const agent = new https.Agent({
          keepAlive: true,
          maxSockets: 20,  // Based on expected concurrency
          keepAliveMsecs: 30000
      });
      ```
    </CodeGroup>
  </Step>

  <Step title="Monitor and tune performance">
    Use metrics to identify bottlenecks and optimize accordingly.

    <Warning>
      Don't optimize prematurely - measure first, then optimize based on actual performance data.
    </Warning>
  </Step>

  <Step title="Handle backpressure">
    Implement proper rate limiting and backpressure handling for high-throughput applications.

    <CodeGroup>
      ```python Python theme={null}
      # Use semaphores to limit concurrent requests
      semaphore = asyncio.Semaphore(10)  # Max 10 concurrent requests

      async def rate_limited_request(client, query):
          async with semaphore:
              return await client.search.create(query=query)
      ```

      ```typescript TypeScript theme={null}
      // Use a queue or throttling library
      import pLimit from 'p-limit';

      const limit = pLimit(10);  // Max 10 concurrent requests

      const rateLimitedRequest = (client: Perplexity, query: string) =>
          limit(() => client.search.create({ query }));
      ```
    </CodeGroup>
  </Step>
</Steps>

## Related Resources

<CardGroup>
  <Card title="Configuration" icon="settings" href="/docs/sdk/configuration">
    Optimize connection pooling and timeouts
  </Card>

  <Card title="Error Handling" icon="alert-triangle" href="/docs/sdk/error-handling">
    Handle errors in async operations
  </Card>
</CardGroup>


# Type Safety
Source: https://docs.perplexity.ai/docs/sdk/type-safety

Learn how to leverage full TypeScript definitions and Python type hints with the Perplexity SDKs for better development experience and code safety.

## Overview

Both Perplexity SDKs provide comprehensive type definitions to help you catch errors at development time and provide better IDE support. This guide covers type annotations, generic types, and advanced typing patterns.

## Basic Type Usage

### Type Imports and Annotations

Use type imports for better IDE support and type checking:

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity
  from perplexity.types import (
      SearchCreateResponse,
      ResponseCreateResponse,
      SearchResult
  )

  client = Perplexity()

  # Type hints for better IDE support
  search_response: SearchCreateResponse = client.search.create(
      query="artificial intelligence"
  )

  # Access typed properties
  result: SearchResult = search_response.results[0]
  print(f"Title: {result.title}")
  print(f"URL: {result.url}")
  print(f"Snippet: {result.snippet}")
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  // TypeScript provides full intellisense and type checking
  const searchResponse: Perplexity.Search.SearchCreateResponse = await client.search.create({
      query: "artificial intelligence"
  });

  // Access typed properties with intellisense
  const result = searchResponse.results[0];
  console.log(`Title: ${result.title}`);
  console.log(`URL: ${result.url}`);
  console.log(`Snippet: ${result.snippet}`);
  ```
</CodeGroup>

### Runtime Type Validation

Python SDK uses Pydantic for runtime type validation:

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity
  from perplexity.types import SearchCreateResponse

  client = Perplexity()

  # Runtime validation ensures type safety
  try:
      search_response = client.search.create(
          query="machine learning",
          max_results=10
      )
      
      # Pydantic model methods for serialization
      json_data = search_response.to_json()
      dict_data = search_response.to_dict()
      
      # Type validation on field access
      first_result = search_response.results[0]
      print(f"Result type: {type(first_result)}")
      
  except ValueError as e:
      print(f"Type validation error: {e}")
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  // TypeScript compile-time type checking
  const searchResponse: Perplexity.Search.SearchCreateResponse = await client.search.create({
      query: "machine learning",
      max_results: 10  // TypeScript ensures correct property names
  });

  // Serialization (already plain objects)
  const jsonData = JSON.stringify(searchResponse);
  const objectData = searchResponse; // Already a plain object

  // Type safety at compile time
  const firstResult = searchResponse.results[0];
  console.log(`Result type available in IDE: ${typeof firstResult}`);
  ```
</CodeGroup>

## Advanced Type Patterns

### Generic Type Helpers

Create reusable typed functions:

<CodeGroup>
  ```python Python theme={null}
  from typing import TypeVar, Generic, List, Optional, Callable
  from perplexity import Perplexity
  from perplexity.types import SearchCreateResponse, ResponseCreateResponse

  T = TypeVar('T')
  R = TypeVar('R')

  class TypedPerplexityClient:
      def __init__(self, client: Perplexity):
          self.client = client
      
      def search_with_transform(
          self, 
          query: str, 
          transform: Callable[[SearchCreateResponse], T]
      ) -> T:
          """Perform search and transform the result with type safety"""
          response = self.client.search.create(query=query)
          return transform(response)
      
      def batch_search(
          self, 
          queries: List[str]
      ) -> List[SearchCreateResponse]:
          """Perform multiple searches with proper typing"""
          results = []
          for query in queries:
              response = self.client.search.create(query=query)
              results.append(response)
          return results

  # Usage with type safety
  client = TypedPerplexityClient(Perplexity())

  def extract_titles(response: SearchCreateResponse) -> List[str]:
      return [result.title for result in response.results]

  # Typed function call
  titles: List[str] = client.search_with_transform("AI research", extract_titles)
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  class TypedPerplexityClient {
      constructor(private client: Perplexity) {}
      
      async searchWithTransform<T>(
          query: string,
          transform: (response: Perplexity.Search.SearchCreateResponse) => T
      ): Promise<T> {
          const response = await this.client.search.create({ query });
          return transform(response);
      }
      
      async batchSearch(queries: string[]): Promise<Perplexity.Search.SearchCreateResponse[]> {
          const tasks = queries.map(query => 
              this.client.search.create({ query })
          );
          return Promise.all(tasks);
      }
  }

  // Usage with type safety
  const client = new TypedPerplexityClient(new Perplexity());

  function extractTitles(response: Perplexity.Search.SearchCreateResponse): string[] {
      return response.results.map(result => result.title);
  }

  // Typed function call with full intellisense
  const titles: string[] = await client.searchWithTransform("AI research", extractTitles);
  ```
</CodeGroup>

### Custom Type Guards

Create type guards for safer type checking:

<CodeGroup>
  ```python Python theme={null}
  from typing import Union, TypeGuard
  from perplexity.types import (
      SearchCreateResponse,
      ResponseCreateResponse,
      SearchResult
  )

  def is_search_response(
      response: Union[SearchCreateResponse, ResponseCreateResponse]
  ) -> TypeGuard[SearchCreateResponse]:
      """Type guard to check if response is a search response"""
      return hasattr(response, 'results')

  def is_valid_search_result(result: SearchResult) -> TypeGuard[SearchResult]:
      """Type guard to validate search result structure"""
      return (
          hasattr(result, 'title') and 
          hasattr(result, 'url') and 
          hasattr(result, 'snippet') and
          result.title is not None and
          result.url is not None
      )

  # Usage
  def process_response(
      response: Union[SearchCreateResponse, ResponseCreateResponse]
  ) -> None:
      if is_search_response(response):
          # Python type checker now knows this is SearchCreateResponse
          for result in response.results:
              if is_valid_search_result(result):
                  print(f"Valid result: {result.title}")
              else:
                  print("Invalid result format")
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  function isSearchResponse(
      response: Perplexity.Search.SearchCreateResponse | Perplexity.StreamChunk
  ): response is Perplexity.Search.SearchCreateResponse {
      return 'results' in response;
  }

  function isValidSearchResult(result: { title: string; url: string; snippet: string }): boolean {
      return (
          typeof result.title === 'string' &&
          typeof result.url === 'string' &&
          typeof result.snippet === 'string' &&
          result.title.length > 0 &&
          result.url.length > 0
      );
  }

  // Usage
  function processResponse(
      response: Perplexity.Search.SearchCreateResponse | Perplexity.StreamChunk
  ): void {
      if (isSearchResponse(response)) {
          // TypeScript now knows this is SearchCreateResponse
          response.results.forEach(result => {
              if (isValidSearchResult(result)) {
                  console.log(`Valid result: ${result.title}`);
              } else {
                  console.log("Invalid result format");
              }
          });
      }
  }
  ```
</CodeGroup>

## Response Type Utilities

### Extracting Nested Types

Work with nested response structures safely:

<CodeGroup>
  ```python Python theme={null}
  from typing import List, Optional
  from perplexity import Perplexity
  from perplexity.types import (
      SearchCreateResponse,
      SearchResult,
      ResponseCreateResponse
  )

  class ResponseUtils:
      @staticmethod
      def extract_search_titles(response: SearchCreateResponse) -> List[str]:
          """Extract all search result titles with type safety"""
          return [result.title for result in response.results if result.title]
      
      @staticmethod
      def extract_search_urls(response: SearchCreateResponse) -> List[str]:
          """Extract all search result URLs with type safety"""
          return [result.url for result in response.results if result.url]
      
      @staticmethod
      def get_first_search_result(
          response: SearchCreateResponse
      ) -> Optional[SearchResult]:
          """Get first search result safely"""
          return response.results[0] if response.results else None
      
      @staticmethod
      def extract_response_output(
          response: ResponseCreateResponse
      ) -> Optional[str]:
          """Extract response output safely"""
          if response.output:
              return response.output
          return None

  # Usage
  client = Perplexity()
  search_response = client.search.create(query="Python programming")

  titles = ResponseUtils.extract_search_titles(search_response)
  urls = ResponseUtils.extract_search_urls(search_response)
  first_result = ResponseUtils.get_first_search_result(search_response)

  print(f"Found {len(titles)} results")
  if first_result:
      print(f"First result: {first_result.title}")
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  class ResponseUtils {
      static extractSearchTitles(response: Perplexity.Search.SearchCreateResponse): string[] {
          return response.results
              .filter(result => result.title)
              .map(result => result.title);
      }
      
      static extractSearchUrls(response: Perplexity.Search.SearchCreateResponse): string[] {
          return response.results
              .filter(result => result.url)
              .map(result => result.url);
      }
      
      static getFirstSearchResult(
          response: Perplexity.Search.SearchCreateResponse
      ) {
          return response.results[0];
      }
      
      static extractChatContent(
          response: Perplexity.StreamChunk
      ): string | undefined {
          const content = response.choices[0]?.message?.content;
          // Handle content which can be string, array of chunks, or null
          if (typeof content === 'string') {
              return content;
          }
          if (Array.isArray(content)) {
              // Extract text from content chunks
              return content
                  .filter(chunk => chunk.type === 'text' && 'text' in chunk)
                  .map(chunk => (chunk as { text: string }).text)
                  .join('');
          }
          return undefined;
      }
  }

  // Usage
  const client = new Perplexity();
  const searchResponse: Perplexity.Search.SearchCreateResponse = await client.search.create({ 
      query: "Python programming" 
  });

  const titles = ResponseUtils.extractSearchTitles(searchResponse);
  const urls = ResponseUtils.extractSearchUrls(searchResponse);
  const firstResult = ResponseUtils.getFirstSearchResult(searchResponse);

  console.log(`Found ${titles.length} results`);
  if (firstResult) {
      console.log(`First result: ${firstResult.title}`);
  }
  ```
</CodeGroup>

### Custom Response Mappers

Create typed mappers for domain-specific data structures:

<CodeGroup>
  ```python Python theme={null}
  from typing import List, Optional, Dict, Any
  from dataclasses import dataclass
  from perplexity.types import SearchCreateResponse, SearchResult

  @dataclass
  class SimplifiedSearchResult:
      title: str
      url: str
      snippet: str
      domain: str

  @dataclass
  class SearchSummary:
      query: str
      total_results: int
      results: List[SimplifiedSearchResult]
      domains: List[str]

  class SearchResponseMapper:
      @staticmethod
      def to_simplified(response: SearchCreateResponse) -> SearchSummary:
          """Convert API response to simplified domain model"""
          simplified_results = []
          domains = set()
          
          for result in response.results:
              if result.title and result.url and result.snippet:
                  # Extract domain from URL
                  try:
                      from urllib.parse import urlparse
                      domain = urlparse(result.url).netloc
                      domains.add(domain)
                      
                      simplified_results.append(SimplifiedSearchResult(
                          title=result.title,
                          url=result.url,
                          snippet=result.snippet,
                          domain=domain
                      ))
                  except Exception:
                      # Skip invalid URLs
                      continue
          
          return SearchSummary(
              query=response.query,
              total_results=len(simplified_results),
              results=simplified_results,
              domains=list(domains)
          )

  # Usage with type safety
  client = Perplexity()
  api_response = client.search.create(query="machine learning frameworks")
  summary: SearchSummary = SearchResponseMapper.to_simplified(api_response)

  print(f"Query: {summary.query}")
  print(f"Results: {summary.total_results}")
  print(f"Unique domains: {len(summary.domains)}")
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  interface SimplifiedSearchResult {
      title: string;
      url: string;
      snippet: string;
      domain: string;
  }

  interface SearchSummary {
      query: string;
      totalResults: number;
      results: SimplifiedSearchResult[];
      domains: string[];
  }

  class SearchResponseMapper {
      static toSimplified(response: Perplexity.Search.SearchCreateResponse): SearchSummary {
          const simplifiedResults: SimplifiedSearchResult[] = [];
          const domains = new Set<string>();
          
          for (const result of response.results) {
              if (result.title && result.url && result.snippet) {
                  try {
                      const domain = new URL(result.url).hostname;
                      domains.add(domain);
                      
                      simplifiedResults.push({
                          title: result.title,
                          url: result.url,
                          snippet: result.snippet,
                          domain
                      });
                  } catch {
                      // Skip invalid URLs
                      continue;
                  }
              }
          }
          
          return {
              query: '',
              totalResults: simplifiedResults.length,
              results: simplifiedResults,
              domains: Array.from(domains)
          };
      }
  }

  // Usage with type safety
  const client = new Perplexity();
  const apiResponse: Perplexity.Search.SearchCreateResponse = await client.search.create({ 
      query: "machine learning frameworks" 
  });
  const summary: SearchSummary = SearchResponseMapper.toSimplified(apiResponse);

  console.log(`Query: ${summary.query}`);
  console.log(`Results: ${summary.totalResults}`);
  console.log(`Unique domains: ${summary.domains.length}`);
  ```
</CodeGroup>

## IDE Integration

### Enhanced Development Experience

Maximize IDE support with proper type usage:

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity
  from perplexity.types import SearchCreateResponse
  from typing import TYPE_CHECKING

  if TYPE_CHECKING:
      # Import types only for type checking (no runtime cost)
      from perplexity.types import ResponseCreateResponse as ChatResponse

  class EnhancedClient:
      def __init__(self):
          self.client = Perplexity()
      
      def search(self, query: str, **kwargs) -> SearchCreateResponse:
          """
          Perform search with full type hints
          
          Args:
              query: Search query string
              **kwargs: Additional search parameters
              
          Returns:
              SearchCreateResponse: Typed search results
          """
          return self.client.search.create(query=query, **kwargs)
      
      def chat(self, message: str, model: str = "sonar") -> "ChatResponse":
          """
          Chat completion with type hints

          Args:
              message: User message
              model: Model to use for completion

          Returns:
              ChatResponse: Typed chat response
          """
          return self.client.chat.completions.create(
              model=model,
              messages=[{"role": "user", "content": message}]
          )

  # Usage with full IDE support
  enhanced_client = EnhancedClient()

  # IDE provides full autocomplete and type checking
  search_result = enhanced_client.search("Python tutorials")
  print(search_result.results[0].title)  # Full intellisense available

  chat_result = enhanced_client.chat("Explain decorators")
  # Access content safely with type checking
  if hasattr(chat_result, 'output') and chat_result.output:
      print(chat_result.output)  # Type-safe access
  ```

  ```typescript TypeScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  class EnhancedClient {
      private client: Perplexity;
      
      constructor() {
          this.client = new Perplexity();
      }
      
      /**
       * Perform search with full type hints
       */
      async search(
          query: string, 
          options?: Partial<Perplexity.Search.SearchCreateParams>
      ): Promise<Perplexity.Search.SearchCreateResponse> {
          return this.client.search.create({ 
              query, 
              ...options 
          });
      }
      
      /**
       * Chat completion with type hints
       */
      async chat(
          message: string, 
          model: string = "sonar"
      ): Promise<Perplexity.StreamChunk> {
          return this.client.chat.completions.create({
              model,
              messages: [{ role: "user", content: message }]
          });
      }
  }

  // Usage with full IDE support
  const enhancedClient = new EnhancedClient();

  // IDE provides full autocomplete and type checking
  const searchResult = await enhancedClient.search("Python tutorials");
  console.log(searchResult.results[0].title); // Full intellisense available

  const chatResult = await enhancedClient.chat("Explain decorators");
  // Content can be string, array of chunks, or null - handle appropriately
  const content = chatResult.choices[0]?.message?.content;
  if (typeof content === 'string') {
      console.log(content); // Type-safe access
  }
  ```
</CodeGroup>

## Type Safety Best Practices

<Steps>
  <Step title="Always use type imports">
    Import and use specific types for better IDE support and error catching.

    <CodeGroup>
      ```python Python theme={null}
      # Good: Specific type imports
      from perplexity.types import SearchCreateResponse, SearchResult

      def process_search(response: SearchCreateResponse) -> List[str]:
          return [result.title for result in response.results]
      ```

      ```typescript TypeScript theme={null}
      // Good: Use namespace types for type safety
      import Perplexity from '@perplexity-ai/perplexity_ai';

      function processSearch(response: Perplexity.Search.SearchCreateResponse): string[] {
          return response.results.map(result => result.title);
      }
      ```
    </CodeGroup>
  </Step>

  <Step title="Use type guards for runtime safety">
    Implement proper type checking for dynamic data.

    <Warning>
      TypeScript types are compile-time only. Use type guards for runtime validation.
    </Warning>
  </Step>

  <Step title="Leverage generic types">
    Create reusable typed functions and classes for common patterns.

    <Tip>
      Generic types help maintain type safety while providing flexibility.
    </Tip>
  </Step>

  <Step title="Document with types">
    Use type annotations as documentation for better code maintainability.

    <CodeGroup>
      ```python Python theme={null}
      def analyze_search_results(
          response: SearchCreateResponse,
          min_score: float = 0.5
      ) -> Dict[str, Any]:
          """
          Analyze search results with scoring
          
          Args:
              response: Search API response
              min_score: Minimum quality score threshold
              
          Returns:
              Analysis results with scores and recommendations
          """
          # Implementation with type safety
      ```

      ```typescript TypeScript theme={null}
      /**
       * Analyze search results with scoring
       */
      function analyzeSearchResults(
          response: Perplexity.Search.SearchCreateResponse,
          minScore: number = 0.5
      ): { scores: number[]; recommendations: string[] } {
          // Implementation with type safety
      }
      ```
    </CodeGroup>
  </Step>
</Steps>

## Related Resources

<CardGroup>
  <Card title="Error Handling" icon="alert-triangle" href="/docs/sdk/error-handling">
    Type-safe error handling patterns
  </Card>

  <Card title="Best Practices" icon="star" href="/docs/sdk/best-practices">
    Type safety in production code
  </Card>
</CardGroup>


# Best Practices
Source: https://docs.perplexity.ai/docs/search/best-practices

Learn best practices for optimizing search queries and implementing efficient async patterns with Perplexity's Search API.

***

## Overview

This guide covers essential best practices for getting the most out of Perplexity's Search API, including query optimization techniques and efficient async usage patterns for high-performance applications.

## Query Optimization

<Steps>
  <Step title="Write specific queries">
    Use highly specific queries for more targeted results. For example, instead of searching for "AI", use a detailed query like "artificial intelligence machine learning healthcare applications 2024".

    <CodeGroup>
      ```python Python theme={null}
      # Better: Specific query
      search = client.search.create(
          query="artificial intelligence medical diagnosis accuracy 2024",
          max_results=10
      )

      # Avoid: Vague query
      search = client.search.create(
          query="AI medical",
          max_results=10
      )
      ```

      ```typescript Typescript theme={null}
      // Better: Specific query
      const search = await client.search.create({
          query: "artificial intelligence medical diagnosis accuracy 2024",
          max_results: 10
      });

      // Avoid: Vague query
      const search = await client.search.create({
          query: "AI medical",
          max_results: 10
      });
      ```
    </CodeGroup>

    <Tip>
      Specific queries with context, time frames, and precise terminology yield more relevant and actionable results.
    </Tip>
  </Step>

  <Step title="Use multi-query for comprehensive research">
    Break your main topic into related sub-queries to cover all aspects of your research. Use the multi-query search feature to run multiple related queries in a single request for more comprehensive and relevant information.

    <CodeGroup>
      ```python Python theme={null}
      from perplexity import Perplexity

      client = Perplexity()

      # Comprehensive research with related queries
      search = client.search.create(
          query=[
              "artificial intelligence medical diagnosis accuracy 2024",
              "machine learning healthcare applications FDA approval",
              "AI medical imaging radiology deployment hospitals"
          ],
          max_results=5
      )

      # Access results
      for result in search.results:
          print(f"  {result.title}: {result.url}")
      ```

      ```typescript Typescript theme={null}
      import Perplexity from '@perplexity-ai/perplexity_ai';

      const client = new Perplexity();

      // Comprehensive research with related queries
      const search = await client.search.create({
          query: [
              "artificial intelligence medical diagnosis accuracy 2024",
              "machine learning healthcare applications FDA approval",
              "AI medical imaging radiology deployment hospitals"
          ],
          max_results: 5
      });

      // Access results
      search.results.forEach(result => {
          console.log(`  ${result.title}: ${result.url}`);
      });
      ```
    </CodeGroup>

    <Info>
      You can include up to 5 queries in a single multi-query request for efficient batch processing.
    </Info>
  </Step>

  <Step title="Handle rate limits efficiently">
    Implement exponential backoff for rate limit errors and use appropriate batching strategies.

    <CodeGroup>
      ```python Python theme={null}
      import time
      import random
      from perplexity import Perplexity, RateLimitError

      def search_with_retry(client, query, max_retries=3):
          for attempt in range(max_retries):
              try:
                  return client.search.create(query=query)
              except RateLimitError:
                  if attempt < max_retries - 1:
                      # Exponential backoff with jitter
                      delay = (2 ** attempt) + random.uniform(0, 1)
                      time.sleep(delay)
                  else:
                      raise

      client = Perplexity()

      # Usage
      try:
          search = search_with_retry(client, "AI developments")
          for result in search.results:
              print(f"{result.title}: {result.url}")
      except RateLimitError:
          print("Maximum retries exceeded for search")
      ```

      ```typescript Typescript theme={null}
      import Perplexity from '@perplexity-ai/perplexity_ai';

      async function searchWithRetry(
          client: Perplexity, 
          query: string, 
          maxRetries: number = 3
      ) {
          for (let attempt = 0; attempt < maxRetries; attempt++) {
              try {
                  return await client.search.create({ query });
              } catch (error) {
                  if (error instanceof Perplexity.RateLimitError && attempt < maxRetries - 1) {
                      // Exponential backoff with jitter
                      const delay = (2 ** attempt) + Math.random();
                      await new Promise(resolve => setTimeout(resolve, delay * 1000));
                  } else {
                      throw error;
                  }
              }
          }
          throw new Error("Max retries exceeded");
      }

      const client = new Perplexity();

      // Usage
      try {
          const search = await searchWithRetry(client, "AI developments");
          search.results.forEach(result => {
              console.log(`${result.title}: ${result.url}`);
          });
      } catch (error) {
          console.log("Maximum retries exceeded for search");
      }
      ```
    </CodeGroup>
  </Step>

  <Step title="Process concurrent searches efficiently">
    Use async for concurrent requests while respecting rate limits.

    <CodeGroup>
      ```python Python theme={null}
      import asyncio
      from perplexity import AsyncPerplexity

      async def batch_search(queries, batch_size=3, delay_ms=1000):
          async with AsyncPerplexity() as client:
              results = []
              
              for i in range(0, len(queries), batch_size):
                  batch = queries[i:i + batch_size]
                  
                  batch_tasks = [
                      client.search.create(query=query, max_results=5)
                      for query in batch
                  ]
                  
                  batch_results = await asyncio.gather(*batch_tasks)
                  results.extend(batch_results)
                  
                  # Add delay between batches
                  if i + batch_size < len(queries):
                      await asyncio.sleep(delay_ms / 1000)
              
              return results

      # Usage
      queries = ["AI developments", "climate change", "space exploration"]
      results = asyncio.run(batch_search(queries))
      print(f"Processed {len(results)} searches")
      ```

      ```typescript Typescript theme={null}
      import Perplexity from '@perplexity-ai/perplexity_ai';

      async function batchSearch(
          queries: string[],
          batchSize: number = 3,
          delayMs: number = 1000
      ) {
          const client = new Perplexity();
          const results = [];
          
          for (let i = 0; i < queries.length; i += batchSize) {
              const batch = queries.slice(i, i + batchSize);
              
              const batchPromises = batch.map(query =>
                  client.search.create({
                      query,
                      max_results: 5
                  })
              );
              
              const batchResults = await Promise.all(batchPromises);
              results.push(...batchResults);
              
              // Add delay between batches
              if (i + batchSize < queries.length) {
                  await new Promise(resolve => setTimeout(resolve, delayMs));
              }
          }
          
          return results;
      }

      // Usage
      const queries = ["AI developments", "climate change", "space exploration"];
      const results = await batchSearch(queries);
      console.log(`Processed ${results.length} searches`);
      ```
    </CodeGroup>
  </Step>
</Steps>

## Async Usage

For high-performance applications requiring concurrent requests, use the async client:

<CodeGroup>
  ```python Python theme={null}
  import asyncio
  from perplexity import AsyncPerplexity

  async def main():
      async with AsyncPerplexity() as client:
          # Concurrent searches for better performance
          tasks = [
              client.search.create(
                  query="artificial intelligence trends 2024",
                  max_results=5
              ),
              client.search.create(
                  query="machine learning breakthroughs",
                  max_results=5
              ),
              client.search.create(
                  query="deep learning applications",
                  max_results=5
              )
          ]
          
          results = await asyncio.gather(*tasks)
          
          for i, search in enumerate(results):
              print(f"Query {i+1} results:")
              for result in search.results:
                  print(f"  {result.title}: {result.url}")
              print("---")

  asyncio.run(main())
  ```

  ```typescript Typescript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  async function main() {
      // Concurrent searches for better performance
      const tasks = [
          client.search.create({
              query: "artificial intelligence trends 2024",
              max_results: 5
          }),
          client.search.create({
              query: "machine learning breakthroughs",
              max_results: 5
          }),
          client.search.create({
              query: "deep learning applications",
              max_results: 5
          })
      ];
      
      const results = await Promise.all(tasks);
      
      results.forEach((search, i) => {
          console.log(`Query ${i+1} results:`);
          search.results.forEach(result => {
              console.log(`  ${result.title}: ${result.url}`);
          });
          console.log("---");
      });
  }

  main();
  ```

  ```javascript JavaScript theme={null}
  const Perplexity = require('@perplexity-ai/perplexity_ai');

  const client = new Perplexity();

  async function main() {
      // Concurrent searches for better performance
      const tasks = [
          client.search.create({
              query: "artificial intelligence trends 2024",
              max_results: 5
          }),
          client.search.create({
              query: "machine learning breakthroughs",
              max_results: 5
          }),
          client.search.create({
              query: "deep learning applications",
              max_results: 5
          })
      ];
      
      const results = await Promise.all(tasks);
      
      results.forEach((search, i) => {
          console.log(`Query ${i+1} results:`);
          search.results.forEach(result => {
              console.log(`  ${result.title}: ${result.url}`);
          });
          console.log("---");
      });
  }

  main();
  ```
</CodeGroup>

### Advanced Async Patterns

#### Rate-Limited Concurrent Processing

For large-scale applications, implement controlled concurrency with rate limiting:

<CodeGroup>
  ```python Python theme={null}
  import asyncio
  from perplexity import AsyncPerplexity

  class SearchManager:
      def __init__(self, max_concurrent=5, delay_between_batches=1.0):
          self.max_concurrent = max_concurrent
          self.delay_between_batches = delay_between_batches
          self.semaphore = asyncio.Semaphore(max_concurrent)
      
      async def search_single(self, client, query):
          async with self.semaphore:
              return await client.search.create(query=query, max_results=5)
      
      async def search_many(self, queries):
          async with AsyncPerplexity() as client:
              tasks = [
                  self.search_single(client, query) 
                  for query in queries
              ]
              
              results = await asyncio.gather(*tasks, return_exceptions=True)
              
              # Filter out exceptions and return successful results
              successful_results = [
                  result for result in results 
                  if not isinstance(result, Exception)
              ]
              
              return successful_results

  # Usage
  async def main():
      manager = SearchManager(max_concurrent=3)
      queries = [
          "AI research 2024",
          "quantum computing advances",
          "renewable energy innovations",
          "biotechnology breakthroughs",
          "space exploration updates"
      ]
      
      results = await manager.search_many(queries)
      print(f"Successfully processed {len(results)} out of {len(queries)} searches")

  asyncio.run(main())
  ```

  ```typescript Typescript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  class SearchManager {
      private maxConcurrent: number;
      private delayBetweenBatches: number;
      
      constructor(maxConcurrent: number = 5, delayBetweenBatches: number = 1000) {
          this.maxConcurrent = maxConcurrent;
          this.delayBetweenBatches = delayBetweenBatches;
      }
      
      async searchMany(queries: string[]) {
          const client = new Perplexity();
          const results = [];
          
          // Process in batches to respect rate limits
          for (let i = 0; i < queries.length; i += this.maxConcurrent) {
              const batch = queries.slice(i, i + this.maxConcurrent);
              
              const batchPromises = batch.map(query =>
                  client.search.create({ query, max_results: 5 })
                      .catch(error => ({ error, query }))
              );
              
              const batchResults = await Promise.all(batchPromises);
              
              // Filter out errors and collect successful results
              const successfulResults = batchResults.filter(
                  result => !('error' in result)
              );
              
              results.push(...successfulResults);
              
              // Add delay between batches
              if (i + this.maxConcurrent < queries.length) {
                  await new Promise(resolve => 
                      setTimeout(resolve, this.delayBetweenBatches)
                  );
              }
          }
          
          return results;
      }
  }

  // Usage
  async function main() {
      const manager = new SearchManager(3, 1000);
      const queries = [
          "AI research 2024",
          "quantum computing advances", 
          "renewable energy innovations",
          "biotechnology breakthroughs",
          "space exploration updates"
      ];
      
      const results = await manager.searchMany(queries);
      console.log(`Successfully processed ${results.length} out of ${queries.length} searches`);
  }

  main();
  ```
</CodeGroup>

#### Error Handling in Async Operations

Implement robust error handling for async search operations:

<CodeGroup>
  ```python Python theme={null}
  import asyncio
  import logging
  from perplexity import AsyncPerplexity, APIStatusError, RateLimitError

  logging.basicConfig(level=logging.INFO)
  logger = logging.getLogger(__name__)

  async def resilient_search(client, query, max_retries=3):
      for attempt in range(max_retries):
          try:
              result = await client.search.create(query=query, max_results=5)
              logger.info(f"Search successful for: {query}")
              return result
              
          except RateLimitError as e:
              if attempt < max_retries - 1:
                  delay = 2 ** attempt
                  logger.warning(f"Rate limited for '{query}', retrying in {delay}s")
                  await asyncio.sleep(delay)
              else:
                  logger.error(f"Max retries exceeded for: {query}")
                  return None
                  
          except APIStatusError as e:
              logger.error(f"API error for '{query}': {e}")
              return None
              
          except Exception as e:
              logger.error(f"Unexpected error for '{query}': {e}")
              return None

  async def main():
      async with AsyncPerplexity() as client:
          queries = ["AI developments", "invalid query", "tech trends"]
          
          tasks = [resilient_search(client, query) for query in queries]
          results = await asyncio.gather(*tasks)
          
          successful_results = [r for r in results if r is not None]
          print(f"Successful searches: {len(successful_results)}/{len(queries)}")

  asyncio.run(main())
  ```

  ```typescript Typescript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  async function resilientSearch(
      client: Perplexity, 
      query: string, 
      maxRetries: number = 3
  ) {
      for (let attempt = 0; attempt < maxRetries; attempt++) {
          try {
              const result = await client.search.create({ query, max_results: 5 });
              console.log(`Search successful for: ${query}`);
              return result;
              
          } catch (error: any) {
              if (error.constructor.name === 'RateLimitError') {
                  if (attempt < maxRetries - 1) {
                      const delay = 2 ** attempt * 1000;
                      console.warn(`Rate limited for '${query}', retrying in ${delay}ms`);
                      await new Promise(resolve => setTimeout(resolve, delay));
                  } else {
                      console.error(`Max retries exceeded for: ${query}`);
                      return null;
                  }
              } else {
                  console.error(`Error for '${query}':`, error.message);
                  return null;
              }
          }
      }
      
      return null;
  }

  async function main() {
      const client = new Perplexity();
      const queries = ["AI developments", "invalid query", "tech trends"];
      
      const tasks = queries.map(query => resilientSearch(client, query));
      const results = await Promise.all(tasks);
      
      const successfulResults = results.filter(r => r !== null);
      console.log(`Successful searches: ${successfulResults.length}/${queries.length}`);
  }

  main();
  ```
</CodeGroup>

## Performance Optimization Tips

<Steps>
  <Step title="Optimize result count">
    Request only the number of results you actually need. More results = longer response times.

    ```python theme={null}
    # Good: Request only what you need
    search = client.search.create(query="tech news", max_results=5)

    # Avoid: Over-requesting results
    search = client.search.create(query="tech news", max_results=50)
    ```
  </Step>

  <Step title="Cache frequently used searches">
    Implement caching for queries that don't need real-time results.

    <CodeGroup>
      ```python Python theme={null}
      import time
      from typing import Dict, Tuple, Optional

      class SearchCache:
          def __init__(self, ttl_seconds=3600):  # 1 hour default
              self.cache: Dict[str, Tuple[any, float]] = {}
              self.ttl = ttl_seconds
          
          def get(self, query: str) -> Optional[any]:
              if query in self.cache:
                  result, timestamp = self.cache[query]
                  if time.time() - timestamp < self.ttl:
                      return result
                  else:
                      del self.cache[query]
              return None
          
          def set(self, query: str, result: any):
              self.cache[query] = (result, time.time())

      # Usage
      cache = SearchCache(ttl_seconds=1800)  # 30 minutes

      def cached_search(client, query):
          cached_result = cache.get(query)
          if cached_result:
              return cached_result
          
          result = client.search.create(query=query)
          cache.set(query, result)
          return result
      ```

      ```typescript Typescript theme={null}
      class SearchCache {
          private cache: Map<string, { result: any; timestamp: number }> = new Map();
          private ttl: number;
          
          constructor(ttlSeconds: number = 3600) {  // 1 hour default
              this.ttl = ttlSeconds * 1000;  // Convert to milliseconds
          }
          
          get(query: string): any | null {
              const cached = this.cache.get(query);
              if (cached) {
                  if (Date.now() - cached.timestamp < this.ttl) {
                      return cached.result;
                  } else {
                      this.cache.delete(query);
                  }
              }
              return null;
          }
          
          set(query: string, result: any): void {
              this.cache.set(query, { result, timestamp: Date.now() });
          }
      }

      // Usage
      const cache = new SearchCache(1800);  // 30 minutes

      async function cachedSearch(client: Perplexity, query: string) {
          const cachedResult = cache.get(query);
          if (cachedResult) {
              return cachedResult;
          }
          
          const result = await client.search.create({ query });
          cache.set(query, result);
          return result;
      }
      ```
    </CodeGroup>
  </Step>
</Steps>

## Related Resources

<CardGroup>
  <Card title="Quickstart" icon="rocket" href="/docs/search/quickstart">
    Get started with basic search functionality
  </Card>

  <Card title="Perplexity SDK" icon="code-circle" href="/docs/sdk/overview">
    Explore the full SDK capabilities for enhanced performance
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/search-post">
    Complete Search API documentation
  </Card>
</CardGroup>


# Search Date and Time Filters
Source: https://docs.perplexity.ai/docs/search/filters/date-time-filters



<Note>
  The `search_after_date_filter` and `search_before_date_filter` parameters allow you to restrict search results to a specific publication date range. Only results with publication dates falling between these dates will be returned.

  The `last_updated_after_filter` and `last_updated_before_filter` parameters allow you to filter by when content was last modified or updated, rather than when it was originally published.

  The `search_recency_filter` parameter provides a convenient way to filter results by predefined time periods (e.g., "hour", "day", "week", "month", "year") relative to the current date.
</Note>

<Info>
  Specific date filters must be provided in the "%m/%d/%Y" format (e.g., "3/1/2025"). Recency filters use predefined values like "hour", "day", "week", "month", or "year". All filters are optional—you may supply either specific dates or recency filters as needed.
</Info>

## Overview

Date and time filters for the Search API allow you to control which search results are returned by limiting them to specific time periods. There are three types of date and time filters available:

### Publication Date Filters

The `search_after_date_filter` and `search_before_date_filter` parameters filter results based on when content was **originally created or published**. This is useful when you need to:

* Find content published within a specific timeframe
* Exclude outdated or overly recent publications
* Focus on content from a particular publication period

### Last Updated Date Filters

The `last_updated_after_filter` and `last_updated_before_filter` parameters filter results based on when content was **last modified or updated**. This is useful when you need to:

* Find recently updated or maintained content
* Exclude stale content that hasn't been updated recently
* Focus on content that has been refreshed within a specific period

### Search Recency Filter

The `search_recency_filter` parameter provides a simple way to filter results by predefined time periods relative to the current date. This is useful when you need to:

* Find content from the past hour, day, week, month, or year
* Get recent results without specifying exact dates
* Quickly filter for timely information

**Available values:**

* `"hour"` - Content from the past hour. Use for real-time data such as breaking news or live events.
* `"day"` - Content from the past 24 hours
* `"week"` - Content from the past 7 days
* `"month"` - Content from the past 30 days
* `"year"` - Content from the past 365 days

**Important:** Publication filters use the original creation/publication date, last updated filters use the modification date, while recency filters use a relative time period from the current date.

To constrain search results by publication date:

```bash theme={null}
"search_after_date_filter": "3/1/2025",
"search_before_date_filter": "3/5/2025"
```

To constrain search results by last updated date:

```bash theme={null}
"last_updated_after_filter": "07/01/2025",
"last_updated_before_filter": "12/30/2025"
```

To constrain search results by recency:

```bash theme={null}
"search_recency_filter": "week"
```

These filters will be applied in addition to any other search parameters.

## Examples

**1. Limiting Results by Publication Date Range**

This example limits search results to content published between March 1, 2025, and March 5, 2025.

**Request Example**

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity

  client = Perplexity()

  response = client.search.create(
      query="latest AI developments",
      max_results=10,
      search_after_date_filter="3/1/2025",
      search_before_date_filter="3/5/2025"
  )

  print(response)
  ```

  ```typescript Typescript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  const response = await client.search.create({
    query: "latest AI developments",
    max_results: 10,
    search_after_date_filter: "3/1/2025",
    search_before_date_filter: "3/5/2025"
  });

  console.log(response);
  ```

  ```bash cURL theme={null}
  curl -X POST 'https://api.perplexity.ai/search' \
    -H 'Authorization: Bearer $PERPLEXITY_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
      "query": "latest AI developments",
      "max_results": 10,
      "search_after_date_filter": "3/1/2025",
      "search_before_date_filter": "3/5/2025"
    }' | jq
  ```
</CodeGroup>

**2. Filtering with a Single Publication Date Parameter**

If you only wish to restrict the results to those published on or after a specific date, include just the `search_after_date_filter`:

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity

  client = Perplexity()

  response = client.search.create(
      query="tech news published after March 1, 2025",
      max_results=10,
      search_after_date_filter="3/1/2025"
  )

  print(response)
  ```

  ```typescript Typescript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  const response = await client.search.create({
    query: "tech news published after March 1, 2025",
    max_results: 10,
    search_after_date_filter: "3/1/2025"
  });

  console.log(response);
  ```

  ```bash cURL theme={null}
  curl -X POST 'https://api.perplexity.ai/search' \
    -H 'Authorization: Bearer $PERPLEXITY_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
      "query": "tech news published after March 1, 2025",
      "max_results": 10,
      "search_after_date_filter": "3/1/2025"
    }' | jq
  ```
</CodeGroup>

**3. Filtering by Last Updated Date Range**

This example limits search results to content that was last updated between July 1, 2025, and December 30, 2025. This is useful for finding recently maintained or refreshed content.

**Request Example**

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity

  client = Perplexity()

  response = client.search.create(
      query="recently updated tech articles",
      max_results=10,
      last_updated_after_filter="07/01/2025",
      last_updated_before_filter="12/30/2025"
  )

  print(response)
  ```

  ```typescript Typescript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  const response = await client.search.create({
    query: "recently updated tech articles",
    max_results: 10,
    last_updated_after_filter: "07/01/2025",
    last_updated_before_filter: "12/30/2025"
  });

  console.log(response);
  ```

  ```bash cURL theme={null}
  curl -X POST 'https://api.perplexity.ai/search' \
    -H 'Authorization: Bearer $PERPLEXITY_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
      "query": "recently updated tech articles",
      "max_results": 10,
      "last_updated_after_filter": "07/01/2025",
      "last_updated_before_filter": "12/30/2025"
    }' | jq
  ```
</CodeGroup>

**4. Using Search Recency Filter**

The `search_recency_filter` provides a convenient way to filter results by predefined time periods without specifying exact dates:

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity

  client = Perplexity()

  response = client.search.create(
      query="latest AI developments",
      max_results=10,
      search_recency_filter="week"
  )

  print(response)
  ```

  ```typescript Typescript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  const response = await client.search.create({
    query: "latest AI developments",
    max_results: 10,
    search_recency_filter: "week"
  });

  console.log(response);
  ```

  ```bash cURL theme={null}
  curl -X POST 'https://api.perplexity.ai/search' \
    -H 'Authorization: Bearer $PERPLEXITY_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
      "query": "latest AI developments",
      "max_results": 10,
      "search_recency_filter": "week"
    }' | jq
  ```
</CodeGroup>

This example will return only content from the past 7 days, automatically calculated from the current date.

**5. Different Recency Filter Options**

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity

  client = Perplexity()

  # Get content from the past hour (real-time: breaking news or live events)
  hour_response = client.search.create(
      query="live market updates",
      max_results=5,
      search_recency_filter="hour"
  )

  # Get content from the past day
  day_response = client.search.create(
      query="breaking tech news",
      max_results=5,
      search_recency_filter="day"
  )

  # Get content from the past month
  month_response = client.search.create(
      query="AI research developments",
      max_results=10,
      search_recency_filter="month"
  )

  # Get content from the past year
  year_response = client.search.create(
      query="major tech trends",
      max_results=15,
      search_recency_filter="year"
  )
  ```

  ```typescript Typescript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  // Get content from the past hour (real-time: breaking news or live events)
  const hourResponse = await client.search.create({
    query: "live market updates",
    max_results: 5,
    search_recency_filter: "hour"
  });

  // Get content from the past day
  const dayResponse = await client.search.create({
    query: "breaking tech news",
    max_results: 5,
    search_recency_filter: "day"
  });

  // Get content from the past month
  const monthResponse = await client.search.create({
    query: "AI research developments",
    max_results: 10,
    search_recency_filter: "month"
  });

  // Get content from the past year
  const yearResponse = await client.search.create({
    query: "major tech trends",
    max_results: 15,
    search_recency_filter: "year"
  });
  ```

  ```bash cURL theme={null}
  # Get content from the past hour (real-time: breaking news or live events)
  curl -X POST 'https://api.perplexity.ai/search' \
    -H 'Authorization: Bearer $PERPLEXITY_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
      "query": "live market updates",
      "max_results": 5,
      "search_recency_filter": "hour"
    }' | jq

  # Get content from the past day
  curl -X POST 'https://api.perplexity.ai/search' \
    -H 'Authorization: Bearer $PERPLEXITY_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
      "query": "breaking tech news",
      "max_results": 5,
      "search_recency_filter": "day"
    }' | jq

  # Get content from the past month
  curl -X POST 'https://api.perplexity.ai/search' \
    -H 'Authorization: Bearer $PERPLEXITY_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
      "query": "AI research developments",
      "max_results": 10,
      "search_recency_filter": "month"
    }' | jq
  ```
</CodeGroup>

## Parameter Reference

### `search_after_date_filter`

* **Type**: String
* **Format**: "%m/%d/%Y" (e.g., "3/1/2025")
* **Description**: Filters search results to only include content published after this date
* **Optional**: Yes
* **Example**: `"search_after_date_filter": "1/1/2025"`

### `search_before_date_filter`

* **Type**: String
* **Format**: "%m/%d/%Y" (e.g., "3/1/2025")
* **Description**: Filters search results to only include content published before this date
* **Optional**: Yes
* **Example**: `"search_before_date_filter": "12/31/2025"`

### `last_updated_after_filter`

* **Type**: String
* **Format**: "%m/%d/%Y" (e.g., "07/01/2025")
* **Description**: Filters search results to only include content last updated after this date
* **Optional**: Yes
* **Example**: `"last_updated_after_filter": "07/01/2025"`

### `last_updated_before_filter`

* **Type**: String
* **Format**: "%m/%d/%Y" (e.g., "12/30/2025")
* **Description**: Filters search results to only include content last updated before this date
* **Optional**: Yes
* **Example**: `"last_updated_before_filter": "12/30/2025"`

### `search_recency_filter`

* **Type**: String
* **Allowed Values**: "hour", "day", "week", "month", "year"
* **Description**: Filters search results to content from the specified time period relative to the current date
* **Optional**: Yes
* **Example**: `"search_recency_filter": "week"`

## Best Practices

**Date Format**

* Strict Format: Dates must match the "%m/%d/%Y" format exactly. For example, "3/1/2025" or "03/01/2025" is acceptable.
* Consistency: Use one or both date filters consistently based on your search needs. Combining both provides a clear range.

**Filter Selection**

* Choose the Right Filter Type: Use publication date filters (`search_after_date_filter`/`search_before_date_filter`) when you care about when content was originally created. Use last updated filters (`last_updated_after_filter`/`last_updated_before_filter`) when you need recently maintained content. Use recency filters (`search_recency_filter`) for quick, relative time filtering.
* Recency vs. Exact Dates: Use `search_recency_filter` for convenience when you want recent content (e.g., "past week"). Use specific date filters when you need precise control over the time range.
* Combining Filters: You can use both publication and last updated filters together to find content that meets both criteria (e.g., published in 2024 but updated recently). Note that `search_recency_filter` cannot be combined with specific date filters (`search_after_date_filter`/`search_before_date_filter` or `last_updated_after_filter`/`last_updated_before_filter`).

**Client-Side Validation**

* Regex Check: Validate date strings on the client side using a regex such as:

<CodeGroup>
  ```bash theme={null}
  date_regex='^(0?[1-9]|1[0-2])/(0?[1-9]|[12][0-9]|3[01])/[0-9]{4}$'
  ```

  ```python theme={null}
  date_regex = r'^(0?[1-9]|1[0-2])/(0?[1-9]|[12]\d|3[01])/\d{4}$'
  ```
</CodeGroup>

This ensures that dates conform to the required format before sending the request.

**Performance Considerations**

* Narrowing the Search: Applying date range filters typically reduces the number of results, which may improve response times and result relevance.
* Avoid Over-Restriction: Ensure that the date range is neither too narrow (limiting useful results) nor too broad (defeating the purpose of the filter).

## Advanced Usage Patterns

**Finding Breaking News**

Use the `search_recency_filter` with `"hour"` for live events, or `"day"` for the most recent breaking news:

```python theme={null}
# Live events and real-time data
response = client.search(
    query="live market updates",
    max_results=5,
    search_recency_filter="hour"
)

# Breaking news from the past 24 hours
response = client.search(
    query="breaking news technology",
    max_results=5,
    search_recency_filter="day"
)
```

**Historical Research**

Use specific date ranges to research historical events or trends:

```python theme={null}
response = client.search(
    query="AI developments",
    max_results=20,
    search_after_date_filter="1/1/2023",
    search_before_date_filter="12/31/2023"
)
```

**Finding Recently Maintained Content**

Use last updated filters to find content that has been refreshed or maintained recently:

```python theme={null}
response = client.search(
    query="React best practices",
    max_results=10,
    last_updated_after_filter="07/01/2025"
)
```

**Trend Analysis**

Compare different time periods by making multiple searches:

```python theme={null}
# Recent trends
recent = client.search(
    query="machine learning trends",
    search_recency_filter="month"
)

# Older trends for comparison
older = client.search(
    query="machine learning trends",
    search_after_date_filter="1/1/2023",
    search_before_date_filter="1/31/2023"
)
```

## Error Handling

When using date filters, ensure proper error handling for invalid date formats:

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity
  import re

  def validate_date_format(date_string):
      pattern = r'^(0?[1-9]|1[0-2])/(0?[1-9]|[12]\d|3[01])/\d{4}$'
      return bool(re.match(pattern, date_string))

  def search_with_date_filter(query, after_date=None, before_date=None):
      client = Perplexity()
      
      # Validate date formats
      if after_date and not validate_date_format(after_date):
          raise ValueError(f"Invalid date format: {after_date}")
      if before_date and not validate_date_format(before_date):
          raise ValueError(f"Invalid date format: {before_date}")
      
      try:
          response = client.search(
              query=query,
              search_after_date_filter=after_date,
              search_before_date_filter=before_date
          )
          return response
      except Exception as e:
          print(f"Search failed: {e}")
          return None
  ```

  ```typescript Typescript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  function validateDateFormat(dateString: string): boolean {
    const pattern = /^(0?[1-9]|1[0-2])\/(0?[1-9]|[12]\d|3[01])\/\d{4}$/;
    return pattern.test(dateString);
  }

  async function searchWithDateFilter(
    query: string, 
    afterDate?: string, 
    beforeDate?: string
  ) {
    const client = new Perplexity();
    
    // Validate date formats
    if (afterDate && !validateDateFormat(afterDate)) {
      throw new Error(`Invalid date format: ${afterDate}`);
    }
    if (beforeDate && !validateDateFormat(beforeDate)) {
      throw new Error(`Invalid date format: ${beforeDate}`);
    }
    
    try {
      const response = await client.search.create({
        query,
        search_after_date_filter: afterDate,
        search_before_date_filter: beforeDate
      });
      return response;
    } catch (error) {
      console.error('Search failed:', error);
      return null;
    }
  }
  ```
</CodeGroup>


# Search Domain Filter
Source: https://docs.perplexity.ai/docs/search/filters/domain-filter



<Note>
  The `search_domain_filter` parameter allows you to limit search results to specific domains or exclude certain domains from search results. This supports domain-level filtering for precise content control.
</Note>

<Warning>
  You can add a maximum of 20 domains to the `search_domain_filter` list. The filter works in either allowlist mode (include only) or denylist mode (exclude), but not both simultaneously.
</Warning>

<Info>
  Domain filters allow you to specify which domains to include or exclude in search results. You can filter by specific domains, top-level domains (TLDs), or domain parts. You can specify up to 20 domains per request. Domains should be provided without the protocol (e.g., "nature.com" not "[https://nature.com](https://nature.com)").
</Info>

## Overview

The domain filter for the Search API allows you to control which sources appear in your search results by limiting them to specific domains or excluding certain domains. This is particularly useful when you need to:

* Focus research on authoritative or trusted sources
* Filter out specific domains from search results
* Search within specific publication networks or organizations
* Build domain-specific search applications
* Conduct competitive research within specific industry domains

The `search_domain_filter` parameter accepts an array of domain strings. The filter operates in two modes:

* **Allowlist mode**: Include only the specified domains (no `-` prefix)
* **Denylist mode**: Exclude the specified domains (use `-` prefix)

```bash theme={null}
# Allowlist: Only search these domains
"search_domain_filter": ["nature.com", "science.org", "cell.com"]

# Denylist: Exclude these domains
"search_domain_filter": ["-reddit.com", "-pinterest.com", "-quora.com"]
```

## Filtering Capabilities

Domain filters support flexible matching across different domain components:

### Root Domain Filtering

Specify a root domain to match all content from that domain and its subdomains:

```bash theme={null}
"search_domain_filter": ["wikipedia.org"]
```

This will match:

* `en.wikipedia.org`
* `fr.wikipedia.org`
* `de.wikipedia.org`
* Any other Wikipedia language subdomain

### Top-Level Domain (TLD) Filtering

Filter by top-level domain to target specific categories of sites:

```bash theme={null}
"search_domain_filter": [".gov"]
```

This will match all government domains:

* `nasa.gov`
* `cdc.gov`
* `irs.gov`
* Any other `.gov` domain

<Tip>
  TLD filtering is particularly useful for targeting specific types of organizations, such as `.gov` for government sites, `.edu` for educational institutions, or country-specific TLDs like `.uk` or `.ca`.
</Tip>

### Domain Part Filtering

Any part of a domain can be used as a filter. The system will match domains containing that component.

## Examples

**1. Allowlist Specific Domains**

This example limits search results to authoritative academic publishers:

**Request Example**

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity

  client = Perplexity()

  response = client.search.create(
      query="climate change research",
      max_results=10,
      search_domain_filter=[
          "nature.com",
          "science.org",
          "cell.com"
      ]
  )

  for result in response.results:
      print(f"{result.title}: {result.url}")
  ```

  ```typescript Typescript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  const response = await client.search.create({
    query: "climate change research",
    max_results: 10,
    search_domain_filter: [
      "nature.com",
      "science.org",
      "cell.com"
    ]
  });

  for (const result of response.results) {
    console.log(`${result.title}: ${result.url}`);
  }
  ```

  ```bash cURL theme={null}
  curl -X POST 'https://api.perplexity.ai/search' \
    -H 'Authorization: Bearer $PERPLEXITY_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
      "query": "climate change research",
      "max_results": 10,
      "search_domain_filter": [
        "nature.com",
        "science.org",
        "cell.com"
      ]
    }' | jq
  ```
</CodeGroup>

**2. Tech News Sources**

Search across major technology news websites:

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity

  client = Perplexity()

  response = client.search.create(
      query="latest tech trends 2025",
      max_results=10,
      search_domain_filter=[
          "techcrunch.com",
          "theverge.com",
          "arstechnica.com",
          "wired.com"
      ]
  )

  for result in response.results:
      print(f"{result.title}")
      print(f"Source: {result.url}")
      print(f"Date: {result.date}")
      print("---")
  ```

  ```typescript Typescript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  const response = await client.search.create({
    query: "latest tech trends 2025",
    max_results: 10,
    search_domain_filter: [
      "techcrunch.com",
      "theverge.com",
      "arstechnica.com",
      "wired.com"
    ]
  });

  for (const result of response.results) {
    console.log(`${result.title}`);
    console.log(`Source: ${result.url}`);
    console.log(`Date: ${result.date}`);
    console.log("---");
  }
  ```

  ```bash cURL theme={null}
  curl -X POST 'https://api.perplexity.ai/search' \
    -H 'Authorization: Bearer $PERPLEXITY_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
      "query": "latest tech trends 2025",
      "max_results": 10,
      "search_domain_filter": [
        "techcrunch.com",
        "theverge.com",
        "arstechnica.com",
        "wired.com"
      ]
    }' | jq
  ```
</CodeGroup>

**3. Government and Educational Sources (TLD Filtering)**

Use top-level domain filtering to search across all government or educational institutions:

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity

  client = Perplexity()

  # Search all .gov and .edu domains
  response = client.search.create(
      query="climate change policy research",
      max_results=15,
      search_domain_filter=[
          ".gov",
          ".edu"
      ]
  )

  for result in response.results:
      print(f"{result.title}")
      print(f"Source: {result.url}")
      print("---")
  ```

  ```typescript Typescript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  // Search all .gov and .edu domains
  const response = await client.search.create({
    query: "climate change policy research",
    max_results: 15,
    search_domain_filter: [
      ".gov",
      ".edu"
    ]
  });

  for (const result of response.results) {
    console.log(`${result.title}`);
    console.log(`Source: ${result.url}`);
    console.log("---");
  }
  ```

  ```bash cURL theme={null}
  curl -X POST 'https://api.perplexity.ai/search' \
    -H 'Authorization: Bearer $PERPLEXITY_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
      "query": "climate change policy research",
      "max_results": 15,
      "search_domain_filter": [
        ".gov",
        ".edu"
      ]
    }' | jq
  ```
</CodeGroup>

**4. Wikipedia Across Languages (Subdomain Matching)**

Search across all Wikipedia language editions by specifying the root domain:

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity

  client = Perplexity()

  # Matches en.wikipedia.org, fr.wikipedia.org, de.wikipedia.org, etc.
  response = client.search.create(
      query="quantum mechanics",
      max_results=10,
      search_domain_filter=["wikipedia.org"]
  )

  for result in response.results:
      print(f"{result.title}")
      print(f"URL: {result.url}")
      print("---")
  ```

  ```typescript Typescript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  // Matches en.wikipedia.org, fr.wikipedia.org, de.wikipedia.org, etc.
  const response = await client.search.create({
    query: "quantum mechanics",
    max_results: 10,
    search_domain_filter: ["wikipedia.org"]
  });

  for (const result of response.results) {
    console.log(`${result.title}`);
    console.log(`URL: ${result.url}`);
    console.log("---");
  }
  ```

  ```bash cURL theme={null}
  curl -X POST 'https://api.perplexity.ai/search' \
    -H 'Authorization: Bearer $PERPLEXITY_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
      "query": "quantum mechanics",
      "max_results": 10,
      "search_domain_filter": ["wikipedia.org"]
    }' | jq
  ```
</CodeGroup>

**5. Denylist Specific Domains**

This example shows how to exclude specific domains from search results by prefixing the domain name with a minus sign (`-`):

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity

  client = Perplexity()

  # Exclude social media and Q&A sites from search results
  response = client.search.create(
      query="latest advancements in renewable energy",
      max_results=10,
      search_domain_filter=[
          "-pinterest.com",
          "-reddit.com",
          "-quora.com"
      ]
  )

  for result in response.results:
      print(f"{result.title}: {result.url}")
  ```

  ```typescript Typescript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  // Exclude social media and Q&A sites from search results
  const response = await client.search.create({
    query: "latest advancements in renewable energy",
    max_results: 10,
    search_domain_filter: [
      "-pinterest.com",
      "-reddit.com",
      "-quora.com"
    ]
  });

  for (const result of response.results) {
    console.log(`${result.title}: ${result.url}`);
  }
  ```

  ```bash cURL theme={null}
  curl -X POST 'https://api.perplexity.ai/search' \
    -H 'Authorization: Bearer $PERPLEXITY_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
      "query": "latest advancements in renewable energy",
      "max_results": 10,
      "search_domain_filter": [
        "-pinterest.com",
        "-reddit.com",
        "-quora.com"
      ]
    }' | jq
  ```
</CodeGroup>

**6. Combining Domain Filter with Other Filters**

Domain filters work seamlessly with other search parameters for precise control:

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity

  client = Perplexity()

  # Combine domain filter with date and language filters
  response = client.search.create(
      query="quantum computing breakthroughs",
      max_results=20,
      search_domain_filter=[
          "nature.com",
          "science.org",
          "arxiv.org"
      ],
      search_recency_filter="month",
      search_language_filter=["en"]
  )

  for result in response.results:
      print(f"{result.title}")
      print(f"URL: {result.url}")
      print(f"Date: {result.date}")
      print("---")
  ```

  ```typescript Typescript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  // Combine domain filter with date and language filters
  const response = await client.search.create({
    query: "quantum computing breakthroughs",
    max_results: 20,
    search_domain_filter: [
      "nature.com",
      "science.org",
      "arxiv.org"
    ],
    search_recency_filter: "month",
    search_language_filter: ["en"]
  });

  for (const result of response.results) {
    console.log(`${result.title}`);
    console.log(`URL: ${result.url}`);
    console.log(`Date: ${result.date}`);
    console.log("---");
  }
  ```

  ```bash cURL theme={null}
  curl -X POST 'https://api.perplexity.ai/search' \
    -H 'Authorization: Bearer $PERPLEXITY_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
      "query": "quantum computing breakthroughs",
      "max_results": 20,
      "search_domain_filter": [
        "nature.com",
        "science.org",
        "arxiv.org"
      ],
      "search_recency_filter": "month",
      "search_language_filter": ["en"]
    }' | jq
  ```
</CodeGroup>

## Parameter Reference

### `search_domain_filter`

* **Type**: Array of strings
* **Format**:
  * Domain names without protocol (e.g., "example.com")
  * Prefix with `-` for denylisting (e.g., "-reddit.com")
* **Description**: Filters search results to include or exclude content from specified domains
* **Optional**: Yes
* **Maximum**: 20 domains per request
* **Modes**:
  * Allowlist mode: Include only specified domains (no `-` prefix)
  * Denylist mode: Exclude specified domains (use `-` prefix)
* **Example**:
  * Allowlist: `"search_domain_filter": ["nature.com", "science.org"]`
  * Denylist: `"search_domain_filter": ["-reddit.com", "-pinterest.com"]`

## Domain Format Guidelines

**Correct Domain Formats:**

* `"nature.com"` - Root domain (matches nature.com and all subdomains)
* `"blog.example.com"` - Specific subdomain
* `"arxiv.org"` - Root domain (matches all subdomains)
* `".gov"` - Top-level domain (matches all .gov sites)
* `".edu"` - Top-level domain (matches all .edu sites)
* `".uk"` - Country-code TLD (matches all .uk sites)
* `"wikipedia.org"` - Matches en.wikipedia.org, fr.wikipedia.org, etc.
* `"-reddit.com"` - Exclude entire domain and all subdomains
* `"-pinterest.com"` - Exclude domain
* `"-.gov"` - Exclude all .gov domains

**Incorrect Domain Formats:**

* ❌ `"https://nature.com"` - Don't include protocol
* ❌ `"nature.com/"` - Don't include trailing slash
* ❌ `"nature.com/articles"` - Don't include path (path filtering coming soon)
* ❌ `"www.nature.com"` - Avoid www prefix (use root domain)

## Best Practices

### Domain Selection Strategy

* **Use Root Domains for Broad Coverage**: Specify root domains (e.g., "wikipedia.org") to match all subdomains automatically, including different language versions and regional sites.
* **Use TLDs for Categorical Filtering**: Target specific organization types with TLD filters like `.gov` for government, `.edu` for education, or `.org` for non-profits.
* **Be Specific When Needed**: Choose specific domains that are directly relevant to your search query to ensure high-quality results.
* **Quality Over Quantity**: Using fewer, highly relevant domains often produces better results than maximizing the 20-domain limit.
* **Consider Domain Authority**: Prioritize authoritative sources in your field for more reliable information.
* **Choose Your Mode**: Use either allowlist mode (include only) OR denylist mode (exclude), but not both in the same request. Denylisting is useful when you want broad search coverage but need to exclude specific low-quality or irrelevant sources.

### Locale and Regional Targeting

While domain filters don't directly filter by user location, you can target specific locales using:

* **Country-code TLDs**: Use filters like `.uk`, `.ca`, `.de`, `.jp` to target country-specific domains
* **Subdomain matching**: Specify regional subdomains when available (e.g., "uk.domain.com")
* **Combined approach**: Mix country TLDs with specific trusted domains for precise regional filtering

<Tip>
  For international research, combine TLD filtering with the `search_language_filter` parameter to refine results by both location and language.
</Tip>

### Domain Selection

* **Use Trusted Sources**: Select a specific set of trusted sources you want to search within (e.g., academic research, official documentation).
* **Leverage TLD Filtering**: When researching topics that span many sites of the same type, use TLD filters to cast a wider net (e.g., `.gov` for policy research).
* **Focus on Quality**: Choose authoritative domains that consistently provide reliable information relevant to your queries.

### Client-Side Validation

Validate domain formats on the client side before sending requests:

<CodeGroup>
  ```python Python theme={null}
  import re

  def validate_domain(domain):
      """Validate domain format including TLD filters."""
      # TLD filter (e.g., .gov, .edu)
      if domain.startswith('.'):
          tld_pattern = r'^\.[a-zA-Z]{2,}$'
          return bool(re.match(tld_pattern, domain))
      
      # Standard domain validation pattern
      pattern = r'^[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(\.[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$'
      return bool(re.match(pattern, domain))

  def validate_domain_filter(domains):
      """Validate domain filter array."""
      if len(domains) > 20:
          raise ValueError("Maximum 20 domains allowed")

      for domain in domains:
          if not validate_domain(domain):
              raise ValueError(f"Invalid domain format: {domain}")

      return True

  # Usage examples
  try:
      # Mix of regular domains and TLD filters
      domains = ["nature.com", "science.org", ".gov", ".edu"]
      validate_domain_filter(domains)

      response = client.search.create(
          query="research topic",
          search_domain_filter=domains
      )
  except ValueError as e:
      print(f"Validation error: {e}")
  ```

  ```typescript Typescript theme={null}
  function validateDomain(domain: string): boolean {
    // TLD filter (e.g., .gov, .edu)
    if (domain.startsWith('.')) {
      const tldPattern = /^\.[a-zA-Z]{2,}$/;
      return tldPattern.test(domain);
    }
    
    // Standard domain validation pattern
    const pattern = /^[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(\.[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$/;
    return pattern.test(domain);
  }

  function validateDomainFilter(domains: string[]): void {
    if (domains.length > 20) {
      throw new Error("Maximum 20 domains allowed");
    }

    for (const domain of domains) {
      if (!validateDomain(domain)) {
        throw new Error(`Invalid domain format: ${domain}`);
      }
    }
  }

  // Usage examples
  try {
    // Mix of regular domains and TLD filters
    const domains = ["nature.com", "science.org", ".gov", ".edu"];
    validateDomainFilter(domains);

    const response = await client.search.create({
      query: "research topic",
      search_domain_filter: domains
    });
  } catch (error) {
    console.error("Validation error:", error.message);
  }
  ```
</CodeGroup>

### Performance Considerations

* **Result Availability**: Narrowing to specific domains may reduce the number of available results. Be prepared to handle cases where fewer results are returned than requested.
* **Domain Coverage**: Ensure the domains you specify actually contain content relevant to your query. Overly restrictive filters may return zero results.
* **Combination Effects**: Domain filters combined with other restrictive filters (date, language) can significantly reduce result counts.

<Tip>
  For best results, combine domain filtering with other filters like `search_recency_filter` or `search_language_filter` to narrow down your search to highly relevant, timely content from your target sources. Use TLD filters like `.gov` or `.edu` when you need broad coverage across an entire category of authoritative sites.
</Tip>


# Search Language Filter
Source: https://docs.perplexity.ai/docs/search/filters/language-filter



<Note>
  The `search_language_filter` parameter allows you to filter search results by language using ISO 639-1 language codes. Only results in the specified languages will be returned.
</Note>

<Info>
  Language codes must be valid 2-letter ISO 639-1 codes (e.g., "en", "ru", "fr"). You can filter by up to 10 languages per request.
</Info>

## Overview

The language filter for the Search API allows you to control which search results are returned by limiting them to specific languages. This is particularly useful when you need to:

* Search for content in specific languages
* Conduct multilingual research across multiple languages
* Focus on regional content in local languages
* Build language-specific applications or features

The `search_language_filter` parameter accepts an array of ISO 639-1 language codes and returns only results that match those languages.

To filter search results by language:

```bash theme={null}
"search_language_filter": ["en", "fr", "de"]
```

This filter will be applied in addition to any other search parameters.

## Examples

**1. Single Language Filter**

This example limits search results to English language content only.

**Request Example**

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity

  client = Perplexity()

  response = client.search.create(
      query="artificial intelligence",
      max_results=10,
      search_language_filter=["en"]
  )

  for result in response.results:
      print(f"{result.title}: {result.url}")
  ```

  ```typescript Typescript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  const response = await client.search.create({
    query: "artificial intelligence",
    max_results: 10,
    search_language_filter: ["en"]
  });

  for (const result of response.results) {
    console.log(`${result.title}: ${result.url}`);
  }
  ```

  ```bash cURL theme={null}
  curl -X POST 'https://api.perplexity.ai/search' \
    -H 'Authorization: Bearer $PERPLEXITY_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
      "query": "artificial intelligence",
      "max_results": 10,
      "search_language_filter": ["en"]
    }' | jq
  ```
</CodeGroup>

**2. Multiple Language Filter**

Search across multiple languages to gather diverse perspectives or multilingual content:

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity

  client = Perplexity()

  # Search for content in English, French, and German
  response = client.search.create(
      query="renewable energy innovations",
      max_results=15,
      search_language_filter=["en", "fr", "de"]
  )

  for result in response.results:
      print(f"{result.title}: {result.url}")
  ```

  ```typescript Typescript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  // Search for content in English, French, and German
  const response = await client.search.create({
    query: "renewable energy innovations",
    max_results: 15,
    search_language_filter: ["en", "fr", "de"]
  });

  for (const result of response.results) {
    console.log(`${result.title}: ${result.url}`);
  }
  ```

  ```bash cURL theme={null}
  curl -X POST 'https://api.perplexity.ai/search' \
    -H 'Authorization: Bearer $PERPLEXITY_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
      "query": "renewable energy innovations",
      "max_results": 15,
      "search_language_filter": ["en", "fr", "de"]
    }' | jq
  ```
</CodeGroup>

**3. Regional Language Search**

Focus on content from specific regions by using their local languages:

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity

  client = Perplexity()

  # Search for Asian market news in Chinese, Japanese, and Korean
  response = client.search.create(
      query="technology market trends",
      max_results=10,
      search_language_filter=["zh", "ja", "ko"]
  )

  # Search for European tech news in multiple European languages
  eu_response = client.search.create(
      query="tech startups",
      max_results=10,
      search_language_filter=["en", "de", "fr", "es", "it"]
  )
  ```

  ```typescript Typescript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  // Search for Asian market news in Chinese, Japanese, and Korean
  const response = await client.search.create({
    query: "technology market trends",
    max_results: 10,
    search_language_filter: ["zh", "ja", "ko"]
  });

  // Search for European tech news in multiple European languages
  const euResponse = await client.search.create({
    query: "tech startups",
    max_results: 10,
    search_language_filter: ["en", "de", "fr", "es", "it"]
  });
  ```

  ```bash cURL theme={null}
  # Search for Asian market news
  curl -X POST 'https://api.perplexity.ai/search' \
    -H 'Authorization: Bearer $PERPLEXITY_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
      "query": "technology market trends",
      "max_results": 10,
      "search_language_filter": ["zh", "ja", "ko"]
    }' | jq
  ```
</CodeGroup>

**4. Combining with Other Filters**

Language filters work seamlessly with other search parameters for precise control:

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity

  client = Perplexity()

  # Combine language filter with date and domain filters
  response = client.search.create(
      query="climate change research",
      max_results=20,
      search_language_filter=["en", "de"],
      search_domain_filter=["nature.com", "science.org"],
      search_recency_filter="month"
  )

  for result in response.results:
      print(f"{result.title}")
      print(f"URL: {result.url}")
      print(f"Date: {result.date}")
      print("---")
  ```

  ```typescript Typescript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  // Combine language filter with date and domain filters
  const response = await client.search.create({
    query: "climate change research",
    max_results: 20,
    search_language_filter: ["en", "de"],
    search_domain_filter: ["nature.com", "science.org"],
    search_recency_filter: "month"
  });

  for (const result of response.results) {
    console.log(`${result.title}`);
    console.log(`URL: ${result.url}`);
    console.log(`Date: ${result.date}`);
    console.log("---");
  }
  ```

  ```bash cURL theme={null}
  curl -X POST 'https://api.perplexity.ai/search' \
    -H 'Authorization: Bearer $PERPLEXITY_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
      "query": "climate change research",
      "max_results": 20,
      "search_language_filter": ["en", "de"],
      "search_domain_filter": ["nature.com", "science.org"],
      "search_recency_filter": "month"
    }' | jq
  ```
</CodeGroup>

## Parameter Reference

### `search_language_filter`

* **Type**: Array of strings
* **Format**: ISO 639-1 language codes (2 lowercase letters)
* **Description**: Filters search results to only include content in the specified languages
* **Optional**: Yes
* **Maximum**: 10 language codes per request
* **Example**: `"search_language_filter": ["en", "fr", "de"]`

## Common Language Codes

Here's a comprehensive list of frequently used ISO 639-1 language codes:

| Language   | Code | Language   | Code |
| ---------- | ---- | ---------- | ---- |
| English    | `en` | Portuguese | `pt` |
| Spanish    | `es` | Dutch      | `nl` |
| French     | `fr` | Polish     | `pl` |
| German     | `de` | Swedish    | `sv` |
| Italian    | `it` | Norwegian  | `no` |
| Russian    | `ru` | Danish     | `da` |
| Chinese    | `zh` | Finnish    | `fi` |
| Japanese   | `ja` | Czech      | `cs` |
| Korean     | `ko` | Hungarian  | `hu` |
| Arabic     | `ar` | Greek      | `el` |
| Hindi      | `hi` | Turkish    | `tr` |
| Bengali    | `bn` | Hebrew     | `he` |
| Indonesian | `id` | Thai       | `th` |
| Vietnamese | `vi` | Ukrainian  | `uk` |

<Tip>
  For a complete list of ISO 639-1 language codes, see the [ISO 639-1 standard](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes).
</Tip>

## Best Practices

### Language Code Validation

* **Use Valid Codes**: Always use valid 2-letter ISO 639-1 codes. Invalid codes will result in an API error.
* **Lowercase Only**: Language codes must be lowercase (e.g., "en" not "EN").
* **Client-Side Validation**: Validate language codes on the client side using a regex pattern:

<CodeGroup>
  ```python Python theme={null}
  import re

  def validate_language_code(code):
      pattern = r'^[a-z]{2}$'
      return bool(re.match(pattern, code))

  def validate_language_filters(codes):
      if len(codes) > 10:
          raise ValueError("Maximum 10 language codes allowed")
      
      for code in codes:
          if not validate_language_code(code):
              raise ValueError(f"Invalid language code: {code}")
      
      return True

  # Usage
  try:
      codes = ["en", "fr", "de"]
      validate_language_filters(codes)
      
      response = client.search.create(
          query="technology news",
          search_language_filter=codes
      )
  except ValueError as e:
      print(f"Validation error: {e}")
  ```

  ```typescript Typescript theme={null}
  function validateLanguageCode(code: string): boolean {
    const pattern = /^[a-z]{2}$/;
    return pattern.test(code);
  }

  function validateLanguageFilters(codes: string[]): void {
    if (codes.length > 10) {
      throw new Error("Maximum 10 language codes allowed");
    }
    
    for (const code of codes) {
      if (!validateLanguageCode(code)) {
        throw new Error(`Invalid language code: ${code}`);
      }
    }
  }

  // Usage
  try {
    const codes = ["en", "fr", "de"];
    validateLanguageFilters(codes);
    
    const response = await client.search.create({
      query: "technology news",
      search_language_filter: codes
    });
  } catch (error) {
    console.error("Validation error:", error.message);
  }
  ```
</CodeGroup>

### Strategic Language Selection

* **Be Specific**: Choose languages that are most relevant to your research or application needs.
* **Consider Your Audience**: Select languages that match your target audience's preferences.
* **Regional Relevance**: Combine language filters with geographic filters (`country` parameter) for better regional targeting.
* **Content Availability**: Some topics may have limited content in certain languages. Start broad and narrow down as needed.

### Performance Considerations

* **Filter Size**: While you can specify up to 10 languages, using fewer languages may improve response times.
* **Result Quality**: More languages mean a broader search scope, which can dilute result relevance. Be strategic about which languages to include.
* **Combination Effects**: Language filters combined with other restrictive filters (domain, date) may significantly reduce the number of results.

## Advanced Usage Patterns

### Multilingual Research

Conduct comprehensive research by searching across multiple languages:

```python theme={null}
from perplexity import Perplexity

client = Perplexity()

# Research a global topic in multiple languages
languages = [
    ["en"],           # English-speaking countries
    ["zh", "ja"],     # East Asia
    ["es", "pt"],     # Latin America and Iberia
    ["fr", "de", "it"] # Western Europe
]

results_by_region = {}

for lang_group in languages:
    response = client.search.create(
        query="sustainable development goals progress",
        max_results=10,
        search_language_filter=lang_group
    )
    results_by_region[", ".join(lang_group)] = response.results

# Analyze results by language/region
for region, results in results_by_region.items():
    print(f"Results in {region}: {len(results)} found")
```

### Content Localization Research

Find examples and references in target languages for localization projects:

```python theme={null}
# Find product reviews in target markets
target_languages = ["ja", "ko", "zh"]  # Asian markets

response = client.search.create(
    query="smartphone reviews 2024",
    max_results=15,
    search_language_filter=target_languages,
    search_recency_filter="month"
)
```

### Academic Research Across Languages

Access scholarly content in different languages:

```python theme={null}
# Search for research papers in multiple languages
response = client.search.create(
    query="quantum computing algorithms",
    max_results=20,
    search_language_filter=["en", "de", "fr", "ru"],
    search_domain_filter=["arxiv.org", "nature.com", "science.org"]
)
```

### News Monitoring by Language

Track news stories across different language regions:

```python theme={null}
# Monitor breaking news in different languages
news_queries = {
    "English": ["en"],
    "Chinese": ["zh"],
    "Spanish": ["es"],
    "Arabic": ["ar"]
}

for region, langs in news_queries.items():
    response = client.search.create(
        query="breaking news technology",
        max_results=5,
        search_language_filter=langs,
        search_recency_filter="day"
    )
    print(f"{region} News: {len(response.results)} articles")
```

## Error Handling

When using language filters, implement proper error handling for validation issues:

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity, BadRequestError

  client = Perplexity()

  def safe_language_search(query, languages):
      """
      Perform a language-filtered search with error handling.
      """
      try:
          # Validate language codes
          if not isinstance(languages, list):
              raise ValueError("Languages must be provided as a list")
          
          if len(languages) > 10:
              raise ValueError("Maximum 10 language codes allowed")
          
          # Validate each code format
          for lang in languages:
              if not isinstance(lang, str) or len(lang) != 2 or not lang.islower():
                  raise ValueError(f"Invalid language code format: {lang}")
          
          # Perform search
          response = client.search.create(
              query=query,
              search_language_filter=languages,
              max_results=10
          )
          
          return response
          
      except ValueError as e:
          print(f"Validation error: {e}")
          return None
      except BadRequestError as e:
          print(f"API error: {e.message}")
          return None
      except Exception as e:
          print(f"Unexpected error: {e}")
          return None

  # Usage
  results = safe_language_search(
      "artificial intelligence",
      ["en", "fr", "de"]
  )

  if results:
      print(f"Found {len(results.results)} results")
  ```

  ```typescript Typescript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  async function safeLanguageSearch(
    query: string,
    languages: string[]
  ): Promise<any | null> {
    try {
      // Validate language codes
      if (!Array.isArray(languages)) {
        throw new Error("Languages must be provided as an array");
      }
      
      if (languages.length > 10) {
        throw new Error("Maximum 10 language codes allowed");
      }
      
      // Validate each code format
      for (const lang of languages) {
        if (typeof lang !== 'string' || 
            lang.length !== 2 || 
            lang !== lang.toLowerCase()) {
          throw new Error(`Invalid language code format: ${lang}`);
        }
      }
      
      // Perform search
      const response = await client.search.create({
        query,
        search_language_filter: languages,
        max_results: 10
      });
      
      return response;
      
    } catch (error) {
      if (error instanceof Perplexity.BadRequestError) {
        console.error("API error:", error.message);
      } else if (error instanceof Error) {
        console.error("Error:", error.message);
      }
      return null;
    }
  }

  // Usage
  const results = await safeLanguageSearch(
    "artificial intelligence",
    ["en", "fr", "de"]
  );

  if (results) {
    console.log(`Found ${results.results.length} results`);
  }
  ```
</CodeGroup>

<Tip>
  For best results, combine language filtering with other filters like `search_domain_filter` or `search_recency_filter` to narrow down your search to highly relevant, timely content in your target languages.
</Tip>


# People Search
Source: https://docs.perplexity.ai/docs/search/filters/people-search



<Note>
  The `search_type` parameter switches the Search API between general web search and specialized search modes. Set `search_type="people"` to invoke People Search and retrieve professional information about individuals such as names, job titles, and companies.
</Note>

## Overview

People Search lets you query Perplexity's index for professionals, employees, and public figures. Use it when your application needs to:

* Look up a specific person's professional background
* Find employees at a company by role or title
* Identify professionals in a particular field or location
* Research leadership teams or organizational structures

Pass `search_type="people"` on a standard Search API request to route the query through the People Search backend. All other Search API parameters (e.g., `max_results`, `max_tokens_per_page`) continue to apply.

## Request Example

The example below finds engineering leadership at a specific company.

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity

  client = Perplexity()

  response = client.search.create(
      query="VP of Engineering at Stripe",
      search_type="people",
      max_results=10
  )

  for result in response.results:
      print(f"{result.title}: {result.url}")
  ```

  ```typescript Typescript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  const response = await client.search.create({
      query: "VP of Engineering at Stripe",
      search_type: "people",
      max_results: 10
  });

  for (const result of response.results) {
      console.log(`${result.title}: ${result.url}`);
  }
  ```

  ```bash cURL theme={null}
  curl -X POST 'https://api.perplexity.ai/search' \
    -H 'Authorization: Bearer $PERPLEXITY_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
      "query": "VP of Engineering at Stripe",
      "search_type": "people",
      "max_results": 10
    }' | jq
  ```
</CodeGroup>

## Query Tips

For best results, include identifying details in the query:

| Approach            | Example query                              |
| ------------------- | ------------------------------------------ |
| **Name + company**  | "Find John Smith who works at Google"      |
| **Role + company**  | "Head of Design at Figma"                  |
| **Role + location** | "Marketing directors in San Francisco"     |
| **Role + field**    | "Machine learning researchers at Stanford" |

<Tip>
  For agentic workflows that need the model to autonomously decide when to look up people, use the [`people_search` tool](/docs/agent-api/tools/people-search) with the Agent API instead.
</Tip>


# Perplexity Search API
Source: https://docs.perplexity.ai/docs/search/quickstart

Access real-time web search results with Perplexity's Search API. Get ranked results, domain filtering, multi-query search, and content extraction for developers.

## Overview

<Card title="Try Our New Interactive Playground" href="https://console.perplexity.ai">
  Test search queries and parameters in real time, **no API key required**.
</Card>

Perplexity's Search API provides developers with real-time access to ranked web search results from a continuously refreshed index. Unlike traditional search APIs, Perplexity returns structured results with advanced filtering by domain, language, and region.

Use the Search API when you need raw, ranked web results with control over sources, regions, and extracted content. For LLM-generated summaries, use our [Agent API](/docs/agent-api/quickstart) or [Sonar API](/docs/sonar/quickstart).

<Card title="Search Evals" href="https://github.com/perplexityai/search_evals">
  Benchmark Perplexity Search against other web search APIs across multiple evaluation suites, and explore our latest results.
</Card>

<Info>
  We recommend using our [official SDKs](/docs/sdk/overview) for a more convenient and type-safe way to interact with the Search API.
</Info>

## Installation

Install the SDK for your preferred language:

<CodeGroup>
  ```bash Python theme={null}
  pip install perplexityai
  ```

  ```bash Typescript theme={null}
  npm install @perplexity-ai/perplexity_ai
  ```
</CodeGroup>

## Authentication

Set your API key as an environment variable. The SDK will automatically read it:

<Tabs>
  <Tab title="macOS/Linux">
    ```bash theme={null}
    export PERPLEXITY_API_KEY="your_api_key_here"
    ```
  </Tab>

  <Tab title="Windows">
    ```powershell theme={null}
    setx PERPLEXITY_API_KEY "your_api_key_here"
    ```
  </Tab>
</Tabs>

<Info>
  All SDK examples below automatically use the `PERPLEXITY_API_KEY` environment variable. You can also pass the key explicitly if needed.
</Info>

## Basic Usage

Start with a basic search query to get relevant web results. See the [API Reference](/api-reference/search-post) for complete parameter documentation.

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity

  client = Perplexity()

  search = client.search.create(
      query="latest AI developments 2024",
      max_results=5,
      max_tokens_per_page=4096
  )

  for result in search.results:
      print(f"{result.title}: {result.url}")
  ```

  ```typescript Typescript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  const search = await client.search.create({
      query: "latest AI developments 2024",
      max_results: 5,
      max_tokens_per_page: 4096
  });

  for (const result of search.results) {
      console.log(`${result.title}: ${result.url}`);
  }
  ```

  ```javascript JavaScript theme={null}
  const Perplexity = require('@perplexity-ai/perplexity_ai');

  const client = new Perplexity();

  async function main() {
      const search = await client.search.create({
          query: "latest AI developments 2024",
          max_results: 5,
          max_tokens_per_page: 4096
      });

      for (const result of search.results) {
          console.log(`${result.title}: ${result.url}`);
      }
  }

  main();
  ```

  ```bash cURL theme={null}
  curl -X POST 'https://api.perplexity.ai/search' \
    -H 'Authorization: Bearer $PERPLEXITY_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
      "query": "latest AI developments 2024",
      "max_results": 5,
      "max_tokens_per_page": 4096
    }' | jq
  ```
</CodeGroup>

<Accordion title="Response">
  ```json theme={null}
  {
    "results": [
      {
        "title": "2024: A year of extraordinary progress and advancement in AI - Google Blog",
        "url": "https://blog.google/technology/ai/2024-ai-extraordinary-progress-advancement/",
        "snippet": "## Relentless innovation in models, products and technologies\n\n2024 was a year of experimenting, fast shipping, and putting our latest technologies in the hands of developers.\n\nIn December 2024, we released the first models in our Gemini 2.0 experimental series — AI models designed for the agentic era. First out of the gate was Gemini 2.0 Flash, our workhorse model, followed by prototypes from the frontiers of our agentic research including: an updated Project Astra, which explores the capabilities of a universal AI assistant; Project Mariner, an early prototype capable of taking actions in Chrome as an experimental extension; and Jules, an AI-powered code agent. We're looking forward to bringing Gemini 2.0’s powerful capabilities to our flagship products — in Search, we've already started testing in AI Overviews, which are now used by over a billion people to ask new types of questions.\n\nWe also released Deep Research, a new agentic feature in Gemini Advanced that saves people hours of research work by creating and executing multi-step plans for finding answers to complicated questions; and introduced Gemini 2.0 Flash Thinking Experimental, an experimental model that explicitly shows its thoughts.\n\nThese advances followed swift progress earlier in the year, from incorporating Gemini's capabilities into more Google products to the release of Gemini 1.5 Pro and Gemini 1.5 Flash — a model optimized for speed and efficiency. 1.5 Flash's compact size made it more cost-efficient to serve, and in 2024 it became our most popular model for developers.... ## The architecture of intelligence: advances in robotics, hardware and computing\n\nAs our multimodal models become more capable and gain a better understanding of the world and its physics, they are making possible incredible new advances in robotics and bringing us closer to our goal of ever-more capable and helpful robots.\n\nWith ALOHA Unleashed, our robot learned to tie a shoelace, hang a shirt, repair another robot, insert a gear and even clean a kitchen.\n\nAt the beginning of the year, we introduced AutoRT, SARA-RT and RT-Trajectory, extensions of our Robotics Transformers work intended to help robots better understand and navigate their environments, and make decisions faster. We also published ALOHA Unleashed, a breakthrough in teaching robots on how to use two robotic arms in coordination, and DemoStart, which uses a reinforcement learning algorithm to improve real-world performance on a multi-fingered robotic hand by using simulations.\n\nRobotic Transformer 2 (RT-2) is a novel vision-language-action model that learns from both web and robotics data.\n\nBeyond robotics, our AlphaChip reinforcement learning method for accelerating and improving chip floorplanning is transforming the design process for chips found in data centers, smartphones and more. To accelerate adoption of these techniques, we released a pre-trained checkpoint to enable external parties to more easily make use of the AlphaChip open source release for their own chip designs. And we made Trillium, our sixth-generation and most performant TPU to date, generally available to Google Cloud customers. Advances in computer chips have accelerated AI. And now, AI can return the favor.... We are exploring how machine learning can help medical fields struggling with access to imaging expertise, such as radiology, dermatology and pathology. In the past year, we released two research tools, Derm Foundation and Path Foundation, that can help develop models for diagnostic tasks, image indexing and curation and biomarker discovery and validation. We collaborated with physicians at Stanford Medicine on an open-access, inclusive Skin Condition Image Network (SCIN) dataset. And we unveiled CT Foundation, a medical imaging embedding tool used for rapidly training models for research.\n\nWith regard to learning, we explored new generative AI tools to support educators and learners. We introduced LearnLM, our new family of models fine-tuned for learning and used it to enhance learning experiences in products like Search, YouTube and Gemini; a recent report showed LearnLM outperformed other leading AI models. We also made it available to developers as an experimental model in AI Studio. Our new conversational learning companion, LearnAbout, uses AI to help you dive deeper into any topic you're curious about, while Illuminate lets you turn content into engaging AI-generated audio discussions.\n\nIn the fields of disaster forecasting and preparedness, we announced several breakthroughs. We introduced GenCast, our new high-resolution AI ensemble model, which improves day-to-day weather and extreme events forecasting across all possible weather trajectories. We also introduced our NeuralGCM model, able to simulate over 70,000 days of the atmosphere in the time it would take a physics-based model to simulate only 19 days. And GraphCast won the 2024 MacRobert Award for engineering innovation.",
        "date": "2025-01-23",
        "last_updated": "2025-09-25"
      },
      {
        "title": "The 2025 AI Index Report | Stanford HAI",
        "url": "https://hai.stanford.edu/ai-index/2025-ai-index-report",
        "snippet": "Read the translation\n\nIn 2023, researchers introduced new benchmarks—MMMU, GPQA, and SWE-bench—to test the limits of advanced AI systems. Just a year later, performance sharply increased: scores rose by 18.8, 48.9, and 67.3 percentage points on MMMU, GPQA, and SWE-bench, respectively. Beyond benchmarks, AI systems made major strides in generating high-quality video, and in some settings, language model agents even outperformed humans in programming tasks with limited time budgets.\n\nFrom healthcare to transportation, AI is rapidly moving from the lab to daily life. In 2023, the FDA approved 223 AI-enabled medical devices, up from just six in 2015. On the roads, self-driving cars are no longer experimental: Waymo, one of the largest U.S. operators, provides over 150,000 autonomous rides each week, while Baidu's affordable Apollo Go robotaxi fleet now serves numerous cities across China.\n\nIn 2024, U.S. private AI investment grew to $109.1 billion—nearly 12 times China's $9.3 billion and 24 times the U.K.'s $4.5 billion. Generative AI saw particularly strong momentum, attracting $33.9 billion globally in private investment—an 18.7% increase from 2023. AI business usage is also accelerating: 78% of organizations reported using AI in 2024, up from 55% the year before. Meanwhile, a growing body of research confirms that AI boosts productivity and, in most cases, helps narrow skill gaps across the workforce.... In 2024, U.S.-based institutions produced 40 notable AI models, significantly outpacing China's 15 and Europe's three. While the U.S. maintains its lead in quantity, Chinese models have rapidly closed the quality gap: performance differences on major benchmarks such as MMLU and HumanEval shrank from double digits in 2023 to near parity in 2024. Meanwhile, China continues to lead in AI publications and patents. At the same time, model development is increasingly global, with notable launches from regions such as the Middle East, Latin America, and Southeast Asia.\n\nAI-related incidents are rising sharply, yet standardized RAI evaluations remain rare among major industrial model developers. However, new benchmarks like HELM Safety, AIR-Bench, and FACTS offer promising tools for assessing factuality and safety. Among companies, a gap persists between recognizing RAI risks and taking meaningful action. In contrast, governments are showing increased urgency: In 2024, global cooperation on AI governance intensified, with organizations including the OECD, EU, U.N., and African Union releasing frameworks focused on transparency, trustworthiness, and other core responsible AI principles.\n\nIn countries like China (83%), Indonesia (80%), and Thailand (77%), strong majorities see AI products and services as more beneficial than harmful. In contrast, optimism remains far lower in places like Canada (40%), the United States (39%), and the Netherlands (36%). Still, sentiment is shifting: since 2022, optimism has grown significantly in several previously skeptical countries—including Germany (+10%), France (+10%), Canada (+8%), Great Britain (+8%), and the United States (+4%).... Driven by increasingly capable small models, the inference cost for a system performing at the level of GPT-3.5 dropped over 280-fold between November 2022 and October 2024. At the hardware level, costs have declined by 30% annually, while energy efficiency has improved by 40% each year. Open-weight models are also closing the gap with closed models, reducing the performance difference from 8% to just 1.7% on some benchmarks in a single year. Together, these trends are rapidly lowering the barriers to advanced AI.\n\nIn 2024, U.S. federal agencies introduced 59 AI-related regulations—more than double the number in 2023—and issued by twice as many agencies. Globally, legislative mentions of AI rose 21.3% across 75 countries since 2023, marking a ninefold increase since 2016. Alongside growing attention, governments are investing at scale: Canada pledged $2.4 billion, China launched a $47.5 billion semiconductor fund, France committed €109 billion, India pledged $1.25 billion, and Saudi Arabia's Project Transcendence represents a $100 billion initiative.\n\nTwo-thirds of countries now offer or plan to offer K–12 CS education—twice as many as in 2019—with Africa and Latin America making the most progress. In the U.S., the number of graduates with bachelor's degrees in computing has increased 22% over the last 10 years. Yet access remains limited in many African countries due to basic infrastructure gaps like electricity. In the U.S., 81% of K–12 CS teachers say AI should be part of foundational CS education, but less than half feel equipped to teach it.",
        "date": "2024-09-10",
        "last_updated": "2025-09-25"
      }
    ],
    "id": "e38104d5-6bd7-4d82-bc4e-0a21179d1f77"
  }
  ```
</Accordion>

<Info>
  The `max_results` parameter accepts values from 1 to 20, with a default maximum of 10 results per search. See [pricing](/docs/getting-started/pricing) for details on search costs.
</Info>

## Regional Web Search

You can refine your search results by specifying a country to get more geographically relevant results:

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity

  client = Perplexity()

  # Search for results from a specific country
  search = client.search.create(
      query="government policies on renewable energy",
      country="US",  # ISO country code
      max_results=5
  )

  for result in search.results:
      print(f"{result.title}: {result.url}")
  ```

  ```typescript Typescript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  // Search for results from a specific country
  const search = await client.search.create({
      query: "government policies on renewable energy",
      country: "US", // ISO country code
      max_results: 5
  });

  for (const result of search.results) {
      console.log(`${result.title}: ${result.url}`);
  }
  ```

  ```bash cURL theme={null}
  curl -X POST 'https://api.perplexity.ai/search' \
    -H 'Authorization: Bearer $PERPLEXITY_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
      "query": "government policies on renewable energy",
      "country": "US",
      "max_results": 5
    }' | jq
  ```
</CodeGroup>

<Tip>
  Use ISO 3166-1 alpha-2 country codes (e.g., "US", "GB", "DE", "JP") to target specific regions. This is particularly useful for queries about local news, regulations, or region-specific information.
</Tip>

## Multi-Query Web Search

Execute multiple related queries in a single request for comprehensive research:

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity

  client = Perplexity()

  search = client.search.create(
      query=[
          "artificial intelligence trends 2024",
          "machine learning breakthroughs recent",
          "AI applications in healthcare"
      ],
      max_results=5
  )

  # Access results
  for result in search.results:
      print(f"  {result.title}: {result.url}")
  ```

  ```typescript Typescript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  const search = await client.search.create({
      query: [
          "artificial intelligence trends 2024",
          "machine learning breakthroughs recent", 
          "AI applications in healthcare"
      ],
      max_results: 5
  });

  // Access results
  search.results.forEach(result => {
      console.log(`  ${result.title}: ${result.url}`);
  });
  ```

  ```bash cURL theme={null}
  curl -X POST 'https://api.perplexity.ai/search' \
    -H 'Authorization: Bearer $PERPLEXITY_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
      "query": [
        "artificial intelligence trends 2024",
        "machine learning breakthroughs recent",
        "AI applications in healthcare"
      ],
      "max_results": 5
    }' | jq
  ```
</CodeGroup>

<Tip>
  Multi-query search is ideal for research tasks where you need to explore different angles of a topic. Each query is processed independently, giving you comprehensive coverage.
</Tip>

<Info>
  For single queries, `search.results` is a flat list. For multi-query requests, results are grouped per query in the same order.
</Info>

<Info>
  You can include up to 5 queries in a single multi-query request for efficient batch processing.
</Info>

## Domain Filtering for Search Results

The `search_domain_filter` parameter allows you to limit search results to specific domains (allowlist) or exclude certain domains (denylist) for focused research. The filter works in two modes:

* **Allowlist mode**: Include only specified domains (no `-` prefix)
* **Denylist mode**: Exclude specified domains (use `-` prefix)

**Note**: You can use either allowlist or denylist mode, but not both simultaneously in the same request.

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity

  client = Perplexity()

  search = client.search.create(
      query="climate change research",
      search_domain_filter=[
          "science.org",
          "pnas.org",
          "cell.com"
      ],
      max_results=10
  )

  for result in search.results:
      print(f"{result.title}: {result.url}")
      print(f"Published: {result.date}")
      print("---")
  ```

  ```typescript Typescript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  const search = await client.search.create({
      query: "climate change research",
      search_domain_filter: [
          "science.org",
          "pnas.org",
          "cell.com"
      ],
      max_results: 10
  });

  for (const result of search.results) {
      console.log(`${result.title}: ${result.url}`);
      console.log(`Published: ${result.date}`);
      console.log("---");
  }
  ```

  ```javascript JavaScript theme={null}
  const Perplexity = require('@perplexity-ai/perplexity_ai');

  const client = new Perplexity();

  async function main() {
      const search = await client.search.create({
          query: "climate change research",
          search_domain_filter: [
              "science.org",
              "pnas.org",
              "cell.com"
          ],
          max_results: 10
      });

      for (const result of search.results) {
          console.log(`${result.title}: ${result.url}`);
          console.log(`Published: ${result.date}`);
          console.log("---");
      }
  }

  main();
  ```

  ```bash cURL theme={null}
  curl -X POST 'https://api.perplexity.ai/search' \
    -H 'Authorization: Bearer $PERPLEXITY_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
      "query": "climate change research",
      "search_domain_filter": [
        "science.org",
        "pnas.org",
        "cell.com"
      ],
      "max_results": 10
    }' | jq
  ```
</CodeGroup>

<Warning>
  You can add a maximum of 20 domains to the `search_domain_filter` list. The filter works in either allowlist mode (include only) or denylist mode (exclude), but not both simultaneously. See the [domain filter guide](/docs/search/filters/domain-filter) for advanced usage patterns.
</Warning>

### Denylisting Example

You can also exclude specific domains from search results:

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity

  client = Perplexity()

  # Exclude social media sites from search results
  search = client.search.create(
      query="renewable energy innovations",
      search_domain_filter=[
          "-pinterest.com",
          "-reddit.com",
          "-quora.com"
      ],
      max_results=10
  )

  for result in search.results:
      print(f"{result.title}: {result.url}")
  ```

  ```typescript Typescript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  // Exclude social media sites from search results
  const search = await client.search.create({
      query: "renewable energy innovations",
      search_domain_filter: [
          "-pinterest.com",
          "-reddit.com",
          "-quora.com"
      ],
      max_results: 10
  });

  for (const result of search.results) {
      console.log(`${result.title}: ${result.url}`);
  }
  ```

  ```bash cURL theme={null}
  curl -X POST 'https://api.perplexity.ai/search' \
    -H 'Authorization: Bearer $PERPLEXITY_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
      "query": "renewable energy innovations",
      "search_domain_filter": [
        "-pinterest.com",
        "-reddit.com",
        "-quora.com"
      ],
      "max_results": 10
    }' | jq
  ```
</CodeGroup>

## Language Filtering for Web Search

The `search_language_filter` parameter allows you to filter search results by language using ISO 639-1 language codes:

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity

  client = Perplexity()

  # Search for English, French, and German language results
  search = client.search.create(
      query="latest AI news",
      search_language_filter=["en", "fr", "de"],
      max_results=10
  )

  for result in search.results:
      print(f"{result.title}: {result.url}")
  ```

  ```typescript Typescript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  // Search for English, French, and German language results
  const search = await client.search.create({
      query: "latest AI news",
      search_language_filter: ["en", "fr", "de"],
      max_results: 10
  });

  for (const result of search.results) {
      console.log(`${result.title}: ${result.url}`);
  }
  ```

  ```javascript JavaScript theme={null}
  const Perplexity = require('@perplexity-ai/perplexity_ai');

  const client = new Perplexity();

  async function main() {
      // Search for English, French, and German language results
      const search = await client.search.create({
          query: "latest AI news",
          search_language_filter: ["en", "fr", "de"],
          max_results: 10
      });

      for (const result of search.results) {
          console.log(`${result.title}: ${result.url}`);
      }
  }

  main();
  ```

  ```bash cURL theme={null}
  curl -X POST 'https://api.perplexity.ai/search' \
    -H 'Authorization: Bearer $PERPLEXITY_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
      "query": "latest AI news",
      "search_language_filter": ["en", "fr", "de"],
      "max_results": 10
    }' | jq
  ```
</CodeGroup>

<Warning>
  Language codes must be valid 2-letter ISO 639-1 codes (e.g., "en", "ru", "fr"). You can add a maximum of 10 language codes per request. See the [language filter guide](/docs/search/filters/language-filter) for the complete list of supported codes.
</Warning>

## Content Extraction Control

The `max_tokens_per_page` parameter controls how much content is extracted from each webpage during search processing. This allows you to balance between comprehensive content coverage and processing efficiency.

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity

  client = Perplexity()

  # Extract more content for comprehensive analysis
  detailed_search = client.search.create(
      query="artificial intelligence research methodology",
      max_results=5,
      max_tokens_per_page=4096
  )

  # Use default extraction for faster processing
  quick_search = client.search.create(
      query="AI news headlines",
      max_results=10,
      max_tokens_per_page=512
  )

  for result in detailed_search.results:
      print(f"{result.title}: {result.snippet[:100]}...")
  ```

  ```typescript Typescript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  // Extract more content for comprehensive analysis
  const detailedSearch = await client.search.create({
      query: "artificial intelligence research methodology",
      max_results: 5,
      max_tokens_per_page: 4096
  });

  // Use default extraction for faster processing
  const quickSearch = await client.search.create({
      query: "AI news headlines",
      max_results: 3,
      max_tokens_per_page: 512
  });

  for (const result of detailedSearch.results) {
      console.log(`${result.title}: ${result.snippet.substring(0, 100)}...`);
  }
  ```

  ```bash cURL theme={null}
  # Comprehensive content extraction
  curl -X POST 'https://api.perplexity.ai/search' \
    -H 'Authorization: Bearer $PERPLEXITY_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
      "query": "artificial intelligence research methodology",
      "max_results": 5,
      "max_tokens_per_page": 4096
    }' | jq

  # Lighter content extraction
  curl -X POST 'https://api.perplexity.ai/search' \
    -H 'Authorization: Bearer $PERPLEXITY_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
      "query": "AI news headlines",
      "max_results": 3,
      "max_tokens_per_page": 512
    }' | jq
  ```
</CodeGroup>

<Info>
  The `max_tokens_per_page` parameter defaults to 4096 tokens. Higher values provide more comprehensive content extraction but may increase processing time. Lower values enable faster processing with more focused content.
</Info>

<Tip>
  Use lower `max_tokens_per_page` values (256-512) for quick information retrieval or when processing large result sets.
</Tip>

## Total Content Budget Control

The `max_tokens` parameter sets the maximum total tokens of webpage content returned across all search results. This controls how much content appears in the `snippet` fields. Use it together with `max_tokens_per_page` to control content distribution across results.
The `max_tokens` parameter defaults to 10,000 tokens. The maximum allowed value is 1,000,000 tokens.

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity

  client = Perplexity()

  # Higher token budget = more content in snippets
  detailed_search = client.search.create(
      query="renewable energy technologies",
      max_results=10,
      max_tokens=50000,  # Total content budget across all results
      max_tokens_per_page=4096  # Per-result limit
  )

  # Lower token budget = shorter snippets
  brief_search = client.search.create(
      query="latest stock market news",
      max_results=5,
      max_tokens=5000
  )

  for result in detailed_search.results:
      print(f"{result.title}: {len(result.snippet)} chars")
  ```

  ```typescript Typescript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  // Higher token budget = more content in snippets
  const detailedSearch = await client.search.create({
      query: "renewable energy technologies",
      max_results: 10,
      max_tokens: 50000,  // Total content budget across all results
      max_tokens_per_page: 4096  // Per-result limit
  });

  // Lower token budget = shorter snippets
  const briefSearch = await client.search.create({
      query: "latest stock market news",
      max_results: 5,
      max_tokens: 5000
  });

  for (const result of detailedSearch.results) {
      console.log(`${result.title}: ${result.snippet.length} chars`);
  }
  ```

  ```bash cURL theme={null}
  # Higher token budget for detailed content
  curl -X POST 'https://api.perplexity.ai/search' \
    -H 'Authorization: Bearer $PERPLEXITY_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
      "query": "renewable energy technologies",
      "max_results": 10,
      "max_tokens": 50000,
      "max_tokens_per_page": 4096
    }' | jq

  # Lower token budget for brief snippets
  curl -X POST 'https://api.perplexity.ai/search' \
    -H 'Authorization: Bearer $PERPLEXITY_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
      "query": "latest stock market news",
      "max_results": 5,
      "max_tokens": 5000
    }' | jq
  ```
</CodeGroup>

<Info>
  Search API charges per request only, with no additional token-based pricing.
</Info>

<Tip>
  **When to adjust each parameter:**

  * `max_tokens` controls the total content returned across all results—increase for longer snippets
  * `max_tokens_per_page` controls content per individual result—increase to get more from each page
  * Both parameters work together: `max_tokens` is the total budget, `max_tokens_per_page` is the per-result cap
</Tip>

## Next Steps

<Card title="Best Practices" icon="star" href="/docs/search/best-practices">
  Optimize your queries and implement async patterns
</Card>

## Explore More

<CardGroup>
  <Card title="API Reference" icon="book" href="/api-reference/search-post">
    Complete API documentation for the Perplexity Search API
  </Card>

  <Card title="Perplexity SDK" icon="code-circle" href="/docs/sdk/overview">
    Type-safe SDK for Python and Typescript
  </Card>

  <Card title="Date & Time Filters" icon="calendar" href="/docs/search/filters/date-time-filters">
    Filter search results by recency and date ranges
  </Card>

  <Card title="Domain Filtering Guide" icon="globe" href="/docs/search/filters/domain-filter">
    Advanced domain allowlist and denylist patterns
  </Card>

  <Card title="Agent API" icon="code-circle" href="/docs/agent-api/quickstart">
    Third-party models from OpenAI, Anthropic, Google, and more with presets and web search tools.
  </Card>

  <Card title="Sonar API" icon="message" href="/docs/sonar/quickstart">
    Get AI-generated summaries with built-in search capabilities.
  </Card>

  <Card title="Search Evals" icon="chart-bar" href="https://github.com/perplexityai/search_evals">
    Benchmark Perplexity Search against other web search APIs across multiple evaluation suites, and explore our latest results.
  </Card>
</CardGroup>


# Core Features
Source: https://docs.perplexity.ai/docs/sonar/features

Streaming and structured outputs for the Sonar API

## Overview

The Sonar API provides powerful features for building production-ready applications. This guide covers two core capabilities: streaming responses for real-time output and structured outputs for consistent data formats. For prompting guidance, see the [Prompt Guide](/docs/sonar/prompt-guide).

## Streaming Responses

Streaming allows you to receive partial responses from the Sonar API as they are generated, rather than waiting for the complete response. This is particularly useful for real-time user experiences, long responses, and interactive applications.

<Info>
  Streaming is supported across all Sonar models.
</Info>

### How Streaming Works

When streaming, you receive:

1. **Content chunks** which arrive progressively in real-time
2. **Search results** (delivered in the final chunk(s))
3. **Usage stats** and other metadata

<Warning>
  Search results and metadata are delivered in the **final chunk(s)** of a streaming response, not progressively during the stream.
</Warning>

### Example

```python theme={null}
from perplexity import Perplexity

client = Perplexity()

# Create streaming completion
stream = client.chat.completions.create(
    model="sonar",
    messages=[{"role": "user", "content": "What is the latest in AI research?"}],
    stream=True
)

# Process streaming response
content = ""
for chunk in stream:
    if chunk.choices[0].delta.content:
        content_piece = chunk.choices[0].delta.content
        content += content_piece
        print(content_piece, end="", flush=True)
    
    # Collect metadata from final chunks
    if hasattr(chunk, 'search_results') and chunk.search_results:
        search_results = chunk.search_results
    
    if hasattr(chunk, 'usage') and chunk.usage:
        usage_info = chunk.usage
```

## Structured Outputs

Structured outputs enable you to enforce specific response formats from Perplexity's models, ensuring consistent, machine-readable data that can be directly integrated into your applications without manual parsing.

We support **JSON Schema** structured outputs. To enable structured outputs, add a `response_format` field to your request with the following structure:

```json theme={null}
{
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "schema": { /* your JSON schema object */ }
    }
  }
}
```

<Tip>
  **Improve Schema Compliance**: Give the LLM hints about the output format in your prompts to improve adherence to the structured format. Include phrases like "Please return the data as a JSON object with the following structure..."
</Tip>

<Info>
  The first request with a new JSON Schema may incur a delay on the first token (typically 10-30 seconds) as the schema is prepared. Subsequent requests will not see this delay.
</Info>

### Example: Financial Analysis

```python theme={null}
from perplexity import Perplexity
from typing import List, Optional
from pydantic import BaseModel

class FinancialMetrics(BaseModel):
    company: str
    quarter: str
    revenue: float
    net_income: float
    eps: float
    revenue_growth_yoy: Optional[float] = None
    key_highlights: Optional[List[str]] = None

client = Perplexity()

completion = client.chat.completions.create(
    model="sonar-pro",
    messages=[
        {
            "role": "user",
            "content": "Analyze the latest quarterly earnings report for Apple Inc. Extract key financial metrics."
        }
    ],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "schema": FinancialMetrics.model_json_schema()
        }
    }
)

metrics = FinancialMetrics.model_validate_json(completion.choices[0].message.content)
print(f"Revenue: ${metrics.revenue}B")
```

<Warning>
  **Links in JSON Responses**: Requesting links as part of a JSON response may not always work reliably. Use the links returned in the `citations` or `search_results` fields from the API response instead.
</Warning>

## Next Steps

<CardGroup>
  <Card title="Sonar Prompt Guide" icon="book" href="/docs/sonar/prompt-guide">
    Sonar-specific prompting caveats and best practices.
  </Card>

  <Card title="Pro Search for Sonar Pro" icon="bolt" href="/docs/sonar/pro-search/quickstart">
    Enhanced search with automated tools, multi-step reasoning, and real-time thought streaming.
  </Card>

  <Card title="Sonar API Search Filters" icon="filter" href="/docs/sonar/filters">
    Learn how to control search behavior with filters and parameters.
  </Card>

  <Card title="Sonar API Media Attachments" icon="photo" href="/docs/sonar/media">
    Send and receive images, videos, and files with the Sonar API.
  </Card>
</CardGroup>


# Search Filters
Source: https://docs.perplexity.ai/docs/sonar/filters

Control and customize Sonar API search results with filters

Control which websites appear in search results, filter by date and location, target specific languages, and fine-tune search behavior using Sonar API filters.

## Domain Filters

Control which websites are included or excluded from search results using `search_domain_filter`. Supports both domain-level and URL-level filtering.

**Key parameters:**

* `search_domain_filter`: Array of domains or URLs (max 20)
* **Allowlist mode**: Include only specified domains (no prefix)
* **Denylist mode**: Exclude domains (prefix with `-`)

```python theme={null}
from perplexity import Perplexity

client = Perplexity()

# Allowlist: Only search specific domains
completion = client.chat.completions.create(
    model="sonar",
    messages=[{"role": "user", "content": "Tell me about space discoveries."}],
    search_domain_filter=["nasa.gov", "wikipedia.org", "space.com"]
)

# Denylist: Exclude specific domains
completion = client.chat.completions.create(
    model="sonar",
    messages=[{"role": "user", "content": "What are renewable energy advances?"}],
    search_domain_filter=["-reddit.com", "-pinterest.com"]
)
```

<Warning>
  You can add a maximum of 20 domains or URLs. Use either allowlist OR denylist mode, not both simultaneously.
</Warning>

## Date & Time Filters

Filter search results by publication date, last updated date, or recency using date range parameters.

**Key parameters:**

* `search_after_date_filter`: Filter by publication date (format: `%m/%d/%Y`)
* `search_before_date_filter`: Filter by publication date (format: `%m/%d/%Y`)
* `last_updated_after_filter`: Filter by last updated date
* `last_updated_before_filter`: Filter by last updated date
* `search_recency_filter`: Predefined periods (`"hour"`, `"day"`, `"week"`, `"month"`, `"year"`)

```python theme={null}
from perplexity import Perplexity

client = Perplexity()

# Publication date range
completion = client.chat.completions.create(
    model="sonar",
    messages=[{"role": "user", "content": "Show me tech news from this week."}],
    search_after_date_filter="3/1/2025",
    search_before_date_filter="3/5/2025"
)

# Last updated date range
completion = client.chat.completions.create(
    model="sonar-pro",
    messages=[{"role": "user", "content": "Show me recently updated articles."}],
    last_updated_after_filter="3/1/2025",
    last_updated_before_filter="3/5/2025"
)

# Recency filter for real-time results (breaking news or live events)
completion = client.chat.completions.create(
    model="sonar-pro",
    messages=[{"role": "user", "content": "What is happening right now in the markets?"}],
    search_recency_filter="hour"
)

# Recency filter (convenient relative dates)
completion = client.chat.completions.create(
    model="sonar-pro",
    messages=[{"role": "user", "content": "Latest AI developments?"}],
    search_recency_filter="week"
)
```

<Info>
  Date filters must use `%m/%d/%Y` format (e.g., `"3/1/2025"`). `search_recency_filter` cannot be combined with other date filters. Use `hour` for real-time data such as breaking news or live events.
</Info>

## Location Filters

Customize search results based on geographic location using `user_location` within `web_search_options`.

**Key parameters:**

* `country`: Two-letter ISO 3166 country code (required with coordinates)
* `region`: State, province, or administrative division
* `city`: City name
* `latitude`: Latitude coordinate (-90 to 90)
* `longitude`: Longitude coordinate (-180 to 180)

```python theme={null}
from perplexity import Perplexity

client = Perplexity()

# Full location specification (recommended)
completion = client.chat.completions.create(
    model="sonar-pro",
    messages=[{"role": "user", "content": "What are good coffee shops nearby?"}],
    web_search_options={
        "user_location": {
            "country": "US",
            "region": "California",
            "city": "San Francisco",
            "latitude": 37.7749,
            "longitude": -122.4194
        }
    }
)

# Country code only
completion = client.chat.completions.create(
    model="sonar-pro",
    messages=[{"role": "user", "content": "Summarize today's news."}],
    web_search_options={
        "user_location": {
            "country": "US"
        }
    }
)
```

<Tip>
  For best accuracy, provide as many location fields as possible. City and region significantly improve location precision.
</Tip>

## Language Filter

Filter search results by language using ISO 639-1 language codes.

**Key parameters:**

* `search_language_filter`: Array of 2-letter language codes (max 10)

```python theme={null}
from perplexity import Perplexity

client = Perplexity()

# Single language
completion = client.chat.completions.create(
    model="sonar",
    messages=[{"role": "user", "content": "Tell me about AI developments."}],
    search_language_filter=["en"]
)

# Multiple languages
completion = client.chat.completions.create(
    model="sonar-pro",
    messages=[{"role": "user", "content": "Renewable energy in Europe?"}],
    search_language_filter=["en", "fr", "de"]
)
```

<Info>
  Language codes must be valid ISO 639-1 codes (e.g., `"en"`, `"fr"`, `"de"`). You can filter by up to 10 languages per request.
</Info>

## Academic Filter

Prioritize scholarly sources and peer-reviewed content by setting `search_mode` to `"academic"`.

**Key parameters:**

* `search_mode`: Set to `"academic"` to target academic sources

```python theme={null}
from perplexity import Perplexity

client = Perplexity()

completion = client.chat.completions.create(
    model="sonar-pro",
    messages=[{"role": "user", "content": "What is the scientific name of lion's mane mushroom?"}],
    search_mode="academic",
    web_search_options={"search_context_size": "low"}
)
```

<Warning>
  Date filters are **not supported** with `search_mode="academic"` and are silently ignored. This includes `search_after_date_filter`, `search_before_date_filter`, `search_recency_filter`, `last_updated_after_filter`, and `last_updated_before_filter`. To narrow academic results by date, include the desired time range directly in your query text (e.g., "findings on neural networks since 2023").
</Warning>

## SEC Filings Filter

Target U.S. Securities and Exchange Commission filings and official financial documents.

**Key parameters:**

* `search_mode`: Set to `"sec"` to target SEC filings

```python theme={null}
from perplexity import Perplexity

client = Perplexity()

completion = client.chat.completions.create(
    model="sonar-pro",
    messages=[{"role": "user", "content": "Prepare me for markets opening."}],
    search_mode="sec"
)

# Combine with date filters for recent filings
completion = client.chat.completions.create(
    model="sonar",
    messages=[{"role": "user", "content": "Summarize latest 10-K filings for Apple Inc."}],
    search_mode="sec",
    search_after_date_filter="1/1/2023"
)
```

## Context Size Control

Control how much search context is retrieved to balance cost and comprehensiveness.

**Key parameters:**

* `search_context_size`: Set to `"low"` (default), `"medium"`, or `"high"` within `web_search_options`

```python theme={null}
from perplexity import Perplexity

client = Perplexity()

# Low context (cost-efficient, default)
completion = client.chat.completions.create(
    model="sonar",
    messages=[{"role": "user", "content": "How many stars in our galaxy?"}],
    web_search_options={"search_context_size": "low"}
)

# High context (comprehensive)
completion = client.chat.completions.create(
    model="sonar",
    messages=[{"role": "user", "content": "Explain the 2008 financial crisis."}],
    web_search_options={"search_context_size": "high"}
)
```

<Warning>
  Selecting `"high"` increases search costs due to more extensive web retrieval. Use `"low"` when cost efficiency is critical.
</Warning>

## Search Control

Control when web search is performed using the search classifier or by disabling search entirely.

**Key parameters:**

* `enable_search_classifier`: Let AI decide when to search (boolean)
* `disable_search`: Disable web search completely (boolean)

```python theme={null}
from perplexity import Perplexity

client = Perplexity()

# Search classifier (AI decides when to search)
completion = client.chat.completions.create(
    model="sonar-pro",
    messages=[{"role": "user", "content": "What are latest quantum computing developments?"}],
    enable_search_classifier=True
)

# Disable search completely
completion = client.chat.completions.create(
    model="sonar-pro",
    messages=[{"role": "user", "content": "What is 2 + 2?"}],
    disable_search=True
)
```

<Warning>
  Pricing remains the same regardless of whether search is triggered. Search control is for performance optimization, not cost reduction.
</Warning>

## Combining Filters

You can combine multiple filters for precise control over search results:

```python theme={null}
from perplexity import Perplexity

client = Perplexity()

# Combine domain, language, date, and context size filters
completion = client.chat.completions.create(
    model="sonar-pro",
    messages=[{"role": "user", "content": "Recent quantum computing breakthroughs?"}],
    search_domain_filter=["nature.com", "science.org", "arxiv.org"],
    search_language_filter=["en", "de"],
    search_recency_filter="month",
    web_search_options={"search_context_size": "high"}
)
```

## Next Steps

<Card title="Sonar Quickstart" icon="rocket" href="/docs/sonar/quickstart">
  Get started with the Sonar API and learn the basics
</Card>


# Media & Attachments
Source: https://docs.perplexity.ai/docs/sonar/media

Send and receive images, videos, and files with the Sonar API

## Overview

The Sonar API supports comprehensive media handling: send images and files for analysis, and receive images and videos in responses. This guide covers all media functionality in one place.

## Sending Images

Send images to the API for analysis using either base64 encoding or HTTPS URLs. Images are embedded in the `messages` array alongside text content.

<Warning>
  * Base64 images: Maximum 50 MB per image. Supported formats: PNG, JPEG, WEBP, GIF
  * HTTPS URLs: Must be publicly accessible and point directly to the image file
</Warning>

### Base64 Encoded Images

Use base64 encoding when you have the image file locally:

```python Python SDK theme={null}
from perplexity import Perplexity
import base64

client = Perplexity()

# Read and encode image as base64
with open("path/to/your/image.png", "rb") as image_file:
    base64_image = base64.b64encode(image_file.read()).decode("utf-8")
    image_data_uri = f"data:image/png;base64,{base64_image}"

# Analyze the image
completion = client.chat.completions.create(
    model="sonar-pro",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Can you describe this image?"},
                {"type": "image_url", "image_url": {"url": image_data_uri}}
            ]
        }
    ]
)
print(completion.choices[0].message.content)
```

### HTTPS URL Images

Reference images hosted online:

```python Python SDK theme={null}
from perplexity import Perplexity

client = Perplexity()

image_url = "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg"

completion = client.chat.completions.create(
    model="sonar-pro",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Can you describe the image at this URL?"},
                {"type": "image_url", "image_url": {"url": image_url}}
            ]
        }
    ]
)
print(completion.choices[0].message.content)
```

### Key Parameters

* **Image format**: Use `data:image/{format};base64,{content}` for base64 (e.g., `data:image/png;base64,...`)
* **Token pricing**: Images are tokenized as `(width × height) / 750` tokens, priced at input token rates
* **Supported formats**: PNG (`image/png`), JPEG (`image/jpeg`), WEBP (`image/webp`), GIF (`image/gif`)

## Sending Files

Upload documents (PDF, DOC, DOCX, TXT, RTF) for analysis using URLs or base64 encoding. Files can be provided as publicly accessible URLs or base64 encoded bytes without any prefix.

<Warning>
  Maximum file size is 50MB per file. Files larger than this limit will not be processed.
</Warning>

### Using a Public URL

```python Python SDK theme={null}
from perplexity import Perplexity

client = Perplexity()

completion = client.chat.completions.create(
    model="sonar-pro",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Summarize this document"},
                {
                    "type": "file_url",
                    "file_url": {"url": "https://example.com/document.pdf"}
                }
            ]
        }
    ]
)
print(completion.choices[0].message.content)
```

### Using Base64 Encoding

```python Python SDK theme={null}
from perplexity import Perplexity
import base64

client = Perplexity()

# Read and encode file (no prefix needed)
with open("document.pdf", "rb") as file:
    encoded_file = base64.b64encode(file.read()).decode('utf-8')

completion = client.chat.completions.create(
    model="sonar-pro",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Summarize this document"},
                {
                    "type": "file_url",
                    "file_url": {"url": encoded_file}  # Just base64 string, no prefix
                }
            ]
        }
    ]
)
print(completion.choices[0].message.content)
```

### Key Parameters

* **Supported formats**: PDF, DOC, DOCX, TXT, RTF
* **Base64 encoding**: Provide only the base64 string without `data:` prefix
* **File size limit**: 50MB per file, maximum 30 files per request
* **URL requirements**: Must be publicly accessible and return the file directly

## Receiving Images

Control which images are returned in API responses using `return_images`, `image_domain_filter`, and `image_format_filter` parameters.

<Info>
  The `return_images` feature is currently only available in the Sonar API.
</Info>

### Basic Image Returns

Enable image returns by setting `return_images: true`:

```python Python SDK theme={null}
from perplexity import Perplexity

client = Perplexity()

completion = client.chat.completions.create(
    model="sonar",
    return_images=True,
    messages=[
        {"role": "user", "content": "Show me images of Mount Everest"}
    ]
)
print(completion.choices[0].message.content)
```

### Filtering Image Domains

Control which image sources are included or excluded:

```python Python SDK theme={null}
from perplexity import Perplexity

client = Perplexity()

# Exclude specific domains (prefix with -)
completion = client.chat.completions.create(
    model="sonar",
    return_images=True,
    image_domain_filter=["-gettyimages.com", "-shutterstock.com"],
    messages=[
        {"role": "user", "content": "Show me nature photography"}
    ]
)

# Include only specific domains
completion = client.chat.completions.create(
    model="sonar",
    return_images=True,
    image_domain_filter=["wikimedia.org", "nasa.gov"],
    messages=[
        {"role": "user", "content": "Show me historical images"}
    ]
)
```

### Filtering Image Formats

Restrict results to specific file formats:

```python Python SDK theme={null}
from perplexity import Perplexity

client = Perplexity()

# Only return GIF images
completion = client.chat.completions.create(
    model="sonar",
    return_images=True,
    image_format_filter=["gif"],
    messages=[
        {"role": "user", "content": "Show me a funny cat gif"}
    ]
)

# Allow multiple formats
completion = client.chat.completions.create(
    model="sonar",
    return_images=True,
    image_format_filter=["jpeg", "png", "webp"],
    messages=[
        {"role": "user", "content": "Show me high-quality landscape images"}
    ]
)
```

### Key Parameters

* **`return_images`**: Set to `true` to enable image returns
* **`image_domain_filter`**: Array of domains (max 10 entries). Prefix with `-` to exclude (e.g., `-gettyimages.com`)
* **`image_format_filter`**: Array of lowercase file extensions (max 10 entries). Use `gif`, `jpeg`, `png`, `webp` (no dot prefix)
* **Limitations**: Maximum 30 images per response, filters only apply when `return_images: true`

## Receiving Videos

Enable video returns in responses using the `media_response.overrides.return_videos` parameter.

<Info>
  The `return_videos` feature is currently only available in the Sonar API.
</Info>

<Warning>
  Video returns may increase response size and processing time. Use this feature selectively for queries where video content adds significant value.
</Warning>

### Basic Video Returns

```python Python SDK theme={null}
from perplexity import Perplexity

client = Perplexity()

completion = client.chat.completions.create(
    model="sonar-pro",
    media_response={
        "overrides": {
            "return_videos": True
        }
    },
    messages=[
        {"role": "user", "content": "2024 Olympics highlights"}
    ]
)
print(completion.choices[0].message.content)
```

### Combining Videos with Images

You can request both videos and images in the same response:

```python Python SDK theme={null}
from perplexity import Perplexity

client = Perplexity()

completion = client.chat.completions.create(
    model="sonar-pro",
    return_images=True,
    media_response={
        "overrides": {
            "return_videos": True
        }
    },
    messages=[
        {"role": "user", "content": "Mars rover discoveries 2024"}
    ]
)
```

### Key Parameters

* **`media_response.overrides.return_videos`**: Set to `true` to enable video returns
* **Response format**: Videos appear in the `videos` array with `url`, `thumbnail_url`, and metadata
* **Performance**: Video-enabled requests may take longer to process and produce larger responses

## Best Practices

<Tip>
  **Image optimization**: Compress images before encoding to reduce payload size and token costs. Resize very large images before sending.

  **File preparation**: Ensure documents are text-based (not scanned images). For URLs, verify they return the file directly, not a preview page.

  **Filter strategy**: Start with broad filters and gradually refine based on result quality. Keep filter lists concise (≤10 entries) for best performance.
</Tip>

## Next Steps

<Card title="Sonar Quickstart" icon="rocket" href="/docs/sonar/quickstart">
  Get started with the Sonar API and learn the fundamentals
</Card>


# Models
Source: https://docs.perplexity.ai/docs/sonar/models



<div>
  <div>
    <div>
      <SonarLogo />

      <h1><span>Models</span></h1>
    </div>
  </div>

  <div>
    <div>
      <h3><span>Explore the Sonar range and compare models</span></h3>
    </div>
  </div>

  <Frame>
    <img alt="Sonar Range" />
  </Frame>

  <ModelOverviewCards />
</div>


# OpenAI SDK Compatibility
Source: https://docs.perplexity.ai/docs/sonar/openai-compatibility

Use OpenAI SDKs with the Sonar API by changing the base URL and API key

## Overview

Perplexity's Sonar API is fully compatible with OpenAI's Chat Completions format. You can use your existing OpenAI client libraries with the Sonar API by simply changing the base URL and providing your Perplexity API key.

<Info>
  **Endpoint Note:** Perplexity's canonical Sonar API endpoint is `POST /v1/sonar`. For OpenAI SDK compatibility, `POST /chat/completions` is also accepted as an alias. The OpenAI SDK automatically routes `client.chat.completions.create()` to `/chat/completions`, which Perplexity handles seamlessly. No SDK changes are needed beyond setting the base URL.
</Info>

<Tip>
  **We recommend using the [Perplexity SDK](/docs/sdk/overview)** for the best experience with full type safety, enhanced features, and preset support. Use OpenAI SDKs if you're already integrated and need drop-in compatibility.
</Tip>

## Quick Start

Use the OpenAI SDK with Perplexity's Sonar API:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    import os
    from openai import OpenAI

    client = OpenAI(
        api_key=os.environ.get("PERPLEXITY_API_KEY"),
        base_url="https://api.perplexity.ai"
    )

    completion = client.chat.completions.create(
        model="sonar-pro",
        messages=[
            {"role": "user", "content": "What breakthroughs in fusion energy have been announced this year?"}
        ]
    )

    print(completion.choices[0].message.content)
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    import OpenAI from 'openai';

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

    const completion = await client.chat.completions.create({
      model: "sonar-pro",
      messages: [
        { role: "user", content: "What breakthroughs in fusion energy have been announced this year?" }
      ]
    });

    console.log(completion.choices[0].message.content);
    ```
  </Tab>
</Tabs>

## Configuration

### Setting Up the OpenAI SDK

Configure OpenAI SDKs to work with Perplexity by setting the `base_url` to `https://api.perplexity.ai`:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    import os
    from openai import OpenAI

    client = OpenAI(
        api_key=os.environ.get("PERPLEXITY_API_KEY"),
        base_url="https://api.perplexity.ai"
    )
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    import OpenAI from 'openai';

    const client = new OpenAI({
      apiKey: process.env.PERPLEXITY_API_KEY,
      baseURL: "https://api.perplexity.ai"
    });
    ```
  </Tab>
</Tabs>

<Info>
  **Important**: Use `base_url="https://api.perplexity.ai"` for the Sonar API.
</Info>

## Basic Usage

Perplexity's Sonar API is fully compatible with OpenAI's Chat Completions interface.

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    import os
    from openai import OpenAI

    client = OpenAI(
        api_key=os.environ.get("PERPLEXITY_API_KEY"),
        base_url="https://api.perplexity.ai"
    )

    completion = client.chat.completions.create(
        model="sonar-pro",
        messages=[
            {"role": "user", "content": "What breakthroughs in fusion energy have been announced this year?"}
        ]
    )

    print(completion.choices[0].message.content)
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    import OpenAI from 'openai';

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

    const completion = await client.chat.completions.create({
      model: "sonar-pro",
      messages: [
        { role: "user", content: "What breakthroughs in fusion energy have been announced this year?" }
      ]
    });

    console.log(completion.choices[0].message.content);
    ```
  </Tab>
</Tabs>

## Streaming

Streaming works exactly like OpenAI's API:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    import os
    from openai import OpenAI

    client = OpenAI(
        api_key=os.environ.get("PERPLEXITY_API_KEY"),
        base_url="https://api.perplexity.ai"
    )

    stream = client.chat.completions.create(
        model="sonar-pro",
        messages=[
            {"role": "user", "content": "What breakthroughs in fusion energy have been announced this year?"}
        ],
        stream=True
    )

    for chunk in stream:
        if chunk.choices[0].delta.content:
            print(chunk.choices[0].delta.content, end="", flush=True)
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    import OpenAI from 'openai';

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

    const stream = await client.chat.completions.create({
      model: "sonar-pro",
      messages: [
        { role: "user", content: "What breakthroughs in fusion energy have been announced this year?" }
      ],
      stream: true
    });

    for await (const chunk of stream) {
      if (chunk.choices[0]?.delta?.content) {
        process.stdout.write(chunk.choices[0].delta.content);
      }
    }
    ```
  </Tab>
</Tabs>

## Perplexity-Specific Parameters

Add Perplexity-specific search parameters using `extra_body` (Python) or direct parameters (TypeScript):

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    import os
    from openai import OpenAI

    client = OpenAI(
        api_key=os.environ.get("PERPLEXITY_API_KEY"),
        base_url="https://api.perplexity.ai"
    )

    completion = client.chat.completions.create(
        model="sonar-pro",
        messages=[
            {"role": "user", "content": "Latest climate research findings"}
        ],
        extra_body={
            "search_domain_filter": ["nature.com", "science.org"],
            "search_recency_filter": "month"
        }
    )

    print(completion.choices[0].message.content)
    print(f"Sources: {len(completion.search_results)} articles found")
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    import OpenAI from 'openai';

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

    const completion = await client.chat.completions.create({
      model: "sonar-pro",
      messages: [
        { role: "user", content: "Latest climate research findings" }
      ],
      search_domain_filter: ["nature.com", "science.org"],
      search_recency_filter: "month"
    } as any);

    console.log(completion.choices[0].message.content);
    console.log(`Sources: ${(completion as any).search_results.length} articles found`);
    ```
  </Tab>
</Tabs>

## API Compatibility

### Standard OpenAI Parameters

These parameters work exactly the same as OpenAI's API:

* `model` - Model name (use Perplexity model names like `sonar-pro`)
* `messages` - Chat messages array
* `max_tokens` - Maximum tokens in response
* `stream` - Enable streaming responses
* `temperature` - Response randomness (0-2)
* `top_p` - Nucleus sampling parameter
* `response_format` - Response format specification

### Perplexity-Specific Parameters

Sonar API supports additional search and response parameters:

* `search_domain_filter` - Limit or exclude specific domains
* `search_recency_filter` - Filter by content recency ("day", "week", "month", "year")
* `return_images` - Include image URLs in response
* `return_related_questions` - Include related questions
* `search_mode` - "web" (default) or "academic" mode selector
* `enable_search_classifier` - Let AI decide when to search
* `disable_search` - Turn off web search completely

<Info>
  See [Sonar API Reference](/api-reference/sonar-post) for complete parameter details.
</Info>

## Endpoint Mapping

| Method                                    | Perplexity Endpoint    | OpenAI Equivalent              | Notes                                               |
| ----------------------------------------- | ---------------------- | ------------------------------ | --------------------------------------------------- |
| `client.chat.completions.create()`        | `POST /v1/sonar`       | `POST /chat/completions`       | Both paths accepted by Perplexity for compatibility |
| `client.async_.chat.completions.create()` | `POST /v1/async/sonar` | `POST /async/chat/completions` | Both paths accepted by Perplexity for compatibility |

<Info>
  When using the OpenAI SDK, `client.chat.completions.create()` sends requests to `/chat/completions`. Perplexity accepts this path as an alias for `/v1/sonar`, so no SDK configuration changes are needed beyond `base_url`.
</Info>

## Response Structure

Perplexity responses match OpenAI's format exactly, with additional fields:

### Standard OpenAI Fields

* `choices[0].message.content` - The AI-generated response
* `model` - The model name used
* `usage` - Token consumption details
* `id`, `created`, `object` - Standard response metadata

### Perplexity-Specific Fields

* `search_results` - Array of web sources with `title`, `url`, and `date`
* `citations` - Array of citation URLs referenced in the response

**Example Response:**

```json theme={null}
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "model": "sonar-pro",
  "created": 1234567890,
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "The latest developments in AI include..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 315,
    "total_tokens": 327
  },
  "search_results": [
    {
      "title": "Latest AI Developments",
      "url": "https://example.com/ai-news",
      "date": "2025-02-01"
    }
  ],
  "citations": [
    "https://example.com/ai-news"
  ]
}
```

## Best Practices

<Steps>
  <Step title="Use the correct base URL">
    Always use `https://api.perplexity.ai` for the Sonar API.

    ```python theme={null}
    client = OpenAI(
        api_key=os.environ.get("PERPLEXITY_API_KEY"),
        base_url="https://api.perplexity.ai"  # Correct
    )
    ```
  </Step>

  <Step title="Handle errors gracefully">
    Use the OpenAI SDK's error handling:

    ```python theme={null}
    import os
    from openai import OpenAI, APIError, RateLimitError

    client = OpenAI(
        api_key=os.environ.get("PERPLEXITY_API_KEY"),
        base_url="https://api.perplexity.ai"
    )

    try:
        completion = client.chat.completions.create(
            model="sonar-pro",
            messages=[{"role": "user", "content": "Hello"}]
        )
    except RateLimitError:
        print("Rate limit exceeded, please retry later")
    except APIError as e:
        print(f"API error: {e.message}")
    ```
  </Step>

  <Step title="Use streaming for better UX">
    Stream responses for real-time user experience:

    ```python theme={null}
    stream = client.chat.completions.create(
        model="sonar-pro",
        messages=[{"role": "user", "content": "Long query..."}],
        stream=True
    )

    for chunk in stream:
        if chunk.choices[0].delta.content:
            print(chunk.choices[0].delta.content, end="", flush=True)
    ```
  </Step>

  <Step title="Access search results">
    Use the `search_results` field to get accurate source URLs:

    ```python theme={null}
    completion = client.chat.completions.create(
        model="sonar-pro",
        messages=[{"role": "user", "content": "Latest AI news"}]
    )

    # Access search results
    for result in completion.search_results:
        print(f"{result['title']}: {result['url']}")
    ```
  </Step>
</Steps>

## Recommended: Perplexity SDK

We recommend using Perplexity's native SDKs for the best developer experience:

* **Type safety** - Full TypeScript/Python type definitions for all parameters
* **Enhanced features** - Direct access to all Perplexity-specific features
* **Better error messages** - Perplexity-specific error handling
* **Simpler setup** - No need to configure base URLs

See the [Perplexity SDK Guide](/docs/sdk/overview) for details.

## Next Steps

<CardGroup>
  <Card title="Sonar Quickstart" icon="rocket" href="/docs/sonar/quickstart">
    Get started with Sonar API using OpenAI SDKs.
  </Card>

  <Card title="Sonar API Features" icon="book" href="/docs/sonar/features">
    Learn best practices for prompting and using the Sonar API.
  </Card>

  <Card title="API Reference" icon="code-circle" href="/api-reference/sonar-post">
    View complete API documentation for the Sonar endpoint.
  </Card>

  <Card title="Search Filters" icon="search" href="/docs/sonar/filters#search-control">
    Learn how to control search behavior with filters and parameters.
  </Card>
</CardGroup>


# Pro Search Classifier
Source: https://docs.perplexity.ai/docs/sonar/pro-search/classifier

Optimize cost and performance with automatic query classification between Pro Search and Fast Search modes

## Overview

The Pro Search Classifier is an intelligent system that automatically determines whether a query requires the advanced multi-step tool usage of Pro Search or can be effectively answered with standard Fast Search. This optimization helps you balance performance needs with cost efficiency.

<Info>
  Instead of manually choosing between `"pro"` and `"fast"` search types, you can use `"auto"` to let the classifier make the optimal decision for each query.
</Info>

## How It Works

When you set `search_type: "auto"`, the classifier analyzes your query across multiple dimensions:

<Steps>
  <Step title="Query Complexity Analysis">
    The classifier evaluates:

    * Number of sub-questions or aspects
    * Requirement for comparative analysis
    * Need for multi-step reasoning
    * Complexity of information synthesis required

    ```json theme={null}
    {
      "web_search_options": {
        "search_type": "auto"  // Let the classifier decide
      }
    }
    ```
  </Step>

  <Step title="Classification Decision">
    Based on the analysis, the classifier routes the query to either:

    * **Pro Search** for complex, multi-faceted queries requiring multi-step tool usage
    * **Fast Search** for straightforward information retrieval

    The decision is transparent in the response metadata.
  </Step>

  <Step title="Execution">
    The selected search mode processes your query:

    * **Pro Search**: Uses built-in tools (web\_search, fetch\_url\_content) automatically
    * **Fast Search**: Performs optimized single-pass search and synthesis

    You receive the same high-quality response format regardless of which mode is used.
  </Step>
</Steps>

## Classification Patterns

### Queries Classified as Pro Search

Complex queries that benefit from multi-step tool usage are automatically routed to Pro Search:

<AccordionGroup>
  <Accordion title="Multi-Part Questions">
    **Example Query:**
    "What are the differences between React, Vue, and Angular in terms of performance, learning curve, and ecosystem? Which one should I choose for a large enterprise application?"

    **Why Pro Search:**

    * Requires information about three different frameworks
    * Needs comparative analysis across multiple dimensions
    * Involves gathering expert opinions and recommendations
    * Benefits from synthesis of diverse sources

    **Tool Usage:**

    * Multiple web searches for each framework
    * URL fetching for benchmark data and official documentation
  </Accordion>

  <Accordion title="Research Synthesis">
    **Example Query:**
    "Summarize the latest peer-reviewed research on the effectiveness of intermittent fasting for weight loss and metabolic health. Include sample sizes and study limitations."

    **Why Pro Search:**

    * Requires finding multiple research papers
    * Needs access to full paper content, not just abstracts
    * Involves extracting specific data (sample sizes, limitations)
    * Requires synthesis across multiple studies

    **Tool Usage:**

    * Web search for recent peer-reviewed papers
    * `fetch_url_content` to read full papers
    * Information extraction and synthesis
  </Accordion>

  <Accordion title="Time-Sensitive Complex Analysis">
    **Example Query:**
    "Analyze the stock market impact of the Federal Reserve's most recent interest rate decision, including effects on different sectors and expert predictions for the next quarter."

    **Why Pro Search:**

    * Requires very recent information
    * Needs multi-source verification
    * Involves sector-by-sector analysis
    * Benefits from expert opinion gathering

    **Tool Usage:**

    * Multiple targeted web searches
    * URL fetching for financial analysis reports
    * Synthesis of diverse expert opinions
  </Accordion>
</AccordionGroup>

### Queries Classified as Fast Search

Straightforward queries that don't require multi-step reasoning are efficiently handled by Fast Search:

<AccordionGroup>
  <Accordion title="Simple Factual Questions">
    **Example Query:**
    "What is the capital of France?"

    **Why Fast Search:**

    * Single, well-established fact
    * No calculation or analysis needed
    * Information readily available in search snippets

    **Processing:**

    * Single web search
    * Direct answer from search results
    * No need for multi-step reasoning
  </Accordion>

  <Accordion title="Straightforward Information Retrieval">
    **Example Query:**
    "What are the main features of the iPhone 15 Pro?"

    **Why Fast Search:**

    * Single product inquiry
    * Information available in product descriptions
    * No comparative analysis required
    * No calculations needed

    **Processing:**

    * Search for product specifications
    * Extract and list features
    * Synthesize from search results
  </Accordion>

  <Accordion title="Single-Topic Queries">
    **Example Query:**
    "Explain what machine learning is."

    **Why Fast Search:**

    * Single concept definition
    * No multi-part analysis required
    * Standard information readily available

    **Processing:**

    * Search for machine learning explanations
    * Synthesize clear definition
    * Provide context from reliable sources
  </Accordion>

  <Accordion title="Basic Definitional Requests">
    **Example Query:**
    "What does API stand for and what is it used for?"

    **Why Fast Search:**

    * Simple definition request
    * No complex analysis needed
    * Information readily available

    **Processing:**

    * Quick search for API definition
    * Explain acronym and basic usage
    * Provide clear, concise answer
  </Accordion>
</AccordionGroup>

## Cost Implications

Understanding the cost difference helps you optimize your API usage:

<div>
  <div>
    <h4>Classified as Pro Search</h4>

    <ul>
      <li>Complex multi-part questions</li>
      <li>Requests requiring calculation or analysis</li>
      <li>Comparative research across sources</li>
      <li>Time-sensitive information needs</li>
    </ul>

    <div>
      <span>Uses Pro Search billing rates</span>
    </div>
  </div>

  <div>
    <h4>Classified as Fast Search</h4>

    <ul>
      <li>Simple factual questions</li>
      <li>Straightforward information retrieval</li>
      <li>Single-topic queries</li>
      <li>Basic definitional requests</li>
    </ul>

    <div>
      <span>Uses standard Sonar Pro billing rates</span>
    </div>
  </div>
</div>

### Pricing Comparison

**Pro Search Rates:**

* Input: \$3 per 1M tokens
* Output: \$15 per 1M tokens
* Request fees: \$14-\$22 per 1,000 requests (based on context size)

**Fast Search Rates:**

* Input: \$3 per 1M tokens
* Output: \$15 per 1M tokens
* Request fees: \$6-\$14 per 1,000 requests (based on context size - same as standard Sonar Pro)

<Tip>
  The automatic classifier helps you save money by using Pro Search only when its advanced capabilities are truly needed, while still ensuring complex queries get full multi-step tool usage.
</Tip>

## Usage Examples

### Using Automatic Classification

<CodeGroup>
  ```python Python SDK theme={null}
  from perplexity import Perplexity

  client = Perplexity()
  # Let the classifier decide
  response = client.chat.completions.create(
      model="sonar-pro",
      messages=[
          {
              "role": "user",
              "content": "Compare the energy efficiency of Tesla Model 3, Chevrolet Bolt, and Nissan Leaf"
          }
      ],
      stream=True,
      web_search_options={
          "search_type": "auto"  # Automatic classification
      }
  )

  for chunk in response:
      if chunk.choices[0].delta.content:
          print(chunk.choices[0].delta.content, end="")
  ```

  ```typescript Typescript SDK theme={null}
  import { Perplexity } from '@perplexity-ai/sdk';

  const client = new Perplexity();

  // Let the classifier decide
  const response = await client.chat.completions.create({
    model: 'sonar-pro',
    messages: [
      {
        role: 'user',
        content: 'Compare the energy efficiency of Tesla Model 3, Chevrolet Bolt, and Nissan Leaf'
      }
    ],
    stream: true,
    web_search_options: {
      search_type: 'auto'  // Automatic classification
    }
  });

  for await (const chunk of response) {
    if (chunk.choices[0]?.delta?.content) {
      process.stdout.write(chunk.choices[0].delta.content);
    }
  }
  ```

  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.perplexity.ai/v1/sonar \
    --header "Authorization: Bearer $PERPLEXITY_API_KEY" \
    --header "Content-Type: application/json" \
    --data '{
      "model": "sonar-pro",
      "messages": [
        {
          "role": "user",
          "content": "Compare the energy efficiency of Tesla Model 3, Chevrolet Bolt, and Nissan Leaf"
        }
      ],
      "stream": true,
      "web_search_options": {
        "search_type": "auto"
      }
    }' --no-buffer
  ```
</CodeGroup>

### Manual Override

You can still manually specify the search type when you know what you need:

<Tabs>
  <Tab title="Force Pro Search">
    Use when you know you need multi-step tool usage:

    ```python theme={null}
    response = client.chat.completions.create(
        model="sonar-pro",
        messages=[{"role": "user", "content": "Your complex query"}],
        stream=True,
        web_search_options={
            "search_type": "pro"  # Force Pro Search
        }
    )
    ```

    **Use cases for manual Pro:**

    * You know the query needs multi-step reasoning
    * Previous auto-classification was Fast but you need deeper analysis
    * Critical queries where you want maximum capability
  </Tab>

  <Tab title="Force Fast Search">
    Use when you want to optimize for speed and cost:

    ```python theme={null}
    response = client.chat.completions.create(
        model="sonar-pro",
        messages=[{"role": "user", "content": "Your simple query"}],
        stream=True,
        web_search_options={
            "search_type": "fast"  # Force Fast Search (or omit - fast is default)
        }
    )
    ```

    **Use cases for manual Fast:**

    * Simple queries where Pro Search would be overkill
    * Cost-sensitive applications
    * When response speed is critical
  </Tab>
</Tabs>

## Best Practices

<Steps>
  <Step title="Default to automatic classification">
    For most applications, use `search_type: "auto"` and let the classifier optimize:

    ```python theme={null}
    web_search_options={"search_type": "auto"}
    ```

    This ensures the right tool for each query while optimizing costs.
  </Step>

  <Step title="Monitor classification patterns">
    Track which queries get classified as Pro vs Fast to understand your usage patterns:

    * Review queries that consistently use Pro Search
    * Identify opportunities to rephrase queries for Fast Search when appropriate
    * Understand which user questions require advanced capabilities

    This helps optimize your application's query design.
  </Step>

  <Step title="Use manual override strategically">
    Override the classifier only when:

    * You have specific performance requirements
    * Testing and comparing Pro vs Fast results
    * Building features with known complexity levels

    **Example:**

    ```python theme={null}
    # Known complex analysis - force Pro
    if query_requires_calculations(user_query):
        search_type = "pro"
    else:
        search_type = "auto"
    ```
  </Step>

  <Step title="Design queries effectively">
    Structure queries to help the classifier make optimal decisions:

    **Less optimal:**
    "Tell me about electric cars"

    **Better:**
    "What is the average range of electric vehicles?" (Fast Search appropriate)

    **Or:**
    "Compare the total cost of ownership over 5 years for Tesla Model 3, Chevrolet Bolt, and Nissan Leaf, including depreciation, electricity costs, and maintenance" (Pro Search appropriate)

    Clear, specific queries enable better classification.
  </Step>
</Steps>

## Classification Transparency

You can verify the classification decision in the response metadata:

```json theme={null}
{
  "id": "12345",
  "model": "sonar-pro",
  "search_metadata": {
    "search_type_used": "pro",  // or "fast"
    "classification_reason": "Multi-part comparative analysis with calculations"
  },
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 150,
    "total_tokens": 175
  }
}
```

<Info>
  This transparency helps you understand why queries were classified a certain way and optimize future queries.
</Info>

## When to Use Each Mode

<CardGroup>
  <Card title="Auto (Recommended)" icon="wand">
    **Best for:** Most applications

    Let the classifier optimize for you. Balances cost and capability automatically based on query complexity.
  </Card>

  <Card title="Manual Pro" icon="brain">
    **Best for:** Known complex tasks

    Use when you're certain multi-step tool usage is needed: calculations, multi-source synthesis, deep analysis.
  </Card>

  <Card title="Manual Fast" icon="bolt">
    **Best for:** Simple retrieval

    Use for straightforward facts, definitions, or when optimizing for speed and cost with simple queries.
  </Card>
</CardGroup>

## Common Questions

<AccordionGroup>
  <Accordion title="How accurate is the classifier?">
    The classifier is highly accurate, trained on thousands of query patterns. It errs on the side of using Pro Search when there's any ambiguity, ensuring you don't lose capability.

    However, if you notice consistent mis-classifications:

    * Rephrase queries to be more specific
    * Use manual override for those query types
    * Consider your use case's specific needs
  </Accordion>

  <Accordion title="Can I see which mode was used?">
    Yes, the response includes metadata showing:

    * Which search type was used
    * Why the classification was made (when using auto)
    * Cost breakdown by search type

    This helps you understand and optimize your usage patterns.
  </Accordion>

  <Accordion title="Does automatic classification add latency?">
    No. Classification happens in milliseconds before query processing begins and does not meaningfully impact response time. The classifier is optimized for real-time decision making.
  </Accordion>

  <Accordion title="What if I disagree with the classification?">
    You can always use manual override:

    ```python theme={null}
    web_search_options={"search_type": "pro"}  # Force your preference
    ```

    If you consistently disagree with classifications, consider:

    * Making queries more specific
    * Using manual override for those query types
    * Reviewing whether your use case needs consistent Pro or Fast mode
  </Accordion>
</AccordionGroup>

## Related Resources

<CardGroup>
  <Card title="Quickstart" icon="rocket" href="/docs/sonar/pro-search/quickstart">
    Get started with Pro Search basics
  </Card>

  <Card title="Built-in Tool Capabilities" icon="tool" href="/docs/sonar/pro-search/tools">
    Learn about Pro Search's built-in tools and capabilities
  </Card>

  <Card title="Pricing Guide" icon="currency-dollar" href="/docs/getting-started/pricing">
    Understand pricing for Pro and Fast Search
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/sonar-post">
    Complete API documentation
  </Card>
</CardGroup>


# Quickstart
Source: https://docs.perplexity.ai/docs/sonar/pro-search/quickstart

Get started with Pro Search for Sonar Pro - enhanced search with automated tools, multi-step reasoning, and real-time thought streaming

## Overview

Pro Search enhances [Sonar Pro](/docs/sonar/models/sonar-pro) with automated tool usage, enabling multi-step reasoning through intelligent tool orchestration including web search and URL content fetching.

<Warning>
  Pro Search only works when streaming is enabled. Non-streaming requests will fall back to standard Sonar Pro behavior.
</Warning>

<div>
  <div>
    <h3>Standard Sonar Pro</h3>

    <ul>
      <li>Single web search execution</li>
      <li>Fast response synthesis</li>
      <li>Fixed search strategy</li>
      <li>Static result processing</li>
    </ul>
  </div>

  <div>
    <h3>Pro Search for Sonar Pro</h3>

    <ul>
      <li>Multi-step reasoning with automated tools</li>
      <li>Dynamic tool execution</li>
      <li>Real-time thought streaming</li>
      <li>Adaptive research strategies</li>
    </ul>
  </div>
</div>

## Basic Usage

Enabling Pro Search requires setting `stream` to `true` and specifying `"search_type": "pro"` in your API request. The default search type is `"fast"` for regular Sonar Pro.

Here is an example of how to enable Pro Search with streaming:

<CodeGroup>
  ```python Python SDK theme={null}
  from perplexity import Perplexity

  client = Perplexity()

  messages = [
      {
          "role": "user", 
          "content": "Analyze the latest developments in quantum computing and their potential impact on cryptography. Include recent research findings and expert opinions."
      }
  ]

  response = client.chat.completions.create(
      model="sonar-pro",
      messages=messages,
      stream=True,
      web_search_options={
          "search_type": "pro"
      }
  )

  for chunk in response:
      if chunk.choices[0].delta.content:
          print(chunk.choices[0].delta.content, end="")
  ```

  ```typescript Typescript SDK theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  const response = await client.chat.completions.create({
    model: 'sonar-pro',
    messages: [
      {
        role: 'user',
        content: 'Analyze the latest developments in quantum computing and their potential impact on cryptography. Include recent research findings and expert opinions.'
      }
    ],
    stream: true,
    web_search_options: {
      search_type: 'pro'
    }
  });

  for await (const chunk of response) {
    if (chunk.choices[0]?.delta?.content) {
      process.stdout.write((chunk.choices[0]?.delta?.content ?? '') as string);
    }
  }
  ```

  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.perplexity.ai/v1/sonar \
    --header "Authorization: Bearer $PERPLEXITY_API_KEY" \
    --header "Content-Type: application/json" \
    --data '{
      "model": "sonar-pro",
      "messages": [
        {
          "role": "user",
          "content": "Analyze the latest developments in quantum computing and their potential impact on cryptography. Include recent research findings and expert opinions."
        }
      ],
      "stream": true,
      "web_search_options": {
        "search_type": "pro"
      }
    }' --no-buffer
  ```
</CodeGroup>

<Accordion title="Response">
  ```json theme={null}
  {
    "id": "2f16f4a0-e1d7-48c7-832f-8757b96ec221",
    "model": "sonar-pro", 
    "created": 1759957470,
    "usage": {
      "prompt_tokens": 15,
      "completion_tokens": 98,
      "total_tokens": 113,
      "search_context_size": "low",
      "cost": {
        "input_tokens_cost": 0.0,
        "output_tokens_cost": 0.001,
        "request_cost": 0.014,
        "total_cost": 0.015
      }
    },
    "search_results": [
      {
        "title": "Quantum Computing Breakthrough 2024",
        "url": "https://example.com/quantum-breakthrough",
        "date": "2024-03-15",
        "snippet": "Researchers at MIT have developed a new quantum error correction method...",
        "source": "web"
      }
    ],
    "reasoning_steps": [
      {
        "thought": "I need to search for recent quantum computing developments first.",
        "type": "web_search",
        "web_search": {
          "search_keywords": [
            "quantum computing developments 2024 cryptography impact",
            "post-quantum cryptography"
          ],
          "search_results": [
            {
              "title": "Quantum Computing Breakthrough 2024",
              "url": "https://example.com/quantum-breakthrough",
              "date": "2024-03-15",
              "last_updated": "2024-03-20",
              "snippet": "Researchers at MIT have developed a new quantum error correction method...",
              "source": "web"
            }
          ]
        }
      },
      {
        "thought": "Let me fetch detailed content from this research paper.",
        "type": "fetch_url_content", 
        "fetch_url_content": {
          "contents": [
            {
              "title": "Quantum Error Correction Paper",
              "url": "https://arxiv.org/abs/2024.quantum",
              "date": null,
              "last_updated": null,
              "snippet": "Abstract: This paper presents a novel approach to quantum error correction...",
              "source": "web"
            }
          ]
        }
      }
    ],
    "object": "chat.completion.chunk",
    "choices": [
      {
        "index": 0,
        "delta": {
          "role": "assistant",
          "content": "## Latest Quantum Computing Developments\n\nBased on my research and analysis..."
        }
      }
    ]
  }
  ```
</Accordion>

## Enabling Automatic Classification

Sonar Pro can be configured to automatically classify queries into Pro Search or Fast Search based on complexity. This is the recommended approach for most applications.

Set `search_type: "auto"` to let the system intelligently route queries based on complexity.

<CodeGroup>
  ```python Python SDK theme={null}
  from perplexity import Perplexity

  client = Perplexity()

  response = client.chat.completions.create(
      model="sonar-pro",
      messages=[
          {
              "role": "user",
              "content": "Compare the energy efficiency of Tesla Model 3, Chevrolet Bolt, and Nissan Leaf"
          }
      ],
      stream=True,
      web_search_options={
          "search_type": "auto"  # Automatic classification
      }
  )

  for chunk in response:
      if chunk.choices[0].delta.content:
          print(chunk.choices[0].delta.content, end="")
  ```

  ```typescript Typescript SDK theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  const response = await client.chat.completions.create({
    model: 'sonar-pro',
    messages: [
      {
        role: 'user',
        content: 'Compare the energy efficiency of Tesla Model 3, Chevrolet Bolt, and Nissan Leaf'
      }
    ],
    stream: true,
    web_search_options: {
      search_type: 'auto'  // Automatic classification
    }
  });

  for await (const chunk of response) {
    if (chunk.choices[0]?.delta?.content) {
      process.stdout.write((chunk.choices[0]?.delta?.content ?? '') as string);
    }
  }
  ```

  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.perplexity.ai/v1/sonar \
    --header "Authorization: Bearer $PERPLEXITY_API_KEY" \
    --header "Content-Type: application/json" \
    --data '{
      "model": "sonar-pro",
      "messages": [
        {
          "role": "user",
          "content": "Compare the energy efficiency of Tesla Model 3, Chevrolet Bolt, and Nissan Leaf"
        }
      ],
      "stream": true,
      "web_search_options": {
        "search_type": "auto"
      }
    }' --no-buffer
  ```
</CodeGroup>

#### How Classification Works

The classifier analyzes your query and automatically routes it to:

* **Pro Search** for complex queries requiring:
  * Multi-step reasoning or analysis
  * Comparative analysis across multiple sources
  * Deep research workflows

* **Fast Search** for straightforward queries like:
  * Simple fact lookups
  * Direct information retrieval
  * Basic question answering

#### Billing with Auto Classification

**You are billed based on which search type your query triggers:**

* If classified as **Pro Search**: \$14–\$22 per 1,000 requests (based on context size)
* If classified as **Fast Search**: \$6–\$14 per 1,000 requests (based on context size - same as standard Sonar Pro)

To see the full pricing details, see the <a href="/docs/sonar/pro-search/quickstart#pricing">Pricing</a> section.

<Tip>
  Automatic classification is recommended for most applications as it balances cost optimization with query performance. You get Pro Search capabilities when needed without overpaying for simple queries.
</Tip>

### Manually Specifying the Search Type

If needed, you can manually specify the search type. This is useful for specific use cases where you know the query requires Pro Search capabilities.

* **`"search_type": "pro"`**: Manually specify Pro Search for complex queries when you know multi-step tool usage is needed
* **`"search_type": "fast"`**: Manually specify Fast Search for simple queries to optimize speed and cost (this is also the default when `search_type` is omitted)

## Built-in Tool Capabilities

Pro Search provides access to two powerful built-in tools that the model can use automatically:

<CardGroup>
  <Card title="web_search" icon="search" href="/docs/sonar/pro-search/tools#web_search">
    Conduct targeted web searches with custom queries, filters, and search strategies based on the evolving research context.
  </Card>

  <Card title="fetch_url_content" icon="globe" href="/docs/sonar/pro-search/tools#fetch_url_content">
    Retrieve and analyze content from specific URLs to gather detailed information beyond search result snippets.
  </Card>
</CardGroup>

<Info>
  The model automatically decides which tools to use and when, creating dynamic research workflows tailored to each specific query. These are built-in tools called by the system. Custom tools cannot be registered. Learn more in the [Built-in Tool Capabilities](/docs/sonar/pro-search/tools) guide.
</Info>

## Additional Capabilities

Pro Search also provides access to advanced Sonar Pro features that enhance your development experience:

* **[Stream Mode Guide](/docs/sonar/pro-search/stream-mode)**: Control streaming response formats with concise or full mode for optimized bandwidth usage and enhanced reasoning visibility.

## Pricing

Pro Search pricing consists of token usage plus request fees that vary by search type and context size.

<div>
  <div>
    <h3>Token Usage (Same for All Search Types)</h3>

    <div>
      <div>
        <span>Input Tokens</span>
        <span>\$3 per 1M</span>
      </div>

      <div>
        <span>Output Tokens</span>
        <span>\$15 per 1M</span>
      </div>
    </div>
  </div>

  <div>
    <h3>Request Fees (per 1,000 requests)</h3>

    <div>
      <h4>Pro Search (Complex Queries)</h4>

      <div>
        <div>
          <span>High Context</span>
          <span>\$22</span>
        </div>

        <div>
          <span>Medium Context</span>
          <span>\$18</span>
        </div>

        <div>
          <span>Low Context</span>
          <span>\$14</span>
        </div>
      </div>
    </div>

    <div>
      <h4>Fast Search (Simple Queries)</h4>

      <div>
        <div>
          <span>High Context</span>
          <span>\$14</span>
        </div>

        <div>
          <span>Medium Context</span>
          <span>\$10</span>
        </div>

        <div>
          <span>Low Context</span>
          <span>\$6</span>
        </div>
      </div>
    </div>
  </div>
</div>

<Info>
  When using `search_type: "auto"`, you're billed at the Pro Search rate if your query is classified as complex, or the Fast Search rate if classified as simple. See the full pricing details <a href="/docs/getting-started/pricing">here</a>.
</Info>

## Next Steps

<CardGroup>
  <Card title="Pro Search Tools" icon="brain" href="/docs/sonar/pro-search/tools">
    Learn about the tools available to the model for Pro Search.
  </Card>

  <Card title="Pro Search Classifier" icon="brain" href="/docs/sonar/pro-search/classifier">
    Learn about the classifier that automatically determines whether a query requires Pro Search or Fast Search.
  </Card>

  <Card title="Pro Search Stream Mode" icon="bolt" href="/docs/sonar/pro-search/stream-mode">
    Learn about the streaming mode for Pro Search.
  </Card>

  <Card title="Agent API Quickstart" icon="rocket" href="/docs/agent-api/quickstart">
    Get started with the Agent API.
  </Card>
</CardGroup>


# Stream Mode: Concise vs Full
Source: https://docs.perplexity.ai/docs/sonar/pro-search/stream-mode

Learn how to use stream_mode to control streaming response formats and optimize your integration

## Overview

The `stream_mode` parameter gives you control over how streaming responses are formatted. Choose between two modes:

* **`full`** (default) - Traditional streaming format with complete message objects in each chunk
* **`concise`** - Optimized streaming format with reduced redundancy and enhanced reasoning visibility

<Info>
  The `concise` mode is designed to minimize bandwidth usage and provide better visibility into the model's reasoning process.
</Info>

## Quick Comparison

| Feature                 | Full Mode                                | Concise Mode                        |
| ----------------------- | ---------------------------------------- | ----------------------------------- |
| **Message aggregation** | Server-side (includes `choices.message`) | Client-side (delta only)            |
| **Chunk types**         | Single type (`chat.completion.chunk`)    | Multiple types for different stages |
| **Search results**      | Multiple times during stream             | Only in `done` chunks               |
| **Bandwidth**           | Higher (includes redundant data)         | Lower (optimized for efficiency)    |

## Using Concise Mode

Set `stream_mode: "concise"` when creating streaming completions:

<Tabs>
  <Tab title="Python SDK">
    ```python theme={null}
    from perplexity import Perplexity

    client = Perplexity()

    stream = client.chat.completions.create(
        model="sonar-pro",
        messages=[{"role": "user", "content": "What's the weather in Seattle?"}],
        stream=True,
        stream_mode="concise"
    )

    for chunk in stream:
        print(f"Chunk type: {chunk.object}")
        if chunk.choices and chunk.choices[0].delta.content:
            print(chunk.choices[0].delta.content, end="")
    ```
  </Tab>

  <Tab title="Typescript SDK">
    ```typescript theme={null}
    import Perplexity from '@perplexity-ai/perplexity_ai';

    const client = new Perplexity();

    const stream = await client.chat.completions.create({
      model: "sonar-pro",
      messages: [{ role: "user", content: "What's the weather in Seattle?" }],
      stream: true,
      stream_mode: "concise"
    });

    for await (const chunk of stream) {
      console.log(`Chunk type: ${chunk.object}`);
      if (chunk.choices[0]?.delta?.content) {
        process.stdout.write((chunk.choices[0]?.delta?.content ?? '') as string);
      }
    }
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST "https://api.perplexity.ai/v1/sonar" \
      -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "sonar-pro",
        "messages": [{"role": "user", "content": "What is the weather in Seattle?"}],
        "stream": true,
        "stream_mode": "concise"
      }'
    ```
  </Tab>
</Tabs>

## Understanding Chunk Types

In concise mode, you'll receive four different types of chunks during the stream:

### 1. `chat.reasoning`

Streamed during the reasoning stage, containing real-time reasoning steps and search operations.

<Tabs>
  <Tab title="Structure">
    ```json theme={null}
    {
      "id": "cfa38f9d-fdbc-4ac6-a5d2-a3010b6a33a6",
      "model": "sonar-pro",
      "created": 1759441590,
      "object": "chat.reasoning",
      "choices": [{
        "index": 0,
        "finish_reason": null,
        "message": {
          "role": "assistant",
          "content": ""
        },
        "delta": {
          "role": "assistant",
          "content": "",
          "reasoning_steps": [{
            "thought": "Searching the web for Seattle's current weather...",
            "type": "web_search",
            "web_search": {
              "search_results": [...],
              "search_keywords": ["Seattle current weather"]
            }
          }]
        }
      }],
      "type": "message"
    }
    ```
  </Tab>

  <Tab title="Python Handler">
    ```python theme={null}
    def handle_reasoning_chunk(chunk):
        """Process reasoning stage updates"""
        if chunk.object == "chat.reasoning":
            delta = chunk.choices[0].delta

            if hasattr(delta, 'reasoning_steps'):
                for step in delta.reasoning_steps:
                    print(f"\n[Reasoning] {step.thought}")

                    if step.type == "web_search":
                        keywords = step.web_search.search_keywords
                        print(f"[Search] Keywords: {', '.join(keywords)}")
    ```
  </Tab>

  <Tab title="Typescript Handler">
    ```typescript theme={null}
    function handleReasoningChunk(chunk: any) {
      if (chunk.object === "chat.reasoning") {
        const delta = chunk.choices[0].delta;

        if (delta.reasoning_steps) {
          for (const step of delta.reasoning_steps) {
            console.log(`\n[Reasoning] ${step.thought}`);

            if (step.type === "web_search") {
              const keywords = step.web_search.search_keywords;
              console.log(`[Search] Keywords: ${keywords.join(', ')}`);
            }
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

### 2. `chat.reasoning.done`

Marks the end of the reasoning stage and includes all search results (web, images, videos) and reasoning steps.

<Tabs>
  <Tab title="Structure">
    ```json theme={null}
    {
      "id": "3dd9d463-0fef-47e3-af70-92f9fcc4db1f",
      "model": "sonar-pro",
      "created": 1759459505,
      "object": "chat.reasoning.done",
      "usage": {
        "prompt_tokens": 6,
        "completion_tokens": 0,
        "total_tokens": 6,
        "search_context_size": "low"
      },
      "search_results": [...],
      "images": [...],
      "choices": [{
        "index": 0,
        "finish_reason": null,
        "message": {
          "role": "assistant",
          "content": "",
          "reasoning_steps": [...]
        },
        "delta": {
          "role": "assistant",
          "content": ""
        }
      }]
    }
    ```
  </Tab>

  <Tab title="Python Handler">
    ```python theme={null}
    def handle_reasoning_done(chunk):
        """Process end of reasoning stage"""
        if chunk.object == "chat.reasoning.done":
            print("\n[Reasoning Complete]")

            # Access all search results
            if hasattr(chunk, 'search_results'):
                print(f"Found {len(chunk.search_results)} sources")
                for result in chunk.search_results[:3]:
                    print(f"  • {result['title']}")

            # Access image results
            if hasattr(chunk, 'images'):
                print(f"Found {len(chunk.images)} images")

            # Partial usage stats available
            if hasattr(chunk, 'usage'):
                print(f"Tokens used so far: {chunk.usage.total_tokens}")
    ```
  </Tab>

  <Tab title="Typescript Handler">
    ```typescript theme={null}
    function handleReasoningDone(chunk: any) {
      if (chunk.object === "chat.reasoning.done") {
        console.log("\n[Reasoning Complete]");

        // Access all search results
        if (chunk.search_results) {
          console.log(`Found ${chunk.search_results.length} sources`);
          chunk.search_results.slice(0, 3).forEach((result: any) => {
            console.log(`  • ${result.title}`);
          });
        }

        // Access image results
        if (chunk.images) {
          console.log(`Found ${chunk.images.length} images`);
        }

        // Partial usage stats available
        if (chunk.usage) {
          console.log(`Tokens used so far: ${chunk.usage.total_tokens}`);
        }
      }
    }
    ```
  </Tab>
</Tabs>

### 3. `chat.completion.chunk`

Streamed during the response generation stage, containing the actual content being generated.

<Tabs>
  <Tab title="Structure">
    ```json theme={null}
    {
      "id": "cfa38f9d-fdbc-4ac6-a5d2-a3010b6a33a6",
      "model": "sonar-pro",
      "created": 1759441592,
      "object": "chat.completion.chunk",
      "choices": [{
        "index": 0,
        "finish_reason": null,
        "message": {
          "role": "assistant",
          "content": ""
        },
        "delta": {
          "role": "assistant",
          "content": " tonight"
        }
      }]
    }
    ```
  </Tab>

  <Tab title="Python Handler">
    ```python theme={null}
    def handle_completion_chunk(chunk):
        """Process content generation updates"""
        if chunk.object == "chat.completion.chunk":
            delta = chunk.choices[0].delta

            if hasattr(delta, 'content') and delta.content:
                # Stream content to user
                print(delta.content, end='', flush=True)
                return delta.content

        return ""
    ```
  </Tab>

  <Tab title="Typescript Handler">
    ```typescript theme={null}
    function handleCompletionChunk(chunk: any): string {
      if (chunk.object === "chat.completion.chunk") {
        const delta = chunk.choices[0]?.delta;

        if (delta?.content) {
          // Stream content to user
          process.stdout.write(delta.content);
          return delta.content;
        }
      }

      return "";
    }
    ```
  </Tab>
</Tabs>

### 4. `chat.completion.done`

Final chunk indicating the stream is complete, including final search results, usage statistics, and cost information.

<Tabs>
  <Tab title="Structure">
    ```json theme={null}
    {
      "id": "cfa38f9d-fdbc-4ac6-a5d2-a3010b6a33a6",
      "model": "sonar-pro",
      "created": 1759441595,
      "object": "chat.completion.done",
      "usage": {
        "prompt_tokens": 6,
        "completion_tokens": 238,
        "total_tokens": 244,
        "search_context_size": "low",
        "cost": {
          "input_tokens_cost": 0.0,
          "output_tokens_cost": 0.004,
          "request_cost": 0.006,
          "total_cost": 0.01
        }
      },
      "search_results": [...],
      "images": [...],
      "choices": [{
        "index": 0,
        "finish_reason": "stop",
        "message": {
          "role": "assistant",
          "content": "## Seattle Weather Forecast\n\nSeattle is experiencing...",
          "reasoning_steps": [...]
        },
        "delta": {
          "role": "assistant",
          "content": ""
        }
      }]
    }
    ```
  </Tab>

  <Tab title="Python Handler">
    ```python theme={null}
    def handle_completion_done(chunk):
        """Process stream completion"""
        if chunk.object == "chat.completion.done":
            print("\n\n[Stream Complete]")

            # Final aggregated message
            full_message = chunk.choices[0].message.content

            # Final search results
            if hasattr(chunk, 'search_results'):
                print(f"\nFinal sources: {len(chunk.search_results)}")

            # Complete usage and cost information
            if hasattr(chunk, 'usage'):
                usage = chunk.usage
                print(f"\nTokens: {usage.total_tokens}")

                if hasattr(usage, 'cost'):
                    print(f"Cost: ${usage.cost.total_cost:.4f}")

            return {
                'content': full_message,
                'search_results': getattr(chunk, 'search_results', []),
                'images': getattr(chunk, 'images', []),
                'usage': getattr(chunk, 'usage', None)
            }
    ```
  </Tab>

  <Tab title="Typescript Handler">
    ```typescript theme={null}
    function handleCompletionDone(chunk: any) {
      if (chunk.object === "chat.completion.done") {
        console.log("\n\n[Stream Complete]");

        // Final aggregated message
        const fullMessage = chunk.choices[0].message.content;

        // Final search results
        if (chunk.search_results) {
          console.log(`\nFinal sources: ${chunk.search_results.length}`);
        }

        // Complete usage and cost information
        if (chunk.usage) {
          console.log(`\nTokens: ${chunk.usage.total_tokens}`);

          if (chunk.usage.cost) {
            console.log(`Cost: $${chunk.usage.cost.total_cost.toFixed(4)}`);
          }
        }

        return {
          content: fullMessage,
          search_results: chunk.search_results || [],
          images: chunk.images || [],
          usage: chunk.usage || null
        };
      }
    }
    ```
  </Tab>
</Tabs>

## Complete Implementation Examples

### Full Concise Mode Handler

<Tabs>
  <Tab title="Python SDK">
    ```python theme={null}
    from perplexity import Perplexity

    class ConciseStreamHandler:
        def __init__(self):
            self.content = ""
            self.reasoning_steps = []
            self.search_results = []
            self.images = []
            self.usage = None

        def stream_query(self, query: str, model: str = "sonar-pro"):
            """Handle a complete concise streaming request"""
            client = Perplexity()

            stream = client.chat.completions.create(
                model=model,
                messages=[{"role": "user", "content": query}],
                stream=True,
                stream_mode="concise"
            )

            for chunk in stream:
                self.process_chunk(chunk)

            return self.get_result()

        def process_chunk(self, chunk):
            """Route chunk to appropriate handler"""
            chunk_type = chunk.object

            if chunk_type == "chat.reasoning":
                self.handle_reasoning(chunk)
            elif chunk_type == "chat.reasoning.done":
                self.handle_reasoning_done(chunk)
            elif chunk_type == "chat.completion.chunk":
                self.handle_content(chunk)
            elif chunk_type == "chat.completion.done":
                self.handle_done(chunk)

        def handle_reasoning(self, chunk):
            """Process reasoning updates"""
            delta = chunk.choices[0].delta

            if hasattr(delta, 'reasoning_steps'):
                for step in delta.reasoning_steps:
                    self.reasoning_steps.append(step)
                    print(f"💭 {step.thought}")

        def handle_reasoning_done(self, chunk):
            """Process end of reasoning"""
            if hasattr(chunk, 'search_results'):
                self.search_results = chunk.search_results
                print(f"\n🔍 Found {len(self.search_results)} sources")

            if hasattr(chunk, 'images'):
                self.images = chunk.images
                print(f"🖼️  Found {len(self.images)} images")

            print("\n📝 Generating response...\n")

        def handle_content(self, chunk):
            """Process content chunks"""
            delta = chunk.choices[0].delta

            if hasattr(delta, 'content') and delta.content:
                self.content += delta.content
                print(delta.content, end='', flush=True)

        def handle_done(self, chunk):
            """Process completion"""
            if hasattr(chunk, 'usage'):
                self.usage = chunk.usage
                print(f"\n\n✅ Complete | Tokens: {self.usage.total_tokens}")

                if hasattr(self.usage, 'cost'):
                    print(f"💰 Cost: ${self.usage.cost.total_cost:.4f}")

        def get_result(self):
            """Return complete result"""
            return {
                'content': self.content,
                'reasoning_steps': self.reasoning_steps,
                'search_results': self.search_results,
                'images': self.images,
                'usage': self.usage
            }

    # Usage
    handler = ConciseStreamHandler()
    result = handler.stream_query("What's the latest news in AI?")

    print(f"\n\nFinal content length: {len(result['content'])} characters")
    print(f"Sources used: {len(result['search_results'])}")
    ```
  </Tab>

  <Tab title="Typescript SDK">
    ```typescript theme={null}
    import Perplexity from '@perplexity-ai/perplexity_ai';

    interface StreamResult {
      content: string;
      reasoning_steps: any[];
      search_results: any[];
      images: any[];
      usage: any;
    }

    class ConciseStreamHandler {
      private content: string = "";
      private reasoning_steps: any[] = [];
      private search_results: any[] = [];
      private images: any[] = [];
      private usage: any = null;

      async streamQuery(query: string, model: string = "sonar-pro"): Promise<StreamResult> {
        const client = new Perplexity();

        const stream = await client.chat.completions.create({
          model,
          messages: [{ role: "user", content: query }],
          stream: true,
          stream_mode: "concise"
        });

        for await (const chunk of stream) {
          this.processChunk(chunk);
        }

        return this.getResult();
      }

      private processChunk(chunk: any) {
        const chunkType = chunk.object;

        switch (chunkType) {
          case "chat.reasoning":
            this.handleReasoning(chunk);
            break;
          case "chat.reasoning.done":
            this.handleReasoningDone(chunk);
            break;
          case "chat.completion.chunk":
            this.handleContent(chunk);
            break;
          case "chat.completion.done":
            this.handleDone(chunk);
            break;
        }
      }

      private handleReasoning(chunk: any) {
        const delta = chunk.choices[0].delta;

        if (delta.reasoning_steps) {
          for (const step of delta.reasoning_steps) {
            this.reasoning_steps.push(step);
            console.log(`💭 ${step.thought}`);
          }
        }
      }

      private handleReasoningDone(chunk: any) {
        if (chunk.search_results) {
          this.search_results = chunk.search_results;
          console.log(`\n🔍 Found ${this.search_results.length} sources`);
        }

        if (chunk.images) {
          this.images = chunk.images;
          console.log(`🖼️  Found ${this.images.length} images`);
        }

        console.log("\n📝 Generating response...\n");
      }

      private handleContent(chunk: any) {
        const delta = chunk.choices[0]?.delta;

        if (delta?.content) {
          this.content += delta.content;
          process.stdout.write(delta.content);
        }
      }

      private handleDone(chunk: any) {
        if (chunk.usage) {
          this.usage = chunk.usage;
          console.log(`\n\n✅ Complete | Tokens: ${this.usage.total_tokens}`);

          if (this.usage.cost) {
            console.log(`💰 Cost: $${this.usage.cost.total_cost.toFixed(4)}`);
          }
        }
      }

      private getResult(): StreamResult {
        return {
          content: this.content,
          reasoning_steps: this.reasoning_steps,
          search_results: this.search_results,
          images: this.images,
          usage: this.usage
        };
      }
    }

    // Usage
    const handler = new ConciseStreamHandler();
    const result = await handler.streamQuery("What's the latest news in AI?");

    console.log(`\n\nFinal content length: ${result.content.length} characters`);
    console.log(`Sources used: ${result.search_results.length}`);
    ```
  </Tab>

  <Tab title="Raw HTTP">
    ```python theme={null}
    import os
    import requests
    import json

    def stream_concise_mode(query: str):
        """Handle concise streaming with raw HTTP"""
        url = "https://api.perplexity.ai/v1/sonar"
        headers = {
            "Authorization": f"Bearer {os.environ.get('PERPLEXITY_API_KEY')}",
            "Content-Type": "application/json"
        }
        payload = {
            "model": "sonar-pro",
            "messages": [{"role": "user", "content": query}],
            "stream": True,
            "stream_mode": "concise"
        }

        response = requests.post(url, headers=headers, json=payload, stream=True)

        content = ""
        search_results = []
        usage = None

        for line in response.iter_lines():
            if line:
                line = line.decode('utf-8')
                if line.startswith('data: '):
                    data_str = line[6:]
                    if data_str == '[DONE]':
                        break

                    try:
                        chunk = json.loads(data_str)
                        chunk_type = chunk.get('object')

                        if chunk_type == 'chat.reasoning':
                            # Handle reasoning
                            delta = chunk['choices'][0]['delta']
                            if 'reasoning_steps' in delta:
                                for step in delta['reasoning_steps']:
                                    print(f"💭 {step['thought']}")

                        elif chunk_type == 'chat.reasoning.done':
                            # Handle reasoning completion
                            if 'search_results' in chunk:
                                search_results = chunk['search_results']
                                print(f"\n🔍 Found {len(search_results)} sources\n")

                        elif chunk_type == 'chat.completion.chunk':
                            # Handle content
                            delta = chunk['choices'][0]['delta']
                            if 'content' in delta and delta['content']:
                                content += delta['content']
                                print(delta['content'], end='', flush=True)

                        elif chunk_type == 'chat.completion.done':
                            # Handle completion
                            if 'usage' in chunk:
                                usage = chunk['usage']
                                print(f"\n\n✅ Tokens: {usage['total_tokens']}")

                    except json.JSONDecodeError:
                        continue

        return {
            'content': content,
            'search_results': search_results,
            'usage': usage
        }

    # Usage
    result = stream_concise_mode("What's the latest news in AI?")
    ```
  </Tab>
</Tabs>

## Best Practices

<Steps>
  <Step title="Aggregate content on the client side">
    In concise mode, `choices.message` is not incrementally updated. You must aggregate chunks yourself.

    ```python theme={null}
    # Track content yourself
    content = ""
    for chunk in stream:
        if chunk.object == "chat.completion.chunk":
            if chunk.choices[0].delta.content:
                content += chunk.choices[0].delta.content
    ```
  </Step>

  <Step title="Use reasoning steps for transparency">
    Display reasoning steps to users for better transparency and trust.

    ```python theme={null}
    def display_reasoning(step):
        """Show reasoning to users"""
        print(f"🔍 Searching for: {step.web_search.search_keywords}")
        print(f"💭 {step.thought}")
    ```
  </Step>

  <Step title="Handle search results from done chunks only">
    Search results and usage information only appear in `chat.reasoning.done` and `chat.completion.done` chunks.

    ```python theme={null}
    # Don't check for search_results in other chunk types
    if chunk.object in ["chat.reasoning.done", "chat.completion.done"]:
        if hasattr(chunk, 'search_results'):
            process_search_results(chunk.search_results)
    ```
  </Step>

  <Step title="Implement proper type checking">
    Use the `object` field to route chunks to appropriate handlers.

    ```python theme={null}
    chunk_handlers = {
        "chat.reasoning": handle_reasoning,
        "chat.reasoning.done": handle_reasoning_done,
        "chat.completion.chunk": handle_content,
        "chat.completion.done": handle_done
    }

    handler = chunk_handlers.get(chunk.object)
    if handler:
        handler(chunk)
    ```
  </Step>

  <Step title="Track cost from the final chunk">
    Cost information is only available in the `chat.completion.done` chunk.

    ```python theme={null}
    if chunk.object == "chat.completion.done":
        if hasattr(chunk.usage, 'cost'):
            total_cost = chunk.usage.cost.total_cost
            print(f"Request cost: ${total_cost:.4f}")
    ```
  </Step>
</Steps>

## Migration from Full Mode

If you're migrating from full mode to concise mode, here are the key changes:

<Tabs>
  <Tab title="Before (Full Mode)">
    ```python theme={null}
    from perplexity import Perplexity

    client = Perplexity()

    stream = client.chat.completions.create(
        model="sonar-pro",
        messages=[{"role": "user", "content": "What's the weather?"}],
        stream=True
        # stream_mode defaults to "full"
    )

    for chunk in stream:
        # All chunks are chat.completion.chunk
        if chunk.choices[0].delta.content:
            print(chunk.choices[0].delta.content, end="")

        # Search results may appear in multiple chunks
        if hasattr(chunk, 'search_results'):
            print(f"Sources: {len(chunk.search_results)}")
    ```
  </Tab>

  <Tab title="After (Concise Mode)">
    ```python theme={null}
    from perplexity import Perplexity

    client = Perplexity()

    stream = client.chat.completions.create(
        model="sonar-pro",
        messages=[{"role": "user", "content": "What's the weather?"}],
        stream=True,
        stream_mode="concise"  # Enable concise mode
    )

    for chunk in stream:
        # Multiple chunk types - route appropriately
        if chunk.object == "chat.reasoning":
            # New: Handle reasoning steps
            if chunk.choices[0].delta.reasoning_steps:
                print("Reasoning in progress...")

        elif chunk.object == "chat.reasoning.done":
            # New: Reasoning complete, search results available
            if hasattr(chunk, 'search_results'):
                print(f"Sources: {len(chunk.search_results)}")

        elif chunk.object == "chat.completion.chunk":
            # Content chunks (similar to full mode)
            if chunk.choices[0].delta.content:
                print(chunk.choices[0].delta.content, end="")

        elif chunk.object == "chat.completion.done":
            # Final chunk with complete metadata
            print(f"\nTotal tokens: {chunk.usage.total_tokens}")
    ```
  </Tab>
</Tabs>

## When to Use Each Mode

<CardGroup>
  <Card title="Use Full Mode" icon="clipboard-list">
    * Simple integrations where you want the SDK to handle aggregation
    * Backward compatibility with existing implementations
    * When you don't need reasoning visibility
  </Card>

  <Card title="Use Concise Mode" icon="bolt">
    * Production applications optimizing for bandwidth
    * Applications that need reasoning transparency
    * Real-time chat interfaces with reasoning display
    * Cost-sensitive applications
  </Card>
</CardGroup>

## Resources

* [Streaming Responses Guide](/docs/agent-api/output-control#streaming-responses) - General streaming documentation
* [Sonar API Guide](/docs/sonar/quickstart) - Complete Sonar API guide
* [API Reference - Sonar API](/api-reference/sonar-post) - API documentation


# Built-in Tool Capabilities
Source: https://docs.perplexity.ai/docs/sonar/pro-search/tools

Learn about Pro Search's built-in tools: web search and URL content fetching

## Overview

Pro Search provides two built-in tools that the model uses automatically to answer your queries. The model decides which tools to use and when, so no configuration is needed. These tools are called automatically by the system; custom tools cannot be registered.

<Info>
  All tool executions appear in the `reasoning_steps` array of streaming responses, giving you visibility into how the model researched your query.
</Info>

## web\_search

Conducts web searches to find current information, statistics, and expert opinions.

**Example in action:**

```json theme={null}
{
  "thought": "I need current data on EV market trends",
  "type": "web_search",
  "web_search": {
    "search_keywords": [
      "EV Statistics 2023-2024",
      "electric vehicle sales data",
      "global EV market trends"
    ],
    "search_results": [
      {
        "title": "Trends in electric cars",
        "url": "https://www.iea.org/reports/global-ev-outlook-2024/trends-in-electric-cars",
        "date": "2024-03-15",
        "last_updated": null,
        "snippet": "Electric car sales neared 14 million in 2023, 95% of which were in China, Europe and the United States...",
        "source": "web"
      }
    ]
  }
}
```

## fetch\_url\_content

Retrieves full content from specific URLs to access detailed information beyond search result snippets.

**Example in action:**

```json theme={null}
{
  "thought": "This research paper contains detailed methodology I need to review",
  "type": "fetch_url_content",
  "fetch_url_content": {
    "contents": [
      {
        "title": "Attention Is All You Need",
        "url": "https://arxiv.org/pdf/1706.03762",
        "date": null,
        "last_updated": null,
        "snippet": "The dominant sequence transduction models are based on complex recurrent or convolutional neural networks that include an encoder and a decoder...",
        "source": "web"
      }
    ]
  }
}
```

## Multi-Tool Workflows

The model automatically combines multiple tools when needed. For example, when asked to research solar panel options, it might:

1. Use `web_search` to find current incentives and costs
2. Use `fetch_url_content` to read detailed policy documents
3. Use `web_search` again to verify electricity rates and compare providers

## Related Resources

<CardGroup>
  <Card title="Quickstart" icon="rocket" href="/docs/sonar/pro-search/quickstart">
    Get started with Pro Search basics
  </Card>

  <Card title="Stream Mode Guide" icon="bolt" href="/docs/sonar/pro-search/stream-mode">
    Learn about streaming and real-time reasoning visibility
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/sonar-post">
    Complete API documentation
  </Card>
</CardGroup>


# Prompt Guide
Source: https://docs.perplexity.ai/docs/sonar/prompt-guide

Sonar-specific prompting guidance and how it differs from the Agent API.

The shared prompting best practices live in the [Agent API Prompt Guide](/docs/agent-api/prompt-guide) and apply to Sonar without modification — be specific, cap result counts, don't ask for URLs in prose, avoid few-shot content, and prefer parameters over prose for filters.

This page covers the one structural difference that changes how Sonar is prompted: the system prompt does not influence search.

<Info>
  For new applications, we recommend the [Agent API](/docs/agent-api/quickstart). The agent loop, custom tools, and richer prompt control make it the better default.
</Info>

## Shape Search Through the User Message

Sonar runs a web search before generating its answer, and only the user message is used to drive that search. The system prompt is not visible to search; it reaches the model only at answer time, when results are already in hand. Use the system prompt for tone, style, and grounding rules, but treat the user message as both the question for the model and the seed for the search.

The practical consequence: phrasing in the user message directly affects which sources show up. A specific, descriptive question produces better results than a vague one, and a polished system prompt cannot rescue a vague user message. If retrieval quality matters, invest there first.

**Good Example**: "What guidance has the FDA issued on AI in medical devices in the past year, and which device categories does it cover?"

**Poor Example**: "Tell me about FDA AI rules."

<Warning>
  Do not put search instructions in the system prompt. Phrases like "search only on Wikipedia" or "look for the latest results" have no effect. For hard constraints like domain, recency, or region, use the dedicated [search filter parameters](/docs/sonar/filters) on the request body rather than trying to express the constraint in prose.
</Warning>

<CodeGroup>
  ```python Python theme={null}
  from perplexity import Perplexity

  client = Perplexity()

  completion = client.chat.completions.create(
      model="sonar",
      messages=[
          {"role": "user", "content": "What guidance has the FDA issued on AI in medical devices in the past year?"}
      ],
      search_domain_filter=["fda.gov"],
      search_recency_filter="month"
  )

  print(completion.choices[0].message.content)
  ```

  ```typescript Typescript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  const completion = await client.chat.completions.create({
    model: "sonar",
    messages: [
      { role: "user", content: "What guidance has the FDA issued on AI in medical devices in the past year?" }
    ],
    search_domain_filter: ["fda.gov"],
    search_recency_filter: "month"
  });

  console.log(completion.choices[0].message.content);
  ```

  ```bash cURL theme={null}
  curl https://api.perplexity.ai/v1/sonar \
    -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "sonar",
      "messages": [
        {"role": "user", "content": "What guidance has the FDA issued on AI in medical devices in the past year?"}
      ],
      "search_domain_filter": ["fda.gov"],
      "search_recency_filter": "month"
    }' | jq
  ```
</CodeGroup>

This contrasts with the Agent API, where `instructions` are re-read on every turn of the agent loop and shape both tool calls and the final answer. In Sonar, `instructions` has no equivalent. System messages only influence generation, never retrieval.

## Reduce Hallucinations

LLMs are tuned to be helpful, which can occasionally lead them to provide an answer when search results are thin or off-target rather than flagging the gap. The system prompt doesn't shape the search step itself, but it does shape how the model uses the search results when writing the final response, which makes it the right place for grounding rules. Two short additions cover most of these edge cases.

**Give the model permission to say it didn't find anything.** With an explicit out in the system prompt, the model is more likely to acknowledge insufficient results instead of leaning on training data to fill the gap.

```text System Prompt theme={null}
Only answer using the search results provided. If the results do not contain the answer, say so explicitly rather than guessing.
```

**Require disclosure of near-misses.** Search sometimes returns related but non-matching results (a different year, a parent company instead of a subsidiary, a similar product). Asking the model to surface the mismatch up front keeps these cases from being presented as direct answers.

```text System Prompt theme={null}
If the search results are related but do not match the question (a different year, a parent company, or a similar product), state the mismatch explicitly before answering.
```

## What Carries Over from the Agent API Guide

The same core prompting rules apply with no changes:

* **Be specific and descriptive** in the user message. Vague queries produce scattered results.
* **Cap result counts.** If a list is needed, say how long.
* **Don't few-shot content.** Pasting a written-out example answer can cause the search step to latch onto the example topic. Few-shotting *structure* is fine; for guaranteed shape use `response_format`.
* **Don't ask for URLs in the response text.** Sonar always returns sources in the top-level `citations` and `search_results` fields. Read them from there.
* **Use parameters, not prose, for filters.** The search backend reads parameters; it does not read the system prompt.

## Next Steps

<CardGroup>
  <Card title="Agent API Prompt Guide" icon="book" href="/docs/agent-api/prompt-guide">
    The full prompting guide. Most rules apply to Sonar as well.
  </Card>

  <Card title="Search Filters" icon="magnifying-glass" href="/docs/sonar/filters">
    Domain, recency, and date filters for narrowing Sonar search results.
  </Card>

  <Card title="Pro Search" icon="layer-group" href="/docs/sonar/pro-search/quickstart">
    Multi-step search and reasoning when single-shot is not enough.
  </Card>

  <Card title="Agent API Quickstart" icon="rocket" href="/docs/agent-api/quickstart">
    Recommended for new applications. Multi-turn loop and custom tools.
  </Card>
</CardGroup>


# Sonar API
Source: https://docs.perplexity.ai/docs/sonar/quickstart

Get started with Perplexity's Sonar API for web-grounded AI responses. Make your first API call in minutes.

## Overview

Perplexity's Sonar API provides web-grounded AI responses with support for streaming, tools, search options, and more. You can use it with OpenAI-compatible client libraries or our native SDKs for type safety and enhanced features.

Use the Sonar API when you need web search capabilities built-in, streaming responses, or Perplexity's Sonar models. For structured outputs and third-party models, use our [Agent API](/docs/agent-api/quickstart).

<Tip>
  Keep using your existing OpenAI SDKs to get started fast; switch to our [native SDKs](/docs/sdk/overview) later as needed.
</Tip>

## Installation

Install the SDK for your preferred language:

<CodeGroup>
  ```bash Python theme={null}
  pip install perplexityai
  ```

  ```bash Typescript theme={null}
  npm install @perplexity-ai/perplexity_ai
  ```

  ```bash OpenAI Python (Compatible) theme={null}
  pip install openai
  ```

  ```bash OpenAI Typescript (Compatible) theme={null}
  npm install openai
  ```
</CodeGroup>

## Authentication

Set your API key as an environment variable. The SDK will automatically read it:

<Tabs>
  <Tab title="macOS/Linux">
    ```bash theme={null}
    export PERPLEXITY_API_KEY="your_api_key_here"
    ```
  </Tab>

  <Tab title="Windows">
    ```powershell theme={null}
    setx PERPLEXITY_API_KEY "your_api_key_here"
    ```
  </Tab>
</Tabs>

<Info>
  All SDK examples below automatically use the `PERPLEXITY_API_KEY` environment variable. You can also pass the key explicitly if needed.
</Info>

## Generating an API Key

<Card title="Get your Perplexity API Key" icon="key" href="https://console.perplexity.ai">
  Navigate to the **API Keys** tab in the API Portal and generate a new key.
</Card>

<Note>
  **OpenAI SDK Compatible:** Perplexity's API supports the OpenAI Chat Completions format. You can use OpenAI client libraries by pointing to our endpoint.
</Note>

## Basic Usage

### Non-Streaming Request

<CodeGroup>
  ```python Python SDK theme={null}
  from perplexity import Perplexity

  client = Perplexity()

  completion = client.chat.completions.create(
      model="sonar-pro",
      messages=[
          {"role": "user", "content": "What are the latest developments in quantum computing?"}
      ]
  )

  print(completion.choices[0].message.content)
  ```

  ```typescript Typescript SDK theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  const completion = await client.chat.completions.create({
      model: "sonar-pro",
      messages: [
          { role: "user", content: "What are the latest developments in quantum computing?" }
      ],
  });

  console.log(completion.choices[0].message.content);
  ```

  ```python OpenAI Python SDK theme={null}
  import os
  from openai import OpenAI

  client = OpenAI(
      api_key=os.environ.get("PERPLEXITY_API_KEY"),
      base_url="https://api.perplexity.ai"
  )

  resp = client.chat.completions.create(
      model="sonar-pro",
      messages=[
          {"role": "user", "content": "What are the latest developments in quantum computing?"}
      ]
  )
  print(resp.choices[0].message.content)
  ```

  ```typescript OpenAI Typescript SDK theme={null}
  import OpenAI from 'openai';

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

  const resp = await client.chat.completions.create({
      model: "sonar-pro",
      messages: [
          { role: "user", content: "What are the latest developments in quantum computing?" }
      ],
  });
  console.log(resp.choices[0].message.content);
  ```

  ```bash cURL theme={null}
  curl https://api.perplexity.ai/v1/sonar \
    -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "sonar-pro",
      "messages": [
        {
          "role": "user",
          "content": "What are the latest developments in quantum computing?"
        }
      ]
    }' | jq
  ```
</CodeGroup>

### Streaming Response

<CodeGroup>
  ```python Python SDK theme={null}
  from perplexity import Perplexity

  client = Perplexity()

  stream = client.chat.completions.create(
      model="sonar-pro",
      messages=[
          {"role": "user", "content": "What are the most popular open-source alternatives to OpenAI's GPT models?"}
      ],
      stream=True
  )

  for chunk in stream:
      if chunk.choices[0].delta.content:
          print(chunk.choices[0].delta.content, end="")
  ```

  ```typescript Typescript SDK theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  const stream = await client.chat.completions.create({
      model: "sonar-pro",
      messages: [
          { role: "user", content: "What are the most popular open-source alternatives to OpenAI's GPT models?" }
      ],
      stream: true,
  });

  for await (const chunk of stream) {
      if (chunk.choices[0].delta.content) {
          process.stdout.write((chunk.choices[0]?.delta?.content ?? '') as string);
      }
  }
  ```

  ```bash cURL theme={null}
  curl https://api.perplexity.ai/v1/sonar \
    -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "sonar-pro",
      "messages": [
        {
          "role": "user",
          "content": "What are the most popular open-source alternatives to OpenAI'\''s GPT models?"
        }
      ],
      "stream": true
    }'
  ```
</CodeGroup>

<Info title="Complete Streaming Guide" href="/docs/agent-api/output-control#streaming-responses">
  For a full guide on streaming, including parsing, error handling, citation management, and best practices, see our [Agent API streaming guide](/docs/agent-api/output-control#streaming-responses).
</Info>

## Response Structure

Sonar API responses follow an OpenAI-compatible format:

```json theme={null}
{
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "model": "sonar-pro",
    "created": 1234567890,
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "Recent developments in quantum computing include advances in error correction, new qubit architectures, and progress toward fault-tolerant systems..."
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 14,
        "completion_tokens": 287,
        "total_tokens": 301
    }
}
```

## Next Steps

<CardGroup>
  <Card title="Agent API" icon="code-circle" href="/docs/agent-api/quickstart">
    Need structured outputs or third-party models? Check out the Agent API.
  </Card>

  <Card title="Search API" icon="search" href="/docs/search/quickstart">
    Get raw search results with the Search API.
  </Card>

  <Card title="Sonar API Features" icon="book" href="/docs/sonar/features">
    Complete guide to the Sonar API with advanced features and examples.
  </Card>

  <Card title="Models" icon="brain" href="/docs/sonar/models">
    Explore available Sonar models and their capabilities.
  </Card>

  <Card title="API Reference" icon="code-circle" href="/api-reference/sonar-post">
    View complete endpoint documentation and parameters.
  </Card>

  <Card title="Search Filters" icon="search" href="/docs/sonar/filters#search-control">
    Learn how to control search behavior with filters and parameters.
  </Card>
</CardGroup>

<Info>
  Need help? Check out our [community](https://community.perplexity.ai) for support and discussions with other developers.
</Info>