Skip to main content

​
Why Use the Agentic Research API?

Multi-Provider Access

Access OpenAI, Anthropic, Google, xAI, and more through one unified API, no need to manage multiple API keys.

Transparent Pricing

See exact token counts and costs per request, no markup, just direct provider pricing.

Granular Control

Change models, reasoning, tokens, and tools with consistent syntax.
We recommend using our official SDKs for a more convenient and type-safe way to interact with the Agentic Research API.

​
Installation

Install the SDK for your preferred language: 
pip install perplexityai

​
Authentication

Set your API key as an environment variable. The SDK will automatically read it: 
export PERPLEXITY_API_KEY="your_api_key_here"
Or use a .env file in your project:
.env
PERPLEXITY_API_KEY=your_api_key_here
All SDK examples below automatically use the PERPLEXITY_API_KEY environment variable. You can also pass the key explicitly if needed.

​
Generating an API Key

Get your Perplexity API Key

Navigate to the API Keys tab in the API Portal and generate a new key.

​
Basic Usage

Convenience Property: Both Python and TypeScript SDKs provide an output_text property that aggregates all text content from response outputs. Instead of iterating through response.output, simply use response.output_text for cleaner code.

​
Using a Third-Party Model

Use third-party models from OpenAI, Anthropic, Google, X.AI, and other providers for specific capabilities: 
from perplexity import Perplexity

client = Perplexity()

# Using a third-party model
response = client.responses.create(
    model="openai/gpt-5.2",
    input="What are the latest developments in AI?",
    tools=[{"type": "web_search"}],
    instructions="You have access to a web_search tool. Use it for questions about current events, news, or recent developments. Use 1 query for simple questions. Keep queries brief: 2-5 words. NEVER ask permission to search - just search when appropriate",
)

print(f"Response ID: {response.id}")
print(response.output_text)

​
Using a Preset

Presets provide optimized defaults for specific use cases. Start with a preset for quick setup: 
from perplexity import Perplexity

client = Perplexity()

# Using a preset (e.g., pro-search)
response = client.responses.create(
    preset="pro-search",
    input="What are the latest developments in AI?",
)

print(f"Response ID: {response.id}")
print(response.output_text)

​
With Web Search Tool

Enable web search capabilities using the web_search tool: 
from perplexity import Perplexity

client = Perplexity()

response = client.responses.create(
    model="openai/gpt-5.2",
    input="What's the weather in San Francisco?",
    tools=[
        {
            "type": "web_search"
        }
    ],
    instructions="You have access to a web_search tool. Use it when you need current information.",
)

if response.status == "completed":
    print(response.output_text)

​
Input Formats

The input parameter accepts either a string or an array of message objects.

​
String Input

Simple string input for straightforward queries: 
from perplexity import Perplexity

client = Perplexity()

response = client.responses.create(
    model="openai/gpt-5.2",
    input="What are the latest AI developments?",
)

​
Message Array Input

Use message arrays for multi-turn conversations: 
from perplexity import Perplexity

client = Perplexity()

response = client.responses.create(
    model="openai/gpt-5.2",
    input=[
        {"type": "message", "role": "system", "content": "You are a helpful assistant."},
        {"type": "message", "role": "user", "content": "What are the latest AI developments?"},
    ],
    instructions="Provide detailed, well-researched answers.",
)

​
Instructions Parameter

The instructions parameter provides system instructions or guidelines for the model. This is particularly useful for:
  • Tool usage instructions: Guide the model on when and how to use available tools
  • Response style guidelines: Control the tone and format of responses
  • Behavior constraints: Set boundaries and constraints for model behavior
Example with tool instructions: 
response = client.responses.create(
    model="openai/gpt-5.2",
    input="What are the latest developments in AI?",
    instructions="You have access to a web_search tool. Use it for questions about current events, news, or recent developments. Use 1 query for simple questions. Keep queries brief: 2-5 words. NEVER ask permission to search - just search when appropriate",
    tools=[{"type": "web_search"}],
)

​
Tools

The Agentic Research API provides two powerful tools for accessing real-time web information:
  • web_search - Performs web searches to retrieve current information and news
  • fetch_url - Fetches and extracts content from specific URLs
The web_search tool can optionally include user location for localized results: 
response = client.responses.create(
    model="openai/gpt-5.2",
    input="What are the latest news in San Francisco?",
    tools=[
        {
            "type": "web_search",
            "user_location": {
                "latitude": 37.7749,
                "longitude": -122.4194,
                "country": "US",
                "city": "San Francisco",
                "region": "CA"
            }
        }
    ],
    instructions="Use web_search to find current information.",
)

​
Generation Parameters

Control response generation with standard parameters: 
response = client.responses.create(
    model="openai/gpt-5.2",
    input="Explain quantum computing",
    max_output_tokens=1000,  # Maximum tokens to generate
)

​
Reasoning Effort

Control the reasoning effort level for reasoning models:
  • low: Minimal reasoning effort
  • medium: Moderate reasoning effort
  • high: Maximum reasoning effort
The reasoning parameter is only supported by models with reasoning capabilities. Models without reasoning support will ignore this parameter.
response = client.responses.create(
    model="openai/gpt-5.2",
    input="Solve this complex problem step by step",
    reasoning={
        "effort": "high"  # Use maximum reasoning
    },
)

​
Streaming Responses

The Agentic Research API supports streaming responses using Server-Sent Events (SSE). Enable streaming by setting stream=True: 
response = client.responses.create(
    model="openai/gpt-5.2",
    input="Explain quantum computing in detail",
    stream=True,
)

# Process streaming response
for chunk in response:
    if chunk.type == "response.output_text.delta":
        print(chunk.delta, end="", flush=True)
    elif chunk.type == "response.completed":
        print(f"\n\nResponse completed: {chunk.response.output_text}")
For comprehensive streaming documentation, see the Streaming Guide.

​
Error Handling

Handle errors gracefully: 
from perplexity import Perplexity, APIError

try:
    response = client.responses.create(
        model="openai/gpt-5.2",
        input="What is AI?",
    )

    if response.status == "completed":
        print(response.output_text)
    elif response.status == "failed":
        if response.error:
            print(f"Error: {response.error.message}")

except APIError as e:
    print(f"API Error: {e.message}")
    print(f"Status Code: {e.status_code}")

​
Response Structure

Responses from the Agentic Research API have a structured format:
{
    "id": "resp_1234567890",
    "object": "response",
    "created_at": 1234567890,
    "model": "openai/gpt-5.2",
    "status": "completed",
    "output": [
        {
            "type": "message",
            "id": "msg_1234567890",
            "status": "completed",
            "role": "assistant",
            "content": [
                {
                    "type": "output_text",
                    "text": "The weather in San Francisco is currently sunny...",
                    "annotations": [
                        {
                            "type": "citation",
                            "start_index": 0,
                            "end_index": 50,
                            "url": "https://example.com/weather",
                            "title": "Weather Report"
                        }
                    ]
                }
            ]
        }
    ],
    "usage": {
        "input_tokens": 100,
        "output_tokens": 200,
        "total_tokens": 300
    }
}

​
Next Steps

Model Fallback

Specify multiple models for automatic failover and higher availability.

Presets

Explore available presets and their configurations.

Models

Explore available presets and third-party models for the Agentic Research API.

API Reference

View complete endpoint documentation and parameters.

Structured Outputs

Generate formatted responses with JSON schema or regex.

Chat Completions API

Need web-grounded responses with built-in search? Check out the Chat Completions API.

Search API

Get raw search results with the Search API.
Need help? Check out our community for support and discussions with other developers.