ARarkhq-io
Usage

List usage for all tenants

Changed on

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.

get/usage/tenants

Request

Query parameters

periodstring

Time period for usage data. Defaults to current month.

Shortcuts: today, yesterday, this_week, last_week, this_month, last_month, last_7_days, last_30_days, last_90_days

Month format: 2024-01 (YYYY-MM)

Custom range: 2024-01-01..2024-01-15

pageinteger

Page number (1-indexed)

perPageinteger

Results per page (max 100)

sort'sent' | '-sent' | 'delivered' | '-delivered' | 'bounce_rate' | '-bounce_rate' | 'delivery_rate' | '-delivery_rate' | 'tenant_name' | '-tenant_name'

Sort order for results. Prefix with - for descending order.

status'active' | 'suspended' | 'archived'

Filter by tenant status

minSentinteger

Only include tenants with at least this many emails sent

timezonestring

Timezone for period calculations (IANA format). Defaults to UTC.

Response

Paginated tenant usage statistics

pageinteger required

Current page number (1-indexed)

perPageinteger required

Items per page

totalinteger required

Total number of tenants

totalPagesinteger required

Total number of pages

Example response

{
  "data": [
    {
      "tenantId": "cm6abc123def456",
      "tenantName": "Acme Corp",
      "externalId": "acme_123",
      "status": "active",
      "emails": {
        "sent": 10000,
        "delivered": 9700,
        "soft_failed": 100,
        "hard_failed": 50,
        "bounced": 100,
        "held": 50
      },
      "rates": {
        "delivery_rate": 0.97,
        "bounce_rate": 0.015
      }
    }
  ],
  "page": 1,
  "perPage": 50,
  "total": 150,
  "totalPages": 3,
  "period": {
    "start": "2024-01-01T00:00:00.000Z",
    "end": "2024-01-31T23:59:59.999Z"
  },
  "summary": {
    "totalTenants": 150,
    "totalSent": 500000,
    "totalDelivered": 485000
  },
  "meta": {
    "requestId": "req_V1StGXR8_Z5jdHi6"
  }
}

Changes