> ## 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.

# Orchestrator API FAQ

> Answers to common questions about Orchestrator API access, billing, reasoning, caching, routing, and errors.

## Access and Setup

> [accordion] Do I Need a Separate API Key?
>
> No. Use your existing Perplexity API key and configure the [base URL for your SDK](https://docs.perplexity.ai/docs/orchestrator/quickstart.md). Which models the key can call depends on your API organization's [usage tier](https://docs.perplexity.ai/docs/admin/rate-limits-usage-tiers.md); see [Which Models Can I Use?](#access-and-setup).

> [accordion] Which Base URL Do 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](https://docs.perplexity.ai/docs/orchestrator/quickstart.md) for code in each language.

> [accordion] Which Request Formats Are Supported?
>
> Three: OpenAI Chat Completions at `/chat/completions`, OpenAI Responses at `/responses`, and Anthropic Messages at `/messages`. Every model in the [catalog](https://docs.perplexity.ai/docs/orchestrator/models.md) 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`.

> [accordion] Why Use the Orchestrator API Instead of Calling Each Provider?
>
> 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.

> [accordion] Which Models Can I Use?
>
> The [models page](https://docs.perplexity.ai/docs/orchestrator/models.md) lists every model with its ID, context window, max output, rates, and the minimum [usage tier](https://docs.perplexity.ai/docs/admin/rate-limits-usage-tiers.md) 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?](#errors-and-troubleshooting). `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.

> [accordion] Can I Use My Own Provider API Keys?
>
> 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](https://docs.perplexity.ai/docs/orchestrator/models.md).

> [accordion] Does the Orchestrator API Support Zero Data Retention?
>
> Yes. Zero data retention (ZDR) is off by default and requires a written agreement with Perplexity and account-level configuration; see [Privacy & Security](https://docs.perplexity.ai/docs/resources/privacy-security.md). 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.

> [accordion] Can I Request a Model That Is Not in the Catalog?
>
> Other models may be available upon request, subject to licensing, data residency, and capacity. Contact [api@perplexity.ai](mailto: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

> [accordion] How Am I Billed?
>
> 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](https://docs.perplexity.ai/docs/orchestrator/models.md) 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](https://docs.perplexity.ai/docs/getting-started/pricing.md) for how credits and billing work across the platform.

> [accordion] How Do I Track Usage and Spend?
>
> 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?](#reasoning-and-caching). Responses do not include a cost field.
>
> To estimate the cost of a request, apply the rates on the [models page](https://docs.perplexity.ai/docs/orchestrator/models.md) 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](https://docs.perplexity.ai/docs/getting-started/projects.md).

> [accordion] What Are the Rate Limits?
>
> 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](https://docs.perplexity.ai/docs/admin/rate-limits-usage-tiers.md#orchestrator-api-rate-limits). To request a higher limit, [fill out the rate limit increase request form](https://perplexity.typeform.com/to/yctmfyVT).

## Reasoning and Caching

> [accordion] How Do I Control Reasoning?
>
> Set the effort in the field your request format uses. Any model accepts any format's field.
>
> | Format | Field | Values |
> | - | - | - |
> | Chat Completions | `reasoning_effort` | `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max` |
> | Responses | `reasoning.effort` | `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max` |
> | Messages | `thinking: {"type": "adaptive"}` with `output_config.effort` | `low`, `medium`, `high`, `xhigh`, `max` |
>
> 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.

> [accordion] Why Did I Get 0 Reasoning Tokens?
>
> 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.

> [accordion] Where Do I See Cached and Reasoning Tokens in a Response?
>
> 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`.

> [accordion] Does Prompt Caching Work Across Requests?
>
> 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:
>
> ```json theme={null}
> {
>   "model": "anthropic/claude-sonnet-5-5",
>   "messages": [
>     {
>       "role": "system",
>       "content": [
>         {
>           "type": "text",
>           "text": "<long shared instructions>",
>           "prompt_cache_breakpoint": { "mode": "explicit" }
>         }
>       ]
>     },
>     { "role": "user", "content": "A question that changes on every request" }
>   ]
> }
> ```
>
> 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](https://docs.perplexity.ai/docs/orchestrator/models.md#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](https://docs.perplexity.ai/docs/orchestrator/models.md#cached-and-reasoning-tokens). See [Routing and Reliability](#routing-and-reliability).

> [accordion] How Do I Carry Reasoning Across Turns?
>
> 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

> [accordion] What Is perplexity/auto?
>
> 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](https://docs.perplexity.ai/docs/orchestrator/routing-and-reliability.md#model-routing).

> [accordion] How Do I Control Which Models perplexity/auto Uses?
>
> 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](https://docs.perplexity.ai/docs/orchestrator/routing-and-reliability.md#route-rules) and [Errors](https://docs.perplexity.ai/docs/orchestrator/routing-and-reliability.md#errors).

> [accordion] Why Did a Different Model Answer My perplexity/auto Request?
>
> 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`.

> [accordion] Can I Choose Which Deployment Serves My Request?
>
> 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](https://docs.perplexity.ai/docs/orchestrator/routing-and-reliability.md).

> [accordion] Do Multi-Turn Conversations Stay on One Deployment?
>
> 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?](#reasoning-and-caching) for each model family's cache markers.

> [accordion] What Happens When a Deployment Fails?
>
> 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.

> [accordion] What Happens If a Stream Fails?
>
> 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

> [accordion] Why Did I Get 'Invalid model'?
>
> 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](https://docs.perplexity.ai/docs/orchestrator/models.md) 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.

> [accordion] Why Does a Request Seem to Hang Before the First Token?
>
> 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.

> [accordion] Why Did I Get HTTP 402 or 403?
>
> These status codes mean your API organization cannot use the requested model:
>
> | Status | Message | Cause and fix |
> | - | - | - |
> | 402 | `The requested model 'anthropic/claude-opus-5-5' is not available for use with promotional credits.` | Your usage tier is below the model's minimum. Pick a model your tier can use, or move up a [usage tier](https://docs.perplexity.ai/docs/admin/rate-limits-usage-tiers.md). See [Which Models Can I Use?](#access-and-setup). |
> | 403 | `This API key is not allowed to access non-ZDR models. The requested model "anthropic/claude-fable-5-2" is a non-ZDR model. Contact api@perplexity.ai to request access.` | Your organization has zero data retention enabled, and the model does not support it. Pick another model. |
> | 403 | ``Your organization's API access settings do not allow the model `openai/gpt-6-luna`. Ask a project admin to change them.`` | Your organization's API access settings exclude the model. Ask a project admin to allow it. |
> | 403 | `Your organization does not have access to this model.` | An access restriction set for your organization excludes the model. Contact [api@perplexity.ai](mailto:api@perplexity.ai). |
>
> 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.

> [accordion] Which Request Fields Return 'unsupported' or 'unknown field'?
>
> The Orchestrator API validates the fields each format accepts and returns HTTP 400 with the exact problem in `error.message`:
>
> | Request | Message |
> | - | - |
> | `thinking` on `/chat/completions` | `invalid request body: json: unknown field "thinking"` |
> | `store: true` on `/responses` | `store=true is not supported: this endpoint is stateless; omit store or set it to false` |
> | `previous_response_id` on `/responses` | `previous_response_id is not supported: this endpoint is stateless` |
> | `conversation` on `/responses` | `conversation is not supported: this endpoint is stateless` |
> | `background: true` on `/responses` | `background=true is not supported by this endpoint` |
> | `reasoning_effort: "pro"` | `unsupported reasoning_effort value "pro"` |
> | `service_tier: "scale"` | `service_tier "scale" is not supported by this endpoint` |
> | `service_tier: "ultrafast"` | `unsupported service_tier value "ultrafast"` |
> | `routing` without `model: "perplexity/auto"` | `routing requires model perplexity/auto` |
>
> `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.

> [accordion] How Do Safety Identifiers Affect My Requests?
>
> 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](https://docs.perplexity.ai/docs/admin/safety-identifiers.md).

> [accordion] Why Is content Empty When finish\_reason Is length?
>
> 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.

> [accordion] How Do I Handle 401, 429, and 5xx Errors?
>
> 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](https://docs.perplexity.ai/docs/resources/faq.md#errors-%26-troubleshooting) for each status code.
