Usage Reporting

Read-only endpoints that surface credit consumption for the admin Usage dashboard. All consumption is recorded in the append-only usage_event ledger and aggregated on read.

The usage ledger

Every metered activity appends one row to usage_event with the actor, resource type, credits charged, and resource-specific metadata. AI events are mirrored into the ledger from the AI audit log so all resource types share a single read path. The reporting endpoints below aggregate this ledger.

---

GET /api/usage

Aggregated credit usage for a date range, plus current budgets, credit pool, and License Manager sync health. Defaults to the current month when no range is supplied.

Authentication: Required (session)

Pre-blocks: permission.billing.manage

Query Parameters:

Parameter	Type	Default	Description
startDate	ISO date	start of current month	Range start (inclusive)
endDate	ISO date	now	Range end (inclusive)

Response:

{
  "usageSummary": [
    {
      "entityId": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
      "entityType": "app",
      "resourceType": "ai",
      "totalCredits": 1250.5,
      "totalEvents": 87
    }
  ],
  "dailyTotals": [
    { "date": "2026-05-01", "resourceType": "ai", "totalCredits": 120.0 }
  ],
  "budgets": [
    {
      "entityId": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
      "entityType": "app",
      "monthlyBudget": 2000,
      "creditsUsed": 1250.5,
      "isOverBudget": false,
      "budgetPercent": 62.5,
      "budgetRemaining": 749.5,
      "entity": { "name": "Sales Dashboard", "slug": "sales-dashboard", "ownerId": "jdoe" }
    }
  ],
  "creditPool": { "included": 50000, "used": 12340, "remaining": 37660 },
  "sync": {
    "syncedAt": "2026-05-23T12:00:00Z",
    "lastSyncFailedAt": null,
    "lastSyncFailureCode": null,
    "stalenessLevel": null
  }
}

The sync block surfaces License Manager connectivity so the UI can render a "license server unreachable" banner. lastSyncFailedAt is null when the most recent sync succeeded; lastSyncFailureCode is one of lm_unreachable, lm_unavailable, lm_error, or license_not_recognized.

---

GET /api/usage/monthly

Credit usage grouped by month and resource type, for the historical trend chart.

Authentication: Required (session)

Pre-blocks: permission.billing.manage

Query Parameters:

Parameter	Type	Default	Description
months	integer (1–24)	12	Number of trailing months to include

Response:

{
  "history": [
    { "month": "2026-05", "resourceType": "ai", "totalCredits": 4200.0, "totalEvents": 312 },
    { "month": "2026-05", "resourceType": "app_compute", "totalCredits": 180.0, "totalEvents": 540 }
  ],
  "creditPool": { "included": 50000, "used": 12340, "remaining": 37660 }
}

---

GET /api/usage/top-consumers

Top apps and top users (or agents) by credit consumption over a rolling window.

Authentication: Required (session)

Pre-blocks: permission.billing.manage

Query Parameters:

Parameter	Type	Default	Description
days	integer (1–365)	30	Rolling window size
limit	integer (1–50)	10	Max rows per list

Response:

{
  "windowDays": 30,
  "startDate": "2026-04-24",
  "endDate": "2026-05-23",
  "topApps": [
    {
      "entityId": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
      "entityType": "app",
      "name": "Sales Dashboard",
      "slug": "sales-dashboard",
      "totalCredits": 1250.5,
      "totalEvents": 87
    }
  ],
  "topUsers": [
    {
      "actor": "jdoe",
      "actorType": "user",
      "displayName": "Jane Doe",
      "totalCredits": 980.0,
      "totalEvents": 64
    }
  ]
}

---

GET /api/usage/resource-types

The canonical resource type registry. Read-only — types are defined in code and cannot be created or edited.

Authentication: Required (session)

Pre-blocks: permission.tenant.superuser

Response:

[
  { "slug": "ai", "name": "AI", "category": "ai", "mode": "event", "unit": "dollar" },
  { "slug": "agent_run", "name": "Agent Run", "category": "ai", "mode": "event", "unit": "run" },
  { "slug": "app_compute", "name": "App Compute", "category": "compute", "mode": "event", "unit": "second" },
  { "slug": "job_compute", "name": "Job Compute", "category": "compute", "mode": "event", "unit": "second" },
  { "slug": "app_storage", "name": "App Storage", "category": "storage", "mode": "gauge", "unit": "byte" },
  { "slug": "workspace_storage", "name": "Workspace Storage", "category": "storage", "mode": "gauge", "unit": "byte" },
  { "slug": "file_storage", "name": "File Storage", "category": "storage", "mode": "gauge", "unit": "byte" },
  { "slug": "es_index_count", "name": "ES Index Count", "category": "storage", "mode": "gauge", "unit": "index" }
]

Field	Description
slug	Stable identifier used on usage events
name	Display name
category	ai, compute, or storage
mode	event (per-occurrence) or gauge (point-in-time)
unit	Unit of the raw measurement before rate application