Passthrough - Portkey Docs

The Passthrough provider allows you to send requests exactly as they are to any backend provider, without Portkey’s usual parameter mapping or validation. This is not recommended because you lose out on features like cost attribution and rate limiting, but useful when you need full control over the request body or when working with provider-specific features that aren’t part of the standard API signatures.

Passthrough vs standard providers

Feature	Regular Providers	Passthrough Provider
Parameter validation	Strict - only base signature parameters allowed	None - all parameters forwarded as-is
Request transformation	Portkey maps parameters to unified format	No transformation - request sent unchanged
Response transformation	Response is transformed to unified format	No transformation - response sent unchanged
Provider-specific params	May be rejected or ignored	Fully supported
Unified routes	Parameters normalized across providers	Original request body preserved
Header forwarding	Portkey manages headers	All non-`x-portkey-*` headers forwarded to endpoint
Target endpoint	Configured per provider	Set via `x-portkey-custom-host` header
Error handling	Standardized error responses	Raw provider errors returned
Use case	Cross-provider compatibility	Direct provider access with full control

With standard providers like Anthropic or OpenAI, Portkey validates and transforms your request to match the expected API signature. With Passthrough, your request body is forwarded directly to the target endpoint without any modifications.

When to use Passthrough

Provider-specific parameters: When you need to use parameters that aren’t in Portkey’s standard API signatures
Direct API access: When you want to interact with a provider’s API exactly as documented
Custom integrations: When working with endpoints or features not yet mapped by Portkey
Debugging: When you need to see exactly what the provider receives

Quick start

cURL

curl https://api.portkey.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "x-portkey-api-key: $PORTKEY_API_KEY" \
  -H "x-portkey-provider: passthrough" \
  -H "x-portkey-custom-host: https://my.vllm.com/v1" \
  -H "authorization: Bearer sk-your-api-key" \
  -H "my-custom-header: my-custom-value" \
  -d '{
    "model": "my-custom-vllm-model",
    "stream": true,
    "max_completion_tokens": 1000,
    "random-key": "value",
    "messages": [
      { "role": "developer", "content": "You are a helpful assistant" },
      { "role": "user", "content": "Hello!" }
    ]
  }'

Required headers

Header	Description
`x-portkey-api-key`	Your Portkey API key
`x-portkey-provider`	Set to `passthrough`
`x-portkey-custom-host`	The base URL of your target endpoint (e.g., `https://my.vllm.com/v1`)

Header forwarding

All headers except those starting with x-portkey- are forwarded to the target endpoint. This includes:

authorization - Your target provider’s API key
Content-Type - Request content type
Any custom headers your endpoint requires

from portkey_ai import Portkey

portkey = Portkey(
    api_key="PORTKEY_API_KEY",
    provider="passthrough",
    custom_host="https://my.vllm.com/v1",
    default_headers={
        "my_custom_header": "abc"
    }
)

# Request body is sent directly without transformation
response = portkey.chat.completions.create(
    model="my-custom-vllm-model",
    messages=[{"role": "user", "content": "Hello!"}],
    # Any parameters you include are passed through unchanged
    stream=True,
    max_completion_tokens=1000,
    random_key="value"  # Custom parameters supported
)

print(response.choices[0].message.content)

import Portkey from 'portkey-ai'

const portkey = new Portkey({
    apiKey: "PORTKEY_API_KEY",
    provider: "passthrough",
    customHost: "https://my.vllm.com/v1",
    defaultHeaders: {
        "my-custom-header": "abc"
    }
})

// Request body is sent directly without transformation
const response = await portkey.chat.completions.create({
    model: "my-custom-vllm-model",
    messages: [{ role: "user", content: "Hello!" }],
    // Any parameters you include are passed through unchanged
    stream: true,
    max_completion_tokens: 1000,
    random_key: "value"  // Custom parameters supported
})

console.log(response.choices[0].message.content)

from openai import OpenAI
from portkey_ai import PORTKEY_GATEWAY_URL, createHeaders

client = OpenAI(
    api_key="PORTKEY_API_KEY",
    base_url=PORTKEY_GATEWAY_URL,
    default_headers=createHeaders(
        provider="passthrough",
        custom_host="https://my.vllm.com/v1",
        my_custom_header="abc"
    )
)

response = client.chat.completions.create(
    model="my-custom-vllm-model",
    messages=[{"role": "user", "content": "Hello!"}]
)

print(response.choices[0].message.content)

import OpenAI from "openai"
import { PORTKEY_GATEWAY_URL, createHeaders } from "portkey-ai"

const client = new OpenAI({
    apiKey: "PORTKEY_API_KEY",
    baseURL: PORTKEY_GATEWAY_URL,
    defaultHeaders: createHeaders({
        provider: "passthrough",
        customHost: "https://my.vllm.com/v1",
        myCustomHeader: "abc"
    })
})

const response = await client.chat.completions.create({
    model: "my-custom-vllm-model",
    messages: [{ role: "user", content: "Hello!" }]
})

console.log(response.choices[0].message.content)

Configuration

Passthrough requires you to specify the target endpoint using the x-portkey-custom-host header. This tells Portkey where to forward your requests.

x-portkey-custom-host: https://your-endpoint.com/v1

The path from your request (e.g., /chat/completions) is appended to this base URL.

How it works

When you use the Passthrough provider with any unified route (like /v1/chat/completions or /v1/messages), Portkey:

Receives your request as-is without validating against standard parameter signatures
Forwards the entire request body directly to the configured backend
Returns the response from the provider without transformation

This differs from standard providers where Portkey normalizes parameters, validates required fields, and transforms requests to match each provider’s API format.

Example: Standard vs Passthrough

Standard provider (Anthropic):

// Your request
{
  "model": "@anthropic/claude-sonnet-4-5-20250929",
  "messages": [{"role": "user", "content": "Hi"}],
  "unknown_param": "value"  // This may be rejected or ignored
}

// Portkey validates and transforms before sending to Anthropic

Passthrough provider:

// Your request - with x-portkey-custom-host header set
{
  "model": "claude-sonnet-4-5-20250929",
  "messages": [{"role": "user", "content": "Hi"}],
  "unknown_param": "value"  // Passed through unchanged
}

// Sent directly to the backend exactly as provided

Header behavior

When you send a request through Passthrough:

Header type	Behavior
`x-portkey-*` headers	Used by Portkey, not forwarded
`authorization`	Forwarded to target endpoint
`Content-Type`	Forwarded to target endpoint
Custom headers	Forwarded to target endpoint

This allows you to pass authentication and custom headers directly to your target provider.

Supported routes

Passthrough works with all unified routes:

/v1/chat/completions - Chat completions
/v1/messages - Anthropic-style messages
/v1/completions - Text completions
/v1/embeddings - Embeddings
Any other supported endpoint

The key difference is that no parameter mapping or validation is applied—your request body reaches the provider exactly as you sent it.

Use cases

Provider-specific features

Use parameters that are unique to a specific provider:

response = portkey.chat.completions.create(
    model="@passthrough/model-name",
    messages=[{"role": "user", "content": "Analyze this"}],
    # Provider-specific parameters passed through directly
    provider_specific_mode="advanced",
    custom_sampling_params={"top_k": 50, "repetition_penalty": 1.2}
)

const response = await portkey.chat.completions.create({
    model: "@passthrough/model-name",
    messages: [{ role: "user", content: "Analyze this" }],
    // Provider-specific parameters passed through directly
    provider_specific_mode: "advanced",
    custom_sampling_params: { top_k: 50, repetition_penalty: 1.2 }
})

Self-hosted vLLM or custom endpoints

Connect to your own vLLM deployment or any OpenAI-compatible endpoint:

cURL

curl https://api.portkey.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "x-portkey-api-key: $PORTKEY_API_KEY" \
  -H "x-portkey-provider: passthrough" \
  -H "x-portkey-custom-host: https://my.vllm.com/v1" \
  -H "authorization: Bearer $VLLM_API_KEY" \
  -d '{
    "model": "my-custom-model",
    "messages": [{"role": "user", "content": "Hello"}],
    "max_completion_tokens": 1000,
    "experimental_feature": true,
    "custom_config": {
      "nested": "parameters",
      "are": "supported"
    }
  }'

Gateway features

Passthrough requests still benefit from Portkey’s gateway features:

Observability: Full logging and monitoring of requests/responses
Caching: Response caching works as expected
Rate limiting: Budget and rate controls apply
Retries: Automatic retry logic on failures
Fallbacks: Configure fallback providers in your config

Next steps

Add Metadata

Add metadata to your Passthrough requests

Gateway Configs

Configure fallbacks, retries, and caching

Tracing

Trace your Passthrough requests

Model Catalog

Set up your Passthrough provider

​Passthrough vs standard providers

​When to use Passthrough

​Quick start

​Required headers

​Header forwarding

​Configuration

​How it works

​Example: Standard vs Passthrough

​Header behavior

​Supported routes

​Use cases

​Provider-specific features

​Self-hosted vLLM or custom endpoints

​Gateway features

​Next steps

Add Metadata

Gateway Configs

Tracing

Model Catalog

Passthrough vs standard providers

When to use Passthrough

Quick start

Required headers

Header forwarding

Configuration

How it works

Example: Standard vs Passthrough

Header behavior

Supported routes

Use cases

Provider-specific features

Self-hosted vLLM or custom endpoints

Gateway features

Next steps