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

# Get Usage Aggregate

`GET /v1/usage/aggregate`

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.net/cyberdesk-hq/apis/cyberdesk-cloud.md) · [All operations](https://skmtc.net/cyberdesk-hq/apis/cyberdesk-cloud/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/cyberdesk-hq/cyberdesk-cloud/versions/830d2f48963d/schema)