Usage

Get org-wide usage summary

Changed on Feb 8, 2026

Returns aggregated email sending statistics for your entire organization. For per-tenant breakdown, use GET /usage/tenants.

Use cases:

Platform dashboards showing org-wide metrics
Quick health check on overall sending
Monitoring total volume and delivery rates

Response includes:

emails - Aggregated email counts across all tenants
rates - Overall delivery and bounce rates
tenants - Tenant count summary (total, active, with activity)

Related endpoints:

GET /usage/tenants - Paginated usage per tenant
GET /usage/export - Export usage data for billing
GET /tenants/{tenantId}/usage - Single tenant usage details
GET /limits - Rate limits and send limits

get/usage

Request

Base URL
https://api.arkhq.io/v1
Auth
HTTP bearer
TypeScript
https://skmtc.dev/arkhq-io/apis/ark-email-api/docs/usage/get.ts
A function with typed inputs. Its response is checked against the schema.

Query parameters

periodstring

Time period for usage data.

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

timezonestring

Timezone for period calculations (IANA format)

Response

Org-wide usage summary

successtrue required

Example response

{
  "data": {
    "period": {
      "start": "2024-01-01T00:00:00.000Z",
      "end": "2024-01-31T23:59:59.999Z"
    },
    "emails": {
      "sent": 10000,
      "delivered": 9700,
      "soft_failed": 100,
      "hard_failed": 50,
      "bounced": 100,
      "held": 50
    },
    "rates": {
      "delivery_rate": 0.97,
      "bounce_rate": 0.015
    },
    "tenants": {
      "total": 25,
      "active": 20,
      "withActivity": 18
    }
  },
  "meta": {
    "requestId": "req_V1StGXR8_Z5jdHi6"
  }
}

Changes

Feb 8, 202637bce0c9a4d7 Revision changes
- breaking
  removed the required property / from the response with the status
- breaking
  removed the required property / from the response with the status
- breaking
  removed the required property / from the response with the status
- warning
  added the new infrastructure_error enum value to the / response property for the response status
- warning
  added the new infrastructure_error enum value to the / response property for the response status
- warning
  added the new infrastructure_error enum value to the / response property for the response status
- info
  api operation id usage_retrieve_limits removed and replaced with usage_retrieve
- info
  endpoint reactivated
- info
  added the new optional query request parameter period
- info
  added the new optional query request parameter timezone
- info
  added the non-success response with the status
- info
  removed the postal_error enum value from the / response property for the response status
- info
  removed the postal_error enum value from the / response property for the response status
- info
  removed the postal_error enum value from the / response property for the response status
- info
  added the required property / to the response with the status
- info
  added the required property / to the response with the status
- info
  added the required property / to the response with the status
- info
  added the required property / to the response with the status
Feb 8, 20264f8eeb0b9933 Revision changes
- warning
  added the new already_exists enum value to the / response property for the response status
- warning
  added the new already_exists enum value to the / response property for the response status
- warning
  added the new already_exists enum value to the / response property for the response status
- warning
  added the new attachment_too_large enum value to the / response property for the response status
- warning
  added the new attachment_too_large enum value to the / response property for the response status
- warning
  added the new attachment_too_large enum value to the / response property for the response status
- warning
  added the new authentication_required enum value to the / response property for the response status
- warning
  added the new authentication_required enum value to the / response property for the response status
- warning
  added the new authentication_required enum value to the / response property for the response status
- warning
  added the new billing_error enum value to the / response property for the response status
- warning
  added the new billing_error enum value to the / response property for the response status
- warning
  added the new billing_error enum value to the / response property for the response status
- warning
  added the new billing_not_configured enum value to the / response property for the response status
- warning
  added the new billing_not_configured enum value to the / response property for the response status
- warning
  added the new billing_not_configured enum value to the / response property for the response status
- warning
  added the new credential_not_found enum value to the / response property for the response status
- warning
  added the new credential_not_found enum value to the / response property for the response status
- warning
  added the new credential_not_found enum value to the / response property for the response status
- warning
  added the new credential_on_hold enum value to the / response property for the response status
- warning
  added the new credential_on_hold enum value to the / response property for the response status
- warning
  added the new credential_on_hold enum value to the / response property for the response status
- warning
  added the new credential_revoked enum value to the / response property for the response status
- warning
  added the new credential_revoked enum value to the / response property for the response status
- warning
  added the new credential_revoked enum value to the / response property for the response status
- warning
  added the new delivery_not_found enum value to the / response property for the response status
- warning
  added the new delivery_not_found enum value to the / response property for the response status
- warning
  added the new delivery_not_found enum value to the / response property for the response status
- warning
  added the new domain_already_exists enum value to the / response property for the response status
- warning
  added the new domain_already_exists enum value to the / response property for the response status
- warning
  added the new domain_already_exists enum value to the / response property for the response status
- warning
  added the new domain_not_found enum value to the / response property for the response status
- warning
  added the new domain_not_found enum value to the / response property for the response status
- warning
  added the new domain_not_found enum value to the / response property for the response status
- warning
  added the new domain_not_verified enum value to the / response property for the response status
- warning
  added the new domain_not_verified enum value to the / response property for the response status
- warning
  added the new domain_not_verified enum value to the / response property for the response status
- warning
  added the new email_not_found enum value to the / response property for the response status
- warning
  added the new email_not_found enum value to the / response property for the response status
- warning
  added the new email_not_found enum value to the / response property for the response status
- warning
  added the new external_id_already_exists enum value to the / response property for the response status
- warning
  added the new external_id_already_exists enum value to the / response property for the response status
- warning
  added the new external_id_already_exists enum value to the / response property for the response status
- warning
  added the new forbidden enum value to the / response property for the response status
- warning
  added the new forbidden enum value to the / response property for the response status
- warning
  added the new forbidden enum value to the / response property for the response status
- warning
  added the new idempotency_conflict enum value to the / response property for the response status
- warning
  added the new idempotency_conflict enum value to the / response property for the response status
- warning
  added the new idempotency_conflict enum value to the / response property for the response status
- warning
  added the new insufficient_balance enum value to the / response property for the response status
- warning
  added the new insufficient_balance enum value to the / response property for the response status
- warning
  added the new insufficient_balance enum value to the / response property for the response status
- warning
  added the new internal_error enum value to the / response property for the response status
- warning
  added the new internal_error enum value to the / response property for the response status
- warning
  added the new internal_error enum value to the / response property for the response status
- warning
  added the new invalid_api_key enum value to the / response property for the response status
- warning
  added the new invalid_api_key enum value to the / response property for the response status
- warning
  added the new invalid_api_key enum value to the / response property for the response status
- warning
  added the new invalid_email_address enum value to the / response property for the response status
- warning
  added the new invalid_email_address enum value to the / response property for the response status
- warning
  added the new invalid_email_address enum value to the / response property for the response status
- warning
  added the new invalid_raw_message enum value to the / response property for the response status
- warning
  added the new invalid_raw_message enum value to the / response property for the response status
- warning
  added the new invalid_raw_message enum value to the / response property for the response status
- warning
  added the new invalid_request enum value to the / response property for the response status
- warning
  added the new invalid_request enum value to the / response property for the response status
- warning
  added the new invalid_request enum value to the / response property for the response status
- warning
  added the new ip_not_allowed enum value to the / response property for the response status
- warning
  added the new ip_not_allowed enum value to the / response property for the response status
- warning
  added the new ip_not_allowed enum value to the / response property for the response status
- warning
  added the new message_too_large enum value to the / response property for the response status
- warning
  added the new message_too_large enum value to the / response property for the response status
- warning
  added the new message_too_large enum value to the / response property for the response status
- warning
  added the new metadata_key_invalid enum value to the / response property for the response status
- warning
  added the new metadata_key_invalid enum value to the / response property for the response status
- warning
  added the new metadata_key_invalid enum value to the / response property for the response status
- warning
  added the new metadata_too_large enum value to the / response property for the response status
- warning
  added the new metadata_too_large enum value to the / response property for the response status
- warning
  added the new metadata_too_large enum value to the / response property for the response status
- warning
  added the new metadata_value_invalid enum value to the / response property for the response status
- warning
  added the new metadata_value_invalid enum value to the / response property for the response status
- warning
  added the new metadata_value_invalid enum value to the / response property for the response status
- warning
  added the new missing_field enum value to the / response property for the response status
- warning
  added the new missing_field enum value to the / response property for the response status
- warning
  added the new missing_field enum value to the / response property for the response status
- warning
  added the new missing_scope enum value to the / response property for the response status
- warning
  added the new missing_scope enum value to the / response property for the response status
- warning
  added the new missing_scope enum value to the / response property for the response status
- warning
  added the new not_found enum value to the / response property for the response status
- warning
  added the new not_found enum value to the / response property for the response status
- warning
  added the new not_found enum value to the / response property for the response status
- warning
  added the new payload_too_large enum value to the / response property for the response status
- warning
  added the new payload_too_large enum value to the / response property for the response status
- warning
  added the new payload_too_large enum value to the / response property for the response status
- warning
  added the new payment_required enum value to the / response property for the response status
- warning
  added the new payment_required enum value to the / response property for the response status
- warning
  added the new payment_required enum value to the / response property for the response status
- warning
  added the new postal_error enum value to the / response property for the response status
- warning
  added the new postal_error enum value to the / response property for the response status
- warning
  added the new postal_error enum value to the / response property for the response status
- warning
  added the new rate_limit_exceeded enum value to the / response property for the response status
- warning
  added the new rate_limit_exceeded enum value to the / response property for the response status
- warning
  added the new rate_limit_exceeded enum value to the / response property for the response status
- warning
  added the new send_limit_exceeded enum value to the / response property for the response status
- warning
  added the new send_limit_exceeded enum value to the / response property for the response status
- warning
  added the new send_limit_exceeded enum value to the / response property for the response status
- warning
  added the new server_suspended enum value to the / response property for the response status
- warning
  added the new server_suspended enum value to the / response property for the response status
- warning
  added the new server_suspended enum value to the / response property for the response status
- warning
  added the new service_unavailable enum value to the / response property for the response status
- warning
  added the new service_unavailable enum value to the / response property for the response status
- warning
  added the new service_unavailable enum value to the / response property for the response status
- warning
  added the new suppressed_recipient enum value to the / response property for the response status
- warning
  added the new suppressed_recipient enum value to the / response property for the response status
- warning
  added the new suppressed_recipient enum value to the / response property for the response status
- warning
  added the new suppression_not_found enum value to the / response property for the response status
- warning
  added the new suppression_not_found enum value to the / response property for the response status
- warning
  added the new suppression_not_found enum value to the / response property for the response status
- warning
  added the new tenant_not_found enum value to the / response property for the response status
- warning
  added the new tenant_not_found enum value to the / response property for the response status
- warning
  added the new tenant_not_found enum value to the / response property for the response status
- warning
  added the new too_many_attachments enum value to the / response property for the response status
- warning
  added the new too_many_attachments enum value to the / response property for the response status
- warning
  added the new too_many_attachments enum value to the / response property for the response status
- warning
  added the new too_many_recipients enum value to the / response property for the response status
- warning
  added the new too_many_recipients enum value to the / response property for the response status
- warning
  added the new too_many_recipients enum value to the / response property for the response status
- warning
  added the new unauthenticated_from_address enum value to the / response property for the response status
- warning
  added the new unauthenticated_from_address enum value to the / response property for the response status
- warning
  added the new unauthenticated_from_address enum value to the / response property for the response status
- warning
  added the new unprocessable_entity enum value to the / response property for the response status
- warning
  added the new unprocessable_entity enum value to the / response property for the response status
- warning
  added the new unprocessable_entity enum value to the / response property for the response status
- warning
  added the new validation_error enum value to the / response property for the response status
- warning
  added the new validation_error enum value to the / response property for the response status
- warning
  added the new validation_error enum value to the / response property for the response status
- warning
  added the new webhook_not_found enum value to the / response property for the response status
- warning
  added the new webhook_not_found enum value to the / response property for the response status
- warning
  added the new webhook_not_found enum value to the / response property for the response status

Operation history (4 revisions)