> ## 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.

# Web Search

> Search the web from the Agent API with filters, search configs, pricing, parameters, and response fields.

## Overview

The `web_search` tool lets the model search the web during an Agent API request. Use it for current information, recent news, source-grounded research, and questions that need information beyond the model's training data.

Enable the tool by adding it to the `tools` array. The model decides when to call it based on your prompt and instructions.

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

  client = Perplexity()

  response = client.responses.create(
      model="openai/gpt-5.5",
      input="What are the latest AI infrastructure announcements this week?",
      tools=[
          {
              "type": "web_search",
              "snippet_mode": "medium"
          }
      ],
      instructions="Search for current, source-grounded information before answering.",
  )

  print(response.output_text)
  ```

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

  const client = new Perplexity();

  const response = await client.responses.create({
    model: 'openai/gpt-5.5',
    input: 'What are the latest AI infrastructure announcements this week?',
    tools: [
      {
        type: 'web_search' as const,
        snippet_mode: 'medium',
      },
    ],
    instructions: 'Search for current, source-grounded information before answering.',
  });

  console.log(response.output_text);
  ```

  ```bash cURL theme={null}
  curl https://api.perplexity.ai/v1/agent \
    -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "openai/gpt-5.5",
      "input": "What are the latest AI infrastructure announcements this week?",
      "tools": [
        {
          "type": "web_search",
          "snippet_mode": "medium"
        }
      ],
      "instructions": "Search for current, source-grounded information before answering."
    }' | jq
  ```
</CodeGroup>

## Search Configs

Start with `low`, `medium`, or `high` for search context sizing. These static configs are the recommended default because they keep the request readable and let Perplexity tune the underlying token budgets over time.

| Config   | Best for                                                                         | Tradeoff                               |
| -------- | -------------------------------------------------------------------------------- | -------------------------------------- |
| `low`    | Simple facts, lightweight lookups, cost-sensitive traffic                        | Lowest cost and fastest search context |
| `medium` | General research, product comparisons, most production defaults                  | Balanced cost, latency, and context    |
| `high`   | Source-heavy answers, complex research, queries where missing details are costly | More context and higher cost           |

<CodeGroup>
  ```python Python theme={null}
  tools = [
      {
          "type": "web_search",
          "snippet_mode": "high"
      }
  ]
  ```

  ```typescript Typescript theme={null}
  const tools = [
    {
      type: 'web_search' as const,
      snippet_mode: 'high',
    },
  ];
  ```

  ```bash cURL theme={null}
  "tools": [
    {
      "type": "web_search",
      "snippet_mode": "high"
    }
  ]
  ```
</CodeGroup>

### Advanced

Use explicit token budgeting when you need to pin exact budgets for cost controls, latency controls, or evaluations. Set `max_tokens` to cap total search context across results, and set `max_tokens_per_page` to cap content extracted from each result page.

Users can choose a static config by setting `snippet_mode` to `low`, `medium`, or `high`, or choose dynamic behavior through explicit token budgeting. At any time, you can override the `low`, `medium`, or `high` config by passing explicit `max_tokens` and `max_tokens_per_page` values.

<CodeGroup>
  ```python Python theme={null}
  response = client.responses.create(
      model="openai/gpt-5.5",
      input="Find recent government guidance on AI procurement.",
      tools=[
          {
              "type": "web_search",
              "max_tokens": 6000,
              "max_tokens_per_page": 1200,
              "filters": {
                  "search_domain_filter": [".gov"],
                  "search_recency_filter": "month"
              }
          }
      ],
  )
  ```

  ```typescript Typescript theme={null}
  const response = await client.responses.create({
    model: 'openai/gpt-5.5',
    input: 'Find recent government guidance on AI procurement.',
    tools: [
      {
        type: 'web_search' as const,
        max_tokens: 6000,
        max_tokens_per_page: 1200,
        filters: {
          search_domain_filter: ['.gov'],
          search_recency_filter: 'month',
        },
      },
    ],
  });
  ```

  ```bash cURL theme={null}
  curl https://api.perplexity.ai/v1/agent \
    -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "openai/gpt-5.5",
      "input": "Find recent government guidance on AI procurement.",
      "tools": [
        {
          "type": "web_search",
          "max_tokens": 6000,
          "max_tokens_per_page": 1200,
          "filters": {
            "search_domain_filter": [".gov"],
            "search_recency_filter": "month"
          }
        }
      ]
    }' | jq
  ```
</CodeGroup>

## Filters

Use filters to constrain the sources, dates, and location context used by `web_search`. See the full [Search Filters](/docs/agent-api/filters) guide for examples and edge cases.

| Filter                       | Type             | Description                                                                           |
| ---------------------------- | ---------------- | ------------------------------------------------------------------------------------- |
| `search_domain_filter`       | array of strings | Include or exclude up to 20 domains or URLs. Prefix entries with `-` to exclude them. |
| `search_recency_filter`      | string           | Restrict results to `"hour"`, `"day"`, `"week"`, `"month"`, or `"year"`.              |
| `search_after_date_filter`   | string           | Include results published after a date in `MM/DD/YYYY` format.                        |
| `search_before_date_filter`  | string           | Include results published before a date in `MM/DD/YYYY` format.                       |
| `last_updated_after_filter`  | string           | Include results last updated after a date in `MM/DD/YYYY` format.                     |
| `last_updated_before_filter` | string           | Include results last updated before a date in `MM/DD/YYYY` format.                    |
| `user_location`              | object           | Personalize search by country, region, city, latitude, and longitude.                 |

<Warning>
  Use `search_domain_filter` in either allowlist mode or denylist mode, not both. For example, `["nasa.gov", "wikipedia.org"]` includes only those domains, while `["-reddit.com", "-pinterest.com"]` excludes those domains.
</Warning>

<CodeGroup>
  ```python Python theme={null}
  response = client.responses.create(
      model="openai/gpt-5.5",
      input="What changed in US AI policy this month?",
      tools=[
          {
              "type": "web_search",
              "snippet_mode": "medium",
              "filters": {
                  "search_domain_filter": [".gov"],
                  "search_recency_filter": "month"
              },
              "user_location": {
                  "country": "US"
              }
          }
      ],
  )
  ```

  ```typescript Typescript theme={null}
  const response = await client.responses.create({
    model: 'openai/gpt-5.5',
    input: 'What changed in US AI policy this month?',
    tools: [
      {
        type: 'web_search' as const,
        snippet_mode: 'medium',
        filters: {
          search_domain_filter: ['.gov'],
          search_recency_filter: 'month',
        },
        user_location: {
          country: 'US',
        },
      },
    ],
  });
  ```

  ```bash cURL theme={null}
  curl https://api.perplexity.ai/v1/agent \
    -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "openai/gpt-5.5",
      "input": "What changed in US AI policy this month?",
      "tools": [
        {
          "type": "web_search",
          "snippet_mode": "medium",
          "filters": {
            "search_domain_filter": [".gov"],
            "search_recency_filter": "month"
          },
          "user_location": {
            "country": "US"
          }
        }
      ]
    }' | jq
  ```
</CodeGroup>

## Parameters

| Parameter             | Type    | Required | Description                                                             |
| --------------------- | ------- | -------- | ----------------------------------------------------------------------- |
| `type`                | string  | Yes      | Must be `"web_search"`.                                                 |
| `snippet_mode`        | string  | No       | Static search config: `"low"`, `"medium"`, or `"high"`.                 |
| `filters`             | object  | No       | Domain and date filters. See [Search Filters](/docs/agent-api/filters). |
| `user_location`       | object  | No       | Location context for search personalization.                            |
| `max_tokens`          | integer | No       | Maximum total tokens for search context.                                |
| `max_tokens_per_page` | integer | No       | Maximum tokens extracted from each search result page.                  |

## Response Shape

When `web_search` runs, the response can include a `search_results` output item before the final assistant message. The final `usage` object includes token counts, cost details, and `tool_calls_details.web_search.invocation` when tool-call usage is reported.

```json theme={null}
{
  "output": [
    {
      "type": "search_results",
      "queries": ["AI infrastructure announcements"],
      "results": [
        {
          "id": 1,
          "url": "https://example.com/news",
          "title": "Example AI infrastructure announcement",
          "snippet": "A short snippet from the search result.",
          "date": "2026-05-01",
          "last_updated": "2026-05-01",
          "source": "web"
        }
      ]
    },
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "The answer generated from the search results."
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 1200,
    "output_tokens": 300,
    "total_tokens": 1500,
    "tool_calls_details": {
      "web_search": {
        "invocation": 1
      }
    }
  }
}
```

## Pricing

`web_search` is billed at **$5 per 1,000 search calls** (**$0.005 per search**). Model token usage is billed separately according to Agent API token pricing.

<Note>
  Pricing follows the same pattern as other tool calls: pay for tool invocations plus model tokens. See [Pricing](/docs/getting-started/pricing).
</Note>

## Next Steps

<CardGroup cols={2}>
  <Card title="Fetch URL Content" icon="file-text" href="/docs/agent-api/tools/fetch-url-content">
    Fetch full content from known URLs.
  </Card>

  <Card title="Search Filters" icon="filter" href="/docs/agent-api/filters">
    Control domains, dates, recency, and location context.
  </Card>

  <Card title="Agent API Presets" icon="settings" href="/docs/agent-api/presets">
    Use optimized presets for common Agent API workloads.
  </Card>

  <Card title="API Reference" icon="code-circle" href="/api-reference/agent-post">
    View complete endpoint documentation.
  </Card>
</CardGroup>