CostLens

Turn JSON usage events into cost summaries, budget checks, and offline reports.

When to use

• You already have token usage events and need a quick spend summary.
• You want a simple budget gate in local automation or CI.
• You need an exportable JSON report without relying on a hosted billing dashboard.

Commands

node {baseDir}/bin/costlens.js monitor --events ./events.json --budget 10.00 --threshold 80
node {baseDir}/bin/costlens.js budget check --events ./events.json --budget 5.00 --format json
node {baseDir}/bin/costlens.js report --events ./events.json --out ./reports/cost-report.json

Built-in default rates

Events can override the defaults with inputCostPer1k and outputCostPer1k.

Event shape

[
  {
    "model": "gpt-4.1",
    "promptTokens": 1500,
    "completionTokens": 800,
    "timestamp": "2026-02-26T10:00:00Z"
  }
]

Output

• Total calls, total tokens, and total cost
• Per-model breakdowns for calls, tokens, and cost
• Per-day spend trends
• Budget usage percentage and alert level (ok, warning, or critical)

Boundaries

• Pricing is based on built-in defaults plus per-event overrides. It is not a live pricing feed.
• CostLens is optimized for offline JSON analysis, not streaming metering or invoice reconciliation.