API reference: Cost forecast

The cost forecast endpoint returns a projection of AI spend for the current month based on the trailing 7-day rolling average burn rate. It supports three scopes: global (all users), per-group, and per-user.

All endpoints require admin authentication.

Base path: /api/admin/cost

Endpoints

Method	Path	Description
`GET`	`/api/admin/cost/forecast`	Get cost forecast with burn rate and projection

GET /api/admin/cost/forecast

Returns a cost forecast including the daily burn rate, projected month-end total, estimated budget exhaustion date (if a budget is configured), spend trend, and a confidence interval.

Authentication: Admin Bearer token

Query parameters:

Parameter	Type	Required	Description
`group_id`	UUID	No	Scope the forecast to a specific group
`user_id`	UUID	No	Scope the forecast to a specific user

If neither group_id nor user_id is provided, the forecast covers all users in the organization.

Response `200 OK`

CostForecastResponse schema:

Field	Type	Description
`daily_burn_rate`	float	Average daily spend over the trailing 7 days (USD)
`projected_monthly_total`	float	`daily_burn_rate × days_in_current_month` (USD)
`projected_exhaustion_date`	date \| null	Estimated date when the configured budget will be exhausted, or `null` if no budget is set or scope is global
`trend`	string	Spend trend: `"increasing"`, `"stable"`, or `"decreasing"`
`confidence_interval`	object	Low/high monthly projection bounds (see below)

confidence_interval schema:

Field	Type	Description
`low`	float	Monthly projection using the minimum daily cost in the trailing 14-day window (USD)
`high`	float	Monthly projection using the maximum daily cost in the trailing 14-day window (USD)

Example responses

Global forecast (no scope):

GET /api/admin/cost/forecast
Authorization: Bearer <admin_token>

{
  "daily_burn_rate": 14.235000,
  "projected_monthly_total": 440.285000,
  "projected_exhaustion_date": null,
  "trend": "increasing",
  "confidence_interval": {
    "low": 250.000000,
    "high": 620.000000
  }
}

Group-scoped forecast:

GET /api/admin/cost/forecast?group_id=grp_01abc123-...
Authorization: Bearer <admin_token>

{
  "daily_burn_rate": 3.420000,
  "projected_monthly_total": 105.900000,
  "projected_exhaustion_date": "2026-03-28",
  "trend": "stable",
  "confidence_interval": {
    "low": 80.000000,
    "high": 130.000000
  }
}

User-scoped forecast:

GET /api/admin/cost/forecast?user_id=usr_01abc123-...
Authorization: Bearer <admin_token>

{
  "daily_burn_rate": 0.940000,
  "projected_monthly_total": 29.140000,
  "projected_exhaustion_date": "2026-04-02",
  "trend": "decreasing",
  "confidence_interval": {
    "low": 18.000000,
    "high": 45.000000
  }
}

Forecast methodology

Burn rate

The daily_burn_rate is the average daily spend over the trailing 7-day window:

daily_burn_rate = total_cost(last 7 days) / 7

For global scope (no user_id or group_id), the total aggregates across all users. For scoped requests, only usage records belonging to the specified user or group members are included.

Monthly projection

projected_monthly_total = daily_burn_rate × days_in_current_month

This is a straight-line projection. Actual spend may differ if usage patterns change.

Exhaustion date

When a budget cap is configured for the user or group, the API calculates how many days of spend at the current burn rate remain before the budget is exhausted:

days_remaining = budget_remaining / daily_burn_rate
exhaustion_date = today + days_remaining

The global scope does not have a budget concept — projected_exhaustion_date is always null for global forecasts.

Trend

Trend compares the sum of costs in the most recent 7-day window against the prior 7 days:

"increasing" — spend is up more than 10% week-over-week
"decreasing" — spend is down more than 10% week-over-week
"stable" — spend change is within ±10%

Confidence interval

The confidence interval projects the full month at the minimum and maximum daily costs seen in the trailing 14-day window:

low  = min_daily_cost × days_in_current_month
high = max_daily_cost × days_in_current_month

A wide interval indicates volatile daily spend; a narrow interval suggests consistent usage.