Perplexity API

Summary

Perplexity API provides programmatic access to Perplexity's AI search and reasoning capabilities for building applications.

Release history

1. changelog-20260828-02a9ef78 Aug 28, 2026 · issue 009

   Perplexity API adds GLM 5.3 model and automatic prompt cache keys for Agent API presets

   └──▷ TRY IT
   Call the new GLM 5.3 model for a chat completion via the Perplexity API.
   copy

   $ curl https://api.perplexity.ai/chat/completions \
     -H 'Authorization: Bearer <YOUR_API_KEY>' \
     -H 'Content-Type: application/json' \
     -d '{"model": "perplexity/glm-5.3", "messages": [{"role": "user", "content": "Explain prompt caching."}]}'

   • ›An explicit prompt_cache_key in a request still overrides the preset-derived default, preserving full manual control over cache partitioning.
2. docs update Aug 28, 2026 · issue 009

   Perplexity API gateway adds prompt caching, search_result content blocks, and explicit validation rejects for unsupported fields.

   └──▷ TRY IT
   Cache a large system prompt for 5 minutes to reduce repeated input-token costs across many turns.
   copy

   $ curl https://api.perplexity.ai/gateway/messages \
     -H 'Authorization: Bearer $PERPLEXITY_API_KEY' \
     -H 'Content-Type: application/json' \
     -d '{
       "model": "sonar",
       "messages": [
         {
           "role": "user",
           "content": [
             {
               "type": "text",
               "text": "You are a security analyst. <large system context here>",
               "cache_control": {"type": "ephemeral", "ttl": "5m"}
             },
             {
               "type": "text",
               "text": "Summarize the latest threat intel."
             }
           ]
         }
       ]
     }'

   • ›Adds cache_control with ephemeral type and ttl field (value "5m") to message content and tool_result.content blocks, enabling prompt cache breakpoints; ttl value "1h" is explicitly rejected until 1h writes are billed distinctly.
   • ›Exposes cache_creation usage fields ephemeral_5m_input_tokens and ephemeral_1h_input_tokens in API responses to report cached token counts.
   • ›Adds search_result as a supported content block type alongside text, image, and document in message content and tool_result.content.
   • ›Document content blocks now accept base64, plain text, or URL sources and support optional title and context fields.
   • ›Adds service_tier field (auto, standard_only) to the gateway — accepted and ignored, as service_tier is OpenAI-only.
   +6 moreshow less

   • ›Adds output_config and context_management fields — accepted and ignored; context edits are not applied but are kept raw so evolving strategies decode.
   • ›Adds inference_geo field — rejected by validation because geo-pinning cannot be honored (silently ignoring it would break residency expectations).
   • ›Adds mcp_servers field — rejected by validation; server-side MCP execution is not supported.
   • ›Adds speed field ("standard" | "fast") — "standard" is inert and "fast" is rejected (no fast-mode routing).
   • ›Adds fallbacks and fallback_credit_token fields — both rejected by validation because fallback models would bill as the requested slug.
   • ›Adds container field — rejected by validation; no code-execution containers are supported.
3. docs update Aug 28, 2026 · issue 009

   Perplexity API adds a gateway responses endpoint at POST /router/v1/responses with tool-calling, reasoning, and caching fields.

   └──▷ TRY IT
   Send a multi-turn request through the gateway and retrieve reasoning token usage to understand chain-of-thought cost.
   copy

   $ curl --request POST \
     --url https://api.perplexity.ai/router/v1/responses \
     --header 'Authorization: Bearer <token>' \
     --header 'Content-Type: application/json' \
     --data '{
       "previous_response_id": "<prior_response_id>",
       "instructions": "You are a helpful assistant.",
       "temperature": 0.7,
       "reasoning": {},
       "store": true
     }'

   Use tool-calling with parallel execution capped at a fixed number of calls, then inspect the prompt_cache_key to verify cache reuse across requests.
   copy

   $ curl --request POST \
     --url https://api.perplexity.ai/router/v1/responses \
     --header 'Authorization: Bearer <token>' \
     --header 'Content-Type: application/json' \
     --data '{
       "instructions": "Answer using the provided tools.",
       "tools": [{"function": {"name": "search", "description": "Search the web", "parameters": {}, "strict": true}}],
       "tool_choice": {"function": {"name": "search"}},
       "parallel_tool_calls": true,
       "max_tool_calls": 3,
       "truncation": "disabled"
     }'

   • ›Response object exposes usage.input_tokens_details.cached_tokens, cache_write_tokens, and prompt_cache_key fields for tracking prompt-cache hits and writes.
   • ›Response object includes usage.output_tokens_details.reasoning_tokens and a top-level reasoning object for models that produce chain-of-thought reasoning.
   • ›Supports parallel_tool_calls, max_tool_calls, and truncation (values: disabled) fields for fine-grained tool-call control.
   • ›Supports store, background, service_tier, safety_identifier, and metadata fields in the response object for lifecycle and routing management.
   • ›Output content items carry a phase field (e.g. commentary) enabling structured labeling of response segments.
   +2 moreshow less

   • ›Exposes standard sampling parameters — temperature, top_p, presence_penalty, frequency_penalty, top_logprobs, and max_output_tokens — directly on the response object.
   • ›Response lifecycle tracked via status, created_at, completed_at, and incomplete_details.reason fields.
4. docs update Aug 28, 2026 · issue 009

   Perplexity Enterprise gets an Analytics API with time-series usage data across credits, queries, members, and more

   └──▷ TRY IT
   Pull daily credit usage for the whole organization into a BI pipeline over the last 90 days.
   copy

   $ curl -X GET 'https://api.perplexity.ai/analytics/v1?dataset=credits&bucket_width=1d' \
     -H 'Authorization: Bearer <your_api_key>'

   Get per-member query volume breakdowns at daily granularity using the v2 endpoint to see which team members are consuming the most queries.
   copy

   $ curl -X GET 'https://api.perplexity.ai/analytics/v2?dataset=query_volume' \
     -H 'Authorization: Bearer <your_api_key>'

   Restrict a credits report to a single organization member to audit individual usage.
   copy

   $ curl -X GET 'https://api.perplexity.ai/analytics/v1?dataset=credits&member=alice%40example.com' \
     -H 'Authorization: Bearer <your_api_key>'

   • ›Adds a new Analytics API giving Perplexity Enterprise organizations programmatic access to usage time series covering credits, query_volume, daily_active_users, threads by connector/artifact/skill/space/workflow, and task durations.
   • ›Supports bucket_width parameter on most datasets; query_volume and daily_active_users are organization-only and aggregated daily, rejecting bucket_width and member filters with an error.
   • ›Adds a member filter parameter to restrict results to a single organization member — available on all datasets except query_volume and daily_active_users.
   • ›Adds a v2 endpoint for per-member breakdowns at daily granularity, returning one row per member keyed by email; supports credits (with the same breakdown axes as v1) and query_volume (with Feature, Project, and Comet breakdowns).
   • ›The query_volume dataset exposes five breakdown axes: Feature (splits queries into Search or other), model name (exact selection), Model Family (coarser grouping), Project, and Comet — note these axes are overlapping subsets, not partitions, so they do not sum to a total.
   +1 moreshow less

   • ›Returns bucketed time series consumable by BI tools or internal reporting pipelines; the response top-level field lists breakdown axes in canonical render order per dataset.
5. docs update Aug 28, 2026 · issue 009

   Perplexity API adds an automatic routing layer with health-based failover, multi-turn affinity, and prompt-cache continuity across deployments.

   • ›Introduces Router API (private preview) that automatically distributes requests across multiple underlying deployments for a model, with no routing parameters or per-provider configuration required — contact [email protected] to request access.
   • ›Weighted traffic splitting continuously adjusts based on observed error rates, capacity, and latency, shedding traffic from degraded deployments and gradually restoring them as they recover.
   • ›Multi-turn conversations are pinned to the same deployment where possible, preserving prompt-cache continuity so repeated conversation prefixes benefit from cache-read pricing without extra configuration.
   • ›Automatic failover retries on an alternative deployment when a provider error, rate limit, or timeout is encountered — each attempt is bounded by time-to-first-token and total-duration limits.
   • ›Deterministic client errors (invalid request or context-window overflow) surface immediately as a 400 and are never retried across deployments.
   +2 moreshow less

   • ›When every deployment for a model is exhausted, the API returns a 429 with a Retry-After header; requests that fail before producing any output are not billed.
   • ›For streaming requests, failover before the first token is transparent to the client; a stream that fails mid-response ends with an in-band error event, and only tokens actually delivered are billed.
6. docs update Aug 28, 2026 · issue 009

   Perplexity Router API (private preview) adds Chat Completions and Messages endpoints with a live model catalog via GET /models

   └──▷ TRY IT
   Discover all currently available Router models and their pricing before choosing one for your integration.
   copy

   $ curl 'https://api.perplexity.ai/router/v1/models' \
     -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
     | jq

   • ›Adds GET /router/v1/models endpoint to programmatically list all available models with their token pricing, sorted by id; requesting an unlisted model returns a 400 error.
   • ›New Router API exposes six perplexity-hosted open-source models under creator/model-name IDs: perplexity/deepseek-v4-flash-0731, perplexity/kimi-k3, perplexity/glm-5.2, perplexity/glm-5.3, perplexity/nemotron-3.5-lightning-30b-a3b, and perplexity/nemotron-3-ultra-550b-a55b.
   • ›Router API supports both Chat Completions and Messages endpoint shapes under the same creator/model-name model ID.
   • ›Cache reads and cache writes are billed at separate per-model rates distinct from fresh input; reasoning tokens are billed at the output rate.
7. docs update Aug 28, 2026 · issue 009

   Perplexity launches Router API (private preview): one endpoint and API key for OpenAI- and Anthropic-compatible access to open-weight models

   └──▷ TRY IT
   Drop the Router into an existing OpenAI SDK integration to access any open-weight model without managing provider accounts or failover logic.
   copy

   $ curl -X POST 'https://api.perplexity.ai/router/v1/chat/completions' \
     -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"model": "perplexity/kimi-k3", "max_tokens": 1024, "messages": [{"role": "user", "content": "Explain the CAP theorem in two sentences."}]}' | jq

   Discover available models and their per-token pricing before choosing a model for a cost-sensitive workload.
   copy

   $ curl 'https://api.perplexity.ai/router/v1/models' \
     -H "Authorization: Bearer $PERPLEXITY_API_KEY" | jq '.data[] | {id, input: .pricing.input, output: .pricing.output}'

   Stream a response and capture token usage in the final chunk for real-time cost accounting in a pipeline.
   copy

   $ curl -N -X POST 'https://api.perplexity.ai/router/v1/chat/completions' \
     -H "Authorization: Bearer $PERPLEXITY_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"model": "perplexity/kimi-k3", "max_tokens": 1024, "messages": [{"role": "user", "content": "Summarise zero-trust networking in three bullet points."}], "stream": true, "stream_options": {"include_usage": true}}'

   • ›New POST https://api.perplexity.ai/router/v1/chat/completions endpoint accepts OpenAI Chat Completions format requests for any catalog model using creator/model-name slugs (e.g. perplexity/kimi-k3), with automatic failover routing and no per-provider accounts needed.
   • ›New POST https://api.perplexity.ai/router/v1/responses endpoint accepts OpenAI Responses format (client.responses.create()) as a stateless alternative; pass the full conversation in input each request.
   • ›New POST https://api.perplexity.ai/router/v1/messages endpoint (Anthropic SDK base URL: https://api.perplexity.ai/router) accepts Anthropic Messages format, making the Router a drop-in replacement for Anthropic integrations with only a base-URL change.
   • ›New GET https://api.perplexity.ai/router/v1/models endpoint returns the OpenAI-compatible model catalog sorted by model ID, including per-model input, output, and cache_read prices in USD per 1M tokens.
   • ›Streaming via stream: true supported on Chat Completions; set stream_options: {"include_usage": true} to receive token usage in a final server-sent-events chunk before data: [DONE].
   +1 moreshow less

   • ›Existing Perplexity API key authenticates all Router endpoints via Authorization: Bearer header — no new credentials required.
8. docs update Aug 28, 2026 · issue 009

   Perplexity API adds GLM 5.3 model (perplexity/glm-5.3) at $1.40/M input tokens

   └──▷ TRY IT
   Query the new GLM 5.3 model via the Perplexity API to compare cost and quality against existing models.
   copy

   $ curl https://api.perplexity.ai/chat/completions \
     -H 'Authorization: Bearer <your_api_key>' \
     -H 'Content-Type: application/json' \
     -d '{"model": "perplexity/glm-5.3", "messages": [{"role": "user", "content": "Explain zero-day vulnerabilities."}]}'

   • ›Adds perplexity/glm-5.3 as a new model identifier available via the API, priced at $1.40 per million uncached-input tokens, $0.26 per million cached-input tokens, and $4.40 per million output tokens.
9. docs update Aug 28, 2026 · issue 009

   Perplexity gateway endpoint adds reasoning context replay, prompt cache TTL control, moderation results, and tool-call filtering.

   └──▷ TRY IT
   Set a 1-hour prompt cache TTL on a gateway request to control how long your prompt is cached, replacing the deprecated inline retention setting.
   copy

   $ curl --request POST \
     --url https://api.perplexity.ai/router/v1/chat/completions \
     --header 'Authorization: Bearer <token>' \
     --header 'Content-Type: application/json' \
     --data '{
       "model": "<model>",
       "prompt_cache_options": { "ttl": "1h" },
       "messages": [
         { "role": "user", "content": "Summarize the OWASP Top 10." }
       ]
     }'

   Inspect the moderation result on a gateway response to detect flagged output before forwarding it downstream.
   copy

   $ curl --request POST \
     --url https://api.perplexity.ai/router/v1/chat/completions \
     --header 'Authorization: Bearer <token>' \
     --header 'Content-Type: application/json' \
     --data '{
       "model": "<model>",
       "messages": [
         { "role": "user", "content": "<user input>" }
       ]
     }' | jq '.moderation.output.results[0].flagged'

   Replay reasoning_content from a prior turn to preserve chain-of-thought context in a follow-up request.
   copy

   $ curl --request POST \
     --url https://api.perplexity.ai/router/v1/chat/completions \
     --header 'Authorization: Bearer <token>' \
     --header 'Content-Type: application/json' \
     --data '{
       "model": "<model>",
       "messages": [
         { "role": "user", "content": "Analyze this log for anomalies." },
         { "role": "assistant", "content": "<prior answer>", "reasoning_content": "<prior reasoning_content>" },
         { "role": "user", "content": "Which finding is highest severity?" }
       ]
     }'

   • ›New POST https://api.perplexity.ai/router/v1/chat/completions gateway endpoint supports allowed_tools to restrict which function tools the model may call during a request.
   • ›Response choices now include a reasoning_content field; replaying it in a subsequent assistant message preserves reasoning context across multi-turn requests.
   • ›Message parts support a new prompt_cache_breakpoint field to mark cache boundaries within a prompt.
   • ›New prompt_cache_options request object with a ttl field (accepted values: 5m, 1h, 24h) replaces the deprecated cache-retention setting and controls how long prompt cache entries are retained.
   • ›Response usage object now includes cache_write_tokens alongside existing cached_tokens and audio_tokens fields under prompt_tokens_details, giving visibility into cache population costs.
   +1 moreshow less

   • ›New moderation object in the response exposes both input and output moderation results, including per-model flagged status, categories, category_scores, and category_applied_input_types for content safety inspection.
10. docs update Aug 28, 2026 · issue 009

    Perplexity API adds a Router API, Analytics API, managed Connectors, and per-member usage breakdowns.

    • ›New Analytics API endpoint returns org-wide Perplexity usage as a bucketed time series; requires an org-scoped analytics API key generated by an org admin via Settings → Organization → Computer.
    • ›New Usage Analytics per Member endpoint (computer-analytics-usage-v2-get) breaks down daily usage per member (keyed by email), with credit_usage split by Model and Credit Source, and query_volume split by Feature, Project, and Comet.
    • ›New Perplexity Router API provides unified access to open-weight models through OpenAI Chat Completions, OpenAI Responses, and Anthropic Messages APIs using a single Perplexity API key.
    • ›Router API includes automatic failover routing across model deployments when a provider degrades or fails.
    • ›New Connectors support lets Agent API requests use managed connectors (including Slack and GitHub) defined in your API Group.
11. snapshot-20260828 seen Aug 28, 2026 · issue 009

    Perplexity Agent API and Router API add support for GLM 5.3 model.

    • ›Adds perplexity/glm-5.3 to the Agent API and Router API at $1.40/M uncached-input tokens, $0.26/M cached-input tokens, and $4.40/M output tokens.
12. changelog-20260828-9fb6fe49 Aug 28, 2026 · issue 009

    Perplexity Agent API presets now share stable prompt cache keys automatically, cutting costs ~5% with no request changes.

    • ›Agent API presets automatically use stable prompt cache keys so independent requests sharing the same preset reuse the cached system prompt and tool definitions — no request changes required.
    • ›An explicit prompt_cache_key on a request still overrides the preset-level cache default when per-request control is needed.
13. snapshot-20260822 seen Aug 22, 2026 · issue 004

    Perplexity Agent API presets now use stable prompt cache keys automatically, reducing costs by ~5% with no request changes required.

    • ›Agent API presets automatically assign stable prompt cache keys, enabling independent requests sharing the same preset to reuse the cached system prompt and tool definitions prefix — no request changes required.
    • ›An explicit prompt_cache_key still overrides the preset default when per-request cache control is needed.
14. 1.0.0 Aug 20, 2026 · issue 002

    Perplexity API now publishes an API — 15 endpoints across 3 areas: V1, Search, V2

    • ›V1 (13 endpoints) — create, read
    • ›Search (1 endpoint) — create
    • ›V2 (1 endpoint) — read
15. snapshot-20260820 seen Aug 20, 2026 · issue 002

    Perplexity adds Router API, remote MCP server, finance_search tool, AWS Marketplace billing, and a wave of new Agent API models.

    └──▷ TRY IT
    Discover all current Agent API models dynamically — no auth needed — for use in integration bootstrapping or CI pipelines.
    copy

    $ curl https://api.perplexity.ai/v1/models

    • ›New Router API provides unified access to open-weight models via a single endpoint using your existing Perplexity API key, with OpenAI Chat Completions and Anthropic Messages compatibility (base-URL swap), automatic health-based routing and failover, and per-token pricing with no per-request fees.
    • ›New GET /v1/models endpoint lists all available Agent API models in OpenAI-compatible format with no authentication required, enabling dynamic model selection in integrations.
    • ›Remote MCP Server now hosted by Perplexity at https://api.perplexity.ai/mcp — connect any MCP client supporting Streamable HTTP using your API key as a bearer token, with no local install; usage billed to your API key at standard API pricing.
    • ›New finance_search tool added to the Agent API, returning structured financial and market data — quotes (near-real-time prices, OHLCV, pre/after-hours), income statement, balance sheet, cash flow, earnings transcripts, analyst estimates, and ETF constituents for public companies.
    • ›MCP Server v1.0.0 backs perplexity_ask, perplexity_reason, and perplexity_research tools with Agent API presets (fast, medium, and high respectively); long-running research now streams progress to MCP clients, and cancelling an MCP request cancels the underlying run.
    +16 moreshow less

    • ›Agent API presets now include inline citations: fast preset cites with numbered markers such as [1]; low, medium, and high presets cite with source-typed markers such as [web:1].
    • ›Agent API fast preset updated to use openai/gpt-5.6-luna with minimal reasoning effort and priority processing; frozen configurations must update model, reasoning effort, and set service_tier to priority.
    • ›Agent API low preset updated to use openai/gpt-5.6-luna with minimal reasoning effort and a 32,768-token maximum output; frozen configurations must update these values manually.
    • ›Agent API and Router API now support google/gemini-3.7-flash at $0.375/M input tokens, $0.0375/M cached-input tokens, and $1.875/M output tokens.
    • ›Agent API now supports xai/grok-4.6, xAI's latest flagship reasoning and agentic model.
    • ›Agent API and Router API now support perplexity/nemotron-3-ultra-550b-a55b at $0.25/M input or cached-input tokens and $2.50/M output tokens.
    • ›Agent API and Router API now support perplexity/nemotron-3.5-lightning-30b-a3b at $0.0115/M input tokens, $0.00115/M cached-input tokens, and $0.17/M output tokens.
    • ›Agent API and Router API now support perplexity/deepseek-v4-flash-0731, a fast open reasoning model with a 1M-token context window.
    • ›Agent API now supports openai/gpt-5.6-sol Fast mode via service_tier: 'priority' at 2× standard token pricing; openai/gpt-5.6-luna cut to $0.20/M input and $1.20/M output; openai/gpt-5.6-terra cut to $2/M input and $12/M output.
    • ›Agent API now supports anthropic/claude-opus-5, openai/gpt-5.6-sol, openai/gpt-5.6-terra, openai/gpt-5.6-luna, google/gemini-3.6-flash, google/gemini-3.5-flash-lite, xai/grok-4.5, and perplexity/kimi-k3.
    • ›Agent API now supports anthropic/claude-sonnet-5, perplexity/glm-5.2, perplexity/kimi-k2.7-code, and nvidia/nemotron-3-super-120b-a12b.
    • ›Agent API now supports anthropic/claude-opus-4-8, google/gemini-3.5-flash, google/gemini-3.1-flash-lite, xai/grok-4.3, xai/grok-4.20-non-reasoning, and xai/grok-4.20-multi-agent.
    • ›API key management upgraded to a one-time reveal model: full token values are returned only at creation and cannot be retrieved again from the console or any endpoint; token_name should be set at creation for ongoing identification.
    • ›New native n8n integration ships a Perplexity node covering Chat Completions, Agent, Search, and Embeddings APIs with dynamic model loading from the API.
    • ›New OpenClaw integration adds Perplexity Search API as a native web search provider, returning structured results (title, url, snippet) inside terminal workflows.
    • ›Perplexity API credits now purchasable through the AWS Marketplace SaaS listing for consolidated billing under your AWS account.
    └──▷ BREAKING ON UPGRADE

    • !google/gemini-3.1-flash-lite-preview has been retired; requests for this model ID now return a 'model not supported' error — use google/gemini-3.1-flash-lite instead.
    • !The strip_thinking and reasoning_effort parameters have been removed from MCP Server tool schemas (perplexity_ask, perplexity_reason, perplexity_research); clients sending them are ignored gracefully.
    • !The Agent API fast preset now uses openai/gpt-5.6-luna with priority processing (2× standard token prices); frozen configurations that pinned the previous model and service_tier must manually update model, reasoning effort, and set service_tier to priority.
    • !The Agent API low preset now uses openai/gpt-5.6-luna with a 32,768-token maximum output; frozen configurations must update model and max-output values to match.