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

I