Skip to content

Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.

fix(proxy): forward x-litellm-key-* headers on streaming path (#2532)

Bartosz Oudekerk33ade5b0e101
diff --git a/headroom/proxy/handlers/streaming.py b/headroom/proxy/handlers/streaming.py
index 84fa502e0..4c853afe4 100644
--- a/headroom/proxy/handlers/streaming.py
+++ b/headroom/proxy/handlers/streaming.py
@@ -1674,13 +1674,18 @@ class StreamingMixin:
# session/weekly display would stop updating on the streaming path.
# We also forward the ``request-id`` family: clients such as Claude Code
# record it per transcript turn, and downstream usage/cost tools dedup by
- # message id + request id. The buffered (non-streaming) path already
- # forwards every upstream header, so this keeps the two paths symmetric.
+ # message id + request id. ``x-litellm-key-*`` carries the per-key
+ # spend/budget envelope a LiteLLM virtual key reports per request;
+ # downstream status widgets read it from the streaming response the
+ # same way they already do from the buffered path. The buffered
+ # (non-streaming) path already forwards every upstream header, so
+ # this keeps the two paths symmetric.
forwarded_headers = {
k: v
for k, v in upstream_response.headers.items()
if "ratelimit" in k.lower()
or k.lower().startswith("x-codex")
+ or k.lower().startswith("x-litellm-key-")
or k.lower() in ("request-id", "anthropic-request-id", "x-request-id")
}
# Headroom's own compression metrics, as the buffered path stamps them.
diff --git a/tests/test_proxy_streaming_ratelimit_headers.py b/tests/test_proxy_streaming_ratelimit_headers.py
index e583250a0..d3e175f26 100644
--- a/tests/test_proxy_streaming_ratelimit_headers.py
+++ b/tests/test_proxy_streaming_ratelimit_headers.py
@@ -297,6 +297,58 @@ class TestStreamingRatelimitHeaderForwarding:
assert result.headers.get("x-request-id") == "req-ccc"
assert result.headers.get("cf-ray") is None
+ @pytest.mark.asyncio
+ async def test_litellm_key_headers_forwarded_in_streaming(self):
+ """The x-litellm-key-* family is forwarded on the streaming path.
+
+ LiteLLM virtual-key spend/budget headers (``x-litellm-key-spend``,
+ ``x-litellm-key-budget-remaining``, etc.) are dropped on the streaming
+ path because they match no allowlist clause, even though the buffered
+ path forwards every upstream header. Downstream status widgets that
+ read them from the streaming response stop updating — the same class
+ of omission fixed for ``*ratelimit*``, ``x-codex-*`` and ``request-id``.
+ """
+ proxy = self._create_mock_proxy()
+ mock_response = self._create_mock_upstream_response()
+ mock_response.headers = httpx.Headers(
+ {
+ "content-type": "text/event-stream",
+ "x-litellm-key-spend": "12.847",
+ "x-litellm-key-budget-remaining": "87.153",
+ # Non-allowlisted header: must NOT be forwarded.
+ "cf-ray": "ray-456",
+ }
+ )
+
+ mock_request = MagicMock()
+ proxy.http_client.build_request = MagicMock(return_value=mock_request)
+ proxy.http_client.send = AsyncMock(return_value=mock_response)
+
+ result = await proxy._stream_response(
+ url="https://api.anthropic.com/v1/messages",
+ headers={"x-api-key": "sk-test"},
+ body={
+ "model": "claude-sonnet-4-20250514",
+ "max_tokens": 100,
+ "stream": True,
+ "messages": [{"role": "user", "content": "hi"}],
+ },
+ provider="anthropic",
+ model="claude-sonnet-4-20250514",
+ request_id="test-litellm-key",
+ original_tokens=10,
+ optimized_tokens=10,
+ tokens_saved=0,
+ transforms_applied=[],
+ tags={},
+ optimization_latency=0.0,
+ )
+
+ assert result.media_type == "text/event-stream"
+ assert result.headers.get("x-litellm-key-spend") == "12.847"
+ assert result.headers.get("x-litellm-key-budget-remaining") == "87.153"
+ assert result.headers.get("cf-ray") is None
+
@pytest.mark.asyncio
async def test_no_ratelimit_headers_still_works(self):
"""When upstream has no ratelimit headers, streaming should still work."""