Skip to main content

Routing

client.routing controls how the gateway selects a provider for each request. See Routing concepts for a full explanation of strategies.

Get the current config​

const config = await client.routing.getConfig();
console.log(config.strategy, config.policy?.fallbackBehavior);

Update routing config​

await client.routing.updateConfig({
  strategy: 'balanced',   // 'balanced' | 'cheapest' | 'fastest' | 'highest_quality' | 'manual'
  policy:   { fallbackBehavior: 'allow_commercial' },
});

See Fallback for what fallbackBehavior actually controls. It decides what happens when no provider passes your policy constraints, not whether the gateway retries on a provider error.

Model aliases​

Aliases let you decouple model names in your application from actual provider models. Your code calls model: 'smart' and the gateway resolves it to the real model.

// Create or update an alias
await client.routing.setAlias('smart',  'gpt-4o');
await client.routing.setAlias('fast',   'gpt-4o-mini');
await client.routing.setAlias('coding', 'claude-sonnet-4-6');

// List all aliases
const aliases = await client.routing.listAliases();
// [{ alias: 'smart', model: 'gpt-4o' }, ...]

// Delete an alias
await client.routing.deleteAlias('coding');

Using the alias in a chat call:

await client.chat.complete({
  model:    'smart',   // resolves to gpt-4o at gateway level
  messages: [{ role: 'user', content: 'Review this code.' }],
});

Routing history​

Inspect how recent requests were routed:

const { decisions, total } = await client.routing.listHistory({
  limit:    20,
  offset:   0,
  provider: 'openai',   // optional filter
  strategy: 'balanced',  // optional filter
  status:   'success',  // optional filter
});

const detail = await client.routing.getDecision(decisions[0].id);
console.log(detail.selectedProvider, detail.candidates);