---
title: "Pin a Provider"
description: "Use the `only` routing option when caching, policy, or a BYOK credential requires a specific provider, and account for the reduced fallback coverage."
canonical_url: "https://vercel.com/academy/ai-gateway/pin-a-provider"
md_url: "https://vercel.com/academy/ai-gateway/pin-a-provider.md"
docset_id: "vercel-academy"
doc_version: "1.0"
last_updated: "2026-08-08T23:27:13.307Z"
content_type: "lesson"
course: "ai-gateway"
course_title: "Using AI Gateway in Production"
prerequisites:  []
---

<agent-instructions>
Vercel Academy — structured learning, not reference docs.
Lessons are sequenced.
Adapt commands to the human's actual environment (OS, package manager, shell, editor) — detect from project context or ask, don't assume.
The lesson shows one path; if the human's project diverges, adapt concepts to their setup.
Preserve the learning goal over literal steps.
Quizzes are pedagogical — engage, don't spoil.
Quiz answers are included for your reference.
</agent-instructions>

# Pin a Provider

# How Do I Pin Routing to a Specific Provider?

Most reliability strategies keep several providers available. Some workloads need the opposite: a compliance requirement may allow only one named provider, prompt caching may depend on consistent routing, or a BYOK credential may work with one host.

In those cases, restrict the eligible providers explicitly and verify that the Gateway does not silently route elsewhere.

\*\*Note: Quick Answer\*\*

Set `only: ["anthropic"]` in `providerOptions.gateway` to restrict the request to the listed providers. If none can serve the request, the Gateway returns `no_providers_available`. Use `order` when a provider is preferred but alternatives should remain eligible.

A strict provider restriction must return an error when it cannot be honored. Silent fallback would violate the configured requirement.

## Outcome

Pin the order flow to a single provider with `only`, and prove from the routing metadata that no fallbacks were considered.

## Fast Track

1. Add `only: ["anthropic"]` under `providerOptions.gateway`
2. Run `pnpm pin-provider`
3. Read `finalProvider` and the empty fallback list off the output

## Hands-on exercise

Requirements:

- A `scripts/pin-provider.ts` that sends the order-confirmation prompt to `anthropic/claude-sonnet-4.6`
- `only: ["anthropic"]`: Anthropic direct, or an error
- Print who served the request and which fallbacks were considered (the answer should be none)

Calling the provider directly would create a separate integration with its own key, billing, and observability. Keeping the request in AI Gateway preserves centralized management while enforcing the provider restriction.

## Try It

```bash
pnpm pin-provider
```

```
Three Hongos Humildes, no queso — that's $12.00 even. The mushrooms thank you.
---
Served by: anthropic
Fallbacks considered: none — pinned
```

`Served by: anthropic` identifies the selected provider, and `none — pinned` confirms that the Gateway considered no alternatives. In the outage lesson, `fallbacksAvailable` instead lists the eligible fallback providers.

Two issues you may encounter:

**You get `no_providers_available`.** The pinned provider may be unavailable or may not serve the selected model. If the provider is a preference rather than a requirement, use `order` so another eligible provider can run the request.

**Your pin names a provider that doesn't serve your model.** `only` filters the providers that exist for the model; it can't summon new ones. Check the model's page in the model list for which providers actually serve it before writing the pin into config.

\*\*Note: Pinning for the whole team\*\*

`only` applies to one request and is free. A team-wide provider allowlist is available as a paid setting on eligible plans; check the [AI Gateway pricing page](https://vercel.com/docs/ai-gateway/pricing) for current details. Use the team setting when the provider policy must cover every request.

Pinning a provider creates a single point of failure for that request. Use it for features with a clear policy, caching, or credential requirement, and leave broader routing available elsewhere.

## Commit

```bash
git commit -m "feat(routing): pin order confirmations to a single provider"
```

## Done-When

- [ ] `only` configured and the script prints the pinned provider as `finalProvider`
- [ ] Fallbacks considered: none
- [ ] You can say when you'd use `only` vs `order` in one sentence each
- [ ] You identified which features require a provider restriction and which can retain broader routing

## Solution

```ts filename="scripts/pin-provider.ts"
import { generateText } from "ai";
import { MENU } from "../lib/menu";

const result = await generateText({
  model: "anthropic/claude-sonnet-4.6",
  prompt:
    "Confirm this order back with a total: three Hongos Humildes, no " +
    `queso.\n\n${MENU}`,
  providerOptions: {
    gateway: {
      only: ["anthropic"], // this provider or an error — no silent detours
    },
  },
});

const routing = result.finalStep.providerMetadata?.gateway?.routing as any;

console.log(result.text.trim());
console.log("---");
console.log(`Served by: ${routing?.finalProvider}`);
console.log(`Fallbacks considered: ${routing?.fallbacksAvailable?.join(", ") || "none — pinned"}`);
```

The request now carries an explicit provider boundary, and the routing metadata shows whether it was honored.

## Related Questions

- [How do I survive a provider outage?](/ai-gateway/stay-reliable/provider-outage)
- [How do I fail over when a provider is slow, not just down?](/ai-gateway/stay-reliable/latency-failover)
- [How do I keep my prompts private?](/ai-gateway/stay-aware/keep-prompts-private)


---

[Full course index](/academy/llms.txt) · [Sitemap](/academy/sitemap.md)