Search API Overview

What you get

The Search API is one endpoint, POST https://api.perplexity.ai/search. You send a query and get back ranked web results as structured data for your own code to filter, store, or hand to a model. There is no generated answer and no token billing. Each result has:

Field	Contents
`title`	Title of the page
`url`	URL of the page
`snippet`	Query-relevant text extracted from the page, cut to `max_tokens_per_page`. Can be an empty string, so check it before you use the result.
`date`	Publication date, or `null`
`last_updated`	Date the page was last updated, or `null`

The response also carries a request id. A server_time field is present and may be null.

from perplexity import Perplexity

client = Perplexity()

search = client.search.create(
    query="renewable energy technologies",
    max_results=10,
    max_tokens=50000,
    max_tokens_per_page=4096
)

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

import Perplexity from '@perplexity-ai/perplexity_ai';

const client = new Perplexity();

const search = await client.search.create({
    query: "renewable energy technologies",
    max_results: 10,
    max_tokens: 50000,
    max_tokens_per_page: 4096
});

for (const result of search.results) {
    console.log(`${result.title}: ${result.url}`);
}

curl -X POST https://api.perplexity.ai/search \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "renewable energy technologies", "max_results": 10, "max_tokens": 50000, "max_tokens_per_page": 4096}'

Here are the first four of the ten results from a recorded response to this request, with snippets shortened. The fourth result has an empty snippet.

Response

{
  "results": [
    {
      "title": "Appendix B: Renewable Energy Technology Basics",
      "url": "https://www.epa.gov/re-powering/appendix-b-renewable-energy-technology-basics",
      "snippet": "EPA evaluated the following renewable energy technologies for this analysis.\nThey represent the most common types of renewable energy facilities being used as of 2021.",
      "date": "2025-07-24",
      "last_updated": "2025-10-16"
    },
    {
      "title": "What is renewable energy? | United Nations",
      "url": "https://www.un.org/en/climatechange/what-is-renewable-energy",
      "snippet": "Renewable energy is energy derived from natural sources that are replenished at a higher rate than they are consumed.\nSunlight and wind, for example, are such sources that are constantly being replenished.\nRenewable energy sources are plentiful and all around us.",
      "date": null,
      "last_updated": "2026-04-30"
    },
    {
      "title": "Renewable energy sources: Future innovations and breakthroughs",
      "url": "https://instituteofsustainabilitystudies.com/insights/lexicon/the-future-of-renewable-energy-innovations-and-breakthroughs/",
      "snippet": "Renewable energy sources are playing an increasingly pivotal role in the global shift towards sustainability management and green energy systems.\nBy harnessing inexhaustible resources such as sunlight, wind, and water, renewable technologies are not only enhancing energy efficiency but also driving significant environmental and economic benefits.",
      "date": "2024-06-26",
      "last_updated": "2026-05-21"
    },
    {
      "title": "Renewable energy - Wikipedia",
      "url": "https://en.wikipedia.org/wiki/Renewable_energy",
      "snippet": "",
      "date": "2001-07-31",
      "last_updated": "2026-05-18"
    }
  ],
  "id": "58a969d2-452f-4950-97df-7cd74977d479",
  "server_time": null
}

Controls

Parameter	What it does	Limits
`query`	One query, or an array of related queries processed independently	Up to 5 queries per request
`max_results`	Number of results to return	1 to 20 for web search, up to 50 for people search; default 10
`search_type`	`web` (default), `fast` for lower latency and lower cost, or `people`	See Fast Search and People Search
`max_tokens`, `max_tokens_per_page`	How much page content to extract, in total and per result	1 to 1,000,000 tokens each
`search_domain_filter`	Include only, or exclude with a `-` prefix, specific domains	Up to 20 domains, one mode per request
`search_language_filter`	Restrict results to languages	Up to 20 ISO 639-1 codes
`search_recency_filter`	`hour`, `day`, `week`, `month`, or `year`
`search_after_date_filter`, `search_before_date_filter`, `last_updated_after_filter`, `last_updated_before_filter`	Publication and update date windows	`MM/DD/YYYY`
`country`	Return results more relevant to a region	ISO 3166-1 alpha-2 code

Full parameter reference: POST /search. Agent API fields such as model, effort, instructions, and tools are not part of a search request.

Use these results in your own agent

Everything your agent needs from a Search response is title, url, and snippet. Install the Perplexity Python library (pip install perplexityai, imported as perplexity) or the TypeScript SDK (npm install @perplexity-ai/perplexity_ai), set PERPLEXITY_API_KEY in the environment, and the client picks the key up. Then:

Cap the text you hand the model with max_tokens_per_page (per result) and max_tokens (whole response). These change what comes back, not the price.
Pass query as an array of up to five related queries to fan out in one request. Five is the limit, so check the length before you send. The request is billed once but uses one rate-limit unit per query. Each query is processed independently and the results come back in one results list. Dedupe by url before you hand them to the model.
Skip results whose snippet is empty. Keep the url so the model can cite it.

from perplexity import Perplexity

client = Perplexity()

MAX_QUERIES = 5  # Search API limit per request

queries = ["US renewable energy tax credits 2026", "state renewable portfolio standards"]
if len(queries) > MAX_QUERIES:
    raise ValueError(f"Search accepts at most {MAX_QUERIES} queries per request, got {len(queries)}")

search = client.search.create(
    query=queries,
    max_results=5,
    max_tokens_per_page=1024,
    max_tokens=4000,
)

sources, seen_urls = [], set()
for r in search.results:
    snippet = r.snippet.strip()
    if not snippet or r.url in seen_urls:
        continue  # no extracted text, or a URL already kept
    seen_urls.add(r.url)
    sources.append({"title": r.title, "url": r.url, "snippet": snippet})

context = "\n\n".join(f"{s['title']} ({s['url']})\n{s['snippet']}" for s in sources)
print(context if sources else "No results with extracted text.")

import Perplexity from '@perplexity-ai/perplexity_ai';

const client = new Perplexity();

const MAX_QUERIES = 5; // Search API limit per request

const queries = ["US renewable energy tax credits 2026", "state renewable portfolio standards"];
if (queries.length > MAX_QUERIES) {
    throw new Error(`Search accepts at most ${MAX_QUERIES} queries per request, got ${queries.length}`);
}

const search = await client.search.create({
    query: queries,
    max_results: 5,
    max_tokens_per_page: 1024,
    max_tokens: 4000,
});

const seenUrls = new Set<string>();
const sources: { title: string; url: string; snippet: string }[] = [];
for (const r of search.results) {
    const snippet = r.snippet.trim();
    if (!snippet || seenUrls.has(r.url)) {
        continue; // no extracted text, or a URL already kept
    }
    seenUrls.add(r.url);
    sources.push({ title: r.title, url: r.url, snippet });
}

const context = sources.map((s) => `${s.title} (${s.url})\n${s.snippet}`).join("\n\n");
console.log(sources.length ? context : "No results with extracted text.");

curl -X POST https://api.perplexity.ai/search \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": ["US renewable energy tax credits 2026", "state renewable portfolio standards"],
    "max_results": 5,
    "max_tokens_per_page": 1024,
    "max_tokens": 4000
  }' | jq '[.results[] | select(.snippet | test("\\S"))]
          | reduce .[] as $r ([]; if any(.[]; .url == $r.url) then . else . + [$r] end)
          | map({title, url, snippet})'

Wrap that code in a tool the model can call. Each guide has the tool definition, the handler, and the tool-call loop:

OpenAI SDK, Anthropic SDK, and Gemini SDK: Search as a function tool in your own agent loop.
Perplexity API MCP server: the perplexity_search tool for Claude Code, Cursor, VS Code, and other MCP clients, with no handler to write.
Perplexity CLI: pplx search web returns the same JSON from a shell, for coding agents that run commands.
Search SDK: a Python library that adds built-in concurrency, provenance, and checkpointing on top of the same Search results and page snippets.

Price and rate limit

Item	Detail
Web search	$5.00 per 1,000 successful requests
Fast Search (`search_type: "fast"`)	$1.00 per 1,000 successful requests
Billing unit	One successful `POST /search` request. A request with five queries is one billing unit. Invalid, rate-limited, and failed requests are not billed. No token charges.
Rate limit	50 query units per second, same for every usage tier. Each query in a multi-query request counts as one unit.

Details: Search API pricing and Search API rate limits.

Search API or Agent API

You want	Use
Ranked results your code filters, stores, or feeds to your own model	Search API
A finished answer with citations, written by a model that searched for you	Agent API with the `web_search` tool
Sources, not prose, returned to an agent you run on another provider	Search API as a function tool
Sources returned to an agent that already runs on the Agent API	The Agent API `web_search` tool

Extracted text, not page reading

POST /search takes queries, not URLs. Each result’s snippet is text extracted from that page that is relevant to your query, cut to max_tokens_per_page. It is not the full page, and there is no parameter to re-fetch a page live or to control cache age. search_recency_filter, the date filters, and the date and last_updated fields on each result are how you select and check freshness. To get text from URLs you already have:

Perplexity CLI: pplx content snippets "<query>" <url> [<url> ...] returns query-relevant passages from up to 50 URLs you name, with total and per-page token budgets and failures reported per URL.
Search SDK: pplx_srch_sdk.content.snippets(query=..., urls=[...]) does the same from Python, one result per URL, each with text or an error.
Agent API fetch_url tool: a hosted model fetches and reads a URL during an Agent API run. It is a tool inside that run, billed with the run, not a standalone endpoint you call with a URL.

Ways to call it

Quickstart with the Perplexity Python library, the TypeScript SDK, and cURL
Perplexity CLI for the same ranked results as JSON from a shell
As a function tool in the OpenAI, Anthropic, and Gemini SDKs
Search SDK, a Python library for composing multi-step retrieval in code
Interactive Playground, no API key required

Getting Started

Orchestrator API

Agent API

Search API

Embeddings API

Decisions API

Perplexity SDK

Admin & Management

Resources

What you get

Controls

Use these results in your own agent

Price and rate limit

Search API or Agent API

Extracted text, not page reading

Ways to call it

​What you get

​Controls

​Use these results in your own agent

​Price and rate limit

​Search API or Agent API

​Extracted text, not page reading

​Ways to call it

What you get

Controls

Use these results in your own agent

Price and rate limit

Search API or Agent API

Extracted text, not page reading

Ways to call it