Skip to main content

Overview

Perplexity’s Search API returns real-time, ranked web results as structured data, with controls for domains, languages, regions, and extracted content. Use the Search API when you need raw results for your own processing. For an LLM-generated answer with citations, use the Agent API.

Add Perplexity Search to your agent

Ask your agent to install the Perplexity Search skill:
You can also try Perplexity Search in the interactive Playground with no API key required.

Installation

Install one of our official SDKs for a convenient, type-safe integration:

Authentication

Set your API key as an environment variable. The official SDKs read it automatically, but you can also pass it explicitly:

Basic Usage

Start with a basic search query to get relevant web results. max_results accepts values from 1 to 20 and defaults to 10. See the API Reference for all parameters and pricing for search costs.
Set country to an ISO 3166-1 alpha-2 code such as US, GB, DE, or JP to get more geographically relevant results. This is useful for local news, regulations, and other region-specific queries:
Pass up to five related queries in one request to explore different angles of a topic. Each query is processed independently:

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.

Next Steps

Best Practices

Optimize your queries and implement async patterns

Pricing

Review per-request pricing; Search has no additional token charges

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.

Search Evals

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