> ## Documentation Index
> Fetch the complete documentation index at: https://docs.perplexity.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Search API Overview

> The Search API returns ranked web results as JSON, not a generated answer. What each result contains, the request controls and limits, the price per request, and when to use it instead of the Agent API.

## 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` | Content extracted from the page, sized by `max_tokens_per_page` |
| `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`.

```python Python theme={null}
from perplexity import Perplexity

client = Perplexity()

search = client.search.create(
    query="latest AI developments 2025",
    max_results=3
)

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

```typescript TypeScript theme={null}
import Perplexity from '@perplexity-ai/perplexity_ai';

const client = new Perplexity();

const search = await client.search.create({
    query: "latest AI developments 2025",
    max_results: 3
});

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

```bash cURL theme={null}
curl -X POST https://api.perplexity.ai/search \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "latest AI developments 2025", "max_results": 3}'
```

```json Response theme={null}
{
  "results": [
    {
      "title": "...",
      "url": "https://...",
      "snippet": "...",
      "date": "2025-01-15",
      "last_updated": "2025-01-16"
    }
  ],
  "id": "e38104d5-6bd7-4d82-bc4e-0a21179d1f77",
  "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](/docs/search/fast-search.md) and [People Search](/docs/search/filters/people-search.md) |
| `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](/api-reference/search-post.md). Agent API fields such as `model`, `effort`, `instructions`, and `tools` are not part of a search request.

## 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](/docs/getting-started/pricing.md#search-api-pricing) and [Search API rate limits](/docs/admin/rate-limits-usage-tiers.md#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](/docs/agent-api/quickstart.md) 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 |

## Ways to call it

* [Quickstart](/docs/search/quickstart.md) with the Perplexity Python library, the TypeScript SDK, and cURL
* [Perplexity CLI](/docs/cli/overview.md) for the same ranked results as JSON from a shell
* As a function tool in the [OpenAI](/docs/search/agent-sdks/openai.md), [Anthropic](/docs/search/agent-sdks/anthropic.md), and [Gemini](/docs/search/agent-sdks/gemini.md) SDKs
* [Search SDK](/docs/search-sdk/overview.md), a Python library for composing multi-step retrieval in code
* [Interactive Playground](https://console.perplexity.ai/project/playground/search), no API key required