# Cost Runway Tracker

> Track LLM-API spend the right way: balance, burn rate, runway, and the cache-rate awareness that makes multi-model panels affordable. Use when someone asks "how much budget is left", "is the API bill under control", "should we top up", or suspects a runaway spend loop. Encodes the LIVE lesson: the misleading 'usage' field, the missing cap, and the cache math.

- Skill: `amirulskulker/cost-runway-tracker` (Agent Skill)
- Install (CLI): `npx skillmds@latest add amirulskulker/cost-runway-tracker`
- Raw SKILL.md: https://api.skillmd.com/api/skills/amirulskulker/cost-runway-tracker/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: amirulskulker (https://skillmd.com/u/amirulskulker)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/amirulskulker/cost-runway-tracker

---


# Cost & Runway Tracker - the low-budget proof

Spend tracking looks trivial until a stale number gates a pipeline. This
skill encodes what a real tracker must get right, with the exact failure
modes encountered in production.

## Ground rules (the traps)

1. **"Usage" is NOT balance.** The most common bug: reading the key-info
   endpoint's `usage` field and calling it "balance". `usage` is LIFETIME
   spend. Real balance = `total_credits - total_usage`. Getting this wrong
   makes a watchdog report the wrong number forever (verified live).
2. **Never trust a stale status file.** A treasury file synced weeks ago
   says CRITICAL while the real balance is healthy - and gating logic reads
   the file, not the API. Freshness is part of correctness.
3. **Assume the key has NO cap until proven.** Provider keys default to
   `limit: null`. A retry storm spends to zero with no stop. Ask, and if
   unset, flag it - a cap is a 30-second dashboard change that protects the
   whole thesis.
4. **Runway is a range, not a point.** Balance / weekly burn and balance /
   monthly burn disagree for a reason; report both.

## The math

```
balance     = total_credits - total_usage          (from /credits)
burn_weekly = usage_weekly                          (from /auth/key)
burn_monthly= usage_monthly
runway_weeks= balance / burn_weekly
runway_month= balance / burn_monthly
status      = HEALTHY if balance >= floor else LOW  (floor is YOUR call)
```

## Cache awareness (why panels are cheap)

Repeated identical context is not billed at prompt price. Cache-read is a
fraction of the prompt rate:

- flash-class models: cache-read ~50x cheaper than prompt
- frontier models: cache-read ~6-10x cheaper
- A multi-model panel with an identical context pack writes the cache ONCE
  and reads it N times at the discounted rate - that is the mechanism that
  makes 5-flagship panels cost pennies.

Evidence: pull the per-model pricing, compute `saving = prompt / cache_read`,
and print the table in every report. The cache carve-out is a deliberate
design choice (shared system prompts, shared few-shots), not luck.

## The pattern

```
1. PULL credits      -> total_credits, total_usage
2. PULL key info     -> usage_daily / weekly / monthly, limit, free-tier quota
3. PULL model pricing-> per-model cache rates for the models in use
4. COMPUTE           -> balance, burn, runway (weeks & months), cache savings
5. WRITE             -> fresh status file + human report card + raw json
6. GATE              -> exit 0 healthy / nonzero below floor; fail loudly,
                        never silently skip the check
```

## Failure modes seen in production

- `usage` (lifetime spend) misread as balance -> watchdog alerts at wrong
  thresholds forever, and the status file picks the stale value.
- No spend cap -> a bot retry loop burns the whole balance in one incident.
- Cache prices ignored -> "panel is too expensive" conclusion that the
  numbers disprove.
- Report written only on the happy path -> `--json` mode forgot to persist
  the artifacts; every mode must write.

## Output

- Live balance, weekly/monthly burn, runway in weeks AND months
- Per-model cache-rate table with the x saving
- Key-limit status (NONE SET is a finding, not a footnote)
- Status file that gating logic actually reads, timestamped fresh

---
*Skill pattern: get the units right (credits vs usage), check the cap, show
the cache math. The value is not the Dashboard - it is that the number your
pipeline gates on is TRUE.*