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

get /async/chat/completions
Lists all asynchronous chat completion requests for the authenticated user.



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

post /async/chat/completions
Creates an asynchronous chat completion job.



# Get Async Chat Completion Response
Source: https://docs.perplexity.ai/api-reference/async-chat-completions-request_id-get

get /async/chat/completions/{request_id}
Retrieves the status and result of a specific asynchronous chat completion job.



# Chat Completions
Source: https://docs.perplexity.ai/api-reference/chat-completions-post

post /chat/completions
Generates a model's response for the given chat conversation.



# 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.



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

post /revoke_auth_token
Revokes an existing authentication token.



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

post /search
Get ranked search results from Perplexity's continuously refreshed index with advanced filtering and customization options.



# Changelog
Source: https://docs.perplexity.ai/changelog/changelog



<Tip>
  Looking ahead? Check out our [Feature Roadmap](/feature-roadmap) to see what's coming next.
</Tip>

<Update label="September 2025" tags={["File Attachments", "Documents", "API"]}>
  **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.

  **Example:**

  ```python  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"}}
              ]
          }
      ]
  )
  ```

  Get started with our comprehensive [File Attachments Guide](/guides/file-attachments).
</Update>

<Update label="September 2025" tags={["Search", "Standalone API", "Features"]}>
  **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.)

  **Example:**

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

  client = Perplexity()
  search = client.search.create(
      query="latest AI developments 2024",
      max_results=10
  )

  for result in search.results:
      print(f"{result.title}: {result.url}")
  ```

  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](/guides/search-guide).
</Update>

<Update label="September 2025" tags={["Security", "API Keys", "Key Management"]}>
  **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://perplexity.ai/account/api).
</Update>

<Update label="August 2025" tags={["Models", "Deprecation", "API"]}>
  **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" tags={["API", "Cost Tracking", "Usage"]}>
  **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" tags={["SEC Filings", "Search", "API"]}>
  **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/chat/completions \
    --header 'accept: application/json' \
    --header 'authorization: Bearer YOUR_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" tags={["Date Range", "Search", "API"]}>
  **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/chat/completions \
    --header 'accept: application/json' \
    --header 'authorization: Bearer YOUR_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" tags={["Academic Filter", "Search", "API"]}>
  **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/chat/completions \
    --header 'accept: application/json' \
    --header 'authorization: Bearer YOUR_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" tags={["Sonar Deep Research", "Reasoning", "API"]}>
  **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/chat/completions \
    --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](https://docs.perplexity.ai/models/models/sonar-deep-research)
</Update>

<Update label="May 2025" tags={["Sonar Deep Research", "Async", "API"]}>
  **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/async/chat/completions` - Lists all asynchronous chat completion requests for the authenticated user
  2. `POST https://api.perplexity.ai/async/chat/completions` - Creates an asynchronous chat completion job
  3. `GET https://api.perplexity.ai/async/chat/completions/{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](https://docs.perplexity.ai/models/models/sonar-deep-research)
</Update>

<Update label="May 2025" tags={["API", "Search Results", "Breaking Change"]}>
  **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" tags={["API Portal", "Organization", "Management"]}>
  **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://www.perplexity.ai/account/api/group](https://www.perplexity.ai/account/api/group)
</Update>

<Update label="April 2025" tags={["Search", "Location", "Filtering"]}>
  **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" tags={["Images", "Multimodal", "API"]}>
  **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" tags={["Search", "Date Range", "Filtering"]}>
  **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" tags={["Pricing", "Citation Tokens", "API"]}>
  **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" tags={["Features", "Access", "API"]}>
  **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" tags={["Structured Outputs", "API", "Features"]}>
  **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
  * Both JSON and Regex structured outputs are supported for `sonar` and `sonar-reasoning` models

  **Coming soon:**

  * Full Regex support for 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" tags={["Sonar Models", "Search Modes", "Pricing"]}>
  **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" tags={["Models", "Deprecation", "API"]}>
  **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" tags={["Sonar", "Sonar Pro", "New APIs"]}>
  **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 - [http://sonar.perplexity.ai/](http://sonar.perplexity.ai/)
</Update>

<Update label="November 2024" tags={["Citations", "Rate Limits", "API"]}>
  **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.

  If you have any questions or need assistance, feel free to reach out to our team at [api@perplexity.ai](mailto:api@perplexity.ai)
</Update>

<Update label="July 2024" tags={["Sonar Models", "Models", "Deprecation"]}>
  **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" tags={["Models", "Deprecation", "API"]}>
  **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>


# Memory Management
Source: https://docs.perplexity.ai/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 →](chat-summary-memory-buffer/)

### 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 →](chat-with-persistence/)

## 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/your-repo/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/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.md).

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/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.md).

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/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! 🚀


# Examples Overview
Source: https://docs.perplexity.ai/cookbook/examples/README

Ready-to-use applications demonstrating Perplexity Sonar API capabilities

# Examples Overview

Welcome to the **Perplexity Sonar API Examples** collection! These are production-ready applications that demonstrate real-world use cases of the Sonar API.

## 🚀 Quick Start

Navigate to any example directory and follow the instructions in the README.md file.

## 📋 Available Examples

### 🔍 [Fact Checker CLI](fact-checker-cli/)

**Purpose**: Verify claims and articles for factual accuracy\
**Type**: Command-line tool\
**Use Cases**: Journalism, research, content verification

**Key Features**:

* Structured claim analysis with ratings
* Source citation and evidence tracking
* JSON output for automation
* Professional fact-checking workflow

**Quick Start**:

```bash  theme={null}
cd fact-checker-cli/
python fact_checker.py --text "The Earth is flat"
```

***

### 🤖 [Daily Knowledge Bot](daily-knowledge-bot/)

**Purpose**: Automated daily fact delivery system\
**Type**: Scheduled Python application\
**Use Cases**: Education, newsletters, personal learning

**Key Features**:

* Topic rotation based on calendar
* Persistent storage of facts
* Configurable scheduling
* Educational content generation

**Quick Start**:

```bash  theme={null}
cd daily-knowledge-bot/
python daily_knowledge_bot.py
```

***

### 🏥 [Disease Information App](disease-qa/)

**Purpose**: Interactive medical information lookup\
**Type**: Web application (HTML/JavaScript)\
**Use Cases**: Health education, medical reference, patient information

**Key Features**:

* Interactive browser interface
* Structured medical knowledge cards
* Citation tracking for medical sources
* Standalone deployment ready

**Quick Start**:

```bash  theme={null}
cd disease-qa/
jupyter notebook disease_qa_tutorial.ipynb
```

***

### 📊 [Financial News Tracker](financial-news-tracker/)

**Purpose**: Real-time financial news monitoring and market analysis\
**Type**: Command-line tool\
**Use Cases**: Investment research, market monitoring, financial journalism

**Key Features**:

* Real-time financial news aggregation
* Market sentiment analysis (Bullish/Bearish/Neutral)
* Impact assessment and sector analysis
* Investment insights and recommendations

**Quick Start**:

```bash  theme={null}
cd financial-news-tracker/
python financial_news_tracker.py "tech stocks"
```

***

### 📚 [Academic Research Finder](research-finder/)

**Purpose**: Academic literature discovery and summarization\
**Type**: Command-line research tool\
**Use Cases**: Academic research, literature reviews, scholarly work

**Key Features**:

* Academic source prioritization
* Paper citation extraction with DOI links
* Research-focused prompting
* Scholarly workflow integration

**Quick Start**:

```bash  theme={null}
cd research-finder/
python research_finder.py "quantum computing advances"
```

## 🔑 API Key Setup

All examples require a Perplexity API key. You can set it up in several ways:

### Environment Variable (Recommended)

```bash  theme={null}
export PPLX_API_KEY="your-api-key-here"
```

### .env File

Create a `.env` file in the example directory:

```bash  theme={null}
PERPLEXITY_API_KEY=your-api-key-here
```

### Command Line Argument

```bash  theme={null}
python script.py --api-key your-api-key-here
```

## 🛠️ Common Requirements

All examples require:

* **Python 3.7+**
* **Perplexity API Key** ([Get one here](https://docs.perplexity.ai/guides/getting-started))
* **Internet connection** for API calls

Additional requirements vary by example and are listed in each `requirements.txt` file.

## 🎯 Choosing the Right Example

| **If you want to...**       | **Use this example**         |
| --------------------------- | ---------------------------- |
| Verify information accuracy | **Fact Checker CLI**         |
| Learn something new daily   | **Daily Knowledge Bot**      |
| Look up medical information | **Disease Information App**  |
| Track financial markets     | **Financial News Tracker**   |
| Research academic topics    | **Academic Research Finder** |

## 🤝 Contributing

Found a bug or want to improve an example? We welcome contributions!

1. **Report Issues**: Open an issue describing the problem
2. **Suggest Features**: Propose new functionality or improvements
3. **Submit Code**: Fork, implement, and submit a pull request

See our [Contributing Guidelines](https://github.com/ppl-ai/api-cookbook/blob/main/CONTRIBUTING.md) for details.

## 📄 License

All examples are licensed under the [MIT License](https://github.com/ppl-ai/api-cookbook/blob/main/LICENSE).

***

**Ready to explore?** Pick an example above and start building with Perplexity's Sonar API! 🚀


# Daily Knowledge Bot
Source: https://docs.perplexity.ai/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/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 src="https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/cookbook/static/img/discord-py-bot-demo.png?fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=d581adefa9b9dabbf7f743eca45b23af" alt="Discord Bot Demo" data-og-width="1865" width="1865" data-og-height="1074" height="1074" data-path="cookbook/static/img/discord-py-bot-demo.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/cookbook/static/img/discord-py-bot-demo.png?w=280&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=4500962470bb1c9eabec5180819e2781 280w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/cookbook/static/img/discord-py-bot-demo.png?w=560&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=1b6f465565e99fc6b498fbe9c32948dc 560w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/cookbook/static/img/discord-py-bot-demo.png?w=840&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=dc51606115d46613834ffbce9216015e 840w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/cookbook/static/img/discord-py-bot-demo.png?w=1100&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=dea5377027c4fcb130f48c19a0840a02 1100w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/cookbook/static/img/discord-py-bot-demo.png?w=1650&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=a9e32ebd6002a33457c18cc9d32abf49 1650w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/cookbook/static/img/discord-py-bot-demo.png?w=2500&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=3ea199dbcf6b179bc1bb39396548eb65 2500w" />

## ✨ 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 [Perplexity AI Settings](https://www.perplexity.ai/settings/api)

    <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/perplexity-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 [Perplexity AI Account Settings](https://www.perplexity.ai/settings/api)
    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 src="https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/cookbook/static/img/discord-py-bot-slash-command.png?fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=aca6508ef68d71ba094ec3635119602b" alt="Slash Command Demo" data-og-width="2140" width="2140" data-og-height="1062" height="1062" data-path="cookbook/static/img/discord-py-bot-slash-command.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/cookbook/static/img/discord-py-bot-slash-command.png?w=280&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=c236ac60e4ff2509f9d2eda53db6da29 280w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/cookbook/static/img/discord-py-bot-slash-command.png?w=560&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=c056a72302792cc661a79ddf77de7003 560w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/cookbook/static/img/discord-py-bot-slash-command.png?w=840&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=ae729560bc349a7b041cc68ba35e750c 840w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/cookbook/static/img/discord-py-bot-slash-command.png?w=1100&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=18de754a91ad4d55b469f13e7e5b4ffb 1100w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/cookbook/static/img/discord-py-bot-slash-command.png?w=1650&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=30742f76910ad907b4bf1dd58d73ef71 1650w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/cookbook/static/img/discord-py-bot-slash-command.png?w=2500&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=e959cce014bb17d7ee653b13761fe387 2500w" />

**Mention the Bot:**

```
@YourBot [your question here]
```

<img src="https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/cookbook/static/img/discord-py-bot-mention-command.png?fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=19e8953553d66f3b88d0893896729296" alt="Mention Command Demo" data-og-width="2185" width="2185" data-og-height="843" height="843" data-path="cookbook/static/img/discord-py-bot-mention-command.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/cookbook/static/img/discord-py-bot-mention-command.png?w=280&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=d9d233f58bc5d4ac4ad38b65d938849b 280w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/cookbook/static/img/discord-py-bot-mention-command.png?w=560&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=a9521162c1ed9fccbbfe902305a0e0d8 560w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/cookbook/static/img/discord-py-bot-mention-command.png?w=840&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=0073f3ac78347dc11b2f3216e89bc1b2 840w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/cookbook/static/img/discord-py-bot-mention-command.png?w=1100&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=5db62f3f06edbf1c82a87ae6bfcc8679 1100w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/cookbook/static/img/discord-py-bot-mention-command.png?w=1650&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=580d43fe4c15ba0fbd1469550f5d11da 1650w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/cookbook/static/img/discord-py-bot-mention-command.png?w=2500&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=acc2c24d15f76c89cf89ae4cb9292e45 2500w" />

## 📊 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/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.

![Disease Information App Screenshot](https://via.placeholder.com/800x450.png?text=Disease+Information+App)

## 🌟 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


# Fact Checker CLI
Source: https://docs.perplexity.ai/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.


# Financial News Tracker
Source: https://docs.perplexity.ai/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']}")
```


# Academic Research Finder CLI
Source: https://docs.perplexity.ai/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.


# Perplexity API Cookbook
Source: https://docs.perplexity.ai/cookbook/index

A collection of practical examples and guides for building with Perplexity's API Platform

A collection of practical examples and guides for building with [**Perplexity's API Platform**](https://docs.perplexity.ai/) - the fastest, most cost-effective AI answer engine with real-time search capabilities.

## Quick Start

To get started with any project in this cookbook:

1. **Browse examples** - Find the use case that matches your needs
2. **Follow the guide** - Each example includes complete setup instructions
3. **Get the code** - Full implementations are available in our [GitHub repository](https://github.com/perplexityai/api-cookbook)
4. **Build and customize** - Use the examples as starting points for your projects

## What's Inside

### [Examples](/cookbook/examples/README)

Ready-to-run projects that demonstrate specific use cases and implementation patterns.

### [Showcase](/cookbook/showcase/briefo/)

Community-built applications that demonstrate real-world implementations of the API Platform.

### [Integration Guides](/cookbook/articles/memory-management/chat-summary-memory-buffer/README)

In-depth tutorials for advanced implementations and integrations with other tools.

> **Note**: All complete code examples, scripts, and project files can be found in our [GitHub repository](https://github.com/perplexityai/api-cookbook). The documentation here provides guides and explanations, while the repository contains the full runnable implementations.

## Contributing

Have a project built with API Platform? We'd love to feature it! Check our [Contributing Guidelines](https://github.com/perplexityai/api-cookbook/blob/main/CONTRIBUTING.md) to learn how to:

* Submit example tutorials
* Add your project to the showcase
* Improve existing content

## Resources

* [API Documentation](https://docs.perplexity.ai/home)
* [GitHub Repository](https://github.com/perplexityai/api-cookbook)

***

*Maintained by the Perplexity community*


# 4Point Hoops | AI Basketball Analytics Platform
Source: https://docs.perplexity.ai/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 className="w-full aspect-video rounded-xl" src="https://www.youtube.com/embed/lThCWq0ij7k" title="YouTube video player" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen />

## 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/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 className="w-full aspect-video rounded-xl" src="https://www.youtube.com/embed/XUPsSuCBTFw" title="YouTube video player" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen />

## 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/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 className="w-full aspect-video rounded-xl" src="https://www.youtube.com/embed/5t2ldWS3SJ8" title="YouTube video player" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen />

## 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/cookbook/showcase/briefo

AI curated newsfeed, social discussion, and deep research reports built on the Sonar API

# Briefo | Perplexity Powered News & Finance Social App

**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/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 for Personalized Insights**

```python  theme={null}
# Generate AI-powered location recommendations
response = client.chat.completions.create(
    model="sonar-reasoning",
    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/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 className="w-full aspect-video rounded-xl" src="https://www.youtube.com/embed/R558uRLNvUM" title="YouTube video player" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen />

> *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/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 className="w-full aspect-video rounded-xl" src="https://www.youtube.com/embed/nbbisoqsZDc" title="Daily News Briefing Demo" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen />

## 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/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 className="w-full aspect-video rounded-xl" src="https://www.youtube.com/embed/SB1pxIl9Mp0" title="YouTube video player" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen />

## 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/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 align="center">
  <img src="https://raw.githubusercontent.com/vishnu32510/fact_pulse/main/assets/icon/icon.png" alt="Fact Dynamics logo" width="80" height="80" style={{ borderRadius: '14px' }} />
</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 src="https://raw.githubusercontent.com/vishnu32510/fact_pulse/main/assets/screenshots/2.%20Dashboard.png" alt="Dashboard" width="200" />
    </td>

    <td>
      <img src="https://raw.githubusercontent.com/vishnu32510/fact_pulse/main/assets/screenshots/4.%20Fact%20Checks(Speech,%20Debate,%20Image).png" alt="Fact checking interface" width="200" />
    </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 className="w-full aspect-video rounded-xl" src="https://www.youtube.com/embed/92IoX19Djtc" title="YouTube video player" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen />

## 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/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 controls className="w-full aspect-video rounded-xl" src="https://github.com/user-attachments/assets/6016c5dd-6c18-415e-b982-fafb56170b87" />

## 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
PPLX_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/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 className="w-full aspect-video rounded-xl" src="https://www.youtube.com/embed/EI5yT7_aD6U" title="YouTube video player" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen />

### Try it out

* [FlameGuard AI](https://flameguardai.dlyog.com)
* [FlameGuard AI MCP](https://flameguardai-mcp.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/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 className="w-full aspect-video rounded-xl" src="https://www.youtube.com/embed/09h7zluuhQI" title="YouTube video player" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen />

## 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/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 className="w-full aspect-video rounded-xl" src="https://www.youtube.com/embed/IFP0EiHqd7Y" title="YouTube video player" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen />

## 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}
PPLX_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/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 className="w-full aspect-video rounded-xl" src="https://www.youtube.com/embed/BSN3Wp4uE-U" title="YouTube video player" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen />

## Links

* [GitHub Repository](https://github.com/srivastavanik/monday/tree/final)


# MVP LifeLine | AI Youth Empowerment Platform
Source: https://docs.perplexity.ai/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/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 className="w-full aspect-video rounded-xl" src="https://www.youtube.com/embed/5qzbRas0rxc" title="YouTube video player" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen />

## 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/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 Dart & Flutter SDKs
Source: https://docs.perplexity.ai/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 (temperature, top-p, 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/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 className="w-full aspect-video rounded-xl" src="https://www.youtube.com/embed/SCPklDuSR3U" title="YouTube video player" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen />

## 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/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/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 className="w-full aspect-video rounded-xl" src="https://www.youtube.com/embed/nFhciodeQ-c" title="YouTube video player" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen />

## 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/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 className="w-full aspect-video rounded-xl" src="https://www.youtube.com/embed/iusCyDNzY60" title="StarPlex Demo" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen />

## 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/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 className="w-full aspect-video rounded-xl" src="https://www.youtube.com/embed/twXeyK5ajyE" title="YouTube video player" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen />

## 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 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 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",
    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/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 className="w-full aspect-video rounded-xl" src="https://www.youtube.com/embed/WJxW91eu0fs" title="UnCovered Demo" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen />

## 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/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 className="w-full aspect-video rounded-xl" src="https://www.youtube.com/embed/AX3nOh9LbTc" title="YouTube video player" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen />

## 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)


# Get in Touch
Source: https://docs.perplexity.ai/discussions/discussions



## Join Our Developer Community

<Card title="🌟 Community Forum - Your First Stop!" icon="users" iconType="solid" color="#4F46E5">
  **The heart of our developer ecosystem!** Our vibrant community forum is where thousands of developers connect, share ideas, get help, and showcase their amazing projects built with the Perplexity API.

  **[🚀 Join the Community Forum →](https://community.perplexity.ai/)**

  **Why join the forum?**

  * Get technical help from experienced developers and our team
  * Share your projects and get featured in our showcase
  * Access exclusive tutorials, code examples, and best practices
  * Connect with like-minded builders and potential collaborators
  * Stay updated on the latest API features and announcements
</Card>

<CardGroup cols={2}>
  <Card title="Real-Time Chat" icon="comments" iconType="solid" color="#5865F2">
    Join our Discord community for instant help and casual conversations with fellow developers.

    * [Discord Community](https://discord.gg/perplexity-ai) - Real-time chat & support
    * Active community members ready to help
    * Quick answers to urgent questions
  </Card>

  <Card title="Stay Connected" icon="bell" iconType="solid" color="#1DA1F2">
    Follow us for the latest updates, feature announcements, and developer spotlights.

    * [Follow @PPLXDevs](https://twitter.com/PPLXDevs) - Latest updates & announcements
    * Developer showcases and success stories
    * API tips and best practices
  </Card>
</CardGroup>

## Contact Our Team

<CardGroup cols={2}>
  <Card title="Sales & Enterprise" icon="briefcase" iconType="solid" color="#10B981">
    Interested in enterprise solutions, custom pricing, or have sales questions?

    **[Contact Sales Team →](https://pplx.ai/api-sales)**
  </Card>

  <Card title="Technical Support" icon="headset" iconType="solid" color="#F59E0B">
    Need technical assistance? Our support team is here to help.

    <Warning>
      **Please 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 billing inquiries and account issues
  </Card>
</CardGroup>

## Developer Resources

<Steps>
  <Step title="Report Issues">
    Found a bug? Help us improve! Submit detailed bug reports through our [Community Forum](https://community.perplexity.ai/). Create a new post with the `Bug Reports` tag.
  </Step>

  <Step title="Share Your Work">
    Built something amazing 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](/cookbook/showcase/briefo). Let us amplify your work to thousands of developers and AI enthusiasts!
  </Step>
</Steps>


# Frequently Asked Questions
Source: https://docs.perplexity.ai/faq/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 use our GitHub repository and file the bug in [issues](https://github.com/ppl-ai/api-discussion/issues). Once you've submitted your report, we kindly ask that you share the link to the issue with us via email at [api@perplexity.ai](mailto:api@perplexity.ai) so we can track it on our end.

    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.
    3. We give users the power to tune the API to their respective use cases using sampling parameters like `presence_penalty`, `top_p`, etc. Custom tuning to specific use cases might lead to less generalization compared to the UI. We set optimized defaults and recommend not to explicitly provide sampling parameters in your API requests.
  </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 [Perplexity API dashboard](https://perplexity.ai/settings/api).

    **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](changelog/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 [Perplexity API dashboard](https://perplexity.ai/settings/api). 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 and Sonar Reasoning. 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`, `incomplete_details`, `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/feature-roadmap

Upcoming features and improvements for the Perplexity API designed to enhance your development experience.

Our roadmap is shaped by our users - have a feature in mind? Submit your suggestion [here](https://community.perplexity.ai/) and help us build the future of AI together.

<AccordionGroup>
  <Accordion title="Video Upload Capabilities" description="Multimodal video processing">
    We're expanding our multimodal capabilities to include video uploads.

    This feature will enable:

    * **Video Content Analysis**: Upload and analyze video files directly through the API
    * **Frame-by-Frame Processing**: Extract insights from video content at multiple time points
    * **Visual Scene Understanding**: Analyze visual elements, objects, and activities in video content
    * **Multimodal Search**: Search for information based on both visual and audio elements from your uploaded videos

    Supported formats will include common video file types (MP4, MOV, AVI) with reasonable file size limits for API efficiency.

    This capability will unlock new use cases in content moderation, educational analysis, media research, and automated video summarization.
  </Accordion>

  <Accordion title="File Search & Connectors" description="Expanded data access">
    Expanding your ability to access and process information:

    * **File Repository Integration**: Query file repositories tied to your API organization
    * **Multi-format File Search**: Search across various file types (PDFs, documents, spreadsheets)
    * **External Data Source Integration**: Connect to external data stores and databases
    * **Enterprise Connector Parity**: Full feature parity with enterprise connector capabilities

    This feature will allow your applications to tap into a broader range of data sources for more comprehensive insights, enabling you to build applications that can search and analyze your organization's entire knowledge base.
  </Accordion>

  <Accordion title="Expanded Structured Outputs Support" description="Enhanced response formatting">
    We're expanding our structured outputs capabilities:

    * **Universal JSON Support**: JSON structured outputs are now available for all models across all tiers
    * **Complete Regex Support**: Extending regex pattern support to all models (currently available for `sonar` and `sonar-reasoning`)
    * **Advanced Schema Validation**: Enhanced validation options for more reliable structured data
    * **Output Templates**: Pre-defined templates for common use cases

    This expansion will make it easier to build applications that require consistent, structured data from our API responses.
  </Accordion>

  <Accordion title="Documentation Overhaul" description="More comprehensive resources">
    We're committed to making our documentation a truly exceptional resource:

    * **Improved Layout**: Optimized structure for better self-serve workflows
    * **Consistent Design**: Unified branding between our landing page and documentation
    * **Enhanced Content**: Revised explanations for better developer understanding
    * **Vertical-Specific Guides**: Specialized documentation for publishers, merchants, and other industry partners
    * **High-Fidelity Demos**: More comprehensive examples beyond our basic cookbook demos
    * **Comprehensive Prompt Guide**: In-depth resources to help you build effectively with our search + LLM API
    * **API Selection Guides**: Clear guidance on which API is best suited for specific scenarios

    These improvements will help you get up to speed faster and make the most of our API capabilities.
  </Accordion>

  <Accordion title="Increased Rate Limits" description="Support for high-volume applications">
    We're scaling our infrastructure to support significantly higher request volumes:

    * **Enterprise-Scale Rate Limits**: Supporting use cases up to 100K requests per minute
    * **High-Growth Startup Support**: Designed specifically for rapidly scaling applications
    * **Infrastructure Reliability**: Enhanced stability and reduced latency spikes under high load
    * **Regional Scaling**: Expanded infrastructure deployment for global applications

    This enhancement will ensure our API can grow alongside your application's user base and processing needs, supporting everything from high-growth startups to enterprise-scale deployments.
  </Accordion>

  <Accordion title="Better Error Handling" description="Clearer troubleshooting">
    Improving our error framework:

    * More descriptive error messages
    * Clearer guidance on resolving common issues

    This will reduce debugging time and help you understand and address issues more efficiently.
  </Accordion>

  <Accordion title="Multimedia Capabilities" description="Beyond text processing">
    Broadening the types of content you can work with:

    * **URL Content Integration**: Specify URLs within prompts to search for and analyze content from specific web pages directly
    * **Advanced URL Parsing**: Extract and analyze content from web pages with enhanced accuracy and context understanding
    * **Web Page Analysis**: Deep content extraction including text, images, and structured data from URLs
    * **Real-time Web Content**: Access to live web content for dynamic analysis and research

    These features will enable new use cases and richer interactions within your applications, allowing you to reference specific web content and build more comprehensive research workflows with real-time web data integration.
  </Accordion>

  <Accordion title="Context Management / Memory" description="Improved context handling">
    We're addressing the limitations of managing context in API calls by introducing new context management features.

    Key improvements include:

    * **Efficient Context Storage**: Avoid appending responses from previous API calls to new ones, reducing the risk of exceeding context windows.
    * **Session-Based Memory**: Enable session-based memory to maintain context across multiple API calls without manual intervention.

    These enhancements will make it easier to build applications that require persistent context without hitting technical limitations.
  </Accordion>

  <Accordion title="Pro Search Public Release" description="Advanced agentic capabilities for all">
    We're preparing to make Pro Search available to all API users:

    * **Multi-step Reasoning**: Access to the advanced agentic search capabilities currently in beta
    * **Dynamic Tool Execution**: Automated web searches, URL content fetching, and Python code execution
    * **Intelligent Classification**: Automatic determination of when to use pro search vs fast search based on query complexity
    * **Transparent Reasoning**: Real-time streaming of the model's thought process and tool usage

    This will unlock sophisticated research workflows and enable your applications to handle complex, multi-dimensional queries that require computational analysis and deep web research.
  </Accordion>

  <Accordion title="Voice-to-Voice API" description="Real-time audio interactions">
    Introducing voice-based interactions through our API:

    * **Real-time Voice Processing**: Direct voice input and audio response generation
    * **Natural Conversation Flow**: Maintain context across voice interactions
    * **Multi-language Support**: Voice capabilities across multiple languages
    * **Low-latency Streaming**: Optimized for real-time voice applications

    This capability will enable voice assistants, interactive applications, and hands-free interfaces that can search and reason about information through natural speech.
  </Accordion>

  <Accordion title="Finance Tools Integration" description="Financial data and analysis">
    Expanding our capabilities with specialized financial tools:

    * **Market Data Access**: Real-time and historical stock prices, market indicators
    * **Ticker Symbol Lookup**: Intelligent company and symbol resolution
    * **Financial Analysis Tools**: Price history, trend analysis, and market insights
    * **SEC Filing Integration**: Enhanced search and analysis of financial documents

    These tools will enable sophisticated financial applications, trading platforms, and investment research tools with access to comprehensive financial data and analysis capabilities.
  </Accordion>

  <Accordion title="Labs Features via API" description="Experimental capabilities">
    Bringing cutting-edge experimental features to the API:

    * **Early Access Features**: Test new capabilities before general release
    * **Advanced Model Variants**: Access to experimental model configurations
    * **Prototype Integrations**: Early versions of upcoming integrations and tools
    * **Developer Feedback Integration**: Direct influence on feature development through testing

    This will give developers early access to innovative features and the opportunity to shape the future direction of our API capabilities.
  </Accordion>

  <Accordion title="Enhanced Third-Party Integrations" description="Seamless ecosystem connectivity">
    Expanding our integration ecosystem:

    * **Agentic Framework Support**: Enhanced integrations with LangChain, LlamaIndex, and other AI frameworks
    * **Developer Platform Integration**: Native support for popular development environments
    * **Workflow Automation**: Integration with automation platforms and CI/CD pipelines
    * **Real-time Collaboration**: Enhanced tooling for team-based development

    These integrations will make it easier to incorporate our API into your existing development workflows and build more sophisticated AI applications.
  </Accordion>

  <Accordion title="Developer Analytics Dashboard" description="Comprehensive usage insights">
    Advanced analytics and monitoring for your API usage:

    * **Query Analysis**: Detailed insights into query patterns, types, and performance
    * **Usage Metrics**: Comprehensive tracking of API calls, response times, and success rates
    * **Error Monitoring**: Detailed error tracking and debugging information
    * **Performance Optimization**: Insights to help optimize your application's API usage
    * **Cost Management**: Detailed billing breakdowns and usage forecasting

    This dashboard will provide the visibility you need to optimize your applications, manage costs, and understand user behavior patterns.
  </Accordion>
</AccordionGroup>

## Timeline and Availability

This roadmap represents our current development priorities. Features will be released incrementally, with some becoming available in the coming months and others planned for later in the year.

We'll announce new feature availability through our [changelog](/changelog) and via email notifications to API users.


# API Groups & Billing
Source: https://docs.perplexity.ai/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

Once signed in, navigate to the left-hand sidebar and expand the **API** section to access your API group and related settings.

<Frame>
  <img src="https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/images/api_portal/api_group_location.png?fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=60923b0ed18b3940f05b6c94db67a534" alt="API Group Location" data-og-width="202" width="202" data-og-height="180" height="180" data-path="images/api_portal/api_group_location.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/images/api_portal/api_group_location.png?w=280&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=0d9695c8af0909d534de23367b87c2b1 280w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/images/api_portal/api_group_location.png?w=560&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=283d9148c742bca11252072ccb3dbc13 560w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/images/api_portal/api_group_location.png?w=840&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=0c15f6daa67288ab18a2d8044cd051f0 840w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/images/api_portal/api_group_location.png?w=1100&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=37a16253e19753a7d762838ff3f26855 1100w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/images/api_portal/api_group_location.png?w=1650&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=1ef2a10965a71634a2fec034906bbe97 1650w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/images/api_portal/api_group_location.png?w=2500&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=e06ffdaa832991c18f9908943a9510b5 2500w" />
</Frame>

***

## Creating and Managing an API Group

To set up your organization:

<Steps>
  <Step title="Access API Group Settings">
    Click **API Group** in the left sidebar.
  </Step>

  <Step title="Complete Organization Details">
    Fill out your organization's name, address, and tax details.

    <Info>
      Your organization name and address will appear on invoices and help us support you better.
    </Info>

    **Fields include:**

    * Organization name and description
    * Address (Line 1, Line 2, City, State, Zip, Country)
    * Tax ID

    <Frame>
      <img src="https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/images/api_portal/api_group_details.png?fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=1da7640880394837c368c298c345465a" alt="API Group Details" data-og-width="821" width="821" data-og-height="842" height="842" data-path="images/api_portal/api_group_details.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/images/api_portal/api_group_details.png?w=280&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=7acfb5ff709fcbdcf31ac308c47d0c57 280w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/images/api_portal/api_group_details.png?w=560&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=32fa8606f546a64d411f1a8dbfec32ea 560w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/images/api_portal/api_group_details.png?w=840&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=3b08c7f8629bd43364c282b3cd2dfae2 840w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/images/api_portal/api_group_details.png?w=1100&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=72f01191aeca49622d9a09392f12d043 1100w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/images/api_portal/api_group_details.png?w=1650&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=4897d712600c5a42837ffa91ed64f6db 1650w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/images/api_portal/api_group_details.png?w=2500&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=55a355327c4738a8102fa78db2aabbe9 2500w" />
    </Frame>
  </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" arrow="True" horizontal="True" iconType="solid" cta="Go to Billing" href="https://www.perplexity.ai/account/api/billing">
  Navigate directly to your API billing dashboard to manage payment methods, view usage, and configure billing settings.
</Card>

<Steps>
  <Step title="Navigate to Billing">
    Go to the **API Billing** tab in your API Portal.

    <Frame>
      <img src="https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/images/api_portal/api_billing.png?fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=c6c2e8f0f4d2b72639fee33c59bcce96" alt="API Billing" data-og-width="731" width="731" data-og-height="288" height="288" data-path="images/api_portal/api_billing.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/images/api_portal/api_billing.png?w=280&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=5d65109817adbce75ffac6991192cc57 280w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/images/api_portal/api_billing.png?w=560&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=2bd83e25b683ab3535914325de3798ae 560w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/images/api_portal/api_billing.png?w=840&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=027009d05fd6c02e84b6bf9bc4da1b1c 840w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/images/api_portal/api_billing.png?w=1100&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=b28701dd96ff8ef5e91757e098666add 1100w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/images/api_portal/api_billing.png?w=1650&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=b56a45636e0c33db2b17d1c71b754374 1650w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/images/api_portal/api_billing.png?w=2500&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=2e2bb3598954d408eccb85d7523426e9 2500w" />
    </Frame>
  </Step>

  <Step title="Add Payment Method">
    Click **Add Payment Method** and enter your credit card information.

    <Note>
      This step will not charge your credit card. It just stores payment information for future API usage.
    </Note>
  </Step>

  <Step title="Configure Auto Top-Up (Recommended)">
    Enable automatic credit top-up to avoid service interruptions.

    <Frame>
      <img src="https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/images/api_portal/auto_reload.png?fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=ad488d9f227382bda3bbf6119c04d40f" alt="Auto Reload" data-og-width="708" width="708" data-og-height="227" height="227" data-path="images/api_portal/auto_reload.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/images/api_portal/auto_reload.png?w=280&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=a28beb091c576c62e24ac716e55f45ab 280w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/images/api_portal/auto_reload.png?w=560&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=0bad5b10b57c9527a4b0e50701a11402 560w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/images/api_portal/auto_reload.png?w=840&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=d8bcfe1e32b1b80158a254fcba8bf889 840w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/images/api_portal/auto_reload.png?w=1100&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=ac81425af371bfc15bd10b1e1ca126d6 1100w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/images/api_portal/auto_reload.png?w=1650&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=07f527d591ebe5622ce4531a4c8f316d 1650w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/images/api_portal/auto_reload.png?w=2500&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=3605774e24e8429a675216244126f917 2500w" />
    </Frame>

    <Warning>
      If you run out of credits, your API keys will be blocked until you add to your credit balance. Auto top-up prevents this by automatically adding credits when your balance drops below a threshold.
    </Warning>
  </Step>
</Steps>

***

## 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 and billing** for cost attribution
* **Can be revoked or regenerated** 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 YOUR_API_KEY`
</Info>

### Creating an API Key

<Steps>
  <Step title="Navigate to API Keys">
    Go to the **API Keys** tab in your API Portal.
  </Step>

  <Step title="Generate New Key">
    Click **+ Create Key** to generate a new API key.

    <Frame>
      <img src="https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/images/api_portal/generate_api_keys.png?fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=f8c41558ce9dfd90946bc4680454b73d" alt="Generate API Keys" data-og-width="737" width="737" data-og-height="158" height="158" data-path="images/api_portal/generate_api_keys.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/images/api_portal/generate_api_keys.png?w=280&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=e5f35dd228c9f198ab89cfdbc3b7c739 280w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/images/api_portal/generate_api_keys.png?w=560&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=e3ec0a151ffac69befdd3dd6f9c3ade5 560w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/images/api_portal/generate_api_keys.png?w=840&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=fb67be82e1cc01edd23fbd0d81eed2f2 840w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/images/api_portal/generate_api_keys.png?w=1100&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=66e9cbd117df41e5118c23251b3f2e1a 1100w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/images/api_portal/generate_api_keys.png?w=1650&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=9e3c6524759c7cd02e8114470b7e5f3a 1650w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/images/api_portal/generate_api_keys.png?w=2500&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=01afce0ba02019235fa4a0c6c21b7624 2500w" />
    </Frame>
  </Step>

  <Step title="Secure Your Key">
    Copy and securely store your API key immediately.

    <Warning>
      API keys are sensitive credentials. Never expose them in client-side code or share them in public repositories.
    </Warning>
  </Step>
</Steps>

***

## Adding and Managing Members

Admins can invite team members to the organization with specific roles: **Admin** or **Member**.

### Adding a Member

<Steps>
  <Step title="Initiate Member Invitation">
    Click **+ Add Member**.

    <Frame>
      <img src="https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/images/api_portal/click_on_add_member.png?fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=deb5bac5862619ceaf32b63371bf70a5" alt="Click on Add Member" data-og-width="746" width="746" data-og-height="154" height="154" data-path="images/api_portal/click_on_add_member.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/images/api_portal/click_on_add_member.png?w=280&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=04e76cdc3b9ec8cb78b23c45ae581cc2 280w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/images/api_portal/click_on_add_member.png?w=560&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=ad0a10236e175f55bb1591c7df9402c6 560w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/images/api_portal/click_on_add_member.png?w=840&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=141055bf1dfd61d7052a6cf3909d27e8 840w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/images/api_portal/click_on_add_member.png?w=1100&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=167d0df1c95b647cb067eec01d02e24b 1100w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/images/api_portal/click_on_add_member.png?w=1650&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=251f0aee92b97c931e1b6df1104f80f5 1650w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/images/api_portal/click_on_add_member.png?w=2500&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=fa336b8a62d0602bf18b53fd65b02953 2500w" />
    </Frame>
  </Step>

  <Step title="Enter Member Details">
    Enter the user's email address and click **Invite**.

    <Frame>
      <img src="https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/images/api_portal/enter_new_member_email.png?fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=f401d8effceb10a0c74d1f8637256fd6" alt="Enter New Member Email" data-og-width="549" width="549" data-og-height="258" height="258" data-path="images/api_portal/enter_new_member_email.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/images/api_portal/enter_new_member_email.png?w=280&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=30a6b4191cd846c6b30cb4d879f2d3bf 280w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/images/api_portal/enter_new_member_email.png?w=560&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=de4eaf9f3f43360a39473ae278b93d4f 560w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/images/api_portal/enter_new_member_email.png?w=840&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=b2d1bcbcf2f559b63f2ea8212e84fea6 840w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/images/api_portal/enter_new_member_email.png?w=1100&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=097789be2ed44686ed690a1a29230ddd 1100w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/images/api_portal/enter_new_member_email.png?w=1650&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=dbbe8663c05fbd28eebe36ea125ffbfe 1650w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/images/api_portal/enter_new_member_email.png?w=2500&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=4fc27ae417addaa70612961e60fd6389 2500w" />
    </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.

<Frame>
  <img src="https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/images/api_portal/filter_members_by_role.png?fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=27f0c659b98920905d55b7b17461080c" alt="Filter Members by Role" data-og-width="379" width="379" data-og-height="236" height="236" data-path="images/api_portal/filter_members_by_role.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/images/api_portal/filter_members_by_role.png?w=280&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=74a384913ab947bb5ab9d958aa4831f9 280w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/images/api_portal/filter_members_by_role.png?w=560&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=b3f4612587303913b122f60815131b73 560w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/images/api_portal/filter_members_by_role.png?w=840&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=0f103b935268b669a1e08bf4e9111439 840w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/images/api_portal/filter_members_by_role.png?w=1100&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=a0b73af2a29b8a6f40e745e4a1f673a6 1100w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/images/api_portal/filter_members_by_role.png?w=1650&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=08c140b29bf4bf5ae47ea53ffd387f86 1650w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/images/api_portal/filter_members_by_role.png?w=2500&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=ca2cf54efd00a05c1062262ea00f2848 2500w" />
</Frame>

### 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 view API usage by selecting **Usage Metrics** from the sidebar.

Features include:

* Total API call trends over time
* Breakdown by API model and key
* Optional date range filters

<Check>
  Usage metrics help you monitor API activity and optimize for cost or performance.
</Check>

### Tracking Spend Per API Key

You can track billing for each of your API keys by following these steps:

<Steps>
  <Step title="Navigate to Usage Metrics">
    Navigate to the [API section](https://www.perplexity.ai/account/api) of your **Settings** and click on **Usage Metrics**

    <Frame>
      <img src="https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/guides/assets/pricing/view_dashboard.png?fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=ff1983fb45585f3ae3ee18b4a3f594dd" alt="Navigate to dashboard" data-og-width="206" width="206" data-og-height="191" height="191" data-path="guides/assets/pricing/view_dashboard.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/guides/assets/pricing/view_dashboard.png?w=280&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=91bf6a71ff8e26e0dbb1bcc39e2584db 280w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/guides/assets/pricing/view_dashboard.png?w=560&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=855a02cc03211b4e1e406439e3465153 560w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/guides/assets/pricing/view_dashboard.png?w=840&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=5750d06c407df3ce17c2ea86a1e46d96 840w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/guides/assets/pricing/view_dashboard.png?w=1100&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=d06bcd5f7661de8e5f7130c729ac9365 1100w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/guides/assets/pricing/view_dashboard.png?w=1650&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=f85bce9d95d9da56aa2785825e3a8379 1650w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/guides/assets/pricing/view_dashboard.png?w=2500&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=afb598684633b152c5752b5ace7246ee 2500w" />
    </Frame>
  </Step>

  <Step title="Access Invoice History">
    Select **Invoice history** > **Invoices**

    <Frame>
      <img src="https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/guides/assets/pricing/view_invoice_history.png?fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=e54800b7527b37234b229d08dc980aa5" alt="View invoice history" data-og-width="1344" width="1344" data-og-height="381" height="381" data-path="guides/assets/pricing/view_invoice_history.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/guides/assets/pricing/view_invoice_history.png?w=280&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=3f380c9ea64e00b7651c2155371f82af 280w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/guides/assets/pricing/view_invoice_history.png?w=560&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=728aa8f5fdf09ed32b74f5bd73532259 560w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/guides/assets/pricing/view_invoice_history.png?w=840&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=e546f4ad52f33b130986d85d64c8fc38 840w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/guides/assets/pricing/view_invoice_history.png?w=1100&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=9f78bd2444a78fd1b79b350ce62aaea1 1100w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/guides/assets/pricing/view_invoice_history.png?w=1650&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=410cb562cdee4dea19e7d7169fc7836d 1650w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/guides/assets/pricing/view_invoice_history.png?w=2500&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=835023ff6e4e271006d23646890aea47 2500w" />
    </Frame>
  </Step>

  <Step title="View Invoice Details">
    Click on any invoice to view details

    <Frame>
      <img src="https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/guides/assets/pricing/view_spend_per_api_key.png?fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=804d5a1a61d373a6aa27a54254f01f96" alt="View spend per API key" data-og-width="1274" width="1274" data-og-height="575" height="575" data-path="guides/assets/pricing/view_spend_per_api_key.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/guides/assets/pricing/view_spend_per_api_key.png?w=280&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=ba5c9b7a13c47ca3bf50b6fd6866430f 280w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/guides/assets/pricing/view_spend_per_api_key.png?w=560&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=d3ebe858abbdd63907c0aa22e5e4a555 560w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/guides/assets/pricing/view_spend_per_api_key.png?w=840&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=a9b17b5457b4af60c15e9d66e8a2c359 840w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/guides/assets/pricing/view_spend_per_api_key.png?w=1100&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=74810af3e32b3a3829ff03f5ac1517d5 1100w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/guides/assets/pricing/view_spend_per_api_key.png?w=1650&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=eac382d6c4d92b772e23a057def31b56 1650w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/guides/assets/pricing/view_spend_per_api_key.png?w=2500&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=e9ae27aae538134e04731d3e6cbf5e06 2500w" />
    </Frame>
  </Step>

  <Step title="Identify API Key Charges">
    Each item from the total bill will have a code at the end (e.g., pro (743S))

    * The 4 characters in parentheses are the last 4 characters of your API key
  </Step>
</Steps>


# null
Source: https://docs.perplexity.ai/getting-started/models



export const ModelOverviewCards = () => <div className="mt-8 mb-12">
    <hr className="border-t border-border mb-16" />
    <div className="grid grid-cols-1 lg:grid-cols-2 gap-8">
      <div className="space-y-6">
        <div>
          <h2 className="text-xl font-semibold text-foreground mb-4">Search</h2>
          <p className="text-muted-foreground text-m leading-relaxed">
            Models designed to retrieve and synthesize information efficiently.
          </p>
        </div>
        
        <div className="space-y-4">
          <div className="flex items-start gap-3">
            <div className="w-2 h-2 rounded-full bg-primary mt-2 flex-shrink-0"></div>
            <div className="text-muted-foreground text-xs leading-relaxed">
              Best suited for quick factual queries, topic summaries, product comparisons, and current events where simple information retrieval and synthesis is needed without complex reasoning.
            </div>
          </div>
          <div className="flex items-start gap-3">
            <div className="w-2 h-2 rounded-full bg-red-400 mt-2 flex-shrink-0"></div>
            <div className="text-muted-foreground text-xs leading-relaxed">
              Not ideal for multi-step analyses, exhaustive research on broad topics, or projects requiring detailed instructions or comprehensive reports across multiple sources.
            </div>
          </div>
        </div>
      </div>

      <div className="space-y-6 mt-10">
        <a href="../getting-started/models/models/sonar" className="bg-card border border-border rounded-lg p-4 flex items-center gap-4 transition-all duration-300 hover:border-primary hover:bg-card hover:scale-[1.02] cursor-pointer">
          <div className="w-28 h-28 bg-card border border-border rounded-lg flex items-center justify-center flex-shrink-0" style={{
  backgroundImage: `var(--sonar-sq)`,
  backgroundColor: '#77774D'
}}>
            <span className="text-foreground text-xs font-medium">sonar</span>
          </div>
          <div className="flex flex-col">
            <div className="font-semibold text-foreground text-m mb-2">Sonar</div>
            <div className="text-xs text-[#B8C4B0] leading-relaxed">
              Lightweight, cost-effective search model with grounding.
            </div>
          </div>
        </a>

        <a href="../getting-started/models/models/sonar-pro" className="bg-card border border-border rounded-lg p-4 flex items-center gap-4 transition-all duration-300 hover:border-primary hover:bg-card hover:scale-[1.02] cursor-pointer">
          <div className="w-28 h-28 bg-card border border-border rounded-lg flex items-center justify-center flex-shrink-0" style={{
  backgroundImage: `var(--sonar-pro-sq)`,
  backgroundColor: '#77774D'
}}>
            <span className="text-foreground text-xs font-medium">sonar pro</span>
          </div>
          <div className="flex-grow">
            <div className="font-semibold text-foreground text-m mb-2">Sonar Pro</div>
            <div className="text-xs text-[#B8C4B0] leading-relaxed">
              Advanced search offering with grounding, supporting complex queries and follow-ups.
            </div>
          </div>
        </a>
      </div>
    </div>

    <hr className="border-t border-border my-16" />

    <div className="grid grid-cols-1 lg:grid-cols-2 gap-8">
      <div className="space-y-6">
        <div>
          <h2 className="text-xl font-semibold text-foreground mb-4">Reasoning</h2>
          <p className="text-muted-foreground text-m leading-relaxed">
            Models that excel at complex, multi-step tasks.
          </p>
        </div>
        
        <div className="space-y-4">
          <div className="flex items-start gap-3">
            <div className="w-2 h-2 rounded-full bg-primary mt-2 flex-shrink-0"></div>
            <div className="text-muted-foreground text-xs leading-relaxed">
              Excellent for complex analyses requiring step-by-step thinking, tasks needing strict adherence to instructions, information synthesis across sources, and logical problem-solving that demands informed recommendations.
            </div>
          </div>
          <div className="flex items-start gap-3">
            <div className="w-2 h-2 rounded-full bg-red-400 mt-2 flex-shrink-0"></div>
            <div className="text-muted-foreground text-xs leading-relaxed">
              Not recommended for simple factual queries, basic information retrieval, exhaustive research projects (use Research models instead), or when speed takes priority over reasoning quality.
            </div>
          </div>
        </div>
      </div>

      <div className="space-y-6 mt-10">
        <a href="../getting-started/models/models/sonar-reasoning" className="bg-card border border-border rounded-lg p-4 flex items-center gap-4 transition-all duration-300 hover:border-primary hover:bg-card hover:scale-[1.02] cursor-pointer">
          <div className="w-28 h-28 bg-card border border-border rounded-lg flex items-center justify-center flex-shrink-0" style={{
  backgroundImage: `var(--reasoning-sq)`,
  backgroundColor: '#21808D'
}}>
            <span className="text-foreground text-xs font-medium">sonar reasoning</span>
          </div>
          <div className="flex flex-col">
            <div className="font-semibold text-foreground text-m mb-2">Sonar Reasoning</div>
            <div className="text-xs text-[#B8C4B0] leading-relaxed">
              Fast, real-time reasoning model designed for more problem-solving with search.
            </div>
          </div>
        </a>

        <a href="../getting-started/models/models/sonar-reasoning-pro" className="bg-card border border-border rounded-lg p-4 flex items-center gap-4 transition-all duration-300 hover:border-primary hover:bg-card hover:scale-[1.02] cursor-pointer">
          <div className="w-28 h-28 bg-card border border-border rounded-lg flex items-center justify-center flex-shrink-0" style={{
  backgroundImage: `var(--reasoning-pro-sq)`,
  backgroundColor: '#21808D'
}}>
            <span className="text-foreground text-xs font-medium text-center">sonar reasoning pro</span>
          </div>
          <div className="flex-grow">
            <div className="font-semibold text-foreground text-m mb-2">Sonar Reasoning Pro</div>
            <div className="text-xs text-[#B8C4B0] leading-relaxed">
              Precise reasoning offering powered by DeepSeek-R1 with Chain of Thought (CoT).
            </div>
          </div>
        </a>
      </div>
    </div>

    <hr className="border-t border-border my-16" />

    <div className="grid grid-cols-1 lg:grid-cols-2 gap-8">
      <div className="space-y-6">
        <div>
          <h2 className="text-xl font-semibold text-foreground mb-4">Research</h2>
          <p className="text-muted-foreground text-m leading-relaxed">
            Models that conduct in-depth analysis and generate detailed reports.
          </p>
        </div>
        
        <div className="space-y-4">
          <div className="flex items-start gap-3">
            <div className="w-2 h-2 rounded-full bg-primary mt-2 flex-shrink-0"></div>
            <div className="text-muted-foreground text-xs leading-relaxed">
              Ideal for comprehensive topic reports, in-depth analysis with exhaustive web research, and projects requiring synthesis of multiple information sources into cohesive reports like market analyses or literature reviews.
            </div>
          </div>
          
        </div>
      </div>

      <div className="space-y-6 mt-10">
        <a href="../getting-started/models/models/sonar-deep-research" className="bg-card border border-border rounded-lg p-4 flex items-center gap-4 transition-all duration-300 hover:border-primary hover:bg-card hover:scale-[1.02] cursor-pointer">
          <div className="w-28 h-28 bg-card border border-border rounded-lg flex items-center justify-center flex-shrink-0" style={{
  backgroundImage: `var(--deep-sq)`,
  backgroundColor: '#9C452B'
}}>
            <span className="text-foreground text-xs font-medium text-center">sonar deep research</span>
          </div>
          <div className="flex flex-col">
            <div className="font-semibold text-foreground text-m mb-2">Sonar Deep Research</div>
            <div className="text-xs text-muted-foreground leading-relaxed">
              Expert-level research model conducting exhaustive searches and generating comprehensive reports.
            </div>
          </div>
        </a>
      </div>
    </div>
  </div>;

export const SonarLogo = () => {
  return <svg xmlns="http://www.w3.org/2000/svg" width="80" height="30" viewBox="0 0 219 47" fill="none" className="text-foreground">
  <path d="M194.057 1.28212H201.77V7.26314C201.77 7.66217 201.968 7.86059 202.367 7.86059C202.766 7.86059 203.052 7.63382 203.224 7.17592C204.194 5.01072 205.535 3.47349 207.251 2.56205C208.965 1.59392 211.338 1.10986 214.364 1.10986H218.049V8.80037H213.165C209.338 8.80037 206.482 9.71181 204.598 11.5347C202.712 13.3576 201.77 16.3492 201.77 20.5073V45.7157H194.057V1.28212Z" fill="currentColor" />
  <path d="M145.653 32.4715C145.653 28.5402 146.996 25.4635 149.68 23.2416C152.421 20.963 156.505 19.7659 161.933 19.6526L178.212 19.3102V17.5157C178.212 14.1556 177.242 11.5347 175.299 9.65511C173.356 7.77555 170.329 6.83577 166.217 6.83577C162.563 6.83577 159.791 7.63382 157.907 9.22774C156.023 10.8238 155.079 12.8735 155.079 15.381H146.94C147.112 12.4766 147.969 9.85572 149.51 7.52044C151.052 5.18515 153.252 3.36228 156.106 2.05182C158.963 0.684667 162.332 0 166.217 0C172.728 0 177.641 1.56776 180.953 4.69891C184.265 7.83224 185.922 12.2477 185.922 17.9431V45.7157H178.212V41.1018C178.212 40.7595 178.04 40.5894 177.697 40.5894C177.412 40.5894 177.126 40.7595 176.84 41.1018C173.755 45.0332 169.215 46.9978 163.217 46.9978C157.733 46.9978 153.422 45.659 150.28 42.9814C147.195 40.3038 145.653 36.7998 145.653 32.4715ZM153.365 32.4715C153.365 34.8635 154.307 36.7431 156.194 38.1102C158.077 39.4774 160.705 40.1621 164.076 40.1621C168.474 40.1621 171.93 38.965 174.442 36.573C176.956 34.181 178.212 30.677 178.212 26.0631V25.7208L161.933 26.0631C159.019 26.1198 156.85 26.7173 155.422 27.8577C154.05 28.9392 153.365 30.4786 153.365 32.4715Z" fill="currentColor" />
  <path d="M105.794 1.28212V6.15328C105.794 6.55231 105.995 6.75073 106.394 6.75073C106.566 6.75073 106.708 6.69404 106.821 6.58065C106.993 6.41058 107.163 6.23832 107.336 6.06824C110.362 2.02347 114.989 0.00218047 121.214 0.00218047C126.812 0.00218047 131.21 1.56994 134.408 4.70109C137.607 7.83442 139.205 12.2499 139.205 17.9453V45.7179H131.495V19.2274C131.495 15.1826 130.466 12.106 128.41 9.99745C126.354 7.88894 123.384 6.83577 119.501 6.83577C115.103 6.83577 111.703 8.17458 109.305 10.8522C106.963 13.4731 105.792 17.4023 105.792 22.6442V45.7157H98.0818V1.28212H105.794Z" fill="currentColor" />
  <path d="M68.9421 0C73.2834 0 77.1951 0.911436 80.6795 2.73431C84.2206 4.55718 86.992 7.23479 88.9893 10.7672C91.0455 14.2995 92.0746 18.5427 92.0746 23.4989C92.0746 28.4551 91.0455 32.6983 88.9893 36.2307C86.9898 39.763 84.2206 42.4406 80.6795 44.2635C77.1951 46.0864 73.2834 46.9978 68.9421 46.9978C64.6007 46.9978 60.6606 46.0864 57.1196 44.2635C53.6352 42.4406 50.866 39.763 48.8098 36.2307C46.8103 32.6983 45.8116 28.4551 45.8116 23.4989C45.8116 18.5427 46.8103 14.2995 48.8098 10.7672C50.866 7.23479 53.6373 4.55718 57.1196 2.73431C60.6606 0.911436 64.6029 0 68.9421 0ZM68.9421 6.83577C64.3151 6.83577 60.5734 8.31631 57.7192 11.2796C54.9195 14.1839 53.5218 18.2571 53.5218 23.4989C53.5218 28.7408 54.9216 32.8422 57.7192 35.8033C60.5756 38.7077 64.3151 40.1621 68.9421 40.1621C73.569 40.1621 77.2823 38.7099 80.0799 35.8033C82.9363 32.84 84.3645 28.7386 84.3645 23.4989C84.3645 18.2592 82.9363 14.1839 80.0799 11.2796C77.2802 8.31631 73.569 6.83577 68.9421 6.83577Z" fill="currentColor" />
  <path d="M22.2757 0C25.989 0 29.3011 0.625794 32.2142 1.87956C35.184 3.13333 37.5259 4.92786 39.2397 7.26314C40.9536 9.59842 41.8672 12.3044 41.9806 15.381H33.8409C33.383 9.68346 29.3862 6.83577 21.8461 6.83577C18.5907 6.83577 16.0482 7.46156 14.221 8.71533C12.4505 9.9691 11.5652 11.563 11.5652 13.5015C11.5652 15.1543 12.1648 16.3492 13.3641 17.0905C14.62 17.8319 16.7351 18.5144 19.7049 19.1423L27.8446 20.8518C32.2426 21.7633 35.6136 23.0737 37.9554 24.7832C40.3539 26.4927 41.5532 29.1987 41.5532 32.9011C41.5532 35.6354 40.753 38.0841 39.1547 40.2493C37.5564 42.3578 35.2996 44.0084 32.3865 45.2055C29.5301 46.4026 26.218 47 22.4479 47C15.6514 47 10.3965 45.4911 6.68314 42.4712C2.9698 39.3945 0.74354 35.3498 0 30.3347H8.13969C9.22556 36.8848 13.9942 40.1621 22.4479 40.1621C26.1613 40.1621 28.9872 39.5079 30.9299 38.1974C32.8727 36.8303 33.8431 35.2058 33.8431 33.3263C33.8431 32.0725 33.5007 31.1327 32.8139 30.5069C32.1859 29.8223 31.3006 29.3099 30.1581 28.9697C29.0155 28.6274 27.1032 28.1717 24.4169 27.6026L16.2772 25.8931C12.3371 25.095 9.28007 23.7562 7.11051 21.8766C4.94094 19.9971 3.85507 17.2628 3.85507 13.6737C3.85507 9.45887 5.56892 6.12494 8.99661 3.67627C12.4221 1.22542 16.8507 0 22.2757 0Z" fill="currentColor" />
</svg>;
};

<div className="w-[80%] max-w-5xl mx-auto px-8 sm:px-8 lg:px-12 xl:px-16">
  <div className="flex flex-col md:flex-row justify-between items-start md:items-center mt-8 mb-8">
    <div className="flex items-center gap-2">
      <SonarLogo />

      <h1 className="text-2xl font-bold text-foreground"><span className="font-thin">Models</span></h1>
    </div>

    <div className="mt-4 md:mt-0">
      <button className="bg-primary text-foreground px-4 py-2 rounded-lg text-sm font-medium hover:bg-primary/90 transition-colors duration-200" type="button">
        <a href="https://labs.perplexity.ai/" target="_blank" rel="noopener noreferrer" className="block w-full h-full" tabIndex={-1}>
          Play
        </a>
      </button>
    </div>
  </div>

  <div className="flex flex-col md:flex-row justify-between items-start md:items-center mt-8 mb-8">
    <div className="flex items-center gap-2">
      <h3 className="text-xl font-bold text-foreground"><span className="font-thin">Explore the Sonar range and compare models</span></h3>
    </div>
  </div>

  <Frame>
    <img src="https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/models/assets/modelgraph.png?fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=98da92ec8cfc7052d6d007f8c8f6a1bd" alt="Sonar Range" className="mx-auto" data-og-width="1880" width="1880" data-og-height="972" height="972" data-path="models/assets/modelgraph.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/models/assets/modelgraph.png?w=280&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=8c85b601a30a1976791716e56d16c047 280w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/models/assets/modelgraph.png?w=560&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=551709a20a0adee8700d0670c6b79622 560w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/models/assets/modelgraph.png?w=840&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=98f36929ade0c9a2f9e70d6cb7398480 840w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/models/assets/modelgraph.png?w=1100&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=63d16889a2b37f452c21551cf30929bc 1100w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/models/assets/modelgraph.png?w=1650&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=1d71695065714b090eee70bf1eedda0a 1650w, https://mintcdn.com/perplexity/l9g7Fas5bu7d8tY5/models/assets/modelgraph.png?w=2500&fit=max&auto=format&n=l9g7Fas5bu7d8tY5&q=85&s=0ff75f9ce351ca3b8822438329d75a4a 2500w" />
  </Frame>

  <ModelOverviewCards />
</div>


# null
Source: https://docs.perplexity.ai/getting-started/overview



export const PerplexityLogo = () => {
  return <svg width="120" height="80" viewBox="0 0 1234 262" fill="none" xmlns="http://www.w3.org/2000/svg">
<path fill="#FBFAF4" d="M399.033 56.9632H411.597V82.8626H395.333C382.615 82.8626 373.058 85.9459 366.814 92.0353C360.571 98.2018 357.411 108.222 357.411 122.251V207.118H331.744V57.5028H357.411V81.3981C357.411 82.7084 358.105 83.4022 359.415 83.4022C360.186 83.4022 360.725 83.248 361.111 82.8626C361.496 82.4772 361.881 81.7064 362.267 80.5502C367.2 64.8255 379.455 56.9632 399.11 56.9632H399.033ZM566.755 89.0291C573.461 100.977 576.852 115.468 576.852 132.349C576.852 149.23 573.461 163.644 566.755 175.669C559.972 187.616 551.262 196.635 540.471 202.57C529.757 208.505 518.196 211.512 505.786 211.512C481.429 211.512 464.318 201.722 454.452 182.144C453.681 180.602 452.756 179.831 451.6 179.831C450.444 179.831 449.904 180.371 449.904 181.527V261.769H424.237V57.5028H449.904V83.0938C449.904 84.2501 450.444 84.7896 451.6 84.7896C452.756 84.7896 453.681 84.0188 454.452 82.4772C464.318 62.8985 481.429 53.1091 505.786 53.1091C518.119 53.1091 529.68 56.0382 540.471 62.0506C551.185 67.9859 559.972 76.9273 566.755 88.952V89.0291ZM551.262 132.349C551.262 114.697 546.56 100.977 537.157 91.1103C527.753 81.2439 515.344 76.3107 499.928 76.3107C484.512 76.3107 472.103 81.2439 462.699 91.1103C453.296 100.977 449.827 114.774 449.827 132.349C449.827 149.923 453.296 163.721 462.699 173.588C472.103 183.454 484.512 188.387 499.928 188.387C515.344 188.387 527.753 183.454 537.157 173.588C546.56 163.721 551.262 149.923 551.262 132.349ZM142.517 89.2604C149.223 101.208 152.614 115.699 152.614 132.58C152.614 149.461 149.223 163.875 142.517 175.9C135.811 187.925 127.025 196.866 116.234 202.801C105.52 208.737 93.9581 211.743 81.5486 211.743C57.1919 211.743 40.0806 201.954 30.2146 182.375C29.4438 180.833 28.5189 180.062 27.3627 180.062C26.2065 180.062 25.667 180.602 25.667 181.758V262H0V57.734H25.667V83.3251C25.667 84.4813 26.2065 85.0209 27.3627 85.0209C28.5189 85.0209 29.4438 84.2501 30.2146 82.7084C40.0806 63.1297 57.1919 53.3404 81.5486 53.3404C93.881 53.3404 105.443 56.2695 116.234 62.2818C126.948 68.2171 135.734 77.1586 142.517 89.1833V89.2604ZM126.948 132.503C126.948 114.851 122.246 101.131 112.842 91.2645C103.439 81.3981 91.0292 76.4648 75.6135 76.4648C60.1979 76.4648 47.7884 81.3981 38.3849 91.2645C28.9813 101.131 25.5128 114.929 25.5128 132.503C25.5128 150.078 28.9813 163.875 38.3849 173.742C47.7884 183.608 60.1979 188.541 75.6135 188.541C91.0292 188.541 103.439 183.608 112.842 173.742C122.246 163.875 126.948 150.078 126.948 132.503ZM284.418 159.636H311.549C307.927 173.665 300.527 185.766 289.428 196.018C278.329 206.27 262.374 211.435 241.64 211.435C226.07 211.435 212.273 208.197 200.403 201.799C188.533 195.402 179.361 186.229 172.886 174.358C166.411 162.488 163.174 148.459 163.174 132.349C163.174 116.239 166.334 102.21 172.578 90.3395C178.821 78.469 187.685 69.2963 198.938 62.8985C210.269 56.5007 223.526 53.2633 238.711 53.2633C253.895 53.2633 266.536 56.4237 277.096 62.7443C287.655 69.065 295.517 77.4669 300.758 87.8729C306 98.356 308.62 109.764 308.62 122.251V139.517H190.229C191.154 154.471 196.164 166.342 205.182 175.206C214.2 183.994 226.378 188.464 241.563 188.464C253.895 188.464 263.376 185.921 269.927 180.833C276.479 175.746 281.258 168.731 284.341 159.713L284.418 159.636ZM190.614 117.935H280.179C280.179 104.908 276.864 94.6561 270.158 87.2562C263.53 79.8564 253.047 76.1565 238.788 76.1565C225.453 76.1565 214.585 79.7793 206.107 86.9479C197.628 94.1165 192.464 104.445 190.537 117.858L190.614 117.935ZM597.201 207.118H622.868V0H597.201V207.118ZM953.532 41.2386H983.516V8.86437H953.532V41.2386ZM1059.28 184.841C1054.66 185.304 1051.81 185.535 1050.88 185.535C1049.57 185.535 1048.49 185.15 1047.72 184.379C1046.95 183.608 1046.57 182.529 1046.57 181.219C1046.57 180.294 1046.8 177.442 1047.26 172.74C1047.72 168.038 1047.95 160.792 1047.95 151.003V79.471H1084.56L1077.32 57.5799H1047.95V17.2663H1022.29V57.5028H994.384V79.3939H1022.29V158.171C1022.29 174.667 1026.29 186.923 1034.31 195.016C1042.33 203.033 1054.5 207.118 1070.84 207.118H1090.81V184.148H1080.79C1071.08 184.148 1063.91 184.379 1059.21 184.841H1059.28ZM1209.59 57.5028L1167.04 182.991C1166.5 184.533 1165.57 186.537 1162.64 186.537C1159.72 186.537 1158.79 184.533 1158.25 182.991L1115.7 57.5028H1089.5L1138.75 207.041H1156.17C1157.33 207.041 1158.17 207.118 1158.71 207.349C1159.25 207.503 1159.72 208.043 1160.18 208.814C1160.95 209.97 1160.8 211.666 1159.87 213.978L1151.85 235.792C1150.7 238.644 1148.54 240.109 1145.3 240.109C1144.15 240.109 1141.53 239.878 1137.29 239.415C1133.12 238.953 1127.65 238.721 1121.02 238.721H1100.21V261.692H1127.57C1143.53 261.692 1153.16 258.917 1161.41 253.521C1169.66 248.048 1176.13 238.413 1180.68 224.615L1233.87 63.2839V57.5028H1209.43H1209.59ZM869.671 113.31L829.437 57.5028H801.149V63.2839L849.323 128.032L790.589 201.414V207.195H819.416L866.203 147.071L909.829 207.195H937.5V201.414L886.397 132.349L941.739 63.5922V57.5799H912.912L869.517 113.387L869.671 113.31ZM956.23 207.118H981.897V57.5028H956.23V207.041V207.118ZM791.746 159.636C788.123 173.665 780.723 185.766 769.624 196.018C758.525 206.27 742.57 211.435 721.836 211.435C706.266 211.435 692.469 208.197 680.599 201.799C668.729 195.402 659.557 186.229 653.082 174.358C646.608 162.488 643.37 148.459 643.37 132.349C643.37 116.239 646.531 102.21 652.774 90.3395C659.017 78.469 667.881 69.2963 679.135 62.8985C690.465 56.5007 703.722 53.2633 718.907 53.2633C734.091 53.2633 746.732 56.4237 757.292 62.7443C767.851 69.065 775.713 77.4669 780.955 87.8729C786.196 98.356 788.817 109.764 788.817 122.251V139.517H670.425C671.35 154.471 676.36 166.342 685.378 175.206C694.396 183.994 706.574 188.464 721.759 188.464C734.091 188.464 743.572 185.921 750.123 180.833C756.675 175.746 761.454 168.731 764.537 159.713H791.668L791.746 159.636ZM670.81 117.935H760.375C760.375 104.908 757.06 94.6561 750.355 87.2562C743.726 79.8564 733.243 76.1565 718.984 76.1565C705.649 76.1565 694.781 79.7793 686.303 86.9479C677.824 94.1165 672.66 104.445 670.733 117.858L670.81 117.935Z" />
</svg>;
};

export const SonarLogo = () => {
  return <svg xmlns="http://www.w3.org/2000/svg" width="80" height="30" viewBox="0 0 219 47" fill="none" className="text-foreground">
  <path d="M194.057 1.28212H201.77V7.26314C201.77 7.66217 201.968 7.86059 202.367 7.86059C202.766 7.86059 203.052 7.63382 203.224 7.17592C204.194 5.01072 205.535 3.47349 207.251 2.56205C208.965 1.59392 211.338 1.10986 214.364 1.10986H218.049V8.80037H213.165C209.338 8.80037 206.482 9.71181 204.598 11.5347C202.712 13.3576 201.77 16.3492 201.77 20.5073V45.7157H194.057V1.28212Z" fill="currentColor" />
  <path d="M145.653 32.4715C145.653 28.5402 146.996 25.4635 149.68 23.2416C152.421 20.963 156.505 19.7659 161.933 19.6526L178.212 19.3102V17.5157C178.212 14.1556 177.242 11.5347 175.299 9.65511C173.356 7.77555 170.329 6.83577 166.217 6.83577C162.563 6.83577 159.791 7.63382 157.907 9.22774C156.023 10.8238 155.079 12.8735 155.079 15.381H146.94C147.112 12.4766 147.969 9.85572 149.51 7.52044C151.052 5.18515 153.252 3.36228 156.106 2.05182C158.963 0.684667 162.332 0 166.217 0C172.728 0 177.641 1.56776 180.953 4.69891C184.265 7.83224 185.922 12.2477 185.922 17.9431V45.7157H178.212V41.1018C178.212 40.7595 178.04 40.5894 177.697 40.5894C177.412 40.5894 177.126 40.7595 176.84 41.1018C173.755 45.0332 169.215 46.9978 163.217 46.9978C157.733 46.9978 153.422 45.659 150.28 42.9814C147.195 40.3038 145.653 36.7998 145.653 32.4715ZM153.365 32.4715C153.365 34.8635 154.307 36.7431 156.194 38.1102C158.077 39.4774 160.705 40.1621 164.076 40.1621C168.474 40.1621 171.93 38.965 174.442 36.573C176.956 34.181 178.212 30.677 178.212 26.0631V25.7208L161.933 26.0631C159.019 26.1198 156.85 26.7173 155.422 27.8577C154.05 28.9392 153.365 30.4786 153.365 32.4715Z" fill="currentColor" />
  <path d="M105.794 1.28212V6.15328C105.794 6.55231 105.995 6.75073 106.394 6.75073C106.566 6.75073 106.708 6.69404 106.821 6.58065C106.993 6.41058 107.163 6.23832 107.336 6.06824C110.362 2.02347 114.989 0.00218047 121.214 0.00218047C126.812 0.00218047 131.21 1.56994 134.408 4.70109C137.607 7.83442 139.205 12.2499 139.205 17.9453V45.7179H131.495V19.2274C131.495 15.1826 130.466 12.106 128.41 9.99745C126.354 7.88894 123.384 6.83577 119.501 6.83577C115.103 6.83577 111.703 8.17458 109.305 10.8522C106.963 13.4731 105.792 17.4023 105.792 22.6442V45.7157H98.0818V1.28212H105.794Z" fill="currentColor" />
  <path d="M68.9421 0C73.2834 0 77.1951 0.911436 80.6795 2.73431C84.2206 4.55718 86.992 7.23479 88.9893 10.7672C91.0455 14.2995 92.0746 18.5427 92.0746 23.4989C92.0746 28.4551 91.0455 32.6983 88.9893 36.2307C86.9898 39.763 84.2206 42.4406 80.6795 44.2635C77.1951 46.0864 73.2834 46.9978 68.9421 46.9978C64.6007 46.9978 60.6606 46.0864 57.1196 44.2635C53.6352 42.4406 50.866 39.763 48.8098 36.2307C46.8103 32.6983 45.8116 28.4551 45.8116 23.4989C45.8116 18.5427 46.8103 14.2995 48.8098 10.7672C50.866 7.23479 53.6373 4.55718 57.1196 2.73431C60.6606 0.911436 64.6029 0 68.9421 0ZM68.9421 6.83577C64.3151 6.83577 60.5734 8.31631 57.7192 11.2796C54.9195 14.1839 53.5218 18.2571 53.5218 23.4989C53.5218 28.7408 54.9216 32.8422 57.7192 35.8033C60.5756 38.7077 64.3151 40.1621 68.9421 40.1621C73.569 40.1621 77.2823 38.7099 80.0799 35.8033C82.9363 32.84 84.3645 28.7386 84.3645 23.4989C84.3645 18.2592 82.9363 14.1839 80.0799 11.2796C77.2802 8.31631 73.569 6.83577 68.9421 6.83577Z" fill="currentColor" />
  <path d="M22.2757 0C25.989 0 29.3011 0.625794 32.2142 1.87956C35.184 3.13333 37.5259 4.92786 39.2397 7.26314C40.9536 9.59842 41.8672 12.3044 41.9806 15.381H33.8409C33.383 9.68346 29.3862 6.83577 21.8461 6.83577C18.5907 6.83577 16.0482 7.46156 14.221 8.71533C12.4505 9.9691 11.5652 11.563 11.5652 13.5015C11.5652 15.1543 12.1648 16.3492 13.3641 17.0905C14.62 17.8319 16.7351 18.5144 19.7049 19.1423L27.8446 20.8518C32.2426 21.7633 35.6136 23.0737 37.9554 24.7832C40.3539 26.4927 41.5532 29.1987 41.5532 32.9011C41.5532 35.6354 40.753 38.0841 39.1547 40.2493C37.5564 42.3578 35.2996 44.0084 32.3865 45.2055C29.5301 46.4026 26.218 47 22.4479 47C15.6514 47 10.3965 45.4911 6.68314 42.4712C2.9698 39.3945 0.74354 35.3498 0 30.3347H8.13969C9.22556 36.8848 13.9942 40.1621 22.4479 40.1621C26.1613 40.1621 28.9872 39.5079 30.9299 38.1974C32.8727 36.8303 33.8431 35.2058 33.8431 33.3263C33.8431 32.0725 33.5007 31.1327 32.8139 30.5069C32.1859 29.8223 31.3006 29.3099 30.1581 28.9697C29.0155 28.6274 27.1032 28.1717 24.4169 27.6026L16.2772 25.8931C12.3371 25.095 9.28007 23.7562 7.11051 21.8766C4.94094 19.9971 3.85507 17.2628 3.85507 13.6737C3.85507 9.45887 5.56892 6.12494 8.99661 3.67627C12.4221 1.22542 16.8507 0 22.2757 0Z" fill="currentColor" />
</svg>;
};

export const QuickstartBanner = () => <div className="flex flex-col sm:flex-row sm:items-center sm:justify-between bg-card border border-border rounded-xl p-4 md:p-6 w-full mt-4 mb-8 dark:bg-[#2C3A2C] gap-4">
    <div className="flex items-center gap-3 sm:gap-4 flex-1">
      <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 40 35" fill="none" className="flex-shrink-0">
        <path d="M7.3187 33C4.77908 30.4604 3.04959 27.2246 2.34892 23.7021C1.64825 20.1795 2.00788 16.5283 3.38233 13.2101C4.75678 9.89188 7.08432 7.05577 10.0706 5.0604C13.0569 3.06503 16.5678 2 20.1594 2C23.751 2 27.2619 3.06503 30.2482 5.0604C33.2345 7.05577 35.5621 9.89188 36.9365 13.2101C38.311 16.5283 38.6706 20.1795 37.9699 23.7021C37.2693 27.2246 35.5398 30.4604 33.0002 33M28.2303 12.0886L20.1594 20.1594" stroke="currentColor" strokeWidth="3" strokeLinecap="round" strokeLinejoin="round" className="text-muted-foreground" />
      </svg>
      <div className="flex flex-col min-w-0">
        <span className="font-semibold text-base md:text-lg text-foreground">Quickstart Guide</span>
        <span className="text-sm md:text-base text-muted-foreground mt-0.5">Getting started is simple and fast—make your first API call within minutes.</span>
      </div>
    </div>
    <div className="flex flex-col sm:flex-row gap-2 sm:ml-4">
      <a href="/guides/search-quickstart" className="px-3 py-2 bg-primary text-white rounded font-mono text-sm font-semibold shadow hover:bg-primary/90 transition whitespace-nowrap text-center">
        Search 
      </a>
      <a href="/getting-started/quickstart" className="px-3 py-2 bg-primary text-white rounded font-mono text-sm font-semibold shadow hover:bg-primary/90 transition whitespace-nowrap text-center">
        Grounded LLM
      </a>
    </div>
  </div>;

export const UseCaseTabs = () => {
  const [selected, setSelected] = useState(0);
  const [copied, setCopied] = useState(false);
  const copyToClipboard = async text => {
    try {
      await navigator.clipboard.writeText(text);
      setCopied(true);
      setTimeout(() => setCopied(false), 2000);
    } catch (err) {
      console.error('Failed to copy text: ', err);
    }
  };
  const useCases = [{
    label: 'Find Results',
    codeExamples: [{
      language: 'bash',
      code: `curl https://api.perplexity.ai/search \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "query": [
      "What is Comet Browser?",
      "Perplexity AI",
      "Perplexity Changelog"
    ]
  }' | jq`
    }, {
      language: 'python',
      code: `from perplexity import Perplexity

client = Perplexity()

search = client.search.create(
    query=[
      "What is Comet Browser?",
      "Perplexity AI",
      "Perplexity Changelog"
    ]
)

for result in search.results:
    print(f"{result.title}: {result.url}")`
    }, {
      language: 'typescript',
      code: `import Perplexity from '@perplexity-ai/perplexity_ai';

const client = new Perplexity();

const search = await client.search.create({
  query: [
    "What is Comet Browser?",
    "Perplexity AI",
    "Perplexity Changelog"
  ]
});

search.results.forEach(result => {
  console.log(\`\${result.title}: \${result.url}\`);
});`
    }]
  }, {
    label: 'Chat with Grounded Search',
    codeExamples: [{
      language: 'bash',
      code: `curl https://api.perplexity.ai/chat/completions \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "model": "sonar-pro",
    "messages": [
      {
        "role": "user", 
        "content": "What are the major AI developments and announcements from today across the tech industry?"
      }
    ]
  }' | jq`
    }, {
      language: 'python',
      code: `from perplexity import Perplexity

client = Perplexity()

completion = client.chat.completions.create(
    messages=[
        {
            "role": "user",
            "content": "What are the major AI developments and announcements from today across the tech industry?"
        }
    ],
    model="sonar-pro"
)

print(completion.choices[0].message.content)`
    }, {
      language: 'javascript',
      code: `import Perplexity from '@perplexity-ai/perplexity_ai';

const client = new Perplexity();

const completion = await client.chat.completions.create({
  messages: [
    {
      role: 'user',
      content: "What are the major AI developments and announcements from today across the tech industry?"
    }
  ],
  model: 'sonar-pro'
});

console.log(completion.choices[0].message.content);`
    }]
  }, {
    label: 'Filter your sources',
    codeExamples: [{
      language: 'bash',
      code: `curl https://api.perplexity.ai/chat/completions \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "model": "sonar",
    "messages": [
      {
        "role": "user", 
        "content": "What are the most promising machine learning breakthroughs in computer vision and multimodal AI from recent arXiv publications?"
      }
    ],
    "web_search_options": {
      "search_domain_filter": ["arxiv.org"],
      "search_recency_filter": "month"
    }
  }' | jq`
    }, {
      language: 'python',
      code: `from perplexity import Perplexity

client = Perplexity()

completion = client.chat.completions.create(
    messages=[
        {
            "role": "user",
            "content": "What are the most promising machine learning breakthroughs in computer vision and multimodal AI from recent arXiv publications?"
        }
    ],
    model="sonar",
    web_search_options={
        "search_domain_filter": ["arxiv.org"],
        "search_recency_filter": "month"
    }
)

print(completion.choices[0].message.content)`
    }, {
      language: 'javascript',
      code: `import Perplexity from '@perplexity-ai/perplexity_ai';

const client = new Perplexity();

const completion = await client.chat.completions.create({
  messages: [
    {
      role: 'user',
      content: 'What are the most promising machine learning breakthroughs in computer vision and multimodal AI from recent arXiv publications?'
    }
  ],
  model: 'sonar',
  web_search_options: {
    search_domain_filter: ['arxiv.org'],
    search_recency_filter: 'month'
  }
});

console.log(completion.choices[0].message.content);`
    }]
  }, {
    label: 'Structured Outputs',
    codeExamples: [{
      language: 'bash',
      code: `curl https://api.perplexity.ai/chat/completions \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "model": "sonar-pro",
    "messages": [
      {
        "role": "user",
        "content": "Find the top 3 trending AI startups with recent funding. Include company name, funding amount, and focus area."
      }
    ],
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "schema": {
          "type": "object",
          "properties": {
            "startups": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "company_name": {"type": "string"},
                  "funding_amount": {"type": "string"},
                  "focus_area": {"type": "string"}
                },
                "required": ["company_name", "funding_amount", "focus_area"]
              }
            }
          },
          "required": ["startups"]
        }
      }
    }
  }' | jq`
    }, {
      language: 'python',
      code: `from perplexity import Perplexity

client = Perplexity()

completion = client.chat.completions.create(
    messages=[
        {
            "role": "user",
            "content": "Find the top 3 trending AI startups with recent funding. Include company name, funding amount, and focus area."
        }
    ],
    model="sonar-pro",
    response_format={
        "type": "json_schema",
        "json_schema": {
            "schema": {
                "type": "object",
                "properties": {
                    "startups": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "company_name": {"type": "string"},
                                "funding_amount": {"type": "string"},
                                "focus_area": {"type": "string"}
                            },
                            "required": ["company_name", "funding_amount", "focus_area"]
                        }
                    }
                },
                "required": ["startups"]
            }
        }
    }
)

print(completion.choices[0].message.content)`
    }, {
      language: 'javascript',
      code: `import Perplexity from '@perplexity-ai/perplexity_ai';

const client = new Perplexity();

const completion = await client.chat.completions.create({
  messages: [
    {
      role: 'user',
      content: 'Find the top 3 trending AI startups with recent funding. Include company name, funding amount, and focus area.'
    }
  ],
  model: 'sonar-pro',
  response_format: {
    type: 'json_schema',
    json_schema: {
      schema: {
        type: 'object',
        properties: {
          startups: {
            type: 'array',
            items: {
              type: 'object',
              properties: {
                company_name: { type: 'string' },
                funding_amount: { type: 'string' },
                focus_area: { type: 'string' }
              },
              required: ['company_name', 'funding_amount', 'focus_area']
            }
          }
        },
        required: ['startups']
      }
    }
  }
});

console.log(completion.choices[0].message.content);`
    }]
  }];
  const selectedUseCase = useCases[selected];
  return <section className="mx-auto w-full p-4 sm:p-6 lg:p-8 rounded-2xl border border-[rgba(228,227,212,0.30)] bg-[#E4E3D4] flex flex-col lg:flex-row gap-4 sm:gap-6 lg:gap-8 not-prose" aria-label="Sonar use case examples" style={{
    boxSizing: 'border-box',
    backgroundColor: 'var(--color-ecru)'
  }}>
      <nav className="flex flex-col lg:w-1/4 lg:min-w-[240px]" aria-label="Use case tabs">
        <h2 className="text-xl mt-2 font-semibold mb-4 text-[#091717]">Try Our APIs</h2>
        <div className="flex flex-row lg:flex-col gap-1 flex-1 overflow-x-auto lg:overflow-x-visible pb-2 lg:pb-0">
          {useCases.map((uc, idx) => <button key={uc.label} type="button" aria-current={selected === idx} aria-controls={`usecase-panel-${idx}`} className={`py-2 px-3 lg:px-2 flex items-center justify-center lg:justify-start text-[#091717] rounded-lg hover:bg-[#0917171A] whitespace-nowrap lg:whitespace-normal text-sm lg:text-base ${selected === idx ? 'bg-[#0917171A]' : ''}`} onClick={() => setSelected(idx)}>
              {uc.label}
            </button>)}
        </div>
        <a href="https://www.perplexity.ai/account/api/group" className="mt-4 lg:mt-auto text-sm underline px-2 text-[#444] text-center lg:text-left">Create an API key</a>
      </nav>

      <div className="flex-1 rounded-xl relative overflow-hidden min-h-[400px]" id={`usecase-panel-${selected}`} role="tabpanel" aria-live="polite">
        <div className="h-full overflow-y-auto">
          <CodeGroup>
            <pre className="language-python" filename="Python">
              <code>{selectedUseCase.codeExamples[1].code}</code>
            </pre>
            <pre className="language-typescript" filename="TypeScript">
              <code>{selectedUseCase.codeExamples[2].code}</code>
            </pre>
            <pre className="language-bash" filename="cURL">
              <code>{selectedUseCase.codeExamples[0].code}</code>
            </pre>
          </CodeGroup>
        </div>
      </div>
    </section>;
};

<div className="w-full max-w-6xl mx-auto px-4 sm:px-6 md:px-8 lg:px-12 py-6 sm:py-8">
  <div className="flex flex-col lg:flex-row justify-between items-start lg:items-center mt-6 sm:mt-8 mb-8 sm:mb-12 gap-4">
    <div className="flex items-center gap-2">
      <PerplexityLogo />

      <h1 className="text-xl sm:text-2xl font-bold text-foreground"><span className="font-thin">API Platform</span></h1>
    </div>

    <div className="lg:ml-8 max-w-full lg:max-w-md lg:text-right">
      <span className="text-xs sm:text-sm text-muted-foreground font-mono leading-relaxed">
        Power your products with unparalleled real-time, web-wide research and Q\&A capabilities.
      </span>
    </div>
  </div>

  <QuickstartBanner />

  <UseCaseTabs />

  <div className="mt-12">
    <div className="grid grid-cols-1 md:grid-cols-2 gap-8 max-w-4xl mx-auto">
      <div className="flex flex-col items-center">
        <h3 className="text-xl font-semibold text-foreground mb-2">Search</h3>
        <p className="text-sm text-muted-foreground text-center mb-4">Get ranked web search results with advanced filtering and real-time data.</p>

        <a href="/guides/search-quickstart" className="block rounded-xl overflow-hidden shadow-md hover:shadow-lg hover:scale-105 transform transition-all duration-300 cursor-pointer w-full">
          <div className="h-48 flex items-center justify-center relative bg-primary bg-no-repeat bg-cover bg-center" style={{ backgroundImage: 'var(--search-api-banner)' }} />
        </a>
      </div>

      <div className="flex flex-col items-center">
        <h3 className="text-xl font-semibold text-foreground mb-2">Grounded LLM</h3>
        <p className="text-sm text-muted-foreground text-center mb-4">Build AI applications with web-grounded chat completions and reasoning models.</p>

        <a href="/getting-started/quickstart" className="block rounded-xl overflow-hidden shadow-md hover:shadow-lg hover:scale-105 transform transition-all duration-300 cursor-pointer w-full">
          <div className="h-48 flex items-center justify-center relative bg-primary bg-no-repeat bg-cover bg-center" style={{ backgroundImage: 'var(--sonar-bg)' }}>
            <span className="z-10 relative text-foreground text-3xl font-normal tracking-tight">
              sonar
            </span>
          </div>
        </a>
      </div>
    </div>
  </div>
</div>


# Pricing
Source: https://docs.perplexity.ai/getting-started/pricing



<Note>
  This page shows **pricing information** to help you understand API costs. For **billing setup**, payment methods, and usage monitoring, visit the [Admin section](/getting-started/api-groups).
</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>

## Grounded LLM Pricing

<Info>
  **Total cost per query** = Token costs + Request fee (varies by search context size, applies to Sonar, Sonar Pro, Sonar Reasoning, 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**     |          \$1         |          \$5          |            -            |            -           |             -            |
    | **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**     |        \$5       |         \$8         |        \$12       |
    | **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 →](../guides/search-context-size-guide)
    </Note>
  </Tab>
</Tabs>

<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 cols={2}>
  <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-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 (33)        | \$0.000066     |
        | Output tokens (9655)     | \$0.07724      |
        | Citation tokens (12898)  | \$0.025796     |
        | Reasoning tokens (99932) | \$0.299796     |
        | Search queries           | \$0.075        |
        | **Total**                | **\$0.477898** |
      </Tab>

      <Tab title="High">
        | Component                 | Cost           |
        | ------------------------- | -------------- |
        | Input tokens (33)         | \$0.000066     |
        | Output tokens (10490)     | \$0.08392      |
        | Citation tokens (13906)   | \$0.027812     |
        | Reasoning tokens (100352) | \$0.301056     |
        | Search queries            | \$0.075        |
        | **Total**                 | **\$0.487854** |
      </Tab>
    </Tabs>
  </Card>
</CardGroup>

## Choosing the Right API

### Search API

| API            | Description                                    | Best For                                                                          |
| -------------- | ---------------------------------------------- | --------------------------------------------------------------------------------- |
| **Search API** | Raw web search results with advanced filtering | Custom search engines, research tools, competitive intelligence, news aggregation |

### Sonar Models (Chat Completions)

| Model                   | Description                                                    | Best For                                                         |
| ----------------------- | -------------------------------------------------------------- | ---------------------------------------------------------------- |
| **Sonar**               | Lightweight, cost-effective search model                       | Quick facts, news updates, simple Q\&A, high-volume applications |
| **Sonar Pro**           | Advanced search with deeper content understanding              | Complex queries, competitive analysis, detailed research         |
| **Sonar Reasoning**     | Quick problem-solving with step-by-step logic and search       | Logic puzzles, math problems, transparent reasoning              |
| **Sonar Reasoning Pro** | Enhanced multi-step reasoning with web search                  | Complex problem-solving, research analysis, strategic planning   |
| **Sonar Deep Research** | Exhaustive research and detailed report generation with search | Academic research, market analysis, comprehensive reports        |

<Info>
  **Need help choosing?** Use Search API when you want raw data to process yourself. Use Sonar models when you want AI-generated answers with search grounding.
</Info>


# Quickstart
Source: https://docs.perplexity.ai/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" arrow="True" horizontal="True" iconType="solid" cta="Click here" href="https://perplexity.ai/account/api">
  Navigate to the **API Keys** tab in the API Portal and generate a new key.
</Card>

<Info>
  See the [API Groups](/getting-started/api-groups) page to set up an API group.
</Info>

<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 our [OpenAI SDK Guide](/guides/chat-completions-guide) for examples.
</Note>

## Making Your First API Call

<Tabs>
  <Tab title="Python SDK">
    <Note>
      **Install the SDK first:** `pip install perplexityai`
    </Note>

    <CodeGroup>
      ```python Non-streaming Request 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 were the results of the 2025 French Open Finals?"}
          ]
      )

      # Print the AI's response
      print(completion.choices[0].message.content)
      ```

      ```python Streaming Response theme={null}
      from perplexity import Perplexity

      # Initialize the client (uses PERPLEXITY_API_KEY environment variable)
      client = Perplexity()

      # Make the streaming API call
      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
      )

      # Process the streaming response
      for chunk in stream:
          if chunk.choices[0].delta.content:
              print(chunk.choices[0].delta.content, end="")
      ```

      ```python With API Key (Alternative) theme={null}
      import os
      from perplexity import Perplexity

      # Initialize client with explicit API key
      client = Perplexity(api_key=os.environ.get("PERPLEXITY_API_KEY"))

      completion = client.chat.completions.create(
          model="sonar-pro",
          messages=[
              {"role": "user", "content": "What were the results of the 2025 French Open Finals?"}
          ]
      )

      print(completion.choices[0].message.content)
      ```
    </CodeGroup>

    <Note>
      Set your API key as an environment variable: `export PERPLEXITY_API_KEY="your_api_key_here"` (macOS/Linux) or `setx PERPLEXITY_API_KEY "your_api_key_here"` (Windows).
    </Note>
  </Tab>

  <Tab title="TypeScript SDK">
    <Note>
      **Install the SDK first:** `npm install @perplexity-ai/perplexity_ai`
    </Note>

    <CodeGroup>
      ```typescript Non-streaming Request 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 were the results of the 2025 French Open Finals?" }
          ]
      });

      // Print the AI's response
      console.log(completion.choices[0].message.content);
      ```

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

      // Initialize the client (uses PERPLEXITY_API_KEY environment variable)
      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 popular open-source alternatives to OpenAI's GPT models?" }
          ],
          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);
          }
      }
      ```

      ```typescript With API Key (Alternative) theme={null}
      import Perplexity from '@perplexity-ai/perplexity_ai';

      // Initialize client with explicit API key
      const client = new Perplexity({
          apiKey: process.env.PERPLEXITY_API_KEY
      });

      const completion = await client.chat.completions.create({
          model: "sonar-pro",
          messages: [
              { role: "user", content: "What were the results of the 2025 French Open Finals?" }
          ]
      });

      console.log(completion.choices[0].message.content);
      ```
    </CodeGroup>

    <Note>
      Set your API key as an environment variable: `export PERPLEXITY_API_KEY="your_api_key_here"` (macOS/Linux) or `setx PERPLEXITY_API_KEY "your_api_key_here"` (Windows).
    </Note>
  </Tab>

  <Tab title="cURL">
    **cURL** is a command-line tool for making HTTP requests. Set your API key and run the command:

    <CodeGroup>
      ```bash Non-streaming Request theme={null}
      curl --location 'https://api.perplexity.ai/chat/completions' \
      --header 'accept: application/json' \
      --header 'content-type: application/json' \
      --header "Authorization: Bearer $SONAR_API_KEY" \
      --data '{
        "model": "sonar-pro",
        "messages": [
          {
            "role": "user",
            "content": "What were the results of the 2025 French Open Finals?"
          }
        ]
      }' | jq
      ```

      ```bash Streaming Response theme={null}
      curl https://api.perplexity.ai/chat/completions \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer $SONAR_API_KEY" \
      -d '{
      "model": "sonar-pro",
      "messages": [
      {
        "role": "user",
        "content": "What were the results of the 2025 French Open Finals?"
      }
      ],
      "stream": true
      }'| jq
      ```
    </CodeGroup>
  </Tab>
</Tabs>

<Accordion title="Here's an example response (raw response at the end)">
  ## Response Content

  ```
  ## 2025 French Open Finals Results

  **Men's Singles Final**

  - **Champion:** Carlos Alcaraz
  - **Runner-up:** Jannik Sinner
  - **Score:** 4–6, 6–7^(4–7), 6–4, 7–6^(7–3), 7–6^(10–2)
  - **Details:** Carlos Alcaraz successfully defended his title by defeating Jannik Sinner in a dramatic five-set final. The match lasted 5 hours and 29 minutes, making it the longest French Open final in history and the second-longest major final ever. Alcaraz came back from two sets down and saved three championship points, marking a historic comeback. This victory gave Alcaraz his second French Open and fifth Grand Slam title, making him the second-youngest man to win five majors in the Open Era. It was also the first time a French Open singles final was decided by a final-set tiebreak.[1][2]

  **Women's Singles Final**

  - **Champion:** Coco Gauff
  - **Runner-up:** Aryna Sabalenka
  - **Score:** (Set scores not fully provided, but Gauff won in three sets)
  - **Details:** Coco Gauff rallied from an early deficit to defeat Aryna Sabalenka in a three-set battle. After losing the first set, Gauff fought back to claim her second Grand Slam title, with both coming against Sabalenka (the first being the 2023 US Open). Gauff’s victory marks her first French Open crown at age 21.[5]

  **Women's Doubles Final**

  - **Champions:** Anna Danilina / Aleksandra Krunić
  - **Runners-up:** Sara Errani / (partner not fully specified)
  - **Score:** 4–6, 6–1, 6–1
  - **Details:** Danilina and Krunić won the women's doubles final in three sets, taking control after dropping the first set.[3]

  **Summary Table**

  | Event                  | Winner                                | Runner-up                        | Score                                         |
  |------------------------|---------------------------------------|----------------------------------|-----------------------------------------------|
  | Men's Singles          | Carlos Alcaraz                        | Jannik Sinner                    | 4–6, 6–7(4–7), 6–4, 7–6(7–3), 7–6(10–2)       |
  | Women's Singles        | Coco Gauff                            | Aryna Sabalenka                  | Gauff won in 3 sets (full scores not given)   |
  | Women's Doubles        | Anna Danilina / Aleksandra Krunić     | Sara Errani / (unspecified)      | 4–6, 6–1, 6–1                                 |

  Alcaraz's men's final win was both historic for its comeback and duration, and Gauff’s victory marked a defining moment in her early career.[1][2][5]
  ```

  ## Search Results

  ```json  theme={null}
  [
    "https://en.wikipedia.org/wiki/2025_French_Open_%E2%80%93_Men's_singles",
    "https://en.wikipedia.org/wiki/2025_French_Open_%E2%80%93_Men's_singles_final",
    "https://www.rolandgarros.com/en-us/matches?status=finished",
    "https://www.tennis.com/news/articles/who-were-the-winners-and-losers-at-2025-roland-garros",
    "https://www.cbssports.com/tennis/news/2025-french-open-results-schedule-as-jannik-sinner-faces-carlos-alcaraz-coco-gauff-earns-first-title/"
  ]
  ```

  ## Sample Search Results (first 2 sources)

  ```json  theme={null}
  [
    {
      "title": "2025 French Open – Men's singles final",
      "url": "https://en.wikipedia.org/wiki/2025_French_Open_%E2%80%93_Men's_singles_final",
      "date": "2025-06-08",
      "last_updated": "2025-08-09",
      "snippet": "After 5 hours and 29 minutes of play, Alcaraz defeated Sinner 4–6, 6–7 (4–7) , 6–4, 7–6 (7–3) , 7–6 (10–2) , in the longest French Open final in history."
    },
    {
      "title": "2025 Roland Garros Men's Singles Tennis Live Scores - ESPN",
      "url": "https://www.espn.com/tennis/scoreboard/tournament/_/eventId/172-2025/competitionType/1",
      "date": "2025-06-08",
      "last_updated": "2025-08-29",
      "snippet": "2025 Roland Garros Scores May 18 - June 8, 2025 Court Philippe-Chatrier, Paris, France Men's Singles 2025 Carlos Alcaraz Defending Champion Carlos Alcaraz."
    }
  ]
  ```

  ## Usage Information

  ```json  theme={null}
  {
      "prompt_tokens": 12,
      "completion_tokens": 315,
      "total_tokens": 327,
      "search_context_size": "low",
      "cost": {
        "input_tokens_cost": 0.0,
        "output_tokens_cost": 0.005,
        "request_cost": 0.006,
        "total_cost": 0.011
      }
  }
  ```

  ## Raw Response

  ```json expandable theme={null}
  {
    "id": "66f3900f-e32e-4d59-b677-1a55de188262",
    "model": "sonar-pro",
    "created": 1756485272,
    "usage": {
      "prompt_tokens": 12,
      "completion_tokens": 315,
      "total_tokens": 327,
      "search_context_size": "low",
      "cost": {
        "input_tokens_cost": 0.0,
        "output_tokens_cost": 0.005,
        "request_cost": 0.006,
        "total_cost": 0.011
      }
    },
    "citations": [
      "https://en.wikipedia.org/wiki/2025_French_Open_%E2%80%93_Men's_singles_final",
      "https://www.espn.com/tennis/scoreboard/tournament/_/eventId/172-2025/competitionType/1",
      "https://www.cbssports.com/tennis/news/2025-french-open-results-schedule-as-jannik-sinner-faces-carlos-alcaraz-coco-gauff-earns-first-title/",
      "https://www.youtube.com/watch?v=jrkwqoI-gEg",
      "https://en.wikipedia.org/wiki/2025_French_Open_%E2%80%93_Men's_singles"
    ],
    "search_results": [
      {
        "title": "2025 French Open – Men's singles final",
        "url": "https://en.wikipedia.org/wiki/2025_French_Open_%E2%80%93_Men's_singles_final",
        "date": "2025-06-08",
        "last_updated": "2025-08-09",
        "snippet": "After 5 hours and 29 minutes of play, Alcaraz defeated Sinner 4–6, 6–7 (4–7) , 6–4, 7–6 (7–3) , 7–6 (10–2) , in the longest French Open final in history."
      },
      {
        "title": "2025 Roland Garros Men's Singles Tennis Live Scores - ESPN",
        "url": "https://www.espn.com/tennis/scoreboard/tournament/_/eventId/172-2025/competitionType/1",
        "date": "2025-06-08",
        "last_updated": "2025-08-29",
        "snippet": "2025 Roland Garros Scores May 18 - June 8, 2025 Court Philippe-Chatrier, Paris, France Men's Singles 2025 Carlos Alcaraz Defending Champion Carlos Alcaraz."
      },
      {
        "title": "2025 French Open: Results, schedule as Jannik Sinner ...",
        "url": "https://www.cbssports.com/tennis/news/2025-french-open-results-schedule-as-jannik-sinner-faces-carlos-alcaraz-coco-gauff-earns-first-title/",
        "date": "2025-06-07",
        "last_updated": "2025-08-29",
        "snippet": "The women's final is on June 7, and the men's final is one day later on June 8. Men's final. (1) Jannik Sinner vs. (2) Carlos Alcaraz -- Sunday, ..."
      },
      {
        "title": "Alcaraz, Gauff Win French Open 2025 | Swiatek, Ruud Fall - YouTube",
        "url": "https://www.youtube.com/watch?v=jrkwqoI-gEg",
        "date": "2025-06-09",
        "last_updated": "2025-08-04",
        "snippet": "We had some big changes in the rankings also. What was your favorite moment? 0:00 | Intro 0:14 | Weekly Results 0:36 | Rise & Fall 1:24 ..."
      },
      {
        "title": "2025 French Open – Men's singles",
        "url": "https://en.wikipedia.org/wiki/2025_French_Open_%E2%80%93_Men's_singles",
        "date": "2025-04-27",
        "last_updated": "2025-08-29",
        "snippet": "Defending champion Carlos Alcaraz defeated Jannik Sinner in the final, 4–6, 6–7, 6–4, 7–6, 7–6 to win the men's singles tennis title at the 2025 French Open. ..."
      }
    ],
    "object": "chat.completion",
    "choices": [
      {
        "index": 0,
        "finish_reason": "stop",
        "message": {
          "role": "assistant",
          "content": "**Carlos Alcaraz won the 2025 French Open men's singles final, defeating Jannik Sinner 4–6, 6–7(4–7), 6–4, 7–6(7–3), 7–6(10–2), while Coco Gauff won the women's singles title by rallying past Aryna Sabalenka in three sets**[1][3][5][4].\n\nKey details from the finals:\n\n- **Men's Singles:**  \n  - Alcaraz came back from two sets down to win in the longest French Open final ever (5 hours, 29 minutes)[1][5].\n  - He saved three championship points, a record in the Open Era for men's majors[1][5].\n  - This marked his second Roland Garros title and fifth Grand Slam overall[5].\n  - The match was the first French Open singles final decided by a match tiebreak (final set tiebreak introduced in 2022)[1][5].\n\n- **Women's Singles:**  \n  - Coco Gauff defeated Aryna Sabalenka after losing the first set, showcasing a strong comeback[3].\n  - Gauff secured her second Grand Slam (her first was at the 2023 US Open)[3].\n  - The final was played June 7, 2025; Gauff overcame an early deficit to win in three sets[3].\n\nThese finals were historic for their drama, length, and the milestone achievements for both Alcaraz and Gauff."
        },
        "delta": {
          "role": "assistant",
          "content": ""
        }
      }
    ]
  }

  ```
</Accordion>

<Info title="Complete Streaming Guide" href="/guides/streaming-responses">
  For a full guide on streaming, including parsing, error handling, citation management, and best practices, see our [streaming guide](/guides/streaming-responses).
</Info>

## Next Steps

Now that you've made your first API call, here are some recommended next steps:

<CardGroup cols={2}>
  <Card title="The Perplexity SDK Guide" icon="book" href="/guides/perplexity-sdk">
    Learn how to use the official Perplexity SDK with type safety, async support, and advanced features.
  </Card>

  <Card title="Models" icon="brain" href="/getting-started/models">
    Explore the different models available and their capabilities.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference">
    View the complete API documentation with detailed endpoint specifications.
  </Card>

  <Card title="Examples" icon="play" href="/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>


# Academic Filter Guide
Source: https://docs.perplexity.ai/guides/academic-filter-guide



<Note>
  The `search_mode: "academic"` parameter allows you to tailor your searches specifically to academic and scholarly sources, prioritizing peer-reviewed papers, journal articles, and research publications.
</Note>

## Overview

The academic filter—sometimes referred to as "academic mode" or "Focus: Academic"—is a feature in Perplexity that allows users to target their searches specifically to academic and scholarly sources. This is especially useful for students, researchers, and professionals who require peer-reviewed papers, journal articles, and research-focused answers rather than general web content.

When you activate the academic filter by setting `search_mode: "academic"`, Perplexity prioritizes results from scholarly databases, journals, and reputable academic publications, filtering out non-academic or general web sources. This ensures that the answers you receive are grounded in research and scholarly consensus.

## Key Features and Functionality

* **Source Filtering**: Prioritizes scholarly databases, academic journals, and research publications
* **Research Focus**: Returns results based on peer-reviewed research rather than general web content
* **Enhanced Precision**: Provides more technical and discipline-specific information for academic queries
* **Compatibility**: Works with other search parameters like `search_context_size` to further refine results

## Usage Examples

### Basic Academic Search

This example shows how to perform a basic search using the academic filter.

<CodeGroup>
  ```python 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 the lions mane mushroom?"}],
      search_mode="academic",
      web_search_options={"search_context_size": "low"}
  )

  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-pro",
    messages: [{"role": "user", "content": "What is the scientific name of the lions mane mushroom?"}],
    search_mode: "academic",
    web_search_options: {"search_context_size": "low"}
  });

  console.log(completion.choices[0].message.content);
  ```

  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.perplexity.ai/chat/completions \
    --header "accept: application/json" \
    --header "authorization: Bearer $SONAR_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?"}],
      "search_mode": "academic",
      "web_search_options": {"search_context_size": "low"}
  }' | jq
  ```
</CodeGroup>

### Combining Academic Mode with Other Parameters

You can combine the academic filter with other parameters for more refined searches:

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

  client = Perplexity()

  completion = client.chat.completions.create(
      model="sonar",
      messages=[{"role": "user", "content": "What are the latest findings on neural networks for image recognition?"}],
      search_mode="academic",
      search_after_date_filter="1/1/2023",
      web_search_options={"search_context_size": "high"}
  )

  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 are the latest findings on neural networks for image recognition?"}],
    search_mode: "academic",
    search_after_date_filter: "1/1/2023",
    web_search_options: {"search_context_size": "high"}
  });

  console.log(completion.choices[0].message.content);
  ```

  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.perplexity.ai/chat/completions \
    --header "accept: application/json" \
    --header "authorization: Bearer $SONAR_API_KEY" \
    --header "content-type: application/json" \
    --data '{
      "model": "sonar",
      "messages": [{"role": "user", "content": "What are the latest findings on neural networks for image recognition?"}],
      "stream": false,
      "search_mode": "academic",
      "search_after_date_filter": "1/1/2023",
      "web_search_options": {"search_context_size": "high"}
  }' | jq
  ```
</CodeGroup>

## Recommended Use Cases

The academic filter is particularly valuable for:

1. **Research Literature Reviews**: When you need to gather scholarly information on a specific topic
2. **Technical and Scientific Queries**: For questions requiring scientifically accurate, peer-reviewed answers
3. **Academic Writing Assistance**: When working on papers, theses, or dissertations that require scholarly sources
4. **Educational Support**: For students and educators requiring academically rigorous information

## Best Practices

### Optimizing Academic Searches

* **Be Specific**: Formulate clear, focused questions to receive more precise academic responses
* **Use Technical Terminology**: Include field-specific terms to better target relevant academic literature
* **Combine with Date Filters**: For the most recent research, combine with `search_after_date_filter`
* **Adjust Context Size**: Use higher `search_context_size` values for more comprehensive academic responses

### Performance Considerations

* Academic searches may sometimes take slightly longer due to the specialized nature of scholarly databases
* Consider using models like `sonar-deep-research` for particularly complex academic inquiries
* For more comprehensive literature reviews, set `stream: false` to receive complete responses

### Limitations

* Availability of academic sources varies by field and topic
* Very recent research (published within the last few months) may not always be included
* Some paywalled or subscription-only academic content may not be fully accessible

⸻


# API Key Management
Source: https://docs.perplexity.ai/guides/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.

<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://www.perplexity.ai/account/api/group)**

    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://www.perplexity.ai/account/api/keys)**

    You can create multiple keys within each group for different purposes or environments.
  </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 with optional naming for better organization.

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

<Note>
  Store the `auth_token` immediately and securely. This is the only time you'll be able to see the full token value.
</Note>

## 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 YOUR_API_KEY" \
    --header "Content-Type: application/json" \
    --data '{
      "auth_token": "pplx-1234567890abcdef"
    }'
  ```

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

  url = "https://api.perplexity.ai/revoke_auth_token"
  headers = {
      "Authorization": "Bearer YOUR_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 YOUR_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/chat/completions",
        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}/chat/completions"
          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}/chat/completions`, {
          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 cols={2}>
  <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">
    When generating keys, use the `token_name` parameter to identify their purpose and environment.

    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 your [API settings page](https://www.perplexity.ai/settings/api) or contact our support team.
</Info>


# Perplexity Crawlers
Source: https://docs.perplexity.ai/guides/bots

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>


# OpenAI Compatibility
Source: https://docs.perplexity.ai/guides/chat-completions-guide

Use Perplexity’s Sonar API with OpenAI’s client libraries for seamless integration.

## OpenAI compatibility at a glance

Perplexity's Sonar API was designed with OpenAI compatibility in mind, matching the Chat Completions API interface. You can seamlessly use your existing OpenAI client libraries by simply changing the base URL and providing your Perplexity API key.

<Tip>
  Keep using your existing OpenAI SDKs to get started fast; switch to our [native SDKs](/guides/perplexity-sdk) later as needed.
</Tip>

## Configuring OpenAI SDKs to call Sonar

To start using Sonar with OpenAI's client libraries, pass your Perplexity API key and change the base\_url to `https://api.perplexity.ai`:

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

    client = OpenAI(
        api_key="YOUR_API_KEY",
        base_url="https://api.perplexity.ai"
    )

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

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

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

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

<Check>
  Your responses will match OpenAI's format exactly. See the [response structure](#response-structure) section below for complete field details.
</Check>

## API compatibility

### Standard OpenAI parameters

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

* `model` - Model name (use Perplexity model names)
* `messages` - Chat messages array
* `temperature` - Sampling temperature (0-2)
* `max_tokens` - Maximum tokens in response
* `top_p` - Nucleus sampling parameter
* `frequency_penalty` - Frequency penalty (-2.0 to 2.0)
* `presence_penalty` - Presence penalty (-2.0 to 2.0)
* `stream` - Enable streaming responses

### Perplexity-specific parameters

These Perplexity-specific parameters are also included:

* `search_domain_filter` - Limit or exclude specific domains
* `search_recency_filter` - Filter by content recency
* `return_images` - Include image URLs in response
* `return_related_questions` - Include related questions
* `search_mode` - "web" (default) or "academic" mode selector.

<Info>See [API Reference](/api-reference) for parameter details and models.</Info>

## Examples with OpenAI's client libraries

### Basic Usage

Start with these simple examples to make your first API calls:

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

    client = OpenAI(
        api_key="YOUR_API_KEY",
        base_url="https://api.perplexity.ai"
    )

    response = client.chat.completions.create(
        model="sonar-pro",
        messages=[
            {"role": "user", "content": "What are the latest developments in AI?"}
        ]
    )

    print(response.choices[0].message.content)
    ```
  </Tab>

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

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

    const response = await client.chat.completions.create({
        model: "sonar-pro",
        messages: [
            { role: "user", content: "What are the latest developments in AI?" }
        ]
    });

    console.log(response.choices[0].message.content);
    ```
  </Tab>
</Tabs>

### Advanced Examples

For more control over search behavior and response generation:

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

      client = OpenAI(
          api_key="YOUR_API_KEY",
          base_url="https://api.perplexity.ai"
      )

      response = 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(response.choices[0].message.content)
      print(f"Sources: {len(response.search_results)} articles found")
      ```

      ```python Full Configuration theme={null}
      from openai import OpenAI

      client = OpenAI(
          api_key="YOUR_API_KEY",
          base_url="https://api.perplexity.ai"
      )

      response = client.chat.completions.create(
          model="sonar-pro",
          messages=[
              {"role": "system", "content": "Be precise and concise."},
              {"role": "user", "content": "How many stars are in our galaxy?"}
          ],
          temperature=0.2,
          max_tokens=1000,
          extra_body={
              "search_mode": "web",
              "search_domain_filter": ["nasa.gov", "space.com"],
              "return_related_questions": True
          }
      )

      print(response.choices[0].message.content)
      for result in response.search_results:
          print(f"- {result['title']}: {result['url']}")
      ```
    </CodeGroup>
  </Tab>

  <Tab title="TypeScript">
    <CodeGroup>
      ```typescript Search Filtering theme={null}
      import OpenAI from 'openai';

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

      const response = await client.chat.completions.create({
          model: "sonar-pro",
          messages: [
              { role: "user", content: "Latest climate research findings" }
          ],
          // TypeScript SDK: Use direct parameters (not extra_body)
          search_domain_filter: ["nature.com", "science.org"],
          search_recency_filter: "month"
      });

      console.log(response.choices[0].message.content);
      console.log(`Sources: ${response.search_results.length} articles found`);
      ```

      ```typescript Full Configuration theme={null}
      import OpenAI from 'openai';

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

      const response = await client.chat.completions.create({
          model: "sonar-pro",
          messages: [
              { role: "system", content: "Be precise and concise." },
              { role: "user", content: "How many stars are in our galaxy?" }
          ],
          temperature: 0.2,
          max_tokens: 1000,
          search_mode: "web",
          search_domain_filter: ["nasa.gov", "space.com"],
          return_related_questions: true
      });

      console.log(response.choices[0].message.content);
      response.search_results.forEach(result => {
          console.log(`- ${result.title}: ${result.url}`);
      });
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Response structure

Perplexity API responses include both standard OpenAI fields and additional search metadata:

### 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 titles, URLs, and dates
* `usage.search_context_size` - Search context setting used

<Tabs>
  <Tab title="Python">
    ```python  theme={null}
    # Access the main response
    content = response.choices[0].message.content
    print(content)

    # Access search sources
    for result in response.search_results:
        print(f"Source: {result['title']}")
        print(f"URL: {result['url']}")
        print(f"Date: {result['date']}")
        print("---")

    # Check token usage
    print(f"Tokens used: {response.usage.total_tokens}")
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript  theme={null}
    // Access the main response
    const content = response.choices[0].message.content;
    console.log(content);

    // Access search sources
    response.search_results.forEach(result => {
        console.log(`Source: ${result.title}`);
        console.log(`URL: ${result.url}`);
        console.log(`Date: ${result.date}`);
        console.log("---");
    });

    // Check token usage
    console.log(`Tokens used: ${response.usage.total_tokens}`);
    ```
  </Tab>
</Tabs>

<Info>
  Search results are returned even when streaming is enabled, but they arrive in the final chunk of the stream. See the [Streaming Guide](/guides/streaming-responses) for details.
</Info>

## Unsupported and notable differences

While compatibility is high, note the following differences from OpenAI:

* **Model names**: Use Perplexity models like `sonar-pro`, `sonar-reasoning`.
* **Search controls**: Perplexity adds web/academic search parameters via `extra_body` (Python) or root fields (TypeScript) as shown above.

<Warning>
  If you previously used OpenAI-only fields that aren't applicable to Perplexity search controls, remove or ignore them. Check the API Reference for the current list of supported fields.
</Warning>

## Technical notes

* **Error format**: Same as OpenAI's API for compatibility
* **Rate limiting**: Apply standard rate limiting practices
* **Model names**: Use Perplexity model names (`sonar-pro`, `sonar-reasoning`, etc.)
* **Authentication**: Use `Bearer` token format in Authorization header

## Next steps

<CardGroup cols={2}>
  <Card title="Explore Models" icon="brain" href="/getting-started/models">
    Browse available Sonar models and their capabilities.
  </Card>

  <Card title="Search Controls" icon="magnifying-glass" href="/guides/search-control-guide">
    Learn to fine-tune search behavior with filters and parameters.
  </Card>

  <Card title="Streaming Guide" icon="play" href="/guides/streaming-responses">
    Implement real-time streaming responses in your application.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference">
    View complete endpoint documentation and parameter details.
  </Card>
</CardGroup>


# Chat Completions SDK
Source: https://docs.perplexity.ai/guides/chat-completions-sdk

Use the Perplexity SDKs to access the Chat Completions API with type safety, streaming support, and modern language features.

## Overview

Generate AI responses with web-grounded knowledge using either the Python or TypeScript SDKs. Both SDKs provide full support for chat completions, streaming responses, async operations, and comprehensive error handling.

## Quick Start

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

    client = Perplexity()

    completion = client.chat.completions.create(
        messages=[
            {
                "role": "user",
                "content": "Tell me about the latest developments in AI",
            }
        ],
        model="sonar",
    )

    print(f"Response: {completion.choices[0].message.content}")
    ```
  </Tab>

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

    const client = new Perplexity();

    const completion = await client.chat.completions.create({
      messages: [
        {
          role: "user",
          content: "Tell me about the latest developments in AI",
        }
      ],
      model: "sonar",
    });

    console.log(`Response: ${completion.choices[0].message.content}`);
    ```
  </Tab>
</Tabs>

<Accordion title="Example Output">
  ```
  Response: Based on the latest information, here are some key developments in AI for 2024:

  **Large Language Models & Foundation Models:**
  - GPT-4 and its variants continue to improve with better reasoning capabilities
  - Open-source models like Llama 2 and Code Llama have gained significant traction
  - Specialized models for coding, math, and scientific tasks have emerged

  **Multimodal AI:**
  - Vision-language models can now process images, text, and audio simultaneously
  - Real-time image generation and editing capabilities have improved dramatically

  **AI Safety & Alignment:**
  - Constitutional AI and RLHF techniques are becoming standard practice
  - Increased focus on AI governance and regulatory frameworks...

  Request ID: req_123abc456def789
  ```
</Accordion>

## Features

### Model Selection

Choose from different Sonar models based on your needs:

<Tabs>
  <Tab title="Python SDK">
    ```python  theme={null}
    # Standard Sonar model for general queries
    completion = client.chat.completions.create(
        messages=[{"role": "user", "content": "What is quantum computing?"}],
        model="sonar"
    )

    # Sonar Pro for more complex queries
    completion = client.chat.completions.create(
        messages=[{"role": "user", "content": "Analyze the economic implications of renewable energy adoption"}],
        model="sonar-pro"
    )

    # Sonar Reasoning for complex analytical tasks
    completion = client.chat.completions.create(
        messages=[{"role": "user", "content": "Solve this complex mathematical problem step by step"}],
        model="sonar-reasoning"
    )
    ```
  </Tab>

  <Tab title="TypeScript SDK">
    ```typescript  theme={null}
    // Standard Sonar model for general queries
    const completion = await client.chat.completions.create({
      messages: [{ role: "user", content: "What is quantum computing?" }],
      model: "sonar"
    });

    // Sonar Pro for more complex queries
    const completion = await client.chat.completions.create({
      messages: [{ role: "user", content: "Analyze the economic implications of renewable energy adoption" }],
      model: "sonar-pro"
    });

    // Sonar Reasoning for complex analytical tasks
    const completion = await client.chat.completions.create({
      messages: [{ role: "user", content: "Solve this complex mathematical problem step by step" }],
      model: "sonar-reasoning"
    });
    ```
  </Tab>
</Tabs>

### Conversation Context

Build multi-turn conversations with context:

<Tabs>
  <Tab title="Python SDK">
    ```python  theme={null}
    messages = [
        {"role": "system", "content": "You are a helpful research assistant."},
        {"role": "user", "content": "What are the main causes of climate change?"},
        {"role": "assistant", "content": "The main causes of climate change include..."},
        {"role": "user", "content": "What are some potential solutions?"}
    ]

    completion = client.chat.completions.create(
        messages=messages,
        model="sonar"
    )
    ```
  </Tab>

  <Tab title="TypeScript SDK">
    ```typescript  theme={null}
    const messages: Perplexity.ChatMessage[] = [
      { role: "system", content: "You are a helpful research assistant." },
      { role: "user", content: "What are the main causes of climate change?" },
      { role: "assistant", content: "The main causes of climate change include..." },
      { role: "user", content: "What are some potential solutions?" }
    ];

    const completion = await client.chat.completions.create({
      messages,
      model: "sonar"
    });
    ```
  </Tab>
</Tabs>

### Web Search Options

Control how the model searches and uses web information:

<Tabs>
  <Tab title="Python SDK">
    ```python  theme={null}
    completion = client.chat.completions.create(
        messages=[
            {"role": "user", "content": "What are the latest developments in renewable energy?"}
        ],
        model="sonar",
        web_search_options={
            "search_recency_filter": "week",  # Focus on recent results
            "search_domain_filter": ["energy.gov", "iea.org", "irena.org"],  # Trusted sources
            "max_search_results": 10
        }
    )
    ```
  </Tab>

  <Tab title="TypeScript SDK">
    ```typescript  theme={null}
    const completion = await client.chat.completions.create({
      messages: [
        { role: "user", content: "What are the latest developments in renewable energy?" }
      ],
      model: "sonar",
      search_recency_filter: "week",  // Focus on recent results
      search_domain_filter: ["energy.gov", "iea.org", "irena.org"],  // Trusted sources
      return_images: true,  // Include image URLs
      return_related_questions: true  // Get follow-up questions
    });
    ```
  </Tab>
</Tabs>

### Response Customization

Customize response format and behavior:

<Tabs>
  <Tab title="Python SDK">
    ```python  theme={null}
    completion = client.chat.completions.create(
        messages=[
            {"role": "user", "content": "Explain machine learning in simple terms"}
        ],
        model="sonar",
        max_tokens=500,  # Limit response length
        temperature=0.7,  # Control creativity
        top_p=0.9,       # Control diversity
        presence_penalty=0.1,  # Reduce repetition
        frequency_penalty=0.1
    )
    ```
  </Tab>

  <Tab title="TypeScript SDK">
    ```typescript  theme={null}
    const completion = await client.chat.completions.create({
      messages: [
        { role: "user", content: "Explain machine learning in simple terms" }
      ],
      model: "sonar",
      max_tokens: 500,  // Limit response length
      temperature: 0.7,  // Control creativity (0-2)
      top_p: 0.9,       // Control diversity (0-1)
      presence_penalty: 0.1,  // Reduce repetition (-2 to 2)
      frequency_penalty: 0.1  // Reduce repetition (-2 to 2)
    });
    ```
  </Tab>
</Tabs>

### Streaming Responses

Get real-time response streaming for better user experience:

<Tabs>
  <Tab title="Python SDK">
    ```python  theme={null}
    stream = client.chat.completions.create(
        messages=[
            {"role": "user", "content": "Write a summary of recent AI breakthroughs"}
        ],
        model="sonar",
        stream=True
    )

    for chunk in stream:
        if chunk.choices[0].delta.content:
            print(chunk.choices[0].delta.content, end="")
    ```
  </Tab>

  <Tab title="TypeScript SDK">
    ```typescript  theme={null}
    const stream = await client.chat.completions.create({
      messages: [
        { role: "user", content: "Write a summary of recent AI breakthroughs" }
      ],
      model: "sonar",
      stream: true
    });

    for await (const chunk of stream) {
      if (chunk.choices[0]?.delta?.content) {
        process.stdout.write(chunk.choices[0].delta.content);
      }
    }
    ```
  </Tab>
</Tabs>

<Info>
  For comprehensive streaming documentation including metadata collection, error handling, advanced patterns, and raw HTTP examples, see the [Streaming Guide](/guides/streaming-responses).
</Info>

## Async Chat Completions

<Tip>
  Async chat completions are only available for the sonar-deep-research model.
</Tip>

For long-running or batch processing tasks, use the async endpoints:

### Creating Async Requests

<Tabs>
  <Tab title="Python SDK">
    ```python  theme={null}
    # Start an async completion request
    async_request = client.async_.chat.completions.create(
        messages=[
            {"role": "user", "content": "Write a comprehensive analysis of renewable energy trends"}
        ],
        model="sonar-deep-research",
        max_tokens=2000
    )

    print(f"Request submitted with ID: {async_request.request_id}")
    print(f"Status: {async_request.status}")
    ```
  </Tab>

  <Tab title="TypeScript SDK">
    ```typescript  theme={null}
    // Start an async completion request
    const asyncRequest = await client.async.chat.completions.create({
      messages: [
        { role: "user", content: "Write a comprehensive analysis of renewable energy trends" }
      ],
      model: "sonar-deep-reasearch",
      max_tokens: 2000
    });

    console.log(`Request submitted with ID: ${asyncRequest.request_id}`);
    console.log(`Status: ${asyncRequest.status}`);
    ```
  </Tab>
</Tabs>

### Checking Request Status

<Tabs>
  <Tab title="Python SDK">
    ```python  theme={null}
    # Check the status of an async request
    request_id = "req_123abc456def789"
    status = client.async_.chat.completions.get(request_id)

    print(f"Status: {status.status}")
    if status.status == "completed":
        print(f"Response: {status.result.choices[0].message.content}")
    elif status.status == "failed":
        print(f"Error: {status.error}")
    ```
  </Tab>

  <Tab title="TypeScript SDK">
    ```typescript  theme={null}
    // Check the status of an async request
    const requestId = "req_123abc456def789";
    const status = await client.async.chat.completions.get(requestId);

    console.log(`Status: ${status.status}`);
    if (status.status === "completed") {
      console.log(`Response: ${status.result?.choices[0]?.message?.content}`);
    } else if (status.status === "failed") {
      console.log(`Error: ${status.error}`);
    }
    ```
  </Tab>
</Tabs>

### Listing Async Requests

<Tabs>
  <Tab title="Python SDK">
    ```python  theme={null}
    # List recent async requests
    requests = client.async_.chat.completions.list(
        limit=10,
        status="completed"
    )

    for request in requests.data:
        print(f"ID: {request.id}, Status: {request.status}")
    ```
  </Tab>

  <Tab title="TypeScript SDK">
    ```typescript  theme={null}
    // List recent async requests
    const requests = await client.async.chat.completions.list({
      limit: 10,
      status: "completed"
    });

    requests.data.forEach(request => {
      console.log(`ID: ${request.id}, Status: ${request.status}`);
    });
    ```
  </Tab>
</Tabs>

## Advanced Usage

### Error Handling

Handle chat-specific errors:

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

    try:
        completion = client.chat.completions.create(
            messages=[{"role": "user", "content": "What is AI?"}],
            model="sonar",
            max_tokens=50000  # Exceeds limit
        )
    except perplexity.BadRequestError as e:
        print(f"Invalid request parameters: {e}")
    except perplexity.RateLimitError as e:
        print("Rate limit exceeded, please retry later")
    except perplexity.APIStatusError as e:
        print(f"API error: {e.status_code}")
    ```
  </Tab>

  <Tab title="TypeScript SDK">
    ```typescript  theme={null}
    try {
      const completion = await client.chat.completions.create({
        messages: [{ role: "user", content: "What is AI?" }],
        model: "sonar",
        max_tokens: 50000  // Exceeds limit
      });
    } catch (error) {
      if (error instanceof Perplexity.BadRequestError) {
        console.error(`Invalid request parameters: ${error.message}`);
      } 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}`);
      }
    }
    ```
  </Tab>
</Tabs>

### Custom Instructions

Use system messages for consistent behavior:

<Tabs>
  <Tab title="Python SDK">
    ```python  theme={null}
    system_prompt = """You are an expert research assistant specializing in technology and science. 
    Always provide well-sourced, accurate information and cite your sources. 
    Format your responses with clear headings and bullet points when appropriate."""

    completion = client.chat.completions.create(
        messages=[
            {"role": "system", "content": system_prompt},
            {"role": "user", "content": "Explain quantum computing applications"}
        ],
        model="sonar-pro"
    )
    ```
  </Tab>

  <Tab title="TypeScript SDK">
    ```typescript  theme={null}
    const systemPrompt = `You are an expert research assistant specializing in technology and science. 
    Always provide well-sourced, accurate information and cite your sources. 
    Format your responses with clear headings and bullet points when appropriate.`;

    const completion = await client.chat.completions.create({
      messages: [
        { role: "system", content: systemPrompt },
        { role: "user", content: "Explain quantum computing applications" }
      ],
      model: "sonar-pro"
    });
    ```
  </Tab>
</Tabs>

### Concurrent Operations

Handle multiple conversations efficiently:

<Tabs>
  <Tab title="Python SDK">
    ```python  theme={null}
    async def handle_multiple_chats(user_messages):
        client = AsyncPerplexity()
        
        tasks = [
            client.chat.completions.create(
                messages=[{"role": "user", "content": msg}],
                model="sonar-deep-reseach"
            )
            for msg in user_messages
        ]
        
        return await asyncio.gather(*tasks, return_exceptions=True)
    ```
  </Tab>

  <Tab title="TypeScript SDK">
    ```typescript  theme={null}
    async function processQuestions(questions: string[]) {
      const tasks = questions.map(question =>
        client.chat.completions.create({
          messages: [{ role: "user", content: question }],
          model: "sonar-deep-research"
        })
      );
      
      const results = await Promise.all(tasks);
      return results.map(result => result.choices[0].message.content);
    }

    const questions = [
      "What is artificial intelligence?",
      "How does machine learning work?",
      "What are neural networks?"
    ];

    const answers = await processQuestions(questions);
    ```
  </Tab>
</Tabs>

## Best Practices

<Steps>
  <Step title="Use appropriate models">
    Choose the right model for your use case: `sonar` for general queries, `sonar-pro` for complex analysis, `sonar-reasoning` for analytical tasks.

    <Tabs>
      <Tab title="Python SDK">
        ```python  theme={null}
        # For quick factual queries
        simple_query = client.chat.completions.create(
            messages=[{"role": "user", "content": "What is the capital of France?"}],
            model="sonar"
        )

        # For complex analysis
        complex_query = client.chat.completions.create(
            messages=[{"role": "user", "content": "Analyze the economic impact of AI on employment"}],
            model="sonar-pro"
        )
        ```
      </Tab>

      <Tab title="TypeScript SDK">
        ```typescript  theme={null}
        // For quick factual queries
        const simpleQuery = await client.chat.completions.create({
          messages: [{ role: "user", content: "What is the capital of France?" }],
          model: "sonar"
        });

        // For complex analysis
        const complexQuery = await client.chat.completions.create({
          messages: [{ role: "user", content: "Analyze the economic impact of AI on employment" }],
          model: "sonar-pro"
        });
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Implement streaming for long responses">
    Use streaming for better user experience with lengthy responses.

    <Tabs>
      <Tab title="Python SDK">
        ```python  theme={null}
        def stream_response(query):
            stream = client.chat.completions.create(
                messages=[{"role": "user", "content": query}],
                model="sonar",
                stream=True
            )
            
            response = ""
            for chunk in stream:
                if chunk.choices[0].delta.content:
                    content = chunk.choices[0].delta.content
                    print(content, end="", flush=True)
                    response += content
            
            return response
        ```
      </Tab>

      <Tab title="TypeScript SDK">
        ```typescript  theme={null}
        async function streamResponse(query: string): Promise<string> {
          const stream = await client.chat.completions.create({
            messages: [{ role: "user", content: query }],
            model: "sonar",
            stream: true
          });
          
          let response = "";
          for await (const chunk of stream) {
            if (chunk.choices[0]?.delta?.content) {
              const content = chunk.choices[0].delta.content;
              process.stdout.write(content);
              response += content;
            }
          }
          
          return response;
        }
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Handle rate limits gracefully">
    Implement exponential backoff for production applications.

    <Tabs>
      <Tab title="Python SDK">
        ```python  theme={null}
        import time
        import random

        def chat_with_retry(messages, max_retries=3):
            for attempt in range(max_retries):
                try:
                    return client.chat.completions.create(
                        messages=messages,
                        model="sonar"
                    )
                except perplexity.RateLimitError:
                    if attempt == max_retries - 1:
                        raise
                    delay = (2 ** attempt) + random.uniform(0, 1)
                    time.sleep(delay)
        ```
      </Tab>

      <Tab title="TypeScript SDK">
        ```typescript  theme={null}
        async function chatWithRetry(
          messages: Perplexity.ChatMessage[], 
          maxRetries: number = 3
        ): Promise<Perplexity.Chat.CompletionCreateResponse> {
          for (let attempt = 0; attempt < maxRetries; attempt++) {
            try {
              return await client.chat.completions.create({
                messages,
                model: "sonar"
              });
            } catch (error) {
              if (error instanceof Perplexity.RateLimitError && attempt < maxRetries - 1) {
                const delay = Math.pow(2, attempt) * 1000 + Math.random() * 1000;
                await new Promise(resolve => setTimeout(resolve, delay));
                continue;
              }
              throw error;
            }
          }
          throw new Error("Max retries exceeded");
        }
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Optimize for specific use cases">
    Configure parameters based on your application's needs.

    <Tabs>
      <Tab title="Python SDK">
        ```python  theme={null}
        # For factual Q&A
        factual_config = {
            "temperature": 0.1,  # Low creativity for accuracy
            "top_p": 0.9,
            "search_recency_filter": "month"
        }

        # For creative writing
        creative_config = {
            "temperature": 0.8,  # Higher creativity
            "top_p": 0.95,
            "presence_penalty": 0.1,
            "frequency_penalty": 0.1
        }

        # Usage
        factual_response = client.chat.completions.create(
            messages=[{"role": "user", "content": "What is the current inflation rate?"}],
            model="sonar",
            **factual_config
        )
        ```
      </Tab>

      <Tab title="TypeScript SDK">
        ```typescript  theme={null}
        // For factual Q&A
        const factualConfig = {
          temperature: 0.1,  // Low creativity for accuracy
          top_p: 0.9,
          search_recency_filter: "month" as const
        };

        // For creative writing
        const creativeConfig = {
          temperature: 0.8,  // Higher creativity
          top_p: 0.95,
          presence_penalty: 0.1,
          frequency_penalty: 0.1
        };

        // Usage
        const factualResponse = await client.chat.completions.create({
          messages: [{ role: "user", content: "What is the current inflation rate?" }],
          model: "sonar",
          ...factualConfig
        });
        ```
      </Tab>
    </Tabs>
  </Step>
</Steps>

## Resources

* [The Perplexity SDK Guide](/guides/perplexity-sdk) - The Perplexity SDK guide
* [OpenAI Compatibility](/guides/chat-completions-guide) - OpenAI compatibility guide
* [Streaming Responses](/guides/streaming-responses) - Complete streaming guide with advanced patterns
* [API Reference - Chat Completions](/api-reference/chat-completions-post) - Chat Completions API Reference
* [API Reference - Async Chat Completions](/api-reference/async-chat-completions-post) - Async API Reference
* [Structured Outputs](/guides/structured-outputs) - Formatted response generation


# Sonar Date and Time Filters
Source: https://docs.perplexity.ai/guides/date-range-filter-guide



<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., "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 "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 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 day, week, month, or year
* Get recent results without specifying exact dates
* Quickly filter for timely information

**Available values:**

* `"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:** These filter types target different dates—publication filters use the original creation/publication date, while last updated filters use the modification date, and 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": "3/1/2025",
"last_updated_before_filter": "3/5/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 (for example, domain filters).

## 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()

  completion = client.chat.completions.create(
      model="sonar",
      messages=[
          {"role": "system", "content": "You are an expert on current events."},
          {"role": "user", "content": "Show me tech news published this week."}
      ],
      search_after_date_filter="3/1/2025",
      search_before_date_filter="3/5/2025"
  )

  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": "system", "content": "You are an expert on current events."},
      {"role": "user", "content": "Show me tech news published this week."}
    ],
    search_after_date_filter: "3/1/2025",
    search_before_date_filter: "3/5/2025"
  });

  console.log(completion.choices[0].message.content);
  ```

  ```bash cURL theme={null}
  curl --location 'https://api.perplexity.ai/chat/completions' \
    --header "Authorization: Bearer $SONAR_API_KEY" \
    --header "Content-Type: application/json" \
    --data '{
      "model": "sonar",
      "messages": [
        {"role": "system", "content": "You are an expert on current events."},
        {"role": "user", "content": "Show me tech news published this week."}
      ],
      "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`:

```bash  theme={null}
payload = {
    "model": "sonar-pro",
    "messages": [
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Show me news articles published after March 1, 2025."}
    ],
    "search_after_date_filter": "3/1/2025"
}
```

**3. Filtering by Last Updated Date Range**

This example limits search results to content that was last updated between March 1, 2025, and March 5, 2025. This is useful for finding recently maintained or refreshed content.

**Request Example**

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

  client = Perplexity()

  completion = client.chat.completions.create(
      model="sonar-pro",
      messages=[
          {"role": "system", "content": "You are an expert on current events."},
          {"role": "user", "content": "Show me recently updated tech articles."}
      ],
      last_updated_after_filter="3/1/2025",
      last_updated_before_filter="3/5/2025"
  )

  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-pro",
    messages: [
      {"role": "system", "content": "You are an expert on current events."},
      {"role": "user", "content": "Show me recently updated tech articles."}
    ],
    last_updated_after_filter: "3/1/2025",
    last_updated_before_filter: "3/5/2025"
  });

  console.log(completion.choices[0].message.content);
  ```

  ```bash cURL theme={null}
  curl --location 'https://api.perplexity.ai/chat/completions' \
    --header "Authorization: Bearer $SONAR_API_KEY" \
    --header "Content-Type: application/json" \
    --data '{
      "model": "sonar-pro",
      "messages": [
        {"role": "system", "content": "You are an expert on current events."},
        {"role": "user", "content": "Show me recently updated tech articles."}
      ],
      "last_updated_after_filter": "3/1/2025",
      "last_updated_before_filter": "3/5/2025"
  }' | jq
  ```
</CodeGroup>

**4. Combining Publication and Last Updated Filters**

You can combine both filter types to find content that was published in one timeframe and updated in another:

```bash  theme={null}
payload = {
    "model": "sonar-pro",
    "messages": [
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Show me articles published last year but updated recently."}
    ],
    "search_after_date_filter": "1/1/2024",
    "search_before_date_filter": "12/31/2024",
    "last_updated_after_filter": "3/1/2025"
}
```

**5. 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()

  completion = client.chat.completions.create(
      model="sonar-pro",
      messages=[
          {"role": "system", "content": "You are an expert on current events."},
          {"role": "user", "content": "What are the latest AI developments?"}
      ],
      search_recency_filter="week"
  )

  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-pro",
    messages: [
      {"role": "system", "content": "You are an expert on current events."},
      {"role": "user", "content": "What are the latest AI developments?"}
    ],
    search_recency_filter: "week"
  });

  console.log(completion.choices[0].message.content);
  ```

  ```bash cURL theme={null}
  curl --location 'https://api.perplexity.ai/chat/completions' \
    --header "Authorization: Bearer $SONAR_API_KEY" \
    --header "Content-Type: application/json" \
    --data '{
      "model": "sonar-pro",
      "messages": [
        {"role": "system", "content": "You are an expert on current events."},
        {"role": "user", "content": "What are the latest AI developments?"}
      ],
      "search_recency_filter": "week"
  }' | jq
  ```
</CodeGroup>

This example will return only content from the past 7 days, automatically calculated from the current date.

## Best Practices

**Date Format**

* Strict Format: Dates must match the “%m/%d/%Y” format exactly. For example, the date “3/1/2025” or “03/01/2025” is acceptable.
* Consistency: Use one or both 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 other date filters.

**Client-Side Validation**

* Regex Check: Validate date strings on the client side (or via the API) 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).

⸻

## Last Updated Date Filters

The `last_updated_after_filter` and `last_updated_before_filter` parameters provide powerful filtering capabilities based on when content was last modified or updated, rather than when it was originally published. This is particularly useful for finding recently maintained, refreshed, or updated content.

### Parameters

**`last_updated_after_filter`**

* Filters search results to only include content last updated after this date
* Format should be %m/%d/%Y (e.g. 3/1/2025)
* Optional parameter

**`last_updated_before_filter`**

* Filters search results to only include content last updated before this date
* Format should be %m/%d/%Y (e.g. 3/1/2025)
* Optional parameter

### Use Cases

**Content Freshness**: Find articles, documentation, or resources that have been recently updated to ensure you're getting the most current information.

**Maintenance Tracking**: Identify which content has been actively maintained within a specific timeframe.

**Quality Assurance**: Focus on content that has been refreshed recently, which often indicates higher quality and relevance.

### Code Examples

**1. Find Recently Updated Content (After a Specific Date)**

<CodeGroup>
  ```bash cURL theme={null}
  curl --location 'https://api.perplexity.ai/chat/completions' \
    --header "Authorization: Bearer $SONAR_API_KEY" \
    --header "Content-Type: application/json" \
    --data '{
      "model": "sonar-pro",
      "messages": [
        {"role": "system", "content": "You are a helpful assistant focused on current information."},
        {"role": "user", "content": "Find me documentation that has been updated recently."}
      ],
      "last_updated_after_filter": "1/1/2025"
  }' | jq
  ```

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

  url = "https://api.perplexity.ai/chat/completions"
  headers = {"Authorization": "Bearer YOUR_API_KEY"}
  payload = {
      "model": "sonar-pro",
      "messages": [
          {"role": "system", "content": "You are a helpful assistant focused on current information."},
          {"role": "user", "content": "Find me documentation that has been updated recently."}
      ],
      "last_updated_after_filter": "1/1/2025"
  }

  response = requests.post(url, headers=headers, json=payload)
  print(response.json())
  ```

  ```javascript javascript theme={null}
  const response = await fetch('https://api.perplexity.ai/chat/completions', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      model: 'sonar-pro',
      messages: [
        {role: 'system', content: 'You are a helpful assistant focused on current information.'},
        {role: 'user', content: 'Find me documentation that has been updated recently.'}
      ],
      last_updated_after_filter: '1/1/2025'
    })
  });

  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

**2. Find Content Updated Within a Specific Window**

<CodeGroup>
  ```bash cURL theme={null}
  curl --location 'https://api.perplexity.ai/chat/completions' \
    --header "Authorization: Bearer $SONAR_API_KEY" \
    --header "Content-Type: application/json" \
    --data '{
      "model": "sonar-pro",
      "messages": [
        {"role": "system", "content": "You are an expert on technology trends."},
        {"role": "user", "content": "Show me tech articles that were updated last week."}
      ],
      "last_updated_after_filter": "2/24/2025",
      "last_updated_before_filter": "3/3/2025"
  }' | jq
  ```

  ```python python theme={null}
  import requests
  from datetime import datetime, timedelta

  # Calculate dates for last week
  today = datetime.now()
  week_ago = today - timedelta(days=7)

  url = "https://api.perplexity.ai/chat/completions"
  headers = {"Authorization": "Bearer YOUR_API_KEY"}
  payload = {
      "model": "sonar-pro",
      "messages": [
          {"role": "system", "content": "You are an expert on technology trends."},
          {"role": "user", "content": "Show me tech articles that were updated last week."}
      ],
      "last_updated_after_filter": week_ago.strftime("%m/%d/%Y"),
      "last_updated_before_filter": today.strftime("%m/%d/%Y")
  }

  response = requests.post(url, headers=headers, json=payload)
  print(response.json())
  ```
</CodeGroup>

**3. Exclude Recently Updated Content (Before a Date)**

<CodeGroup>
  ```bash cURL theme={null}
  curl --location 'https://api.perplexity.ai/chat/completions' \
    --header "Authorization: Bearer $SONAR_API_KEY" \
    --header "Content-Type: application/json" \
    --data '{
      "model": "sonar-pro",
      "messages": [
        {"role": "system", "content": "You are a research assistant."},
        {"role": "user", "content": "Find historical content that hasn'\''t been updated recently."}
      ],
      "last_updated_before_filter": "1/1/2024"
  }' | jq 
  ```

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

  url = "https://api.perplexity.ai/chat/completions"
  headers = {"Authorization": "Bearer YOUR_API_KEY"}
  payload = {
      "model": "sonar-pro",
      "messages": [
          {"role": "system", "content": "You are a research assistant."},
          {"role": "user", "content": "Find historical content that hasn't been updated recently."}
      ],
      "last_updated_before_filter": "1/1/2024"
  }

  response = requests.post(url, headers=headers, json=payload)
  print(response.json())
  ```
</CodeGroup>

### Advanced Usage Patterns

**Combining with Domain Filters**

```python  theme={null}
payload = {
    "model": "sonar-pro",
    "messages": [
        {"role": "user", "content": "Latest updates on AI research."}
    ],
    "search_domain_filter": ["arxiv.org", "openai.com"],
    "last_updated_after_filter": "2/1/2025"
}
```

**Finding Maintained vs. Stale Content**

```python  theme={null}
# Find actively maintained content
recent_payload = {
    "model": "sonar-pro",
    "messages": [
        {"role": "user", "content": "Current best practices for React development."}
    ],
    "last_updated_after_filter": "1/1/2025"
}

# Find potentially outdated content
stale_payload = {
    "model": "sonar-pro",
    "messages": [
        {"role": "user", "content": "React development practices."}
    ],
    "last_updated_before_filter": "1/1/2023"
}
```

### Tips for Last Updated Filters

1. **Content Freshness Strategy**: Use `last_updated_after_filter` when you need the most current information on rapidly evolving topics.

2. **Quality Indicator**: Recently updated content often indicates active maintenance and higher reliability.

3. **Research Applications**: Combine with publication date filters to find content published years ago but updated recently, indicating ongoing relevance.

4. **Performance**: These filters can significantly improve response relevance by focusing on maintained content.

5. **Date Selection**: Choose update date ranges based on your content type - technical documentation might need monthly updates, while academic papers might be updated annually.


# File Attachments with Sonar
Source: https://docs.perplexity.ai/guides/file-attachments

Learn how to upload and analyze documents (PDF, DOC, DOCX, TXT, RTF) using Sonar models

## Overview

Sonar models support document analysis through file uploads. You can provide files either as URLs to publicly accessible documents or as base64 encoded bytes. Ask questions about document content, get summaries, extract information, and perform detailed analysis of uploaded files in multiple formats including PDF, DOC, DOCX, TXT, and RTF.

<Note>
  **SDK Installation Required**: Install the official SDK first - `pip install perplexityai` for Python or `npm install @perplexity-ai/perplexity_ai` for TypeScript/JavaScript.
</Note>

<Note>
  Document files can be provided as:

  * A public URL pointing to the file
  * Base64 encoded bytes (without any prefix)

  Supported formats: PDF, DOC, DOCX, TXT, RTF.
</Note>

<Warning>
  The maximum file size is 50MB. Files larger than this limit will not be processed.
</Warning>

## Supported Features

* **Document Summarization**: Get concise summaries of document content
* **Question Answering**: Ask specific questions about the document
* **Content Extraction**: Extract key information, data, and insights
* **Multi-language Support**: Analyze documents in various languages
* **Large Document Handling**: Process lengthy documents efficiently
* **Multiple Formats**: Support for PDF, DOC, DOCX, TXT, and RTF files

## Basic Usage

### Simple Document Analysis

#### Using a Public URL

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.perplexity.ai/chat/completions" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "messages": [
        {
          "content": [
            {
              "type": "text",
              "text": "Summarize this document"
            },
            {
              "type": "file_url",
              "file_url": {
                "url": "https://example.com/document.pdf"
              },
            }
          ],
          "role": "user"
        }
      ],
      "model": "sonar-pro"
    }'
  ```

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

  # Initialize the client (uses PERPLEXITY_API_KEY environment variable)
  client = Perplexity()

  # Analyze the document
  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 the response
  print(completion.choices[0].message.content)
  ```

  ```javascript JavaScript theme={null}
  const Perplexity = require('@perplexity-ai/perplexity_ai');

  // Initialize the client (uses PERPLEXITY_API_KEY environment variable)
  const client = new Perplexity();

  // Analyze the document
  const completion = await 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'
                      },
                      file_name: 'document.pdf'
                  }
              ]
          }
      ]
  });

  // Print the response
  console.log(completion.choices[0].message.content);
  ```

  ```go Go theme={null}
  package main

  import (
      "bytes"
      "encoding/json"
      "fmt"
      "net/http"
  )

  func main() {
      url := "https://api.perplexity.ai/chat/completions"
      
      payload := map[string]interface{}{
          "messages": []map[string]interface{}{
              {
                  "content": []map[string]interface{}{
                      {
                          "type": "text",
                          "text": "Summarize this document",
                      },
                      {
                          "type": "file_url",
                          "file_url": map[string]string{
                              "url": "https://example.com/document.pdf",
                          },
                      },
                  },
                  "role": "user",
              },
          },
          "model": "sonar-pro",
      }
      
      jsonData, _ := json.Marshal(payload)
      req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
      req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
      req.Header.Set("Content-Type", "application/json")
      
      client := &http.Client{}
      resp, _ := client.Do(req)
  }
  ```
</CodeGroup>

#### Using Base64 Encoded Bytes

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.perplexity.ai/chat/completions" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "messages": [
        {
          "content": [
            {
              "type": "text",
              "text": "Summarize this document"
            },
            {
              "type": "file_url",
              "file_url": {
                "url": "JVBERi0xLjQKJeLjz9MKNCAwIG9iago..."
              },
              "file_name": "report.pdf"
            }
          ],
          "role": "user"
        }
      ],
      "model": "sonar-pro"
    }'
  ```

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

  # Initialize the client
  client = Perplexity()

  # Read and encode file
  with open("document.pdf", "rb") as file:
      file_data = file.read()
      encoded_file = base64.b64encode(file_data).decode('utf-8')

  # Analyze the document
  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 the base64 string, no prefix
                      },
                  }
              ]
          }
      ]
  )

  print(completion.choices[0].message.content)
  ```

  ```javascript JavaScript theme={null}
  const Perplexity = require('@perplexity-ai/perplexity_ai');
  const fs = require('fs');

  // Initialize the client
  const client = new Perplexity();

  // Read and encode file
  const fileData = fs.readFileSync('document.pdf');
  const encodedFile = fileData.toString('base64');

  // Analyze the document
  const completion = await client.chat.completions.create({
      model: 'sonar-pro',
      messages: [
          {
              role: 'user',
              content: [
                  {
                      type: 'text',
                      text: 'Summarize this document'
                  },
                  {
                      type: 'file_url',
                      file_url: {
                          url: encodedFile  // Just the base64 string, no prefix
                      },
                      file_name: 'document.pdf'
                  }
              ]
          }
      ]
  });

  console.log(completion.choices[0].message.content);
  ```
</CodeGroup>

### Advanced Analysis with Web Search

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.perplexity.ai/chat/completions" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "messages": [
        {
          "content": [
            {
              "type": "text",
              "text": "What are the key findings in this research paper? Provide additional context from recent studies."
            },
            {
              "type": "file_url",
              "file_url": {
                "url": "https://example.com/research-paper.pdf"
              },
              "file_name": "research-paper.pdf"
            }
          ],
          "role": "user"
        }
      ],
      "model": "sonar-pro"
    }'
  ```

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

  # Initialize the client
  client = Perplexity()

  # Analyze the document with web search
  completion = client.chat.completions.create(
      model="sonar-pro",
      messages=[
          {
              "role": "user",
              "content": [
                  {
                      "type": "text",
                      "text": "What are the key findings in this research paper? Provide additional context from recent studies."
                  },
                  {
                      "type": "file_url",
                      "file_url": {
                          "url": "https://example.com/research-paper.pdf"
                      },
                      "file_name": "research-paper.pdf"
                  }
              ]
          }
      ]
  )

  # Print the response
  print(completion.choices[0].message.content)
  ```

  ```javascript JavaScript theme={null}
  const Perplexity = require('@perplexity-ai/perplexity_ai');

  // Initialize the client
  const client = new Perplexity();

  // Analyze the document with web search
  const completion = await client.chat.completions.create({
      model: 'sonar-pro',
      messages: [
          {
              role: 'user',
              content: [
                  {
                      type: 'text',
                      text: 'What are the key findings in this research paper? Provide additional context from recent studies.'
                  },
                  {
                      type: 'file_url',
                      file_url: {
                          url: 'https://example.com/research-paper.pdf'
                      },
                      file_name: 'research-paper.pdf'
                  }
              ]
          }
      ]
  });

  // Print the response
  console.log(completion.choices[0].message.content);
  ```
</CodeGroup>

## File Requirements

<CardGroup cols={2}>
  <Card title="Format Support" icon="check">
    * PDF files (.pdf extension)
    * Word documents (.doc, .docx extensions)
    * Text files (.txt extension)
    * Rich Text Format (.rtf extension)
    * Text-based documents (not scanned images)
    * Base64 encoded file bytes
    * Password-protected files (if publicly accessible)
  </Card>

  <Card title="Size Limits" icon="scale-balanced">
    * Maximum file size: 50MB
    * Recommended: Under 50MB for optimal performance
    * Maximum processing time: 60 seconds
    * Large files may take longer to analyze
  </Card>
</CardGroup>

## Common Use Cases

### Academic Research

```python  theme={null}
question = "What methodology was used in this study and what were the main conclusions?"
```

### Legal Documents

```python  theme={null}
question = "Extract the key terms and conditions from this contract"
```

### Financial Reports

```python  theme={null}
question = "What are the revenue trends and key financial metrics mentioned?"
```

### Technical Documentation

```python  theme={null}
question = "Explain the implementation details and provide a step-by-step guide"
```

## Best Practices

<AccordionGroup>
  <Accordion title="Optimize Your Questions">
    * Be specific about what information you need
    * Ask one focused question per request for best results
    * Use follow-up questions to dive deeper into specific sections
  </Accordion>

  <Accordion title="Prepare Your Documents">
    * Ensure documents are text-based, not scanned images
    * For URLs: Use publicly accessible URLs (Google Drive, Dropbox, etc.)
    * For URLs: Verify the URL returns the document directly, not a preview page
    * For base64: Encode the entire file content properly
    * For base64: Provide only the base64 string without any prefix (no `data:` URI scheme)
  </Accordion>

  <Accordion title="Handle Large Documents">
    * Break down complex questions into smaller parts
    * Consider processing large documents in sections
    * Use streaming for real-time responses on lengthy analyses
  </Accordion>
</AccordionGroup>

## Error Handling

### Common Issues

| Error                | Cause                                | Solution                                                  |
| -------------------- | ------------------------------------ | --------------------------------------------------------- |
| `Invalid URL`        | URL not accessible or invalid base64 | Verify URL returns file directly or check base64 encoding |
| `File too large`     | File exceeds 50MB limit              | Compress or split the document                            |
| `Processing timeout` | Document too complex                 | Simplify question or use smaller sections                 |
| `Invalid base64`     | Malformed base64 string              | Ensure proper base64 encoding without prefix              |

## Pricing

PDF analysis follows standard Sonar pricing based on:

* Input tokens (document content + question)
* Output tokens (AI response)
* Web search usage (if enabled)

<Tip>
  Large documents consume more input tokens. Consider the document size when estimating costs.
</Tip>


# Image Attachments with Sonar
Source: https://docs.perplexity.ai/guides/image-attachments

Learn how to upload and analyze images using Sonar models

## Overview

Sonar models support image analysis through direct image uploads. You can include images in your API requests to support multi-modal conversations alongside text. Images can be provided either as base64 encoded strings within a data URI or as standard HTTPS URLs.

<Note>
  **SDK Installation Required**: Install the official SDK first - `pip install perplexityai` for Python or `npm install @perplexity-ai/perplexity_ai` for TypeScript/JavaScript.
</Note>

<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>

## Supported Features

Image uploads can be useful for:

* **Visual Question Answering**: Ask questions about visual content (e.g., text in a screenshot, diagram interpretation)
* **Context Analysis**: Providing context for follow-up queries
* **Multi-modal Conversations**: Analyzing visual media as part of a multi-turn conversation
* **Content Description**: Get detailed descriptions of images
* **Text Extraction**: Extract text from images and documents

## Upload Methods

You can include images in your requests using two methods:

### 1. Base64 Data URI

Encode the image as a base64 string and embed it in a data URI:

```
data:image/png;base64,<BASE64_ENCODED_IMAGE>
```

Replace `image/png` with the correct MIME type if you're using JPEG or GIF (`image/jpeg` or `image/gif`).

### 2. HTTPS URL

Provide a standard HTTPS URL pointing directly to the image file:

```
https://example.com/path/to/your/image.png
```

## Request Format

Images must be embedded in the `messages` array, alongside any text input. Each image should be provided using the following structure:

**Using Base64 Data URI:**

```json  theme={null}
{
  "type": "image_url",
  "image_url": {
    "url": "data:image/png;base64,<BASE64_ENCODED_IMAGE>"
  }
}
```

**Using HTTPS URL:**

```json  theme={null}
{
  "type": "image_url",
  "image_url": {
    "url": "https://example.com/path/to/your/image.png"
  }
}
```

## Basic Usage

<Tabs>
  <Tab title="Base64 Encoding">
    <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>
      ```bash cURL theme={null}
      curl --location 'https://api.perplexity.ai/chat/completions' \
        --header 'accept: application/json' \
        --header 'content-type: application/json' \
        --header "Authorization: Bearer $SONAR_API_KEY" \
        --data '{
          "model": "sonar-pro",
          "stream": false,
          "messages": [
            {
              "role": "user",
              "content": [
                {
                  "type": "text",
                  "text": "Can you describe this image?"
                },
                {
                  "type": "image_url",
                  "image_url": {
                    "url": "data:image/png;base64,$BASE64_ENCODED_IMAGE"
                  }
                }
              ]
            }
          ]
        }' | jq
      ```

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

      # Initialize the client
      client = Perplexity()

      # Read and encode image as base64
      try:
          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}"  # Ensure correct MIME type
      except FileNotFoundError:
          print("Error: Image file not found.")
          exit()

      # Analyze the image
      try:
          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)
      except Exception as e:
          print(f"API Request failed: {e}")
      ```

      ```javascript JavaScript theme={null}
      const Perplexity = require('@perplexity-ai/perplexity_ai');
      const fs = require('fs');

      // Initialize the client
      const client = new Perplexity();

      // Read and encode image as base64
      try {
          const imageBuffer = fs.readFileSync('path/to/your/image.png');
          const base64Image = imageBuffer.toString('base64');
          const imageDataUri = `data:image/png;base64,${base64Image}`;
          
          // Analyze the image
          const completion = await 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: imageDataUri } }
                      ]
                  }
              ]
          });
          
          console.log(completion.choices[0].message.content);
      } catch (error) {
          console.error('Error:', error.message);
      }
      ```

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

      // Initialize the client
      const client = new Perplexity();

      // Read and encode image as base64
      try {
          const imageBuffer = fs.readFileSync('path/to/your/image.png');
          const base64Image = imageBuffer.toString('base64');
          const imageDataUri = `data:image/png;base64,${base64Image}`;
          
          // Analyze the image
          const completion = await 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: imageDataUri } }
                      ]
                  }
              ]
          });
          
          console.log(completion.choices[0].message.content);
      } catch (error) {
          console.error('Error:', error.message);
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="HTTPS URL">
    <Info>Use this method to reference an image hosted online. Ensure the URL is publicly accessible and points directly to the image file.</Info>

    <CodeGroup>
      ```bash cURL theme={null}
      curl --location 'https://api.perplexity.ai/chat/completions' \
        --header "accept: application/json" \
        --header "content-type: application/json" \
        --header "Authorization: Bearer $SONAR_API_KEY" \
        --data '{
          "model": "sonar-pro",
          "stream": false,
          "messages": [
            {
              "role": "user",
              "content": [
                {
                  "type": "text",
                  "text": "Can you describe the image at this URL?"
                },
                {
                  "type": "image_url",
                  "image_url": {
                    "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
      ```

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

      # Initialize the client
      client = Perplexity()

      # Example HTTPS URL
      image_https_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
      try:
          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_https_url}}
                      ]
                  }
              ]
          )
          print(completion.choices[0].message.content)
      except Exception as e:
          print(f"API Request failed: {e}")
      ```

      ```javascript JavaScript theme={null}
      const Perplexity = require('@perplexity-ai/perplexity_ai');

      // Initialize the client
      const client = new Perplexity();

      // Example HTTPS URL
      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
      try {
          const completion = await 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: imageHttpsUrl } }
                      ]
                  }
              ]
          });
          
          console.log(completion.choices[0].message.content);
      } catch (error) {
          console.error('API Request failed:', error.message);
      }
      ```

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

      // Initialize the client
      const client = new Perplexity();

      // Example HTTPS URL
      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 analyzeImage = async (): Promise<void> => {
          try {
              const completion = await 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: imageHttpsUrl } }
                          ]
                      }
                  ]
              });
              
              console.log(completion.choices[0].message.content);
          } catch (error) {
              console.error('API Request failed:', error.message);
          }
      };

      analyzeImage();
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Common Use Cases

### Screenshot Analysis

```python  theme={null}
question = "What text is visible in this screenshot?"
```

### Diagram Interpretation

```python  theme={null}
question = "Explain the workflow shown in this diagram"
```

### Product Analysis

```python  theme={null}
question = "Describe the features and specifications of this product"
```

### Document Processing

```python  theme={null}
question = "Extract all the key information from this document image"
```

## Best Practices

<AccordionGroup>
  <Accordion title="Image Quality Guidelines">
    * Use high-resolution images for better text extraction
    * Ensure good contrast for text recognition
    * Avoid heavily compressed images when detail is important
    * Use appropriate image formats (PNG for screenshots, JPEG for photos)
  </Accordion>

  <Accordion title="File Size Optimization">
    * Keep images under 50MB for base64 encoding
    * Compress images when possible without losing critical detail
    * Consider using HTTPS URLs for very large images
    * Use WebP format for balanced quality and size
  </Accordion>

  <Accordion title="URL Best Practices">
    * Ensure URLs are publicly accessible (no authentication required)
    * Use direct links to image files, not web pages
    * Test URLs in a browser before using in API calls
    * Consider using CDNs for reliable image hosting
  </Accordion>
</AccordionGroup>

## 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 (e.g., `sonar-pro`, `sonar`, etc.). The image tokens are added to your total token count for the request alongside any text tokens.

<Tip>
  To optimize costs, resize images to the minimum resolution needed for your use case while maintaining adequate quality.
</Tip>

## Limitations

<Warning>
  * Image and regex cannot be used together in the same request
  * `sonar-deep-research` does not support image input
  * Ensure provided HTTPS URLs are publicly accessible
  * Base64 images have a 50MB size limit
  * Supported formats: PNG, JPEG, WEBP, and GIF
</Warning>


# Sonar Language Filter Guide
Source: https://docs.perplexity.ai/guides/language-filter-guide



<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 Sonar models allows you to control which search results are returned by limiting them to specific languages. This is particularly useful when you need to:

* Generate responses based on 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()

  completion = client.chat.completions.create(
      model="sonar",
      messages=[
          {"role": "system", "content": "You are a helpful assistant."},
          {"role": "user", "content": "Tell me about recent AI developments."}
      ],
      search_language_filter=["en"]
  )

  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": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Tell me about recent AI developments."}
    ],
    search_language_filter: ["en"]
  });

  console.log(completion.choices[0].message.content);
  ```

  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.perplexity.ai/chat/completions \
    --header "Authorization: Bearer YOUR_API_KEY" \
    --header "Content-Type: application/json" \
    --data '{
      "model": "sonar",
      "messages": [
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Tell me about recent AI developments."}
      ],
      "search_language_filter": ["en"]
    }' | jq
  ```
</CodeGroup>

**2. Multiple Language Filter**

Search across multiple languages to gather diverse perspectives or multilingual content:

**Request Example**

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

  client = Perplexity()

  completion = client.chat.completions.create(
      model="sonar-pro",
      messages=[
          {"role": "system", "content": "You are a helpful assistant."},
          {"role": "user", "content": "What are the latest renewable energy innovations in Europe?"}
      ],
      search_language_filter=["en", "fr", "de"]
  )

  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-pro",
    messages: [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "What are the latest renewable energy innovations in Europe?"}
    ],
    search_language_filter: ["en", "fr", "de"]
  });

  console.log(completion.choices[0].message.content);
  ```

  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.perplexity.ai/chat/completions \
    --header "Authorization: Bearer YOUR_API_KEY" \
    --header "Content-Type: application/json" \
    --data '{
      "model": "sonar-pro",
      "messages": [
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What are the latest renewable energy innovations in Europe?"}
      ],
      "search_language_filter": ["en", "fr", "de"]
    }' | jq
  ```
</CodeGroup>

**3. Regional Language Research**

Focus on content from specific regions by using their local languages:

**Request Example**

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

  client = Perplexity()

  # Search for Asian market insights in local languages
  completion = client.chat.completions.create(
      model="sonar-pro",
      messages=[
          {"role": "system", "content": "You are a helpful assistant."},
          {"role": "user", "content": "What are the technology market trends in East Asia?"}
      ],
      search_language_filter=["zh", "ja", "ko"]
  )

  print(completion.choices[0].message.content)
  ```

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

  const client = new Perplexity();

  // Search for Asian market insights in local languages
  const completion = await client.chat.completions.create({
    model: "sonar-pro",
    messages: [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "What are the technology market trends in East Asia?"}
    ],
    search_language_filter: ["zh", "ja", "ko"]
  });

  console.log(completion.choices[0].message.content);
  ```

  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.perplexity.ai/chat/completions \
    --header "Authorization: Bearer YOUR_API_KEY" \
    --header "Content-Type: application/json" \
    --data '{
      "model": "sonar-pro",
      "messages": [
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What are the technology market trends in East Asia?"}
      ],
      "search_language_filter": ["zh", "ja", "ko"]
    }' | jq
  ```
</CodeGroup>

**4. Combining with Other Filters**

Language filters work seamlessly with other search parameters for precise control:

**Request Example**

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

  client = Perplexity()

  # Combine language filter with domain and date filters
  completion = client.chat.completions.create(
      model="sonar-pro",
      messages=[
          {"role": "system", "content": "You are a helpful assistant."},
          {"role": "user", "content": "What are recent breakthroughs in quantum computing?"}
      ],
      search_language_filter=["en", "de"],
      search_domain_filter=["nature.com", "science.org", "arxiv.org"],
      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();

  // Combine language filter with domain and date filters
  const completion = await client.chat.completions.create({
    model: "sonar-pro",
    messages: [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "What are recent breakthroughs in quantum computing?"}
    ],
    search_language_filter: ["en", "de"],
    search_domain_filter: ["nature.com", "science.org", "arxiv.org"],
    search_recency_filter: "month"
  });

  console.log(completion.choices[0].message.content);
  ```

  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.perplexity.ai/chat/completions \
    --header "Authorization: Bearer YOUR_API_KEY" \
    --header "Content-Type: application/json" \
    --data '{
      "model": "sonar-pro",
      "messages": [
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What are recent breakthroughs in quantum computing?"}
      ],
      "search_language_filter": ["en", "de"],
      "search_domain_filter": ["nature.com", "science.org", "arxiv.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.chat.completions.create(
          model="sonar",
          messages=[{"role": "user", "content": "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.chat.completions.create({
      model: "sonar",
      messages: [{role: "user", content: "technology news"}],
      searchLanguageFilter: 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 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:
    completion = client.chat.completions.create(
        model="sonar",
        messages=[
            {"role": "user", "content": "sustainable development goals progress"}
        ],
        search_language_filter=lang_group
    )
    results_by_region[", ".join(lang_group)] = completion

# Analyze results by language/region
for region, result in results_by_region.items():
    print(f"Results in {region}:")
    print(result.choices[0].message.content[:200])
    print("---")
```

### Content Localization Research

Find examples and references in target languages for localization projects:

```python  theme={null}
# Generate insights from target market languages
target_languages = ["ja", "ko", "zh"]  # Asian markets

completion = client.chat.completions.create(
    model="sonar-pro",
    messages=[
        {"role": "user", "content": "smartphone reviews 2024"}
    ],
    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
completion = client.chat.completions.create(
    model="sonar-pro",
    messages=[
        {"role": "user", "content": "quantum computing algorithms"}
    ],
    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():
    completion = client.chat.completions.create(
        model="sonar",
        messages=[
            {"role": "user", "content": "breaking news technology"}
        ],
        search_language_filter=langs,
        search_recency_filter="day"
    )
    print(f"{region} News:")
    print(completion.choices[0].message.content[:200])
    print("---")
```

## 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_chat(query, languages):
      """
      Generate a response with language-filtered search and 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 chat completion
          completion = client.chat.completions.create(
              model="sonar",
              messages=[{"role": "user", "content": query}],
              search_language_filter=languages
          )
          
          return completion
          
      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
  result = safe_language_chat(
      "artificial intelligence trends",
      ["en", "fr", "de"]
  )

  if result:
      print(result.choices[0].message.content)
  ```

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

  const client = new Perplexity();

  async function safeLanguageChat(
    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 chat completion
      const completion = await client.chat.completions.create({
        model: "sonar",
        messages: [{role: "user", content: query}],
        searchLanguageFilter: languages
      });
      
      return completion;
      
    } 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 result = await safeLanguageChat(
    "artificial intelligence trends",
    ["en", "fr", "de"]
  );

  if (result) {
    console.log(result.choices[0].message.content);
  }
  ```
</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>


# Perplexity MCP Server
Source: https://docs.perplexity.ai/guides/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 cols={2}>
  <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: "#77774d" }}
    />
  </svg>
}
    href="https://cursor.com/en/install-mcp?name=perplexity&config=eyJ0eXBlIjoic3RkaW8iLCJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBwZXJwbGV4aXR5LWFpL21jcC1zZXJ2ZXIiXX0="
  >
    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: "#77774d" }}
    />
  </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%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" arrow="True" horizontal="True" iconType="solid" cta="Get Key" href="https://www.perplexity.ai/account/api/group">
      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: Plugin Install (Recommended)**

        The easiest way to get started:

        ```bash  theme={null}
        # Add the Perplexity marketplace
        /plugin marketplace add perplexityai/modelcontextprotocol

        # Install the plugin
        /plugin install perplexity

        # Set your API key
        export PERPLEXITY_API_KEY="your_key_here"
        ```

        **Option 2: 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">
        Add 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="Claude Desktop">
        Add to your `claude_desktop_config.json`:

        ```json  theme={null}
        {
          "mcpServers": {
            "perplexity": {
              "command": "npx",
              "args": ["-y", "@perplexity-ai/mcp-server"],
              "env": {
                "PERPLEXITY_API_KEY": "your_key_here"
              }
            }
          }
        }
        ```
      </Tab>

      <Tab title="Other Clients">
        For any MCP-compatible client:

        ```bash  theme={null}
        npx @perplexity-ai/mcp-server
        ```

        Set environment variable: `PERPLEXITY_API_KEY=your_key_here`
      </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 cols={2}>
  <Card title="perplexity_search" icon="magnifying-glass">
    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>


# Quickstart
Source: https://docs.perplexity.ai/guides/perplexity-sdk

Learn how to use the official Perplexity SDKs for Python and TypeScript/JavaScript 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.

## Available APIs

<CardGroup cols={2}>
  <Card title="Chat Completions" icon="message" href="/guides/chat-completions-sdk">
    AI responses with web-grounded knowledge, conversation context, and streaming support.
  </Card>

  <Card title="Search" icon="magnifying-glass" href="/guides/perplexity-sdk-search">
    Ranked web search results with filtering, multi-query support, and domain controls.
  </Card>
</CardGroup>

## Installation

Install the SDK for your preferred language:

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

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

## Authentication

<Card title="Get your Perplexity API Key" icon="key" arrow="True" horizontal="True" iconType="solid" cta="Click here" href="https://perplexity.ai/account/api">
  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/JavaScript 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/JavaScript 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 cols={2}>
  <Card title="Chat Completions" icon="message" href="/guides/chat-completions-sdk">
    Get started with AI responses
  </Card>

  <Card title="Search" icon="magnifying-glass" href="/guides/perplexity-sdk-search">
    Get started with web search
  </Card>
</CardGroup>

## Resources

<CardGroup cols={2}>
  <Card title="Python Package" icon="cube" href="https://pypi.org/project/perplexityai/">
    Install from PyPI with pip
  </Card>

  <Card title="Node.js Package" icon="cube" href="https://www.npmjs.com/package/@perplexity-ai/perplexity_ai">
    Install from npm registry
  </Card>
</CardGroup>


# Best Practices
Source: https://docs.perplexity.ai/guides/perplexity-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/JavaScript 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 .env theme={null}
    PERPLEXITY_API_KEY=your_api_key_here
    PERPLEXITY_MAX_RETRIES=3
    PERPLEXITY_TIMEOUT=30000
    ```

    <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/JavaScript 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/JavaScript 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/JavaScript 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/JavaScript 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 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/JavaScript 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/JavaScript 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
          });
      }
  }

  // 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/JavaScript 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/JavaScript 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
  from perplexity.types import SearchCreateResponse, SearchResult

  class TestPerplexityIntegration(unittest.TestCase):
      def setUp(self):
          self.mock_client = Mock(spec=Perplexity)
          
      def test_search_success(self):
          # Mock successful response
          mock_result = SearchResult(
              title="Test Result",
              url="https://example.com",
              snippet="Test snippet"
          )
          
          mock_response = SearchCreateResponse(
              query="test query",
              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.query, "test query")
          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 = perplexity.RateLimitError("Rate limited")
          
          # Test your error handling logic here
          with self.assertRaises(perplexity.RateLimitError):
              mock_client.search.create(query="test")

  if __name__ == '__main__':
      unittest.main()
  ```

  ```typescript TypeScript/JavaScript theme={null}
  import { jest } from '@jest/globals';
  import Perplexity from '@perplexity-ai/perplexity_ai';
  import type { SearchCreateResponse, SearchResult } from '@perplexity-ai/perplexity_ai';

  // Mock the Perplexity client
  jest.mock('@perplexity-ai/perplexity_ai');

  describe('Perplexity Integration', () => {
      let mockClient: jest.Mocked<Perplexity>;
      
      beforeEach(() => {
          mockClient = new Perplexity() as jest.Mocked<Perplexity>;
      });
      
      test('should handle successful search', async () => {
          const mockResult: SearchResult = {
              title: "Test Result",
              url: "https://example.com",
              snippet: "Test snippet"
          };
          
          const mockResponse: SearchCreateResponse = {
              query: "test query",
              results: [mockResult]
          };
          
          (mockClient.search.create as jest.Mock).mockResolvedValue(mockResponse);
          
          const result = await mockClient.search.create({ query: "test query" });
          
          expect(result.query).toBe("test query");
          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');
          rateLimitError.constructor.name = 'RateLimitError';
          
          (mockClient.search.create as jest.Mock).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 cols={2}>
  <Card title="Error Handling" icon="triangle-exclamation" href="/guides/perplexity-sdk-error-handling">
    Comprehensive error handling strategies
  </Card>

  <Card title="Performance" icon="bolt" href="/guides/perplexity-sdk-performance">
    Async operations and optimization techniques
  </Card>

  <Card title="Configuration" icon="gear" href="/guides/perplexity-sdk-configuration">
    Production-ready configuration patterns
  </Card>

  <Card title="Type Safety" icon="shield-check" href="/guides/perplexity-sdk-type-safety">
    Leveraging types for safer code
  </Card>
</CardGroup>


# Configuration
Source: https://docs.perplexity.ai/guides/perplexity-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/JavaScript 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/JavaScript 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: "llama-3.1-sonar-large-128k-online",
      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/JavaScript 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')
  });

  // Proxy with authentication
  const clientAuth = new Perplexity({
      httpAgent: new HttpsProxyAgent('http://username:password@proxy.company.com:8080')
  });

  // SOCKS proxy
  const clientSocks = new Perplexity({
      httpAgent: new SocksProxyAgent('socks5://proxy.company.com:1080')
  });
  ```
</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/JavaScript 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/JavaScript 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
  });

  // For Node.js environments with custom CA certificates
  const httpsAgentCA = new https.Agent({
      ca: [/* your CA certificates */],
      cert: /* client certificate */,
      key: /* client private key */
  });

  const clientCert = new Perplexity({
      httpAgent: httpsAgentCA
  });
  ```
</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/JavaScript 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
  });

  // 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
  });
  ```
</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/JavaScript 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/JavaScript 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
  });
  ```
</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/JavaScript 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/JavaScript 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
          });
      }
      
      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
          });
      }
  }

  // Usage
  const client = PerplexityClientFactory.production();
  ```
</CodeGroup>

## Related Resources

<CardGroup cols={2}>
  <Card title="Error Handling" icon="triangle-exclamation" href="/guides/perplexity-sdk-error-handling">
    Handle timeouts and connection errors
  </Card>

  <Card title="Performance" icon="bolt" href="/guides/perplexity-sdk-performance">
    Optimize async operations and connection pooling
  </Card>
</CardGroup>


# Error Handling
Source: https://docs.perplexity.ai/guides/perplexity-sdk-error-handling

Learn how to handle API errors gracefully with the Perplexity SDKs for Python and TypeScript/JavaScript.

## 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/JavaScript 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) {
      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/JavaScript 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 (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="llama-3.1-sonar-small-128k-online",
          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/JavaScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  try {
      const chat = await client.chat.completions.create({
          model: "llama-3.1-sonar-small-128k-online",
          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="llama-3.1-sonar-small-128k-online",
              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/JavaScript 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: "llama-3.1-sonar-small-128k-online",
              messages: [{ role: "user", content: query }]
          });
          return response.choices[0].message.content || "";
          
      } 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 || "";
              } 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

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

      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/JavaScript theme={null}
      import Perplexity from '@perplexity-ai/perplexity_ai';

      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/JavaScript 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/JavaScript 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 cols={2}>
  <Card title="Configuration" icon="gear" href="/guides/perplexity-sdk-configuration">
    Configure timeouts and retries
  </Card>

  <Card title="Best Practices" icon="star" href="/guides/perplexity-sdk-best-practices">
    Environment variables and rate limiting
  </Card>
</CardGroup>


# Performance Optimization
Source: https://docs.perplexity.ai/guides/perplexity-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/JavaScript Installation theme={null}
  npm install @perplexity-ai/perplexity_ai
  # Async support is built-in with TypeScript/JavaScript
  ```
</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/JavaScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  async function main() {
      const client = new Perplexity();
      
      // Async is built-in for TypeScript/JavaScript
      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/JavaScript 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/JavaScript 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/JavaScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  // Get raw response with headers
  const response = await client.search.withRawResponse.create({
      query: "machine learning"
  });

  console.log(`Status Code: ${response.response.status}`);
  console.log(`Request ID: ${response.response.headers.get('X-Request-ID')}`);
  console.log(`Rate Limit Remaining: ${response.response.headers.get('X-RateLimit-Remaining')}`);
  console.log(`Rate Limit Reset: ${response.response.headers.get('X-RateLimit-Reset')}`);

  // Parse the actual search results
  const search = response.parse();
  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="llama-3.1-sonar-large-128k-online",
      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/JavaScript 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: "llama-3.1-sonar-large-128k-online",
      messages: [{ role: "user", content: "Explain quantum computing" }],
      stream: true
  });

  for await (const chunk of stream) {
      if (chunk.choices[0]?.delta?.content) {
          process.stdout.write(chunk.choices[0].delta.content);
      }
  }
  ```
</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/JavaScript 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
  });

  // 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
  });
  ```
</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/JavaScript 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/JavaScript 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/JavaScript 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/JavaScript 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 cols={2}>
  <Card title="Configuration" icon="gear" href="/guides/perplexity-sdk-configuration">
    Optimize connection pooling and timeouts
  </Card>

  <Card title="Error Handling" icon="triangle-exclamation" href="/guides/perplexity-sdk-error-handling">
    Handle errors in async operations
  </Card>
</CardGroup>


# Type Safety
Source: https://docs.perplexity.ai/guides/perplexity-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,
      ChatCompletionCreateResponse,
      SearchResult,
      ChatCompletionMessage
  )

  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/JavaScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';
  import type { 
      SearchCreateResponse, 
      ChatCompletionCreateResponse,
      SearchResult,
      ChatCompletionMessage 
  } from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  // TypeScript provides full intellisense and type checking
  const searchResponse: SearchCreateResponse = await client.search.create({
      query: "artificial intelligence"
  });

  // Access typed properties with intellisense
  const result: SearchResult = 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/JavaScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';
  import type { SearchCreateResponse } from '@perplexity-ai/perplexity_ai';

  const client = new Perplexity();

  // TypeScript compile-time type checking
  const searchResponse: SearchCreateResponse = await client.search.create({
      query: "machine learning",
      maxResults: 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, ChatCompletionCreateResponse

  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/JavaScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';
  import type { 
      SearchCreateResponse, 
      ChatCompletionCreateResponse 
  } from '@perplexity-ai/perplexity_ai';

  class TypedPerplexityClient {
      constructor(private client: Perplexity) {}
      
      async searchWithTransform<T>(
          query: string,
          transform: (response: SearchCreateResponse) => T
      ): Promise<T> {
          const response = await this.client.search.create({ query });
          return transform(response);
      }
      
      async batchSearch(queries: string[]): Promise<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: 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, 
      ChatCompletionCreateResponse,
      SearchResult
  )

  def is_search_response(
      response: Union[SearchCreateResponse, ChatCompletionCreateResponse]
  ) -> 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, ChatCompletionCreateResponse]
  ) -> None:
      if is_search_response(response):
          # TypeScript 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/JavaScript theme={null}
  import type { 
      SearchCreateResponse, 
      ChatCompletionCreateResponse,
      SearchResult 
  } from '@perplexity-ai/perplexity_ai';

  function isSearchResponse(
      response: SearchCreateResponse | ChatCompletionCreateResponse
  ): response is SearchCreateResponse {
      return 'results' in response;
  }

  function isValidSearchResult(result: SearchResult): result is SearchResult {
      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: SearchCreateResponse | ChatCompletionCreateResponse
  ): 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,
      ChatCompletionCreateResponse,
      ChatCompletionChoice
  )

  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_chat_content(
          response: ChatCompletionCreateResponse
      ) -> Optional[str]:
          """Extract chat completion content safely"""
          if response.choices and response.choices[0].message:
              return response.choices[0].message.content
          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/JavaScript theme={null}
  import type { 
      SearchCreateResponse,
      SearchResult,
      ChatCompletionCreateResponse,
      ChatCompletionChoice 
  } from '@perplexity-ai/perplexity_ai';

  class ResponseUtils {
      static extractSearchTitles(response: SearchCreateResponse): string[] {
          return response.results
              .filter(result => result.title)
              .map(result => result.title);
      }
      
      static extractSearchUrls(response: SearchCreateResponse): string[] {
          return response.results
              .filter(result => result.url)
              .map(result => result.url);
      }
      
      static getFirstSearchResult(
          response: SearchCreateResponse
      ): SearchResult | undefined {
          return response.results[0];
      }
      
      static extractChatContent(
          response: ChatCompletionCreateResponse
      ): string | undefined {
          return response.choices[0]?.message?.content;
      }
  }

  // Usage
  const client = new Perplexity();
  const searchResponse = 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/JavaScript theme={null}
  import type { SearchCreateResponse, SearchResult } 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: 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: response.query,
              totalResults: simplifiedResults.length,
              results: simplifiedResults,
              domains: Array.from(domains)
          };
      }
  }

  // Usage with type safety
  const client = new Perplexity();
  const apiResponse = 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 ChatCompletionCreateResponse

  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 = "llama-3.1-sonar-small-128k-online") -> "ChatCompletionCreateResponse":
          """
          Chat completion with type hints
          
          Args:
              message: User message
              model: Model to use for completion
              
          Returns:
              ChatCompletionCreateResponse: 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")
  print(chat_result.choices[0].message.content)  # Type-safe access
  ```

  ```typescript TypeScript/JavaScript theme={null}
  import Perplexity from '@perplexity-ai/perplexity_ai';
  import type { 
      SearchCreateResponse, 
      ChatCompletionCreateResponse,
      SearchCreateParams,
      ChatCompletionCreateParams 
  } 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<SearchCreateParams>
      ): Promise<SearchCreateResponse> {
          return this.client.search.create({ 
              query, 
              ...options 
          });
      }
      
      /**
       * Chat completion with type hints
       */
      async chat(
          message: string, 
          model: string = "llama-3.1-sonar-small-128k-online"
      ): Promise<ChatCompletionCreateResponse> {
          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");
  console.log(chatResult.choices[0].message.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/JavaScript theme={null}
      // Good: Specific type imports
      import type { SearchCreateResponse, SearchResult } from '@perplexity-ai/perplexity_ai';

      function processSearch(response: 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/JavaScript theme={null}
      /**
       * Analyze search results with scoring
       */
      function analyzeSearchResults(
          response: SearchCreateResponse,
          minScore: number = 0.5
      ): { scores: number[]; recommendations: string[] } {
          // Implementation with type safety
      }
      ```
    </CodeGroup>
  </Step>
</Steps>

## Related Resources

<CardGroup cols={2}>
  <Card title="Error Handling" icon="triangle-exclamation" href="/guides/perplexity-sdk-error-handling">
    Type-safe error handling patterns
  </Card>

  <Card title="Best Practices" icon="star" href="/guides/perplexity-sdk-best-practices">
    Type safety in production code
  </Card>
</CardGroup>


# Privacy & Security
Source: https://docs.perplexity.ai/guides/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>
  **[SOC 2 Type 1 Report (Insight Assurance)](https://trust.perplexity.ai/)** - Initial assessment of security control design and implementation
</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>


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



## System Prompt

You can use the system prompt to provide instructions related to style, tone, and language of the response.

<Warning>
  The real-time search component of our models does not attend to the system prompt.
</Warning>

**Example of a system prompt**

```
You are a helpful AI assistant.

Rules:
1. Provide only the final answer. It is important that you do not include any explanation on the steps below.
2. Do not show the intermediate steps information.

Steps:
1. Decide if the answer should be a brief sentence or a list of suggestions.
2. If it is a list of suggestions, first, write a brief and natural introduction based on the original query.
3. Followed by a list of suggestions, each suggestion should be split by two newlines.
```

## User Prompt

You should use the user prompt to pass in the actual query for which you need an answer for. The user prompt will be used to kick off a real-time web search to make sure the answer has the latest and the most relevant information needed.

**Example of a user prompt**

```
What are the best sushi restaurants in the world currently?
```

# Web Search Models: General Prompting Guidelines

Our web search-powered models combine the capabilities of LLMs with real-time web searches. Understanding how they differ from traditional LLMs will help you craft more effective prompts.

## Best Practices for Prompting Web Search Models

<CardGroup cols={2}>
  <Card title="Be Specific and Contextual">
    Unlike traditional LLMs, our web search models require specificity to retrieve relevant search results. Adding just 2-3 extra words of context can dramatically improve performance.

    **Good Example**: "Explain recent advances in climate prediction models for urban planning"

    **Poor Example**: "Tell me about climate models"
  </Card>

  <Card title="Avoid Few-Shot Prompting">
    While few-shot prompting works well for traditional LLMs, it confuses web search models by triggering searches for your examples rather than your actual query.

    **Good Example**: "Summarize the current research on mRNA vaccine technology"

    **Poor Example**: "Here's an example of a good summary about vaccines: \[example text]. Now summarize the current research on mRNA vaccines."
  </Card>

  <Card title="Think Like a Web Search User">
    Craft prompts with search-friendly terms that would appear on relevant web pages. Consider how experts in the field would describe the topic online.

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

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

  <Card title="Provide Relevant Context">
    Include critical context to guide the web search toward the most relevant content, but keep prompts concise and focused.

    **Good Example**: "Explain the impact of the 2023 EU digital markets regulations on app store competition for small developers"

    **Poor Example**: "What are the rules for app stores?"
  </Card>
</CardGroup>

## Web Search Model Pitfalls to Avoid

<CardGroup cols={2}>
  <Card title="Overly Generic Questions">
    Generic prompts lead to scattered web search results and unfocused responses. Always narrow your scope.

    **Avoid**: "What's happening in AI?"

    **Instead**: "What are the three most significant commercial applications of generative AI in healthcare in the past year?"
  </Card>

  <Card title="Traditional LLM Techniques">
    Prompting strategies designed for traditional LLM often don't work well with web search models. Adapt your approach accordingly.

    **Avoid**: "Act as an expert chef and give me a recipe for sourdough bread. Start by explaining the history of sourdough, then list ingredients, then..."

    **Instead**: "What's a reliable sourdough bread recipe for beginners? Include ingredients and step-by-step instructions."
  </Card>

  <Card title="Complex Multi-Part Requests">
    Complex prompts with multiple unrelated questions can confuse the search component. Focus on one topic per query.

    **Avoid**: "Explain quantum computing, and also tell me about regenerative agriculture, and provide stock market predictions."

    **Instead**: "Explain quantum computing principles that might impact cryptography in the next decade."
  </Card>

  <Card title="Assuming Search Intent">
    Don't assume the model will search for what you intended without specific direction. Be explicit about exactly what information you need.

    **Avoid**: "Tell me about the latest developments."

    **Instead**: "What are the latest developments in offshore wind energy technology announced in the past 6 months?"
  </Card>
</CardGroup>

## Handling URLs and Source Information

<Warning>
  **Never ask for URLs or source links in your prompts.** The generative model cannot see the actual URLs from the web search, which means any URLs it provides in the response text are likely to be hallucinated and incorrect.
</Warning>

### The Right Way to Access Sources

URLs and source information are automatically returned in the `search_results` field of the API response. This field contains accurate information about the sources used, including:

* `title`: The title of the source page
* `url`: The actual URL of the source
* `date`: The publication date of the content

**Example of incorrect prompting:**

```
❌ BAD: "From the past 5 days, identify high-potential Canadian news stories... 
For each item, include:
- A clear headline  
- 1–2 sentence summary
- Include a link to a source"
```

**Example of correct prompting:**

```
✅ GOOD: "From the past 5 days, identify high-potential Canadian news stories...
For each item, include:
- A clear headline
- 1–2 sentence summary  
- Why it matters from a thought-leadership perspective"

// Then parse URLs from the search_results field in the API response
```

### Why This Matters

The web search and language generation components work differently:

1. **Web Search Component**: Finds and retrieves content from specific URLs
2. **Language Generation Component**: Processes the retrieved content but doesn't have access to the original URLs
3. **API Response**: Provides both the generated text and the accurate source URLs separately

When you ask for URLs in your prompt, the language model will attempt to generate them based on patterns it has seen, but these will not be the actual URLs that were searched. Always use the `search_results` field for accurate source information.

## Preventing Hallucination in Search Results

<Warning>
  **LLMs are designed to be "helpful" and may attempt to provide answers even when they lack sufficient information.** This can lead to hallucinated or inaccurate responses, especially when asking about sources that Sonar cannot access.
</Warning>

### Understanding the Helpfulness Problem

Large Language Models are trained to be assistive and will often try to provide an answer even when they're not confident about the information. This tendency can be problematic when:

* You request information from sources that Sonar cannot access (e.g., LinkedIn posts, private documents, paywalled content)
* The search doesn't return relevant results for your specific query
* You ask for very recent information that may not be indexed yet

### Common Scenarios That Lead to Hallucination

**Inaccessible Sources:**

```
❌ PROBLEMATIC: "What did the CEO of XYZ company post on LinkedIn yesterday about their new product launch?"
```

*Sonar may not be able to access LinkedIn content, but the model might still attempt to provide an answer based on general knowledge or patterns.*

**Overly Specific Recent Events:**

```
❌ PROBLEMATIC: "What was discussed in the closed-door meeting between Company A and Company B last week?"
```

*Private information that wouldn't be publicly searchable may still get a fabricated response.*

### How to Prevent Hallucination

**Use Explicit Instructions:**
Include clear guidance in your prompts about what to do when information isn't available:

```
✅ GOOD: "Search for recent developments in quantum computing breakthroughs. 
If you are not able to get search results or find relevant information, 
please state that clearly rather than providing speculative information."
```

**Set Clear Boundaries:**

```
✅ GOOD: "Based on publicly available sources from the past week, what are the latest policy changes in Canadian healthcare? 
If no recent information is found, please indicate that no recent updates were discovered."
```

**Request Source Transparency:**

```
✅ GOOD: "Find information about Tesla's latest earnings report. 
Only provide information that you can verify from your search results, 
and clearly state if certain details are not available."
```

### Best Practices for Reliable Results

<CardGroup cols={2}>
  <Card title="Be Explicit About Limitations">
    Always instruct the model to acknowledge when it cannot find information rather than guessing.

    **Example**: "If you cannot find reliable sources for this information, please say so explicitly."
  </Card>

  <Card title="Focus on Accessible Sources">
    Stick to information that is likely to be publicly indexed and searchable.

    **Avoid**: LinkedIn posts, private company documents, closed meetings
    **Prefer**: News articles, public reports, official announcements
  </Card>

  <Card title="Use Conditional Language">
    Frame requests with conditional statements that give the model permission to say "I don't know."

    **Example**: "If available, provide details about... Otherwise, indicate what information could not be found."
  </Card>

  <Card title="Verify with Multiple Queries">
    For critical information, consider breaking complex requests into smaller, more specific queries to verify consistency.

    **Strategy**: Ask the same question in different ways and compare results for consistency.
  </Card>
</CardGroup>

## Use Built-in Search Parameters, Not Prompts

<Tip>
  **Always use Perplexity's built-in search parameters instead of trying to control search behavior through prompts.** API parameters are guaranteed to work and are much more effective than asking the model to filter results.
</Tip>

### Why Built-in Parameters Are Better

When you want to control search behavior—such as limiting sources, filtering by date, or adjusting search depth—use the API's built-in parameters rather than prompt instructions. The search component processes these parameters directly, ensuring reliable and consistent results.

### Common Mistakes: Prompt-Based Control

**❌ Ineffective - Trying to control via prompts:**

```json  theme={null}
{
  "model": "sonar-pro",
  "messages": [
    {
      "role": "user", 
      "content": "Search only on Wikipedia and official government sites for information about climate change policies. Make sure to only look at sources from the past month."
    }
  ]
}
```

### Correct Approach: Use API Parameters

**✅ Effective - Using built-in parameters:**

```json  theme={null}
{
  "model": "sonar-pro",
  "messages": [
    {
      "role": "user", 
      "content": "What are the latest climate change policies?"
    }
  ],
  "search_domain_filter": ["wikipedia.org"]
}
```

### Available Search Parameters

### Benefits of Using Built-in Parameters

<CardGroup cols={2}>
  <Card title="Guaranteed Execution">
    Built-in parameters are processed directly by the search engine, ensuring they're applied correctly every time.
  </Card>

  <Card title="Better Performance">
    Parameters filter results before they reach the language model, leading to more focused and relevant responses.
  </Card>

  <Card title="Cleaner Prompts">
    Keep your prompts focused on what you want the model to generate, not how to search.
  </Card>

  <Card title="Consistent Results">
    API parameters provide predictable behavior across different queries and use cases.
  </Card>
</CardGroup>

### Advanced Techniques

<Tip>
  We recommend for users *not* to tune language parameters such as `temperature`, as the default settings for these have already been optimized.
</Tip>

<CardGroup cols={1}>
  <Card title="Parameter Optimization">
    Adjust model parameters based on your specific needs:

    * **Search Domain Filter**: Limit results to trusted sources for research-heavy queries.
    * **Search Context Size**: Use "high" for comprehensive research questions and "low" for simple factual queries.

    Example configuration for technical documentation:

    ```json  theme={null}
    {
      "search_domain_filter": ["wikipedia.org", "docs.python.org"],
      "web_search_options": {
        "search_context_size": "medium"
      }
    }
    ```
  </Card>
</CardGroup>

### Tips for Different Query Types

| Query Type              | Best Practices                                                                                                                         |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| **Factual Research**    | • Use specific questions  • Use search domain filters for academic sources  • Consider "high" search context size                      |
| **Creative Content**    | • Provide detailed style guidelines in system prompt  • Specify tone, voice, and audience                                              |
| **Technical Questions** | • Include relevant technical context  • Specify preferred programming language/framework  • Use domain filters for documentation sites |
| **Analysis & Insights** | • Request step-by-step reasoning  • Ask for specific metrics or criteria                                                               |


# Rate Limits & Usage Tiers
Source: https://docs.perplexity.ai/guides/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.

<Info>
  You can check your current usage tier by visiting your [API settings page](https://www.perplexity.ai/settings/api).
</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>

***

## How Tiers Work

* **Automatic advancement** - Tiers increase based on your total lifetime credit purchases
* **Rate limit increases** - Higher tiers get significantly more requests per minute
* **Permanent status** - Once you reach a tier, you keep it (no downgrade)

## Rate Limits by Model

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

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

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

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

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

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

***

## Search Rate Limits

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

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

**Search Rate Limiter Behavior:**

* **Burst**: Can handle 3 requests instantly
* **Refill**: 1 token every 333ms
* **Sustained**: Exactly 3 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>

<Info>
  **Need Higher Search Rate Limits?**

  If you require increased rate limits for the Search API beyond the standard 3 requests per second, please fill out our [rate limit increase request form](https://perplexity.typeform.com/to/yctmfyVT). We'll review your use case and work with you to accommodate your needs.
</Info>

***

## 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 refill over time (your rate limit)
    * **Token Refill**: New requests become available at regular intervals

    **Key Benefits:**

    * ✅ Allows legitimate burst traffic
    * ✅ Prevents sustained abuse
    * ✅ Predictable and fair rate enforcement
  </Accordion>

  <Accordion title="Rate Limiter Behavior Example">
    Let's examine how **3 requests per second** works in practice:

    **Parameters:**

    * Capacity: 3 tokens
    * Leak rate: 3 tokens/second
    * Refill: 1 token every 333ms

    **Scenario 1: Burst Traffic**

    ```
    Time 0.0s: Bucket full (3 tokens)
    → Send 3 requests instantly → ALL ALLOWED ✅
    → Send 4th request → REJECTED ❌ (bucket empty)

    Time 0.333s: 1 token refilled
    → Send 1 request → ALLOWED ✅
    → Send 2nd request → REJECTED ❌

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

    **Scenario 2: Steady 3 QPS**

    ```
    Request every 333ms:
    Time 0.0s: Request → ✅ (3→2 tokens)
    Time 0.333s: Request → ✅ (2+1-1=2 tokens)
    Time 0.666s: Request → ✅ (2+1-1=2 tokens)
    ... maintains 2-3 tokens, all requests pass
    ```

    **Scenario 3: Slightly Over 3 QPS**

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

  <Accordion title="Real-World Implications">
    **What this means for your applications:**

    **✅ Burst Tolerance:**

    * Can handle your full rate limit instantly
    * Perfect for batch operations or sudden traffic spikes
    * No need to artificially spread requests

    **✅ Predictable Behavior:**

    * Strict average rate enforcement over time
    * Quick recovery after burst usage
    * Consistent performance across different usage patterns

    **❌ Abuse Prevention:**

    * Prevents sustained over-limit usage
    * Blocks excessive burst attempts
    * Maintains fair resource allocation

    **Best Practices:**

    * Take advantage of burst capacity for batch operations
    * Monitor your usage patterns to optimize request timing
    * 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:**

* **3 QPS limit**: 1 token refills every 333ms
* **50 QPS limit**: 1 token refills every 20ms
* **500 QPS limit**: 1 token refills every 2ms

<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 your [API settings page](https://www.perplexity.ai/settings/api) 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>
</Steps>

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


# Returning Images with Sonar
Source: https://docs.perplexity.ai/guides/returning-images

Control image results with domain and format filters using Sonar models

## Overview

Sonar models can return images as part of their responses to enhance the information provided. You can control which images are returned using domain and format filters, giving you fine-grained control over the sources and file types of image results.

<Note>
  **SDK Installation Required**: Install the official SDK first - `pip install perplexityai` for Python or `npm install @perplexity-ai/perplexity_ai` for TypeScript/JavaScript.
</Note>

<Note>
  The `image_domain_filter` and `image_format_filter` parameters allow you to control the sources and file types of image results returned by the Sonar models.
</Note>

<Warning>
  You can include a maximum of 10 entries in each of the filter lists. These filters currently apply only when `"return_images": true` is set in your request.
</Warning>

## Filter Types

### Domain Filtering

The `image_domain_filter` parameter controls which image sources are included or excluded:

* **Exclude domains**: Prefix with `-` (e.g., `-gettyimages.com`)
* **Include domains**: Use domain name directly (e.g., `wikimedia.org`)

### Format Filtering

The `image_format_filter` parameter restricts results to specific file formats:

* Use lowercase file extensions: `gif`, `jpg`, `png`, `webp`
* Omit the dot prefix: use `gif`, not `.gif`

## Basic Usage

To enable image returns, your request must include `"return_images": true`.

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.perplexity.ai/chat/completions \
    --header "Authorization: Bearer $SONAR_API_KEY" \
    --header "Content-Type: application/json" \
    --data '{
      "model": "sonar",
      "return_images": true,
      "messages": [
        {"role": "user", "content": "Show me images of Mount Everest"}
      ]
    }' | jq
  ```

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

  # Initialize the client
  client = Perplexity()

  # Request with image returns enabled
  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)
  ```

  ```javascript JavaScript theme={null}
  const Perplexity = require('@perplexity-ai/perplexity_ai');

  // Initialize the client
  const client = new Perplexity();

  // Request with image returns enabled
  const completion = await client.chat.completions.create({
      model: 'sonar',
      return_images: true,
      messages: [
          { role: 'user', content: 'Show me images of Mount Everest' }
      ]
  });

  console.log(completion.choices[0].message.content);
  ```

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

  // Initialize the client
  const client = new Perplexity();

  // Request with image returns enabled
  const completion = await client.chat.completions.create({
      model: 'sonar',
      return_images: true,
      messages: [
          { role: 'user', content: 'Show me images of Mount Everest' }
      ]
  });

  console.log(completion.choices[0].message.content);
  ```
</CodeGroup>

## Filtering Examples

### 1. Exclude Specific Image Domains

Filter out images from specific providers like Getty Images:

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.perplexity.ai/chat/completions \
    --header "Authorization: Bearer $SONAR_API_KEY" \
    --header "Content-Type: application/json" \
    --data '{
      "model": "sonar",
      "return_images": true,
      "image_domain_filter": ["-gettyimages.com"],
      "messages": [
        {"role": "user", "content": "What is the weather like today in London?"}
      ]
    }' | jq
  ```

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

  # Initialize the client
  client = Perplexity()

  # Exclude Getty Images from results
  completion = client.chat.completions.create(
      model="sonar",
      return_images=True,
      image_domain_filter=["-gettyimages.com"],
      messages=[
          {"role": "user", "content": "Show me images of Mount Everest"}
      ]
  )

  print(completion.choices[0].message.content)
  ```

  ```javascript JavaScript theme={null}
  const Perplexity = require('@perplexity-ai/perplexity_ai');

  // Initialize the client
  const client = new Perplexity();

  // Exclude Getty Images from results
  const completion = await client.chat.completions.create({
      model: 'sonar',
      return_images: true,
      image_domain_filter: ['-gettyimages.com'],
      messages: [
          { role: 'user', content: 'Show me images of Mount Everest' }
      ]
  });

  console.log(completion.choices[0].message.content);
  ```

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

  // Initialize the client
  const client = new Perplexity();

  // Exclude Getty Images from results
  const completion = await client.chat.completions.create({
      model: 'sonar',
      return_images: true,
      image_domain_filter: ['-gettyimages.com'],
      messages: [
          { role: 'user', content: 'Show me images of Mount Everest' }
      ]
  });

  console.log(completion.choices[0].message.content);
  ```
</CodeGroup>

### 2. Only Return GIFs

Restrict results to GIF images only:

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.perplexity.ai/chat/completions \
    --header "Authorization: Bearer $SONAR_API_KEY" \
    --header "Content-Type: application/json" \
    --data '{
      "model": "sonar",
      "return_images": true,
      "image_format_filter": ["gif"],
      "messages": [
        {"role": "user", "content": "Show me a funny cat gif"}
      ]
    }' | jq
  ```

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

  # Initialize the client
  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"}
      ]
  )

  print(completion.choices[0].message.content)
  ```

  ```javascript JavaScript theme={null}
  const Perplexity = require('@perplexity-ai/perplexity_ai');

  // Initialize the client
  const client = new Perplexity();

  // Only return GIF images
  const completion = await client.chat.completions.create({
      model: 'sonar',
      return_images: true,
      image_format_filter: ['gif'],
      messages: [
          { role: 'user', content: 'Show me a funny cat gif' }
      ]
  });

  console.log(completion.choices[0].message.content);
  ```

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

  // Initialize the client
  const client = new Perplexity();

  // Only return GIF images
  const completion = await client.chat.completions.create({
      model: 'sonar',
      return_images: true,
      image_format_filter: ['gif'],
      messages: [
          { role: 'user', content: 'Show me a funny cat gif' }
      ]
  });

  console.log(completion.choices[0].message.content);
  ```
</CodeGroup>

### 3. Combine Domain and Format Filters

Use both filters together for precise control:

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.perplexity.ai/chat/completions \
    --header "Authorization: Bearer $SONAR_API_KEY" \
    --header "Content-Type: application/json" \
    --data '{
      "model": "sonar",
      "return_images": true,
      "image_domain_filter": ["-gettyimages.com"],
      "image_format_filter": ["gif"],
      "messages": [
        {"role": "user", "content": "Show me a gif of a dog"}
      ]
    }' | jq
  ```

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

  # Initialize the client
  client = Perplexity()

  # Combine domain and format filtering
  completion = client.chat.completions.create(
      model="sonar",
      return_images=True,
      image_domain_filter=["-gettyimages.com"],
      image_format_filter=["gif"],
      messages=[
          {"role": "user", "content": "Show me a gif of a dog"}
      ]
  )

  print(completion.choices[0].message.content)
  ```

  ```javascript JavaScript theme={null}
  const Perplexity = require('@perplexity-ai/perplexity_ai');

  // Initialize the client
  const client = new Perplexity();

  // Combine domain and format filtering
  const completion = await client.chat.completions.create({
      model: 'sonar',
      return_images: true,
      image_domain_filter: ['-gettyimages.com'],
      image_format_filter: ['gif'],
      messages: [
          { role: 'user', content: 'Show me a gif of a dog' }
      ]
  });

  console.log(completion.choices[0].message.content);
  ```

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

  // Initialize the client
  const client = new Perplexity();

  // Combine domain and format filtering
  const completion = await client.chat.completions.create({
      model: 'sonar',
      return_images: true,
      image_domain_filter: ['-gettyimages.com'],
      image_format_filter: ['gif'],
      messages: [
          { role: 'user', content: 'Show me a gif of a dog' }
      ]
  });

  console.log(completion.choices[0].message.content);
  ```
</CodeGroup>

## Advanced Filtering

### Multiple Domain Exclusions

```python  theme={null}
# Exclude multiple image providers
completion = client.chat.completions.create(
    model="sonar",
    return_images=True,
    image_domain_filter=["-gettyimages.com", "-shutterstock.com", "-stockphoto.com"],
    messages=[
        {"role": "user", "content": "Show me nature photography"}
    ]
)
```

### Multiple Format Types

```python  theme={null}
# Allow multiple image formats
completion = client.chat.completions.create(
    model="sonar",
    return_images=True,
    image_format_filter=["jpg", "png", "webp"],
    messages=[
        {"role": "user", "content": "Show me high-quality landscape images"}
    ]
)
```

### Include Specific Domains

```python  theme={null}
# Include only Wikipedia images
completion = client.chat.completions.create(
    model="sonar", 
    return_images=True,
    image_domain_filter=["wikimedia.org"],
    messages=[
        {"role": "user", "content": "Show me historical images"}
    ]
)
```

## Common Use Cases

### Educational Content

```python  theme={null}
# Get educational images from trusted sources
image_domain_filter = ["wikimedia.org", "nasa.gov", "archive.org"]
image_format_filter = ["jpg", "png"]
```

### Creative Projects

```python  theme={null}
# Get animated content for presentations
image_format_filter = ["gif", "webp"]
image_domain_filter = ["-gettyimages.com", "-shutterstock.com"]  # Avoid watermarked images
```

### High-Quality Photography

```python  theme={null}
# Focus on professional photography formats
image_format_filter = ["jpg", "png"]
image_domain_filter = ["-lowres.com", "-thumbnail.com"]  # Exclude low-quality sources
```

## Best Practices

<AccordionGroup>
  <Accordion title="Domain Filtering Strategy">
    * Use simple domain names like `example.com` or `-gettyimages.com`
    * Do not include `http://`, `https://`, or subdomains
    * Mix inclusion and exclusion in domain filters for precise control
    * Keep lists short (≤10 entries) for performance and relevance
  </Accordion>

  <Accordion title="Format Filtering Guidelines">
    * File extensions must be lowercase: `["jpg"]`, not `["JPG"]`
    * Omit dot prefix: use `gif`, not `.gif`
    * Consider your use case: GIFs for animation, PNG for transparency, JPG for photos
    * WebP offers good compression but may have limited compatibility
  </Accordion>

  <Accordion title="Performance Optimization">
    * Filters may slightly increase response time
    * Overly restrictive filters may reduce result quality or quantity
    * Test different filter combinations to find the right balance
    * Monitor response times with different filter configurations
  </Accordion>
</AccordionGroup>

## Filter Reference

### Supported Image Formats

| Format | Extension | Best For                              |
| ------ | --------- | ------------------------------------- |
| JPEG   | `jpg`     | Photographs, complex images           |
| PNG    | `png`     | Screenshots, images with transparency |
| WebP   | `webp`    | Modern format with good compression   |
| GIF    | `gif`     | Animated images, simple graphics      |

### Common Domain Exclusions

| Domain              | Type         | Reason                    |
| ------------------- | ------------ | ------------------------- |
| `-gettyimages.com`  | Stock Photos | Watermarked content       |
| `-shutterstock.com` | Stock Photos | Watermarked content       |
| `-istockphoto.com`  | Stock Photos | Watermarked content       |
| `-pinterest.com`    | Social Media | Mixed quality/attribution |

<Tip>
  Start with broad filters and gradually refine them based on the quality and relevance of returned images.
</Tip>

## Limitations

<Warning>
  * Maximum of 10 entries in each filter list
  * Filters only apply when `"return_images": true` is set
  * Some domains may not be filterable due to CDN usage
  * Very restrictive filters may result in no images being returned
</Warning>


# Returning Videos with Sonar
Source: https://docs.perplexity.ai/guides/returning-videos

Learn how to return videos in API responses using media_response overrides with raw HTTP requests

## Overview

Sonar models can return videos as part of their responses to provide rich multimedia content that enhances the information delivered. You can control video returns using the `media_response` parameter with `overrides` to specify when videos should be included in responses.

<Note>
  Use the `media_response.overrides.return_videos` parameter to control when videos are returned in API responses.
</Note>

<Warning>
  Video returns may increase response size and processing time. Use this feature selectively for queries where video content adds significant value.
</Warning>

## Basic Usage

To enable video returns, include the `media_response` parameter with `overrides.return_videos` set to `true` in your request.

### Simple Video Request

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.perplexity.ai/chat/completions \
    -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "sonar-pro",
      "media_response": {
        "overrides": {
          "return_videos": true
        }
      },
      "messages": [
        {
          "role": "user",
          "content": "2024 Olympics highlights"
        }
      ]
    }' | jq
  ```

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

  url = "https://api.perplexity.ai/chat/completions"
  headers = {
      "Authorization": f"Bearer {os.environ['PERPLEXITY_API_KEY']}",
      "Content-Type": "application/json"
  }

  data = {
      "model": "sonar-pro",
      "media_response": {
          "overrides": {
              "return_videos": True
          }
      },
      "messages": [
          {
              "role": "user",
              "content": "2024 Olympics highlights"
          }
      ]
  }

  response = requests.post(url, headers=headers, json=data)
  result = response.json()
  print(json.dumps(result, indent=2))
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch('https://api.perplexity.ai/chat/completions', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.PERPLEXITY_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      model: 'sonar-pro',
      media_response: {
        overrides: {
          return_videos: true
        }
      },
      messages: [
        {
          role: 'user',
          content: '2024 Olympics highlights'
        }
      ]
    })
  });

  const result = await response.json();
  console.log(JSON.stringify(result, null, 2));
  ```
</CodeGroup>

<AccordionGroup>
  <Accordion title="Sample Response">
    ```json  theme={null}
    {
      "id": "58dee6e4-d2de-4d7e-910f-4048caa6903d",
      "model": "sonar-pro",
      "created": 1758844959,
      "usage": {
        "prompt_tokens": 6,
        "completion_tokens": 542,
        "total_tokens": 548,
        "search_context_size": "low",
        "cost": {
          "input_tokens_cost": 0.0,
          "output_tokens_cost": 0.008,
          "request_cost": 0.006,
          "total_cost": 0.014
        }
      },
      "citations": [
        "https://en.wikipedia.org/wiki/2024_Summer_Olympics",
        "https://www.teamusa.com/news/2024/august/13/top-moments-from-the-paris-2024-olympic-games",
        "https://www.nbcolympics.com/news/olympic-track-and-field-paris-2024-biggest-stories-replays-medal-results-top-athletes-new",
        "https://www.youtube.com/watch?v=WajxULWXIFE",
        "https://www.nbcolympics.com/news/olympic-gymnastics-paris-2024-biggest-stories-replays-medal-results-top-athletes-new-records",
        "https://www.youtube.com/watch?v=vy6FivZHRjQ",
        "https://www.espn.com/olympics/story/_/id/40813327/2024-paris-summer-olympics-live-updates-highlights-results-sunday-closing-ceremony",
        "https://www.youtube.com/watch?v=q4Mujt1wer4",
        "https://www.youtube.com/olympics",
        "https://www.youtube.com/watch?v=OFCVkSQYTjA",
        "https://www.youtube.com/watch?v=7Xnr805bm4E",
        "https://www.nbcolympics.com/videos"
      ],
      "search_results": [
        {
          "title": "2024 Summer Olympics - Wikipedia",
          "url": "https://en.wikipedia.org/wiki/2024_Summer_Olympics",
          "date": "2006-03-05",
          "last_updated": "2025-09-24",
          "snippet": "Paris 2024 featured the debut of breaking as an Olympic sport, and was the final Olympic Games held during the IOC presidency of Thomas Bach. The 2024 Games ..."
        },
        {
          "title": "Top Moments From the Paris 2024 Olympic Games | Team USA",
          "url": "https://www.teamusa.com/news/2024/august/13/top-moments-from-the-paris-2024-olympic-games",
          "date": "2024-08-13",
          "last_updated": "2025-09-25",
          "snippet": "Scottie Scheffler wins his first Olympic Gold Medal | Golf · Victor Montalvo Takes Bronze in Breaking | Breaking · Brooke Raboutou Secures Her ..."
        },
        {
          "title": "Olympic track and field at Paris 2024: Biggest stories, replays, medal ...",
          "url": "https://www.nbcolympics.com/news/olympic-track-and-field-paris-2024-biggest-stories-replays-medal-results-top-athletes-new",
          "date": "2024-08-11",
          "last_updated": "2024-08-11",
          "snippet": "In the Paris Olympic men's 100m final, Lyles edged past Jamaican Kishane Thompson to win his first Olympic gold medal in a lifetime-best 9.784 ..."
        },
        {
          "title": "When Every Millisecond Counts at the Olympics | Top Moments",
          "url": "https://www.youtube.com/watch?v=WajxULWXIFE",
          "date": "2025-01-31",
          "last_updated": "2025-07-29",
          "snippet": "Re-live ALL the incredible #Paris2024 action: ➡️ https://oly.ch/P24Replays The most thrilling finishes of the Olympic Games in Paris 2024 ..."
        },
        {
          "title": "Olympic gymnastics at Paris 2024: Biggest stories, replays, medal ...",
          "url": "https://www.nbcolympics.com/news/olympic-gymnastics-paris-2024-biggest-stories-replays-medal-results-top-athletes-new-records",
          "date": "2024-08-11",
          "last_updated": "2024-08-11",
          "snippet": "Here's a look back at all the action, from highlights to medal results and everything in between. FULL EVENT REPLAYS:ARTISTIC GYMNASTICS"
        },
        {
          "title": "Best of Olympic Games Paris 2024 - YouTube",
          "url": "https://www.youtube.com/watch?v=vy6FivZHRjQ",
          "date": "2024-10-21",
          "last_updated": "2025-07-27",
          "snippet": "the Paris 2024 Olympics! From jaw-dropping athletic feats to ... highlights, including iconic victories, emotional celebrations, and ..."
        },
        {
          "title": "2024 Olympics: Highlights from Sunday in Paris - ESPN",
          "url": "https://www.espn.com/olympics/story/_/id/40813327/2024-paris-summer-olympics-live-updates-highlights-results-sunday-closing-ceremony",
          "date": "2024-08-11",
          "last_updated": "2024-08-11",
          "snippet": "The US Olympic run concluded with Team USA becoming the first team in any sport to win eight consecutive Olympic gold medals with a win over France."
        },
        {
          "title": "Moments that Left Us SPEECHLESS at Paris 2024! ❤️   - YouTube",
          "url": "https://www.youtube.com/watch?v=q4Mujt1wer4",
          "date": "2025-01-13",
          "last_updated": "2025-08-29",
          "snippet": "I'll always love the moment between Tara Davis-Woodhall and her husband Hunter Woodhall, who'd later snag his first gold medal in the Paralympics later on."
        },
        {
          "title": "Olympics - YouTube",
          "url": "https://www.youtube.com/olympics",
          "date": "2025-03-24",
          "last_updated": "2025-03-26",
          "snippet": "Witness the power, dedication, and skill of Olympic athletes as they compete for their chance to shine on the world stage."
        },
        {
          "title": "‍♂️ Best Athletics Moments at #Paris2024 ‍     - YouTube",
          "url": "https://www.youtube.com/watch?v=OFCVkSQYTjA",
          "date": "2025-03-30",
          "last_updated": "2025-07-29",
          "snippet": "Receive the best athletics moments at the olympic games in Paris 2024 ♂️. #Paris2024 ..."
        },
        {
          "title": "Men's 100m Final | Paris Champions - YouTube",
          "url": "https://www.youtube.com/watch?v=7Xnr805bm4E",
          "date": "2024-08-11",
          "last_updated": "2025-07-28",
          "snippet": "Re-live ALL the incredible #Paris2024 action: https://oly.ch/P24Replays Watch Noah Lyles of Team USA celebrate his gold medal victory ..."
        },
        {
          "title": "All Highlights | NBC Olympics",
          "url": "https://www.nbcolympics.com/videos",
          "date": "2025-09-24",
          "last_updated": "2025-09-25",
          "snippet": "All Highlights · Melissa Jefferson-Wooden claps her hands in joy after winning the world women's 200m final · Three runners prepare to cross the finish line in ..."
        }
      ],
      "videos": [
        {
          "url": "https://www.youtube.com/watch?v=lmPuoxNSRr4",
          "duration": null,
          "thumbnail_width": 480,
          "thumbnail_height": 360,
          "thumbnail_url": "https://www.youtube.com/watch?v=lmPuoxNSRr4"
        },
        {
          "url": "https://www.youtube.com/watch?v=cptEWh0yT4E",
          "duration": null,
          "thumbnail_width": 480,
          "thumbnail_height": 360,
          "thumbnail_url": "https://www.youtube.com/watch?v=cptEWh0yT4E"
        },
        {
          "url": "https://www.youtube.com/watch?v=6bhS_AUKjtc",
          "duration": null,
          "thumbnail_width": 480,
          "thumbnail_height": 360,
          "thumbnail_url": "https://www.youtube.com/watch?v=6bhS_AUKjtc"
        },
        {
          "url": "https://www.youtube.com/watch?v=vy6FivZHRjQ",
          "duration": null,
          "thumbnail_width": 480,
          "thumbnail_height": 360,
          "thumbnail_url": "https://www.youtube.com/watch?v=vy6FivZHRjQ"
        },
        {
          "url": "https://www.youtube.com/watch?v=WajxULWXIFE",
          "duration": null,
          "thumbnail_width": 480,
          "thumbnail_height": 360,
          "thumbnail_url": "https://www.youtube.com/watch?v=WajxULWXIFE"
        }
      ],
      "object": "chat.completion",
      "choices": [
        {
          "index": 0,
          "finish_reason": "stop",
          "message": {
            "role": "assistant",
            "content": "The 2024 Summer Olympics in Paris were marked by major milestones, standout athletic performances, record medal hauls, and historic firsts[1][2][3][6].\n\n**Key highlights:**\n\n- **Medal Table Leaders:** The United States and China finished tied with 40 gold medals each, but the U.S. claimed the top spot overall with 126 total medals; China followed with 91 total[1][2]. It was the first time the two Olympic powers tied in golds. Japan (20 golds), Australia (18 golds), and host nation France (16 golds) rounded out the top five[1].\n\n- **Breakdancing Debut:** Paris 2024 introduced **breaking** (breakdancing) as an Olympic sport for the first time[1].\n\n- **Athletics Dominance:** The U.S. displayed overwhelming strength in **track and field**, securing 34 medals—their best since 1984—and sweeping all four hurdle events for the first time[3]. Noah Lyles won his first Olympic gold in the men's 100m with a dramatic, lifetime-best 9.784 seconds[3][4]. Sydney McLaughlin-Levrone broke her own women's 400m hurdles world record yet again[3].\n\n- **Gymnastics Spectacle:** The games featured high drama and new records in **artistic gymnastics**, with full event replays and standout moments available for fans[5].\n\n- **Historic Firsts:** Several nations, including **Dominica, Saint Lucia, Cape Verde, and Albania**, celebrated their first-ever Olympic medals—some of them gold[1]. The **Refugee Olympic Team** won its first medal, a bronze in boxing by Cindy Ngamba[1].\n\n- **Iconic Performances:** Scottie Scheffler secured his first Olympic golf gold for Team USA; Victor Montalvo earned bronze in breaking; and Brooke Raboutou delivered in sport climbing[2].\n\n- **Intensity and Sportsmanship:** Multiple events featured finishes decided by milliseconds and millimeters, capturing the Olympic spirit, as showcased in event highlight reels and replays[4][6].\n\n- **Record-Breaking Tickets:** Paris 2024 broke Olympic records with over 9.5 million tickets sold (12.1 million including Paralympics), becoming a celebrated success despite some controversies around politics and logistics[1].\n\n**Notable Podium Sweep:** France swept all three medals in the men's BMX race, a moment of national pride[1].\n\nThe Paris Olympics were hailed as both a sporting and organizational triumph, celebrated by both locals and worldwide observers[1]."
          },
          "delta": {
            "role": "assistant",
            "content": ""
          }
        }
      ]
    }
    ```
  </Accordion>
</AccordionGroup>

## Use Case Examples

### Sports and Events

Request videos for major sporting events or news:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.perplexity.ai/chat/completions \
    -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "sonar-pro",
      "media_response": {
        "overrides": {
          "return_videos": true
        }
      },
      "messages": [
        {
          "role": "user",
          "content": "World Cup 2024 final match highlights"
        }
      ]
    }' | jq
  ```

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

  response = requests.post(
      "https://api.perplexity.ai/chat/completions",
      headers={
          "Authorization": f"Bearer {os.environ['PERPLEXITY_API_KEY']}",
          "Content-Type": "application/json"
      },
      json={
          "model": "sonar-pro",
          "media_response": {
              "overrides": {
                  "return_videos": True
              }
          },
          "messages": [
              {
                  "role": "user",
                  "content": "World Cup 2024 final match highlights"
              }
          ]
      }
  )
  print(json.dumps(response.json(), indent=2))
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch('https://api.perplexity.ai/chat/completions', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.PERPLEXITY_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      model: 'sonar-pro',
      media_response: {
        overrides: {
          return_videos: true
        }
      },
      messages: [
        {
          role: 'user',
          content: 'World Cup 2024 final match highlights'
        }
      ]
    })
  });

  const result = await response.json();
  console.log(JSON.stringify(result, null, 2));
  ```
</CodeGroup>

### Educational Content

Get instructional videos for learning topics:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.perplexity.ai/chat/completions \
    -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "sonar-pro",
      "media_response": {
        "overrides": {
          "return_videos": true
        }
      },
      "messages": [
        {
          "role": "user",
          "content": "How to perform CPR tutorial videos"
        }
      ]
    }' | jq
  ```

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

  response = requests.post(
      "https://api.perplexity.ai/chat/completions",
      headers={
          "Authorization": f"Bearer {os.environ['PERPLEXITY_API_KEY']}",
          "Content-Type": "application/json"
      },
      json={
          "model": "sonar-pro",
          "media_response": {
              "overrides": {
                  "return_videos": True
              }
          },
          "messages": [
              {
                  "role": "user",
                  "content": "How to perform CPR tutorial videos"
              }
          ]
      }
  )
  print(response.json())
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch('https://api.perplexity.ai/chat/completions', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.PERPLEXITY_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      model: 'sonar-pro',
      media_response: {
        overrides: {
          return_videos: true
        }
      },
      messages: [
        {
          role: 'user',
          content: 'How to perform CPR tutorial videos'
        }
      ]
    })
  });

  const result = await response.json();
  console.log(result);
  ```
</CodeGroup>

### Technology Demonstrations

Request videos showing product demos or tutorials:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.perplexity.ai/chat/completions \
    -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "sonar-pro",
      "media_response": {
        "overrides": {
          "return_videos": true
        }
      },
      "messages": [
        {
          "role": "user",
          "content": "iPhone 16 pro camera features demonstration"
        }
      ]
    }' | jq
  ```

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

  response = requests.post(
      "https://api.perplexity.ai/chat/completions",
      headers={
          "Authorization": f"Bearer {os.environ['PERPLEXITY_API_KEY']}",
          "Content-Type": "application/json"
      },
      json={
          "model": "sonar-pro",
          "media_response": {
              "overrides": {
                  "return_videos": True
              }
          },
          "messages": [
              {
                  "role": "user",
                  "content": "iPhone 16 pro camera features demonstration"
              }
          ]
      }
  )
  print(response.json())
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch('https://api.perplexity.ai/chat/completions', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.PERPLEXITY_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      model: 'sonar-pro',
      media_response: {
        overrides: {
          return_videos: true
        }
      },
      messages: [
        {
          role: 'user',
          content: 'iPhone 16 pro camera features demonstration'
        }
      ]
    })
  });

  const result = await response.json();
  console.log(result);
  ```
</CodeGroup>

## Combined Media Responses

You can combine video returns with other media response options:

### Videos with Images

```bash  theme={null}
curl https://api.perplexity.ai/chat/completions \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sonar-pro",
    "media_response": {
      "overrides": {
        "return_videos": true,
        "return_images": true
      }
    },
    "messages": [
      {
        "role": "user",
        "content": "Mars rover discoveries 2024"
      }
    ]
  }' | jq
```

### Videos with Search Filters

```bash  theme={null}
curl https://api.perplexity.ai/chat/completions \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sonar-pro",
    "search_recency_filter": "week",
    "media_response": {
      "overrides": {
        "return_videos": true
      }
    },
    "messages": [
      {
        "role": "user",
        "content": "Latest SpaceX launch footage"
      }
    ]
  }' | jq
```

## Advanced Usage

### Streaming with Videos

Enable streaming responses while including video content:

```bash  theme={null}
curl https://api.perplexity.ai/chat/completions \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sonar-pro",
    "stream": true,
    "media_response": {
      "overrides": {
        "return_videos": true
      }
    },
    "messages": [
      {
        "role": "user",
        "content": "Breaking news today with video coverage"
      }
    ]
  }'
```

### Multi-turn Conversation with Videos

Continue a conversation while maintaining video context:

```bash  theme={null}
curl https://api.perplexity.ai/chat/completions \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sonar-pro",
    "media_response": {
      "overrides": {
        "return_videos": true
      }
    },
    "messages": [
      {
        "role": "user",
        "content": "Show me cooking videos for pasta recipes"
      },
      {
        "role": "assistant",
        "content": "Here are some great pasta cooking videos..."
      },
      {
        "role": "user",
        "content": "Now show me videos for making homemade sauce"
      }
    ]
  }' | jq
```

## Best Practices

<AccordionGroup>
  <Accordion title="Query Optimization">
    * **Be specific**: Use descriptive queries that clearly indicate when video content would be valuable
    * **Include context**: Mention specific events, products, or topics that commonly have video coverage
    * **Use recency filters**: Combine with search filters to get the most current video content
    * **Consider query intent**: Videos work best for demonstrations, tutorials, events, and visual explanations
  </Accordion>

  <Accordion title="Performance Considerations">
    * **Monitor response times**: Video-enabled requests may take longer to process
    * **Handle larger payloads**: Responses containing videos will be larger than text-only responses
    * **Implement timeouts**: Set appropriate timeout values for video-enabled requests
    * **Cache strategically**: Consider caching video responses for frequently requested content
  </Accordion>

  <Accordion title="Content Quality">
    * **Verify video relevance**: Not all queries will return relevant video content
    * **Handle empty results**: Implement fallback logic when no videos are available
    * **Check video accessibility**: Ensure returned video content is accessible and appropriate
    * **Validate video links**: Test that returned video URLs are functional before displaying
  </Accordion>
</AccordionGroup>

## Response Format

When videos are returned, they appear in the response content along with text. The videos will be included as part of the response structure, with video URLs and metadata available for display or processing.

## Common Use Cases

### News and Current Events

```bash  theme={null}
# Get breaking news with video coverage
curl https://api.perplexity.ai/chat/completions \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sonar-pro",
    "search_recency_filter": "day",
    "media_response": {
      "overrides": {
        "return_videos": true
      }
    },
    "messages": [
      {"role": "user", "content": "Latest political developments today"}
    ]
  }'
```

### Product Reviews and Demonstrations

```bash  theme={null}
# Get product demo videos
curl https://api.perplexity.ai/chat/completions \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sonar-pro",
    "media_response": {
      "overrides": {
        "return_videos": true
      }
    },
    "messages": [
      {"role": "user", "content": "MacBook Pro M4 unboxing and first impressions"}
    ]
  }'
```

### Educational and How-to Content

```bash  theme={null}
# Get tutorial videos
curl https://api.perplexity.ai/chat/completions \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sonar-pro",
    "media_response": {
      "overrides": {
        "return_videos": true
      }
    },
    "messages": [
      {"role": "user", "content": "How to change a car tire step by step"}
    ]
  }'
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="No Videos Returned">
    If your request doesn't return videos:

    * Verify the `media_response.overrides.return_videos` parameter is set to `true`
    * Check that your query is likely to have video content available
    * Ensure you're using a model that supports video returns (sonar-pro recommended)
    * Try different query phrasings that explicitly mention video content
  </Accordion>

  <Accordion title="Request Timeouts">
    For timeout issues:

    * Increase your request timeout settings
    * Use streaming responses for better user experience
    * Consider breaking complex queries into smaller parts
    * Implement retry logic for failed requests
  </Accordion>

  <Accordion title="Large Response Handling">
    When dealing with video-heavy responses:

    * Implement proper JSON parsing for large payloads
    * Consider pagination for multiple video results
    * Use appropriate data structures to handle media content
    * Implement progressive loading for video content
  </Accordion>
</AccordionGroup>

## Limitations

<Warning>
  **Current Limitations:**

  * Video returns may not be available for all query types
  * Response times will be longer when videos are included
  * Video content availability depends on external sources
  * Some video content may be region-restricted
  * No direct video format or quality control options currently available
</Warning>

## Environment Variables

For security, use environment variables for your API key:

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

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

Then reference it in your requests:

```bash  theme={null}
curl https://api.perplexity.ai/chat/completions \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "sonar-pro", ...}'
```

<Tip>
  Start with simple queries to test video returns, then gradually build more complex requests as you understand the response patterns and performance characteristics.
</Tip>


# Best Practices
Source: https://docs.perplexity.ai/guides/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",
          maxResults: 10
      });

      // Avoid: Vague query
      const search = await client.search.create({
          query: "AI medical",
          maxResults: 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 each query
      for i, query_results in enumerate(search.results):
          print(f"Results for query {i+1}:")
          for result in query_results:
              print(f"  {result.title}: {result.url}")
          print("---")
      ```

      ```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"
          ],
          maxResults: 5
      });

      // Access results for each query
      search.results.forEach((queryResults, i) => {
          console.log(`Results for query ${i+1}:`);
          queryResults.forEach(result => {
              console.log(`  ${result.title}: ${result.url}`);
          });
          console.log("---");
      });
      ```
    </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 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

      # 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");
      }

      // 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,
                      maxResults: 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",
              maxResults: 5
          }),
          client.search.create({
              query: "machine learning breakthroughs",
              maxResults: 5
          }),
          client.search.create({
              query: "deep learning applications",
              maxResults: 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",
              maxResults: 5
          }),
          client.search.create({
              query: "machine learning breakthroughs",
              maxResults: 5
          }),
          client.search.create({
              query: "deep learning applications",
              maxResults: 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, maxResults: 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, maxResults: 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 cols={2}>
  <Card title="Quickstart" icon="rocket" href="/guides/search-quickstart">
    Get started with basic search functionality
  </Card>

  <Card title="Perplexity SDK" icon="code" href="/guides/perplexity-sdk">
    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>


# Sonar Search Context Size
Source: https://docs.perplexity.ai/guides/search-context-size-guide



<Note>
  The `search_context_size` parameter allows you to control how much search context is retrieved from the web during query resolution, letting you balance cost and comprehensiveness.
</Note>

<Warning>
  * Default `search_context_size` is `low`
  * Selecting `"high"` increases search costs due to more extensive web retrieval. Use `"low"` when cost efficiency is critical.
</Warning>

## Overview

The `search_context_size` field—passed via the `web_search_options` object—determines how much search context is retrieved by the Sonar models. This setting can help you optimize for either:

* Cost savings with minimal search input (`low`)
* Comprehensive answers by maximizing retrieved information (`high`)
* A balance of both (`medium`)

This flexibility allows teams to tune their API usage to their budget and use case.

To enable this feature, include the web\_search\_options.search\_context\_size parameter in your request payload:

```bash  theme={null}
"web_search_options": {
  "search_context_size": "medium"
}
```

## Best Practices

**Choosing the Right Context Size**

* `low`: Best for short factual queries or when operating under strict token cost constraints.
* `medium`: The default and best suited for general use cases.
* `high`: Use for deep research, exploratory questions, or when citations and evidence coverage are critical.

**Cost Optimization**

* Selecting `low` or `medium` can significantly reduce overall token usage, especially at scale.
* Consider defaulting to `low` for high-volume endpoints and selectively upgrading to `high` for complex user prompts.

Combining with Other Filters

* You can use `search_context_size` alongside other features like `search_domain_filter` to further control the scope of search.
* Combining `medium` with a focused domain filter often gives a good tradeoff between quality and cost.

Performance Considerations

* Larger context sizes may slightly increase response latency due to more extensive search and reranking.
* If you’re batching queries or supporting real-time interfaces, test with different settings to balance user experience and runtime.

## Examples

**1. Minimal Search Context ("low")**

This option limits the search context retrieved for the model, reducing cost per request while still producing useful responses for simpler questions.

## Request

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.perplexity.ai/chat/completions \
    --header "Authorization: Bearer $SONAR_API_KEY" \
    --header "Content-Type: application/json" \
    --data '{
      "model": "sonar",
      "messages": [
        {
          "role": "system",
          "content": "Be precise and concise."
        },
        {
          "role": "user",
          "content": "How many stars are there in our galaxy?"
        }
      ],
      "web_search_options": {
        "search_context_size": "low"
      }
    }' | jq
  ```

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

  client = Perplexity()

  completion = client.chat.completions.create(
      model="sonar",
      messages=[
          {"role": "system", "content": "Be precise and concise."},
          {"role": "user", "content": "How many stars are there in our galaxy?"}
      ],
      web_search_options={
          "search_context_size": "low"
      }
  )

  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": "system", "content": "Be precise and concise."},
      {"role": "user", "content": "How many stars are there in our galaxy?"}
    ],
    web_search_options: {
      "search_context_size": "low"
    }
  });

  console.log(completion.choices[0].message.content);
  ```
</CodeGroup>

**Pro-tip**: Use `low` when cost optimization is more important than answer completeness.

**2. Comprehensive Search Context ("high")**

This option maximizes the amount of search context used to answer the question, resulting in more thorough and nuanced responses.

## Request

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.perplexity.ai/chat/completions \
    --header "Authorization: Bearer $SONAR_API_KEY" \
    --header "Content-Type: application/json" \
    --data '{
      "model": "sonar",
      "messages": [
        {
          "role": "system",
          "content": "Be precise and concise."
        },
        {
          "role": "user",
          "content": "Explain the economic causes of the 2008 financial crisis."
        }
      ],
      "web_search_options": {
        "search_context_size": "high"
      }
    }' | jq
  ```

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

  client = Perplexity()

  completion = client.chat.completions.create(
      model="sonar",
      messages=[
          {"role": "system", "content": "Be precise and concise."},
          {"role": "user", "content": "Explain the economic causes of the 2008 financial crisis."}
      ],
      web_search_options={
          "search_context_size": "high"
      }
  )

  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": "system", "content": "Be precise and concise."},
      {"role": "user", "content": "Explain the economic causes of the 2008 financial crisis."}
    ],
    web_search_options: {
      "search_context_size": "high"
    }
  });

  console.log(completion.choices[0].message.content);
  ```
</CodeGroup>

**Pro-tip**: Use `high` for research-heavy or nuanced queries where coverage matters more than cost.

⸻


# Sonar Web Search Control
Source: https://docs.perplexity.ai/guides/search-control-guide

Control when Sonar models search the web using the search classifier or by disabling search altogether.

## Overview

Sonar models provide powerful web search capabilities, but there are times when you want to control when and how searches are performed. Perplexity offers two main approaches for search control:

* **Search Classifier** - Let AI intelligently decide when to search based on the query context
* **Disable Search** - Turn off web search completely for specific requests

<Info>
  Search control is available across all Sonar models.
</Info>

<Warning>
  Pricing remains the same regardless of whether search is triggered or not. Search control features are designed for performance optimization and user experience, not cost reduction.
</Warning>

## Search Classifier

The search classifier is a trained model that automatically determines whether a web search is necessary based on the context and content of your query. This helps optimize performance and costs by only searching when beneficial.

### How It Works

The classifier analyzes your query and decides whether:

* **Search is needed** - For questions requiring current information, facts, or research
* **Search is unnecessary** - For creative tasks, math problems, or general knowledge that doesn't require real-time data

### When to Use Search Classifier

Use the search classifier when you want to:

* **Improve response speed** - Skip search for queries that don't benefit from it
* **Automatic intelligence** - Let AI decide the best approach for each query
* **Optimal user experience** - Ensure search is only used when it adds value

<Tabs>
  <Tab title="Python">
    ```python  theme={null}
    import requests

    # API configuration
    API_URL = "https://api.perplexity.ai/chat/completions"
    API_KEY = "your-api-key-here"

    headers = {
        "accept": "application/json",
        "authorization": f"Bearer {API_KEY}",
        "content-type": "application/json"
    }

    # Query that benefits from search classifier
    user_query = "What are the latest developments in quantum computing?"

    payload = {
        "model": "sonar-pro",
        "messages": [{"role": "user", "content": user_query}],
        "stream": False,
        "enable_search_classifier": True
    }

    response = requests.post(API_URL, json=payload, headers=headers)
    print(response.json())
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript  theme={null}
    interface ChatCompletionRequest {
      model: string;
      messages: Array<{role: string; content: string}>;
      stream?: boolean;
      enable_search_classifier?: boolean;
    }

    const API_URL = "https://api.perplexity.ai/chat/completions";
    const API_KEY = "your-api-key-here";

    const headers = {
      "accept": "application/json",
      "authorization": `Bearer ${API_KEY}`,
      "content-type": "application/json"
    };

    // Query that benefits from search classifier
    const userQuery = "What are the latest developments in quantum computing?";

    const payload: ChatCompletionRequest = {
      model: "sonar-pro",
      messages: [{role: "user", content: userQuery}],
      stream: false,
      enable_search_classifier: true
    };

    fetch(API_URL, {
      method: "POST",
      headers: headers,
      body: JSON.stringify(payload)
    })
    .then(response => response.json())
    .then(data => console.log(data));
    ```
  </Tab>

  <Tab title="cURL">
    ```bash  theme={null}
    curl -X POST "https://api.perplexity.ai/chat/completions" \
      -H "accept: application/json" \
      -H "authorization: Bearer $SONAR_API_KEY" \
      -H "content-type: application/json" \
      -d '{
        "model": "sonar",
        "messages": [
          {
            "role": "user", 
            "content": "What is 2+2?"
          }
        ],
        "stream": false,
        "enable_search_classifier": true
      }' | jq
    ```
  </Tab>
</Tabs>

### Search Classifier Examples

<AccordionGroup>
  <Accordion title="Queries that typically trigger search">
    * "What happened in the stock market today?"
    * "Latest news about renewable energy"
    * "Current weather in San Francisco"
    * "Recent research on machine learning"
  </Accordion>

  <Accordion title="Queries that typically skip search">
    * "What is 2 + 2?"
    * "Write a creative story about a dragon"
    * "Explain the concept of recursion"
    * "Generate a business name for a bakery"
  </Accordion>
</AccordionGroup>

## Disabling Search Completely

For certain use cases, you may want to disable web search entirely. This is useful when:

* **Offline-like responses** - Get responses based only on training data
* **Creative tasks** - Focus on generation without external influence
* **Deterministic responses** - Ensure consistent outputs based only on training data

### Implementation

To disable search completely, set the `disable_search` parameter to `true`:

<Tabs>
  <Tab title="Python">
    ```python  theme={null}
    import requests

    # API configuration
    API_URL = "https://api.perplexity.ai/chat/completions"
    API_KEY = "your-api-key-here"

    headers = {
        "accept": "application/json",
        "authorization": f"Bearer {API_KEY}",
        "content-type": "application/json"
    }

    # Query that doesn't need web search
    user_query = "What is 2 + 2?"

    payload = {
        "model": "sonar-pro",
        "messages": [{"role": "user", "content": user_query}],
        "stream": False,
        "disable_search": True
    }

    response = requests.post(API_URL, json=payload, headers=headers)
    print(response.json())
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript  theme={null}
    interface ChatCompletionRequest {
      model: string;
      messages: Array<{role: string; content: string}>;
      stream?: boolean;
      disable_search?: boolean;
    }

    const API_URL = "https://api.perplexity.ai/chat/completions";
    const API_KEY = "your-api-key-here";

    const headers = {
      "accept": "application/json",
      "authorization": `Bearer ${API_KEY}`,
      "content-type": "application/json"
    };

    // Query that doesn't need web search
    const userQuery = "What is 2 + 2?";

    const payload: ChatCompletionRequest = {
      model: "sonar-pro",
      messages: [{role: "user", content: userQuery}],
      stream: false,
      disable_search: true
    };

    fetch(API_URL, {
      method: "POST",
      headers: headers,
      body: JSON.stringify(payload)
    })
    .then(response => response.json())
    .then(data => console.log(data));
    ```
  </Tab>

  <Tab title="cURL">
    ```bash  theme={null}
    curl -X POST "https://api.perplexity.ai/chat/completions" \
      -H "accept: application/json" \
      -H "authorization: Bearer your-api-key-here" \
      -H "content-type: application/json" \
      -d '{
        "model": "sonar-pro",
        "messages": [
          {
            "role": "user", 
            "content": "What is 2 + 2?"
          }
        ],
        "stream": false,
        "disable_search": true
      }'
    ```
  </Tab>
</Tabs>

<Warning>
  When search is disabled, responses will be based solely on the model's training data and may not include the most current information.
</Warning>

## Comparison and Best Practices

### When to Use Each Approach

<CardGroup cols={2}>
  <Card title="Search Classifier" icon="brain">
    **Best for:**

    * Mixed workloads with varying query types
    * Performance optimization without manual intervention
    * General-purpose applications
    * Unknown query patterns
  </Card>

  <Card title="Disabled Search" icon="ban">
    **Best for:**

    * Creative content generation
    * Mathematical computations
    * Sensitive data processing
    * Offline-like experiences
  </Card>
</CardGroup>

### Performance Considerations

<Tabs>
  <Tab title="Response Time">
    **Search Classifier:** Variable response time depending on whether search is triggered

    **Disabled Search:** Consistently faster responses since no search operations occur
  </Tab>

  <Tab title="Information Accuracy">
    **Search Classifier:** Provides current information when search is triggered

    **Disabled Search:** Limited to training data cutoff date
  </Tab>
</Tabs>

## Complete Examples

### Search Classifier in Action

<Steps>
  <Step title="Set up the request with search classifier">
    ```python  theme={null}
    payload = {
        "model": "sonar-pro",
        "messages": [{"role": "user", "content": "Explain machine learning"}],
        "enable_search_classifier": True
    }
    ```

    <Info>
      The classifier will likely skip search for this general concept explanation.
    </Info>
  </Step>

  <Step title="Try with a current events query">
    ```python  theme={null}
    payload = {
        "model": "sonar-pro", 
        "messages": [{"role": "user", "content": "Latest AI news this week"}],
        "enable_search_classifier": True
    }
    ```

    <Check>
      The classifier will trigger search for this time-sensitive query.
    </Check>
  </Step>
</Steps>

### Creative Task with Disabled Search

Here's an example of using disabled search for creative content generation:

```python  theme={null}
import requests

payload = {
    "model": "sonar-pro",
    "messages": [
        {
            "role": "user", 
            "content": "Write a short science fiction story about time travel"
        }
    ],
    "disable_search": True,
    "temperature": 0.8
}

response = requests.post(
    "https://api.perplexity.ai/chat/completions",
    headers={
        "authorization": "Bearer your-api-key-here",
        "content-type": "application/json"
    },
    json=payload
)
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Search classifier not working as expected">
    **Common causes:**

    * API key doesn't have access to classifier features
    * Using an unsupported model
    * Incorrect parameter syntax

    **Solutions:**

    * Verify your API key permissions
    * Ensure you're using a Sonar model
    * Check parameter spelling: `enable_search_classifier`
  </Accordion>

  <Accordion title="Responses seem outdated with disabled search">
    This is expected behavior when search is disabled. The model can only use information from its training data.

    **Solutions:**

    * Re-enable search for queries requiring current information
    * Use search classifier for automatic optimization
    * Clearly document when search is disabled for your users
  </Accordion>
</AccordionGroup>

<Tip>
  Start with the search classifier for most applications, then selectively disable search for specific use cases where you want guaranteed offline-like behavior.
</Tip>


# Search Date and Time Filters
Source: https://docs.perplexity.ai/guides/search-date-time-filters



<Note>
  The `search_after_date` and `search_before_date` 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 `search_recency_filter` parameter provides a convenient way to filter results by predefined time periods (e.g., "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 "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 two types of date and time filters available:

### Publication Date Filters

The `search_after_date` and `search_before_date` 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

### 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 day, week, month, or year
* Get recent results without specifying exact dates
* Quickly filter for timely information

**Available values:**

* `"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, 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": "3/1/2025",
"search_before_date": "3/5/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(
      query="latest AI developments",
      max_results=10,
      search_after_date="3/1/2025",
      search_before_date="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({
    query: "latest AI developments",
    max_results: 10,
    search_after_date: "3/1/2025",
    search_before_date: "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": "3/1/2025",
      "search_before_date": "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`:

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

  client = Perplexity()

  response = client.search(
      query="tech news published after March 1, 2025",
      max_results=10,
      search_after_date="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({
    query: "tech news published after March 1, 2025",
    max_results: 10,
    search_after_date: "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": "3/1/2025"
    }' | jq
  ```
</CodeGroup>

**3. 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(
      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({
    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.

**4. Different Recency Filter Options**

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

  client = Perplexity()

  # Get content from the past day
  day_response = client.search(
      query="breaking tech news",
      max_results=5,
      search_recency_filter="day"
  )

  # Get content from the past month
  month_response = client.search(
      query="AI research developments",
      max_results=10,
      search_recency_filter="month"
  )

  # Get content from the past year
  year_response = client.search(
      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 day
  const dayResponse = await client.search({
    query: "breaking tech news",
    max_results: 5,
    search_recency_filter: "day"
  });

  // Get content from the past month
  const monthResponse = await client.search({
    query: "AI research developments",
    max_results: 10,
    search_recency_filter: "month"
  });

  // Get content from the past year
  const yearResponse = await client.search({
    query: "major tech trends",
    max_results: 15,
    search_recency_filter: "year"
  });
  ```

  ```bash cURL theme={null}
  # 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`

* **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": "1/1/2025"`

### `search_before_date`

* **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": "12/31/2025"`

### `search_recency_filter`

* **Type**: String
* **Allowed Values**: "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`/`search_before_date`) when you care about when content was originally created. 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.
* Filter Limitations: Note that `search_recency_filter` cannot be combined with specific date filters (`search_after_date`/`search_before_date`).

**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 "day" to find the most recent breaking news:

```python  theme={null}
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="1/1/2023",
    search_before_date="12/31/2023"
)
```

**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="1/1/2023",
    search_before_date="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=after_date,
              search_before_date=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({
        query,
        search_after_date: afterDate,
        search_before_date: beforeDate
      });
      return response;
    } catch (error) {
      console.error('Search failed:', error);
      return null;
    }
  }
  ```
</CodeGroup>


# Search Domain Filter
Source: https://docs.perplexity.ai/guides/search-domain-filter-guide



<Note>
  The `search_domain_filter` parameter allows you to limit search results to specific domains or URLs, enabling focused research from trusted sources. You can also exclude domains by prefixing them with a `-` character.
</Note>

<Info>
  Domain filters support both allowlisting (include specific domains) and denylisting (exclude specific domains). 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 unwanted domains. This is particularly useful when you need to:

* Focus research on authoritative or trusted sources
* Search within specific publication networks or organizations
* Exclude unreliable or off-topic domains from results
* Build domain-specific search applications
* Conduct competitive research within specific industry domains

The `search_domain_filter` parameter accepts an array of domain strings and supports two filtering modes:

### Allowlisting (Include Domains)

Allowlisting restricts results to only the specified domains. This is useful when you want to search exclusively within trusted or relevant sources.

```bash  theme={null}
"search_domain_filter": ["nature.com", "science.org", "cell.com"]
```

### Denylisting (Exclude Domains)

Denylisting excludes specific domains from your results by prefixing them with a `-` character. This is useful when you want broad coverage but need to filter out specific sources.

```bash  theme={null}
"search_domain_filter": ["-example.com", "-spam-site.net"]
```

<Warning>
  You cannot combine allowlisting and denylisting in the same request. Use either inclusion (no prefix) or exclusion (`-` prefix), but not both.
</Warning>

## Examples

**1. Allowlisting Academic Sources**

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",
    maxResults: 10,
    searchDomainFilter: [
      "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. Denylisting Unwanted Sources**

Exclude specific domains from your search results:

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

  client = Perplexity()

  response = client.search.create(
      query="artificial intelligence news",
      max_results=15,
      search_domain_filter=[
          "-socialmedia.com",
          "-clickbait-news.net"
      ]
  )

  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();

  const response = await client.search.create({
    query: "artificial intelligence news",
    maxResults: 15,
    searchDomainFilter: [
      "-socialmedia.com",
      "-clickbait-news.net"
    ]
  });

  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": "artificial intelligence news",
      "max_results": 15,
      "search_domain_filter": [
        "-socialmedia.com",
        "-clickbait-news.net"
      ]
    }' | jq
  ```
</CodeGroup>

**3. 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",
    maxResults: 10,
    searchDomainFilter: [
      "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>

**4. 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",
    maxResults: 20,
    searchDomainFilter: [
      "nature.com",
      "science.org",
      "arxiv.org"
    ],
    searchRecencyFilter: "month",
    searchLanguageFilter: ["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")
* **Description**: Filters search results to only include (allowlist) or exclude (denylist) content from specified domains
* **Optional**: Yes
* **Maximum**: 20 domains per request
* **Allowlisting Example**: `"search_domain_filter": ["nature.com", "science.org"]`
* **Denylisting Example**: `"search_domain_filter": ["-spam.com", "-ads.net"]`

## Domain Format Guidelines

**Correct Domain Formats:**

* `"nature.com"` - Root domain
* `"blog.example.com"` - Subdomain
* `"arxiv.org"` - Root domain
* `"-unwanted.net"` - Denylist with prefix

**Incorrect Domain Formats:**

* ❌ `"https://nature.com"` - Don't include protocol
* ❌ `"nature.com/"` - Don't include trailing slash
* ❌ `"nature.com/articles"` - Don't include path
* ❌ `"www.nature.com"` - Avoid www prefix (use root domain)

## Best Practices

### Domain Selection Strategy

* **Use Root Domains**: Specify root domains (e.g., "nature.com") rather than subdomains or specific paths. The filter will match all content from that domain.
* **Be Specific**: Choose 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.

### Filtering Mode Selection

* **Allowlisting**: Use when you have a specific set of trusted sources you want to search within (e.g., academic research, official documentation).
* **Denylisting**: Use when you want broad coverage but need to exclude known problematic sources (e.g., spam sites, social media).
* **Never Mix**: Do not combine allowlisting and denylisting in the same request. Choose one approach based on your needs.

### 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."""
      # Remove denylist prefix if present
      clean_domain = domain.lstrip('-')

      # Basic 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, clean_domain))

  def validate_domain_filter(domains):
      """Validate domain filter array."""
      if len(domains) > 20:
          raise ValueError("Maximum 20 domains allowed")

      # Check for mixed allowlist/denylist
      has_allowlist = any(not d.startswith('-') for d in domains)
      has_denylist = any(d.startswith('-') for d in domains)

      if has_allowlist and has_denylist:
          raise ValueError("Cannot mix allowlisting and denylisting")

      for domain in domains:
          if not validate_domain(domain):
              raise ValueError(f"Invalid domain format: {domain}")

      return True

  # Usage
  try:
      domains = ["nature.com", "science.org", "arxiv.org"]
      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 {
    // Remove denylist prefix if present
    const cleanDomain = domain.replace(/^-/, '');

    // Basic 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(cleanDomain);
  }

  function validateDomainFilter(domains: string[]): void {
    if (domains.length > 20) {
      throw new Error("Maximum 20 domains allowed");
    }

    // Check for mixed allowlist/denylist
    const hasAllowlist = domains.some(d => !d.startsWith('-'));
    const hasDenylist = domains.some(d => d.startsWith('-'));

    if (hasAllowlist && hasDenylist) {
      throw new Error("Cannot mix allowlisting and denylisting");
    }

    for (const domain of domains) {
      if (!validateDomain(domain)) {
        throw new Error(`Invalid domain format: ${domain}`);
      }
    }
  }

  // Usage
  try {
    const domains = ["nature.com", "science.org", "arxiv.org"];
    validateDomainFilter(domains);

    const response = await client.search.create({
      query: "research topic",
      searchDomainFilter: 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.
</Tip>


# Sonar Domain Filter Guide
Source: https://docs.perplexity.ai/guides/search-domain-filters



<Note>
  The `search_domain_filter` feature allows you to limit search results to specific domains/URLs or exclude certain domains/URLs from search results. This supports both broad domain-level filtering and granular URL-level filtering for precise content control.
</Note>

<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>

<Warning>
  Before adding URLs to your allowlist, test that they are accessible via the API by making a sample request. URLs that are blocked, require authentication, or have access restrictions may not return search results, which can significantly impact response quality when using allowlist mode.
</Warning>

## Overview

The `search_domain_filter` parameter allows you to control which websites are included in or excluded from the search results used by the Sonar models. This feature is particularly useful when you want to:

* Restrict search results to trusted sources
* Filter out specific domains from search results
* Focus research on particular websites

Enabling domain filtering can be done by adding a `search_domain_filter` field in the request:

```
"search_domain_filter": [
  "<domain1>",
  "<domain2>",
  ...
]
```

Each entry in the list can be a domain name or a specific URL. The filter operates in two modes:

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

## Filtering Capabilities

### Domain-Level Filtering

Filter entire domains for broad control:

```json  theme={null}
// Allowlist: Only search these domains
"search_domain_filter": ["wikipedia.org", "github.com", "stackoverflow.com"]

// Denylist: Exclude these domains  
"search_domain_filter": ["-reddit.com", "-pinterest.com", "-quora.com"]
```

### URL-Level Filtering

Target specific pages or sections for granular control:

```json  theme={null}
// Allowlist: Only search these specific URLs
"search_domain_filter": [
  "https://en.wikipedia.org/wiki/Chess",
  "https://stackoverflow.com/questions/tagged/python",
  "https://docs.python.org/3/tutorial/"
]

// Denylist: Exclude these specific URLs
"search_domain_filter": [
  "-https://en.wikipedia.org/wiki/FIDE_rankings",
  "-https://reddit.com/r/politics"
]
```

This granular approach allows you to:

* Include or exclude specific Wikipedia articles while keeping/removing the rest
* Target particular sections of large sites like Stack Overflow or Reddit
* Filter specific documentation pages or subdirectories

## Examples

### 1. Allowlist Specific Domains

This example shows how to limit search results to only include content from specific domains.

**Request**

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

  client = Perplexity()

  completion = client.chat.completions.create(
      model="sonar",
      messages=[
          {"role": "system", "content": "You are a helpful assistant."},
          {"role": "user", "content": "Tell me about the James Webb Space Telescope discoveries."}
      ],
      search_domain_filter=[
          "nasa.gov",
          "wikipedia.org",
          "space.com"
      ]
  )

  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": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Tell me about the James Webb Space Telescope discoveries."}
    ],
    search_domain_filter: [
      "nasa.gov",
      "wikipedia.org",
      "space.com"
    ]
  });

  console.log(completion.choices[0].message.content);
  ```

  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.perplexity.ai/chat/completions \
    --header "Authorization: Bearer YOUR_API_KEY" \
    --header "Content-Type: application/json" \
    --data '{
      "model": "sonar",
      "messages": [
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Tell me about the James Webb Space Telescope discoveries."}
      ],
      "search_domain_filter": [
        "nasa.gov",
        "wikipedia.org",
        "space.com"
      ]
    }' | jq
  ```
</CodeGroup>

**Best Practice**: Use simple domain names (e.g., `wikipedia.org`) without additional elements like `https://` or `www.` prefixes.

### 2. Denylist Specific Domains

This example shows how to exclude specific domains from search results by prefixing the domain name with a minus sign (`-`).

**Request**

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

  client = Perplexity()

  completion = client.chat.completions.create(
      model="sonar",
      messages=[
          {"role": "system", "content": "You are a helpful assistant."},
          {"role": "user", "content": "What are the latest advancements in renewable energy?"}
      ],
      search_domain_filter=[
          "-pinterest.com",
          "-reddit.com",
          "-quora.com"
      ]
  )

  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": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "What are the latest advancements in renewable energy?"}
    ],
    search_domain_filter: [
      "-pinterest.com",
      "-reddit.com",
      "-quora.com"
    ]
  });

  console.log(completion.choices[0].message.content);
  ```

  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.perplexity.ai/chat/completions \
    --header "Authorization: Bearer YOUR_API_KEY" \
    --header "Content-Type: application/json" \
    --data '{
      "model": "sonar",
      "messages": [
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What are the latest advancements in renewable energy?"}
      ],
      "search_domain_filter": [
        "-pinterest.com",
        "-reddit.com",
        "-quora.com"
      ]
    }' | jq
  ```
</CodeGroup>

**Best Practice**: Use simple domain names with a minus prefix (e.g., `-pinterest.com`) to exclude domains from search results.

### 3. URL-Level Filtering for Granular Control

This example shows how to exclude specific pages while keeping the rest of the domain accessible.

**Request**

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

  client = Perplexity()

  completion = client.chat.completions.create(
      model="sonar-pro",
      messages=[
          {"role": "system", "content": "You are a helpful assistant."},
          {"role": "user", "content": "Tell me about chess rankings and tournaments."}
      ],
      search_domain_filter=[
          "-https://en.wikipedia.org/wiki/FIDE_rankings"
      ]
  )

  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-pro",
    messages: [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Tell me about chess rankings and tournaments."}
    ],
    search_domain_filter: [
      "-https://en.wikipedia.org/wiki/FIDE_rankings"
    ]
  });

  console.log(completion.choices[0].message.content);
  ```

  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.perplexity.ai/chat/completions \
    --header "Authorization: Bearer YOUR_API_KEY" \
    --header "Content-Type: application/json" \
    --data '{
      "model": "sonar-pro",
      "messages": [
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Tell me about chess rankings and tournaments."}
      ],
      "search_domain_filter": [
        "-https://en.wikipedia.org/wiki/FIDE_rankings"
      ]
    }' | jq
  ```
</CodeGroup>

**Result**: This will search all websites except the specific FIDE rankings Wikipedia page, while keeping all other Wikipedia content accessible.

**Alternative - Allowlist specific URLs only:**

```json  theme={null}
"search_domain_filter": [
  "https://en.wikipedia.org/wiki/Chess",
  "https://en.wikipedia.org/wiki/World_Chess_Championship",
  "https://chess.com"
]
```

This would only search those three specific sources and ignore all other websites.

## Best Practices

### Domain and URL Specification

* **Domain filtering**: Use simple domain names (e.g., `example.com`) without protocol prefixes for broad filtering.
* **URL filtering**: Use complete URLs including protocol (e.g., `https://en.wikipedia.org/wiki/FIDE_rankings`) for specific page targeting.
* **Subdomain behavior**: Using a main domain (e.g., `nytimes.com`) will filter all subdomains as well.
* **Granular control**: URL-level filtering allows you to include/exclude specific pages while keeping the rest of the domain.

### Filter Optimization

* **Be specific**: Use domains/URLs that are most relevant to your query to get the best results.
* **Choose your mode**: Use either allowlist mode (include only) OR denylist mode (exclude), but not both in the same request.
* **Limit filter size**: You can add up to 20 domains or URLs. Using fewer, more targeted entries often yields better results.
* **URL precision**: Use full URLs (including `https://`) when targeting specific pages for maximum precision.

### Performance Considerations

* Adding domain filters may slightly increase response time as the search engine needs to apply additional filtering.
* Overly restrictive domain filters might result in fewer search results, potentially affecting the quality of the response.


# Search Language Filter
Source: https://docs.perplexity.ai/guides/search-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",
    maxResults: 10,
    searchLanguageFilter: ["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",
    maxResults: 15,
    searchLanguageFilter: ["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",
    maxResults: 10,
    searchLanguageFilter: ["zh", "ja", "ko"]
  });

  // Search for European tech news in multiple European languages
  const euResponse = await client.search.create({
    query: "tech startups",
    maxResults: 10,
    searchLanguageFilter: ["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",
    maxResults: 20,
    searchLanguageFilter: ["en", "de"],
    searchDomainFilter: ["nature.com", "science.org"],
    searchRecencyFilter: "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",
      searchLanguageFilter: 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,
        searchLanguageFilter: languages,
        maxResults: 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>


# Quickstart
Source: https://docs.perplexity.ai/guides/search-quickstart

Get started with Perplexity's Search API to retrieve ranked web search results with advanced filtering and customization options.

## Overview

<Card title="Try Our New Interactive Playground" href="https://perplexity.ai/account/api/playground/search" horizontal="True" cta="Launch Playground">
  Test queries and explore parameters in real-time. **No API key required.**
</Card>

The Search API gives ranked results from Perplexity's continuously refreshed index.

<Info>
  We recommend using our official SDKs 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/JavaScript theme={null}
  npm install @perplexity-ai/perplexity_ai
  ```
</CodeGroup>

## Basic Usage

Start with a basic search query to get relevant web results:

<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=1024
  )

  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",
      maxResults: 5,
      maxTokensPerPage: 1024
  });

  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",
          maxResults: 5,
          maxTokensPerPage: 1024
      });

      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 YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
      "query": "latest AI developments 2024",
      "max_results": 5,
      "max_tokens_per_page": 1024
    }' | 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"
      },
      {
        "title": "The State of AI: Global survey - McKinsey",
        "url": "https://www.mckinsey.com/capabilities/quantumblack/our-insights/the-state-of-ai",
        "snippet": "**Organizations are starting to make** organizational changes designed to generate future value from gen AI, and large companies are leading the way. The latest McKinsey Global Survey on AI finds that organizations are beginning to take steps that drive bottom-line impact—for example, redesigning workflows as they deploy gen AI and putting senior leaders in critical roles, such as overseeing AI governance. The findings also show that organizations are working to mitigate a growing set of gen-AI-related risks and are hiring for new AI-related roles while they retrain employees to participate in AI deployment. Companies with at least $500 million in annual revenue are changing more quickly than smaller organizations. Overall, the use of AI—that is, gen AI as well as analytical AI—continues to build momentum: More than three-quarters of respondents now say that their organizations use AI in at least one business function. The use of gen AI in particular is rapidly increasing.\n\n## How companies are organizing their gen AI deployment—and who's in charge... ## AI is shifting the skills that organizations need\n\nThis survey also examines the state of AI-related hiring and other ways AI affects the workforce. Respondents working for organizations that use AI are about as likely as they were in the early 2024 survey to say their organizations hired individuals for AI-related roles in the past 12 months. The only roles that differ this year are data-visualization and design specialists, which respondents are significantly less likely than in the previous survey to report hiring. The findings also indicate several new risk-related roles that are becoming part of organizations' AI deployment processes. Thirteen percent of respondents say their organizations have hired AI compliance specialists, and 6 percent report hiring AI ethics specialists. Respondents at larger companies are more likely than their peers at smaller organizations to report hiring a broad range of AI-related roles, with the largest gaps seen in hiring AI data scientists, machine learning engineers, and data engineers.\n\nRespondents continue to see these roles as largely challenging to fill, though a smaller share of respondents than in the past two years describe hiring for many roles as "difficult" or "very difficult" (Exhibit 5). One exception is AI data scientists, who will continue to be in high demand in the year ahead: Half of respondents whose organizations use AI say their employers will need more data scientists than they have now.... *AI*—including gen AI and analytical AI—C-level executives are more likely than middle managers to predict increasing head count.\n\nLooking at the expected effects of gen AI deployment by business function, respondents most often predict decreasing head count in service operations, such as customer care and field services, as well as in supply chain and inventory management (Exhibit 7). In IT and product development, however, respondents are more likely to expect increasing than decreasing head count.... ## AI use continues to climb\n\nReported use of AI increased in 2024.\n\n3 In the latest survey, 78 percent of respondents say their organizations use AI in at least one business function, up from 72 percent in early 2024 and 55 percent a year earlier (Exhibit 8). Respondents most often report using the technology in the IT and marketing and sales functions, followed by service operations. The business function that saw the largest increase in AI use in the past six months is IT, where the share of respondents reporting AI use jumped from 27 percent to 36 percent.\n\nOrganizations are also using AI in more business functions than in the previous State of AI survey. For the first time, most survey respondents report the use of AI in more than one business function (Exhibit 9). Responses show organizations using AI in an average of three business functions—an increase from early 2024, but still a minority of functions.\n\nThe use of gen AI has seen a similar jump since early 2024: 71 percent of respondents say their organizations regularly use gen AI in at least one business function, up from 65 percent in early 2024.\n\n4 (Individuals' use of gen AI has also grown. See sidebar, "C-level executives are using gen AI more than others.") Responses show that organizations are most often using gen AI in marketing and sales, product and service development, service operations, and software engineering—business functions where gen AI deployment would likely generate the most value, according to previous McKinsey research—as well as in IT.... ## About the research\n\nThe online survey was in the field from July 16 to July 31, 2024, and garnered responses from 1,491 participants in 101 nations representing the full range of regions, industries, company sizes, functional specialties, and tenures. Forty-two percent of respondents say they work for organizations with more than $500 million in annual revenues. To adjust for differences in response rates, the data are weighted by the contribution of each respondent's nation to global GDP.",
        "date": "2025-03-12",
        "last_updated": "2025-09-25"
      },
      {
        "title": "The Top Artificial Intelligence Trends - IBM",
        "url": "https://www.ibm.com/think/insights/artificial-intelligence-trends",
        "snippet": "Approaching the midpoint of 2025, we can look back at the prevailing artificial intelligence trends of the year so far—and look ahead to what the rest of the year might bring.\n\nGiven the breadth and depth of AI development, no roundup of AI trends can hope to be exhaustive. This piece is no exception. We've narrowed things down to a list of 10: 5 developments that have driven the first half of the year, and 5 more that we expect to play a major role in the months to come.\n\nTrends in AI are driven not only by advancements in AI models and algorithms themselves, but by the ever-expanding array of use cases to which generative AI (gen AI) capabilities are being applied. As models grow more capable, versatile and efficient, so too do the AI applications, AI tools and other AI-powered workflows they enable. A true understanding of how today's AI ecosystem is evolving therefore requires a contextual understanding of the causes and effects of machine learning breakthroughs.\n\nThis article primarily explores ongoing trends whose real-world impact might be realized on a horizon of months: in other words, trends with tangible impact mostly on or in the year 2025. There are, of course, other AI initiatives that are more evergreen and familiar. For example, though there has been recent movement on fully self-driving vehicles in isolated pockets—robotaxi pilots have been launched in a handful of U.S. cities, with additional trials abroad in Oslo, Geneva and 16 Chinese cities—they're likely still years away from ubiquity.... One study estimates the pace of algorithmic improvement at roughly 400% per year: in other words, today's results can be achieved a year later using one fourth of the compute—and that's\n\n*without *accounting for simultaneous improvements in computing (see: Moore's Law) or synthetic training data. The original GPT-4, rumored to have around 1.8 trillion parameters, 1 achieved a score of 67% on HumanEval, a popular benchmark for coding performance. IBM Granite 3.3 2B Instruct, released 2 years later and *900 times smaller, *achieved a score of 80.5%. 2\n\nThis exponential expansion of model economy, more than anything, is what empowers the emerging era of AI agents. Large language models (LLMs) are becoming more practical even faster than they're becoming more capable, which enables the deployment of complex multi-agent systems in which a cadre of models can plan, execute and coordinate on complex tasks autonomously—without skyrocketing inference costs.\n\nThe release of OpenAI's o1 introduced a new avenue for increasing model performance. Its head-turning improvement over prior state-of-the-art performance on highly technical math and coding benchmarks initiated an arms race in so-called "reasoning models." Their enhanced performance on tasks requiring logical decision-making figures to play an important role in the development of agentic AI. But as is often the case with AI technology, the initial frenzy over raw performance has more recently given way to a search for the most practical implementation.... When it comes to transformers or mamba, the future of AI is not probably an "either/or" situation: in fact, research suggests that a hybrid of the two is better than either on their own. Several mamba or hybrid mamba/transformer models have been released in the past year. Most have been academic research-only models, with notable exceptions including Mistral AI's Codestral Mamba and AI2I's hybrid Jamba series. More recently, the upcoming IBM Granite 4.0 series will be using a hybrid of transformer and Mamba-2 architectures.\n\nMost importantly, the reduced hardware requirements of Mamba and hybrid models will significantly reduce hardware costs, which in turn will help continue to democratize AI access.\n\nThe advent of multimodal AI models marked the expansion of LLMs beyond text, but the next frontier of AI development aims to bring those multimodal abilities into the physical world.\n\nThis emerging field largely falls under the heading of "Embodied AI." Venture capital firms are increasingly pouring funding into startups pursuing advanced, generative AI-driven humanoid robotics, such as Skild AI, Physical Intelligence, and 1X Technologies.\n\nAnother stream of research is focusing on "world models" that aim to model real-world interactions directly and holistically, rather than indirectly and discretely through the mediums of language, image and video data. World Labs, a startup headed by Stanford's Fei-Fei Li—famed for, among other things, the ImageNet dataset that helped pave a path for modern computer vision—raised USD 230 million at the end of last year.",
        "date": "2025-05-21",
        "last_updated": "2025-09-25"
      },
      {
        "title": "AI Pulse: Top AI Trends from 2024 - A Look Back | Trend Micro (US)",
        "url": "https://www.trendmicro.com/en_us/research/25/a/top-ai-trends-from-2024-review.html",
        "snippet": "AI Comes Into Its Own\n\n2024 may go down as the year AI stopped being a technological novelty and became—more consequentially—a Fact of Life. Big names like Microsoft, Salesforce, and Intuit built AI into mainstream enterprise solutions; specialized AI apps and services sprung up for everything from copywriting to data analysis; and governments, think tanks, and regulators poured effort into setting up meaningful guardrails for AI development and use. Meanwhile, bad actors made good on finding new ways to dupe, intimidate, and extort using AI tools.\n\nThis special issue of\n\n*AI Pulse* looks back over the AI trends in 2024 and what they mean for the year ahead.\n\nAI Trends in 2024\n\n**AI Advances by Leaps and Bounds\n\n**Our previous\n\n*AI Pulse*was dedicated mostly to agentic AI—for good reason. Autonomous, cooperative machine-based problem solving is widely seen as an essential step along the path to artificial general intelligence (AGI). All the big AI players spotlighted R&D efforts in the agentic arena over the course of 2024—and non-AI players moved in to offer AI agents as a service (AIAaaS).\n\n**Teaching computers to use computers\n\n**One of the year's big agentic releases was the public beta of Computer Use for Anthropic's Claude 3.5 Sonnet model. As the name suggests, Computer Use allows Claude 3.5 Sonnet to use a computer by 'looking' at the screen, manipulating the cursor, clicking on links, and entering text. Other developers are also working on web-savvy agents, though assessing performance at scale is a widely recognized challenge. The research company ServiceNow is aiming to change that with its AgentLab offering—an open-source Python package launched in December that's capable of running large-scale web agent experiments in parallel across a diversity of online environments.... **From RAGs to AI riches\n\n**AI systems need relevant data to solve problems effectively. Retrieval-augmented generation (RAG) provides that by giving systems access to contextually significant information instead of broad, unfocused data sets. On its own, RAG has been found to reduce AI hallucinations and outperform alternative approaches such as long-context transformers and fine-tuning. Combining RAG with fine-tuning produces even better results.\n\nAnthropic announced its own spin on RAG earlier this fall with "contextual retrieval"—said to make information retrieval more successful—and a new Model Context Protocol (MCP) for connecting AI assistants to data systems in a reliable and scalable way.\n\nTrend Micro has found RAG isn't without its risks. Exposed vector stores and LLM-hosting platforms can give way to data leaks and unauthorized access. Security issues such as data validation bugs and denial-of-service (DoS) attacks are common across RAG components. Beyond authentication, Trend recommends implementing transport layer security (TLS) encryption and zero-trust networking to prevent unauthorized access and manipulation.\n\n**'Smallifying' AI models\n\n**Hand in hand with the shift to agentic AI is the need for smaller, nimbler, faster models purpose-built for specific tasks. Again, lots of work went into this in 2024. In October, Meta released updates to its Llama AI model that are as much as four times faster and 56% smaller than their precursors, enabling sophisticated AI features on devices as small as smartphones. And Nvidia released its Nemotron-Mini-4B Instruct small language model (SLM), which gets VRAM usage down to about 2GB for far faster speeds than LLMs.... MIT also contributed to the effort to track AI risks. In August, it launched a public AI Risk Repository with more than 700 risks based on over 40 different frameworks, with citations and risk taxonomies.\n\nAI Can do Good, Too\n\nWhile it's important to be clear about the risks of AI, it's just as important to stay mindful of the benefits—and a number of efforts sought to highlight those positive capabilities in 2024.\n\n**Beating the bad guys to it\n\n**Using AI to discover vulnerabilities and exploits got a fair bit of attention throughout the year. While AI isn't always needed, in situations where complexity is high and unknowns abound, it can deliver excellent results. The Frontier Model Forum found vulnerability discovery and patching is an emerging area of AI strength, due partly to increased use of coding examples in post-training and partly because of expanding context windows. AI can also support open-source intelligence gathering and reporting through real-time monitoring and analysis, trend identification, and more.\n\nAs predicted by Trend Micro for 2025, agentic AI could expand on those capabilities with a combination of tooling, data, and planning that reduce the amount of human brain time involved. Combining agentic use of reverse-engineering tools such as Ida, Ghidra, and Binary Ninja with code similarity, architectural RAG, and algorithm identification for compiled code could be a powerful lever in the cybersecurity arms race.",
        "date": "2025-01-03",
        "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.
</Info>

## Regional 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
      maxResults: 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 YOUR_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 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 each query
  for i, query_results in enumerate(search.results):
      print(f"Results for query {i+1}:")
      for result in query_results:
          print(f"  {result.title}: {result.url}")
      print("---")
  ```

  ```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"
      ],
      maxResults: 5
  });

  // Access results for each query
  search.results.forEach((queryResults, i) => {
      console.log(`Results for query ${i+1}:`);
      queryResults.forEach(result => {
          console.log(`  ${result.title}: ${result.url}`);
      });
      console.log("---");
  });
  ```

  ```bash cURL theme={null}
  curl -X POST 'https://api.perplexity.ai/search' \
    -H 'Authorization: Bearer YOUR_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>
  You can include up to 5 queries in a single multi-query request for efficient batch processing.
</Info>

## Domain Filtering

The `search_domain_filter` parameter allows you to limit search results to specific domains/URLs for focused research:

<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",
      searchDomainFilter: [
          "science.org",
          "pnas.org",
          "cell.com"
      ],
      maxResults: 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",
          searchDomainFilter: [
              "science.org",
              "pnas.org",
              "cell.com"
          ],
          maxResults: 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 YOUR_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 or URLs to the `search_domain_filter` list.
</Warning>

## Language Filtering

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 multiLangSearch = await client.search.create({
      query: "latest AI news",
      searchLanguageFilter: ["en", "fr", "de"],
      maxResults: 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",
          searchLanguageFilter: ["en", "fr", "de"],
          maxResults: 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 YOUR_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.
</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=2048
  )

  # 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",
      maxResults: 5,
      maxTokensPerPage: 2048
  });

  // Use default extraction for faster processing
  const quickSearch = await client.search.create({
      query: "AI news headlines",
      maxResults: 3,
      maxTokensPerPage: 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 YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{
      "query": "artificial intelligence research methodology",
      "max_results": 5,
      "max_tokens_per_page": 2048
    }' | jq

  # Lighter content extraction
  curl -X POST 'https://api.perplexity.ai/search' \
    -H 'Authorization: Bearer YOUR_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 1024 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 higher `max_tokens_per_page` values (1500-2048) for research tasks requiring detailed content analysis, and lower values (256-512) for quick information retrieval or when processing large result sets.
</Tip>

## Authentication

Set up your API key as an environment variable:

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

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

Or use a `.env` file:

```bash .env theme={null}
PERPLEXITY_API_KEY=your_api_key_here
```

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

  # Automatically uses PERPLEXITY_API_KEY environment variable
  client = Perplexity()

  # Or specify explicitly
  client = Perplexity(api_key=os.getenv("PERPLEXITY_API_KEY"))
  ```

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

  // Automatically uses PERPLEXITY_API_KEY environment variable
  const client = new Perplexity();

  // Or specify explicitly
  const client = new Perplexity({
      apiKey: process.env.PERPLEXITY_API_KEY
  });
  ```
</CodeGroup>

## Next Steps

<Card title="Best Practices" icon="star" href="/guides/search-best-practices">
  Optimize your queries and implement async patterns
</Card>

## Related Resources

<CardGroup cols={2}>
  <Card title="API Reference" icon="book" href="/api-reference/search-post">
    Complete API documentation
  </Card>

  <Card title="Perplexity SDK" icon="code" href="/guides/perplexity-sdk">
    Type-safe SDK for Python and TypeScript
  </Card>
</CardGroup>


# SEC Filings Filter Guide
Source: https://docs.perplexity.ai/guides/sec-guide



<Note>
  The `search_mode: "sec"` parameter allows you to tailor your searches specifically to U.S. Securities and Exchange Commission (SEC) filings, prioritizing official financial documents, disclosures, and regulatory filings from public companies.
</Note>

## Overview

The SEC filter allows users to target their searches specifically to official SEC filings. This is especially useful for investors, analysts, journalists, and professionals who require authoritative financial documents, such as 10-Ks, 10-Qs, 8-Ks, and other regulatory filings, rather than general web content or news articles.

When you activate the SEC filter by setting `search_mode: "sec"`, Perplexity limits results to the SEC's EDGAR database and other reputable sources of regulatory filings, filtering out non-official or general web sources. This ensures that the answers you receive are grounded in official disclosures and regulatory compliance.

## Key Features and Functionality

* **Source Filtering**: Prioritizes SEC filings such as 10-K, 10-Q, 8-K, S-1, and more
* **Regulatory Focus**: Returns results based on official financial and regulatory documents
* **Enhanced Precision**: Provides more accurate and up-to-date information for financial and compliance queries

## Usage Examples

### Basic SEC Filings Search

This example shows how to perform a basic search using the SEC filter.

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.perplexity.ai/chat/completions \
    --header "accept: application/json" \
    --header "authorization: Bearer $SONAR_API_KEY" \
    --header "content-type: application/json" \
    --data '{
      "model": "sonar-pro",
      "messages": [{"role": "user", "content": "Prepare me for markets opening."}],
      "search_mode": "sec"
    }' | jq
  ```

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

  url = "https://api.perplexity.ai/chat/completions"
  headers = {
      "accept": "application/json",
      "authorization": "Bearer YOUR_API_KEY",
      "content-type": "application/json"
  }
  payload = {
      "model": "sonar-pro",
      "messages": [{"role": "user", "content": "Prepare me for markets opening."}],
      "search_mode": "sec"
  }'

  response = requests.post(url, headers=headers, json=payload)
  print(response.json())
  ```

  ```javascript Node.js theme={null}
  const axios = require('axios');

  const url = "https://api.perplexity.ai/chat/completions";
  const headers = {
    "accept": "application/json",
    "authorization": "Bearer YOUR_API_KEY",
    "content-type": "application/json"
  };
  const payload = {
    "model": "sonar-pro",
    "messages": [{"role": "user", "content": "Prepare me for markets opening."}],
    "stream": false,
    "search_mode": "sec"
  };

  axios.post(url, payload, { headers })
    .then(response => console.log(response.data))
    .catch(error => console.error(error));
  ```
</CodeGroup>

### Combining SEC Mode with Other Parameters

You can combine the SEC filter with other parameters for more refined searches:

<CodeGroup>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.perplexity.ai/chat/completions \
    --header "accept: application/json" \
    --header "authorization: Bearer $SONAR_API_KEY" \
    --header "content-type: application/json" \
    --data '{
      "model": "sonar",
      "messages": [{"role": "user", "content": "Summarize the latest 10-K filings for Apple Inc."}],
      "stream": false,
      "search_mode": "sec",
      "search_after_date_filter": "1/1/2023"
  }' | jq
  ```

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

  client = Perplexity()

  completion = client.chat.completions.create(
      model="sonar",
      messages=[{"role": "user", "content": "Summarize the latest 10-K filings for Apple Inc."}],
      search_mode="sec",
      search_after_date_filter="1/1/2023"
  )

  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": "Summarize the latest 10-K filings for Apple Inc."}],
    search_mode: "sec",
    search_after_date_filter: "1/1/2023"
  });

  console.log(completion.choices[0].message.content);
  ```
</CodeGroup>

## Recommended Use Cases

The SEC filter is particularly valuable for:

1. **Financial Analysis**: When you need to review official financial statements and disclosures
2. **Regulatory Compliance**: For questions requiring up-to-date regulatory filings and compliance information
3. **Market Research**: When tracking company events, earnings, and risk factors
4. **Due Diligence**: For investors and analysts evaluating public companies

## Best Practices

### Optimizing SEC Filings Searches

* **Be Specific**: Reference the type of filing (e.g., 10-K, 8-K) and company name for more precise results
* **Use Financial Terminology**: Include terms like "earnings," "risk factors," or "management discussion" to target relevant sections
* **Combine with Date Filters**: For the most recent filings, combine with `search_after_date_filter`
* **Adjust Context Size**: Use higher `search_context_size` values for more comprehensive responses

### Limitations

* Availability is limited to filings made public through the SEC's EDGAR system
* Some filings may be delayed or amended after initial publication
* Only covers U.S. public companies and registered entities

⸻


# Streaming Responses
Source: https://docs.perplexity.ai/guides/streaming-responses

Learn how to stream real-time responses using Perplexity's SDKs and APIs

## Overview

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** - Display responses as they're generated
* **Long responses** - Start showing content immediately for lengthy analyses
* **Interactive applications** - Provide immediate feedback to users

<Info>
  Streaming is supported across all Perplexity models including Sonar, Sonar Pro, and reasoning models.
</Info>

## Quick Start

The easiest way to get started is with the Perplexity SDKs, which handle all the streaming parsing automatically.

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

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

    # Initialize the client (uses PERPLEXITY_API_KEY environment variable)
    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
    for chunk in stream:
        if 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();

    // Create streaming completion
    const stream = await client.chat.completions.create({
      model: "sonar",
      messages: [{ role: "user", content: "What is the latest in AI research?" }],
      stream: true
    });

    // Process streaming response
    for await (const chunk of stream) {
      if (chunk.choices[0]?.delta?.content) {
        process.stdout.write(chunk.choices[0].delta.content);
      }
    }
    ```
  </Tab>

  <Tab title="cURL">
    ```bash  theme={null}
    curl -X POST "https://api.perplexity.ai/chat/completions" \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "sonar",
        "messages": [{"role": "user", "content": "What is the latest in AI research?"}],
        "stream": true
      }'
    ```
  </Tab>
</Tabs>

## Search Results and Metadata During Streaming

<Info>
  Search results and metadata are delivered in the **final chunk(s)** of a streaming response, not progressively during the stream.
</Info>

### How Metadata Works with Streaming

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

### Collecting Metadata During Streaming

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

    def stream_with_metadata():
        client = Perplexity()
        
        stream = client.chat.completions.create(
            model="sonar",
            messages=[{"role": "user", "content": "Explain quantum computing"}],
            stream=True
        )
        
        content = ""
        search_results = []
        usage_info = None
        
        for chunk in stream:
            # Process content
            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
                
            # Check if streaming is complete
            if chunk.choices[0].finish_reason:
                print(f"\n\nSearch Results: {search_results}")
                print(f"Usage: {usage_info}")
        
        return content, search_results, usage_info

    stream_with_metadata()
    ```
  </Tab>

  <Tab title="TypeScript SDK">
    ```typescript  theme={null}
    async function streamWithMetadata(query: string) {
      const client = new Perplexity();
      
      const stream = await client.chat.completions.create({
        model: "sonar",
        messages: [{ role: "user", content: query }],
        stream: true
      });

      let content = "";
      let searchResults: any[] = [];
      let usage: any = undefined;

      for await (const chunk of stream) {
        // Process content
        if (chunk.choices[0]?.delta?.content) {
          const contentPiece = chunk.choices[0].delta.content;
          content += contentPiece;
          process.stdout.write(contentPiece);
        }

        // Collect metadata from final chunks
        if (chunk.search_results) {
          searchResults = chunk.search_results;
        }

        if (chunk.usage) {
          usage = chunk.usage;
        }

        // Check if streaming is complete
        if (chunk.choices[0]?.finish_reason) {
          console.log(`\n\nSearch Results:`, searchResults);
          console.log(`Usage:`, usage);
        }
      }

      return { content, searchResults, usage };
    }

    // Usage
    const result = await streamWithMetadata("Explain quantum computing");
    ```
  </Tab>

  <Tab title="Raw HTTP">
    ```python  theme={null}
    import requests
    import json

    def stream_with_requests_metadata():
        url = "https://api.perplexity.ai/chat/completions"
        headers = {
            "Authorization": "Bearer YOUR_API_KEY",
            "Content-Type": "application/json"
        }
        payload = {
            "model": "sonar",
            "messages": [{"role": "user", "content": "Explain quantum computing"}],
            "stream": True
        }
        
        response = requests.post(url, headers=headers, json=payload, stream=True)
        
        content = ""
        metadata = {}
        
        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)
                        
                        # Process content
                        if 'choices' in chunk and chunk['choices'][0]['delta'].get('content'):
                            content_piece = chunk['choices'][0]['delta']['content']
                            content += content_piece
                            print(content_piece, end='', flush=True)
                        
                        # Collect metadata
                        for key in ['search_results', 'usage']:
                            if key in chunk:
                                metadata[key] = chunk[key]
                                
                        # Check if streaming is complete
                        if chunk['choices'][0].get('finish_reason'):
                            print(f"\n\nMetadata: {metadata}")
                            
                    except json.JSONDecodeError:
                        continue
        
        return content, metadata

    stream_with_requests_metadata()
    ```
  </Tab>
</Tabs>

## Error Handling

Proper error handling is important to ensure your application can recover from errors and provide a good user experience.

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

    client = Perplexity()

    try:
        stream = client.chat.completions.create(
            model="sonar-pro",
            messages=[
                {"role": "user", "content": "Explain machine learning concepts"}
            ],
            stream=True
        )
        
        content = ""
        for chunk in stream:
            if chunk.choices[0].delta.content:
                content_chunk = chunk.choices[0].delta.content
                content += content_chunk
                print(content_chunk, end="")
                
    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}")
    except Exception as e:
        print(f"Unexpected error: {e}")
    ```
  </Tab>

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

    const client = new Perplexity();

    try {
      const stream = await client.chat.completions.create({
        model: "sonar-pro",
        messages: [
          { role: "user", content: "Explain machine learning concepts" }
        ],
        stream: true
      });
      
      for await (const chunk of stream) {
        if (chunk.choices[0]?.delta?.content) {
          process.stdout.write(chunk.choices[0].delta.content);
        }
      }
    } catch (error) {
      if (error instanceof Perplexity.APIConnectionError) {
        console.error("Network connection failed:", error.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}`);
      } else {
        console.error("Unexpected error:", error);
      }
    }
    ```
  </Tab>

  <Tab title="Raw HTTP">
    ```python  theme={null}
    import requests
    import time
    import json

    def stream_with_retry(max_retries=3):
        url = "https://api.perplexity.ai/chat/completions"
        headers = {
            "Authorization": "Bearer YOUR_API_KEY",
            "Content-Type": "application/json",
            "Accept": "application/json"
        }

        data = {
            "model": "sonar-pro",
            "messages": [
                {"role": "system", "content": "Be precise and concise."},
                {"role": "user", "content": "Explain machine learning concepts"}
            ],
            "stream": True,
            "max_tokens": 1000,
            "temperature": 0.2
        }

        for attempt in range(max_retries):
            try:
                with requests.post(url, headers=headers, json=data, stream=True, timeout=300) as resp:
                    resp.raise_for_status()
                    for line in resp.iter_lines(decode_unicode=True):
                        if line and line.startswith("data: "):
                            chunk_data = line[len("data: "):]
                            if chunk_data == "[DONE]":
                                break
                            try:
                                chunk = json.loads(chunk_data)
                                content = chunk["choices"][0].get("delta", {}).get("content")
                                if content:
                                    print(content, end="", flush=True)
                            except json.JSONDecodeError:
                                continue
                break
            except Exception as e:
                print(f"Attempt {attempt + 1} failed: {e}")
                if attempt < max_retries - 1:
                    time.sleep(2 ** attempt)
                else:
                    raise

    stream_with_retry()
    ```
  </Tab>
</Tabs>

## Proper SSE Parsing

For production use, you should properly parse Server-Sent Events (SSE) format:

<Tabs>
  <Tab title="Python with SSE Library">
    ```python  theme={null}
    # pip install sseclient-py
    import sseclient
    import requests
    import json

    def stream_with_proper_sse():
        url = "https://api.perplexity.ai/chat/completions"
        headers = {
            "Authorization": "Bearer YOUR_API_KEY",
            "Content-Type": "application/json"
        }
        payload = {
            "model": "sonar",
            "messages": [{"role": "user", "content": "Explain quantum computing"}],
            "stream": True
        }
        
        response = requests.post(url, headers=headers, json=payload, stream=True)
        client = sseclient.SSEClient(response)
        
        for event in client.events():
            if event.data == '[DONE]':
                break
            try:
                chunk_data = json.loads(event.data)
                content = chunk_data['choices'][0]['delta'].get('content', '')
                if content:
                    print(content, end='')
            except json.JSONDecodeError:
                continue

    stream_with_proper_sse()
    ```
  </Tab>

  <Tab title="JavaScript with EventSource">
    ```javascript  theme={null}
    // For browser environments
    function streamInBrowser() {
      const eventSource = new EventSource('/api/stream'); // Your server endpoint
      
      eventSource.onmessage = function(event) {
        if (event.data === '[DONE]') {
          eventSource.close();
          return;
        }
        
        try {
          const chunk = JSON.parse(event.data);
          const content = chunk.choices[0]?.delta?.content;
          if (content) {
            document.getElementById('output').innerHTML += content;
          }
        } catch (e) {
          console.error('Error parsing chunk:', e);
        }
      };
      
      eventSource.onerror = function(event) {
        console.error('EventSource failed:', event);
        eventSource.close();
      };
    }
    ```
  </Tab>

  <Tab title="Manual SSE Parsing">
    ```python  theme={null}
    import requests
    import json

    def stream_with_manual_parsing():
        url = "https://api.perplexity.ai/chat/completions"
        headers = {
            "Authorization": "Bearer YOUR_API_KEY",
            "Content-Type": "application/json"
        }
        payload = {
            "model": "sonar",
            "messages": [{"role": "user", "content": "Explain quantum computing"}],
            "stream": True
        }
        
        response = requests.post(url, headers=headers, json=payload, stream=True)
        
        for line in response.iter_lines():
            if line:
                line = line.decode('utf-8')
                if line.startswith('data: '):
                    data_str = line[6:]  # Remove 'data: ' prefix
                    if data_str == '[DONE]':
                        break
                    try:
                        chunk_data = json.loads(data_str)
                        content = chunk_data['choices'][0]['delta'].get('content', '')
                        if content:
                            print(content, end='')
                    except json.JSONDecodeError:
                        continue

    stream_with_manual_parsing()
    ```
  </Tab>
</Tabs>

## Advanced Streaming Patterns

### Buffered Streaming

For applications that need to process chunks in batches:

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

    def buffered_streaming(buffer_size=50, flush_interval=1.0):
        client = Perplexity()
        
        stream = client.chat.completions.create(
            model="sonar",
            messages=[{"role": "user", "content": "Write a detailed explanation of machine learning"}],
            stream=True
        )
        
        buffer = ""
        last_flush = time.time()
        
        for chunk in stream:
            if chunk.choices[0].delta.content:
                buffer += chunk.choices[0].delta.content
                
                # Flush buffer if it's full or enough time has passed
                if len(buffer) >= buffer_size or (time.time() - last_flush) >= flush_interval:
                    print(buffer, end='', flush=True)
                    buffer = ""
                    last_flush = time.time()
        
        # Flush remaining buffer
        if buffer:
            print(buffer, end='', flush=True)

    buffered_streaming()
    ```
  </Tab>

  <Tab title="TypeScript SDK">
    ```typescript  theme={null}
    async function bufferedStreaming(bufferSize: number = 50, flushInterval: number = 1000) {
      const client = new Perplexity();
      
      const stream = await client.chat.completions.create({
        model: "sonar",
        messages: [{ role: "user", content: "Write a detailed explanation of machine learning" }],
        stream: true
      });
      
      let buffer = "";
      let lastFlush = Date.now();
      
      for await (const chunk of stream) {
        if (chunk.choices[0]?.delta?.content) {
          buffer += chunk.choices[0].delta.content;
          
          // Flush buffer if it's full or enough time has passed
          if (buffer.length >= bufferSize || (Date.now() - lastFlush) >= flushInterval) {
            process.stdout.write(buffer);
            buffer = "";
            lastFlush = Date.now();
          }
        }
      }
      
      // Flush remaining buffer
      if (buffer) {
        process.stdout.write(buffer);
      }
    }

    bufferedStreaming();
    ```
  </Tab>
</Tabs>

### Stream Processing with Callbacks

For applications that need to process chunks with custom logic:

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

    def stream_with_callbacks(
        query: str,
        on_content: Optional[Callable[[str], None]] = None,
        on_search_results: Optional[Callable[[list], None]] = None,
        on_complete: Optional[Callable[[str, dict], None]] = None
    ):
        client = Perplexity()
        
        stream = client.chat.completions.create(
            model="sonar",
            messages=[{"role": "user", "content": query}],
            stream=True
        )
        
        full_content = ""
        metadata = {}
        
        for chunk in stream:
            # Handle content chunks
            if chunk.choices[0].delta.content:
                content_piece = chunk.choices[0].delta.content
                full_content += content_piece
                if on_content:
                    on_content(content_piece)
            
            # Handle search results
            if hasattr(chunk, 'search_results') and chunk.search_results:
                metadata['search_results'] = chunk.search_results
                if on_search_results:
                    on_search_results(chunk.search_results)
            
            # Handle other metadata
            if hasattr(chunk, 'usage') and chunk.usage:
                metadata['usage'] = chunk.usage
            
            # Handle completion
            if chunk.choices[0].finish_reason:
                if on_complete:
                    on_complete(full_content, metadata)
        
        return full_content, metadata

    # Usage example
    def print_content(content: str):
        print(content, end='', flush=True)

    def handle_search_results(results: list):
        print(f"\n[Found {len(results)} sources]", end='')

    def handle_completion(content: str, metadata: dict):
        print(f"\n\nCompleted. Total length: {len(content)} characters")
        if 'usage' in metadata:
            print(f"Token usage: {metadata['usage']}")

    stream_with_callbacks(
        "Explain the latest developments in renewable energy",
        on_content=print_content,
        on_search_results=handle_search_results,
        on_complete=handle_completion
    )
    ```
  </Tab>

  <Tab title="TypeScript SDK">
    ```typescript  theme={null}
    interface StreamCallbacks {
      onContent?: (content: string) => void;
      onSearchResults?: (results: any[]) => void;
      onComplete?: (content: string, metadata: any) => void;
    }

    async function streamWithCallbacks(query: string, callbacks: StreamCallbacks = {}) {
      const client = new Perplexity();
      
      const stream = await client.chat.completions.create({
        model: "sonar",
        messages: [{ role: "user", content: query }],
        stream: true
      });
      
      let fullContent = "";
      const metadata: any = {};
      
      for await (const chunk of stream) {
        // Handle content chunks
        if (chunk.choices[0]?.delta?.content) {
          const contentPiece = chunk.choices[0].delta.content;
          fullContent += contentPiece;
          callbacks.onContent?.(contentPiece);
        }
        
        // Handle search results
        if (chunk.search_results) {
          metadata.search_results = chunk.search_results;
          callbacks.onSearchResults?.(chunk.search_results);
        }
        
        // Handle other metadata
        if (chunk.usage) {
          metadata.usage = chunk.usage;
        }
        
        // Handle completion
        if (chunk.choices[0]?.finish_reason) {
          callbacks.onComplete?.(fullContent, metadata);
        }
      }
      
      return { content: fullContent, metadata };
    }

    // Usage example
    const result = await streamWithCallbacks(
      "Explain the latest developments in renewable energy",
      {
        onContent: (content) => process.stdout.write(content),
        onSearchResults: (results) => process.stdout.write(`\n[Found ${results.length} sources]`),
        onComplete: (content, metadata) => {
          console.log(`\n\nCompleted. Total length: ${content.length} characters`);
          if (metadata.usage) {
            console.log(`Token usage:`, metadata.usage);
          }
        }
      }
    );
    ```
  </Tab>
</Tabs>

## Best Practices

<Steps>
  <Step title="Handle network interruptions">
    Implement reconnection logic for robust streaming applications.

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

        def robust_streaming(query: str, max_retries: int = 3):
            client = Perplexity()
            
            for attempt in range(max_retries):
                try:
                    stream = client.chat.completions.create(
                        model="sonar",
                        messages=[{"role": "user", "content": query}],
                        stream=True
                    )
                    
                    for chunk in stream:
                        if chunk.choices[0].delta.content:
                            print(chunk.choices[0].delta.content, end='', flush=True)
                    
                    return  # Success, exit retry loop
                    
                except (perplexity.APIConnectionError, perplexity.APITimeoutError) as e:
                    if attempt < max_retries - 1:
                        delay = (2 ** attempt) + random.uniform(0, 1)
                        print(f"\nConnection error, retrying in {delay:.1f}s...")
                        time.sleep(delay)
                    else:
                        print(f"\nFailed after {max_retries} attempts: {e}")
                        raise

        robust_streaming("Explain quantum computing")
        ```
      </Tab>

      <Tab title="TypeScript SDK">
        ```typescript  theme={null}
        async function robustStreaming(query: string, maxRetries: number = 3) {
          const client = new Perplexity();
          
          for (let attempt = 0; attempt < maxRetries; attempt++) {
            try {
              const stream = await client.chat.completions.create({
                model: "sonar",
                messages: [{ role: "user", content: query }],
                stream: true
              });
              
              for await (const chunk of stream) {
                if (chunk.choices[0]?.delta?.content) {
                  process.stdout.write(chunk.choices[0].delta.content);
                }
              }
              
              return; // Success, exit retry loop
              
            } catch (error) {
              if (error instanceof Perplexity.APIConnectionError && attempt < maxRetries - 1) {
                const delay = Math.pow(2, attempt) * 1000 + Math.random() * 1000;
                console.log(`\nConnection error, retrying in ${delay / 1000:.1f}s...`);
                await new Promise(resolve => setTimeout(resolve, delay));
              } else {
                console.error(`\nFailed after ${maxRetries} attempts:`, error);
                throw error;
              }
            }
          }
        }

        robustStreaming("Explain quantum computing");
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Implement proper buffering">
    Use appropriate buffering strategies for your application's needs.

    ```python  theme={null}
    # For real-time chat applications
    buffer_size = 1  # Character-by-character for immediate display

    # For document processing
    buffer_size = 100  # Larger chunks for efficiency

    # For API responses
    buffer_size = 500  # Balance between responsiveness and efficiency
    ```
  </Step>

  <Step title="Handle metadata appropriately">
    Remember that search results and metadata arrive at the end of the stream.

    ```python  theme={null}
    # Don't expect search results until the stream is complete
    if chunk.choices[0].finish_reason == "stop":
        # Now search results and usage info are available
        process_search_results(chunk.search_results)
        log_usage_stats(chunk.usage)
    ```
  </Step>

  <Step title="Optimize for your use case">
    Choose streaming parameters based on your application requirements.

    <Tabs>
      <Tab title="Real-time Chat">
        ```python  theme={null}
        # Optimize for immediate response
        stream = client.chat.completions.create(
            model="sonar",
            messages=messages,
            stream=True,
            max_tokens=1000,  # Reasonable limit
            temperature=0.7   # Balanced creativity
        )
        ```
      </Tab>

      <Tab title="Document Generation">
        ```python  theme={null}
        # Optimize for quality and completeness
        stream = client.chat.completions.create(
            model="sonar-pro",
            messages=messages,
            stream=True,
            max_tokens=4000,  # Longer responses
            temperature=0.3   # More focused
        )
        ```
      </Tab>
    </Tabs>
  </Step>
</Steps>

<Warning>
  **Important**: 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>

## Resources

* [The Perplexity SDK Guide](/guides/perplexity-sdk) - The Perplexity SDK guide
* [Chat Completions SDK](/guides/chat-completions-sdk) - Complete chat completions guide
* [API Reference - Chat Completions](/api-reference/chat-completions-post) - Complete API documentation


# Structured Outputs Guide
Source: https://docs.perplexity.ai/guides/structured-outputs



## Overview

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 two types of structured outputs: **JSON Schema** and **Regex**. LLM responses will work to match the specified format, except for the following cases:

* The output exceeds `max_tokens`

Enabling the structured outputs can be done by adding a `response_format` field in the request:

**JSON Schema**

* `response_format: { type: "json_schema", json_schema: {"schema": object} }` .

* The schema should be a valid JSON schema object.

**Regex** (only available for `sonar` right now)

* `response_format: { type: "regex", regex: {"regex": str} }` .

* The regex is a regular expression string.

<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 or Regex 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>

## Examples

### 1. Financial Analysis with JSON Schema

<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()

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

  ```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 completion = await 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: {
          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']
        }
      }
    }
  });

  const metrics: FinancialMetrics = JSON.parse(completion.choices[0].message.content);
  ```

  ```bash cURL theme={null}
  curl -X POST "https://api.perplexity.ai/chat/completions" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "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": {
            "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>

### 2. Extract Contact Information with Regex

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

  client = Perplexity()

  completion = client.chat.completions.create(
      model="sonar",
      messages=[
          {
              "role": "user",
              "content": "Find the direct email address for the investor relations contact at Tesla Inc."
          }
      ],
      response_format={
          "type": "regex",
          "regex": {
              "regex": r"[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}"
          }
      }
  )

  email = completion.choices[0].message.content
  print(f"Investor Relations Email: {email}")
  ```

  ```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: 'Find the direct email address for the investor relations contact at Tesla Inc.'
      }
    ],
    response_format: {
      type: 'regex',
      regex: {
        regex: '[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}'
      }
    }
  });

  const email = completion.choices[0].message.content;
  ```

  ```bash cURL theme={null}
  curl -X POST "https://api.perplexity.ai/chat/completions" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "sonar",
      "messages": [
        {
          "role": "user",
          "content": "Find the direct email address for the investor relations contact at Tesla Inc."
        }
      ],
      "response_format": {
        "type": "regex",
        "regex": {
          "regex": "[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}"
        }
      }
    }' | jq
  ```
</CodeGroup>

## Best Practices

### Generating responses in a JSON Format

For Python users, we recommend using the Pydantic library to [generate JSON schema](https://docs.pydantic.dev/latest/api/base_model/#pydantic.BaseModel.model_json_schema).

**Unsupported JSON Schemas**

Recursive JSON schema is not supported. As a result of that, unconstrained objects are not supported either. Here's a few example of unsupported schemas:

```
# UNSUPPORTED!

from typing import Any

class UnconstrainedDict(BaseModel):
   unconstrained: dict[str, Any]

class RecursiveJson(BaseModel):
   value: str
   child: list["RecursiveJson"]
```

<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>

### Generating responses using a regex

**Supported Regex**

* Characters: `\d`, `\w`, `\s` , `.`
* Character classes: `[0-9A-Fa-f]` , `[^x]`
* Quantifiers: `*`, `?` , `+`, `{3}`, `{2,4}` , `{3,}`
* Alternation: `|`
* Group: `( ... )`
* Non-capturing group: `(?: ... )`

**Unsupported Regex**

* Contents of group: `\1`
* Anchors: `^`, `$`, `\b`
* Positive lookahead: `(?= ... )`
* Negative lookahead: `(?! ... )`
* Positive look-behind: `(?<= ... )`
* Negative look-behind: `(?<! ... )`
* Recursion: `(?R)`

## Perplexity's JSON Schema Implementation

Perplexity's structured outputs implementation has several key differences compared to other providers:

### Simplified Schema Definition

* **Optional naming**: Unlike other providers that require explicit schema names, Perplexity automatically handles schema naming with sensible defaults
* **Flexible strictness**: Schema validation is handled automatically without requiring manual strictness configuration
* **Streamlined syntax**: You only need to provide the core schema object without additional wrapper fields

**Other Providers:**

```json  theme={null}
{
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "financial_data",
      "strict": true,
      "schema": { /* your schema */ }
    }
  }
}
```

**Perplexity:**

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

### Enhanced Error Handling

* **Clear error messages**: When schemas fail validation, you'll receive specific, actionable error messages
* **Recursion protection**: Built-in safeguards prevent infinite recursion in complex nested schemas
* **Constraint validation**: Automatic detection and clear messaging for unsupported features like unconstrained objects

### Schema Compatibility

While Perplexity supports standard JSON Schema syntax, some advanced features may not be available:

* Recursive schemas are not supported for performance and reliability reasons
* Unconstrained objects (like `dict[str, Any]`) are automatically detected and rejected
* Complex reference patterns may require simplification

This approach prioritizes reliability and performance while maintaining compatibility with most common JSON Schema use cases.

## Structured Outputs for Reasoning Models

When using structured outputs with reasoning models like `sonar-reasoning-pro`, the response will include a `<think>` section containing reasoning tokens, immediately followed by the structured output. The `response_format` parameter does not remove these reasoning tokens from the output, so the final response will need to be parsed manually.

**Sample Response:**

```
<think>
I need to provide information about France in a structured JSON format with specific fields: country, capital, population, official_language.

For France:
- Country: France
- Capital: Paris
- Population: About 67 million (as of 2023)
- Official Language: French

Let me format this information as required.
</think>
{"country":"France","capital":"Paris","population":67750000,"official_language":"French"}
```

For a reusable implementation to extract JSON from reasoning model outputs, see our [example utility on GitHub](https://github.com/ppl-ai/api-discussion/blob/main/utils/extract_json_reasoning_models.py).


# User Location Filter Guide
Source: https://docs.perplexity.ai/guides/user-location-filter-guide



<Note>
  The `user_location` parameter within `web_search_options` allows you to refine search results based on the user's approximate geographic location. This helps provide more contextually relevant information.
</Note>

<Info>
  You can specify the location using latitude/longitude coordinates, country code, city, and region. For the most accurate results, we recommend providing as much location information as possible, including `city` and `region` fields. For supported country codes, please refer to the list [here](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes).
</Info>

<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>

## Overview

The `user_location` filter helps tailor search results by incorporating geographic context. This is particularly useful for queries where location significantly impacts relevance, such as:

* Finding local businesses or services.
* Getting information about regional events or news.
* Understanding location-specific regulations or customs.

To refine search results by location, include the `user_location` object within the `web_search_options` in your request payload. You can provide coordinates, country code, city, region, or combine them for maximum accuracy:

**Using All Available Fields (Recommended for Best Accuracy):**

```json  theme={null}
"web_search_options": {
  "user_location": {
    "country": "US",
    "region": "California",
    "city": "San Francisco",
    "latitude": 37.7749,
    "longitude": -122.4194
  }
}
```

**Using City and Region with Country:**

```json  theme={null}
"web_search_options": {
  "user_location": {
    "country": "US",
    "region": "New York",
    "city": "New York City"
  }
}
```

**Using Latitude/Longitude:**

```json  theme={null}
"web_search_options": {
  "user_location": {
    "country":"US",
    "latitude": 37.7749,
    "longitude": -122.4194
  }
}
```

**Using Country Code Only:**

```json  theme={null}
"web_search_options": {
  "user_location": {
    "country": "US"
  }
}
```

These filters work alongside other search parameters like date range or domain filters.

## Examples

**1. Refining Results with All Location Fields (Recommended)**

This example provides all available location fields for San Francisco to get the most accurate geographically relevant search results.

**Request Example**

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

  client = Perplexity()

  completion = client.chat.completions.create(
      messages=[
          {"role": "system", "content": "You are a helpful local guide."},
          {"role": "user", "content": "What are some good coffee shops nearby?"}
      ],
      model="sonar-pro",
      web_search_options={
          "user_location": {
              "country": "US",
              "region": "California",
              "city": "San Francisco",
              "latitude": 37.7749,
              "longitude": -122.4194
          }
      }
  )

  print(f"Response: {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({
    messages: [
      {"role": "system", "content": "You are a helpful local guide."},
      {"role": "user", "content": "What are some good coffee shops nearby?"}
    ],
    model: "sonar-pro",
    web_search_options: {
      user_location: {
        country: "US",
        region: "California",
        city: "San Francisco",
        latitude: 37.7749,
        longitude: -122.4194
      }
    }
  });

  console.log(`Response: ${completion.choices[0].message.content}`);
  ```

  ```bash cURL theme={null}
  curl --location 'https://api.perplexity.ai/chat/completions' \
    --header "Authorization: Bearer $SONAR_API_KEY" \
    --header "Content-Type: application/json" \
    --data '{
      "model": "sonar-pro",
      "messages": [
        {"role": "system", "content": "You are a helpful local guide."},
        {"role": "user", "content": "What are some good coffee shops nearby?"}
      ],
      "web_search_options": {
        "user_location": {
          "country": "US",
          "region": "California",
          "city": "San Francisco",
          "latitude": 37.7749,
          "longitude": -122.4194
        }
      }
  }' | jq
  ```
</CodeGroup>

**2. Refining Results with Country Code**

This example uses a two-letter ISO country code (United States) to provide broader geographic context.

**Request Example**

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

  client = Perplexity()

  completion = client.chat.completions.create(
      messages=[
          {"role": "system", "content": "You are an expert on international news."},
          {"role": "user", "content": "Summarize political news from today."}
      ],
      model="sonar-pro",
      web_search_options={
          "user_location": {
              "country": "US"
          }
      }
  )

  print(f"Response: {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({
    messages: [
      {"role": "system", "content": "You are an expert on international news."},
      {"role": "user", "content": "Summarize political news from today."}
    ],
    model: "sonar-pro",
    web_search_options: {
      user_location: {
        country: "US"
      }
    }
  });

  console.log(`Response: ${completion.choices[0].message.content}`);
  ```

  ```bash cURL theme={null}
  curl --location 'https://api.perplexity.ai/chat/completions' \
    --header "Authorization: Bearer $SONAR_API_KEY" \
    --header "Content-Type: application/json" \
    --data '{
      "model": "sonar-pro",
      "messages": [
        {"role": "system", "content": "You are an expert on international news."},
        {"role": "user", "content": "Summarize political news from today."}
      ],
      "web_search_options": {
        "user_location": {
          "country": "US"
        }
      }
  }' | jq
  ```
</CodeGroup>

**3. Using City and Region for Better Accuracy**

This example shows how to use `city` and `region` fields along with coordinates for Paris, France to achieve maximum location accuracy.

**Request Example**

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

  client = Perplexity()

  completion = client.chat.completions.create(
      messages=[
          {"role": "system", "content": "You are an expert on French news and events."},
          {"role": "user", "content": "What major events are happening in the capital this week?"}
      ],
      model="sonar-pro",
      web_search_options={
          "user_location": {
              "country": "FR",
              "region": "Île-de-France",
              "city": "Paris",
              "latitude": 48.8566,
              "longitude": 2.3522
          }
      }
  )

  print(f"Response: {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({
    messages: [
      {"role": "system", "content": "You are an expert on French news and events."},
      {"role": "user", "content": "What major events are happening in the capital this week?"}
    ],
    model: "sonar-pro",
    web_search_options: {
      user_location: {
        country: "FR",
        region: "Île-de-France",
        city: "Paris",
        latitude: 48.8566,
        longitude: 2.3522
      }
    }
  });

  console.log(`Response: ${completion.choices[0].message.content}`);
  ```

  ```bash cURL theme={null}
  curl --location 'https://api.perplexity.ai/chat/completions' \
    --header "Authorization: Bearer $SONAR_API_KEY" \
    --header "Content-Type: application/json" \
    --data '{
      "model": "sonar-pro",
      "messages": [
        {"role": "system", "content": "You are an expert on French news and events."},
        {"role": "user", "content": "What major events are happening in the capital this week?"}
      ],
      "web_search_options": {
        "user_location": {
          "country": "FR",
          "region": "Île-de-France",
          "city": "Paris",
          "latitude": 48.8566, 
          "longitude": 2.3522
        }
      }
  }' | jq
  ```
</CodeGroup>

## Best Practices

**Choosing the Right Specificity**

* **All Fields (Recommended):** For maximum accuracy, provide country, region, city, latitude, and longitude. This combination gives the best results for location-specific queries.
* **City and Region:** Use these fields to significantly improve location accuracy without needing exact coordinates. Particularly useful for metropolitan areas and regional searches.
* **Latitude/Longitude:** Use for high precision when the exact location is known and relevant (e.g., finding nearby points of interest).
* **Country Code:** Use for broader context when country-level relevance is sufficient (e.g., national news, country-specific regulations).
* **Combining Fields:** We strongly recommend providing as many location fields as possible. Each additional field improves search accuracy and relevance.

**Data Accuracy**

* Ensure the provided location data is as accurate as possible. Incorrect data may lead to irrelevant results.
* Latitude values must be between -90 and 90. Longitude values must be between -180 and 180.
* Country codes should be valid two-letter ISO 3166-1 alpha-2 codes (e.g., "US", "GB", "DE").
* City names should match commonly used names (e.g., "New York City" or "NYC" for New York).
* Region names should match standard administrative divisions (states, provinces, etc.).

**Privacy Considerations**

* Be mindful of user privacy when collecting and transmitting location data. Only use location when necessary and with user consent where applicable.

**Client-Side Validation**

* Consider validating location inputs before sending the request:
  * Check latitude/longitude ranges.
  * Validate country code format (two uppercase letters).
  * Sanitize city and region inputs for special characters.


# System Status
Source: https://docs.perplexity.ai/status/status



You can check the real-time status of our services at [status.perplexity.ai](https://status.perplexity.ai).