---
title: "Get plan and usage"
method: GET
path: "/usage"
tags: ["Account"]
---

# Get plan and usage

`GET /usage`

## Request

- Base URL: `https://api.mepmail.dev`
- URL: `https://api.mepmail.dev/usage`
- Auth: HTTP bearer

Returns the team's plan, limits and usage in the current period.

## Response `200`

Effective plan and usage limits. Annual Send contracts renew their 110K allowance monthly within the paid year; overage is disabled and its numeric rate is zero. MepMail extension; plan, limits and period are null on self-hosted and system teams.

- UsageResponse
  - `object` 'usage', required
  - `cloud` boolean, required: True on MepMail Cloud, where plan limits apply
  - `plan` 'free' | 'starter' | 'pro' | 'scale' | 'null', nullable, required: Effective plan; null self-hosted or on the instance's own (system) team
  - `limits` object, required
    - `emails_per_day` integer, nullable, required: Daily cap (UTC day) on Free and Starter; null on monthly plans and self-hosted
    - `emails_per_month` integer, nullable, required: Emails included per billing period on Pro and Scale; null on daily plans and self-hosted
    - `domains` integer, nullable, required: null = unlimited or self-hosted
    - `contacts` integer, nullable, required: Contacts the team may hold; null = unlimited or self-hosted
  - `today` object, required
    - `emails_sent` integer, required: Emails accepted so far this UTC day
    - `resets_at` string, required: Next UTC midnight, when the daily counter resets
  - `period` object, nullable, required: Billing-period usage on monthly plans; null on daily plans and self-hosted
    - `emails_sent` integer, required: Emails accepted so far this billing period
    - `included` integer, required: Emails the plan includes per period
    - `overage_enabled` boolean, required: Whether sends past `included` bill overage instead of being refused
    - `overage_usd_per_1k` number, required: Overage price per 1,000 emails, in USD
    - `starts_at` string, required: Billing period start
    - `ends_at` string, required: Billing period end, when the counter resets
  - `team` object, required
    - `id` string, uuid, required
    - `name` string, required
  - `app_url` string, nullable, required: Dashboard origin, for building links; null when unset

## Other responses

- `401`: Missing, malformed or invalid API key
- `403`: Restricted API key
- `409`: Contract terms or bindings unavailable. Counters remain under usage; period is null when no monthly allowance is verified. No estimated or null overage rate is returned.
- `429`: Rate limit exceeded: 600 requests per minute per API key and 3,000 per team; wait for Retry-After

---

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