---
title: "Get usage stats for a tenant"
method: GET
path: "/tenants/{tenantId}/usage"
tags: ["Usage"]
---

# Get usage stats for a tenant

`GET /tenants/{tenantId}/usage`

Returns email sending statistics for a specific tenant over a time period.

**Use cases:**
- Display usage dashboard to your customers
- Calculate per-tenant billing
- Monitor tenant health and delivery rates

**Period formats:**
- Shortcuts: `today`, `yesterday`, `this_week`, `last_week`, `this_month`, `last_month`, `last_7_days`, `last_30_days`, `last_90_days`
- Month: `2024-01` (full month)
- Date range: `2024-01-01..2024-01-31`
- Single day: `2024-01-15`

**Response includes:**
- `emails` - Counts for sent, delivered, soft_failed, hard_failed, bounced, held
- `rates` - Delivery rate and bounce rate as decimals (0.95 = 95%)

## Path parameters

- `tenantId` string, required

## Query parameters

- `period` string
- `timezone` string

## Response `200`

Tenant usage statistics

- TenantUsageResponse — Usage statistics for a single tenant
  - `success` true, required
  - `data` TenantUsageData, required — Tenant usage statistics
    - `tenant_id` string, required — Unique tenant identifier
    - `tenant_name` string, required — Tenant display name
    - `external_id` string, nullable — Your external ID for this tenant (from metadata)
    - `period` UsagePeriod, required — Time period for usage data
      - `start` string, date-time, required — Period start (inclusive)
      - `end` string, date-time, required — Period end (inclusive)
    - `emails` EmailCounts, required — Email delivery counts
      - `sent` integer, required — Total emails sent
      - `delivered` integer, required — Emails successfully delivered
      - `soft_failed` integer, required — Emails that soft-failed (temporary failures, may be retried)
      - `hard_failed` integer, required — Emails that hard-failed (permanent failures)
      - `bounced` integer, required — Emails that bounced
      - `held` integer, required — Emails currently held for review
    - `rates` EmailRates, required — Email delivery rates (as decimals, e.g., 0.95 = 95%)
      - `delivery_rate` number, float, required — Percentage of sent emails that were delivered (0-1)
      - `bounce_rate` number, float, required — Percentage of sent emails that bounced (0-1)
  - `meta` ApiMeta, required
    - `requestId` string, required — Unique request identifier for debugging and support

## Other responses

- `400` — Invalid request parameters
- `401` — Invalid or missing API key
- `404` — Tenant not found
- `429` — Rate limit exceeded
- `500` — Internal server error
- `503` — Usage statistics temporarily unavailable

---

[API](https://skmtc.net/arkhq-io/apis/ark-email-api.md) · [All operations](https://skmtc.net/arkhq-io/apis/ark-email-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/arkhq-io/ark-email-api/versions/98a90852ffca/schema)