Implementation:BerriAI Litellm Passthrough Utils

Attribute	Value
Sources	`litellm/passthrough/utils.py`
Domains	Pass-Through Endpoints, Proxy, Utilities, AWS Bedrock
Last Updated	2026-02-15 16:00 GMT

Overview

BasePassthroughUtils and CommonUtils provide static utility methods for pass-through endpoint handling, including query parameter merging, header forwarding with prefix stripping, and AWS Bedrock ARN encoding.

Description

This module contains two utility classes for pass-through endpoint processing:

The BasePassthroughUtils class provides two static methods: get_merged_query_parameters merges request query parameters with existing URL parameters (giving priority to existing URL parameters), and forward_headers_from_request handles header forwarding logic. When forward_headers is True, it forwards all original request headers (excluding content-length and host) combined with custom headers. Additionally, headers prefixed with x-pass- (defined by PASS_THROUGH_HEADER_PREFIX) are always forwarded with the prefix stripped (e.g., x-pass-anthropic-beta becomes anthropic-beta).

The CommonUtils class provides encode_bedrock_runtime_modelid_arn, which encodes forward slashes in AWS Bedrock runtime endpoint ARNs to prevent them from being treated as path separators. It handles multiple resource types including application-inference-profile, foundation-model, custom-model, and others.

Usage

Import these utilities when implementing pass-through endpoints that proxy requests to external providers. BasePassthroughUtils is used for general header and query parameter handling, while CommonUtils is specifically for AWS Bedrock ARN encoding.

Code Reference

Source Location

litellm/passthrough/utils.py

Signature

class BasePassthroughUtils:
    @staticmethod
    def get_merged_query_parameters(existing_url: httpx.URL, request_query_params: Dict[str, Union[str, list]]) -> Dict[str, Union[str, List[str]]]
    @staticmethod
    def forward_headers_from_request(request_headers: dict, headers: dict, forward_headers: Optional[bool] = False) -> dict

class CommonUtils:
    @staticmethod
    def encode_bedrock_runtime_modelid_arn(endpoint: str) -> str

Import

from litellm.passthrough.utils import BasePassthroughUtils, CommonUtils

I/O Contract

Inputs

Parameter	Type	Description
`existing_url`	`httpx.URL`	The target URL with existing query parameters to preserve.
`request_query_params`	`Dict[str, Union[str, list]]`	New query parameters from the incoming request.
`request_headers`	`dict`	Headers from the original incoming request.
`headers`	`dict`	Custom headers to include in the forwarded request.
`forward_headers`	`Optional[bool]`	Whether to forward all original request headers. Defaults to `False`.
`endpoint`	`str`	The AWS Bedrock runtime endpoint string that may contain ARNs.

Outputs

Method	Return Type	Description
`get_merged_query_parameters`	`Dict[str, Union[str, List[str]]]`	Merged query parameters with existing URL params taking priority.
`forward_headers_from_request`	`dict`	The combined headers dictionary ready for the outgoing request.
`encode_bedrock_runtime_modelid_arn`	`str`	The endpoint with ARN slashes properly URL-encoded as `%2F`.

Usage Examples

from litellm.passthrough.utils import BasePassthroughUtils, CommonUtils
import httpx

# Merge query parameters
merged = BasePassthroughUtils.get_merged_query_parameters(
    existing_url=httpx.URL("https://api.example.com/v1?key=value"),
    request_query_params={"new_param": "new_value", "key": "override_ignored"},
)
# Result: {"new_param": "new_value", "key": "value"}  (existing URL takes priority)

# Forward headers with x-pass- prefix stripping
headers = BasePassthroughUtils.forward_headers_from_request(
    request_headers={"x-pass-anthropic-beta": "messages-2024-04-04", "authorization": "Bearer key"},
    headers={"Content-Type": "application/json"},
    forward_headers=False,
)
# Result: {"Content-Type": "application/json", "anthropic-beta": "messages-2024-04-04"}

# Encode Bedrock ARN
encoded = CommonUtils.encode_bedrock_runtime_modelid_arn(
    "/model/arn:aws:bedrock:us-east-1:123456:application-inference-profile/abc123/invoke"
)
# Result: "/model/arn:aws:bedrock:us-east-1:123456:application-inference-profile%2Fabc123/invoke"

Related Pages

BerriAI_Litellm_Custom_Auth_Template - Custom authentication for proxy endpoints
BerriAI_Litellm_Veo_Video_Generation_Example - Example using pass-through endpoints for Veo

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment