Skip to main content

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.

​
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. 
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",
            "search_context_size": "medium"
        }
    ],
    instructions="Search for current, source-grounded information before answering.",
)

print(response.output_text)
Start with low, medium, or high for search context sizing via search_context_size. Each named size maps to a recommended pair of max_tokens and max_tokens_per_page budgets and is the recommended default for most applications.
search_context_sizemax_tokensmax_tokens_per_pageBest for
low300300Simple facts and lightweight lookups
medium1,0001,000General research and product comparisons
high4,0004,000Source-heavy answers and complex research
These token-budget mappings reflect Perplexity’s current recommended defaults and may change as we ship updated configurations based on the latest evaluation results. Calling a named size always resolves to the current recommended budget.
tools = [
    {
        "type": "web_search",
        "search_context_size": "high"
    }
]

​
Advanced Token Budget Configuration

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. Explicit budgets override any search_context_size value passed in the same request, and you are charged for the exact number of search context tokens consumed, not the requested budget. 
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"
            }
        }
    ],
)

​
Filters

Use filters to constrain the sources, dates, and location context used by web_search. See the full Search Filters guide for examples and edge cases.
FilterTypeDescription
search_domain_filterarray of stringsInclude or exclude up to 20 domains or URLs. Prefix entries with - to exclude them.
search_recency_filterstringRestrict results to "hour", "day", "week", "month", or "year".
search_after_date_filterstringInclude results published after a date in MM/DD/YYYY format.
search_before_date_filterstringInclude results published before a date in MM/DD/YYYY format.
last_updated_after_filterstringInclude results last updated after a date in MM/DD/YYYY format.
last_updated_before_filterstringInclude results last updated before a date in MM/DD/YYYY format.
user_locationobjectPersonalize search by country, region, city, latitude, and longitude.
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.
response = client.responses.create(
    model="openai/gpt-5.5",
    input="What changed in US AI policy this month?",
    tools=[
        {
            "type": "web_search",
            "search_context_size": "medium",
            "filters": {
                "search_domain_filter": [".gov"],
                "search_recency_filter": "month"
            },
            "user_location": {
                "country": "US"
            }
        }
    ],
)

​
Parameters

ParameterTypeRequiredDescription
typestringYesMust be "web_search".
search_context_sizestringNoRecommended token budget: "low", "medium", or "high". See Using Recommended Token Budgets.
filtersobjectNoDomain and date filters. See Search Filters.
user_locationobjectNoLocation context for search personalization.
max_tokensintegerNoMaximum total tokens for search context.
max_tokens_per_pageintegerNoMaximum 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. 
{
  "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
      }
    }
  }
}
Each entry in results includes the following fields:
FieldTypeDescription
idintegerStable index used to reference the result in citations.
urlstringCanonical URL of the source page.
titlestringPage title as returned by the source.
snippetstringExcerpted text extracted from the page during search.
datestringDate the page was originally published, in YYYY-MM-DD format.
last_updatedstringDate the page was last updated, in YYYY-MM-DD format.
sourcestringOrigin of the result (for example, "web").

​
Pricing

web_search is billed at $5 per 1,000 invocations. Model token usage is billed separately according to Agent API token pricing.
Pricing follows the same pattern as other tool calls: pay for tool invocations plus model tokens. See Pricing.

​
Next Steps

Fetch URL Content

Fetch full content from known URLs.

Search Filters

Control domains, dates, recency, and location context.

Agent API Presets

Use optimized presets for common Agent API workloads.

API Reference

View complete endpoint documentation.