x-venom headers
Every x-venom-* HTTP header venom sends or answers with, on the orchestrator, Venom Cloud and venom serve, and what each one changes.
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.
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
Sessions and 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
| 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
Every routed answer
| 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
| 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
| 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
| 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
| 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.