Quickstart

Generating an API Key

Get your Perplexity API Key

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

See the API Groups page to learn more about API groups.

Overview

The Perplexity API provides five APIs for different use cases: Agent API for accessing OpenAI, Anthropic, Google, and xAI models with unified search tools and transparent pricing, Search for ranked web search results, Sonar for web-grounded AI responses with Sonar models, Browser for remote browser automation, and Embeddings for generating text embeddings. All APIs support both REST and SDK access with streaming, filtering, and advanced controls.

Available APIs

Agent API

Third-party models from OpenAI, Anthropic, Google, and more with presets and web search tools.

Search

Ranked web search results with filtering, multi-query support, and domain controls.

Sonar

Web-grounded AI responses with citations, conversation context, and streaming support.

Browser

Remote browser automation via Chrome DevTools Protocol (CDP).

Embeddings

Generate high-quality text embeddings for semantic search and RAG.

Choosing the Right API

Use the Agent API when...

You need multi-provider access to OpenAI, Anthropic, Google, and more models through one API
You want granular control over model selection, reasoning, token budgets, and tools
You want presets for common use configurations or full customization for advanced workflows

Best for: Agentic workflows, custom AI applications, multi-model experimentation

Use the Search API when...

You need raw search results without LLM processing
You want to build custom AI workflows with your own models
You need search data for indexing, analysis, or training

Best for: Custom AI pipelines, data collection, search integration

Use the Sonar API when...

You want Perplexity’s Sonar models optimized for research and Q&A
You need built-in citations and conversation context
You prefer simplicity—just send a message and get a researched answer

Best for: AI assistants, research tools, Q&A applications

Installation

Install the SDK for your preferred language:

pip install perplexityai

npm install @perplexity-ai/perplexity_ai

Authentication

Set your API key as an environment variable:

macOS/Linux
Windows

export PERPLEXITY_API_KEY="your_api_key_here"

setx PERPLEXITY_API_KEY "your_api_key_here"

OpenAI SDK Compatible: Perplexity’s API supports the OpenAI Chat Completions format. You can use OpenAI client libraries by pointing to our endpoint. See the OpenAI Compatibility Guide for examples.

Making Your First API Call

Choose your API based on your use case:

Agent API
Search API
Sonar API

Use for third-party models with web search tools and presets:

from perplexity import Perplexity

# Initialize the client (uses PERPLEXITY_API_KEY environment variable)
client = Perplexity()

# Make the API call with a preset
response = client.responses.create(
    preset="pro-search",
    input="What are the latest developments in AI?"
)

# Print the AI's response
print(response.output_text)

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

// Initialize the client (uses PERPLEXITY_API_KEY environment variable)
const client = new Perplexity();

// Make the API call with a preset
const response = await client.responses.create({
    preset: "pro-search",
    input: "What are the latest developments in AI?"
});

// Print the AI's response
console.log(response.output_text);

curl https://api.perplexity.ai/v1/responses \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "preset": "pro-search",
    "input": "What are the latest developments in AI?"
  }' | jq

Example Response

The response includes structured output with tool usage and citations:

{
  "background": false,
  "completed_at": 1756485272,
  "created_at": 1756485272,
  "error": null,
  "frequency_penalty": 0,
  "id": "resp_1234567890",
  "incomplete_details": null,
  "instructions": "## Abstract\n<role>\nYou are an AI assistant developed by Perplexity AI. Given a user's query, your goal is to...",
  "max_output_tokens": null,
  "max_tool_calls": null,
  "metadata": {},
  "model": "openai/gpt-5.1",
  "object": "response",
  "output": [
    {
      "type": "message",
      "id": "msg_abc123",
      "role": "assistant",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "text": "Recent developments in AI include...",
          "annotations": [
            {
              "type": "citation",
              "url": "https://example.com/article1"
            }
          ],
          "logprobs": []
        }
      ]
    }
  ],
  "parallel_tool_calls": true,
  "presence_penalty": 0,
  "previous_response_id": null,
  "prompt_cache_key": null,
  "reasoning": null,
  "safety_identifier": null,
  "service_tier": "default",
  "status": "completed",
  "store": true,
  "temperature": 1,
  "text": {
    "format": {
      "type": "text"
    }
  },
  "tool_choice": "auto",
  "tools": [
    {
      "type": "web_search"
    },
    {
      "type": "fetch_url"
    }
  ],
  "top_logprobs": 0,
  "top_p": 1,
  "truncation": "disabled",
  "usage": {
    "cost": {
      "currency": "USD",
      "input_cost": 0.0046,
      "output_cost": 0.0078,
      "tool_calls_cost": 0.005,
      "total_cost": 0.0174
    },
    "input_tokens": 3681,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 780,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "tool_calls_details": {
      "search_web": {
        "invocation": 1
      }
    },
    "total_tokens": 4461
  },
  "user": null
}

Use for ranked web search results without LLM processing:

from perplexity import Perplexity

# Initialize the client (uses PERPLEXITY_API_KEY environment variable)
client = Perplexity()

# Make the API call
search = client.search.create(
    query="latest AI developments 2024",
    max_results=5
)

# Print the search results
for result in search.results:
    print(f"{result.title}: {result.url}")

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

// Initialize the client (uses PERPLEXITY_API_KEY environment variable)
const client = new Perplexity();

// Make the API call
const search = await client.search.create({
    query: "latest AI developments 2024",
    max_results: 5
});

// Print the search results
for (const result of search.results) {
    console.log(`${result.title}: ${result.url}`);
}

curl -X POST 'https://api.perplexity.ai/search' \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "latest AI developments 2024",
    "max_results": 5
  }' | jq

Example Response

The response includes ranked search results with titles, URLs, and snippets:

{
  "results": [
    {
      "title": "2024: A year of extraordinary progress in AI",
      "url": "https://example.com/ai-progress-2024",
      "snippet": "2024 was a year of experimenting, fast shipping, and putting our latest technologies in the hands of developers...",
      "date": "2024-12-15",
      "last_updated": "2024-12-20"
    },
    {
      "title": "Latest AI Developments and Breakthroughs",
      "url": "https://example.com/ai-breakthroughs",
      "snippet": "Recent advances in AI include new models, improved performance on benchmarks, and practical applications...",
      "date": "2024-11-30",
      "last_updated": "2024-12-10"
    }
  ],
  "query_info": {
    "query": "latest AI developments 2024",
    "normalized_query": "latest ai developments 2024"
  }
}

Use for web-grounded AI responses with Perplexity’s Sonar models:

from perplexity import Perplexity

# Initialize the client (uses PERPLEXITY_API_KEY environment variable)
client = Perplexity()

# Make the API call
completion = client.chat.completions.create(
    model="sonar-pro",
    messages=[
        {"role": "user", "content": "What are the latest developments in AI?"}
    ]
)

# Print the AI's response
print(completion.choices[0].message.content)

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

// Initialize the client (uses PERPLEXITY_API_KEY environment variable)
const client = new Perplexity();

// Make the API call
const completion = await client.chat.completions.create({
    model: "sonar-pro",
    messages: [
        { role: "user", content: "What are the latest developments in AI?" }
    ]
});

// Print the AI's response
console.log(completion.choices[0].message.content);

curl https://api.perplexity.ai/chat/completions \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sonar-pro",
    "messages": [
      {
        "role": "user",
        "content": "What are the latest developments in AI?"
      }
    ]
  }' | jq

Example Response

The response includes the AI’s answer with citations and search results:

{
  "id": "66f3900f-e32e-4d59-b677-1a55de188262",
  "model": "sonar-pro",
  "created": 1756485272,
  "object": "chat.completion",
  "choices": [
    {
      "index": 0,
      "finish_reason": "stop",
      "message": {
        "role": "assistant",
        "content": "Recent developments in AI include...[1][2]"
      }
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 315,
    "total_tokens": 327
  },
  "citations": [
    "https://example.com/article1",
    "https://example.com/article2"
  ]
}

Streaming Responses

Enable streaming for real-time output with either API:

Agent API
Sonar API

from perplexity import Perplexity

client = Perplexity()

# Make the streaming API call
stream = client.responses.create(
    preset="pro-search",
    input="Explain quantum computing",
    stream=True
)

# Process the streaming response
for chunk in stream:
    if chunk.type == "response.output_text.delta":
        print(chunk.delta, end="", flush=True)

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

const client = new Perplexity();

// Make the streaming API call
const stream = await client.responses.create({
    preset: "pro-search",
    input: "Explain quantum computing",
    stream: true
});

// Process the streaming response
for await (const chunk of stream) {
    if (chunk.type === "response.output_text.delta") {
        process.stdout.write(chunk.delta);
    }
}

curl https://api.perplexity.ai/v1/responses \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "preset": "pro-search",
    "input": "Explain quantum computing",
    "stream": true
  }'

from perplexity import Perplexity

client = Perplexity()

# Make the streaming API call
stream = client.chat.completions.create(
    model="sonar-pro",
    messages=[
        {"role": "user", "content": "Explain quantum computing"}
    ],
    stream=True
)

# Process the streaming response
for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

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

const client = new Perplexity();

// Make the streaming API call
const stream = await client.chat.completions.create({
    model: "sonar-pro",
    messages: [
        { role: "user", content: "Explain quantum computing" }
    ],
    stream: true
});

// Process the streaming response
for await (const chunk of stream) {
    if (chunk.choices[0]?.delta?.content) {
        process.stdout.write(chunk.choices[0].delta.content);
    }
}

curl https://api.perplexity.ai/chat/completions \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sonar-pro",
    "messages": [
      {
        "role": "user",
        "content": "Explain quantum computing"
      }
    ],
    "stream": true
  }'

For a full guide on streaming, including parsing, error handling, citation management, and best practices, see our streaming guide.

Next Steps

Now that you’ve made your first API call, explore each API in depth:

Agent API

Get started with third-party models and presets

Search API

Get started with web search results

Sonar API

Get started with web-grounded AI responses

Browser API

Get started with browser automation

Embeddings API

Get started with text embeddings

Perplexity SDK

Learn about the official Perplexity SDK with type safety and async support

Models

Explore available models and their capabilities

API Reference

View complete API documentation with detailed endpoint specifications

Examples

Explore code examples, tutorials, and integration patterns

Need help? Check out our community for support and discussions with other developers.

Getting Started

Perplexity SDK

Agent API

Search API

Sonar API

Browser API

Embeddings API

Admin & Management

Resources

Generating an API Key

Get your Perplexity API Key

Overview

Available APIs

Agent API

Search

Sonar

Browser

Embeddings

Choosing the Right API

Installation

Authentication

Making Your First API Call

Streaming Responses

Next Steps

Agent API

Search API

Sonar API

Browser API

Embeddings API

Perplexity SDK

Models

API Reference

Examples

​Generating an API Key

Get your Perplexity API Key

​Overview

​Available APIs

Agent API

Search

Sonar

Browser

Embeddings

​Choosing the Right API

​Installation

​Authentication

​Making Your First API Call

​Streaming Responses

​Next Steps

Agent API

Search API

Sonar API

Browser API

Embeddings API

Perplexity SDK

Models

API Reference

Examples

Generating an API Key

Overview

Available APIs

Choosing the Right API

Installation

Authentication

Making Your First API Call

Streaming Responses

Next Steps