Integration
Request headers
Add X-Zelyx-* headers to any proxy request to tag calls, cap per-session or per-run spending, and override key-level defaults. All headers are optional.
Tagging headers
Tags appear in Explorer, the Team page, Costs breakdown, and budget enforcement. Header values override whatever is set on the Zelyx key for that call.
| Header | Type | Purpose |
|---|---|---|
X-Zelyx-Team | string | Tag this call with a team name. Drives team-level budget enforcement and the Team analytics page. |
X-Zelyx-Project | string | Tag with a project or feature name. Used in project budgets and cost breakdowns. |
X-Zelyx-Environment | string | Label the environment (e.g. production, staging). Analytics only — no enforcement. |
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=[{"role": "user", "content": "..."}],
extra_headers={
"X-Zelyx-Team": "backend",
"X-Zelyx-Project": "search-api",
"X-Zelyx-Environment": "production",
},
)Session headers
Session headers group a series of calls and apply a soft spend cap to the whole session. Useful for interactive features where you want to limit how much one user can spend per conversation.
| Header | Type | Purpose |
|---|---|---|
X-Zelyx-Session-Id | string | Assign a session ID. All calls with the same ID are grouped for loop detection and session spend tracking. |
X-Zelyx-Session-Limit-USD | float | Soft cap for this session. When cumulative session spend reaches this value, the gate blocks further calls with HTTP 402. |
session_id = f"user-{user_id}"
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=conversation,
extra_headers={
"X-Zelyx-Session-Id": session_id,
"X-Zelyx-Session-Limit-USD": "0.50", # 50 cents per session
},
)Run headers
Run headers attach a call to a named job or pipeline and enforce a persistent budget for that job. Unlike session limits, run budgets are stored in the database and survive server restarts.
| Header | Type | Purpose |
|---|---|---|
X-Zelyx-Run-Id | string | A unique identifier for this job or pipeline run. All calls with the same run ID share one budget. |
X-Zelyx-Run-Budget-USD | float | The total spend cap for this run. Set on the first call — subsequent calls with the same run ID use the budget that was already created. |
import uuid
run_id = f"etl-{date.today()}-{uuid.uuid4().hex[:8]}"
for batch in batches:
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=[{"role": "user", "content": batch}],
extra_headers={
"X-Zelyx-Run-Id": run_id,
"X-Zelyx-Run-Budget-USD": "25.00", # $25 cap for the whole run
},
)X-Zelyx-Run-Budget-USD on a later call for the same run ID, the original budget is kept — it is not updated.Response headers
Zelyx sets one response header when the gate flags a call for review.
| Header | Value | Meaning |
|---|---|---|
X-Zelyx-Review-Required | true | The call was approved and the response is returned normally, but it has been flagged for human review in the Gate dashboard. |
response_raw = client.chat.completions.with_raw_response.create(
model="claude-opus-4-7",
messages=[{"role": "user", "content": "Process payment for order #123"}],
)
if response_raw.headers.get("X-Zelyx-Review-Required") == "true":
notify_reviewer(response_raw.parse()) # flag in your own system tooKey-level defaults
When you create a Zelyx key, you can set a default team and project. Every call made with that key is tagged with those values unless overridden by a header on the individual request.
Header values always take precedence over key-level defaults. If neither the key nor the request provides a tag, the field is empty.
Fallback chain
- Request header (e.g.
X-Zelyx-Team: backend) - Query parameter (e.g.
?nexus_team=backend) - Key-level default (set when the key was created)
- Empty / not set