Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.perplexity.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The Pro Search Classifier is an intelligent system that automatically determines whether a query requires the advanced multi-step tool usage of Pro Search or can be effectively answered with standard Fast Search. This optimization helps you balance performance needs with cost efficiency.
Instead of manually choosing between "pro" and "fast" search types, you can use "auto" to let the classifier make the optimal decision for each query.

​
How It Works

When you set search_type: "auto", the classifier analyzes your query across multiple dimensions:
1

Query Complexity Analysis

The classifier evaluates:
  • Number of sub-questions or aspects
  • Requirement for comparative analysis
  • Need for multi-step reasoning
  • Complexity of information synthesis required
{
  "web_search_options": {
    "search_type": "auto"  // Let the classifier decide
  }
}
2

Classification Decision

Based on the analysis, the classifier routes the query to either:
  • Pro Search for complex, multi-faceted queries requiring multi-step tool usage
  • Fast Search for straightforward information retrieval
The decision is transparent in the response metadata.
3

Execution

The selected search mode processes your query:
  • Pro Search: Uses built-in tools (web_search, fetch_url_content) automatically
  • Fast Search: Performs optimized single-pass search and synthesis
You receive the same high-quality response format regardless of which mode is used.

​
Classification Patterns

Complex queries that benefit from multi-step tool usage are automatically routed to Pro Search:
Example Query: “What are the differences between React, Vue, and Angular in terms of performance, learning curve, and ecosystem? Which one should I choose for a large enterprise application?”Why Pro Search:
  • Requires information about three different frameworks
  • Needs comparative analysis across multiple dimensions
  • Involves gathering expert opinions and recommendations
  • Benefits from synthesis of diverse sources
Tool Usage:
  • Multiple web searches for each framework
  • URL fetching for benchmark data and official documentation
Example Query: “Summarize the latest peer-reviewed research on the effectiveness of intermittent fasting for weight loss and metabolic health. Include sample sizes and study limitations.”Why Pro Search:
  • Requires finding multiple research papers
  • Needs access to full paper content, not just abstracts
  • Involves extracting specific data (sample sizes, limitations)
  • Requires synthesis across multiple studies
Tool Usage:
  • Web search for recent peer-reviewed papers
  • fetch_url_content to read full papers
  • Information extraction and synthesis
Example Query: “Analyze the stock market impact of the Federal Reserve’s most recent interest rate decision, including effects on different sectors and expert predictions for the next quarter.”Why Pro Search:
  • Requires very recent information
  • Needs multi-source verification
  • Involves sector-by-sector analysis
  • Benefits from expert opinion gathering
Tool Usage:
  • Multiple targeted web searches
  • URL fetching for financial analysis reports
  • Synthesis of diverse expert opinions
Straightforward queries that don’t require multi-step reasoning are efficiently handled by Fast Search:
Example Query: “What is the capital of France?”Why Fast Search:
  • Single, well-established fact
  • No calculation or analysis needed
  • Information readily available in search snippets
Processing:
  • Single web search
  • Direct answer from search results
  • No need for multi-step reasoning
Example Query: “What are the main features of the iPhone 15 Pro?”Why Fast Search:
  • Single product inquiry
  • Information available in product descriptions
  • No comparative analysis required
  • No calculations needed
Processing:
  • Search for product specifications
  • Extract and list features
  • Synthesize from search results
Example Query: “Explain what machine learning is.”Why Fast Search:
  • Single concept definition
  • No multi-part analysis required
  • Standard information readily available
Processing:
  • Search for machine learning explanations
  • Synthesize clear definition
  • Provide context from reliable sources
Example Query: “What does API stand for and what is it used for?”Why Fast Search:
  • Simple definition request
  • No complex analysis needed
  • Information readily available
Processing:
  • Quick search for API definition
  • Explain acronym and basic usage
  • Provide clear, concise answer

​
Cost Implications

Understanding the cost difference helps you optimize your API usage:

​
Classified as Pro Search

  • Complex multi-part questions
  • Requests requiring calculation or analysis
  • Comparative research across sources
  • Time-sensitive information needs
Uses Pro Search billing rates

​
Classified as Fast Search

  • Simple factual questions
  • Straightforward information retrieval
  • Single-topic queries
  • Basic definitional requests
Uses standard Sonar Pro billing rates

​
Pricing Comparison

Pro Search Rates:
  • Input: $3 per 1M tokens
  • Output: $15 per 1M tokens
  • Request fees: $14-$22 per 1,000 requests (based on context size)
Fast Search Rates:
  • Input: $3 per 1M tokens
  • Output: $15 per 1M tokens
  • Request fees: $6-$14 per 1,000 requests (based on context size - same as standard Sonar Pro)
The automatic classifier helps you save money by using Pro Search only when its advanced capabilities are truly needed, while still ensuring complex queries get full multi-step tool usage.

​
Usage Examples

​
Using Automatic Classification

from perplexity import Perplexity

client = Perplexity()
# Let the classifier decide
response = client.chat.completions.create(
    model="sonar-pro",
    messages=[
        {
            "role": "user",
            "content": "Compare the energy efficiency of Tesla Model 3, Chevrolet Bolt, and Nissan Leaf"
        }
    ],
    stream=True,
    web_search_options={
        "search_type": "auto"  # Automatic classification
    }
)

for chunk in response:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

​
Manual Override

You can still manually specify the search type when you know what you need:

​
Best Practices

1

Default to automatic classification

For most applications, use search_type: "auto" and let the classifier optimize:
web_search_options={"search_type": "auto"}
This ensures the right tool for each query while optimizing costs.
2

Monitor classification patterns

Track which queries get classified as Pro vs Fast to understand your usage patterns:
  • Review queries that consistently use Pro Search
  • Identify opportunities to rephrase queries for Fast Search when appropriate
  • Understand which user questions require advanced capabilities
This helps optimize your application’s query design.
3

Use manual override strategically

Override the classifier only when:
  • You have specific performance requirements
  • Testing and comparing Pro vs Fast results
  • Building features with known complexity levels
Example:
# Known complex analysis - force Pro
if query_requires_calculations(user_query):
    search_type = "pro"
else:
    search_type = "auto"
4

Design queries effectively

Structure queries to help the classifier make optimal decisions:Less optimal: “Tell me about electric cars”Better: “What is the average range of electric vehicles?” (Fast Search appropriate)Or: “Compare the total cost of ownership over 5 years for Tesla Model 3, Chevrolet Bolt, and Nissan Leaf, including depreciation, electricity costs, and maintenance” (Pro Search appropriate)Clear, specific queries enable better classification.

​
Classification Transparency

You can verify the classification decision in the response metadata: 
{
  "id": "12345",
  "model": "sonar-pro",
  "search_metadata": {
    "search_type_used": "pro",  // or "fast"
    "classification_reason": "Multi-part comparative analysis with calculations"
  },
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 150,
    "total_tokens": 175
  }
}
This transparency helps you understand why queries were classified a certain way and optimize future queries.

​
When to Use Each Mode

Auto (Recommended)

Best for: Most applicationsLet the classifier optimize for you. Balances cost and capability automatically based on query complexity.

Manual Pro

Best for: Known complex tasksUse when you’re certain multi-step tool usage is needed: calculations, multi-source synthesis, deep analysis.

Manual Fast

Best for: Simple retrievalUse for straightforward facts, definitions, or when optimizing for speed and cost with simple queries.

​
Common Questions

The classifier is highly accurate, trained on thousands of query patterns. It errs on the side of using Pro Search when there’s any ambiguity, ensuring you don’t lose capability.However, if you notice consistent mis-classifications:
  • Rephrase queries to be more specific
  • Use manual override for those query types
  • Consider your use case’s specific needs
Yes, the response includes metadata showing:
  • Which search type was used
  • Why the classification was made (when using auto)
  • Cost breakdown by search type
This helps you understand and optimize your usage patterns.
No. Classification happens in milliseconds before query processing begins and does not meaningfully impact response time. The classifier is optimized for real-time decision making.
You can always use manual override:
web_search_options={"search_type": "pro"}  # Force your preference
If you consistently disagree with classifications, consider:
  • Making queries more specific
  • Using manual override for those query types
  • Reviewing whether your use case needs consistent Pro or Fast mode

Quickstart

Get started with Pro Search basics

Built-in Tool Capabilities

Learn about Pro Search’s built-in tools and capabilities

Pricing Guide

Understand pricing for Pro and Fast Search

API Reference

Complete API documentation