FinOps Budgets

Read organizational budget gates for AI workflows: their scope, spend limits, threshold-based alert and pause actions, and current status.

Budgets are read-only through the REST API. They are created and managed by administrators through the platform UI and by internal platform services. The API exposes list and get only; it never creates, modifies, pauses, resumes, or deletes budgets.

All endpoints require authentication via the X-API-Key header and the finops:read scope.

---

Budget Object

{
  "_id": "bud_abc123",
  "name": "Q1 AI Spend",
  "description": "Quarterly AI workflow budget",
  "organizationId": "org_xyz",
  "scope": {
    "level": "organization",
    "id": "org_xyz"
  },
  "budget": {
    "amount": 10000,
    "currency": "USD",
    "type": "recurring",
    "period": "monthly",
    "resetDay": 1
  },
  "thresholds": [
    { "percent": 75, "action": "alert" },
    { "percent": 100, "action": "pause" }
  ],
  "status": "active",
  "enabled": true,
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-02-01T14:22:00Z"
}

---

GET /api/v1/finops/budgets

List FinOps budgets. The backend filters by the caller's organization.

Scope: finops:read

Query Parameters

Parameter	Type	Required	Description
scopeLevel	string	No	Filter by scope: platform, organization, user, resourceGroup, resource, resourceType, tag
status	string	No	Filter by status: active, paused, exhausted
limit	integer	No	Number of results to return
offset	integer	No	Number of results to skip

Response 200 OK

{
  "count": 1,
  "limit": 20,
  "offset": 0,
  "items": [
    {
      "_id": "bud_abc123",
      "name": "Q1 AI Spend",
      "scope": { "level": "organization", "id": "org_xyz" },
      "status": "active"
    }
  ]
}

---

GET /api/v1/finops/budgets/:id

Get a single FinOps budget by ID.

Scope: finops:read

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Budget ID

Response 200 OK

Returns the full Budget object.