FinOps

Manage cloud financial operations including cost tracking, budget management, resource scheduling, and resource grouping. Monitor spending, forecast costs, detect anomalies, and optimize cloud resource utilization programmatically.

All endpoints require a valid API key with the appropriate finops:* scope.

Base URL: https://<your-instance>/api/v1

---

Budget Object

{
  "id": "bgt_abc123",
  "name": "Q1 Infrastructure Budget",
  "description": "Quarterly budget for all infrastructure resources",
  "scope": {
    "level": "organization",
    "resourceTypes": ["addon", "app", "workflow"]
  },
  "budget": {
    "amount": 50000,
    "currency": "USD",
    "period": "monthly"
  },
  "amount": 50000,
  "currency": "USD",
  "period": "monthly",
  "currentSpend": 32450.75,
  "status": "on_track",
  "enabled": true,
  "organizationId": "org_xyz789",
  "alerts": [
    {
      "threshold": 80,
      "type": "percentage",
      "channels": ["email", "slack"]
    },
    {
      "threshold": 95,
      "type": "percentage",
      "channels": ["email", "slack", "pagerduty"]
    }
  ],
  "createdAt": "2025-01-01T00:00:00Z",
  "updatedAt": "2025-03-15T12:00:00Z"
}

Schedule Object

{
  "id": "sched_def456",
  "name": "Dev Environment Shutdown",
  "description": "Stop development resources outside business hours",
  "scope": {
    "level": "tag",
    "tags": { "environment": "development" }
  },
  "schedule": {
    "cron": "0 19 * * 1-5",
    "timezone": "America/New_York",
    "action": "stop"
  },
  "status": "active",
  "enabled": true,
  "cron": "0 19 * * 1-5",
  "action": "stop",
  "target": {
    "resourceType": "addon",
    "filter": { "environment": "development" }
  },
  "organizationId": "org_xyz789",
  "lastRun": "2025-03-19T19:00:00Z",
  "nextRun": "2025-03-20T19:00:00Z",
  "createdAt": "2025-01-15T08:00:00Z",
  "updatedAt": "2025-03-19T19:00:00Z"
}

ResourceGroup Object

{
  "id": "rg_ghi789",
  "name": "Payment Processing Stack",
  "description": "All resources related to payment processing",
  "status": "active",
  "organizationId": "org_xyz789",
  "resources": [
    {
      "type": "addon",
      "resourceId": "addon_abc123",
      "name": "Payment PostgreSQL"
    },
    {
      "type": "app",
      "resourceId": "app_def456",
      "name": "Payment API Service"
    }
  ],
  "tags": {
    "team": "payments",
    "environment": "production"
  },
  "totalCost": 8750.25,
  "createdAt": "2025-02-01T08:00:00Z",
  "updatedAt": "2025-03-20T12:00:00Z"
}

---

Costs

---

GET /api/v1/finops/costs/monthly

Retrieve monthly cost breakdown. Returns aggregated costs per month for the specified time range.

Scope: finops:read

Query Parameters

Parameter	Type	Required	Default	Description
months	integer	No	6	Number of months of history to return
year	integer	No	—	Filter to a specific year (defaults to current year)

Response 200 OK

{
  "data": [
    {
      "month": "2025-01",
      "totalCost": 42350.00,
      "currency": "USD",
      "breakdown": {
        "compute": 18500.00,
        "storage": 8200.00,
        "network": 3150.00,
        "addons": 7500.00,
        "aiInference": 5000.00
      }
    },
    {
      "month": "2025-02",
      "totalCost": 45120.50,
      "currency": "USD",
      "breakdown": {
        "compute": 19800.00,
        "storage": 8500.00,
        "network": 3320.50,
        "addons": 7800.00,
        "aiInference": 5700.00
      }
    },
    {
      "month": "2025-03",
      "totalCost": 38900.75,
      "currency": "USD",
      "breakdown": {
        "compute": 17200.00,
        "storage": 8100.00,
        "network": 2900.75,
        "addons": 6200.00,
        "aiInference": 4500.00
      }
    }
  ],
  "period": {
    "start": "2025-01",
    "end": "2025-03",
    "months": 3
  }
}

---

GET /api/v1/finops/costs/daily

Retrieve daily cost breakdown for granular analysis.

Scope: finops:read

Query Parameters

Parameter	Type	Required	Default	Description
startDate	string	No	—	Start date in ISO 8601 format (defaults to 30 days ago)
endDate	string	No	—	End date in ISO 8601 format (defaults to today)
resourceType	string	No	—	Filter by resource type: addon, app, workflow, model

Response 200 OK

{
  "data": [
    {
      "date": "2025-03-18",
      "totalCost": 1523.40,
      "currency": "USD",
      "breakdown": {
        "compute": 680.00,
        "storage": 270.00,
        "network": 103.40,
        "addons": 250.00,
        "aiInference": 220.00
      }
    },
    {
      "date": "2025-03-19",
      "totalCost": 1490.25,
      "currency": "USD",
      "breakdown": {
        "compute": 665.00,
        "storage": 270.00,
        "network": 95.25,
        "addons": 250.00,
        "aiInference": 210.00
      }
    }
  ],
  "period": {
    "start": "2025-03-18",
    "end": "2025-03-19"
  }
}

---

GET /api/v1/finops/costs/forecast

Retrieve cost forecasts based on historical spending patterns.

Scope: finops:read

Query Parameters

Parameter	Type	Required	Default	Description
months	integer	No	3	Number of months to forecast
model	string	No	linear	Forecast model: linear, seasonal, ml

Response 200 OK

{
  "forecast": [
    {
      "month": "2025-04",
      "predictedCost": 47200.00,
      "confidence": {
        "low": 42500.00,
        "high": 51900.00
      },
      "currency": "USD"
    },
    {
      "month": "2025-05",
      "predictedCost": 48500.00,
      "confidence": {
        "low": 43000.00,
        "high": 54000.00
      },
      "currency": "USD"
    },
    {
      "month": "2025-06",
      "predictedCost": 49800.00,
      "confidence": {
        "low": 43500.00,
        "high": 56100.00
      },
      "currency": "USD"
    }
  ],
  "model": "linear",
  "basedOn": {
    "months": 6,
    "dataPoints": 180
  },
  "generatedAt": "2025-03-20T14:00:00Z"
}

---

GET /api/v1/finops/costs/services

Retrieve cost breakdown by service for identifying top spending areas.

Scope: finops:read

Query Parameters

Parameter	Type	Required	Default	Description
period	string	No	monthly	Aggregation period: daily, weekly, monthly
startDate	string	No	—	Start date in ISO 8601 format
endDate	string	No	—	End date in ISO 8601 format

Response 200 OK

{
  "data": [
    {
      "service": "compute",
      "totalCost": 19800.00,
      "percentage": 43.9,
      "trend": "up",
      "changePercent": 7.0,
      "currency": "USD"
    },
    {
      "service": "storage",
      "totalCost": 8500.00,
      "percentage": 18.8,
      "trend": "stable",
      "changePercent": 1.2,
      "currency": "USD"
    },
    {
      "service": "aiInference",
      "totalCost": 5700.00,
      "percentage": 12.6,
      "trend": "up",
      "changePercent": 14.0,
      "currency": "USD"
    },
    {
      "service": "addons",
      "totalCost": 7800.00,
      "percentage": 17.3,
      "trend": "up",
      "changePercent": 4.0,
      "currency": "USD"
    },
    {
      "service": "network",
      "totalCost": 3320.50,
      "percentage": 7.4,
      "trend": "stable",
      "changePercent": 0.5,
      "currency": "USD"
    }
  ],
  "period": "monthly",
  "total": 45120.50,
  "currency": "USD"
}

---

GET /api/v1/finops/costs/anomalies

Detect cost anomalies by comparing recent spending against historical baselines.

Scope: finops:read

Query Parameters

Parameter	Type	Required	Default	Description
days	integer	No	30	Number of days to analyze for anomalies
threshold	number	No	2.0	Standard deviation threshold for anomaly detection

Response 200 OK

{
  "anomalies": [
    {
      "date": "2025-03-12",
      "service": "aiInference",
      "actualCost": 450.00,
      "expectedCost": 210.00,
      "deviation": 2.8,
      "severity": "high",
      "description": "AI inference costs 114% above expected baseline",
      "currency": "USD"
    },
    {
      "date": "2025-03-15",
      "service": "compute",
      "actualCost": 1200.00,
      "expectedCost": 680.00,
      "deviation": 2.3,
      "severity": "medium",
      "description": "Compute costs 76% above expected baseline",
      "currency": "USD"
    }
  ],
  "period": {
    "start": "2025-02-18",
    "end": "2025-03-20",
    "days": 30
  },
  "threshold": 2.0,
  "generatedAt": "2025-03-20T14:00:00Z"
}

---

GET /api/v1/finops/costs/savings

Retrieve savings opportunities and optimization recommendations.

Scope: finops:read

Query Parameters

Parameter	Type	Required	Default	Description
category	string	No	—	Filter by category: rightsizing, scheduling, idle, reserved, spot
minSavings	number	No	—	Minimum estimated monthly savings to include

Response 200 OK

{
  "opportunities": [
    {
      "id": "sav_001",
      "category": "idle",
      "title": "Remove idle PostgreSQL addon",
      "description": "addon_xyz has had zero connections for 14 days",
      "resourceType": "addon",
      "resourceId": "addon_xyz",
      "resourceName": "Staging PostgreSQL",
      "estimatedMonthlySavings": 180.00,
      "confidence": "high",
      "currency": "USD"
    },
    {
      "id": "sav_002",
      "category": "rightsizing",
      "title": "Downsize over-provisioned app",
      "description": "app_abc averages 12% CPU utilization, recommend reducing from 2 CPU to 1 CPU",
      "resourceType": "app",
      "resourceId": "app_abc",
      "resourceName": "Internal Dashboard",
      "estimatedMonthlySavings": 95.00,
      "confidence": "medium",
      "currency": "USD"
    },
    {
      "id": "sav_003",
      "category": "scheduling",
      "title": "Schedule dev resources off-hours",
      "description": "5 development resources run 24/7 but are only accessed during business hours",
      "resourceType": "addon",
      "resourceId": null,
      "resourceName": null,
      "estimatedMonthlySavings": 420.00,
      "confidence": "high",
      "currency": "USD"
    }
  ],
  "totalEstimatedSavings": 695.00,
  "currency": "USD",
  "generatedAt": "2025-03-20T14:00:00Z"
}

---

GET /api/v1/finops/dashboard

Retrieve the FinOps dashboard with a consolidated view of costs, budgets, and optimization opportunities.

Scope: finops:read

Response 200 OK

{
  "currentMonth": {
    "totalCost": 38900.75,
    "budget": 50000.00,
    "budgetUtilization": 77.8,
    "forecastEndOfMonth": 48500.00,
    "currency": "USD"
  },
  "costTrend": {
    "direction": "up",
    "changePercent": 6.5,
    "comparedTo": "previous_month"
  },
  "topServices": [
    { "service": "compute", "cost": 17200.00, "percentage": 44.2 },
    { "service": "storage", "cost": 8100.00, "percentage": 20.8 },
    { "service": "addons", "cost": 6200.00, "percentage": 15.9 }
  ],
  "activeBudgets": 4,
  "budgetsAtRisk": 1,
  "savingsOpportunities": 695.00,
  "anomaliesDetected": 2,
  "generatedAt": "2025-03-20T14:00:00Z"
}

---

GET /api/v1/finops/dashboard/stats

Retrieve dashboard summary statistics for the specified period.

Scope: finops:read

Query Parameters

Parameter	Type	Required	Default	Description
period	string	No	monthly	Statistics period: daily, weekly, monthly, quarterly

Response 200 OK

{
  "period": "monthly",
  "totalSpend": 45120.50,
  "previousPeriodSpend": 42350.00,
  "changePercent": 6.5,
  "averageDailyCost": 1504.02,
  "peakDailyCost": 1890.00,
  "peakDate": "2025-03-12",
  "resourceCount": 42,
  "costPerResource": 1074.30,
  "currency": "USD",
  "generatedAt": "2025-03-20T14:00:00Z"
}

---

GET /api/v1/finops/dashboard/top-drivers

Retrieve the top cost drivers, identifying which resources contribute the most to overall spending.

Scope: finops:read

Query Parameters

Parameter	Type	Required	Default	Description
limit	integer	No	10	Number of top drivers to return (1-50)
period	string	No	monthly	Analysis period: daily, weekly, monthly

Response 200 OK

{
  "drivers": [
    {
      "rank": 1,
      "resourceType": "app",
      "resourceId": "app_prod001",
      "resourceName": "Production API Gateway",
      "cost": 4200.00,
      "percentage": 9.3,
      "trend": "stable",
      "currency": "USD"
    },
    {
      "rank": 2,
      "resourceType": "addon",
      "resourceId": "addon_db001",
      "resourceName": "Production PostgreSQL",
      "cost": 3800.00,
      "percentage": 8.4,
      "trend": "up",
      "currency": "USD"
    },
    {
      "rank": 3,
      "resourceType": "workflow",
      "resourceId": "wf_ml001",
      "resourceName": "ML Training Pipeline",
      "cost": 3200.00,
      "percentage": 7.1,
      "trend": "up",
      "currency": "USD"
    }
  ],
  "period": "monthly",
  "totalCost": 45120.50,
  "currency": "USD",
  "generatedAt": "2025-03-20T14:00:00Z"
}

---

Budgets

---

GET /api/v1/finops/budgets

List all budgets accessible to the authenticated user.

Scope: finops:read

Query Parameters

Parameter	Type	Required	Default	Description
search	string	No	—	Search by budget name or description
status	string	No	—	Filter by status: on_track, at_risk, exceeded, paused
scopeLevel	string	No	—	Filter by scope level: organization, team, project, resource
enabled	boolean	No	—	Filter by enabled state
limit	integer	No	20	Maximum number of results to return (1-100)
offset	integer	No	0	Number of results to skip for pagination
sort	string	No	createdAt:desc	Sort field and direction, e.g. name:asc, currentSpend:desc

Response 200 OK

{
  "data": [
    {
      "id": "bgt_abc123",
      "name": "Q1 Infrastructure Budget",
      "description": "Quarterly budget for all infrastructure resources",
      "scope": {
        "level": "organization",
        "resourceTypes": ["addon", "app", "workflow"]
      },
      "budget": {
        "amount": 50000,
        "currency": "USD",
        "period": "monthly"
      },
      "amount": 50000,
      "currency": "USD",
      "period": "monthly",
      "currentSpend": 32450.75,
      "status": "on_track",
      "enabled": true,
      "organizationId": "org_xyz789",
      "alerts": [],
      "createdAt": "2025-01-01T00:00:00Z",
      "updatedAt": "2025-03-15T12:00:00Z"
    }
  ],
  "pagination": {
    "total": 4,
    "limit": 20,
    "offset": 0,
    "hasMore": false
  }
}

---

POST /api/v1/finops/budgets

Create a new budget with optional alert thresholds.

Scope: finops:write

Request Body

Field	Type	Required	Description
name	string	Yes	Human-readable name for the budget
scope	object	Yes	Budget scope with level and optional resourceTypes, tags, or teamId
budget	object	Yes	Budget definition with amount, currency, and period
description	string	No	Description of the budget purpose
alerts	array	No	Array of alert configurations with threshold, type, and channels

{
  "name": "AI Inference Monthly Cap",
  "scope": {
    "level": "project",
    "resourceTypes": ["model"],
    "tags": { "department": "data-science" }
  },
  "budget": {
    "amount": 10000,
    "currency": "USD",
    "period": "monthly"
  },
  "description": "Monthly spending cap for AI inference workloads",
  "alerts": [
    {
      "threshold": 75,
      "type": "percentage",
      "channels": ["email"]
    },
    {
      "threshold": 90,
      "type": "percentage",
      "channels": ["email", "slack"]
    },
    {
      "threshold": 100,
      "type": "percentage",
      "channels": ["email", "slack", "pagerduty"]
    }
  ]
}

Response 201 Created

Returns the full Budget object.

---

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

Retrieve a single budget by its ID.

Scope: finops:read

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	The budget ID

Response 200 OK

Returns the full Budget object.

---

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

Update an existing budget. Only provided fields are updated.

Scope: finops:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	The budget ID

Request Body

Field	Type	Required	Description
name	string	No	Updated budget name
description	string	No	Updated description
scope	object	No	Updated budget scope
budget	object	No	Updated budget definition (amount, currency, period)
alerts	array	No	Updated alert configurations
enabled	boolean	No	Enable or disable the budget

{
  "budget": {
    "amount": 12000,
    "currency": "USD",
    "period": "monthly"
  },
  "alerts": [
    {
      "threshold": 80,
      "type": "percentage",
      "channels": ["email", "slack"]
    }
  ]
}

Response 200 OK

Returns the updated Budget object.

---

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

Permanently delete a budget and all associated alert configurations.

Scope: finops:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	The budget ID

Response 204 No Content

No response body.

---

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

Pause a budget. Paused budgets stop tracking spend and sending alerts.

Scope: finops:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	The budget ID

Response 200 OK

{
  "id": "bgt_abc123",
  "status": "paused",
  "enabled": false,
  "updatedAt": "2025-03-20T15:00:00Z"
}

---

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

Resume a paused budget. The budget will resume tracking from the current spend level.

Scope: finops:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	The budget ID

Response 200 OK

{
  "id": "bgt_abc123",
  "status": "on_track",
  "enabled": true,
  "updatedAt": "2025-03-20T15:30:00Z"
}

---

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

Reset a budget's current spend counter to zero. Useful for starting a new tracking period manually.

Scope: finops:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	The budget ID

Response 200 OK

{
  "id": "bgt_abc123",
  "currentSpend": 0,
  "status": "on_track",
  "updatedAt": "2025-03-20T16:00:00Z"
}

---

GET /api/v1/finops/budgets/summary

Retrieve a summary of all budgets with aggregated health metrics.

Scope: finops:read

Response 200 OK

{
  "totalBudgets": 4,
  "activeBudgets": 3,
  "pausedBudgets": 1,
  "byStatus": {
    "on_track": 2,
    "at_risk": 1,
    "exceeded": 0,
    "paused": 1
  },
  "totalBudgeted": 150000.00,
  "totalSpent": 98500.75,
  "overallUtilization": 65.7,
  "currency": "USD",
  "generatedAt": "2025-03-20T14:00:00Z"
}

---

Schedules

---

GET /api/v1/finops/schedules

List all resource schedules. Schedules automate start/stop actions to reduce costs during off-peak hours.

Scope: finops:read

Query Parameters

Parameter	Type	Required	Default	Description
search	string	No	—	Search by schedule name or description
status	string	No	—	Filter by status: active, paused, failed
scopeLevel	string	No	—	Filter by scope level: resource, tag, team
enabled	boolean	No	—	Filter by enabled state
limit	integer	No	20	Maximum number of results to return (1-100)
offset	integer	No	0	Number of results to skip for pagination
sort	string	No	createdAt:desc	Sort field and direction, e.g. name:asc, nextRun:asc

Response 200 OK

{
  "data": [
    {
      "id": "sched_def456",
      "name": "Dev Environment Shutdown",
      "description": "Stop development resources outside business hours",
      "scope": {
        "level": "tag",
        "tags": { "environment": "development" }
      },
      "schedule": {
        "cron": "0 19 * * 1-5",
        "timezone": "America/New_York",
        "action": "stop"
      },
      "status": "active",
      "enabled": true,
      "cron": "0 19 * * 1-5",
      "action": "stop",
      "target": {
        "resourceType": "addon",
        "filter": { "environment": "development" }
      },
      "organizationId": "org_xyz789",
      "lastRun": "2025-03-19T19:00:00Z",
      "nextRun": "2025-03-20T19:00:00Z",
      "createdAt": "2025-01-15T08:00:00Z",
      "updatedAt": "2025-03-19T19:00:00Z"
    }
  ],
  "pagination": {
    "total": 6,
    "limit": 20,
    "offset": 0,
    "hasMore": false
  }
}

---

POST /api/v1/finops/schedules

Create a new resource schedule.

Scope: finops:write

Request Body

Field	Type	Required	Description
name	string	Yes	Human-readable name for the schedule
scope	object	Yes	Schedule scope with level and resource targeting
schedule	object	Yes	Schedule definition with cron, timezone, and action
description	string	No	Description of the schedule purpose
target	object	No	Target resource configuration with resourceType and filter
enabled	boolean	No	Whether the schedule is active (default: true)

{
  "name": "Dev Startup Morning",
  "scope": {
    "level": "tag",
    "tags": { "environment": "development" }
  },
  "schedule": {
    "cron": "0 8 * * 1-5",
    "timezone": "America/New_York",
    "action": "start"
  },
  "description": "Start development resources at beginning of business hours",
  "target": {
    "resourceType": "addon",
    "filter": { "environment": "development" }
  },
  "enabled": true
}

Response 201 Created

Returns the full Schedule object.

---

GET /api/v1/finops/schedules/:id

Retrieve a single schedule by its ID.

Scope: finops:read

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	The schedule ID

Response 200 OK

Returns the full Schedule object.

---

PUT /api/v1/finops/schedules/:id

Update an existing schedule. Only provided fields are updated.

Scope: finops:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	The schedule ID

Request Body

Field	Type	Required	Description
name	string	No	Updated schedule name
description	string	No	Updated description
scope	object	No	Updated scope configuration
schedule	object	No	Updated schedule definition (cron, timezone, action)
target	object	No	Updated target configuration
enabled	boolean	No	Enable or disable the schedule

{
  "schedule": {
    "cron": "0 20 * * 1-5",
    "timezone": "America/New_York",
    "action": "stop"
  },
  "description": "Updated: shutdown moved to 8 PM ET"
}

Response 200 OK

Returns the updated Schedule object.

---

DELETE /api/v1/finops/schedules/:id

Permanently delete a schedule. Running executions will complete but no future runs will be triggered.

Scope: finops:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	The schedule ID

Response 204 No Content

No response body.

---

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

Pause a schedule. The schedule will not trigger until resumed.

Scope: finops:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	The schedule ID

Response 200 OK

{
  "id": "sched_def456",
  "status": "paused",
  "enabled": false,
  "nextRun": null,
  "updatedAt": "2025-03-20T15:00:00Z"
}

---

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

Resume a paused schedule. The next run time will be recalculated from the cron expression.

Scope: finops:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	The schedule ID

Response 200 OK

{
  "id": "sched_def456",
  "status": "active",
  "enabled": true,
  "nextRun": "2025-03-20T19:00:00Z",
  "updatedAt": "2025-03-20T15:30:00Z"
}

---

POST /api/v1/finops/schedules/:id/execute

Manually trigger immediate execution of a schedule, regardless of the cron timing.

Scope: finops:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	The schedule ID

Response 200 OK

{
  "id": "sched_def456",
  "executionId": "exec_abc123",
  "action": "stop",
  "status": "executing",
  "triggeredBy": "manual",
  "startedAt": "2025-03-20T16:00:00Z"
}

---

GET /api/v1/finops/schedules/:id/history

Retrieve execution history for a schedule.

Scope: finops:read

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	The schedule ID

Response 200 OK

{
  "data": [
    {
      "executionId": "exec_abc123",
      "action": "stop",
      "status": "completed",
      "triggeredBy": "cron",
      "resourcesAffected": 5,
      "startedAt": "2025-03-19T19:00:00Z",
      "completedAt": "2025-03-19T19:02:30Z",
      "estimatedSavings": 14.00,
      "currency": "USD"
    },
    {
      "executionId": "exec_def456",
      "action": "stop",
      "status": "completed",
      "triggeredBy": "cron",
      "resourcesAffected": 5,
      "startedAt": "2025-03-18T19:00:00Z",
      "completedAt": "2025-03-18T19:01:45Z",
      "estimatedSavings": 14.00,
      "currency": "USD"
    }
  ],
  "scheduleId": "sched_def456",
  "totalExecutions": 45
}

---

Resource Groups

---

GET /api/v1/finops/resource-groups

List all resource groups. Resource groups organize related resources for unified cost tracking and management.

Scope: finops:read

Query Parameters

Parameter	Type	Required	Default	Description
search	string	No	—	Search by group name or description
status	string	No	—	Filter by status: active, archived
limit	integer	No	20	Maximum number of results to return (1-100)
offset	integer	No	0	Number of results to skip for pagination
sort	string	No	createdAt:desc	Sort field and direction, e.g. name:asc, totalCost:desc

Response 200 OK

{
  "data": [
    {
      "id": "rg_ghi789",
      "name": "Payment Processing Stack",
      "description": "All resources related to payment processing",
      "status": "active",
      "organizationId": "org_xyz789",
      "resources": [
        {
          "type": "addon",
          "resourceId": "addon_abc123",
          "name": "Payment PostgreSQL"
        },
        {
          "type": "app",
          "resourceId": "app_def456",
          "name": "Payment API Service"
        }
      ],
      "tags": {
        "team": "payments",
        "environment": "production"
      },
      "totalCost": 8750.25,
      "createdAt": "2025-02-01T08:00:00Z",
      "updatedAt": "2025-03-20T12:00:00Z"
    }
  ],
  "pagination": {
    "total": 8,
    "limit": 20,
    "offset": 0,
    "hasMore": false
  }
}

---

POST /api/v1/finops/resource-groups

Create a new resource group.

Scope: finops:write

Request Body

Field	Type	Required	Description
name	string	Yes	Human-readable name for the resource group
description	string	No	Description of the resource group purpose
tags	object	No	Key-value pairs for categorization and filtering

{
  "name": "ML Training Infrastructure",
  "description": "GPU instances and storage for model training pipelines",
  "tags": {
    "team": "data-science",
    "environment": "production",
    "costCenter": "ml-ops"
  }
}

Response 201 Created

Returns the full ResourceGroup object.

---

GET /api/v1/finops/resource-groups/:id

Retrieve a single resource group by its ID.

Scope: finops:read

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	The resource group ID

Response 200 OK

Returns the full ResourceGroup object.

---

PUT /api/v1/finops/resource-groups/:id

Update an existing resource group. Only provided fields are updated.

Scope: finops:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	The resource group ID

Request Body

Field	Type	Required	Description
name	string	No	Updated group name
description	string	No	Updated description
tags	object	No	Updated tags (replaces existing tags)

{
  "description": "GPU instances, storage, and inference endpoints for ML workloads",
  "tags": {
    "team": "data-science",
    "environment": "production",
    "costCenter": "ml-ops",
    "priority": "high"
  }
}

Response 200 OK

Returns the updated ResourceGroup object.

---

DELETE /api/v1/finops/resource-groups/:id

Permanently delete a resource group. The underlying resources are not affected.

Scope: finops:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	The resource group ID

Response 204 No Content

No response body.

---

POST /api/v1/finops/resource-groups/:id/resources

Add a resource to a resource group.

Scope: finops:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	The resource group ID

Request Body

Field	Type	Required	Description
type	string	Yes	Resource type: addon, app, workflow, model
resourceId	string	Yes	The ID of the resource to add
name	string	Yes	Display name for the resource within the group

{
  "type": "addon",
  "resourceId": "addon_gpu001",
  "name": "Training GPU PostgreSQL"
}

Response 200 OK

{
  "id": "rg_ghi789",
  "resources": [
    {
      "type": "addon",
      "resourceId": "addon_abc123",
      "name": "Payment PostgreSQL"
    },
    {
      "type": "app",
      "resourceId": "app_def456",
      "name": "Payment API Service"
    },
    {
      "type": "addon",
      "resourceId": "addon_gpu001",
      "name": "Training GPU PostgreSQL"
    }
  ],
  "updatedAt": "2025-03-20T16:00:00Z"
}

---

DELETE /api/v1/finops/resource-groups/:id/resources/:resourceId

Remove a resource from a resource group. The underlying resource is not affected.

Scope: finops:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	The resource group ID
resourceId	string	Yes	The resource ID to remove from the group

Response 200 OK

{
  "id": "rg_ghi789",
  "resources": [
    {
      "type": "addon",
      "resourceId": "addon_abc123",
      "name": "Payment PostgreSQL"
    },
    {
      "type": "app",
      "resourceId": "app_def456",
      "name": "Payment API Service"
    }
  ],
  "updatedAt": "2025-03-20T16:30:00Z"
}

---

Error Responses

All endpoints may return the following error responses:

Status	Description
400 Bad Request	Invalid request body or parameters
401 Unauthorized	Missing or invalid API key
403 Forbidden	Insufficient scope for the requested operation
404 Not Found	Resource not found or not accessible
409 Conflict	Conflicting state or duplicate name
422 Unprocessable Entity	Validation error on request body
429 Too Many Requests	Rate limit exceeded
500 Internal Server Error	Unexpected server error

{
  "error": {
    "code": "budget_exceeded",
    "message": "Cannot resume budget: current spend already exceeds budget amount",
    "status": 409
  }
}