---
title: "Get account usage"
method: GET
path: "/api/v1/usage"
tags: ["usage"]
---

# Get account usage

`GET /api/v1/usage`

Activity analytics for the account over a selected window, derived from real message and call records: headline metrics with per-day spark series and deltas, a daily activity series, voice-call duration stats, the most active numbers, and fixed-window breakdown totals.

## Query parameters

- `days` '7' | '30' | '90'

## Headers

- `Authorization` string, required

## Response `200`

Usage analytics for the selected window.

- Usage — Activity analytics for the selected window (`days`) plus fixed-window breakdown totals. All figures are derived from real message and call records.
  - `periodDays` integer — The selected window in days (7, 30, or 90).
  - `stats` UsageStats — Headline metrics for the selected window — each with a per-day spark series and percent change vs the previous equal window.
    - `messages` UsageStat
      - `value` integer — Total for the selected window.
      - `deltaPct` number, double, nullable — Percent change vs the previous equal window, or null when that window had no activity.
      - `spark` integer[] — Per-day values across the selected window, oldest first.
    - `calls` UsageStat
      - `value` integer — Total for the selected window.
      - `deltaPct` number, double, nullable — Percent change vs the previous equal window, or null when that window had no activity.
      - `spark` integer[] — Per-day values across the selected window, oldest first.
    - `minutes` UsageStat
      - `value` integer — Total for the selected window.
      - `deltaPct` number, double, nullable — Percent change vs the previous equal window, or null when that window had no activity.
      - `spark` integer[] — Per-day values across the selected window, oldest first.
  - `series` UsageSeriesItems[] — One entry per calendar day in the selected window (UTC), oldest first.
    - `date` string, date
    - `messages` integer
    - `calls` integer
  - `callDuration` UsageCallDuration — Voice-call talk-time stats for connected calls (duration > 0) in the window.
    - `sampleSize` integer — Number of connected calls in the window.
    - `medianSec` integer
    - `p95Sec` integer
    - `longestSec` integer
    - `histogram` UsageCallDurationHistogramItems[] — Duration distribution across fixed buckets.
      - `label` string
      - `count` integer
      - `pct` number, double — Fraction of the sample (0–1).
  - `topNumbers` UsageTopNumbersItems[] — Account numbers ranked by total activity (messages + calls) in the window, descending (up to 6).
    - `number` string
    - `nickname` string, nullable — User-set label for the number, or null. The dashboard falls back to the number's creation age when absent.
    - `createdAt` string, date-time
    - `count` integer
  - `breakdown` UsageBreakdown — Fixed-window totals (last 7 days, last 30 days, all time).
    - `messages` UsageBreakdownRow — Totals for a metric over fixed windows.
      - `d7` integer — Last 7 days.
      - `d30` integer — Last 30 days.
      - `all` integer — All time.
    - `calls` UsageBreakdownRow — Totals for a metric over fixed windows.
      - `d7` integer — Last 7 days.
      - `d30` integer — Last 30 days.
      - `all` integer — All time.
    - `minutes` UsageBreakdownRow — Totals for a metric over fixed windows.
      - `d7` integer — Last 7 days.
      - `d30` integer — Last 30 days.
      - `all` integer — All time.
  - `totals` UsageTotals — All-time totals.
    - `messages` integer
    - `calls` integer
    - `numbers` integer
  - `currentPeriod` CurrentPeriod — Usage for the current period — a monthly cycle anchored to the account's creation date (jumps of one month from `createdAt`; stands in until billing and pricing are defined). Independent of the `days` window. Split per number (plus an `all` aggregate) by direction and domestic/international.
    - `start` string, date-time — Period start (inclusive).
    - `end` string, date-time — Period end (exclusive); the period renews on this date.
    - `daysTotal` integer
    - `daysElapsed` integer
    - `daysLeft` integer
    - `all` PeriodBreakdown — Period usage split by direction (outbound/inbound) and geography (domestic/international).
      - `voice` PeriodBreakdownVoice
        - `outbound` PeriodVoiceGeo
          - `domestic` PeriodVoiceLeaf
            - `calls` integer
            - `minutes` integer
          - `intl` PeriodVoiceLeaf
            - `calls` integer
            - `minutes` integer
        - `inbound` PeriodVoiceGeo
          - `domestic` PeriodVoiceLeaf
            - `calls` integer
            - `minutes` integer
          - `intl` PeriodVoiceLeaf
            - `calls` integer
            - `minutes` integer
      - `messages` PeriodBreakdownMessages
        - `outbound` PeriodMessageGeo
          - `domestic` PeriodMessageLeaf
            - `count` integer
          - `intl` PeriodMessageLeaf
            - `count` integer
        - `inbound` PeriodMessageGeo
          - `domestic` PeriodMessageLeaf
            - `count` integer
          - `intl` PeriodMessageLeaf
            - `count` integer
    - `numbers` CurrentPeriodNumbersItems[] — Per-number breakdown, sorted by total period activity descending.
      - `id` string
      - `number` string
      - `nickname` string, nullable — User-set label for the number, or null. The dashboard falls back to the number's creation age when absent.
      - `createdAt` string, date-time
      - `breakdown` PeriodBreakdown — Period usage split by direction (outbound/inbound) and geography (domestic/international).
        - `voice` PeriodBreakdownVoice
          - `outbound` PeriodVoiceGeo
            - `domestic` PeriodVoiceLeaf
              - …
            - `intl` PeriodVoiceLeaf
              - …
          - `inbound` PeriodVoiceGeo
            - `domestic` PeriodVoiceLeaf
              - …
            - `intl` PeriodVoiceLeaf
              - …
        - `messages` PeriodBreakdownMessages
          - `outbound` PeriodMessageGeo
            - `domestic` PeriodMessageLeaf
              - …
            - `intl` PeriodMessageLeaf
              - …
          - `inbound` PeriodMessageGeo
            - `domestic` PeriodMessageLeaf
              - …
            - `intl` PeriodMessageLeaf
              - …

## Other responses

- `401` — Missing or invalid API key.

---

[API](https://skmtc.net/getdial/apis/rest-api.md) · [All operations](https://skmtc.net/getdial/apis/rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/getdial/rest-api/revisions/5f4eb30ac29a/schema)