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

# Retrieve usage

`GET /usage`

## Request

- Base URL: `https://www.unitpost.com/api/v1`
- URL: `https://www.unitpost.com/api/v1/usage`
- Auth: HTTP bearer

Retrieve your workspace's current billing-period usage snapshot: the plan, the period window, and the email counter. On paid plans the response also carries the dollar sending `wallet`: the monthly allowance included with the plan, spend so far, any upgrade carryover, the non-expiring purchased-credit balance, and billable overage, all as integer USD cents. On the free plan `wallet` is null and the `emails` object carries the monthly quota and daily cap instead. `spend` itemizes the period from the wallet ledger (email, SMS, SMS carrier fees, refunds, and how it was paid), and `sms` breaks SMS down by destination country with segments, the price per segment, monthly number and campaign fees, one-time registration fees, and refunds. Amounts are read from the same ledger and meters that gate sending, so this matches the dashboard statement exactly. Requires the `emails:read` or `sms:read` capability.

## Response `200`

The current-period usage snapshot.

- Usage
  - `object` 'usage', required
  - `plan` string, required
  - `period_start` string, required
  - `period_end` string, required
  - `emails` object, required
    - `sent` integer, required
    - `included` integer, nullable, required
    - `daily_cap` integer, nullable, required
    - `sent_today` integer, required
  - `wallet` object, nullable, required
    - `allowance_cents` integer, nullable, required
    - `used_cents` integer, required
    - `carryover_cents` integer, required
    - `purchased_credit_cents` integer, required
    - `overage_cents` integer, required
    - `overage_cap_cents` integer, nullable, required
    - `email_rate_per_1k_cents` integer, nullable, required
  - `spend` object, required
    - `total_cents` integer, required
    - `email_cents` integer, required
    - `sms_cents` integer, required
    - `sms_carrier_fees_cents` integer, required
    - `other_cents` integer, required
    - `refunds_cents` integer, required
    - `included_cents` integer, required
    - `purchased_credit_cents` integer, required
    - `overage_cents` integer, required
    - `credits_added_cents` integer, required
  - `sms` object, required
    - `messages` integer, required
    - `segments` integer, required
    - `send_cents` integer, required
    - `monthly_fees_cents` integer, required
    - `one_time_fees_cents` integer, required
    - `refunds_cents` integer, required
    - `countries` object[], required
      - `country` string, required
      - `messages` integer, required
      - `segments` integer, required
      - `price_per_segment_cents` integer, nullable, required
      - `cost_cents` integer, required

## Other responses

- `401`: Missing or invalid API key.
- `403`: Insufficient scope.

---

[API](https://skmtc.dev/unitpost/apis/unitpost-api.md) · [All operations](https://skmtc.dev/unitpost/apis/unitpost-api/llms.txt) · [OpenAPI document](https://skmtc.dev/unitpost/apis/unitpost-api/revisions/86ff7c890967?raw)