FinOps Costs

Cost tracking, attribution, and time-series queries for AI workloads, including realtime Kubecost data, historical breakdowns, trends, forecasts, anomalies, savings recommendations, and dashboard rollups.

All endpoints require authentication via X-API-Key header and the appropriate scope.

---

Cost Point Object

{
  "date": "2025-02-01T00:00:00Z",
  "total": 1234.56
}

---

GET /api/v1/finops/costs/monthly

Get monthly cost breakdown.

Scope: finops:read

Query Parameters

Parameter	Type	Required	Description
months	integer	No	Number of months to retrieve (default: 12)
year	integer	No	Year to filter costs for

Response 200 OK

{
  "months": [
    { "date": "2025-01-01T00:00:00Z", "total": 8123.45 }
  ],
  "summary": {
    "average_monthly": 8123.45,
    "highest_month": { "date": "2025-01-01T00:00:00Z", "total": 8123.45 },
    "lowest_month": { "date": "2025-01-01T00:00:00Z", "total": 8123.45 }
  }
}

---

GET /api/v1/finops/costs/daily

Get daily cost breakdown.

Scope: finops:read

Query Parameters

Parameter	Type	Required	Description
startDate	string	No	Start date (ISO 8601)
endDate	string	No	End date (ISO 8601)
resourceType	string	No	Filter by resource type

Response 200 OK

{
  "days": [
    { "date": "2025-02-01T00:00:00Z", "total": 410.22 }
  ],
  "summary": {
    "total_period": 12306.6,
    "daily_average": 410.22,
    "trend": "stable"
  }
}

---

GET /api/v1/finops/costs/forecast

Get cost forecast projections.

Scope: finops:read

Query Parameters

Parameter	Type	Required	Description
months	integer	No	Number of months to forecast (default: 3)
model	string	No	Forecast model to use

Response 200 OK

{
  "historical": [],
  "predictions": [
    {
      "date": "2025-03-01",
      "predicted": 8500,
      "lower_bound": 8000,
      "upper_bound": 9000
    }
  ],
  "analysis": {
    "trend": "stable",
    "monthly_growth_rate": 0.02,
    "confidence": "medium"
  }
}

---

GET /api/v1/finops/costs/services

Get cost breakdown grouped by service.

Scope: finops:read

Query Parameters

Parameter	Type	Required	Description
period	string	No	Time period (e.g. monthly, weekly); default 30d
startDate	string	No	Start date (ISO 8601)
endDate	string	No	End date (ISO 8601)

Response 200 OK

{
  "items": [
    {
      "group_key": "llm",
      "name": "LLM",
      "total_cost": 4321.0,
      "cpu_cost": 100,
      "ram_cost": 50,
      "storage_cost": 25,
      "network_cost": 10,
      "gpu_cost": 4136
    }
  ],
  "total_cost": 4321.0,
  "period_start": "2025-02-01T00:00:00Z",
  "period_end": "2025-02-28T00:00:00Z"
}

---

GET /api/v1/finops/costs/anomalies

Detect cost anomalies.

Scope: finops:read

Query Parameters

Parameter	Type	Required	Description
days	integer	No	Number of days to look back (default: 30)
threshold	number	No	Anomaly detection threshold (default: 2.0)

Response 200 OK

{
  "anomalies": [],
  "period": { "days": 30, "threshold": 2.0 }
}

---

GET /api/v1/finops/costs/savings

Get cost savings recommendations.

Scope: finops:read

Query Parameters

Parameter	Type	Required	Description
category	string	No	Savings category to filter by (e.g. rightsizing)
minSavings	number	No	Minimum savings amount threshold

Response 200 OK

{
  "recommendations": [
    {
      "resource": "workflow-worker-abc",
      "category": "rightsizing",
      "currentCost": 200,
      "potentialSavings": 60,
      "efficiency": 0.3,
      "recommendation": "Resource utilization is 30%. Consider reducing CPU/RAM requests to match actual usage."
    }
  ],
  "totalPotentialSavings": 60
}

---

GET /api/v1/finops/dashboard

Get FinOps dashboard overview with aggregated cost data.

Scope: finops:read

Response 200 OK

{
  "stats": {},
  "costTrend": {},
  "monthlyCosts": {
    "months": [],
    "summary": {
      "average_monthly": 0,
      "highest_month": null,
      "lowest_month": null
    }
  },
  "topDrivers": []
}

---

GET /api/v1/finops/dashboard/stats

Get FinOps dashboard statistics for a given time period.

Scope: finops:read

Query Parameters

Parameter	Type	Required	Description
period	string	No	Time window (default 30d)

Response 200 OK

Returns aggregated dashboard statistics for the requested window.

---

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

Get top cost drivers from the dashboard.

Scope: finops:read

Query Parameters

Parameter	Type	Required	Description
limit	integer	No	Maximum number of drivers to return (default: 10)
period	string	No	Time window (default 30d)

Response 200 OK

Returns an ordered list of top cost-driving resources.

---

GET /api/v1/finops/costs/realtime

Get realtime cost data from Kubecost.

Scope: finops:read

Query Parameters

Parameter	Type	Required	Description
window	string	No	Time window (e.g. 1d, 7d, 30d)
aggregate	string	No	Aggregation level (e.g. namespace, label)
namespace	string	No	Kubernetes namespace to filter by

Response 200 OK

Returns realtime cost items from Kubecost.

---

GET /api/v1/finops/costs/historical

Get historical cost data.

Scope: finops:read

Query Parameters

Parameter	Type	Required	Description
startDate	string	No	Start date (ISO 8601)
endDate	string	No	End date (ISO 8601)
groupBy	string	No	Group results by field
orgId	string	No	Organization ID to filter by
userId	string	No	User ID to filter by

Response 200 OK

Returns historical cost data for the supplied filters.

---

GET /api/v1/finops/costs/breakdown

Get multi-dimensional cost breakdown.

Scope: finops:read

Query Parameters

Parameter	Type	Required	Description
window	string	No	Time window (e.g. 1d, 7d, 30d)
orgId	string	No	Organization ID to filter by
userId	string	No	User ID to filter by
resourceType	string	No	Resource type to filter by
groupBy	string	No	Group results by field

Response 200 OK

Returns a multi-dimensional cost breakdown with totals and grouped items.

---

GET /api/v1/finops/costs/efficiency

Get resource efficiency metrics.

Scope: finops:read

Query Parameters

Parameter	Type	Required	Description
window	string	No	Time window (e.g. 1d, 7d, 30d)
namespace	string	No	Kubernetes namespace to filter by
aggregate	string	No	Aggregation level

Response 200 OK

Returns CPU / RAM / GPU efficiency metrics broken down by resource.

---

GET /api/v1/finops/costs/trends

Get cost trend time-series data.

Scope: finops:read

Query Parameters

Parameter	Type	Required	Description
window	string	No	Time window (e.g. 1d, 7d, 30d)
granularity	string	No	Data point granularity (e.g. hourly, daily, monthly)
groupBy	string	No	Group results by field

Response 200 OK

Returns time-series cost points with totals and change percentages.

---

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

Get top cost-driving resources.

Scope: finops:read

Query Parameters

Parameter	Type	Required	Description
window	string	No	Time window (e.g. 1d, 7d, 30d)
limit	integer	No	Maximum number of drivers to return
compareWindow	string	No	Comparison time window for change analysis

Response 200 OK

Returns the top cost-driving resources for the window, with optional change vs. compareWindow.

---

GET /api/v1/finops/data-health

Get the health status of cost data collection, including coverage percentages and any data gaps.

Scope: finops:read

Response 200 OK

Returns the FinOps data collection health report.