Usage API

Token usage, value-event measurement, and carrier licence/entitlement status.

Endpoints

BudgetRead is admin/operator/developer/viewer/auditor. LicenceRead is broadly readable (admin/operator/developer/viewer/auditor).

There is no GET /usage/billable-events and no GET/PUT /budget — value-event aggregation lives at /usage/value-events, and spend budgets are part of the signed carrier licence: an Ed25519-signed, per-provider ProviderEntitlement.budget_usd that the runtime only ever reads, never a value an operator sets via the API. Read it via GET /licence/status's provider_entitlements field.

GET /usage

Real, ledger-backed — token/request/cost totals for the current licence period (period_start to now), distinct from /usage/summary's all-time totals. Falls back to zero counts, not an error, when no licence/routing gateway is loaded.

curl -H "Api-Version: v1" -H "Authorization: Bearer hzn_sk_..." \
  http://localhost:4200/usage

Response (200)

{
  "total_input_tokens": 128000,
  "total_output_tokens": 42000,
  "total_requests": 214,
  "total_cost_usd": 6.83
}

GET /usage/summary

Real, ledger-backed — all-time token, request, and spend totals across every provider (Issue #634 Phase 3 / #692).

curl -H "Api-Version: v1" -H "Authorization: Bearer hzn_sk_..." \
  http://localhost:4200/usage/summary

Response (200)

{
  "period": "all_time",
  "input_tokens": 18400000,
  "output_tokens": 6400000,
  "requests": 950,
  "cost_usd": 41.2
}

GET /usage/value-events

Real, ledger-backed — value-event aggregation grouped by ValueEventClass (Intake/Servicing/Recovery/Underwriting/Compliance) and SolutionId over a trailing window, plus a weekly series for the Business Activity dashboard's calendar heatmap (Issue #766, ADR-064's "value-delivered narrative" — measurement only, not a bill-gate).

curl -H "Api-Version: v1" -H "Authorization: Bearer hzn_sk_..." \
  "http://localhost:4200/usage/value-events?window=2592000&weeks=12"

Query Parameters

Response (200)

{
  "window_secs": 2592000,
  "since": "2026-06-04T10:00:00Z",
  "until": "2026-07-04T10:00:00Z",
  "total": 49,
  "by_class": {"intake": 30, "servicing": 12, "recovery": 7},
  "by_solution": {"claims_suite": 49},
  "weekly": [{"week_start": "2026-06-01T00:00:00Z", "count": 12}]
}

GET /licence/status

Real carrier licence status (ADR-034, issue #295) — carrier identity, expiry, transaction-budget utilization by workflow type, Hoziron Cloud spend (if provisioned), and per-provider entitlement budgets (ADR-064, Issue #683).

curl -H "Api-Version: v1" -H "Authorization: Bearer hzn_sk_..." \
  http://localhost:4200/licence/status

Response (200) — licence loaded

{
  "carrier_name": "Example Insurance Corp",
  "carrier_id": "ins-example-001",
  "status": "active",
  "expires_at": "2027-01-01T00:00:00Z",
  "days_remaining": 210,
  "period_start": "2026-06-01T00:00:00Z",
  "period_end": "2026-06-30T23:59:59Z",
  "transaction_utilization": {
    "fnol": {"budget": 1000, "used": 214, "remaining": 786},
    "endorsement": {"budget": null, "used": 42, "remaining": null}
  },
  "cloud_spend": {"budget_usd": 500.0, "spent_usd": 112.4, "remaining_usd": 387.6},
  "provider_entitlements": [
    {"provider_id": "hoziron-regional-eu", "budget_usd": 200.0, "spent_usd": 34.5, "remaining_usd": 165.5},
    {"provider_id": "byo-openai", "budget_usd": null, "spent_usd": 0.0, "remaining_usd": null}
  ],
  "providers": {"local": true, "hoziron_cloud": true}
}

status is "active", "expiring_soon" (≤7 days remaining), or "expired". cloud_spend is null when no Hoziron Cloud entitlement is provisioned. provider_entitlements is [] when the licence carries none; each entry's budget_usd/remaining_usd are null for an uncapped (unlimited-spend) entitlement.

Response (200) — no licence loaded

{
  "status": "no_licence",
  "message": "No carrier licence loaded — all model invocations are blocked. Install a licence to enable workflow execution.",
  "enforcement": "all_blocked"
}

Per the Carrier Licence Absolute Rule (see project CLAUDE.md), there is exactly one licensing path — no test/dev bypass exists for this gate.

Related

• health-status.md — /providers, /models (boot-time inventory the licence's routing gateway dispatches against)
• security.md — audit trail (a fuller picture of activity than usage/value-event aggregates provide)