---
title: "List usage for all tenants"
method: GET
path: "/usage/tenants"
tags: ["Usage"]
---

# List usage for all tenants

`GET /usage/tenants`

Returns email usage statistics for all tenants in your organization.
Results are paginated with page-based navigation.

**Jobs to be done:**
- Generate monthly billing invoices per tenant
- Build admin dashboards showing all customer usage
- Identify high-volume or problematic tenants
- Track usage against plan limits

**Sorting options:**
- `sent`, `-sent` - Sort by emails sent (ascending/descending)
- `delivered`, `-delivered` - Sort by emails delivered
- `bounce_rate`, `-bounce_rate` - Sort by bounce rate
- `tenant_name`, `-tenant_name` - Sort alphabetically by tenant name

**Filtering:**
- `status` - Filter by tenant status (active, suspended, archived)
- `minSent` - Only include tenants with at least N emails sent

**Auto-pagination:** SDKs support iterating over all pages automatically.

## Query parameters

- `period` string
- `page` integer
- `perPage` integer
- `sort` 'sent' | '-sent' | 'delivered' | '-delivered' | 'bounce_rate' | '-bounce_rate' | 'delivery_rate' | '-delivery_rate' | 'tenant_name' | '-tenant_name'
- `status` 'active' | 'suspended' | 'archived'
- `minSent` integer
- `timezone` string

## Response `200`

Paginated tenant usage statistics

- ListTenantUsageResponse — Paginated tenant usage list (Stainless SDK compatible)
  - `data` TenantUsageItem[], required — List of tenant usage records
    - `tenantId` string, required — Unique tenant identifier
    - `tenantName` string, required — Tenant display name
    - `externalId` string, nullable — Your external ID for this tenant
    - `status` 'active' | 'suspended' | 'archived', required — Current tenant status
    - `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)
  - `page` integer, required — Current page number (1-indexed)
  - `perPage` integer, required — Items per page
  - `total` integer, required — Total number of tenants
  - `totalPages` integer, required — Total number of pages
  - `period` UsagePeriod, required — Time period for usage data
    - `start` string, date-time, required — Period start (inclusive)
    - `end` string, date-time, required — Period end (inclusive)
  - `summary` object, required
    - `totalTenants` integer, required — Total tenants in query
    - `totalSent` integer, required — Total emails sent
    - `totalDelivered` integer, required — Total emails delivered
  - `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
- `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)