[DOCS] LLM gateway docs missing `X-Claude-Code-Session-Id` header guidance

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/llm-gateway

Section/Topic

Gateway requirements, especially request-header guidance for proxies and LLM gateways that do usage tracking or audit logging

Current Documentation

The docs currently say:

LLM gateways provide a centralized proxy layer between Claude Code and model providers, often providing: Centralized authentication - Single point for API key management Usage tracking - Monitor usage across teams and projects Cost controls - Implement budgets and rate limits Audit logging - Track all model interactions for compliance * Model routing - Switch between providers without code changes

And under gateway requirements:

1. Anthropic Messages: /v1/messages, /v1/messages/count_tokens Must forward request headers: anthropic-beta, anthropic-version 3. Vertex rawPredict: :rawPredict, :streamRawPredict, /count-tokens:rawPredict Must forward request headers: anthropic-beta, anthropic-version Failure to forward headers or preserve body fields may result in reduced functionality or inability to use Claude Code features.

The environment variables reference also says:

ANTHROPIC_BASE_URL | Override the API endpoint to route requests through a proxy or gateway.

No current page documents X-Claude-Code-Session-Id or explains that proxies can use it to correlate requests from the same Claude Code session without parsing request bodies.

What's Wrong or Missing?

Changelog v2.1.86 added a new request header specifically for proxy/session aggregation:

Added X-Claude-Code-Session-Id header to API requests so proxies can aggregate requests by session without parsing the body

The docs currently explain proxy/gateway routing and list other Claude Code request headers that matter to gateways, but they do not tell operators:

A. That Claude Code now sends X-Claude-Code-Session-Id on API requests

B. What the header means

The changelog describes it as a session-correlation header so proxies can group multiple requests from one Claude Code session.

C. Whether gateways/proxies should preserve or log this header alongside the existing forwarded-header guidance

Without that guidance, admins who rely on proxies for usage tracking or audit logging may keep parsing request bodies or miss the simpler session-correlation mechanism entirely.

Suggested Improvement

Add a short subsection to llm-gateway near Gateway requirements that documents the new header. For example:

Claude Code adds X-Claude-Code-Session-Id to API requests. The value identifies the Claude Code session that produced the request, which lets gateways and proxies group multiple requests from the same session without parsing the request body. If your gateway performs usage tracking or audit logging, preserve this header and index it alongside request metadata. If header-forwarding expectations differ by API format, document that here next to the existing anthropic-beta / anthropic-version guidance.

Optionally add a brief cross-reference from the monitoring docs so proxy-side session correlation and OpenTelemetry session.id are described consistently.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/llm-gateway | Primary gateway/proxy requirements and request-header guidance |
| https://code.claude.com/docs/en/network-config | Enterprise proxy configuration page for admins deploying Claude Code behind proxies |
| https://code.claude.com/docs/en/env-vars | ANTHROPIC_BASE_URL reference for routing requests through a proxy or gateway |
| https://code.claude.com/docs/en/monitoring-usage | Existing session.id telemetry documentation that could align with proxy-side session aggregation |

Total scope: 4 pages affected

Source: Changelog v2.1.86

Changelog entry: Added \X-Claude-Code-Session-Id\ header to API requests so proxies can aggregate requests by session without parsing the body