Perplexity API & Developer Guide: Search-Grounded AI From Setup to Production (2026)

Last verified: May 7, 2026  ·  Format: Guide  ·  Est. time: 20-25 min

Perplexity's API gives you programmatic access to something no other major AI provider offers natively: search-grounded responses with inline citations. Every answer the Sonar models return comes with URLs pointing to the web sources that informed the response. If you have built applications that chain an LLM call with a separate search API, then parse and inject results into context, Perplexity collapses that entire pipeline into a single API call.

The Sonar model family spans four tiers: a lightweight model for quick factual lookups, a pro model for complex multi-source queries, a reasoning model with chain-of-thought for analytical tasks, and a deep research model that conducts exhaustive multi-step searches. This guide walks through every step from API key generation to production deployment, covering search-grounded completions, structured JSON output, domain filtering, and the cost and rate limit decisions that determine whether your integration runs efficiently at scale.

What You Need Before Starting

Perplexity's Sonar API is accessed through their developer console at console.perplexity.ai. You will need an account, an API key, and either the OpenAI SDK (which works out of the box) or direct REST calls. The Sonar API follows the OpenAI chat completions format with Bearer token authentication at the base URL https://api.perplexity.ai.

Step 1: Get Your API Key and Configure Authentication

Start at console.perplexity.ai. Create an account if you do not have one, then navigate to the API Keys section. Generate a new key, give it a descriptive name, and copy it immediately. You will not see the full key again after leaving the page.

Set the environment variable

macOS / Linux:

export PERPLEXITY_API_KEY="your_api_key_here"

Windows (PowerShell):

$env:PERPLEXITY_API_KEY = "your_api_key_here"

For persistence, add the export to your shell profile (.bashrc, .zshrc) or use a .env file with a library like python-dotenv.

Authentication format

All API requests use Bearer token authentication via the Authorization header:

Authorization: Bearer YOUR_API_KEY

The Sonar API base URL is https://api.perplexity.ai. The chat completions endpoint follows the OpenAI-compatible format at POST /v1/chat/completions.

Step 2: Send Your First Search-Grounded Request

The Sonar API's chat completions endpoint accepts messages in the same format as OpenAI's API. The key difference: every response includes a citations array with URLs to the web sources that grounded the answer.

cURL example

curl -X POST \
  "https://api.perplexity.ai/v1/chat/completions" \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sonar",
    "messages": [
      {
        "role": "system",
        "content": "You are a technical research "
                   "assistant. Be precise and "
                   "cite sources."
      },
      {
        "role": "user",
        "content": "What are the current rate "
                   "limits for the OpenAI API?"
      }
    ]
  }'

Python example (using OpenAI SDK)

Because the Sonar API is OpenAI-compatible, you can use the OpenAI Python SDK by changing the base URL:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["PERPLEXITY_API_KEY"],
    base_url="https://api.perplexity.ai"
)

response = client.chat.completions.create(
    model="sonar",
    messages=[
        {
            "role": "user",
            "content": "What are the latest changes "
                       "to the Python packaging "
                       "ecosystem?"
        }
    ]
)

print(response.choices[0].message.content)
# Response includes inline citations [1], [2]
# Citations array in response metadata

Understanding citations

The response includes a citations field: an array of URLs that the model referenced when generating its answer. The response text contains numbered references (e.g., [1], [2]) that map to positions in this array. This is the core differentiator: you get verifiable, source-attributed answers without building a separate retrieval pipeline.

Step 3: Choose the Right Sonar Model

According to Perplexity, the Sonar family includes four models, each targeting a different complexity and cost profile.

Source: Perplexity API Pricing (May 2026)

Beyond token costs, each model incurs per-request fees based on search context size (Low, Medium, or High). Sonar starts at $5 per 1,000 requests (Low context) and scales to $12 (High context). Sonar Pro ranges from $6 to $14 per 1,000 requests. According to Perplexity, Sonar Pro also supports Pro Search modes (fast, pro, auto) with higher per-request fees ($14-$22 per 1,000 requests).

Decision heuristic: Start with sonar for prototyping and simple lookups. Upgrade to sonar-pro when you need multi-source synthesis or follow-up conversation support. Use sonar-reasoning-pro for analytical tasks requiring step-by-step logic. Reserve sonar-deep-research for comprehensive research reports where thoroughness matters more than latency.

Step 4: Control Search Behavior With Filters

The Sonar API provides parameters that control how the underlying search operates, which directly affects the quality and relevance of grounded responses.

Domain filtering

Restrict searches to specific domains using search_domain_filter:

response = client.chat.completions.create(
    model="sonar",
    messages=[
        {
            "role": "user",
            "content": "What are the latest "
                       "Kubernetes security "
                       "best practices?"
        }
    ],
    extra_body={
        "search_domain_filter": [
            "kubernetes.io",
            "cncf.io",
            "github.com"
        ]
    }
)

This ensures citations only come from the specified domains, useful for compliance, medical, legal, or technical documentation use cases.

Recency filtering

Control how recent the search results should be with search_recency_filter:

response = client.chat.completions.create(
    model="sonar-pro",
    messages=[
        {
            "role": "user",
            "content": "What AI regulations were "
                       "announced this week?"
        }
    ],
    extra_body={
        "search_recency_filter": "week"
    }
)

Accepted values include hour, day, week, and month. For rapidly evolving topics like AI news, security advisories, or market data, recency filtering prevents stale information from contaminating responses.

Search context size

The search_context_size parameter controls how much search context the model ingests. Options are low, medium, and high. Higher context means more thorough grounding but increases per-request cost. Use low for simple factual lookups and high for research-grade queries.

Related questions and images

Two additional parameters expand what comes back in the response:

• return_related_questions: Returns suggested follow-up queries, useful for building conversational research interfaces
• return_images: Includes relevant images in the response, useful for visual content aggregation

Step 5: Request Structured JSON Output

For applications that need machine-parseable responses, the Sonar API supports structured output via the response_format parameter with JSON Schema.

response = client.chat.completions.create(
    model="sonar-pro",
    messages=[
        {
            "role": "user",
            "content": "Compare the pricing of "
                       "the top 3 cloud GPU "
                       "providers for A100 "
                       "instances."
        }
    ],
    extra_body={
        "response_format": {
            "type": "json_schema",
            "json_schema": {
                "name": "gpu_pricing",
                "schema": {
                    "type": "object",
                    "properties": {
                        "providers": {
                            "type": "array",
                            "items": {
                                "type": "object",
                                "properties": {
                                    "name": {
                                        "type": "string"
                                    },
                                    "hourly_rate": {
                                        "type": "number"
                                    },
                                    "gpu_model": {
                                        "type": "string"
                                    }
                                },
                                "required": [
                                    "name",
                                    "hourly_rate",
                                    "gpu_model"
                                ]
                            }
                        }
                    },
                    "required": ["providers"]
                }
            }
        }
    }
)

According to Perplexity, schema names must be 1-64 alphanumeric characters, and new schemas may experience 10-30 second delays on first use due to preparation. Responses match the specified format unless the output exceeds max_tokens.

One important caveat: according to Perplexity, requesting links as part of a JSON response may not work reliably. For verifiable URLs, use the citations field from the response metadata rather than asking the model to embed URLs in the JSON output.

Step 6: Use the Agent API for Multi-Provider Workflows

The Agent API (POST https://api.perplexity.ai/v1/agent) offers a higher-level interface that supports multiple AI providers, built-in tool use, and multi-step research workflows.

import requests
import os

api_key = os.environ["PERPLEXITY_API_KEY"]

response = requests.post(
    "https://api.perplexity.ai/v1/agent",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    },
    json={
        "input": "Research the current state "
                 "of WebAssembly adoption in "
                 "production environments.",
        "preset": "pro-search",
        "tools": [
            {
                "type": "web_search",
                "config": {
                    "filters": {
                        "domains": [
                            "github.com",
                            "stackoverflow.com",
                            "developer.mozilla.org"
                        ]
                    }
                }
            }
        ],
        "reasoning": {
            "effort": "high"
        },
        "max_steps": 5
    }
)

The Agent API supports three presets: fast-search for quick lookups, pro-search for thorough multi-source queries, and deep-research for exhaustive investigations with up to 10 research loop iterations.

Tool costs on the Agent API are separate from model token costs: web_search costs $0.005 per invocation and fetch_url costs $0.0005 per invocation, according to Perplexity's pricing page.

Key Agent API features

• Model fallback chains: The models parameter accepts up to 5 models for automatic failover if your primary model is unavailable
• Reasoning effort: Configurable at low, medium, or high via the reasoning object
• Custom functions: Define your own tools alongside built-in web_search, finance_search, and fetch_url
• Cost tracking: The response usage object includes a cost breakdown in USD covering input, output, cache operations, and tool invocations

Step 7: Handle Streaming and Real-Time Output

For chat interfaces or long-form generation, enable streaming to receive tokens as they are generated:

response = client.chat.completions.create(
    model="sonar",
    messages=[
        {
            "role": "user",
            "content": "Explain the differences "
                       "between gRPC and "
                       "REST APIs."
        }
    ],
    stream=True
)

for chunk in response:
    delta = chunk.choices[0].delta
    if delta.content:
        print(delta.content,
              end="", flush=True)

The Agent API supports streaming via Server-Sent Events (SSE) with typed event discriminators:

• response.output_text.delta for incremental text output
• response.reasoning.search_queries for search activity visibility
• response.reasoning.search_results for incoming search data
• response.completed for final status

Step 8: Deploy to Production

Moving from prototype to production requires attention to rate limits, error handling, and cost control.

Rate limits by tier

According to Perplexity, accounts progress through six tiers based on cumulative spending:

Source: Perplexity Rate Limits (May 2026)

Sonar Deep Research has significantly lower limits: 5 RPM at Tier 0, scaling to 100 RPM at Tier 5. The rate limiting system uses a leaky bucket algorithm that permits burst capacity while enforcing sustained rate control. Plan your architecture accordingly if deep research is a core workflow.

Error handling

import time

def query_perplexity(prompt, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = client.chat.completions.create(
                model="sonar",
                messages=[
                    {"role": "user",
                     "content": prompt}
                ]
            )
            return response.choices[0].message.content
        except Exception as e:
            if "429" in str(e):
                wait = 2 ** attempt
                time.sleep(wait)
                continue
            elif "401" in str(e):
                raise ValueError(
                    "Invalid API key"
                )
            else:
                raise
    raise RuntimeError(
        "Max retries exceeded"
    )

Cost optimization checklist

• Use sonar for simple lookups ($1/M tokens input) and reserve sonar-pro ($3/M input, $15/M output) for complex queries
• Set search_context_size to low when full grounding is not critical to reduce per-request fees
• Set max_tokens to the minimum needed for your use case
• Cache responses for repeated queries to avoid redundant search costs
• Monitor usage via the Perplexity console dashboard
• Use the Agent API's cost field in response usage to track per-request spend

Troubleshooting and FAQ

Next Step

Build a research automation pipeline. Pick a domain your team monitors (security advisories, regulatory changes, competitor product launches), wire up sonar-pro with domain filtering and recency controls, and output structured JSON to a database or notification system. This exercise demonstrates the full value of search-grounded AI: automated, source-attributed intelligence gathering that would otherwise require manual research.