---
title: "Get Usage Aggregate"
method: GET
path: "/v1/usage/aggregate"
tags: ["usage"]
---

# Get Usage Aggregate

`GET /v1/usage/aggregate`

## Request

- Base URL: `https://api.cyberdesk.io`
- URL: `https://api.cyberdesk.io/v1/usage/aggregate`
- Auth: HTTP bearer

Aggregate usage (agentic and cached steps) for a given date range.

Two modes are supported:
- **simulated** (default): Uses total_agentic_steps and total_cached_steps from usage_metadata,
  but excludes runs where billing_outcome is 'infra_failure' (these would have been free).
  Use this for customers not yet on Stripe billing.
- **billed**: Uses total_agentic_steps_billed and total_cached_steps_billed.
  Use this for customers on active Stripe billing.

## Query parameters

- `from_date` string, date-time, required: Start of period (inclusive, ISO format)
- `to_date` string, date-time, required: End of period (exclusive, ISO format)
- `mode` 'simulated' | 'billed': Mode for counting usage steps.

## Response `200`

Successful Response

- UsageAggregateResponse: Response schema for usage aggregation.
  - `total_agentic_steps` integer, required
  - `total_cached_steps` integer, required
  - `period_start` string, date-time, required
  - `period_end` string, date-time, required
  - `mode` 'simulated' | 'billed', required: Mode for counting usage steps.
  - `runs_counted` integer, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/cyberdesk-hq/apis/cyberdesk-cloud.md) - [All operations](https://skmtc.dev/cyberdesk-hq/apis/cyberdesk-cloud/llms.txt) - [OpenAPI document](https://skmtc.dev/cyberdesk-hq/apis/cyberdesk-cloud/revisions/5579352ae05e?raw)