Web Search

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.6-sol",
    input="Explain the architecture of NVIDIA's CUDA programming model: threads, blocks, grids, warps, and memory hierarchy, and how they enable GPU parallelism.",
    tools=[
        {
            "type": "web_search"
        }
    ],
    instructions="Search for current, source-grounded information before answering.",
)

print(response.output_text)

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

const client = new Perplexity();

const response = await client.responses.create({
  model: 'openai/gpt-5.6-sol',
  input: 'Explain the architecture of NVIDIA\'s CUDA programming model: threads, blocks, grids, warps, and memory hierarchy, and how they enable GPU parallelism.',
  tools: [
    {
      type: 'web_search' as const,
    },
  ],
  instructions: 'Search for current, source-grounded information before answering.',
});

console.log(response.output_text);

curl https://api.perplexity.ai/v1/agent \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.6-sol",
    "input": "Explain the architecture of NVIDIA\u0027s CUDA programming model: threads, blocks, grids, warps, and memory hierarchy, and how they enable GPU parallelism.",
    "tools": [
      {
        "type": "web_search"
      }
    ],
    "instructions": "Search for current, source-grounded information before answering."
  }' | jq

Response

{
  "id": "c6e956f3-0667-40d1-9f47-ab3f5afa9bf7",
  "results": [
    {
      "snippet": "",
      "title": "CUDA C++ Programming Guide - NVIDIA Documentation Hub",
      "url": "https://docs.nvidia.com/cuda/cuda-c-programming-guide/",
      "date": "2026-04-02",
      "last_updated": "2026-05-21"
    },
    {
      "snippet": "",
      "title": "CUDA Live: Your Parallel Programming Guide - YouTube",
      "url": "https://www.youtube.com/watch?v=ftI48A8K5Vg",
      "date": "2026-02-19",
      "last_updated": "2026-05-20"
    },
    {
      "snippet": "CUDA\nCUDA, which stands for Compute Unified Device Architecture, is a parallel computing platform and application programming interface (API) model created by NVIDIA.\nIt allows software developers...",
      "title": "What Is CUDA? - Supermicro",
      "url": "https://www.supermicro.com/en/glossary/cuda",
      "date": null,
      "last_updated": "2026-05-16"
    }
  ],
  "server_time": null
}

Configuring Search

Search Type

Set search_type to "fast" to run each web_search call on the lower-latency Fast Search path. Fast calls cost $1.00 per 1,000 invocations instead of $2.50, plus model tokens. Set search_type to "web" for standard web search. If you omit it, the tool inherits the effort level’s search type when one is configured; otherwise, it uses "web". Use fast for day-to-day agent loops and high-volume tool calls. Use web for rare, difficult, or ambiguous questions. search_type is separate from the Agent API fast effort level. The fast, low, medium, high, and xhigh effort levels set search_type: "fast" by default. To override an effort level’s search type, pass search_type on the web_search tool in your request. First, install a library and set PERPLEXITY_API_KEY. Passing search_type on the web_search tool requires Perplexity Python library 0.43.6 or later, or TypeScript SDK 0.38.6 or later. Older TypeScript SDK versions fail type checking on this field. If you can’t upgrade, cast the tool object with as any.

from perplexity import Perplexity

client = Perplexity()

response = client.responses.create(
    model="openai/gpt-5.6-luna",
    input="What is the latest stable Rust release, and what changed?",
    tools=[
        {
            "type": "web_search",
            "search_type": "fast"
        }
    ]
)

print(response.output_text)

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

const client = new Perplexity();

const response = await client.responses.create({
    model: "openai/gpt-5.6-luna",
    input: "What is the latest stable Rust release, and what changed?",
    tools: [
        {
            type: "web_search",
            search_type: "fast"
        }
    ]
});

console.log(response.output_text);

curl https://api.perplexity.ai/v1/agent \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.6-luna",
    "input": "What is the latest stable Rust release, and what changed?",
    "tools": [
      {
        "type": "web_search",
        "search_type": "fast"
      }
    ]
  }' | jq

You can combine search_type with token budgets, max_results, and filters, as described below.

Token Budgets

Use token budgets when you need to control search depth 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. When omitted, the default budgets apply. You are charged for the exact number of search context tokens consumed, not the requested budget.

response = client.responses.create(
    model="openai/gpt-5.6-sol",
    input="Summarize the US OMB M-24-10 memorandum on AI procurement: scope, key requirements for federal agencies, and the rights-impacting AI categories.",
    tools=[
        {
            "type": "web_search",
            "max_tokens": 6000,
            "max_tokens_per_page": 1200,
            "filters": {
                "search_domain_filter": [".gov"],
                "search_recency_filter": "month"
            }
        }
    ],
)

const response = await client.responses.create({
  model: 'openai/gpt-5.6-sol',
  input: 'Summarize the US OMB M-24-10 memorandum on AI procurement: scope, key requirements for federal agencies, and the rights-impacting AI categories.',
  tools: [
    {
      type: 'web_search' as const,
      max_tokens: 6000,
      max_tokens_per_page: 1200,
      filters: {
        search_domain_filter: ['.gov'],
        search_recency_filter: 'month',
      },
    },
  ],
});

curl https://api.perplexity.ai/v1/agent \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.6-sol",
    "input": "Summarize the US OMB M-24-10 memorandum on AI procurement: scope, key requirements for federal agencies, and the rights-impacting AI categories.",
    "tools": [
      {
        "type": "web_search",
        "max_tokens": 6000,
        "max_tokens_per_page": 1200,
        "filters": {
          "search_domain_filter": [".gov"],
          "search_recency_filter": "month"
        }
      }
    ]
  }' | jq

Response

{
  "id": "75a4ee6f-ac57-4ed1-ad17-ad2d54f70428",
  "results": [
    {
      "snippet": "",
      "title": "[PDF] M-24-10 MEMORANDUM FOR THE HEADS OF EXECUTIVE ...",
      "url": "https://www.whitehouse.gov/wp-content/uploads/2024/03/M-24-10-Advancing-Governance-Innovation-and-Risk-Management-for-Agency-Use-of-Artificial-Intelligence.pdf",
      "date": null,
      "last_updated": "2026-03-30"
    },
    {
      "snippet": "",
      "title": "[PDF] M-24-18 MEMORANDUM FOR THE HEADS OF EXECUTIVE ...",
      "url": "https://www.whitehouse.gov/wp-content/uploads/2024/10/M-24-18-AI-Acquisition-Memorandum.pdf",
      "date": null,
      "last_updated": "2026-03-21"
    },
    {
      "snippet": "",
      "title": "OMB Releases Requirements for Responsible AI Procurement by ...",
      "url": "https://www.cov.com/en/news-and-insights/insights/2024/10/omb-releases-requirements-for-responsible-ai-procurement-by-federal-agencies",
      "date": "2023-04-18",
      "last_updated": "2026-03-25"
    }
  ],
  "server_time": null
}

Number of Results

Set max_results to control how many results the tool collects per web_search call. It’s the total for the call; with several reformulated queries the budget is split per query (roughly ceil(max_results / number_of_queries)). When omitted, the default budget applies.

tools = [
    {
        "type": "web_search",
        "max_results": 20
    }
]

const tools = [
  {
    type: 'web_search' as const,
    max_results: 20,
  },
];

"tools": [
  {
    "type": "web_search",
    "max_results": 20
  }
]

max_results accepts the range documented in the API reference. Within range, the backend may return fewer results than requested. Use it together with max_tokens_per_page to trade breadth (number of results) against depth (content extracted per result).

Filters

Use filters to constrain the sources, dates, and location context used by web_search.

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.

Domain filter

Use search_domain_filter in either allowlist mode or denylist mode, not both. The domain filter accepts up to 20 domains or URLs. For example, ["nasa.gov", "wikipedia.org"] includes only those domains, while ["-reddit.com", "-pinterest.com"] excludes those domains.

Entries can be at the domain level (e.g., wikipedia.org) or at the URL level (e.g., https://en.wikipedia.org/wiki/Chess) for more granular control.

Recency filter

search_recency_filter maps each value to a relative window:

Value	Window
`hour`	Past hour — use for real-time data such as breaking news or live events
`day`	Past 24 hours
`week`	Past 7 days
`month`	Past 30 days
`year`	Past 365 days

For exact ranges, use search_after_date_filter / search_before_date_filter (publication date) or last_updated_after_filter / last_updated_before_filter (last update). Date filter values must use the MM/DD/YYYY format (e.g., "03/01/2026").

Location filter

user_location accepts any combination of the following fields:

country — Two-letter ISO 3166-1 alpha-2 code (for example, "US", "FR").
region — Region or state name (for example, "California").
city — City name (for example, "San Francisco").
latitude and longitude — Coordinates for precise targeting.

city and region significantly improve location accuracy. Include them alongside country whenever possible.

latitude and longitude must be provided together with country. They cannot be supplied on their own.

Filter Usage Cheatsheet

Copy any of these snippets into a web_search tool object. user_location sits alongside filters, while the other controls sit inside filters.

Filter	Example
Domain allowlist	`filters: { search_domain_filter: ["docs.perplexity.ai", "developer.mozilla.org"] }`
Domain denylist	`filters: { search_domain_filter: ["-reddit.com", "-pinterest.com"] }`
Recency	`filters: { search_recency_filter: "week" }`
Published date range	`filters: { search_after_date_filter: "01/01/2026", search_before_date_filter: "05/01/2026" }`
Last updated range	`filters: { last_updated_after_filter: "01/01/2026", last_updated_before_filter: "05/01/2026" }`
User location	`user_location: { country: "US", region: "CA", city: "San Francisco", latitude: 37.7749, longitude: -122.4194 }`

Filters compose freely. Combine any of the source, date, recency, and location filters above in a single web_search tool object — there’s no per-request limit on filter combinations.

response = client.responses.create(
    model="openai/gpt-5.6-sol",
    input="What were the binding obligations of President Biden's 2023 Executive Order 14110 on AI?",
    tools=[
        {
            "type": "web_search",
            "filters": {
                "search_domain_filter": [".gov"],
                "search_recency_filter": "month"
            },
            "user_location": {
                "country": "US"
            }
        }
    ],
)

const response = await client.responses.create({
  model: 'openai/gpt-5.6-sol',
  input: 'What were the binding obligations of President Biden\'s 2023 Executive Order 14110 on AI?',
  tools: [
    {
      type: 'web_search' as const,
      filters: {
        search_domain_filter: ['.gov'],
        search_recency_filter: 'month',
      },
      user_location: {
        country: 'US',
      },
    },
  ],
});

curl https://api.perplexity.ai/v1/agent \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.6-sol",
    "input": "What were the binding obligations of President Biden\u0027s 2023 Executive Order 14110 on AI?",
    "tools": [
      {
        "type": "web_search",
        "filters": {
          "search_domain_filter": [".gov"],
          "search_recency_filter": "month"
        },
        "user_location": {
          "country": "US"
        }
      }
    ]
  }' | jq

Response

{
  "id": "11c1c78d-b8c8-4442-8563-a79b7faac177",
  "results": [
    {
      "snippet": "**Executive Order 14110**, titled **Executive Order on Safe, Secure, and Trustworthy Development and Use of Artificial Intelligence** (sometimes referred to as \"**Executive Order on Artificial...",
      "title": "Executive Order 14110 - Wikipedia",
      "url": "https://en.wikipedia.org/wiki/Executive_Order_14110",
      "date": "2023-11-13",
      "last_updated": "2026-03-21"
    },
    {
      "snippet": "",
      "title": "657",
      "url": "https://www.govinfo.gov/content/pkg/CFR-2024-title3-vol1/pdf/CFR-2024-title3-vol1-eo14110.pdf",
      "date": null,
      "last_updated": "2025-01-28"
    },
    {
      "snippet": "",
      "title": "Federal Register, Volume 88 Issue 210 (Wednesday, November 1 ...",
      "url": "https://www.govinfo.gov/content/pkg/FR-2023-11-01/html/2023-24283.htm",
      "date": null,
      "last_updated": "2026-03-08"
    }
  ],
  "server_time": null
}

Parameters

Parameter	Type	Required	Description
`type`	string	Yes	Must be `"web_search"`.
`search_type`	string	No	`"web"` or `"fast"`. Inherits the effort level’s value when configured; otherwise defaults to `"web"`. See Search Type.
`filters`	object	No	Domain, date, recency, and location filters. See Filters.
`user_location`	object	No	Location context for search personalization.
`max_results`	integer	No	Upper bound on results collected per call (1-50). See Number of Results.
`max_tokens`	integer	No	Maximum total tokens for search context. See Token Budgets.
`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.search_web.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": {
      "search_web": {
        "invocation": 1
      }
    }
  }
}

Each entry in results includes the following fields:

Field	Type	Description
`id`	integer	Stable index used to reference the result in citations.
`url`	string	Canonical URL of the source page.
`title`	string	Page title as returned by the source.
`snippet`	string	Excerpted text extracted from the page during search.
`date`	string	Date the page was originally published, in `YYYY-MM-DD` format.
`last_updated`	string	Date the page was last updated, in `YYYY-MM-DD` format.
`source`	string	Origin of the result (for example, `"web"`).

Want inline citations? Whether the model adds markers to the answer is prompt-dependent, so ask for them explicitly - for example, append to your prompt: “Cite your sources inline using bracketed markers, one source per bracket, like [1][2].” Each number then refers to a result’s id. Regardless of markers, treat the id and url fields of each search_results entry as the source of truth for citations.

Pricing

web_search is billed at $2.50 per 1,000 invocations**, or **$1.00 per 1,000 invocations with search_type: "fast". Fast calls are still reported under tool_calls_details.search_web. 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.

Limits / Quotas

web_search runs inside Agent API requests and is governed by Agent API request and token limits. See Rate Limits & Usage Tiers for the current tier-based Agent API limits.

Limit	Applies to	Guidance
Rate limits	Agent API requests that include `web_search`	Agent API request and token limits apply to the request. Add retry and backoff handling for production traffic.
Domain entries	`search_domain_filter`	Up to 20 domains or URLs per request. Use either allowlist or denylist mode as described in the Filters warning.
Search context budget	`max_tokens`, `max_tokens_per_page`	Default budgets apply when omitted. Use explicit token caps when you need tighter cost or latency controls.
Tool-call billing	`web_search` invocations	Each search invocation counts toward tool-call usage and pricing, separate from model token usage.

Next Steps

Fetch URL Content

Fetch full content from known URLs.

People Search

Search for professionals, employees, and people.

Agent API Effort Levels

Use optimized effort levels for common Agent API workloads.

API Reference

View complete endpoint documentation.

Getting Started

Orchestrator API

Agent API

Search API

Embeddings API

Decisions API

Perplexity SDK

Admin & Management

Resources

Overview

Configuring Search

Search Type

Token Budgets

Number of Results

Filters

Domain filter

Recency filter

Location filter

Filter Usage Cheatsheet

Parameters

Response Shape

Pricing

Limits / Quotas

Next Steps

Fetch URL Content

People Search

Agent API Effort Levels

API Reference

​Overview

​Configuring Search

​Search Type

​Token Budgets

​Number of Results

​Filters

​Domain filter

​Recency filter

​Location filter

​Filter Usage Cheatsheet

​Parameters

​Response Shape

​Pricing

​Limits / Quotas

​Next Steps

Fetch URL Content

People Search

Agent API Effort Levels

API Reference

Overview

Configuring Search

Search Type

Token Budgets

Number of Results

Filters

Domain filter

Recency filter

Location filter

Filter Usage Cheatsheet

Parameters

Response Shape

Pricing

Limits / Quotas

Next Steps