> ## Documentation Index
> Fetch the complete documentation index at: https://docs.helicone.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Helicone Header Directory
> Comprehensive guide to all Helicone headers. Learn how to access and implement various Helicone features through custom request headers.
```bash Curl theme={null}
curl https://gateway.helicone.ai/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Helicone-Auth: Bearer $HELICONE_API_KEY" \
-H "Helicone-: "
-d ...
```
```python Python theme={null}
client = OpenAI(
base_url="https://gateway.helicone.ai/v1",
default_headers={
"Helicone-Auth": f"Bearer {HELICONE_API_KEY}",
}
)
client.chat.completions.create(
model="text-davinci-003",
prompt="This is a test",
extra_headers={
"Helicone-Auth": f"Bearer {HELICONE_API_KEY}", # required header
"Helicone-": "", # all headers will follow this format
}
)
```
```typescript Node.js v4+ theme={null}
const openai = new OpenAI({
baseURL: "https://gateway.helicone.ai/v1",
defaultHeaders: {
"Helicone-Auth": `Bearer [HELICONE_API_KEY]`, // required header
"Helicone-": "", // all headers will follow this format
},
});
```
```typescript Node.js ": "", // all headers will follow this format
},
},
});
const openai = new OpenAIApi(configuration);
```
```python Langchain (Python) theme={null}
llm = ChatOpenAI(
openai_api_key="",
openai_api_base="https://gateway.helicone.ai/v1",
headers={
"Helicone-Auth": "Bearer ", # required header
"Helicone-": "", # all headers will follow this format
}
)
```
```javascript LangChain JS theme={null}
const model = new ChatOpenAI({
azureOpenAIBasePath: "https://oai.helicone.ai",
configuration: {
organization: "[organization]",
defaultHeaders: {
"Helicone-Auth": `Bearer ${heliconeApiKey}`, // required header
"Helicone-": "", // all headers will follow this format
},
},
});
```
## Supported Headers
This is the first header you will use, which authenticates you to send requests to the Helicone API. Here's the format: `"Helicone-Auth": "Bearer "`. Remember to replace it with your actual Helicone API key.
When adding the `Helicone-Auth` make sure the key you add has `write` permissions. As of June 2024 all keys have write access.
The URL to proxy the request to when using *gateway.helicone.ai*. For example, `https://api.openai.com/`.
The URL to proxy the request to when using *oai.helicone.ai*. For example, `https://[YOUR_AZURE_DOMAIN].openai.azure.com`.
The ID of the request, in the format: `123e4567-e89b-12d3-a456-426614174000`
Overrides the model used to calculate costs and mapping. Useful for when the model does not exist in URL, request or response. For example, `gpt-4-1106-preview`.
Assigning an ID allows Helicone to associate your prompt with future versions of your prompt, and automatically manage versions on your behalf. For example, both `prompt_story` and `this is the first prompt` are valid.
Custom Properties allow you to add any additional information to your requests, such as environment, conversation, or app IDs. Here are some examples of custom property headers and values: `Helicone-Property-Session: 121`, `Helicone-Property-App: mobile`, or `Helicone-Property-MyUser: John Doe`. There are no restrictions on the value.
Specify the user making the request to track and analyze user metrics, such as the number of requests, costs, and activity associated with that particular user. For example, `alicebob@gmail.com` or `db513bc9-ff1b-4747-a47b-7750d0c701d3` are both valid.
Utilize any provider through a single endpoint by setting fallbacks. See how it's used in [Gateway Fallbacks](https://docs.helicone.ai/getting-started/integration-method/gateway-fallbacks).
Set up a rate limit policy. The value should follow the format: `[quota];w=[time_window];u=[unit];s=[segment]`. For example, `10;w=1000;u=cents;s=user` is a policy that allows 10 cents of requests per 1000 seconds per user.
Add a `Helicone-Session-Id` header to your request to start tracking your (sessions and traces.)\[features/sessions].
To represent parent and child traces we take advantage of a simple path syntax. For example, if you have a parent trace `parent` and a child trace `child`, you can represent this as `parent/child`.
The name of the session. For example, `Course Plan`.
## 3rd Party Integrations
PostHog authentication for [Helicone's PostHog
Integration](getting-started/integration-method/posthog)
PostHog host for [Helicone's PostHog
Integration](getting-started/integration-method/posthog)
## Feature Flags
Whether to exclude the response from the request. Set to `true` or `false`.
Whether to exclude the request from the response. Set to `true` or `false`.
Control how Helicone handles requests that would exceed a model's context window. Accepted values:
* `truncate` — Best-effort normalization and trimming of message content to reduce token count.
* `middle-out` — Preserve the beginning and end of messages while removing middle content to fit within the limit. Uses token estimation to keep high-value context.
* `fallback` — Switch to an alternate model when input exceeds the context limit. Provide multiple candidates in the request body's `model` field as a comma-separated list (e.g., `"gpt-4o, gpt-4o-mini"`). Helicone picks the second model as the fallback when needed. When under the limit, Helicone normalizes the `model` field to the primary model.
If your request body does not include a `model` or you need to override it for estimation, set `Helicone-Model-Override`. For fallbacks, specify multiple `model` candidates in the body; only the first two are considered.
Whether to cache your responses. Set to `true` or `false`. You can customize the behavior of the cache feature by setting additional headers in your request.
| Parameter | Description |
| -------------------------------- | --------------------------------------------------------------------------------------------- |
| `Cache-control` | Specify the cache limit as a `string` in *seconds*, i.e. `max-age=3600` is 1 hour. |
| `Helicone-Cache-Bucket-Max-Size` | The size of cache bucket represented as a `number`. |
| `Helicone-Cache-Seed` | Define a separate cache state as a `string` to generate predictable results, i.e. `user-123`. |
Header values have to be strings. For example, `"Helicone-Cache-Bucket-Max-Size": "10"`.
Retry requests to overcome rate limits and overloaded servers. Set to `true` or `false`.
You can customize the behavior of the retries feature by setting additional headers in your request.
| Parameter | Descriptionretru |
| ---------------------------- | ---------------------------------------------------------------- |
| `helicone-retry-num` | Number of retries as a `number`. |
| `helicone-retry-factor` | Exponential backoff factor as a `number`. |
| `helicone-retry-min-timeout` | Minimum timeout (in milliseconds) between retries as a `number`. |
| `helicone-retry-max-timeout` | Maximum timeout (in milliseconds) between retries as a `number`. |
Header values have to be strings. For example, `"helicone-retry-num": "3"`.
Activate OpenAI moderation to safeguard your chat completions. Set to `true` or `false`.
Secure OpenAI chat completions against prompt injections. Set to `true` or `false`.
Enforce proper stream formatting for libraries that do not inherently support it, such as Ruby. Set to `true` or `false`.
## Response Headers
| Headers | Description |
| ------------------------------ | ---------------------------------------------------------------------------- |
| `Helicone-Id` | Indicates the ID of the request. |
| `Helicone-Cache` | Indicates whether the response was cached. Returns `HIT` or `MISS`. |
| `Helicone-Cache-Bucket-Idx` | Indicates the cache bucket index used as a `number`. |
| `Helicone-Fallback-Index` | Indicates fallback idex used as a `number`. |
| `Helicone-RateLimit-Limit` | Indicates the quota for the `number` of requests allowed in the time window. |
| `Helicone-RateLimit-Remaining` | Indicates the remaining quota in the current window as a `number`. |
| `Helicone-RateLimit-Policy` | Indicates the active rate limit policy. |