Skip to main content

FinOps Costs

FinOps Costs is the cost explorer: monthly/daily spend, forecasts, service breakdowns, anomalies, savings, and dashboard rollups. All endpoints are read-only analytics.

Access it as client.finops.costs on a Strongly client, or the same path on AsyncStrongly with await. All methods exist on both with identical signatures.

Methods​

All methods​

anomalies​

anomalies(*, days: int | None = None, sensitivity: Sensitivity | None = None) -> CostAnomalies

Return resources whose cost on the last whole day moved from their usual day.

A resource's usual day is its average day with cost in the lookback.

Parameters

  • days (int | None, optional): Days to look back; the API's default is 7.
  • sensitivity ({"low", "medium", "high"} | None, optional): The move that counts: at least 100% (low), 50% (medium, the API's default) or 25% (high).

Returns

  • CostAnomalies: The anomalies, largest move first, and the lookback and sensitivity used.

Raises

  • ValidationError: days is not a whole number, or an unknown sensitivity.

breakdown​

breakdown(*, window: str | None = None, group_by: str | None = None, resource_type: str | None = None, org_id: str | None = None, user_id: str | None = None, namespace: str | None = None) -> CostGroupBreakdown

Return the cost of each group with its parts, change and efficiency.

Parameters

  • window (str | None, optional): A window; the API's default is "30d".
  • group_by (str | None, optional): resource_type (the API's default), resource_id, org, user or namespace.
  • resource_type (str | None, optional): Only this type: a resource type (app, addon, workflow, workspace, self-hosted-model, fine-tuning, automl, model-registry, build, ...), platform (the baseline of no organization), platform-scaling (platform scaling caused by organization workloads) or platform:<org id> (one organization's).
  • org_id (str | None, optional): Only this organization (within what you may see).
  • user_id (str | None, optional): Only this user (within what you may see).
  • namespace (str | None, optional): Only this Kubernetes namespace.

Returns

  • CostGroupBreakdown: Each group's cost, most expensive first.

Raises

  • ValidationError: An unknown group_by, or the window is not one the API reads.

cost_top_drivers​

cost_top_drivers(*, window: str | None = None, limit: int | None = None) -> list[TopCostDriver]

Return the most expensive resources over a window.

Parameters

  • window (str | None, optional): A window; the API's default is "30d".
  • limit (int | None, optional): How many resources (1-100); the API's default is 10.

Returns

  • list[TopCostDriver]: The resources, most expensive first, with their GPU cost and efficiency.

Raises

  • ValidationError: limit is outside 1-100, or the window is not one the API reads.

daily​

daily(*, start_date: str | None = None, end_date: str | None = None, resource_type: str | None = None) -> DailyCosts

Return the cost of each UTC day, with its change on the previous period.

Parameters

  • start_date (str | None, optional): First day, YYYY-MM-DD; give it with end_date. Without both, the last 30 days.
  • end_date (str | None, optional): Last day, included, YYYY-MM-DD.
  • resource_type (str | None, optional): Only this resource type (app, workflow, workspace, self-hosted-model, ...).

Returns

  • DailyCosts: Each day's cost, oldest first, with the period's total, daily average and change on the previous period of the same length.

Raises

  • ValidationError: Only one of start_date and end_date is given.

dashboard​

dashboard() -> FinOpsDashboard

Return the FinOps overview.

The last 30 days' KPIs and daily cost, the last 6 calendar months and the 5 most expensive resources.

Returns

  • FinOpsDashboard: The overview.

dashboard_stats​

dashboard_stats(*, period: str | None = None) -> DashboardStats

Return the FinOps KPIs for a window (spend in US cents).

Parameters

  • period (str | None, optional): A window; the API's default is "30d".

Returns

  • DashboardStats: Spend and its change on the previous period, month to date, active resources, budget alerts and efficiency.

Raises

  • ValidationError: The window is not one the API reads.

data_health​

data_health() -> FinOpsDataHealth

Return the health of cost data collection (platform administrators).

Returns

  • FinOpsDataHealth: The status, the latest complete cost hour, coverage and the gaps.

Raises

  • PermissionDeniedError: The key's user is not a platform administrator.
  • ServiceUnavailableError: The health of cost data has not been recorded yet.

efficiency​

efficiency(*, window: str | None = None, group_by: str | None = None, resource_type: str | None = None, namespace: str | None = None) -> CostEfficiency

Return the CPU and memory the pods used against what they requested.

Parameters

  • window (str | None, optional): A window; the API's default is "30d".
  • group_by (str | None, optional): resource_type (the API's default), resource_id, org, user or namespace.
  • resource_type (str | None, optional): Only this resource type.
  • namespace (str | None, optional): Only this Kubernetes namespace.

Returns

  • CostEfficiency: CPU core-hours and memory byte-hours, overall and per group.

Raises

  • ValidationError: An unknown group_by, or the window is not one the API reads.

forecast​

forecast(*, months: int | None = None) -> CostForecast

Project daily cost from a line fit to the last 90 whole days.

Parameters

  • months (int | None, optional): Months to project (30 days each, 1-12); the API's default is 3.

Returns

  • CostForecast: The history, the projected days with their 95% prediction bounds, the monthly growth rate and a confidence level. Nothing is projected with under 3 days of history.

Raises

  • ValidationError: months is not a whole number from 1 to 12.

historical​

historical(*, start_date: str | None = None, end_date: str | None = None, group_by: str | None = None, org_id: str | None = None, user_id: str | None = None) -> HistoricalCosts

Return the cost of each group over a date range.

Parameters

  • start_date (str | None, optional): First day (YYYY-MM-DD or ISO 8601); give it with end_date. Without both, the last 30 days.
  • end_date (str | None, optional): Last day, included.
  • group_by (str | None, optional): resource_type (the API's default), resource_id, org, user or namespace.
  • org_id (str | None, optional): Only this organization (within what you may see).
  • user_id (str | None, optional): Only this user (within what you may see).

Returns

  • HistoricalCosts: Each group's cost and its parts, most expensive first.

Raises

  • ValidationError: Only one of start_date and end_date is given, or an unknown group_by.

monthly​

monthly(*, months: int | None = None, year: int | None = None) -> MonthlyCosts

Return the cost of each calendar month (UTC).

Parameters

  • months (int | None, optional): How many calendar months back, this one included; the API's default is 12.
  • year (int | None, optional): A calendar year's months instead (months is then ignored).

Returns

  • MonthlyCosts: Each month's cost, oldest first, with the average, highest and lowest month.

Raises

  • ValidationError: months is below 1.

realtime​

realtime(*, window: str | None = None, namespace: str | None = None) -> RealtimeCosts

Return each resource's cost over a recent window, with its parts and efficiency.

Parameters

  • window (str | None, optional): A window; the API's default is "1h" (the last complete hour).
  • namespace (str | None, optional): Only this Kubernetes namespace.

Returns

  • RealtimeCosts: Each resource's cost, most expensive first.

Raises

  • ValidationError: The window is not one the API reads.

savings​

savings(*, category: str | None = None, min_savings: float | None = None) -> SavingsRecommendations

Return rightsizing savings over the last 30 days.

A resource whose pods used under 40% of the CPU and memory they requested would save the cost of the unused share by lowering its requests.

Parameters

  • category (str | None, optional): rightsizing, the only category.
  • min_savings (float | None, optional): Only recommendations saving at least this many US dollars.

Returns

  • SavingsRecommendations: The recommendations, largest saving first, and their total.

Raises

  • ValidationError: A category other than rightsizing.

services​

services(*, period: str | None = None, start_date: str | None = None, end_date: str | None = None) -> ServiceCosts

Return the cost of each resource type (apps, workspaces, storage, ...).

Parameters

  • period (str | None, optional): A window; the API's default is "30d". Ignored when start_date and end_date are given.
  • start_date (str | None, optional): Start of a date range (YYYY-MM-DD or ISO 8601); give it with end_date.
  • end_date (str | None, optional): End of the range (a bare date is included).

Returns

  • ServiceCosts: Each resource type's cost and its parts, most expensive first.

Raises

  • ValidationError: Only one of start_date and end_date is given, or the window is not one the API reads.

top_drivers​

top_drivers(*, limit: int | None = None, period: str | None = None) -> list[TopCostDriver]

Return the most expensive resources over a window, as the dashboard shows them.

Parameters

  • limit (int | None, optional): How many resources (1-100); the API's default is 10.
  • period (str | None, optional): A window; the API's default is "30d".

Returns

  • list[TopCostDriver]: The resources, most expensive first.

Raises

  • ValidationError: limit is outside 1-100, or the window is not one the API reads.
trends(*, window: str | None = None, granularity: str | None = None, group_by: str | None = None, resource_type: str | None = None) -> CostTrend

Return the cost of each hour, day, week or month over a window.

Parameters

  • window (str | None, optional): A window; the API's default is "30d".
  • granularity (str | None, optional): hourly, daily (the API's default), weekly (from Monday) or monthly, in UTC.
  • group_by (str | None, optional): Break each point down by resource_type, resource_id, org, user or namespace.
  • resource_type (str | None, optional): Only this resource type.

Returns

  • CostTrend: The points, oldest first, with the window's total, daily average and change on the previous period of the same length.

Raises

  • ValidationError: An unknown granularity or group_by, or the window is not one the API reads.