How do I track cost per agent run?

Goal: See exactly what each agent run cost — not just an aggregate monthly total — and set a per-run budget so a single runaway execution can't consume your entire feature budget.

Time: 15 minutes to instrument. Data appears immediately.

Step 1 — Generate a unique run ID per execution

The key change: generate a fresh UUID at the start of each agent execution and pass it as X-Cost-Run-ID on every API call within that run.

Step 2 — View runs in the dashboard

Go to Dashboard → Run Budgets. Each X-Cost-Run-ID value appears as a row showing:

• Feature and subagent count
• Number of API calls
• Spend against its ceiling
• Status (active / blocked)
• Last activity timestamp

Workstreams (Dashboard → Workstreams) is a related but separate view — it groups calls by X-Cost-Session, not by run ID, so use it for session-level grouping rather than per-run cost.

Step 3 — Set a per-run spending limit (recommended)

A per-run limit can only be set when you create a budget, not added afterward — decide on it up front.

Go to Budgets → New Budget:

When a single run exceeds its per-run limit, only that run is blocked — other concurrent runs with different IDs continue normally. If you don't set an explicit per-run limit, runs still fall back to Cognocient's account-wide default run budget ($25).

Step 4 — Check budget before each step (for long-running agents)

For agents that run dozens of steps, check the budget before each step so you can exit gracefully instead of being cut off mid-execution:

import httpx
 
def budget_ok(feature: str, run_id: str) -> bool:
    try:
        resp = httpx.get(
            "https://api.cognocient.com/api/budgets/status",
            params={"feature": feature, "run_id": run_id},
            headers={"Authorization": f"Bearer {COG_API_KEY}"},
            timeout=0.5,
        )
        return resp.json().get("can_proceed", True)
    except Exception:
        return True   # fail open — never let the budget check break the agent
 
async def run_document_agent(document: str):
    run_id = f"doc-agent-{uuid.uuid4()}"
 
    for step in plan_steps(document):
        if not budget_ok("document-processor", run_id):
            return {"status": "budget_limit_reached", "completed": completed_steps}
        # ... proceed with step