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

# Get usage

`GET /v2/usage`

Returns call-minutes and sent-SMS usage for your organization, grouped by day, week, or month (UTC buckets; weekly buckets start on Monday). When from_date is omitted, the range defaults to the last 30 days for day, 12 weeks for week, and 12 months for month.

## Query parameters

- `group_by` 'day' | 'week' | 'month'
- `from_date` string, date-time
- `to_date` string, date-time

## Response `200`

Usage totals and per-period breakdown.

- GetUsageResponse
  - `group_by` 'day' | 'week' | 'month', required — Bucket granularity used for the breakdown.
  - `start_date` string, date-time, required — Start of the reported range (inclusive).
  - `end_date` string, date-time, required — End of the reported range (exclusive).
  - `total_minutes` number, required — Total call minutes used in the range.
  - `total_sms_sent` integer, required — Total outbound SMS messages sent in the range.
  - `breakdown` UsageBucket[], required
    - `period_start` string, required — UTC start date of the bucket (YYYY-MM-DD). Weekly buckets start on Monday.
    - `minutes` number, required — Call minutes used in this period, rounded to 2 decimals.
    - `sms_sent` integer, required — Outbound SMS messages sent in this period.

## Other responses

- `401` — Missing or invalid API key.
- `429` — Rate limit exceeded.
- `500` — Unexpected server error.

---

[API](https://skmtc.net/openmicai/apis/openmic-v1-external-api.md) · [All operations](https://skmtc.net/openmicai/apis/openmic-v1-external-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/openmicai/openmic-v1-external-api/revisions/58dc5cff0ca7/schema)