Generating an API Key
- Create or select your project in the API Console.
- Open API Keys.
- Click + Generate API Key.
- Copy the key before you leave the page. The console shows the full key only once.
Get your Perplexity API Key
Open the API Keys page in the API Console.
Pricing
The APIs use pay-as-you-go pricing. You do not need a subscription.
Overview
The Perplexity API provides seven core APIs for different use cases: the Orchestrator API, Agent API, Search API, Monitor API, Context API, Embeddings API, and Decisions API.Available APIs
Orchestrator API
Frontier and open-weight models through one API key, in the OpenAI or Anthropic request format.
Agent API
Get web-grounded answers with built-in citations in one call, or access third-party models from OpenAI, Anthropic, Google, and xAI with web search tools and effort levels.
Search API
Get ranked web results and page snippets. Filter by domain, language, or date.
Context API
Fetch Markdown, HTML, links, highlights, and metadata from URLs you already have, and score each page with yes or no criteria.
Monitor API
Run web searches or page checks on a schedule and read the saved results.
Embeddings API
Generate high-quality embeddings for semantic search and RAG pipelines.
Decisions API
Get typed answers with probabilities for yes/no, multiple-choice, and rubric questions about text and images.
Choosing the Right API
Use the Orchestrator API when...
Use the Orchestrator API when...
- You want one API for frontier and open-weight models, with a single API key
- You have an OpenAI or Anthropic SDK integration and can change its base URL, API key, and model ID. Features depend on the model.
- You want routing and failover across model deployments handled for you instead of building it yourself
Use the Agent API when...
Use the Agent API when...
- You want web-grounded answers with built-in citations - send a message and get a researched, cited response, with conversation context when you need it
- You prefer simplicity: pick a effort level and get a researched answer in one call, or take granular control over model, reasoning, token budgets, and tools
- You need multi-provider access to OpenAI, Anthropic, Google, xAI, and Perplexity’s own model through one API
Use the Search API when...
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
Use the Context API when...
Use the Context API when...
- You already have the URLs and need their content as Markdown, HTML, or links
- You want only the passages relevant to a query from each page, with highlights
- You want to score each page with yes or no questions, such as a prompt injection check, before your model reads it
Use the Monitor API when...
Use the Monitor API when...
- You want new search results for a query or text changes at known URLs checked on a schedule
- You want the results saved so you can read them later through the API
- You want webhook notifications when a run finds something new
Use the Embeddings API when...
Use the Embeddings API when...
- You need semantic similarity between texts for search or recommendations
- You’re building RAG pipelines that require vector representations of documents
- You need to cluster, classify, or compare text without generating a response
Use the Decisions API when...
Use the Decisions API when...
- You need a yes/no answer, one of your options, or a level on your rubric instead of generated text
- You want probabilities you can threshold in code, with no output parsing
- You want to ask many questions about the same content, including images, in one request
Installation
Skip package installation if you use cURL. For the Orchestrator examples, install the OpenAI SDK:Authentication
Set your API key as an environment variable:- macOS/Linux
- Windows
- macOS/Linux
- Windows
OpenAI SDK compatible: The Agent API follows the OpenAI Responses API format. Point the OpenAI SDK at
https://api.perplexity.ai/v1 and call client.responses.create(); the canonical endpoint is POST /v1/agent, and POST /v1/responses is accepted as an alias. See the OpenAI Compatibility Guide. For the OpenAI Chat Completions format, use the Orchestrator API at POST /orchestrator/v1/chat/completions.Making Your First API Call
The cURL examples use a Bash-compatible shell. On Windows, use Bash for cURL. Set the key in that shell. If you use PowerShell, use the Python or TypeScript example. If you do not havejq, remove | jq.
To create a scheduled search or page check and read its first run, follow the Monitor API quickstart.
Choose your API based on your use case:
- Orchestrator API
- Agent API
- Search API
- Context API
- Decisions API
Use for direct access to frontier and open-weight models with the OpenAI SDK:
See the Orchestrator Chat Completions reference for the request and response fields.
Example response, abbreviated
Example response, abbreviated
The response uses the OpenAI Chat Completions format. The
model field names the model that served the request. This example shortens reasoning_content. GLM models reason by default; see Reasoning & Caching to set the effort.Streaming Responses
Setstream to true to receive Agent API events as the API sends them. The Python and TypeScript examples print only the text deltas. The cURL example shows the server-sent events.
- Agent API
Example response, abbreviated
Example response, abbreviated
This excerpt shows the first two events, three text deltas, and the final event. Lines with
... mark skipped events. This example shortens each response object to id and status, and keeps model in the final event. The final response.completed event carries the full response object.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:Orchestrator API
Get started with frontier and open-weight models through one API key
Agent API
Get started with third-party models and effort levels
Search API
Get started with web search results
Context API
Get started with content from URLs you already have
Monitor API
Get started with scheduled searches and page checks
Embeddings API
Get started with text embeddings
Decisions API
Get started with typed answers and probabilities
Additional Resources
Perplexity SDK
Learn about the official Perplexity SDK with type safety and async support
Agent API models
Explore available models and their capabilities
Agent API reference
See the Agent API request and response fields.
Examples
Explore code examples, tutorials, and integration patterns
Need help? Check out our community for support and discussions with other developers.