Skip to main content

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.

​
Overview

The Sonar API provides powerful features for building production-ready applications. This guide covers two core capabilities: streaming responses for real-time output and structured outputs for consistent data formats. For prompting guidance, see the Prompt Guide.

​
Streaming Responses

Streaming allows you to receive partial responses from the Sonar API as they are generated, rather than waiting for the complete response. This is particularly useful for real-time user experiences, long responses, and interactive applications.
Streaming is supported across all Sonar models.

​
How Streaming Works

When streaming, you receive:
  1. Content chunks which arrive progressively in real-time
  2. Search results (delivered in the final chunk(s))
  3. Usage stats and other metadata
Search results and metadata are delivered in the final chunk(s) of a streaming response, not progressively during the stream.

​
Example

from perplexity import Perplexity

client = Perplexity()

# Create streaming completion
stream = client.chat.completions.create(
    model="sonar",
    messages=[{"role": "user", "content": "What is the latest in AI research?"}],
    stream=True
)

# Process streaming response
content = ""
for chunk in stream:
    if chunk.choices[0].delta.content:
        content_piece = chunk.choices[0].delta.content
        content += content_piece
        print(content_piece, end="", flush=True)
    
    # Collect metadata from final chunks
    if hasattr(chunk, 'search_results') and chunk.search_results:
        search_results = chunk.search_results
    
    if hasattr(chunk, 'usage') and chunk.usage:
        usage_info = chunk.usage

​
Structured Outputs

Structured outputs enable you to enforce specific response formats from Perplexity’s models, ensuring consistent, machine-readable data that can be directly integrated into your applications without manual parsing. We support JSON Schema structured outputs. To enable structured outputs, add a response_format field to your request with the following structure: 
{
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "schema": { /* your JSON schema object */ }
    }
  }
}
Improve Schema Compliance: Give the LLM hints about the output format in your prompts to improve adherence to the structured format. Include phrases like “Please return the data as a JSON object with the following structure…”
The first request with a new JSON Schema may incur a delay on the first token (typically 10-30 seconds) as the schema is prepared. Subsequent requests will not see this delay.

​
Example: Financial Analysis

from perplexity import Perplexity
from typing import List, Optional
from pydantic import BaseModel

class FinancialMetrics(BaseModel):
    company: str
    quarter: str
    revenue: float
    net_income: float
    eps: float
    revenue_growth_yoy: Optional[float] = None
    key_highlights: Optional[List[str]] = None

client = Perplexity()

completion = client.chat.completions.create(
    model="sonar-pro",
    messages=[
        {
            "role": "user",
            "content": "Analyze the latest quarterly earnings report for Apple Inc. Extract key financial metrics."
        }
    ],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "schema": FinancialMetrics.model_json_schema()
        }
    }
)

metrics = FinancialMetrics.model_validate_json(completion.choices[0].message.content)
print(f"Revenue: ${metrics.revenue}B")
Links in JSON Responses: Requesting links as part of a JSON response may not always work reliably. Use the links returned in the citations or search_results fields from the API response instead.

​
Next Steps

Sonar Prompt Guide

Sonar-specific prompting caveats and best practices.

Pro Search for Sonar Pro

Enhanced search with automated tools, multi-step reasoning, and real-time thought streaming.

Sonar API Search Filters

Learn how to control search behavior with filters and parameters.

Sonar API Media Attachments

Send and receive images, videos, and files with the Sonar API.