# UsageTimeseries

> Usage, costs and forecasts over aligned buckets.

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](/docs/api/objects/usage-resource/) | 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](/docs/api/objects/usage-timeseries-series/) | Grouped series. |
| `totals` * | array of [UsageResourceTotal](/docs/api/objects/usage-resource-total/) | Actual usage totals by resource. |
| `total` * | [Money](/docs/api/objects/money/) | Actual cost over the requested range. |
| `forecast_total` * | [Money](/docs/api/objects/money/) or any or null | Actual plus future forecast cost in the requested range. |
| `month_to_date` * | [Money](/docs/api/objects/money/) | Actual usage cost in the current London calendar month. |
| `forecast_month_end` * | [Money](/docs/api/objects/money/) | Current run-rate forecast for month end. |
| `cap` * | [Money](/docs/api/objects/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

```json
{
  "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](/docs/api/spend/#workspace-usage-timeseries)
- [Project usage timeseries](/docs/api/spend/#project-usage-timeseries)