---
title: x-venom headers
description: Every x-venom-* HTTP header venom sends or answers with, on the orchestrator, Venom Cloud and venom serve, and what each one changes.
section: reference
order: 40
audience: [operator, builder, agent]
sources: [docs/architecture.md, docs/cloud-mesh.md, services/go-orchestrator/internal/proxy, services/nodejs-cloud/lib, packages/harness/src/extensions/provider.ts, packages/harness-server/src/server.ts]
features: []
---

venom keeps the OpenAI request and response bodies unchanged and puts its own information in `x-venom-*` headers. An OpenAI client that ignores them still works; a client that sends them gets session stickiness, cost attribution and routing control.

Header names are case-insensitive. Venom Cloud and the orchestrator accept the same request headers, and Venom Cloud relays the orchestrator's response headers unchanged.

```bash
curl -sS http://localhost:8787/v1/chat/completions \
  -H "Authorization: Bearer $VENOM_API_KEY" \
  -H "x-venom-session: s_demo_1" \
  -H "x-venom-task: ENG-142" \
  -H "content-type: application/json" \
  -d '{"model":"venom-default","messages":[{"role":"user","content":"hi"}]}' \
  -D - -o /dev/null | grep -i '^x-venom'
```

## Request headers {#request}

### Sessions and attribution {#attribution}

| Header | Value | Effect |
|---|---|---|
| `x-venom-session` | a session id; side requests use `<session>:<kind>` | Keeps a session on one upstream so its prompt cache stays warm, and groups usage by session. A `:<kind>` suffix applies that side-request kind's defaults (`side_requests` in the orchestrator config). |
| `x-venom-parent-session` | the parent session id | Sent by subagents. Usage and the console's Sessions view roll the subagent up under its parent. |
| `x-venom-project` | a project name | The project the request's spend is charged to. The CLI sends it from `VENOM_PROJECT`. |
| `x-venom-task` | a pull request or issue URL, `owner/repo#123`, a tracker key like `ENG-142`, or a free-form id (at most 128 characters) | The work item the spend is for; any other value is ignored. Shown in the cloud's Usage, Tasks view. |
| `X-Venom-Intent` | an intent id, at most 128 bytes | Charges the request to an intent's spend account; over its budget the request gets `402 intent_budget_exceeded`. |
| `x-venom-gear`, `x-venom-role` | the gear name; the role (`workers`, `smart`, `vision`, `summary`, `classifier`, `reflex`, `browser`, or `main`) | Recorded per request, so usage can be split by gear and role. |
| `x-venom-human-at` | epoch milliseconds | When the session's person last wrote. An organisation's session guard measures a session's length and spend from it. Never in the prompt. |
| `x-venom-lang` | a language slug such as `go` or `typescript` | The session's main programming language, from file extensions only. Auto routing rules can match on it. |
| `x-venom-escalation` | `id=esc_…; reason=…; from=<model>; to=<tier or model>` | Names an escalated re-run (after failing tests, lint, a type check, tool errors or a rejected review). |
| `x-venom-escalation-result` | the outcome | Sent on the parent's next request, so the escalation's result is recorded. |
| `x-venom-experiment` | `<id>; arm=<a\|b>` | Names a Venom Cloud gear experiment's arm. |

### Routing and cost control {#routing}

| Header | Value | Effect |
|---|---|---|
| `x-venom-profile` | a route profile name | Routes under that profile: which targets are allowed and which body defaults apply. A gear with a profile sends it on every request. |
| `x-venom-service-tier` | `auto`, `default`, `flex`, `priority` or `batch` | The provider tier to ask for. `batch` means the same as `x-venom-urgency: batch`. A `service_tier` in the body wins. |
| `x-venom-urgency` | `batch` or `background` | `batch` turns a chat, completion, embedding or Responses request into a batch request (`202` with a `Location`). `background` sets `x-venom-priority: background`. |
| `x-venom-priority` | `background` | Waits in the background queue when an upstream is full, and uses the flex tier on OpenAI. |
| `x-venom-batch-wait` | seconds, capped at `batch_routing.max_wait` (10 minutes) | With a batch request: wait up to this long and answer like a normal request if the batch finishes in time. |
| `x-venom-callback-url` | an `https` URL | With a batch request: POST the finished object there. The host must be in `batch_routing.callback_hosts`. |
| `x-venom-cache-ttl` | `long` or `short` | The prompt-cache lifetime the client wants. `long` asks a model that supports it for the longer cache from the first request (venom's terminal UI sends it); `short` never does. |
| `x-venom-keep-local` | a code | Keeps the request on local models or the organisation's own daemons, as a keep-local guardrail match would. venom sends it on every request after reading a file under a keep-local path. |
| `x-venom-dedup` | `off` | The request never joins an identical in-flight request. |
| `x-venom-daemon` | a daemon name or id | Venom Cloud only: pins the request to that daemon if the key may use it. |
| `x-venom-mesh-mode` | `auto` (default), `direct` or `relay` | Venom Cloud only: how tokens travel. `direct` fails with `503 no_direct_path` when no daemon endpoint is reachable. |
| `x-venom-networks` | `tailnet:<name>,lan:<label>` | Venom Cloud only: networks the client can reach, so a daemon on them counts as reachable for direct mode. The CLI sends `VENOM_NETWORKS`. |

## Response headers {#response}

### Every routed answer {#routed}

| Header | Value |
|---|---|
| `x-venom-request-id` | The request's id, also in the request log. |
| `x-venom-upstream` | The upstream that served. |
| `x-venom-model` | The concrete model served. |
| `x-venom-base-model` | The model this one is priced as, when its config sets `base_model`. |
| `x-venom-fallback` | Why earlier targets did not serve (for example `rejected_param`, or `daemons:<code>` on Venom Cloud when every daemon failed and a cloud provider served). Absent when the first target served. |
| `x-venom-route-reason` | How the target was picked: `affinity`, `p2c`, `argmin`, `pinned`, `session_pin`, `cloud`, `hedge`, or `failover:<reason>`. |
| `x-venom-variant` | The experiment variant, on answers to an experiment alias. |
| `x-venom-translated` | `chat_completions` when a `/v1/responses` request was served by translating to chat completions. An upstream cannot set it. |
| `x-venom-cache-retention` | The prompt-cache lifetime granted (`24h`, `30m`), when one was asked for. venom's keep-warm pings use it. |
| `x-venom-queued-ms` | How long the request waited in the rate shaper's queue. |
| `x-venom-cost-usd` | The request's cost, where the endpoint reports it (speech). |

### Auto routing {#auto}

| Header | Value |
|---|---|
| `x-venom-auto-tier` | The tier picked: `cheap`, `balanced` or `premium`. |
| `x-venom-auto-reason` | The rule that picked it, in words (ASCII, at most 200 characters). |
| `x-venom-auto-class`, `x-venom-auto-source` | The task class, and where it came from (`rule`, `decider` or the default). |
| `x-venom-auto-escalated` | `from=cheap; to=balanced; reason=provider_error\|empty\|truncated\|filtered` when a cheap answer was redone on a stronger tier. |
| `x-venom-auto-context`, `x-venom-context-cost-usd` | When a longer-context model served: `skipped=<model>; window=<n>; need=<n>; served=<model>`, and the extra input cost in USD. |

### Budgets, guardrails and filters {#budgets}

| Header | Value |
|---|---|
| `x-venom-budget-warning` | A key budget is past its warning share: the period, spend, limit and reset time. |
| `x-venom-budget-reset` | On `429 budget_exceeded`: when the budget resets (RFC 3339, UTC). |
| `x-venom-spend-warning`, `x-venom-spend-downgrade`, `x-venom-spend-reset` | Venom Cloud spend guards: a budget past its warning share; a budget at its limit switched the model; when a refused budget resets. |
| `x-venom-spend-cap-warning`, `x-venom-spend-cap-reset` | The organisation's monthly spend cap: at 80 % (`monthly; spent=…; cap=…; resets=…`), and on refusal. |
| `x-venom-guardrail` | A guardrail redacted, warned or kept the request local, and let it pass. |
| `x-venom-prompt-filter`, `x-venom-prompt-filter-warning` | An organisation prompt filter changed or flagged the request: `redacted=<n>, warned=<n>`; `blocked` with `403 prompt_blocked`; `unchecked` with `503 prompt_classifier_unavailable`. |
| `x-venom-response-filter` | A response filter ran: `active` on a filtered stream, counts on a whole body. |

### Specific endpoints {#endpoints}

| Header | Where | Value |
|---|---|---|
| `x-venom-response-cache` | side requests | `hit` (answered from an identical recent request) or `shared` (joined one in flight). Billed 0. |
| `x-venom-dedup` | deduplicated requests | `joined` or `replayed`, with `Idempotent-Replayed: true` on a replay. |
| `x-venom-batch-request` | `202` batch answers | The batch request id; `Location` is `/v1/batch_requests/{id}`. |
| `x-venom-sample-rate` | `/v1/audio/speech` with PCM | The sample rate of raw PCM audio. |
| `x-venom-voices-failed` | `GET /v1/audio/voices` | The upstreams whose voice list failed; the others still answer. |
| `x-venom-cassette` | cassette replay mode | Marks a replayed response. |
| `x-venom-log-flushed` | `GET /admin/v1/requests?flush=1` | `true` once the request log is written through. |
| `x-venom-served-by`, `x-venom-daemon`, `x-venom-daemon-region`, `x-venom-job` | Venom Cloud | `daemon` or `cloud`; the daemon's name and region (`cloud` and the function region for a cloud provider); the job id. |
| `x-venom-sha256`, `x-venom-pack-sha256` | Venom Cloud downloads | The SHA-256 of a plugin bundle, or of a compliance pack. |
| `x-venom-export-limit` | Venom Cloud log export | The row cap (50,000) applied to the export. |
| `x-venom-epoch` | `venom serve` handoff | The session lease epoch stamped on a handoff bundle. |
| `x-venom-serve-binding` | Venom Cloud remote sessions | The serve binding's last move, as JSON. |

## Other venom headers {#other}

| Header | Where | Meaning |
|---|---|---|
| `x-venom-csrf` | `venom serve` mobile page | The page's CSRF token, required on its POST requests. |
| `X-Venom-Egress` | the sandbox egress proxy | `denied` on a `403` for a host the sandbox does not allow. |
| `x-venom-limit-reset` | read by venom | A reset time venom's long-task runner honours, with `Retry-After` and the providers' rate-limit reset headers, when waiting out a usage limit. |
| `x-venom-mesh-*` | daemons | Reserved for Venom Cloud. A daemon strips any inbound `x-venom-mesh-*` header before handling a request. |
| `x-venom-background`, `x-venom-console-*` | Venom Cloud internals | Set by the cloud on its own internal calls; not part of the client API. |

An upstream cannot spoof these: the orchestrator passes on only an allowlist of upstream response headers and sets the `x-venom-*` ones itself.

## Related

- [Error codes](/docs/reference/errors.md)
- [Architecture, ports and contracts](/docs/reference/architecture.md)
- [Glossary](/docs/reference/glossary.md)
