Agent API

Get your Perplexity API Key

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

Why Use the Agent 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 Agent API.

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. The SDK will automatically read it:

macOS/Linux
Windows

export PERPLEXITY_API_KEY="your_api_key_here"

setx 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.

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, xAI, and other providers for specific capabilities:

from perplexity import Perplexity

client = Perplexity()

response = client.responses.create(
    model="openai/gpt-5.2",
    input="Explain the difference between supervised and unsupervised learning in machine learning.",
    max_output_tokens=300,
)

print(f"Response ID: {response.id}")
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.2",
    input: "Explain the difference between supervised and unsupervised learning in machine learning.",
    max_output_tokens: 300,
});

console.log(`Response ID: ${response.id}`);
console.log(response.output_text);

curl https://api.perplexity.ai/v1/responses \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.2",
    "input": "Explain the difference between supervised and unsupervised learning in machine learning.",
    "max_output_tokens": 300
  }' | jq

Response

{
  "background": false,
  "completed_at": 1771891464,
  "created_at": 1771891464,
  "error": null,
  "frequency_penalty": 0,
  "id": "resp_f854ed0a-f0e2-4ee8-b5ea-8582956910f2",
  "incomplete_details": null,
  "instructions": null,
  "max_output_tokens": 300,
  "max_tool_calls": null,
  "metadata": {},
  "model": "openai/gpt-5.2",
  "object": "response",
  "output": [
    {
      "content": [
        {
          "annotations": [],
          "logprobs": [],
          "text": "**Supervised learning** trains a model on **labeled ...",
          "type": "output_text"
        }
      ],
      "id": "msg_f47013d2-7fe7-44d6-a7aa-4e34c85ce2b6",
      "role": "assistant",
      "status": "completed",
      "type": "message"
    }
  ],
  "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": [],
  "top_logprobs": 0,
  "top_p": 1,
  "truncation": "disabled",
  "usage": {
    "cost": {
      "currency": "USD",
      "input_cost": 4e-05,
      "output_cost": 0.00311,
      "total_cost": 0.00315
    },
    "input_tokens": 20,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 222,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 242
  },
  "user": null
}

Using a Preset

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

from perplexity import Perplexity

client = Perplexity()

response = client.responses.create(
    preset="pro-search",
    input="Compare the latest open-source LLMs released in 2025 in terms of benchmark performance, licensing, and real-world applications.",
)

print(f"Model used: {response.model}")
print(response.output_text)

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

const client = new Perplexity();

const response = await client.responses.create({
    preset: "pro-search",
    input: "Compare the latest open-source LLMs released in 2025 in terms of benchmark performance, licensing, and real-world applications.",
});

console.log(`Model used: ${response.model}`);
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": "Compare the latest open-source LLMs released in 2025 in terms of benchmark performance, licensing, and real-world applications."
  }' | jq

Response

{
  "background": false,
  "completed_at": 1771891641,
  "created_at": 1771891641,
  "error": null,
  "frequency_penalty": 0,
  "id": "resp_aca2bace-3782-4d81-be45-a82c24cfff9d",
  "incomplete_details": null,
  "instructions": "## Abstract\n<role>\nYou are an AI assistant developed by Perplexity AI...\n</role>\n...",
  "max_output_tokens": 8192,
  "max_tool_calls": null,
  "metadata": {},
  "model": "openai/gpt-5.1",
  "object": "response",
  "output": [
    {
      "queries": [
        "2025 open source LLM benchmark performance",
        "2025 newly released open source LLMs license",
        "2025 open source LLM real world use cases"
      ],
      "results": [
        {
          "date": "2025-11-19",
          "id": 1,
          "last_updated": "2026-02-23T12:12:34",
          "snippet": "updated\n\n19 Nov 2025\n\n# Open LLM Leaderboard\n\nThis LLM leaderboard displays...",
          "source": "web",
          "title": "Open LLM Leaderboard 2025",
          "url": "https://www.vellum.ai/open-llm-leaderboard"
        },
        {
          "date": "2023-05-05",
          "id": 2,
          "last_updated": "2026-01-06T09:02:43.651546",
          "snippet": "",
          "source": "web",
          "title": "A list of open LLMs available for commercial use.",
          "url": "https://github.com/eugeneyan/open-llms"
        },
        {
          "date": "2025-05-05",
          "id": 3,
          "last_updated": "2026-02-22T19:27:06",
          "snippet": "# Best Open Source LLMs You Can Run Locally in 2025\n\nRunning large language models on your own hardware is...",
          "source": "web",
          "title": "Best Open Source LLMs You Can Run Locally in 2025 - DemoDazzle",
          "url": "https://demodazzle.com/blog/open-source-llms-2025"
        },
        {
          "date": "2025-12-15",
          "id": 4,
          "last_updated": "2026-02-23T21:56:51",
          "snippet": "updated\n\n15 Dec 2025\n\n# LLM Leaderboard\n\nThis LLM leaderboard displays the latest public benchmark performance for SOTA model versions released after April 2024...",
          "source": "web",
          "title": "LLM Leaderboard 2025 - Vellum",
          "url": "https://www.vellum.ai/llm-leaderboard"
        },
        {
          "date": "2025-11-22",
          "id": 5,
          "last_updated": "2026-02-11T02:35:36",
          "snippet": "Open\u2011source Large Language Models (LLMs) have moved from niche hobby projects to a full\u2011blown industry trend in 2025...",
          "source": "web",
          "title": "Open\u2011Source LLMs 2025: GPT\u2011OSS Models & How ... - Neura AI Blog",
          "url": "https://blog.meetneura.ai/open-source-llms-2025/"
        },
        {
          "date": "2025-07-23",
          "id": 6,
          "last_updated": "2026-02-23T23:43:21",
          "snippet": "",
          "source": "web",
          "title": "55 real-world LLM applications and use cases from top ...",
          "url": "https://www.evidentlyai.com/blog/llm-applications"
        },
        {
          "date": "2025-10-29",
          "id": 7,
          "last_updated": "2026-02-23T21:22:10",
          "snippet": "",
          "source": "web",
          "title": "Top 10 open source LLMs for 2025 - NetApp Instaclustr",
          "url": "https://www.instaclustr.com/education/open-source-ai/top-10-open-source-llms-for-2025/"
        },
        {
          "date": "2025-05-21",
          "id": 8,
          "last_updated": "2026-02-23T14:54:20",
          "snippet": "Here are the details of OpenLLaMA:\n\n**Parameters:** 3B, 7B and 13B\n\n**License:** Apache 2.0...",
          "source": "web",
          "title": "The List of 11 Most Popular Open Source LLMs [2025]",
          "url": "https://www.lakera.ai/blog/open-source-llms"
        },
        {
          "date": "2026-01-07",
          "id": 9,
          "last_updated": "2026-02-23T17:41:06",
          "snippet": "",
          "source": "web",
          "title": "The state of open source AI models in 2025 | Red Hat Developer",
          "url": "https://developers.redhat.com/articles/2026/01/07/state-open-source-ai-models-2025"
        },
        {
          "date": "2025-10-28",
          "id": 10,
          "last_updated": "2026-02-23T07:53:56",
          "snippet": "- **Open source dominates by volume:** 63% of models in our dataset (59 open source vs 35 proprietary)\n- **Performance...",
          "source": "web",
          "title": "Open Source vs Proprietary LLMs: Complete 2025 Benchmark ...",
          "url": "https://whatllm.org/blog/open-source-vs-proprietary-llms-2025"
        },
        {
          "date": "2025-06-02",
          "id": 11,
          "last_updated": "2026-01-18T13:27:38.757741",
          "snippet": "",
          "source": "web",
          "title": "Top 8 Open\u2011Source LLMs to Watch in 2025 - JetRuby Agency",
          "url": "https://jetruby.com/blog/top-8-open-source-llms-to-watch-in-2025/"
        },
        {
          "date": "2026-01-26",
          "id": 12,
          "last_updated": "2026-02-23T16:49:21",
          "snippet": "",
          "source": "web",
          "title": "Best Open Source LLMs in 2026",
          "url": "https://www.keywordsai.co/blog/best-open-source-llms"
        },
        {
          "date": "2025-12-10",
          "id": 13,
          "last_updated": "2026-02-23T18:38:26",
          "snippet": "",
          "source": "web",
          "title": "Full Benchmark Table For...",
          "url": "https://skywork.ai/blog/llm/top-10-open-llms-2025-november-ranking-analysis/"
        },
        {
          "date": "2024-09-19",
          "id": 14,
          "last_updated": "2025-12-27T09:28:04.559969",
          "snippet": "## Top Open-Source LLMs of 2025\n\n### 1. LLaMA 3.1\n\n**Developer:**Meta AI **Release Date:**July 23, 2024 **Parameter Size:**405B, 70B, 8B...",
          "source": "web",
          "title": "Top 10 Open-Source LLMs in 2025 - Kite Metric",
          "url": "https://kitemetric.com/blogs/top-10-open-source-llms-in-2025-a-comprehensive-guide"
        },
        {
          "date": "2025-02-26",
          "id": 15,
          "last_updated": "2025-09-10T16:36:09.704235",
          "snippet": "Use Cases:\n\n**Advanced Chatbots:**Responsive customer support bots. **Content Creation for Marketing:**Generating product descriptions and blog posts...",
          "source": "web",
          "title": "Top 10 Open-Source LLMs in 2025 and Their Use Cases",
          "url": "https://capalearning.com/2025/02/26/top-10-open-source-llms-in-2025-and-their-use-cases/"
        }
      ],
      "type": "search_results"
    },
    {
      "contents": [
        {
          "snippet": "Hi, Camille\u2019s here! On October 28, 2025, I fell into a small rabbit hole...",
          "title": "Full Benchmark Table For...",
          "url": "https://skywork.ai/blog/llm/top-10-open-llms-2025-november-ranking-analysis/"
        },
        {
          "snippet": "# Open source vs proprietary LLMs: complete 2025 benchmark analysis\n\n## TL;DR: The state of LLMs in late 2025\n\n**The landscape has shifted dramatically:**\n\n- **Open source dominates by volume:** 63% of models in our dataset (59 open source vs 35 proprietary)\n- **Performance...",
          "title": "Open Source vs Proprietary LLMs: Complete 2025 Benchmark ...",
          "url": "https://whatllm.org/blog/open-source-vs-proprietary-llms-2025"
        }
      ],
      "type": "fetch_url_results"
    },
    {
      "content": [
        {
          "annotations": [],
          "logprobs": [],
          "text": "In 2025, the strongest open\u2011source LLMs (Qwen 2.5, Llama 3.3/3.x, DeepSeek V3\u2011series, Mixtral...",
          "type": "output_text"
        }
      ],
      "id": "msg_1140f2e2-5bdb-4be8-a4c8-9d56bf61f35f",
      "role": "assistant",
      "status": "completed",
      "type": "message"
    }
  ],
  "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": {
      "cache_read_cost": 0.00059,
      "currency": "USD",
      "input_cost": 0.00919,
      "output_cost": 0.02743,
      "tool_calls_cost": 0.0055,
      "total_cost": 0.04271
    },
    "input_tokens": 12088,
    "input_tokens_details": {
      "cache_creation_input_tokens": 0,
      "cache_read_input_tokens": 4736,
      "cached_tokens": 4736
    },
    "output_tokens": 2743,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "tool_calls_details": {
      "fetch_url": {
        "invocation": 1
      },
      "search_web": {
        "invocation": 1
      }
    },
    "total_tokens": 14831
  },
  "user": null
}

Learn more about presets to explore pre-configured setups optimized for different use cases with specific models, token limits, and tool access.

With Web Search

The Agent API provides access to a number of tools that can be used to extend the capabilities of the model. 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 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",
)

if response.status == "completed":
    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.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.",
});

if (response.status === "completed") {
    console.log(response.output_text);
}

curl https://api.perplexity.ai/v1/responses \
  -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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."
  }' | jq

Response

{
  "background": false,
  "completed_at": 1771891737,
  "created_at": 1771891737,
  "error": null,
  "frequency_penalty": 0,
  "id": "resp_367113ed-7a1b-4b2e-bad7-93e53a6cbeca",
  "incomplete_details": null,
  "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",
  "max_output_tokens": 8192,
  "max_tool_calls": null,
  "metadata": {},
  "model": "openai/gpt-5.2",
  "object": "response",
  "output": [
    {
      "queries": [
        "latest AI developments 2026"
      ],
      "results": [
        {
          "date": "2026-01-01",
          "id": 1,
          "last_updated": "2026-02-23T20:10:25",
          "snippet": "Many believe efficiency will be the new frontier...",
          "source": "web",
          "title": "The trends that will shape AI and tech in 2026 - IBM",
          "url": "https://www.ibm.com/think/news/ai-tech-trends-predictions-2026"
        },
        {
          "date": "2026-01-08",
          "id": 2,
          "last_updated": "2026-02-23T20:19:20",
          "snippet": "## What\u2019s next in AI: 7 trends to watch in 2026\n\nAI is entering a new phase, one defined by real-world impact...",
          "source": "web",
          "title": "What's next in AI: 7 trends to watch in 2026 - Microsoft Source",
          "url": "https://news.microsoft.com/source/features/ai/whats-next-in-ai-7-trends-to-watch-in-2026/"
        },
        {
          "date": "2026-01-06",
          "id": 3,
          "last_updated": "2026-02-21T02:30:13",
          "snippet": "#### Topics\n\n#### AI in Action\n\n**Summary:**\n\nMIT SMR columnists Thomas H. Davenport and Randy Bean see five...",
          "source": "web",
          "title": "Five Trends in AI and Data Science for 2026",
          "url": "https://sloanreview.mit.edu/article/five-trends-in-ai-and-data-science-for-2026/"
        },
        {
          "date": "2026-01-06",
          "id": 4,
          "last_updated": "2026-02-24T00:01:21",
          "snippet": "## Jeff Su\n\n##### Jan 06, 2026 (0:13:13)\nMost #AI predictions are speculation. This video covers...",
          "source": "web",
          "title": "Top 6 AI Trends That Will Define 2026 (backed by data)",
          "url": "https://www.youtube.com/watch?v=B23W1gRT9eY"
        },
        {
          "date": "2026-01-15",
          "id": 5,
          "last_updated": "2026-02-23T17:37:52",
          "snippet": "",
          "source": "web",
          "title": "11 things AI experts are watching for in 2026 | University of California",
          "url": "https://www.universityofcalifornia.edu/news/11-things-ai-experts-are-watching-2026"
        },
        {
          "date": "2026-01-13",
          "id": 6,
          "last_updated": "2026-02-23T16:27:23",
          "snippet": "Artificial intelligence (AI) is no longer an emerging technology, it\u2019s a transformational force driving innovation across industries...",
          "source": "web",
          "title": "AI Trends in 2026: A New Era of AI Advancements and Breakthroughs",
          "url": "https://www.trigyn.com/insights/ai-trends-2026-new-era-ai-advancements-and-breakthroughs"
        },
        {
          "date": "2025-12-22",
          "id": 7,
          "last_updated": "2026-02-23T09:47:25",
          "snippet": "The most significant advances in artificial intelligence next year won't come from...",
          "source": "web",
          "title": "6 AI breakthroughs that will define 2026 - InfoWorld",
          "url": "https://www.infoworld.com/article/4108092/6-ai-breakthroughs-that-will-define-2026.html"
        },
        {
          "date": "2025-12-22",
          "id": 8,
          "last_updated": "2026-02-23T20:21:57",
          "snippet": "What will define AI in 2026? \ud83d\ude80 Martin Keen & Aaron Baughman explore groundbreaking trends like Agentic AI, cloud computing, automation, and quantum computing, plus innovations like Physical AI...",
          "source": "web",
          "title": "AI Trends 2026: Quantum, Agentic AI & Smarter Automation",
          "url": "https://www.youtube.com/watch?v=zt0JA5rxdfM"
        },
        {
          "date": "2025-12-15",
          "id": 9,
          "last_updated": "2026-02-23T13:13:58",
          "snippet": "",
          "source": "web",
          "title": "Stanford AI Experts Predict What Will Happen in 2026",
          "url": "https://hai.stanford.edu/news/stanford-ai-experts-predict-what-will-happen-in-2026"
        },
        {
          "date": "2025-05-10",
          "id": 10,
          "last_updated": "2026-02-20T16:07:11",
          "snippet": "{ts:574} breakthroughs in AlphaGo and Alpha Fold, which are absolutely incredible. Now, DeepMind has basically said...",
          "title": "2026 AI : 10 Things Coming In 2026 (A.I In 2026 Major Predictions)",
          "url": "https://www.youtube.com/watch?v=RfA2Ug4FuaY"
        }
      ],
      "type": "search_results"
    },
    {
      "content": [
        {
          "annotations": [],
          "logprobs": [],
          "text": "Here are major *recent* directions in AI (late 2025\u2013early 2026) that researchers...",
          "type": "output_text"
        }
      ],
      "id": "msg_d0f12cc6-c6a2-426f-b55e-fff247e40c8c",
      "role": "assistant",
      "status": "completed",
      "type": "message"
    }
  ],
  "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"
    }
  ],
  "top_logprobs": 0,
  "top_p": 1,
  "truncation": "disabled",
  "usage": {
    "cost": {
      "currency": "USD",
      "input_cost": 0.00826,
      "output_cost": 0.0063,
      "tool_calls_cost": 0.005,
      "total_cost": 0.01956
    },
    "input_tokens": 4718,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 450,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "tool_calls_details": {
      "search_web": {
        "invocation": 1
      }
    },
    "total_tokens": 5168
  },
  "user": null
}

Next Steps

Tools

Use web search, URL fetching, and function calling to extend model capabilities.

Models

Browse available models and pricing across all supported providers.

Presets

Explore pre-configured setups for common use cases like pro-search and deep-research.

Output Control

Configure streaming responses and structured outputs with JSON schema.

Model Fallback

Specify multiple models for automatic failover and higher availability.

Prompt Guide

Best practices for effective prompting with web search models.

Search Filters

Control search results with domain, date, and location filters.

API Reference

View complete endpoint documentation and parameters.

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

Getting Started

Perplexity SDK

Search API

Sonar API

Browser API

Embeddings API

Admin & Management

Resources

Agent API

Get your Perplexity API Key

Why Use the Agent API?

Multi-Provider Access

Transparent Pricing

Granular Control

Installation

Authentication

Basic Usage

Using a Third-Party Model

Using a Preset

With Web Search

Next Steps

Tools

Models

Presets

Output Control

Model Fallback

Prompt Guide

Search Filters

API Reference

Get your Perplexity API Key

​Why Use the Agent API?

Multi-Provider Access

Transparent Pricing

Granular Control

​Installation

​Authentication

​Basic Usage

​Using a Third-Party Model

​Using a Preset

​With Web Search

​Next Steps

Tools

Models

Presets

Output Control

Model Fallback

Prompt Guide

Search Filters

API Reference

Why Use the Agent API?

Installation

Authentication

Basic Usage

Using a Third-Party Model

Using a Preset

With Web Search

Next Steps