FinOps Budgets

Manage organizational budget gates for AI workflows, including budget creation, scope assignment, threshold-based alerts and pause actions, and lifecycle controls.

All endpoints require authentication via X-API-Key header and the appropriate 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. Backend filters by caller 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"
    }
  ]
}

---

POST /api/v1/finops/budgets

Create a new unified FinOps budget.

Scope: finops:write

Request Body

{
  "name": "Q1 AI Spend",
  "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" }
  ],
  "description": "Quarterly AI workflow budget",
  "enabled": true
}

Field	Type	Required	Description
name	string	Yes	Budget name
organizationId	string	Yes	Tenant org id
scope	object	Yes	Budget scope per schema (level: platform, organization, user, resourceGroup, resource, resourceType, tag)
budget	object	Yes	amount / currency / type / period / resetDay
thresholds	array	Yes	Array of {percent, action: "alert" | "pause"}
description	string	No	Budget description
enabled	boolean	No	Start active (default true)

Response 201 Created

{
  "budgetId": "bud_abc123"
}

---

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.

---

PUT /api/v1/finops/budgets/:id

Update an existing FinOps budget by ID.

Scope: finops:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Budget ID

Request Body

{
  "name": "Q1 AI Spend (revised)",
  "thresholds": [{ "percent": 90, "action": "pause" }],
  "enabled": true
}

Field	Type	Required	Description
name	string	No	Budget name
scope	object	No	Budget scope
budget	object	No	amount / period / resetDay / type
thresholds	array	No	Threshold list
description	string	No	Budget description
enabled	boolean	No	Enable or disable

Response 200 OK

Returns the updated Budget object.

---

DELETE /api/v1/finops/budgets/:id

Delete a FinOps budget by ID.

Scope: finops:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Budget ID

Response 204 No Content

---

POST /api/v1/finops/budgets/:id/pause

Pause a FinOps budget — suspends tracking and enforcement.

Scope: finops:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Budget ID

Response 200 OK

{
  "_id": "bud_abc123",
  "status": "paused"
}

---

POST /api/v1/finops/budgets/:id/resume

Resume a paused FinOps budget.

Scope: finops:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Budget ID

Response 200 OK

{
  "_id": "bud_abc123",
  "status": "active"
}