Agent cost dashboard

Agent cost dashboard

Token bills arrive as one big number. This kit splits it by customer, by task, and by model, and divides by successful outcomes, because a failed agent run still costs money. One script, one HTML file with no external scripts, ready to attach to a pricing or board discussion.

Inputs

1. Usage CSV in data/ in the shared schema (one row per model call):

   timestamp,customer,task,run_id,provider,model,input_tokens,output_tokens,cache_read_tokens,cache_write_tokens,cost_usd,outcome
   2026-10-01T09:12:00Z,northwind-co,research_agent,run-00042,anthropic,claude-opus-5-5,9000,2500,90000,0,,success

   • input_tokens is uncached input only. Cache reads and writes go in their own columns.
   • run_id groups the calls of one task run (optional; without it each row is a run).
   • outcome: success or failure on any row of the run (optional, but cost per success needs it).
   • cost_usd: leave blank to price from the price table.

   App logs usually have all of this. Provider exports do not know your customers or tasks; convert them with the llm-usage-normalizer kit first.

2. Price table (data/llm-prices.csv, or examples/prices.csv to start): per-million-token prices per model. Prices change. Check them against each provider's current pricing page and update checked_on; the script warns when prices were never checked or are over 60 days old.
3. Revenue by customer (optional): customer,month,revenue. Adds gross margin after LLM cost per customer.

Steps

1. Check the usage file: date range, row count, customers, tasks, models. Confirm what one row is (one call) and whether input_tokens includes cached tokens. If it does (common in exports from OpenAI-style APIs), stop and convert with llm-usage-normalizer, or cache savings will be double counted.

2. Run:

   node scripts/cost-dashboard.mjs data/usage.csv --prices data/llm-prices.csv --revenue data/revenue.csv --title "Agent costs, October" --out out/agent-costs.html

   Limit the range with --from 2026-10-01 --to 2026-10-31 so it matches the revenue month.

3. If the script warns about unpriced models, add them to the price table and rerun. Do not guess a price; ask the user or point them to the provider's pricing page.
4. Give a read-out from out/agent-costs.json: total cost, cost per successful outcome, the most expensive task per success, the model that dominates spend, cache hit rate, and any customer with gross margin under 60% or negative.
5. Suggest the next move that fits: gross-margin-by-customer for full margins with hosting and support costs, usage-pricing-simulator if a customer is unprofitable, consumption-guardrails if one day or one customer spiked.

Reading the numbers

• Cost per successful outcome = all cost for a task (including failed runs) / successful runs. Low success rates make this number climb fast; fixing reliability is often the cheapest cost cut.
• Cache hit rate = cache reads / (uncached input + cache reads + cache writes). Agents that resend long context should be well above 50%.
• Model mix: if one top-tier model is most of the spend, check which steps really need it.

Output template

**October agent costs: $147 across 573 runs (86% succeeded).**
- Cost per successful outcome $0.30; research_agent is $1.58 per success (65% success rate).
- claude-opus-5-5 is 90% of spend. Cache hit rate 77%.
- Margin after LLM cost 80% overall; cobalt-labs is negative (-10%), northwind-co 69%.
Dashboard: out/agent-costs.html

Guardrails

• Prices in the kit are examples, not quotes. Always say so when sharing cost numbers built from them.
• Never call provider APIs or billing pages from this kit; it works on files.
• Customer names are business data; keep raw rows out of chat.

Agent cost dashboard

Turns LLM usage logs into one HTML dashboard: cost per customer, per task, and per successful outcome, model mix, cache hit rate, daily cost, and gross margin after model costs when you add revenue. No external scripts; open it anywhere.

Who it is for: founders and engineers running an AI or agent product who need to know which customers and workflows cost what, before pricing or a board meeting.

Example

Input: examples/usage.csv (2,185 model calls, 573 runs, 6 customers, 4 tasks, October), examples/prices.csv, examples/revenue.csv.

Output: out/agent-costs.html and out/agent-costs.json:

Cost $147 over 573 runs; cost per success $0.299; cache hit 77%; gross margin after LLM 80%.
research_agent: $1.58 per successful outcome, 65% success rate
cobalt-labs: $66 LLM cost on $60 revenue, margin -10%

What it can access

• Runs node scripts/cost-dashboard.mjs (Node built-ins only).
• Reads data/. Writes out/agent-costs.html and .json.
• No network, no provider API keys.

Setup

None. Put usage in data/usage.csv (or convert a provider export with @agentcosts/llm-usage-normalizer), copy examples/prices.csv to data/llm-prices.csv, and check every price against the provider's current pricing page. The example prices are a starting point, not a quote.