perplexity

Perplexity API

Build AI applications with real-time web search and grounded responses.

Quick Navigation

• Models & pricing: references/models.md
• Search API patterns: references/search-api.md
• Chat completions guide: references/chat-completions.md
• Browser sessions API: references/browser.md
• Embeddings API: references/embeddings.md
• Structured outputs: references/structured-outputs.md
• Filters (domain/language/date/location): references/filters.md
• Media (images/videos/attachments): references/media.md
• Pro Search: references/pro-search.md
• Prompting best practices: references/prompting.md

When to Use

• Need AI responses grounded in current web data
• Building search-powered applications
• Research tools requiring citations
• Real-time Q&A with source verification
• Document/image analysis with web context

Installation

Install: pip install perplexityai (Python) or npm install @perplexityai/perplexity (TypeScript/JavaScript).

Authentication

# macOS/Linux
export PERPLEXITY_API_KEY="your_api_key_here"

# Windows
setx PERPLEXITY_API_KEY "your_api_key_here"

SDK auto-reads PERPLEXITY_API_KEY environment variable.

Quick Start — Chat Completion

from perplexity import Perplexity

client = Perplexity()

completion = client.chat.completions.create(
    model="sonar-pro",
    messages=[{"role": "user", "content": "What is the latest news on AI?"}]
)

print(completion.choices[0].message.content)

Note (v0.28.0): The Python client includes a custom JSON encoder to support additional types in request payloads.

Quick Start — Search API

from perplexity import Perplexity

client = Perplexity()

search = client.search.create(
    query="artificial intelligence trends 2024",
    max_results=5
)

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

Release Highlights (0.34.1 -> 0.38.0)

• Streaming: responses.create now yields named SSE events and discriminates the ResponseStreamEvent union, which matters for typed stream consumers.
• Search context: search_context_size was briefly exposed on search.create, removed in 0.35.1, then reintroduced in 0.37.0 for both the Search API and the web_search tool to control retrieved context size.
• Background responses: the SDK adds background-task support and responses.retrieve, so long-running response workflows can be polled instead of only streamed inline.
• Reasoning effort: xhigh is available where the API supports reasoning-effort controls.
• Sandbox tool: 0.36.0 adds the Responses API sandbox built-in tool; 0.38.0 adds a files subresource for retrieving sandbox-produced files. Gate both like other executable/tooling surfaces.