Budgets

Run budgets

Attach a spend cap to a named job or pipeline run. The run budget persists in the database across server restarts, making it reliable for long-running batch jobs and agent workflows.

What is a run?

A run is any logical unit of work you want to cap independently: a nightly ETL job, a document-processing pipeline, a single agent session, a one-off analysis. You identify it with a run_id string of your choice.

Every call tagged with the same run_id counts toward that run's budget. When the budget is exhausted, the run status changes to exhausted and all further calls with that run ID are blocked (HTTP 402).

Using run budgets

Send two headers on each call that belongs to the run:

import uuid
from datetime import date

# Generate a stable run ID — same ID across retries to share one budget
run_id = f"nightly-summary-{date.today().isoformat()}"

for document in documents:
    response = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": f"Summarise: {document}"}],
        extra_headers={
            "X-Zelyx-Run-Id": run_id,
            "X-Zelyx-Run-Budget-USD": "10.00",   # $10 for the whole batch
        },
    )

Run lifecycle

View active and recent runs on the Run Budgets dashboard page, which shows spend progress, call count, and current status for each run.

Handling exhaustion in your code

import httpx

try:
    response = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": doc}],
        extra_headers={
            "X-Zelyx-Run-Id": run_id,
            "X-Zelyx-Run-Budget-USD": "10.00",
        },
    )
except httpx.HTTPStatusError as e:
    if e.response.status_code == 402:
        # Run budget exhausted — stop processing, notify operator
        print(f"Run {run_id} budget exhausted. Stopping.")
        break

Budget alert on exhaustion

When a run budget is exhausted, Zelyx fires a run_exhausted alert to all configured channels. Set up a Slack or webhook channel to be notified the moment a run hits its cap (see Alert setup).

Differences from session limits