Skip to main content
GET
/
usage
/
tenants
cURL
# Get all tenant usage for this month
curl "https://api.arkhq.io/v1/usage/tenants" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Sort by highest volume with pagination
curl "https://api.arkhq.io/v1/usage/tenants?sort=-sent&page=1&perPage=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Filter active tenants with activity
curl "https://api.arkhq.io/v1/usage/tenants?status=active&minSent=100" \
  -H "Authorization: Bearer YOUR_API_KEY"
{
  "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
      }
    },
    {
      "tenantId": "cm6def789ghi012",
      "tenantName": "Beta Inc",
      "externalId": null,
      "status": "active",
      "emails": {
        "sent": 5000,
        "delivered": 4850,
        "soft_failed": 50,
        "hard_failed": 30,
        "bounced": 50,
        "held": 20
      },
      "rates": {
        "delivery_rate": 0.97,
        "bounce_rate": 0.016
      }
    }
  ],
  "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_abc123xyz"
  }
}

Documentation Index

Fetch the complete documentation index at: https://arkhq.io/docs/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
Authorization
string
header
required

Use your API key from arkhq.io/org/credentials

Authorization: Bearer YOUR_API_KEY

Query Parameters

​
period
string
default:this_month

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

​
page
integer
default:1

Page number (1-indexed)

Required range: x >= 1
​
perPage
integer
default:50

Results per page (max 100)

Required range: 1 <= x <= 100
​
sort
enum<string>
default:-sent

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

Available options:
sent,
-sent,
delivered,
-delivered,
bounce_rate,
-bounce_rate,
delivery_rate,
-delivery_rate,
tenant_name,
-tenant_name
​
status
enum<string>

Filter by tenant status

Available options:
active,
suspended,
archived
​
minSent
integer

Only include tenants with at least this many emails sent

Required range: x >= 0
​
timezone
string
default:UTC

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

Response

Paginated tenant usage statistics

Paginated tenant usage list (Stainless SDK compatible)

​
data
object[]
required

List of tenant usage records

​
page
integer
required

Current page number (1-indexed)

Example:

1

​
perPage
integer
required

Items per page

Example:

50

​
total
integer
required

Total number of tenants

Example:

150

​
totalPages
integer
required

Total number of pages

Example:

3

​
period
object
required

Time period for usage data

​
summary
object
required
​
meta
object
required