Cost Metrics

Keel exposes cost and request rollups for governed projects through the dashboard observability surface. Rollups are built from persisted permit and usage records — the same records that feed Timeline Replay and per-request Audit evidence. They are read-only summaries, not a separate metrics store.

What’s available

A typical summary response covers a configurable time window and includes:

• Spend totals — total spend in the window, plus breakdowns by project, provider, and model
• Request counts — total request count, error count, and failure count
• Permit decisions — counts by allow, deny, and challenge, plus per-project decision breakdowns
• Failure reasons — top reason codes for the window

Spend values are denominated in usd_micros (USD × 10⁶). Microdollar precision avoids floating-point rounding in budget accounting, the same convention used by Budget Envelopes.

{
  "totals": {
    "spend_usd_micros": 7000,
    "spend_usd": 0.007,
    "request_count": 5,
    "error_count": 1,
    "failure_count": 2,
    "permit_count": 5,
    "permit_decisions": {
      "allow": 3,
      "deny": 1,
      "challenge": 1
    }
  },
  "breakdowns": {
    "spend_by_project": [],
    "spend_by_provider": [],
    "spend_by_model": [],
    "request_counts_by_status": [],
    "permit_decisions_by_project": [],
    "failure_reasons": []
  },
  "latency": {
    "available": false,
    "source": "request.completed logs and in-process metrics",
    "reason": "Latency summaries are not available from the persisted observability data."
  }
}

How values are computed

• Spend uses the actual cost recorded on the permit, attributed to the window in which usage was reported. Permits with no closeout do not contribute to spend totals.
• Spend breakdowns group by the provider, model, and project recorded on the permit decision.
• Request counts use the latest persisted request row per request_id in the window. Re-tries against the same request_id collapse to one row.
• Error count counts requests in a terminal errored state.
• Failure count counts requests in denied or errored state.

Latency boundary

Cost-metrics rollups do not include persisted latency summaries. Keel does not store per-request latency in the observability dataset that feeds these rollups, so a latency block is never returned. If you need request-level latency data, instrument it on your side or rely on the request.completed event in Timeline Replay.

When to use cost metrics vs other surfaces

Cost metrics answer aggregate questions over a window. Per-request investigation belongs on Timeline Replay. Per-permit financial reconciliation belongs on the Reconciliation pillar.

Plan tier availability

Cost-metrics rollups are returned from the dashboard observability surface. Dashboard observability routes are available on every plan tier, but the dashboard visibility window is bounded by the plan’s log retention:

• Starter — 7-day retention
• Growth — 30-day retention
• Business — 180-day retention
• Enterprise — 365-day retention

Records older than the plan’s retention are pruned on a scheduled cadence and do not appear in cost-metrics rollups.

What this page does not claim

• Cost metrics are not a separate metrics database. They are reads against the same persisted permit and usage data that the rest of the trust stack relies on.
• A spend total reflects only permits that have been closed out with actual usage. Permits with missing_usage_report accounting disposition are excluded from spend.
• Latency summaries are not exposed by this surface and will not be added without an explicit retention contract.

Related pages

• Budget Envelopes
• Observability
• Timeline Replay
• Plans & Entitlements