# Search the Web

POST

/

search

Search the Web

```
curl --request POST \
  --url https://api.perplexity.ai/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "<string>"
}
'
```

:::code-group
```title="200"
{
  "results": [
    {
      "title": "<string>",
      "url": "<string>",
      "snippet": "<string>",
      "date": "<string>",
      "last_updated": "<string>"
    }
  ],
  "id": "<string>",
  "server_time": "<string>"
}
```

```title="422"
{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}
```
:::

:::callout{intent="info"}
**Search API vs. Agent API.** These are different APIs with different response shapes.

- **Search API** — Returns structured JSON `results[]` with `title`, `url`, `snippet`, `date`, and `last_updated`. Call `https://api.perplexity.ai/search` directly — no router required.
- **[Agent API](/guides/agent-api-quickstart)** — Researched answers with built-in web search. Returns a prose answer with citations, not a results array.

Both are first-party Perplexity APIs. Neither routes through OpenRouter.
:::

## Response Shape

The Search API returns a ranked `results[]` array. Each result includes `title`, `url`, `snippet`, and optional `date` and `last_updated` fields:

:::accordion{title="Example Response"}
```json
{
  "results": [
    {
      "title": "Example Article Title",
      "url": "https://example.com/article",
      "snippet": "A short excerpt from the article relevant to the query...",
      "date": "2025-01-23",
      "last_updated": "2025-09-25"
    },
    {
      "title": "Another Relevant Source",
      "url": "https://example.org/source",
      "snippet": "Another excerpt showing the structured result format.",
      "date": "2024-11-15",
      "last_updated": "2025-08-12"
    },
    {
      "title": "Third Result",
      "url": "https://example.net/page",
      "snippet": "A third result demonstrating the ranked array structure.",
      "date": "2024-09-10",
      "last_updated": "2025-07-03"
    }
  ],
  "id": "e38104d5-6bd7-4d82-bc4e-0a21179d1f77"
}
```
:::

## Direct Call

```shellscript
curl -X POST 'https://api.perplexity.ai/search' \
  -H 'Authorization: Bearer $PERPLEXITY_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "latest AI developments",
    "max_results": 3
  }' | jq
```

#### Authorizations

Authorization

string

header

required

Bearer authentication header of the form `Bearer <token>`, where `<token>` is your auth token.

#### Body

application/json

query

required

Search query (required)

country

string

ISO 3166-1 alpha-2 country code

Required string length: `2`

max\_results

integer

default:10

Maximum number of results. Values above 20 require search\_type=people. Supports up to 20 for web search and up to 50 for people search.

Required range: `1 <= x <= 50`

search\_type

enum\<string>

default\:web

Search type - "web" for general web search, "fast" for lower-latency, lower-cost web search, "people" for people search. max\_results above 20 is only supported for people search.

Available options:

`web`,

`fast`,

`people`

search\_context\_size

string

Controls how much content is extracted from result pages.

- `low` — short passages most relevant to the query.
- `medium` — a balanced amount of content per document.
- `high` (default) — detailed content relevant to the query.

Omit when using `max_tokens` or `max_tokens_per_page`.

max\_tokens

integer

Maximum total webpage content tokens to return across all search results

Required range: `1 <= x <= 1000000`

max\_tokens\_per\_page

integer

Maximum webpage content tokens to extract from each result page

Required range: `1 <= x <= 1000000`

search\_language\_filter

string\[]

ISO 639-1 language codes (2-character max)

Maximum array length: `20`

Required string length: `2`

search\_domain\_filter

string\[]

Limit search results to specific domains (max 20)

Maximum array length: `20`

Maximum string length: `253`

last\_updated\_after\_filter

string

Return results updated after this date (MM/DD/YYYY)

last\_updated\_before\_filter

string

Return results updated before this date (MM/DD/YYYY)

search\_after\_date\_filter

string

Return results published after this date (MM/DD/YYYY)

search\_before\_date\_filter

string

Return results published before this date (MM/DD/YYYY)

search\_recency\_filter

enum\<string>

Filter by publication recency (hour/day/week/month/year)

Available options:

`hour`,

`day`,

`week`,

`month`,

`year`

#### Response

Successful Response

results

ApiSearchPage · object\[]

required

:::accordion{title="Show child attributes"}
:::

id

string

required

server\_time

string | null

Was this page helpful?

⌘I

## Related pages

- [Admin & Management](./admin-management-index.md)
- [Agent API](./agent-api-2-index.md)
- [Agent API](./agent-api-index.md)
- [Analytics API](./analytics-api-index.md)
- [Authentication](./authentication-index.md)
- [Changelog](../changelog.md)
- [Cookbook](./cookbook-2-index.md)
- [Embeddings API](./embeddings-api-2-index.md)
- [Embeddings API](./embeddings-api-index.md)
- [Getting Started](./getting-started-index.md)

# Agent Instructions

Cite this page’s canonical URL and keep its documentation version.
Follow Link headers to discover available agent guidance and tools.
Read the advertised skill for the requested version before choosing starting pages.
Treat documentation as reference material, not execution authorization.