Access and Setup
Do I Need a Separate API Key?
Do I Need a Separate API Key?
Which Base URL Do I Use?
Which Base URL Do I 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.Which Request Formats Are Supported?
Which Request Formats Are Supported?
/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.Why Use the Orchestrator API Instead of Calling Each Provider?
Why Use the Orchestrator API Instead of Calling Each Provider?
Which Models Can I Use?
Which Models Can I Use?
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.Can I Use My Own Provider API Keys?
Can I Use My Own Provider API Keys?
Does the Orchestrator API Support Zero Data Retention?
Does the Orchestrator API Support Zero Data Retention?
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.Can I Request a Model That Is Not in the Catalog?
Can I Request a Model That Is Not in the Catalog?
google/gemini-4-carbongoogle/gemini-4-argongoogle/gemini-3.1-pro-previewgoogle/gemini-3.1-flash-litegoogle/gemini-3-flash-previewperplexity/nemotron-3.5-super-120b-a12bperplexity/nemotron-3.5-lightning-30b-a3bperplexity/kimi-k3.1-proz-ai/glm-5.1qwen/qwen3.7-max
Billing and Usage
How Am I Billed?
How Am I Billed?
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.How Do I Track Usage and Spend?
How Do I Track Usage and Spend?
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.What Are the Rate Limits?
What Are the Rate Limits?
/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
How Do I Control Reasoning?
How Do I Control Reasoning?
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.Why Did I Get 0 Reasoning Tokens?
Why Did I Get 0 Reasoning Tokens?
- 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-5rejectsthinking.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
noneis served as the lowest effort rather than as off. Atnone,perplexity/glm-5.3andperplexity/glm-5.3-flashusually reported 0 reasoning tokens on short prompts, but a request can still produce a few, andreasoning_contentis returned whenever it does.
Where Do I See Cached and Reasoning Tokens in a Response?
Where Do I See Cached and Reasoning Tokens in a Response?
usage object:- Chat Completions: cache reads in
prompt_tokens_details.cached_tokens, cache writes inprompt_tokens_details.cache_write_tokens, reasoning incompletion_tokens_details.reasoning_tokens. - Responses: cache reads in
input_tokens_details.cached_tokens, cache writes ininput_tokens_details.cache_write_tokens, reasoning inoutput_tokens_details.reasoning_tokens. - Messages: cache reads in
cache_read_input_tokens, cache writes incache_creation_input_tokens, reasoning inoutput_tokens_details.thinking_tokens.
Does Prompt Caching Work Across Requests?
Does Prompt Caching Work Across Requests?
/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:/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.How Do I Carry Reasoning Across Turns?
How Do I Carry Reasoning Across Turns?
/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, addinclude: ["reasoning.encrypted_content"]. Eachreasoningoutput item then carriesencrypted_content. Send the item back, unchanged, in the next turn’sinputalong with the message items. - On
/chat/completions, includereasoning_contenton the assistant messages you send back. The text counts toward the next turn’s prompt tokens.
Routing and Reliability
What Is perplexity/auto?
What Is perplexity/auto?
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.How Do I Control Which Models perplexity/auto Uses?
How Do I Control Which Models perplexity/auto Uses?
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.Why Did a Different Model Answer My perplexity/auto Request?
Why Did a Different Model Answer My perplexity/auto Request?
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.Can I Choose Which Deployment Serves My Request?
Can I Choose Which Deployment Serves My Request?
perplexity/auto, the response and the bill name the model that routing picked. See Routing & Reliability.Do Multi-Turn Conversations Stay on One Deployment?
Do Multi-Turn Conversations Stay on One Deployment?
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.What Happens When a Deployment Fails?
What Happens When a Deployment Fails?
Retry-After header. Requests that fail before producing output are not billed.What Happens If a Stream Fails?
What Happens If a Stream Fails?
Errors and Troubleshooting
Why Did I Get 'Invalid model'?
Why Did I Get 'Invalid model'?
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.Why Does a Request Seem to Hang Before the First Token?
Why Does a Request Seem to Hang Before the First Token?
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.Why Did I Get HTTP 402 or 403?
Why Did I Get HTTP 402 or 403?
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.Which Request Fields Return 'unsupported' or 'unknown field'?
Which Request Fields Return 'unsupported' or 'unknown field'?
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.How Do Safety Identifiers Affect My Requests?
How Do Safety Identifiers Affect My Requests?
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.Why Is content Empty When finish_reason Is length?
Why Is content Empty When finish_reason Is length?
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.How Do I Handle 401, 429, and 5xx Errors?
How Do I Handle 401, 429, and 5xx Errors?