---
title: "Get current usage"
method: GET
path: "/v1/billing/usage"
tags: ["Billing"]
---

# Get current usage

`GET /v1/billing/usage`

## Request

- Base URL: `https://api.mails.ai`
- URL: `https://api.mails.ai/v1/billing/usage`
- Auth: HTTP bearer

**Requires scope:** `read`. Returns metered usage for the current billing period plus the workspace's tier caps. A key tied to one agent cannot read it (403 `insufficient_scope`): usage and costs are counted for the whole workspace, and `GET /v1/metrics` counts that agent's mail.

## Response `200`

Current-period usage and caps.

- BillingUsage
  - `workspace_id` string, required: Your workspace id (`wsk_…`).
  - `tier` string, required: Your plan: `free`, `pro`, `scale` or `metered`, or an older plan, `outbound` or `outbound_pro`. While a payment is past due, `caps` are Free's whatever this says.
  - `tier_status` string: `active`, or `past_due` after a failed renewal payment: the workspace then has Free plan limits until the payment goes through. `canceled` and `paused` refuse every send, with 402 `subscription_canceled` and `payment_required`.
  - `period_start` string, date-time: Start of the usage period: the first day of this month, 00:00 UTC. The counts in `usage` start over each month.
  - `period_end` string, date-time: End of the usage period, exclusive: the first day of next month, 00:00 UTC.
  - `usage` object, required: This period's counts.
    - `sends` integer, required: Recipients sent to this period: each live message counts once per `to`, `cc` and `bcc` address, and test sends do not count. `caps.monthly_sends` limits it.
    - `parses` integer, required: Received emails processed this period, which `caps.monthly_parses` limits. Mail kept or dropped over a limit counts in `inbound_skipped` instead.
    - `inbound_skipped` integer: Received emails not processed this period: kept unclassified because the monthly allowance was used up or the subscription is inactive, or dropped unstored in a flood past `hourly_inbound` or `daily_inbound`.
    - `webhook_deliveries` integer, required: Webhook deliveries your endpoints accepted with a 2xx answer this period. Test deliveries are not counted.
    - `sends_cost_usd` number: Estimated cost of delivering this period's sends, at $0.0001 per recipient. It is not what your plan charges.
    - `parses_cost_usd` number: Estimated cost of classifying this period's received mail. Like `sends_cost_usd`, it is not what your plan charges.
  - `caps` object, required: The limits of the plan the workspace is held to now: its own, or Free's while a payment is past due.
    - `monthly_sends` integer, nullable, required: Recipients the workspace may send to in a month, each live message counted once per `to`, `cc` and `bcc` address; past it, a send gets 429 `monthly_limit_exceeded` (`free_tier_exceeded` on Free limits). Null when the plan has no monthly limit.
    - `monthly_parses` integer, nullable, required: Received emails processed in a month; past it, mail is still stored but not classified, and counts in `inbound_skipped`. Null when the plan has no monthly limit.
    - `agents` union, required: How many agents the plan allows, or the string `unlimited`. Past it, `POST /v1/agents` gets 402 `resource_cap_exceeded`.
      - integer
      - 'unlimited'
    - `hourly` integer: Recipients the workspace may send to in any rolling hour, counted like `monthly_sends`: once per `to`, `cc` and `bcc` address. Mail scheduled for later counts from when it was accepted; mail that was canceled or refused does not count. Past it, a send gets 429 `hourly_limit_exceeded`. Test sends do not count.
    - `daily` integer: Recipients the workspace may send to in any rolling 24 hours, counted as `hourly` is. Past it, a send gets 429 `daily_limit_exceeded`. Test sends do not count.
    - `hourly_inbound` integer: Received emails stored in any rolling hour. Past it, more mail is dropped without being stored, and counts in `inbound_skipped`.
    - `daily_inbound` integer: Received emails stored in any rolling 24 hours. Past it, more mail is dropped without being stored, and counts in `inbound_skipped`.

## Other responses

- `401`: Missing or invalid API key.
- `403`: The API key lacks the required scope (`insufficient_scope`), or the token belongs to an app connected by sign-in and this operation is closed to connected apps (`connected_app_not_allowed`).
- `404`: Resource not found in this workspace, or the agent a send names is archived (`agent_archived`).
- `500`: Internal server error.

---

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