Route requests to specific AI providers

Summary

When multiple AI providers support the same model, Braintrust automatically load balances requests across all available providers. Use the x-bt-endpoint-name header to override this behavior and route requests to a specific provider credential. Note: This feature is only available through API calls and cannot be configured in the Braintrust UI.

Applicable To

Plans: Any

Deployments: Any

Configuration Steps

Step 1: Identify provider credential name

Find the credential name from the AI providers settings page (e.g., AWS_DEFAULT_CREDENTIALS, GOOGLE_DEFAULT_CREDENTIALS, OPENAI_API_KEY). 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