Perplexity

The Perplexity API provides chat completion models with built-in search capabilities, citations, and structured output support. Perplexity models retrieve information from the web in real-time, enabling up-to-date responses with source citations.

Perplexity follows OpenAI's chat completion API format - see our OpenAI documentation for the base API details.

Setup

1. Get an API key from your Perplexity Settings
2. Set the PERPLEXITY_API_KEY environment variable or specify apiKey in your config

Supported Models

Perplexity offers several specialized models optimized for different tasks:

Basic Configuration

providers:
  - id: perplexity:sonar-pro
    config:
      temperature: 0.7
      max_tokens: 4000

  - id: perplexity:sonar
    config:
      temperature: 0.2
      max_tokens: 1000
      search_domain_filter: ['wikipedia.org', 'nature.com', '-reddit.com'] # Include wikipedia/nature, exclude reddit
      search_recency_filter: 'week' # Only use recent sources

Features

Search and Citations

Perplexity models automatically search the internet and cite sources. You can control this with:

• search_domain_filter: List of domains to include/exclude (prefix with - to exclude)
• search_recency_filter: Time filter for sources ('month', 'week', 'day', 'hour')
• return_related_questions: Get follow-up question suggestions
• web_search_options.search_context_size: Control search context amount ('low', 'medium', 'high')

providers:
  - id: perplexity:sonar-pro
    config:
      search_domain_filter: ['stackoverflow.com', 'github.com', '-quora.com']
      search_recency_filter: 'month'
      return_related_questions: true
      web_search_options:
        search_context_size: 'high'

Date Range Filters

Control search results based on publication date:

providers:
  - id: perplexity:sonar-pro
    config:
      # Date filters - format: "MM/DD/YYYY"
      search_after_date_filter: '3/1/2025'
      search_before_date_filter: '3/15/2025'

Location-Based Filtering

Localize search results by specifying user location:

providers:
  - id: perplexity:sonar
    config:
      web_search_options:
        user_location:
          latitude: 37.7749
          longitude: -122.4194
          country: 'US' # Optional: ISO country code

Structured Output

Get responses in specific formats using JSON Schema:

providers:
  - id: perplexity:sonar
    config:
      response_format:
        type: 'json_schema'
        json_schema:
          schema:
            type: 'object'
            properties:
              title: { type: 'string' }
              year: { type: 'integer' }
              summary: { type: 'string' }
            required: ['title', 'year', 'summary']

Or with regex patterns (sonar model only):

providers:
  - id: perplexity:sonar
    config:
      response_format:
        type: 'regex'
        regex:
          regex: "(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)"

Note: First request with a new schema may take 10-30 seconds to prepare. For reasoning models, the response will include a <think> section followed by the structured output.

Image Support

Enable image retrieval in responses:

providers:
  - id: perplexity:sonar-pro
    config:
      return_images: true

Cost Tracking

promptfoo includes built-in cost calculation for Perplexity models based on their official pricing. You can specify the usage tier with the usage_tier parameter:

providers:
  - id: perplexity:sonar-pro
    config:
      usage_tier: 'medium' # Options: 'high', 'medium', 'low'

The cost calculation includes:

• Different rates for input and output tokens
• Model-specific pricing (sonar, sonar-pro, sonar-reasoning, etc.)
• Usage tier considerations (high, medium, low)

Advanced Use Cases

Comprehensive Research

For in-depth research reports:

providers:
  - id: perplexity:sonar-deep-research
    config:
      temperature: 0.1
      max_tokens: 4000
      search_domain_filter: ['arxiv.org', 'researchgate.net', 'scholar.google.com']
      web_search_options:
        search_context_size: 'high'

Step-by-Step Reasoning

For problems requiring explicit reasoning steps:

providers:
  - id: perplexity:sonar-reasoning-pro
    config:
      temperature: 0.2
      max_tokens: 3000

Offline Creative Tasks

For creative content that doesn't require web search:

providers:
  - id: perplexity:r1-1776
    config:
      temperature: 0.7
      max_tokens: 2000

Best Practices

Model Selection

• sonar-pro: Use for complex queries requiring detailed responses with citations
• sonar: Use for factual queries and cost efficiency
• sonar-reasoning-pro/sonar-reasoning: Use for step-by-step problem solving
• sonar-deep-research: Use for comprehensive reports (may take 30+ minutes)
• r1-1776: Use for creative content not requiring search

Search Optimization

• Set search_domain_filter to trusted domains for higher quality citations
• Use search_recency_filter for time-sensitive topics
• For cost optimization, set web_search_options.search_context_size to "low"
• For comprehensive research, set web_search_options.search_context_size to "high"

Structured Output Tips

• When using structured outputs with reasoning models, responses will include a <think> section followed by the structured output
• For regex patterns, ensure they follow the supported syntax
• JSON schemas cannot include recursive structures or unconstrained objects

Example Configurations

Check our perplexity.ai-example with multiple configurations showcasing Perplexity's capabilities:

• promptfooconfig.yaml: Basic model comparison
• promptfooconfig.structured-output.yaml: JSON schema and regex patterns
• promptfooconfig.search-filters.yaml: Date and location-based filters
• promptfooconfig.research-reasoning.yaml: Specialized research and reasoning models

You can initialize these examples with:

npx promptfoo@latest init --example provider-perplexity

Pricing and Rate Limits

Pricing varies by model and usage tier:

Rate limits also vary by usage tier (high, medium, low). Specify your tier with the usage_tier parameter to get accurate cost calculations.

Check Perplexity's pricing page for the latest rates.

Troubleshooting

• Long Initial Requests: First request with a new schema may take 10-30 seconds
• Citation Issues: Use search_domain_filter with trusted domains for better citations
• Timeout Errors: For research models, consider increasing your request timeout settings
• Reasoning Format: For reasoning models, outputs include <think> sections, which may need parsing for structured outputs