---
title: "Get legacy usage or additive Usage V2 entitlements"
method: GET
path: "/v1/usage"
tags: ["Usage"]
---

# Get legacy usage or additive Usage V2 entitlements

`GET /v1/usage`

## Request

- Base URL: `https://api.thrd.email`
- URL: `https://api.thrd.email/v1/usage`
- Auth: HTTP bearer

Returns the legacy usage projection while the usage ledger is disabled. With the ledger enabled, returns schema_version=2.0 additively: commercial plan, authority tier, inbound unmetered billing mode, observational inbound counters with explicit availability, retention, outbound daily/monthly units, Gate and semantic usage. Unlimited incoming email means no monthly message-count quota; fair-use, anti-abuse, message-size and retention limits still apply.

## Response `200`

Legacy Usage V1 or additive Usage V2 snapshot

- union
  - UsageV1
    - `plan` 'sandbox' | 'limited' | 'verified', required
    - `tier` 'tier_1' | 'tier_2' | 'tier_3', required
    - `starter_active` boolean, required
    - `monthly` object, required
      - `limit` number, required
      - `used` number, required
      - `reserved` number
      - `remaining` number, required
      - `ratio` number, required
      - `state` 'ok' | 'near_limit' | 'limit_reached', required
      - `warning_threshold_ratio` number, required
      - `warning_threshold_units` number, required
      - `window_start` string, date-time, required
      - `window_end` string, date-time, required
      - `reset_at` string, date-time, required
    - `upgrade_offer` object, nullable, required
      - `kind` 'sandbox_starter' | 'tier_upgrade', required
      - `plan` 'sandbox' | 'limited' | 'verified', required
      - `price_eur_month` number, required
      - `monthly_limit` number, required
    - `upgrade_plan` 'sandbox' | 'limited' | 'verified', nullable, required
  - UsageV2
    - `plan` 'sandbox' | 'limited' | 'verified', required
    - `tier` 'tier_1' | 'tier_2' | 'tier_3', required
    - `starter_active` boolean, required
    - `monthly` object, required
      - `limit` number, required
      - `used` number, required
      - `reserved` number
      - `remaining` number, required
      - `ratio` number, required
      - `state` 'ok' | 'near_limit' | 'limit_reached', required
      - `warning_threshold_ratio` number, required
      - `warning_threshold_units` number, required
      - `window_start` string, date-time, required
      - `window_end` string, date-time, required
      - `reset_at` string, date-time, required
    - `upgrade_plan` 'sandbox' | 'limited' | 'verified', nullable, required
    - `schema_version` '2.0', required
    - `commercial_plan` 'free' | 'starter' | 'limited' | 'verified', required
    - `authority_tier` 'sandbox' | 'limited' | 'verified', required
    - `lifecycle` object, required
      - `state` 'active' | 'provisional' | 'expired', required
      - `claim_required` boolean, required
      - `provisional_until` string, date-time, nullable, required
    - `inbound` object, required
      - `billing_mode` 'unmetered', required
      - `monthly_message_limit` unknown, required
      - `observed` object, required
        - `messages_month` integer, required
        - `bytes_month` unknown, required
        - `rejected_month` unknown, required
        - `quarantined_month` integer, required
        - `availability` object, required
          - `messages_month` 'available', required
          - `bytes_month` 'unavailable', required
          - `rejected_month` 'unavailable', required
          - `quarantined_month` 'available', required
      - `message_size_limit_bytes` integer, required
      - `retention` object, required
        - `raw_hours` number, nullable, required
        - `attachments_hours` number, nullable, required
        - `body_days` number, nullable, required
        - `metadata_days` number, nullable, required
      - `fair_use_state` unknown, required
      - `fair_use_availability` 'unavailable', required
    - `outbound` object, required
      - `mode` 'reply_only' | 'controlled_new_send' | 'verified_send', required
      - `resource` 'safe_reply_units' | 'outbound_recipient_units', required
      - `monthly` object, required
        - `limit` number, nullable, required
        - `reserved` number, required
        - `used` number, required
        - `remaining` number, nullable, required
        - `state` 'available' | 'exhausted' | 'unmetered', required
        - `window_start` string, date-time, required
        - `window_end` string, date-time, required
        - `reset_at` string, date-time, required
      - `daily` object, nullable, required
        - `limit` number, nullable, required
        - `reserved` number, required
        - `used` number, required
        - `remaining` number, nullable, required
        - `state` 'available' | 'exhausted' | 'unmetered', required
        - `window_start` string, date-time, required
        - `window_end` string, date-time, required
        - `reset_at` string, date-time, required
    - `gate` object, required
      - `decisions` object, required
        - `limit` number, nullable, required
        - `reserved` number, required
        - `used` number, required
        - `remaining` number, nullable, required
        - `state` 'available' | 'exhausted' | 'unmetered', required
        - `window_start` string, date-time, required
        - `window_end` string, date-time, required
        - `reset_at` string, date-time, required
      - `enforced_actions` object, required
        - `limit` number, nullable, required
        - `reserved` number, required
        - `used` number, required
        - `remaining` number, nullable, required
        - `state` 'available' | 'exhausted' | 'unmetered', required
        - `window_start` string, date-time, required
        - `window_end` string, date-time, required
        - `reset_at` string, date-time, required
    - `semantic` object, required
      - `deep_analyses` object, required
        - `limit` number, nullable, required
        - `reserved` number, required
        - `used` number, required
        - `remaining` number, nullable, required
        - `state` 'available' | 'exhausted' | 'unmetered', required
        - `window_start` string, date-time, required
        - `window_end` string, date-time, required
        - `reset_at` string, date-time, required
    - `upgrade_offer` object, nullable, required
      - `plan` 'starter' | 'limited' | 'verified', required
      - `price_eur_month` number, required
      - `outbound_recipient_units` number, required

## Other responses

- `401`: Unauthorized

---

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