Skip to main content

Access and Setup

No. Use your existing Perplexity API key and configure the base URL for your SDK. Which models the key can call depends on your API organization’s usage tier; see Which Models Can I Use?.
Use https://api.perplexity.ai/orchestrator/v1 for direct HTTP requests and the OpenAI SDKs, which append /chat/completions and /responses. Use https://api.perplexity.ai/orchestrator for the Anthropic SDKs, which append /v1/messages. See the quickstart for code in each language.
Three: OpenAI Chat Completions at /chat/completions, OpenAI Responses at /responses, and Anthropic Messages at /messages. Every model in the catalog supports all three formats, though individual features depend on the model. For example, anthropic/claude-haiku-5-5 answers through /chat/completions and openai/gpt-6-luna answers through /messages.
Use proprietary and open-weight models with one API key and consolidated billing. The same model ID works in all three request formats, so you keep the client you already have. When a deployment fails, the request is retried on another deployment of the same model when one is available, at the same price.
The models page lists every model with its ID, context window, max output, rates, and the minimum usage tier that can call it. Google, xAI, and open-weight models start at Tier 0; Anthropic and OpenAI models at Tier 1; Claude Opus 5, Opus 5.5, and the Fable models at Tier 2. A request for a model your tier cannot use returns HTTP 402; see Why Did I Get HTTP 402 or 403?. GET /orchestrator/v1/models lists only the models your tier can call. It does not apply zero data retention or organization model settings, so a ZDR organization still sees the Claude Fable models in the list. It also does not confirm capacity.
No. The Orchestrator API does not accept OpenAI, Anthropic, or other provider keys. Requests authenticate with your Perplexity API key and are billed to your Perplexity API credits at the rates on the models page.
Yes. Zero data retention (ZDR) is off by default and requires a written agreement with Perplexity and account-level configuration; see Privacy & Security. For an API organization with ZDR enabled, anthropic/claude-fable-5, anthropic/claude-fable-5-1, and anthropic/claude-fable-5-2 return HTTP 403. With perplexity/auto, the decision model for a ZDR organization also runs with zero data retention.
Other models may be available upon request, subject to licensing, data residency, and capacity. Contact api@perplexity.ai with your request.The following models can be requested, subject to approval:
  • google/gemini-4-carbon
  • google/gemini-4-argon
  • google/gemini-3.1-pro-preview
  • google/gemini-3.1-flash-lite
  • google/gemini-3-flash-preview
  • perplexity/nemotron-3.5-super-120b-a12b
  • perplexity/nemotron-3.5-lightning-30b-a3b
  • perplexity/kimi-k3.1-pro
  • z-ai/glm-5.1
  • qwen/qwen3.7-max

Billing and Usage

Per token, at the requested model’s published rates, with no per-request fee. With perplexity/auto, billing uses the model that served the request. Some models charge a higher rate once the input exceeds a threshold; the models page shows both rates and the threshold for each. Cache reads are billed at the model’s cache-read rate and reasoning tokens at the output rate. See Pricing for how credits and billing work across the platform.
Each response’s usage object reports the input, output, cache-read, cache-write, and reasoning tokens for that request; see Where Do I See Cached and Reasoning Tokens in a Response?. Responses do not include a cost field.To estimate the cost of a request, apply the rates on the models page to each bucket, using the higher rate when the input exceeds a model’s threshold. The buckets overlap in the OpenAI formats: in Chat Completions and Responses, the total input count includes cache reads and cache writes, and the total output count includes reasoning tokens. Apply the input rate to total input minus cache reads and cache writes, the cache-read rate to cache reads, the cache-write rate to cache writes, and the output rate to total output. In Messages, input_tokens, cache_read_input_tokens, and cache_creation_input_tokens do not overlap, so each is charged at its own rate, and output_tokens includes thinking tokens.Orchestrator API usage draws on the same credit balance as the rest of the Perplexity API, and project admins can review usage and spend on the Billing page in the API Console, which breaks down cost by model and can filter usage by API key. To keep environments or applications apart, use separate projects and API keys.
Successful responses on /chat/completions and /responses carry x-ratelimit-limit-requests, x-ratelimit-remaining-requests, and x-ratelimit-reset-requests headers; /messages reports the same limit as anthropic-ratelimit-requests-limit, anthropic-ratelimit-requests-remaining, and anthropic-ratelimit-requests-reset (a timestamp). Requests rejected for an invalid body or model do not carry them. The reset interval is one second, so the request limit is a requests-per-second limit; read the headers to pace your traffic. When you receive HTTP 429, back off and retry after the Retry-After interval. Requests rejected with 429 are not billed. See Rate Limits and Usage Tiers. To request a higher limit, fill out the rate limit increase request form.

Reasoning and Caching

Set the effort in the field your request format uses. Any model accepts any format’s field.Other values return HTTP 400, for example unsupported reasoning_effort value "pro". The Anthropic thinking field is accepted only on /messages; on /chat/completions it returns HTTP 400 invalid request body: json: unknown field "thinking".Whether the reasoning text comes back in message.reasoning_content depends on the model family. GLM models return it whenever they reason, including at none. OpenAI and Anthropic models return it only when you set an effort other than none. Anthropic models return the thinking text; OpenAI models return a summary, and the summary is not always present even when reasoning tokens were used. usage reports the reasoning tokens in every case, and you pay for them whether or not the text is returned.
Setting an effort does not guarantee reasoning tokens, and omitting it does not guarantee none. Each model family treats the setting differently:
  • OpenAI models reason by default and stop when you set none. A trivial prompt can report 0 reasoning tokens with no setting too.
  • Anthropic models decide per request whether thinking is needed at the effort you set, so 0 reasoning tokens on a short prompt is normal. A fixed budget is not a way around this: anthropic/claude-sonnet-5-5 rejects thinking.type: "enabled" with "thinking.type.enabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.
  • GLM models reason by default, and none is served as the lowest effort rather than as off. At none, perplexity/glm-5.3 and perplexity/glm-5.3-flash usually reported 0 reasoning tokens on short prompts, but a request can still produce a few, and reasoning_content is returned whenever it does.
Each format reports them in its own usage object:
  • Chat Completions: cache reads in prompt_tokens_details.cached_tokens, cache writes in prompt_tokens_details.cache_write_tokens, reasoning in completion_tokens_details.reasoning_tokens.
  • Responses: cache reads in input_tokens_details.cached_tokens, cache writes in input_tokens_details.cache_write_tokens, reasoning in output_tokens_details.reasoning_tokens.
  • Messages: cache reads in cache_read_input_tokens, cache writes in cache_creation_input_tokens, reasoning in output_tokens_details.thinking_tokens.
Yes, but how you turn it on depends on the model family.OpenAI models cache a repeated prefix automatically on /chat/completions and /responses. The first call reports cache_write_tokens and repeats report cached_tokens. Short prompts are not cached: a 639-token prompt reported no cache activity and a 1,259-token prompt did.Anthropic models need a marker at the end of the reusable prefix. On /messages, use cache_control as you would with the Anthropic Messages API. On /chat/completions, add prompt_cache_breakpoint to the last content part of the prefix:
On /responses, put the same prompt_cache_breakpoint on the last input_text part of the prefix.The marked prefix is cached for five minutes. To cache it for one hour, set prompt_cache_options to { "ttl": "1h" } on /chat/completions and /responses, or "ttl": "1h" inside cache_control on /messages. One-hour cache writes are billed at 2 times the model’s input rate; see Cached and Reasoning Tokens. Other models reject "1h" with HTTP 400 prompt_cache_options.ttl "1h" is supported only on anthropic/* models, got model "perplexity/glm-5.3-flash".Without a marker, Anthropic models report no cache writes and no cache reads. With the marker, the first call reports cache_write_tokens and later calls report cached_tokens on both /chat/completions and /responses. Every Anthropic model needs the marker. mode accepts only explicit.For best-effort reuse of a deployment across turns, send a stable x-session-id header for the conversation, or a stable prompt_cache_key in the body on /chat/completions and /responses. Cache markers do not establish session affinity, and failover or a model change can cause a cache miss. Prompt tokens that miss the cache are billed as fresh input at the model’s input rate. On models that charge for cache writes, tokens written to the cache are billed at the cache-write rate instead; see Cached and Reasoning Tokens. See Routing and Reliability.
The Orchestrator API is stateless, so send the full conversation on every turn. On /responses, store: true returns HTTP 400 store=true is not supported: this endpoint is stateless; omit store or set it to false, and previous_response_id returns HTTP 400 previous_response_id is not supported: this endpoint is stateless.To keep a reasoning model’s earlier thinking in context, request it and send it back:
  • On /responses, add include: ["reasoning.encrypted_content"]. Each reasoning output item then carries encrypted_content. Send the item back, unchanged, in the next turn’s input along with the message items.
  • On /chat/completions, include reasoning_content on the assistant messages you send back. The text counts toward the next turn’s prompt tokens.

Routing and Reliability

A model ID that lets the Orchestrator API pick the model for each request. A decision model reads the conversation and matches the task underway against the route descriptions in routing: a default model and one to five routes, each pairing a plain-language description with a model. Without routing, the default policy applies: openai/gpt-6.1-sol is the default model, and simple requests go to openai/gpt-6-luna. See Model Routing.
Pass a routing object with your own default_model and routes. The decision model sees route descriptions, not route names or model IDs, so describe the requests each route should handle. Models that cannot serve the request are removed before selection. routing is accepted only with model: "perplexity/auto"; with any other model the request returns HTTP 400 routing requires model perplexity/auto. See Route Rules and Errors.
The model field names the model that served the request, and you are billed at that model’s rate. On a successful response, x-perplexity-autoroute-outcome reports routed, media_input, fallback, or single_model. With routed, the route header names the match or none, and the confidence header is present when the decision model returned a probability. Each request is routed on its own, so turns of one conversation can use different models. To stay on one model, name it in model.
No. You choose a model ID and the platform chooses the deployment based on observed error rates, capacity, and latency. The response echoes the model ID you requested, and billing uses that model’s published rates whatever deployment served it. With perplexity/auto, the response and the bill name the model that routing picked. See Routing & Reliability.
Send a stable x-session-id header on every turn, or a stable prompt_cache_key in the body on /chat/completions and /responses, to request best-effort deployment affinity. Cache markers alone do not establish affinity, and a failover can move the request to a cold cache. With perplexity/auto, the header does not pin model selection across turns. See Does Prompt Caching Work Across Requests? for each model family’s cache markers.
When a deployment returns a provider error, a rate limit, or a timeout, the request is retried on another deployment of the same model when one is available. An invalid request or a prompt that exceeds the model’s context window returns HTTP 400 and is not retried on another deployment. If every deployment fails, you receive HTTP 429 with a Retry-After header. Requests that fail before producing output are not billed.
Failures before the first token are handled before the stream starts, so you receive a normal response. If a stream fails after output has begun, it ends with an in-band error event; treat an unterminated stream as incomplete. Streamed requests are billed for the tokens delivered.

Errors and Troubleshooting

The model ID is not in the catalog. The response is HTTP 404 with a message that starts with Invalid model 'gpt-6-luna'; /responses sets code to model_not_found. The most common cause is a missing prefix: gpt-6-luna fails and openai/gpt-6-luna works. Use the exact ID from the models page or from GET /orchestrator/v1/models. The catalog has no -pro variants of the OpenAI models; use the base model ID and pick a reasoning effort.
Reasoning models think before they write the first content token, and the wait grows with the effort you set. To see progress during that wait, set stream: true and an explicit effort other than none. On /chat/completions, any reasoning text the model returns arrives as reasoning_content deltas in choices[0].delta before the content deltas start. A model can return little or no reasoning text, so a quiet stream alone does not mean the connection stalled. With no effort set, OpenAI models stream no reasoning_content, so the connection is silent until the answer begins. If you cannot stream, give the client timeout room for the reasoning phase, or lower the effort.
These status codes mean your API organization cannot use the requested model:With perplexity/auto, custom routes that name a model your tier cannot use are rejected with HTTP 400 routing: model anthropic/claude-opus-5-5 is not available. Models your organization cannot use are removed from the routes before selection, and the request returns HTTP 400 with each model’s reason in the message when none remain.
The Orchestrator API validates the fields each format accepts and returns HTTP 400 with the exact problem in error.message:service_tier accepts auto and default on every model. flex and priority are accepted on OpenAI models only; other models return HTTP 400. When the response reports service_tier as flex or priority, the model’s token rates are multiplied by 0.5 or 2.
If your application serves many end users, send a Perplexity-Safety-Identifier header with a stable, opaque ID for the end user behind each request. When a model provider flags abuse, the block then lands on that one identifier instead of your whole API organization, and requests for a blocked identifier return HTTP 403 with type safety_identifier_blocked. See Safety Identifiers.
Reasoning models spend part of the output budget on reasoning before they write the answer. With a small max_tokens, the budget runs out during reasoning: finish_reason is length, content is null, and usage.completion_tokens_details.reasoning_tokens accounts for the tokens used. Raise max_tokens (or max_output_tokens on /responses). For example, perplexity/glm-5.3-flash returned null content at max_tokens: 20 and a complete answer at max_tokens: 400 for the same one-word prompt.
The same way as for the rest of the Perplexity API: check the key on 401, back off and retry on 429, and retry with backoff on 5xx. See the platform FAQ for each status code.