Perplexity Search API Tutorial: Requests, Filters and Examples

In one line

POST a query to /search, get ranked web results back

Endpoint https://api.perplexity.ai/search · up to 20 results per query and 5 queries per request · $5 per 1,000 requests, or $1 per 1,000 in fast mode · same API key as Sonar.

Choose

Search API vs Sonar API: which do you need?

Search API

Returns the raw results. You decide what to do with them.

Show results in your own UI
Feed your own LLM (RAG)
Monitor news, brands or prices
Cheapest per call

results[] → title, url, snippet, date

Sonar API

Searches, reads and writes a cited answer for you.

Q&A features and chatbots
No model of your own needed
Citations included
Billed per token plus request fee

choices[0].message.content + citations[]

Tutorial

Perplexity Search API tutorial in 6 steps

1Get your API key

Create a key in the API console and save it as PERPLEXITY_API_KEY. Our API key guide covers storing it safely.

2Make your first search request

cURL

curl -X POST https://api.perplexity.ai/search \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "latest renewable energy policy in Sri Lanka",
    "max_results": 5
  }'

Python

# pip install perplexityai
from perplexity import Perplexity

client = Perplexity()  # reads PERPLEXITY_API_KEY

search = client.search.create(
    query="latest renewable energy policy in Sri Lanka",
    max_results=5,
)

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

Node.js

// Node.js 18+, server-side only
const res = await fetch("https://api.perplexity.ai/search", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.PERPLEXITY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: "latest renewable energy policy in Sri Lanka",
    max_results: 5,
  }),
});
const data = await res.json();
for (const r of data.results) console.log(r.title, r.url);

3Read the results

Results arrive in results, ranked by relevance. Each has a title, url, snippet of extracted page text, a publish date and last_updated (either can be null).

Response (shortened example)

{
  "id": "…",
  "server_time": "…",
  "results": [
    {
      "title": "Page title",
      "url": "https://example.com/article",
      "snippet": "Extracted text from the page…",
      "date": "2026-09-30",
      "last_updated": "2026-10-02"
    }
  ]
}

4Filter by site, recency, country and language

Narrow results to trusted sources and fresh content. Use a minus sign to exclude a domain.

Python

search = client.search.create(
    query="electric vehicle battery recycling",
    max_results=10,
    search_recency_filter="month",              # hour, day, week, month, year
    country="US",                                # ISO 3166-1 alpha-2
    search_language_filter=["en"],               # ISO 639-1, max 10
    search_domain_filter=["nature.com", "-reddit.com"],  # allow, or "-" to exclude (max 20)
)

Need an exact window? Use publish-date filters:

Python

search = client.search.create(
    query="central bank interest rate decision",
    search_after_date_filter="01/01/2026",    # MM/DD/YYYY
    search_before_date_filter="06/30/2026",
)

5Run several queries at once

Send up to five related queries in a single request, which is useful for comparisons and broad research.

Python

search = client.search.create(
    query=[
        "Perplexity Sonar API pricing",
        "Perplexity Search API pricing",
        "Perplexity Agent API tools",
    ],                       # up to 5 queries in one request
    max_results=5,
)

6Go faster and cheaper

Set search_type to fast for lower latency at $1 per 1,000 requests, and cap snippet length with max_tokens_per_page.

Python

search = client.search.create(
    query="weather Colombo today",
    search_type="fast",         # lower latency, $1 per 1,000 requests
    max_results=3,
    max_tokens_per_page=300,    # keep snippets short
)

Search API request builder

Set your options and copy a ready-made request in cURL or Python.

Query Max results Search type Recency Country (optional) Domains (comma separated)

cURL

Python

Estimated cost: $0.005 per request.

Reference

Search API parameter reference

Request body for POST https://api.perplexity.ai/search.

Parameter	Type	Default	What it does
query	string or string[]	required	Your search. Pass a list for up to 5 queries at once.
max_results	integer	10	Results per query: 1–20.
search_type	string	web	web, fast (lower latency, cheaper) or people.
search_recency_filter	string	—	hour, day, week, month or year.
search_after_date_filter	string	—	Only results published after a date (MM/DD/YYYY).
search_before_date_filter	string	—	Only results published before a date (MM/DD/YYYY).
last_updated_after_filter	string	—	Only pages updated after a date (MM/DD/YYYY).
last_updated_before_filter	string	—	Only pages updated before a date (MM/DD/YYYY).
search_domain_filter	string[]	—	Up to 20 domains. Prefix with - to exclude.
country	string	—	ISO 3166-1 alpha-2 code, e.g. US, GB, LK.
search_language_filter	string[]	—	Up to 10 ISO 639-1 codes, e.g. en, fr.
search_context_size	string	high	low, medium or high.
max_tokens	integer	—	Total content budget across results (1–1,000,000).
max_tokens_per_page	integer	—	Content limit per result (1–1,000,000).

From the official API reference, October 2026.

Recipes

Practical recipes

Build a RAG pipeline with fresh web data

Fetch results, format them as numbered sources, and ask your own language model to answer with citations.

Python

from perplexity import Perplexity

client = Perplexity()

def web_context(question: str, k: int = 5) -> str:
    """Fetch fresh web results and format them as numbered context for any LLM."""
    search = client.search.create(query=question, max_results=k, max_tokens_per_page=500)
    blocks = []
    for i, r in enumerate(search.results, start=1):
        blocks.append(f"[{i}] {r.title}\nURL: {r.url}\nDate: {r.date}\n{r.snippet}")
    return "\n\n".join(blocks)

question = "What changed in the EU AI Act this year?"
context = web_context(question)

prompt = f"""Answer using only the sources below. Cite them like [1], [2].

{context}

Question: {question}"""
# Send `prompt` to the language model of your choice.

Brand and news monitoring

Run on a schedule with a one-day recency filter to catch new mentions.

Python

search = client.search.create(
    query=["your-company-name", "your-product-name review"],
    search_recency_filter="day",
    max_results=10,
)

Search only your documentation

Restrict results to your own docs site for a help-centre search box.

Python

search = client.search.create(
    query="how to configure rate limits",
    search_domain_filter=["docs.yourproduct.com"],
    max_results=8,
)

Production

Best practices

Call from your server

Keep the API key on the backend and expose your own endpoint.

Use fast mode by default

Switch to web search only where quality matters more than speed.

Filter to trusted domains

Allowlists improve quality and reduce noise for focused apps.

Cache and deduplicate

Cache popular queries briefly and remove duplicate URLs across multi-query results.

Handle null dates

date and last_updated can be null; don’t sort or filter on them without a fallback.

Respect source sites

Link back to the original pages and follow each site’s terms when displaying content.

Common errors

Code	Likely cause	Fix
400	Invalid parameter	Check max_results is 1–20, dates use MM/DD/YYYY, and no more than 20 domains or 5 queries.
401	Missing or wrong key	Send Authorization: Bearer YOUR_KEY and check the environment variable loads.
429	Too many requests	Retry with exponential backoff and cache repeated queries.
Empty results	Filters too strict	Loosen recency, domains or language, or rephrase the query.

FAQ

Search API questions

What is the Perplexity Search API?

An API that returns ranked web search results (title, URL, snippet, publish date and last-updated date) for a query, without writing an answer. It’s built for apps and AI pipelines that need fresh web data.

How much does the Search API cost?

$5 per 1,000 requests for standard web search and $1 per 1,000 requests with search_type set to fast. There are no token charges for the results. See our API pricing guide for more.

What’s the difference between the Search API and the Sonar API?

Sonar searches the web and writes a cited answer. The Search API only returns the results, so you decide what to do with them: show them, filter them or feed them to your own model.

How many results can I get per request?

Up to 20 per query with web or fast search. You can send up to 5 queries in one request.

Can I limit results to specific websites?

Yes. Use search_domain_filter with up to 20 domains. Add a minus sign before a domain to exclude it instead.

How do I get only recent results?

Use search_recency_filter (hour, day, week, month or year), or the date filters with MM/DD/YYYY dates.

Do I need a separate key for the Search API?

No. The same Perplexity API key works for Search, Sonar, Agent and the other APIs.

More API guides

API starting guideFirst call in 5 steps Get an API keyCreate and secure it API pricingCosts and calculator Sonar APICited answers Python guideSDK examples TroubleshootingErrors and fixes

Build

Run your first search in under a minute

Grab a key from the official console, paste the cURL example, and see live results.

Open the API console ↗ Official docs ↗