Research-backed calculator guide

OpenRouter BYOK key priority vs shared capacity: choose the fallback policy

Understand OpenRouter BYOK key priority, shared-capacity fallback, provider order, and the cost trade-off between resilience and billing certainty.

What “shared capacity fallback” actually controls

A BYOK credential changes which upstream account can serve a request. It does not remove OpenRouter's routing layer. OpenRouter describes two key sections. Prioritized keys are tried in their configured order before OpenRouter endpoints. Fallback keys are tried only after OpenRouter endpoints have been attempted. Multiple keys in either section are evaluated in order, and a key can be filtered by model, OpenRouter API key, or workspace member. ^{[1] [3]}

The phrase “shared capacity” refers to OpenRouter's own endpoint for that provider. When a prioritized key fails because of a rate limit, an upstream error, or an inapplicable model filter, the default setting allows the router to continue to that shared endpoint. That may improve completion reliability, but it can move inference from your provider account to OpenRouter-funded capacity. A valid key therefore does not prove that every successful request appeared on the provider invoice.

The three settings are easiest to understand as boundaries:

The last row is not a universal “never spend credits” switch. Provider routing can still move a request to another compatible provider. OpenRouter's provider-selection documentation exposes order, allow_fallbacks, only, and ignore controls for that request-level decision. ^[2]

Key priority is different from provider order

Two ordering systems are easy to conflate. Key priority orders credentials inside one provider. Provider order orders providers in a request. With no explicit order, OpenRouter says BYOK endpoints are automatically prioritized for providers where you have keys. When you provide an order list, that list decides which provider slot is considered first, but the BYOK endpoint is tried before shared capacity within a named provider's slot. ^{[1] [2]}

For example, suppose a request names anthropic first, but you have a prioritized Google Vertex key. If the request uses an explicit provider order, the order can put Anthropic's shared endpoint first, followed by the named provider slots. The exact route also depends on fallback settings, model eligibility, privacy filters, and which endpoints support the model. Do not infer the actual route from configuration alone; verify it in usage data.

A useful strict-boundary pattern is to combine the key setting with request routing:

{
  "provider": {
    "only": ["anthropic"],
    "allow_fallbacks": false
  }
}

Use only when another provider would violate a contract, regional requirement, or cost-allocation rule. Use allow_fallbacks: false when the request should fail instead of proceeding to other providers. These controls reduce resilience, so apply them to the traffic that needs a hard boundary rather than assuming every request has the same priority.

Worked cost example

Consider a Standard plan workload for one calendar month. This is an estimate, not a vendor quote, and it uses the policy terms observed on 2026-11-02:

• The workload produces $50,000 of OpenRouter list-price inference if the same traffic were served at OpenRouter's listed model/provider prices.
• All eligible requests use a prioritized BYOK key for one provider.
• The plan's current BYOK allowance is $25,000 of list-price inference per month.
• The key remains on Use shared capacity.
• The provider account's direct invoice is excluded because its negotiated price, taxes, credits, and provider-side billing are unknown.
• Shared-capacity usage is measured separately from the BYOK-fee calculation.

The estimated OpenRouter BYOK platform fee is:

excess list-price inference = $50,000 - $25,000 = $25,000
BYOK platform fee           = $25,000 × 5% = $1,250

That $1,250 is an OpenRouter credit deduction under the current published policy. It is not the provider's inference bill. If 3% of 100,000 monthly requests fail over to shared capacity, that is 3,000 fallback requests. If your measured average shared-capacity inference cost is $0.012 per completed request, the separate fallback estimate is:

shared-capacity fallback estimate = 3,000 × $0.012 = $36

The $0.012 is an explicit workload assumption, not an OpenRouter quote. Replace it with the actual model and token mix from your Activity export. Under these assumptions, the OpenRouter-side estimate is $1,286 ($1,250 BYOK fee plus $36 of shared-capacity inference), while the upstream provider invoice remains a separate unknown. If strict provider ownership changes the policy so those 3,000 requests fail instead, the $36 estimate may disappear, but your application now carries retry, incident, and availability costs that are not included in this arithmetic.

The practical break-even question is therefore not “Is BYOK 5%?” Ask instead: how much traffic leaves the BYOK path, what does each fallback route cost, and what is one failed request worth to the product? The OpenRouter effective cost calculator can hold the token and route assumptions, while the model pricing comparison helps you normalize the model/provider rates used in the estimate. If you need to rebuild the token inputs, use the AI token cost calculator.

![OpenRouter effective cost calculator showing the calculator context for modeling provider and routing costs.]

A policy choice that matches failure tolerance

Use a resilient policy when a completed answer is more valuable than strict provider attribution. Put the primary credential in the prioritized section, keep shared capacity enabled, and monitor the serving provider. This works well for user-facing chat, experimentation, and workloads that can accept a different compatible endpoint. It also requires a budget alert because a rate-limit incident can increase OpenRouter-funded usage without changing application request volume.

Use a provider-pinned policy when the provider account carries a negotiated rate, a data-processing agreement, a region constraint, or a finance requirement that every request reconcile to one vendor. Set the strongest shared-capacity restriction for the provider, use provider.only when cross-provider fallback is unacceptable, and make errors visible to the application. A request that fails is operationally different from a request that silently completes on another endpoint.

Use a model-scoped policy when only selected models need the hard boundary. This is often a safer migration step than applying a provider-wide restriction: constrain the contract-sensitive models, keep broader experimentation flexible, and review whether the key's model filter matches the model IDs actually sent by the application. The API reference describes allowed_models, is_required, is_byok_only, and is_fallback as distinct credential controls; do not substitute one flag for another without testing the resulting route. ^[3]

How to verify what actually happened

Configuration is a hypothesis until a request is observed. Create a test matrix with one healthy key, one deliberately ineligible model filter, and one simulated provider error where your provider permits safe testing. For every test, record the OpenRouter application key, workspace, requested model, requested provider controls, serving provider, and whether OpenRouter credits changed.

OpenRouter's FAQ says the Activity page can show historic usage and filter it by model, provider, and API key. ^[5] Use that record to distinguish at least four outcomes: the prioritized BYOK key served the request; the same provider's shared capacity served it; a fallback-section key served it; or another provider served it. If the provider differs from the credential you expected, investigate provider order, model eligibility, privacy policy, and fallback settings before rotating a valid secret.

Reconcile monthly in two passes. First, match provider-side usage to the upstream invoice using the provider account and model. Second, match OpenRouter Activity and credits to BYOK platform fees and shared-capacity inference. Do not use a top-up amount as proof that one request used shared capacity: a credit purchase can cover several kinds of deductions. Also keep the checked date with the policy snapshot because the allowance, fee, and UI labels can change.

Common mistakes to avoid

Treating BYOK as a billing switch. BYOK selects a credential path, but the provider may still bill inference directly and OpenRouter may charge its own fee or use shared capacity after failure.

Putting a backup key in the wrong section. A key in the fallback section is intentionally after OpenRouter endpoints. If you want a second provider credential before shared capacity, use the prioritized section and order it explicitly. ^[1]

Assuming “Never use shared capacity” blocks every alternate provider. It blocks the named provider's shared endpoint. It does not, by itself, prevent a different compatible provider from completing the request. ^{[1] [2]}

Ignoring model filters. A key that applies only to selected model slugs will not serve other models. Those requests may use shared capacity or another provider, depending on the rest of the route.

Comparing request counts to a dollar allowance. The current published BYOK allowance is measured in list-price inference dollars, not a fixed number of requests. Two requests with very different token volumes are not equivalent for this purpose. ^{[4] [5]}

Mixing estimates with vendor quotes. The worked example's 3% fallback rate and $0.012 per-request assumption are planning inputs. Replace them with observed usage and current model prices before approving a budget.

FAQ

Does OpenRouter always try my BYOK key first?

Not in every possible request configuration. A prioritized key is designed to run before shared capacity for its provider, and OpenRouter says BYOK endpoints are automatically prioritized when no provider order is supplied. An explicit provider order can change which provider slot is considered first. Within a named provider slot, the BYOK endpoint is tried before that provider's shared capacity. Model filters, privacy requirements, and request restrictions can still make a key ineligible. ^{[1] [2]}

What is the safest default for avoiding unexpected OpenRouter credit usage?

For a provider-specific boundary, use Never use shared capacity for any model on this provider and restrict the request with provider.only when another provider is also unacceptable. Then test failure behavior and monitor Activity. This is not the highest-availability default: exhausted keys or provider outages can become errors. If availability is more important, keep shared capacity enabled but budget and alert for the fallback route.

Does the strongest shared-capacity setting stop cross-provider fallback?

No. It removes OpenRouter's shared endpoint for that provider. A compatible model can still be served by another provider unless the request restricts providers. Use provider.only for a hard provider boundary and consider allow_fallbacks: false when the request must fail rather than move to another provider. ^{[1] [2]}

Are fallback requests charged twice?

An errored attempt is not automatically the same as two completed inferences. OpenRouter's FAQ says a provider error can trigger another provider and that failed attempts are not charged for their model tokens; the request that completes is the one to reconcile. ^[4] Still, auxiliary services or application retries can create separate costs, so compare request IDs, token usage, and provider records rather than assuming every retry is free.

How do I calculate the BYOK fee for a month?

Start with list-price inference value for the same model/provider traffic, not request count and not necessarily the discounted upstream invoice. Subtract the plan's fee-free allowance, floor the result at zero, and multiply the excess by the published BYOK fee rate. For the 2026-11-02 Standard/Business terms checked here: max(0, list-price inference - $25,000) × 5%. Treat Enterprise as custom, and record the date because pricing can change. ^{[4] [5]}

Which page should I use to estimate tokens and model rates?

Use the AI token cost calculator for input/output token assumptions, the model pricing comparison for normalized model/provider rates, and the OpenRouter effective cost calculator for the combined route and billing scenario. Replace estimates with Activity and provider-invoice evidence after the workload runs.

Limitations and assumptions

This guide describes the OpenRouter policy and pricing pages checked on 2026-11-02. It does not promise a particular provider, latency, uptime, fee, ranking, or cost outcome. Exact routing can depend on model availability, key filters, provider policies, regional endpoints, privacy controls, request fields, and changes made after the checked date. The worked calculation excludes taxes, negotiated provider discounts, credit-purchase fees, application retries, engineering time, and the business cost of failed requests. Treat the route matrix as a reviewable policy artifact, not a substitute for a controlled test and invoice reconciliation.