Provider pinning

Force a specific EU provider per request — and what happens when it can't serve the model.

When you need a hard guarantee (regulatory, performance test, data residency audit), pin a provider. Strategy hints become irrelevant once you pin.

Headers vs SDK options

SDK option	HTTP header	Values
`provider`	`X-CleverRouter-Provider`	`scaleway`, `tensorix`, `bedrock`
`strategy`	`X-CleverRouter-Strategy`	`cheapest`, `fastest`, `best`, `default`

The SDK turns its options into headers — the two paths are equivalent.

Default for every call

cr.ts

import { createCleverRouter } from '@cleverrouter/sdk';

export const cr = createCleverRouter({
  apiKey: process.env.CLEVERROUTER_API_KEY!,
  provider: 'scaleway',
});

Every call from this instance pins to Scaleway — including cr.openai() (the header rides in defaultHeaders).

Per-call override

await cr.chat(
  { model: 'meta/llama-3.3-70b', messages },
  { provider: 'tensorix' },
);

await cr.stream(
  { model: 'mistral/mistral-small-3.2', messages },
  { provider: 'scaleway', strategy: 'cheapest' },
);

await cr.embed(['hello'], {
  provider: 'bedrock',
  model: 'cohere/embed-v4',
});

With `cr.openai()`

await cr
  .openai({
    defaultHeaders: cr.headers({ provider: 'tensorix', strategy: 'fastest' }),
  })
  .chat.completions.create({
    model: 'meta/llama-3.3-70b',
    messages: [/* ... */],
  });

cr.headers({ ... }) returns the header object built from the same options the SDK uses internally.

What happens when the pinned provider can't host the model

HTTP 400
{
  "error": {
    "message": "Provider tensorix does not host model cohere/rerank-v3-5",
    "type": "provider_unsupported",
    "code": "provider_unsupported"
  }
}

There is no silent fallback when you pin explicitly. That's the whole point — pinning is a hard guarantee.

If you want pinning with failover, the right pattern is strategy without provider. (A X-CleverRouter-Provider-Prefer soft hint is on the roadmap.)

Inspecting the chosen provider

X-CleverRouter-Provider: scaleway

This is on every successful response. With cr.chat() / cr.stream(), it's on the raw Response. With cr.openai(), OpenAI's SDK exposes it via _response.headers.

Health filter applies even when pinned

Providers marked down in the last health probe are skipped — even with an explicit pin, the gateway tells you upfront with 502 provider_down rather than silently routing somewhere else.

When to pin

Audit & compliance — you must demonstrate "every call went to Scaleway Paris" for the next 12 months.
Performance comparison — A/B testing Scaleway vs Tensorix on the same model.
Specialised endpoints — rerank only exists on Bedrock; pin to avoid surprises.
Procurement-led contract — your contract is with Scaleway, not with Clevermation as your sub-processor list intermediary.

Routing overview
Strategies — the soft-hint alternative.
Providers — what each provider hosts.

On this page