UsageTimeseries

Usage, costs and forecasts over aligned buckets.

Fields

Field	Type	Description
scope *	object	Workspace or project scope.
from *	string (date-time)	UTC aligned range start.
to *	string (date-time)	UTC aligned exclusive range end.
step *	5m, 1h, 1d	Bucket size.
step_seconds *	integer	Nominal bucket length in seconds.
timezone *	Europe/London	Calendar timezone for daily buckets.
range *	7d, month, last_month, 90d or null	Shorthand range
group_by *	resource, service, environment, project	Grouping mode.
resources *	array of UsageResource	Resource filter applied.
buckets *	array of string (date-time)	UTC bucket start times.
days *	array of string (date)	London calendar date for each daily bucket; empty for other steps.
forecast_from *	integer or null	Index of the first future forecast bucket.
series *	array of UsageTimeseriesSeries	Grouped series.
totals *	array of UsageResourceTotal	Actual usage totals by resource.
total *	Money	Actual cost over the requested range.
forecast_total *	Money or any or null	Actual plus future forecast cost in the requested range.
month_to_date *	Money	Actual usage cost in the current London calendar month.
forecast_month_end *	Money	Current run-rate forecast for month end.
cap *	Money or any or null	Applicable spend cap.
busiest *	object or null	Largest CPU user over the range.
simulated *	boolean	Whether usage was synthesised for this response.
updated_at *	string (date-time)	Response calculation time in UTC.

* always present

Example

{
  "scope": {
    "type": "project",
    "id": "prj_example",
    "name": "Example"
  },
  "from": "2026-10-01T00:00:00Z",
  "to": "2026-11-01T00:00:00Z",
  "step": "1d",
  "step_seconds": 86400,
  "timezone": "Europe/London",
  "range": "month",
  "group_by": "resource",
  "resources": [
    "cpu"
  ],
  "buckets": [],
  "days": [],
  "forecast_from": null,
  "series": [],
  "totals": [],
  "total": {
    "amount": "0.000000",
    "currency": "GBP",
    "display": "£0.00"
  },
  "forecast_total": null,
  "month_to_date": {
    "amount": "0.000000",
    "currency": "GBP",
    "display": "£0.00"
  },
  "forecast_month_end": {
    "amount": "0.000000",
    "currency": "GBP",
    "display": "£0.00"
  },
  "cap": null,
  "busiest": null,
  "simulated": false,
  "updated_at": "2026-10-23T12:00:00Z"
}

Used by

• Workspace usage timeseries
• Project usage timeseries