Skip to main content

​
Overview

The Agentic Research API provides two powerful tools that third-party models can use to access real-time web information:
  • web_search - Performs web searches to retrieve current information with advanced filtering options
  • fetch_url - Fetches and extracts content from specific URLs
Tools must be explicitly configured in your API request. Once enabled, models can autonomously decide when to use them based on your instructions. The web_search tool allows models to perform web searches with all the filtering capabilities of the Search API.

​
Pricing

Web search pricing is **5.00per1,000searchcalls∗∗(5.00 per 1,000 search calls** (0.005 per search). Additionally, you are charged for the tokens consumed when search results are embedded in the model’s context. For full pricing details, see our Pricing page. Cost Example: If a model makes 3 web searches and receives 1,800 tokens of search results, plus your original 100-token query, using openai/gpt-5.2:
  • Tool calls: 3 searches × 0.005=0.005 = 0.015
  • Input tokens: 1,900 tokens × (1.75/1M)=1.75 / 1M) = 0.003325
  • Output tokens: 300 tokens × (14.00/1M)=14.00 / 1M) = 0.0042
  • Total cost: $0.022525

​
Basic Usage

from perplexity import Perplexity

client = Perplexity()

response = client.responses.create(
    model="openai/gpt-5.2",
    input="What are the latest developments in quantum computing?",
    tools=[
        {
            "type": "web_search"
        }
    ],
    instructions="You have access to a web_search tool. Use it for current information."
)


print(response.output_text)

​
Search Filters

The web_search tool supports all Search API filters. Configure them in the filters object within the tool definition.

​
Available Filters

FilterTypeDescriptionLimit
search_domain_filterArray of stringsFilter by specific domains (allowlist or denylist with - prefix)Max 20 domains
search_language_filterArray of stringsFilter by ISO 639-1 language codesMax 10 languages
search_recency_filterStringFilter by time period: "day", "week", "month", "year"-
search_after_dateStringFilter results published after this date (format: "M/D/YYYY")-
search_before_dateStringFilter results published before this date (format: "M/D/YYYY")-
last_updated_after_filterStringFilter results last updated after this date (format: "M/D/YYYY")-
last_updated_before_filterStringFilter results last updated before this date (format: "M/D/YYYY")-

​
Examples with Filters

​
Domain Filtering

Filter search results to specific trusted sources: 
from perplexity import Perplexity

client = Perplexity()

response = client.responses.create(
    model="openai/gpt-5.2",
    input="What are the latest climate change findings?",
    tools=[
        {
            "type": "web_search",
            "filters": {
                "search_domain_filter": [
                    "nature.com",
                    "science.org",
                    ".gov",
                    ".edu"
                ]
            }
        }
    ],
    instructions="Use web_search to find recent academic and governmental sources."
)


print(response.output_text)

​
Language Filtering

Search across multiple languages: 
from perplexity import Perplexity

client = Perplexity()

response = client.responses.create(
    model="openai/gpt-5.2",
    input="What are European perspectives on AI regulation?",
    tools=[
        {
            "type": "web_search",
            "filters": {
                "search_language_filter": ["en", "fr", "de", "es"]
            }
        }
    ],
    instructions="Search for content in English, French, German, and Spanish."
)


print(response.output_text)

​
Recency Filtering

Filter by time period for recent information: 
from perplexity import Perplexity

client = Perplexity()

response = client.responses.create(
    model="openai/gpt-5.2",
    input="What are the latest tech industry layoffs?",
    tools=[
        {
            "type": "web_search",
            "filters": {
                "search_recency_filter": "week"
            }
        }
    ],
    instructions="Search for news from the past week only."
)


print(response.output_text)

​
Date Range Filtering

Filter by specific publication dates: 
from perplexity import Perplexity

client = Perplexity()

response = client.responses.create(
    model="openai/gpt-5.2",
    input="What happened in AI during Q1 2025?",
    tools=[
        {
            "type": "web_search",
            "filters": {
                "search_after_date_filter": "1/1/2025",
                "search_before_date_filter": "3/31/2025"
            }
        }
    ],
    instructions="Search for content published in Q1 2025."
)


print(response.output_text)

​
Combining Multiple Filters

Combine filters for precise control: 
from perplexity import Perplexity

client = Perplexity()

response = client.responses.create(
    model="openai/gpt-5.2",
    input="What are recent academic findings on renewable energy?",
    tools=[
        {
            "type": "web_search",
            "filters": {
                "search_domain_filter": [
                    "nature.com",
                    "science.org",
                    ".edu"
                ],
                "search_language_filter": ["en"],
                "search_recency_filter": "month"
            }
        }
    ],
    instructions="Search for recent English-language academic publications."
)


print(response.output_text)

​
User Location

Configure user location for localized search results: 
from perplexity import Perplexity

client = Perplexity()

response = client.responses.create(
    model="openai/gpt-5.2",
    input="What are local news headlines?",
    tools=[
        {
            "type": "web_search",
            "user_location": {
                "latitude": 37.7749,
                "longitude": -122.4194,
                "country": "US",
                "city": "San Francisco",
                "region": "CA"
            }
        }
    ],
    instructions="Search for local news in the San Francisco area."
)


print(response.output_text)

​
Token Control

Control the amount of content retrieved per search result: 
from perplexity import Perplexity

client = Perplexity()

response = client.responses.create(
    model="openai/gpt-5.2",
    input="Summarize recent AI breakthroughs",
    tools=[
        {
            "type": "web_search",
            "max_tokens_per_page": 1024  # Limit tokens per result
        }
    ],
    instructions="Search and summarize concisely."
)


print(response.output_text)

​
Tool: fetch_url

The fetch_url tool fetches and extracts content from specific URLs provided by the model.

​
Pricing

URL fetch pricing is **0.50per1,000requests∗∗(0.50 per 1,000 requests** (0.0005 per fetch). Additionally, you are charged for the tokens consumed when fetched content is embedded in the model’s context. For full pricing details, see our Pricing page. Cost Example: If a model fetches 2 URLs with 3,000 tokens of content, plus your original 80-token query, using anthropic/claude-sonnet-4-5:
  • Tool calls: 2 fetches × 0.0005=0.0005 = 0.001
  • Input tokens: 3,080 tokens × (3.00/1M)=3.00 / 1M) = 0.009240
  • Output tokens: 500 tokens × (15.00/1M)=15.00 / 1M) = 0.0075
  • Total cost: $0.01774

​
Basic Usage

from perplexity import Perplexity

client = Perplexity()

response = client.responses.create(
    model="openai/gpt-5.2",
    input="Summarize the content at https://example.com/article",
    tools=[
        {
            "type": "fetch_url"
        }
    ],
    instructions="Use fetch_url to retrieve and summarize the article."
)


print(response.output_text)

​
Use Cases

  • Article Summarization: Fetch and summarize specific articles or blog posts
  • Documentation Analysis: Extract and analyze technical documentation
  • Content Comparison: Compare content from multiple specific URLs
  • URL Validation: Verify content at specific URLs before sharing

​
Combining Both Tools

Use both tools together for comprehensive information gathering: 
from perplexity import Perplexity

client = Perplexity()

response = client.responses.create(
    model="openai/gpt-5.2",
    input="Find recent articles about quantum computing and summarize the top result",
    tools=[
        {
            "type": "web_search",
            "filters": {
                "search_recency_filter": "week"
            }
        },
        {
            "type": "fetch_url"
        }
    ],
    instructions="First use web_search to find recent articles, then use fetch_url to retrieve the full content of the most relevant article and provide a detailed summary."
)


print(response.output_text)

​
Best Practices

​
Effective Instructions

Provide clear instructions to guide tool usage: 
instructions = """You have access to web_search and fetch_url tools.

Use web_search when:
- You need current information or recent news
- The query requires multiple sources
- You need to find specific domains or publications

Use fetch_url when:
- You need detailed content from a specific URL
- You want to analyze a particular article or document
- You need to verify specific claims from a URL

Keep searches focused and relevant to the user's question."""

​
Filter Selection

  • Domain Filtering: Use for trusted sources or to exclude low-quality sites
  • Language Filtering: Essential for multilingual research or regional content
  • Recency Filtering: Best for news, trends, and time-sensitive information
  • Date Range Filtering: Ideal for historical research or specific time periods

​
Cost Management

  • Minimize tool calls: web_search costs 0.005/call,‘fetchurl‘costs0.005/call, `fetch_url` costs 0.0005/call
  • Set max_tokens_per_page: Control the token costs of search results embedded in context
  • Use specific filters: Reduce unnecessary searches with precise filtering
  • Combine filters: Narrow results to the most relevant content, reducing both tool calls and token consumption

​
Next Steps

Agentic Research API Quickstart

Get started with the Agentic Research API

Presets

Use pre-configured presets with built-in tools

Search API

Learn more about search filters and capabilities

Models

Explore available third-party models