Skip to main content
This page focuses on the Search API. For shared setup (installation, authentication, configuration, error handling, performance, and type safety), see the SDK overview.

​
Quick Start

Get ranked web search results: 
from perplexity import Perplexity

client = Perplexity()

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

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

The Top Artificial Intelligence Trends - IBM: https://www.ibm.com/think/insights/artificial-intelligence-trends
Year in review: Google's biggest AI advancements of 2024: https://blog.google/technology/ai/2024-ai-extraordinary-progress-advancement/
AI Pulse: Top AI Trends from 2024 - A Look Back | Trend Micro (US): https://www.trendmicro.com/en_us/research/25/a/top-ai-trends-from-2024-review.html
The State of AI: Global survey - McKinsey: https://www.mckinsey.com/capabilities/quantumblack/our-insights/the-state-of-ai
Generative AI Developments & Trends in 2024: A Timeline: https://www.channelinsider.com/managed-services/generative-ai-developments-trends-year-in-review/

​
Features

Run multiple related searches in a single request: 
search = client.search.create(
    query=[
        "latest AI developments 2024",
        "solar power innovations",
        "wind energy developments"
    ]
)

# Results are combined and ranked
for i, result in enumerate(search.results):
    print(f"{i + 1}. {result.title}")
    print(f"   URL: {result.url}")
    print(f"   Date: {result.date}\n")

​
Limiting Search Results

Control the number of search results returned: 
search = client.search.create(
    query="latest AI developments 2024",
    max_results=5  # Get only top 5 results
)

print(f"Found {len(search.results)} results")
Get geographically relevant results by country:
The country parameter only supports ISO 3166-1 alpha-2 country codes (e.g., “US”, “GB”, “DE”).
search = client.search.create(
    query="local restaurants",
    country="US"  # ISO country code
)

# Search in different countries
uk_search = client.search.create(
    query="tech events",
    country="GB"  # United Kingdom
)

canada_search = client.search.create(
    query="hockey news",
    country="CA"  # Canada
)
Common ISO country codes: US (United States), GB (United Kingdom), CA (Canada), DE (Germany), FR (France), JP (Japan), AU (Australia). See the full list at ISO 3166-1 alpha-2.

​
Advanced Usage

​
Complex Search Configuration

Combine available options for enhanced results: 
from perplexity.types import SearchCreateParams

advanced_search_params = SearchCreateParams(
    query="renewable energy research",
    max_results=15,
    return_images=True,
    return_snippets=True,
    country="US"  # ISO country code
)

search = client.search.create(**advanced_search_params.dict())

# Process results with metadata
for result in search.results:
    print(f"Title: {result.title}")
    print(f"URL: {result.url}")
    print(f"Date: {result.date}")
    print(f"Snippet: {result.snippet}")
    
    if result.images and len(result.images) > 0:
        print(f"Images: {len(result.images)} found")
    print("---")

​
Error Handling

Handle search-specific errors: 
import perplexity
from perplexity import Perplexity

client = Perplexity()

try:
    search = client.search.create(
        query="",  # Empty query will cause error
        max_results=5
    )
except perplexity.BadRequestError as e:
    print(f"Invalid search parameters: {e}")
except perplexity.RateLimitError as e:
    print("Search rate limit exceeded")
except perplexity.APIStatusError as e:
    print(f"Search API error {e.status_code}: {e}")
except Exception as e:
    print(f"Unexpected error: {e}")

​
Async Usage

import asyncio
from perplexity import AsyncPerplexity

async def main():
    client = AsyncPerplexity()
    
    # Single search
    search = await client.search.create(
        query="What is Perplexity AI?",
        max_results=5
    )
    print(search)
    
    # Concurrent searches
    tasks = [
        client.search.create(query=f"query {i}")
        for i in range(3)
    ]
    results = await asyncio.gather(*tasks)
    print(f"Completed {len(results)} searches")

asyncio.run(main())

​
Best Practices

1

Handle rate limits efficiently

Implement exponential backoff for rate limit errors.
import time
import random
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:
                # Exponential backoff with jitter
                delay = (2 ** attempt) + random.uniform(0, 1)
                time.sleep(delay)
            else:
                raise
2

Process concurrent searches efficiently

Use async for concurrent requests while respecting rate limits.
import asyncio
from perplexity import AsyncPerplexity

async def batch_search(queries, batch_size=3, delay_ms=1000):
    client = AsyncPerplexity()
    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")

​
Resources