Route requests to specific AI providers

Summary

When multiple providers are eligible for a model request, the legacy AI proxy distributes requests by randomly choosing which provider to try first. Use the x-bt-endpoint-name header to select a specific eligible provider instead. Provider permissions, model restrictions, and project overrides still apply.

Note: This routing preference is set on individual API requests and cannot be configured in the Braintrust UI.

The Gateway also supports this header, but uses different provider selection rules. The generated Gateway command on a provider’s Models tab includes the header to select that provider.

Configuration Steps

Step 1: Identify provider credential name

Find the configuration name in Settings > AI providers. For built-in providers, use the identifier beneath the friendly name, such as AWS_DEFAULT_CREDENTIALS, GOOGLE_DEFAULT_CREDENTIALS, or OPENAI_API_KEY. For custom providers, use the exact name, including capitalization. Alternatively, retrieve available providers using the List AI secrets API endpoint.

Step 2: Add header to API requests

Include the x-bt-endpoint-name header with the provider credential name as the value in your API calls.

curl -X POST "https://api.braintrust.dev/v1/proxy/chat/completions" \
  -H "Authorization: Bearer $BRAINTRUST_API_KEY" \
  -H "Content-Type: application/json" \
  -H "x-bt-endpoint-name: OPENAI_API_KEY" \
  -d '{
    "model": "gpt-5",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Step 3: Verify provider selection

Check the x-bt-used-endpoint response header to confirm which provider handled the request.

curl -i https://api.braintrust.dev/v1/proxy/chat/completions \
  -X POST \
  -H "Authorization: Bearer $BRAINTRUST_API_KEY" \
  -H "Content-Type: application/json" \
  -H "x-bt-endpoint-name: OPENAI_API_KEY" \
  -d '{
    "model": "gpt-5",
    "messages": [
      { "role": "user", "content": "Hello" }
    ]
  }'

# Response will include header:
# x-bt-used-endpoint: OPENAI_API_KEY

​Summary

​Configuration Steps

​Step 1: Identify provider credential name

​Step 2: Add header to API requests

​Step 3: Verify provider selection

Summary

Configuration Steps

Step 1: Identify provider credential name

Step 2: Add header to API requests

Step 3: Verify provider selection