> ## Documentation Index
> Fetch the complete documentation index at: https://docs.perplexity.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Agent API
> The Agent API is a multi-provider, interoperable API specification for building LLM applications. Access models from multiple providers with integrated real-time web search, tool configuration, reasoning control, and token budgets—all through one unified interface.
Test Agent API requests and parameters interactively in the API console.
## Why Use the Agent API?
Access OpenAI, Anthropic, Google, xAI, and more through one unified API, no need to manage multiple API keys.
See exact token counts and costs per request, no markup, just direct provider pricing.
Change models, reasoning, tokens, and tools with consistent syntax.
We recommend using our [official SDKs](/docs/sdk/overview) for a more convenient and type-safe way to interact with the Agent API.
**Endpoint:** The Agent API is available at `POST https://api.perplexity.ai/v1/agent`. For OpenAI SDK compatibility, `POST /v1/responses` is also accepted as an alias. See the [OpenAI Compatibility Guide](/docs/agent-api/openai-compatibility) for details on using OpenAI SDKs with Perplexity.
## Installation
Install the SDK for your preferred language:
```bash Python theme={null}
pip install perplexityai
```
```bash Typescript theme={null}
npm install @perplexity-ai/perplexity_ai
```
## Authentication
Set your API key as an environment variable. The SDK will automatically read it:
```bash theme={null}
export PERPLEXITY_API_KEY="your_api_key_here"
```
```powershell theme={null}
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:
```python Python theme={null}
from perplexity import Perplexity
client = Perplexity()
response = client.responses.create(
model="openai/gpt-5.5",
input="Explain the difference between supervised and unsupervised learning in machine learning."
)
print(f"Response ID: {response.id}")
print(response.output_text)
```
```typescript Typescript theme={null}
import Perplexity from '@perplexity-ai/perplexity_ai';
const client = new Perplexity();
const response = await client.responses.create({
model: "openai/gpt-5.5",
input: "Explain the difference between supervised and unsupervised learning in machine learning."
});
console.log(`Response ID: ${response.id}`);
console.log(response.output_text);
```
```bash cURL theme={null}
curl https://api.perplexity.ai/v1/agent \
-H "Authorization: Bearer $PERPLEXITY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "openai/gpt-5.5",
"input": "Explain the difference between supervised and unsupervised learning in machine learning."
}' | jq
```
```json theme={null}
{
"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": null,
"max_tool_calls": null,
"metadata": {},
"model": "openai/gpt-5.5",
"object": "response",
"output": [
{
"content": [
{
"annotations": [],
"logprobs": [],
"text": "Supervised learning uses labeled data where each example has a known output, enabling the model to learn direct input-output relationships. Examples include classification and regression.",
"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:
```python Python theme={null}
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)
```
```typescript Typescript theme={null}
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);
```
```bash cURL theme={null}
curl https://api.perplexity.ai/v1/agent \
-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
```
```json theme={null}
{
"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\nYou are an AI assistant developed by Perplexity AI...\n\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](/docs/agent-api/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:
```python Python theme={null}
from perplexity import Perplexity
client = Perplexity()
response = client.responses.create(
model="openai/gpt-5.5",
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)
```
```typescript Typescript theme={null}
import Perplexity from '@perplexity-ai/perplexity_ai';
const client = new Perplexity();
const response = await client.responses.create({
model: "openai/gpt-5.5",
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);
}
```
```bash cURL theme={null}
curl https://api.perplexity.ai/v1/agent \
-H "Authorization: Bearer $PERPLEXITY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "openai/gpt-5.5",
"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
```
```json theme={null}
{
"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.5",
"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
}
```
### With Finance Search
Retrieve structured financial and market data using the `finance_search` tool. See the [Finance Search guide](/docs/agent-api/tools/finance-search) for capabilities and recommended configurations.
```python Python theme={null}
from perplexity import Perplexity
client = Perplexity()
response = client.responses.create(
model="perplexity/sonar",
input="What's NVIDIA trading at right now, and what is its current P/E?",
tools=[{"type": "finance_search"}],
)
for item in response.output:
if item.type == "message":
print(item.content[0].text)
```
```typescript Typescript theme={null}
import Perplexity from '@perplexity-ai/perplexity_ai';
const client = new Perplexity();
const response = await client.responses.create({
model: "perplexity/sonar",
input: "What's NVIDIA trading at right now, and what is its current P/E?",
tools: [{ type: "finance_search" }],
});
console.log(response.output_text);
```
```bash cURL theme={null}
curl https://api.perplexity.ai/v1/agent \
-H "Authorization: Bearer $PERPLEXITY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "perplexity/sonar",
"input": "What is NVIDIA trading at right now, and what is its current P/E?",
"tools": [{"type": "finance_search"}]
}' | jq
```
## Next Steps
Use web search for source-grounded, current context.
Browse available models and pricing across all supported providers.
Explore pre-configured setups for common use cases like pro-search and deep-research.
Configure streaming responses and structured outputs with JSON schema.
Specify multiple models for automatic failover and higher availability.
Best practices for effective prompting with web search models.
Control search results with domain, date, and location filters.
View complete endpoint documentation and parameters.
Need help? Check out our [community](https://community.perplexity.ai) for support and discussions with other developers.