# Request headers

> Every request header ACOG reads: authentication, routing, batching, caching, labels, tracing, sessions and fallback control.

Product: AI Cost Optimizer Gateway (ACOG). Web version: https://tessarac.com/docs/acog/reference/request-headers. Last updated: 2026-10-16.

Headers not listed here, such as `anthropic-version` and `anthropic-beta`, are forwarded to your provider.

## Authentication

| Header | Where | Notes |
|---|---|---|
| `Authorization: Bearer acog_…` | Compatible endpoints, `/openai`, `/vertex`, `/custom`, management API | |
| `x-acog-key: acog_…` | Everywhere | |
| `x-api-key: acog_…` | `/anthropic`; also compatible endpoints when the value starts with `acog_` | |
| `api-key: acog_…` | `/azure`; also compatible endpoints when the value starts with `acog_` | |

## Routing and execution

| Header | Values | Effect |
|---|---|---|
| `x-acog-channel` | `direct`, `bedrock`, `vertex`, `azure`, `custom` | Pin the request to one platform. See [Routing and failover](https://tessarac.com/docs/acog/providers/routing-and-failover.md#pin-a-request-to-one-platform-x-acog-channel). |
| `x-acog-batch` | `defer`, optionally `; max-wait=<duration>` | Run at batch prices. See [Batches](https://tessarac.com/docs/acog/api/batches.md). |
| `x-acog-policy-fallback` | `off` | Do not retry a safety-classifier refusal on the fallback model |

## Caching

| Header | Values | Effect |
|---|---|---|
| `x-acog-cache-control` | `no-cache`, `no-store`, `ttl=<seconds>`, `namespace=<name>` (comma-separated) | Control the response cache. See [Caching](https://tessarac.com/docs/acog/optimize/caching.md#controlling-the-response-cache-per-request). |
| `x-acog-cache-ttl` | `auto`, `in_memory`, `5m`, `30m`, `1h`, `24h`, `forever` | Provider prompt-cache lifetime for this request. See [Caching](https://tessarac.com/docs/acog/optimize/caching.md#cache-lifetime). |

## Attribution and tracing

| Header | Effect |
|---|---|
| `x-acog-label` | A free-form label for reports, such as a ticket number or cost center. Up to 128 characters. |
| `x-acog-trace-tags` | Comma-separated tags added to this request's trace |
| `x-acog-trace-metadata` | A JSON object added to this request's trace |
| `x-request-id` | Your own request ID, echoed in the response and recorded |

The application a request is attributed to comes from its key, never from a header.

## Conversations (auto mode)

| Header | Effect |
|---|---|
| `x-acog-session-id`, `x-session-id`, `x-claude-code-session-id` | Identify a conversation, so auto mode keeps it on a stable model |
| `x-acog-agent-id`, `x-agent-id`, `x-claude-code-agent-id` | Identify the agent or sub-agent within a conversation |