How do I set up hierarchical AI budgets?

Goal: A budget hierarchy where the org ceiling can never be breached, even if every individual child budget still has room.

The problem this solves: Without hierarchy, 50 agent runs × $0.49 each = $24.50 against a $20 department budget. Every individual run passes (it's under its own $0.50 limit) while the department budget is blown. Hierarchy means the parent ceiling wins.

Prerequisites: At least one application making calls through the proxy.

Step 1 — Create the org-level budget (the ceiling)

Go to Budgets → New Budget.

This is the hard ceiling. No combination of child budgets can exceed it.

Step 2 — Create department budgets

Create one budget per department that uses AI. Each is scoped to a department header value.

Repeat for each department: customer-success, product, sales, etc.

Step 3 — Create feature budgets for high-risk features

For agent workflows, experimental features, or anything that can loop, add a feature-level budget.

Step 4 — Add a per-run limit for agents

For any agent that runs multi-step workflows, add a per-run limit. This caps the cost of a single agent execution, independent of the monthly feature budget — but it can only be set when you create the budget, not added afterward, so plan for it up front in Step 3.

In the Create Budget modal, check Per-Run Spend Limit (Optional) and enter a dollar amount:

Tag agent runs with a run ID so Cognocient can group calls per run:

import uuid
 
run_id = f"doc-proc-{uuid.uuid4()}"
 
for step in agent_steps:
    response = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=step.messages,
        extra_headers={
            "X-Cost-Feature":  "document-processor",
            "X-Cost-Run-ID":   run_id,   # groups all steps in this run
        }
    )

Step 5 — Test the hierarchy

Make a test call tagged with a feature that has budgets at all levels, and confirm it succeeds:

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "test"}],
    extra_headers={
        "X-Cost-Department": "engineering",
        "X-Cost-Feature":    "document-processor",
        "X-Cost-Run-ID":     "test-run-001",
    }
)

There's no single response header that reports remaining budget across every matching level — use the status endpoint in Step 6 to check headroom instead. A call is blocked (429) if any matching budget level — run, feature, department, or org — is out of room.

Step 6 — Check budget status before each agent step (advanced)

For long-running agents, poll the budget status API before each step to avoid being stopped mid-execution. feature, department, and run_id are query parameters, not headers:

import httpx
 
def check_budget(feature: str, run_id: str) -> bool:
    resp = httpx.get(
        "https://api.cognocient.com/api/budgets/status",
        params={"feature": feature, "run_id": run_id},
        headers={"Authorization": f"Bearer {COG_API_KEY}"},
    )
    status = resp.json()
    return status.get("can_proceed", True)
 
for step in agent_steps:
    if not check_budget("document-processor", run_id):
        return {"status": "budget_limit_reached", "steps_completed": completed}
    # ... proceed with step

Done

Your hierarchy is active. The enforcement chain is: run → feature → department → org. Any level being exhausted stops the call — the most restrictive level always wins.

Monitor budget consumption across all levels in Budgets.