---
title: "Retrieve current usage and limits"
method: GET
path: "/api/v1/usage"
tags: ["Usage"]
---

# Retrieve current usage and limits

`GET /api/v1/usage`

## Request

- Base URL: `https://api.sendly.now`
- URL: `https://api.sendly.now/api/v1/usage`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `better-auth.session_token`
  - OAuth 2 (authorization code, authorization URL `https://app.sendly.now/api/auth/oauth2/authorize`, token URL `https://app.sendly.now/api/auth/oauth2/token`, scopes: `usage:read`)

Email usage against the limits that are actually enforced: the current month's counts per source category, the monthly cap applied to their total, and today's sends against the trust-tier daily ceiling.

Every figure is read from an enforcement path, so what this reports and what refuses a send cannot disagree. Correspondingly, nothing else is published — there is no billing period, invoice total or non-email meter here, because the platform meters none of those.

Two caveats worth reading before you alert on these numbers:

- The windows differ. The monthly counters roll over on the SERVER's calendar month; the daily counter buckets on the UTC date. The two therefore reset at different instants.
- `monthly.limit` is null once a subscription makes sending metered rather than capped, and also when an operator has set per-category limits — in that case the caps live in `monthly.categories[*].limit`.

Requires the `usage:read` scope — View your usage totals and billing limits.

## Response `200`

Current usage

- UsageV1: Current email usage against the limits that are actually enforced.
  - `daily` object, required
    - `emails_sent` integer, nullable, required: Today's sends. Null when the counter could not be read.
    - `limit` integer, required
    - `trust_tier` 'NEW' | 'ESTABLISHED' | 'TRUSTED', required
  - `monthly` object, required
    - `categories` object, required
      - `campaign` object, required
        - `emails_sent` integer, required
        - `limit` integer, nullable, required
      - `inbound` object, required
        - `emails_sent` integer, required
        - `limit` integer, nullable, required
      - `transactional` object, required
        - `emails_sent` integer, required
        - `limit` integer, nullable, required
      - `workflow` object, required
        - `emails_sent` integer, required
        - `limit` integer, nullable, required
    - `emails_sent` integer, required
    - `limit` integer, nullable, required: Monthly cap on the total. Null when per-category limits govern instead.
  - `plan` 'free' | 'pro' | 'custom', required: `custom` when an operator set per-category limits, `pro` on an active subscription or store entitlement, else `free`.

## Other responses

- `401`: `invalid_api_key` or `invalid_session` — missing or invalid credentials.
- `403`: `scope_missing`, `project_access_denied`, or `project_disabled`.
- `422`: `validation_error` — query, path, or body parameters did not match the schema.
- `429`: `rate_limited` — see `Retry-After` and the `RateLimit` headers.
- `500`: `internal_error`.

---

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