Skip to main content

Generating an API Key

  1. Create or select your project in the API Console.
  2. Open API Keys.
  3. Click + Generate API Key.
  4. 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.
Your project needs API credits. If you only have sign-up credit, open Billing. Buy API credits before you call the Agent API or Orchestrator API.

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

  • 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
Best for: Products that use more than one model
  • 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
Best for: AI assistants, research and Q&A tools, agentic workflows, custom AI applications
  • 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
  • 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
Best for: Reading lists, RAG over known sources, agents that read pages before acting
  • 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
Best for: News and competitor tracking, price or policy change alerts, scheduled research
  • 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
Best for: Semantic search, RAG applications, text classification, recommendation systems
  • 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
Best for: Classification, routing, grading against a rubric, filtering and gating decisions

Installation

Skip package installation if you use cURL. For the Orchestrator examples, install the OpenAI SDK:
For the other Perplexity APIs, use the Perplexity Python library or the Perplexity TypeScript SDK:

Authentication

Set your API key as an environment variable:
Confirm the key is set without printing it:
Do not print the key or any part of it. Commands like env or echo "$PERPLEXITY_API_KEY" can expose it in terminal output and logs. Do not paste a real key into code, fixtures, or commit messages.
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 have jq, 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:
Use for direct access to frontier and open-weight models with the OpenAI SDK:
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.
See the Orchestrator Chat Completions reference for the request and response fields.

Streaming Responses

Set stream 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.
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.