Skip to main content
The gateway reads x-portkey-* headers to control routing, authentication, and observability. All other headers are forwarded to the target provider unchanged.

​
Required headers

Every request must include at least one of the following two headers:
​
x-portkey-provider
string
The target LLM provider to route the request to. Must be a recognized provider slug.Examples: openai, anthropic, bedrock, vertex-ai, azure-openai, groq, mistral-ai, cohere, together-ai, deepseek, ollamaRequired unless x-portkey-config is provided with a provider or targets field.
​
x-portkey-config
string (JSON)
A JSON object that configures routing, reliability, and guardrail behavior. Accepts either a JSON string or a base64-encoded JSON string.When this header is used, the config must contain either a provider field or a targets array. If x-portkey-provider is also present, it takes precedence for provider selection.
{
  "provider": "openai",
  "api_key": "sk-...",
  "retry": { "attempts": 3 },
  "cache": { "mode": "simple" }
}
For advanced routing (fallback, load balancing):
{
  "strategy": { "mode": "fallback" },
  "targets": [
    { "provider": "openai", "api_key": "sk-..." },
    { "provider": "anthropic", "api_key": "sk-ant-..." }
  ]
}

​
Authentication headers

​
Authorization
string
The provider API key, formatted as a Bearer token. Forwarded to the target provider.Example: Bearer sk-abc123
​
x-portkey-api-key
string
Your Portkey API key, used with the Portkey hosted service. When present, Portkey handles provider credential resolution via virtual keys.Example: pk-abc123
​
x-portkey-virtual-key
string
A virtual key identifier stored in Portkey’s key vault. The gateway resolves it to the actual provider API key at request time. Available on the hosted service.Example: openai-prod-key

​
Observability headers

​
x-portkey-trace-id
string
A custom trace ID to attach to the request for log correlation. If not provided, the gateway generates one automatically.Example: req_abc123xyz
​
x-portkey-metadata
string (JSON)
A JSON object of key-value pairs attached to the request for use in routing conditions, logging, and analytics.Keys and values must be strings.
{"environment": "production", "user_id": "u_123", "team": "search"}

​
Routing and behavior headers

​
x-portkey-custom-host
string
Override the provider’s default API base URL. Useful for self-hosted models or custom inference endpoints.Must be a valid http:// or https:// URL. Private IP ranges, cloud metadata endpoints, and non-HTTP schemes are blocked.Example: https://my-llm-endpoint.example.com
​
x-portkey-forward-headers
string (JSON array)
A JSON array of header names that should be forwarded as-is to the provider. By default, x-portkey-* headers are stripped before forwarding.Example: ["x-my-custom-header", "x-request-id"]
​
x-portkey-request-timeout
number
Request timeout in milliseconds. If the provider does not respond within this duration, the request is terminated.Example: 30000
​
x-portkey-cache
string
Cache mode for this request. Supported values: simple, semantic.
  • simple — exact-match cache based on request body hash.
  • semantic — similarity-based cache (hosted service only).
Example: simple
​
x-portkey-cache-force-refresh
string
When present (any value), bypasses the cache and forces a fresh request to the provider. The response is written back to the cache.
​
x-portkey-strict-open-ai-compliance
boolean
When set to true, the gateway strips non-OpenAI-standard fields from the response before returning it to the client.Example: true
​
x-portkey-mode
string
Explicitly sets the routing mode. In most cases this is controlled through x-portkey-config. Accepted values mirror the config strategy.mode options: single, fallback, loadbalance, conditional.

​
Response headers

The gateway adds these headers to every response:
HeaderDescription
x-portkey-trace-idThe trace ID for the request (echoed back or generated).
x-portkey-cache-statusCache result: HIT, MISS, SEMANTIC HIT, REFRESH, or DISABLED.
x-portkey-retry-attempt-countNumber of retry attempts made before a successful response.
x-portkey-last-used-option-indexIndex of the target option selected during load balancing or fallback.
x-portkey-last-used-option-paramsParameters of the target option that was ultimately used.

​
Retry counter

​
x-portkey-retry-count
number
Set by the gateway internally on retried requests to track the current retry attempt number. This header is not intended to be set by clients.

​
Provider-specific headers

Some providers require additional credentials or configuration passed via dedicated x-portkey-* headers. These are used when the corresponding config fields are not available in x-portkey-config.

​
AWS Bedrock

HeaderDescription
x-portkey-aws-access-key-idAWS access key ID.
x-portkey-aws-secret-access-keyAWS secret access key.
x-portkey-aws-session-tokenAWS session token (for temporary credentials).
x-portkey-aws-regionAWS region (e.g., us-east-1).
x-portkey-aws-role-arnIAM role ARN for assumed-role authentication.
x-portkey-aws-auth-typeAuthentication type (e.g., assumedRole).

​
Azure OpenAI

HeaderDescription
x-portkey-azure-resource-nameAzure resource name.
x-portkey-azure-deployment-idAzure deployment ID.
x-portkey-azure-api-versionAzure API version.
x-portkey-azure-ad-tokenAzure AD bearer token.
x-portkey-azure-auth-modeAzure authentication mode.

​
Google Vertex AI

HeaderDescription
x-portkey-vertex-project-idGoogle Cloud project ID.
x-portkey-vertex-regionVertex AI region (e.g., us-central1).
x-portkey-vertex-storage-bucket-nameGCS bucket name for batch operations.

​
Anthropic

HeaderDescription
x-portkey-anthropic-versionAnthropic API version string.
x-portkey-anthropic-betaAnthropic beta feature flag.
Provider-specific headers that are not listed here can be passed using x-portkey-forward-headers to have them forwarded directly to the provider.

Build docs developers (and LLMs) love

Get started for freeTalk to us