Sign in
Usage

Export usage data for billing

Export usage data for all tenants in a format suitable for billing systems.

Use cases:

  • Import into billing systems (Stripe, Chargebee, etc.)
  • Generate invoices
  • Archive usage data

Export formats:

  • csv - Comma-separated values (default)
  • jsonl - JSON Lines (one JSON object per line)
  • json - JSON array

Response headers:

  • X-Total-Tenants - Total number of tenants in export
  • X-Total-Sent - Total emails sent across all tenants
  • Content-Disposition - Suggested filename for download

This endpoint returns up to 10,000 tenants per request. For organizations with more tenants, use the /usage/by-tenant endpoint with pagination.

get/usage/export

Query parameters

periodstring

Time period for export. Defaults to current month.

format'csv' | 'jsonl' | 'json'

Export format

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

Filter by tenant status

min_sentinteger

Only include tenants with at least this many emails sent

timezonestring

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

Response

Usage export data

tenant_idstring required

Unique tenant identifier

tenant_namestring required

Tenant display name

external_idstring nullable

Your external ID for this tenant

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

Current tenant status

sentinteger required

Total emails sent

deliveredinteger required

Emails successfully delivered

soft_failedinteger required

Emails that soft-failed

hard_failedinteger required

Emails that hard-failed

bouncedinteger required

Emails that bounced

heldinteger required

Emails currently held

delivery_ratenumber float required

Delivery rate (0-1)

bounce_ratenumber float required

Bounce rate (0-1)

Example response

[
  {
    "tenant_id": "cm6abc123def456",
    "tenant_name": "Acme Corp",
    "external_id": "acme_123",
    "status": "active",
    "sent": 10000,
    "delivered": 9700,
    "soft_failed": 100,
    "hard_failed": 50,
    "bounced": 100,
    "held": 50,
    "delivery_rate": 0.97,
    "bounce_rate": 0.015
  }
]

Changes