Skip to main content

Overview

Try Our New Interactive Playground

Test search queries and parameters in real time, no API key required.
Perplexity’s Search API provides developers with real-time access to ranked web search results from a continuously refreshed index. Unlike traditional search APIs, Perplexity returns structured results with advanced filtering by domain, language, and region. Use the Search API when you need raw, ranked web results with control over sources, regions, and extracted content. For LLM-generated summaries, use our Agent API. The Sonar API remains available in maintenance mode.
Search API vs. generated answers. The Search API returns a structured JSON results[] array - title, url, snippet, date, last_updated - one entry per ranked result. When you want a prose answer with built-in citations, use the Agent API; Sonar, now in maintenance mode, also returns a cited prose answer. All are first-party Perplexity APIs; none route through OpenRouter.

Search Evals

Benchmark Perplexity Search against other web search APIs across multiple evaluation suites, and explore our latest results.
We recommend using our official SDKs for a more convenient and type-safe way to interact with the Search API.

Pricing

Pay-as-you-go pricing for all APIs. No subscription required.

Installation

Install the SDK for your preferred language:

Authentication

Set your API key as an environment variable. The SDK will automatically read it:
All SDK examples below automatically use the PERPLEXITY_API_KEY environment variable. You can also pass the key explicitly if needed.

Basic Usage

Start with a basic search query to get relevant web results. See the API Reference for complete parameter documentation.
The max_results parameter accepts values from 1 to 20, with a default maximum of 10 results per search. See pricing for details on search costs.
You can refine your search results by specifying a country to get more geographically relevant results:
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.
Execute multiple related queries in a single request for comprehensive research:
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.
For single queries, search.results is a flat list. For multi-query requests, results are grouped per query in the same order.
You can include up to 5 queries in a single multi-query request for efficient batch processing.

Domain Filtering for Search Results

The search_domain_filter parameter allows you to limit search results to specific domains (allowlist) or exclude certain domains (denylist) for focused research. The filter works in two modes:
  • Allowlist mode: Include only specified domains (no - prefix)
  • Denylist mode: Exclude specified domains (use - prefix)
You can also append a path to restrict results to a section of a site (e.g., "nature.com/articles"). See the domain filter guide for path filtering and advanced patterns. Note: You can use either allowlist or denylist mode, but not both simultaneously in the same request.
You can add a maximum of 20 domains to the search_domain_filter list. The filter works in either allowlist mode (include only) or denylist mode (exclude), but not both simultaneously. See the domain filter guide for advanced usage patterns.

Denylisting Example

You can also exclude specific domains from search results:
The search_language_filter parameter allows you to filter search results by language using ISO 639-1 language codes:
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. See the language filter guide for the complete list of supported codes.

Budget Control

To choose how much content is extracted from result pages, use the search_context_size parameter. The following values are supported:
  • low — short passages most relevant to the query.
  • medium — a balanced amount of content per document.
  • high (default) — detailed content relevant to the query.
Use search_context_size: "low" for lightweight previews or to minimize downstream token usage.

Manual Token Budgets

Use max_tokens and max_tokens_per_page when you need manual control over exact content limits for response size, total tokens returned, evaluations, or downstream context-window and cost management.
  • max_tokens caps the total webpage content returned across all results. Allows up to 1,000,000 tokens.
  • max_tokens_per_page caps content extracted from each result page.
Higher values return more extracted content; lower values keep the returned content shorter for tighter response-size, downstream context-window, or token-cost budgets. search_context_size and explicit budgets interact as follows:
  • If neither search_context_size nor budgets are specified, the default search_context_size is applied.
  • If both max_tokens and max_tokens_per_page are specified without search_context_size, those budgets are used.
  • If only one of max_tokens or max_tokens_per_page is specified without search_context_size, the other falls back to the value from the default search_context_size.
  • search_context_size cannot be combined with max_tokens or max_tokens_per_page in the same request.
Search API charges per request only, with no additional token-based pricing.

Next Steps

Best Practices

Optimize your queries and implement async patterns

Explore More

API Reference

Complete API documentation for the Perplexity Search API

Perplexity SDK

Type-safe SDK for Python and Typescript

Date & Time Filters

Filter search results by recency and date ranges

Domain Filtering Guide

Advanced domain allowlist and denylist patterns

Agent API

Third-party models from OpenAI, Anthropic, Google, and more with presets and web search tools.

Sonar API

Get AI-generated summaries with built-in search capabilities.

Search Evals

Benchmark Perplexity Search against other web search APIs across multiple evaluation suites, and explore our latest results.