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 Monitor → 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

That table holds runs that are still live. A run's live budget counter is cleared after 24 hours without activity, so finished runs move to the Past runs section below it, rebuilt from your call log for the last 30 days (spend, calls, subagent calls, first and last call). Open any run, live or past, in Agent Workflows: the run picker lists the last 30 days of runs and draws the step-by-step tree, including subagent calls linked by X-Cost-Parent-Run-Id.

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 Control → 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