Skip to content
Docs menu

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.

View .md

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.