---
title: "Usage"
method: GET
path: "/v2/billing/usage"
tags: ["billing"]
---

# Usage

`GET /v2/billing/usage`

## Request

- Base URL: `https://api.stuut.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.stuut.ai/v2/billing/usage`
- Auth: HTTP bearer

Return product-grouped usage totals and chart windows.

## Query parameters

- `window` 'DAY' | 'MONTH': Chart bucket size.
- `starting_on` string, date-time, nullable: Range start (inclusive); defaults to the current billing period.
- `ending_before` string, date-time, nullable: Range end (exclusive); defaults to the current billing period.

## Response `200`

Successful Response

- UsageResponse: Metered quantities grouped by Stuut product.
  - `starting_on` string, date-time, required: Range start (inclusive).
  - `ending_before` string, date-time, required: Range end (exclusive).
  - `window` 'DAY' | 'MONTH', required: Chart bucket size. MONTH is composed from authoritative per-month aggregates.
  - `products` ProductUsage[], required: Catalog products with authoritative metric totals and zero-filled chart windows.
    - `key` 'active_accounts' | 'collections' | 'cash_application' | 'deductions' | 'disputes' | 'voice' | 'sms', required: Stable slug for a product offered by Stuut.
    - `name` string, required: Customer-facing product name.
    - `metrics` MetricUsage[], required: The product's independently measured metrics; quantities with different units are never combined.
      - `metric_name` string, required: Stable Metronome billable-metric name.
      - `total` string, decimal, required: Authoritative usage across the full response range.
      - `groups` object, nullable, required: Authoritative full-range dimensional breakdown, when requested for this metric.
      - `windows` UsageWindow[], required: Zero-filled chart buckets for this metric.
        - `start` string, date-time, required: Window start.
        - `end` string, date-time, required: Window end.
        - `quantity` string, decimal, required: Metered UNITS consumed in the window (not money).
        - `groups` object, nullable, required: Dimensional breakdown of `quantity` by the metric's group key (e.g. disputes by activity: {'worked': 3, 'resolved': 1}); null for ungrouped metrics.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/stuut/apis/stuut-api.md) - [All operations](https://skmtc.dev/stuut/apis/stuut-api/llms.txt) - [OpenAPI document](https://skmtc.dev/stuut/apis/stuut-api/revisions/3b5ab941f918?raw)