Entity Budgets

An entity budget caps the monthly credit spend of a single app or dataset, independent of any per-actor usage profile cap. Budgets reset at the start of each calendar month.

Budget fields

Field	Type	Description
entityId	UUID	The app or dataset ID
entityType	string	app or dataset
monthlyBudget	integer | null	Monthly cap in credits. null = no cap
creditsUsed	number	Credits consumed in the current period
periodStart	date	Start of the current monthly period
budgetRemaining	number | null	monthlyBudget - creditsUsed (≥ 0), or null when uncapped
budgetPercent	number	Percent of budget consumed (0–100)
isOverBudget	boolean	true once creditsUsed >= monthlyBudget

---

GET /api/usage-budgets/{entityType}/{entityId}

Get the budget for an app or dataset. A budget row is created on first access if one does not yet exist (with monthlyBudget: null).

Authentication: Required (session)

Pre-blocks: permission.tenant.superuser

Path Parameters:

Parameter	Type	Description
entityType	string	app or dataset
entityId	UUID	The entity's ID

Response:

{
  "id": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
  "entityId": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
  "entityType": "app",
  "monthlyBudget": 2000,
  "creditsUsed": 450.25,
  "periodStart": "2026-05-01T00:00:00Z",
  "hasBudget": true,
  "budgetRemaining": 1549.75,
  "budgetPercent": 22.5,
  "isOverBudget": false,
  "createdAt": "2026-05-01T00:00:00Z",
  "updatedAt": "2026-05-23T12:00:00Z"
}

The hasBudget, budgetRemaining, budgetPercent, and isOverBudget fields are computed getters serialized alongside the stored columns.

---

PUT /api/usage-budgets/{entityType}/{entityId}

Set or clear the monthly budget for an app or dataset.

Authentication: Required (session)

Pre-blocks: permission.usage.write

Request Body:

Field	Type	Required	Description
monthlyBudget	integer | null	No	Monthly cap in credits, or null to remove the cap. Omitting the field is accepted as a no-op.

Example Request:

{ "monthlyBudget": 2000 }

Response:

Returns the updated budget object (same shape as GET).