Repository navigation
Feature request: Allow overriding / per-request HTTP headers (e.g. for Langfuse, tracing, custom auth) #731
Description
Many observability / tracing tools (Langfuse, Helicone, OpenLLMetry, Phoenix, etc.) in AI gateways (LiteLLM) rely on sending custom HTTP headers with every OpenAI request (e.g. langfuse-trace-id, trace-id, x-helicone-id, X-Request-ID).
Currently the only way to add custom headers is globally via withHttpHeader() on the factory — which means you have to create a completely new client instance for every request that needs different headers.
This leads to very verbose and repetitive code, especially in applications that trace many LLM calls in one flow.
Describe the solution you'd like
It would be great to have at least one of these options:
- Per-request header override (most useful):
$client->chat()->create([
'model' => 'gpt-4o-mini',
'messages' => [...],
], extraHeaders: [
'langfuse-trace-id' => $traceId,
'langfuse-session-id' => $sessionId,
]);
Activity
iBotPeaches commentedon Jan 13, 2026
Yeah its a tough spot for the library at the moment. We spin up the HTTP library so early because we need to determine what library we even have - which means it gets pretty rigid once we are in userland.
Thankfully for adding headers we can apply those on a per-basis after this pr: https://github.com/openai-php/client/pull/688/changes
However, from pure userland like you describe that isn't possible due to the strict typing since you can only control parameters and don't have access to transporter. Best hacky workaround I can think of is some key we know will be unused like
_headersand strip that out of outgoing payload, but use that apply extra headers.However that falls apart for some endpoint/functions that had no parameters in the first place. Adding a 2nd optional parameter to everything seems terrible - so still need to think this out.
[-]eature request: Allow overriding / per-request HTTP headers (e.g. for Langfuse, tracing, custom auth)[/-][+]Feature request: Allow overriding / per-request HTTP headers (e.g. for Langfuse, tracing, custom auth)[/+]