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 → Sessions (or Workstreams). Each X-Cost-Run-ID value appears as a row showing:

• Total cost for the entire run
• Number of API calls (steps)
• Models used and their individual costs
• Duration from first to last call
• Any waste flags (e.g. "Context bloat after step 3")

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

Create a budget with a per-session limit so a single runaway run can't consume your entire monthly feature budget.

Go to Dashboard → Budgets → New Budget:

When a single run exceeds $0.50, only that run is blocked — other concurrent runs with different IDs continue normally.

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",
            headers={
                "Authorization": f"Bearer {COG_API_KEY}",
                "X-Cost-Feature": feature,
                "X-Cost-Session": run_id,
            },
            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

Related: Debug Runaway Agent Loops · Hierarchical Budgets · MCP / A2A Attribution