Usage & Analytics

Monitor your notification platform usage in real time — track email, push, SMS, and auth volumes, monitor MAU (Monthly Active Users), set up usage alerts, and export data for reporting.

Overview

The Usage API gives you visibility into:

Metric	Description
Email Volume	Emails sent in the current billing period
Push Volume	Push notifications sent
SMS Volume	Text messages sent
Auth Events	Authentication events (logins, signups, MFA)
MAU	Monthly Active Users across your applications
Overage	Usage beyond your plan's included limits

Current Period Usage

Get Usage Summary

curl https://api.zyphr.dev/v1/usage \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Returns your current billing period usage alongside your plan limits:

{
  "data": {
    "plan": "pro",
    "period": {
      "start": "2026-02-01T00:00:00Z",
      "end": "2026-02-28T23:59:59Z"
    },
    "usage": {
      "emails": { "used": 45000, "limit": 100000, "percentage": 45 },
      "push": { "used": 12000, "limit": 50000, "percentage": 24 },
      "sms": { "used": 800, "limit": 5000, "percentage": 16 },
      "auth": { "used": 3200, "limit": 10000, "percentage": 32 },
      "mau": { "used": 1500, "limit": 5000, "percentage": 30 }
    }
  }
}

Get Raw Current Usage

For a simplified view without plan limit context:

curl https://api.zyphr.dev/v1/usage/current \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Daily Breakdown

Get daily usage data for granular analysis:

curl "https://api.zyphr.dev/v1/usage/daily?start_date=2026-02-01&end_date=2026-02-28" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Query Parameters

Parameter	Type	Default	Description
`start_date`	string	30 days ago	Start date (YYYY-MM-DD)
`end_date`	string	Today	End date (YYYY-MM-DD)

Response

{
  "data": {
    "daily": [
      {
        "date": "2026-02-01",
        "emails": 1500,
        "push": 420,
        "sms": 30,
        "auth": 110
      },
      {
        "date": "2026-02-02",
        "emails": 1620,
        "push": 380,
        "sms": 25,
        "auth": 95
      }
    ]
  }
}

Usage History

View historical usage across past billing periods:

curl "https://api.zyphr.dev/v1/usage/history?months=6" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Parameter	Type	Default	Max	Description
`months`	number	6	12	Number of past billing periods

MAU Tracking

Get Monthly Active User breakdown by application:

curl https://api.zyphr.dev/v1/usage/mau \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response

{
  "data": {
    "total_mau": 1500,
    "applications": [
      { "app_id": "app_main", "name": "Main App", "mau": 1200 },
      { "app_id": "app_mobile", "name": "Mobile App", "mau": 800 }
    ]
  }
}

note

MAU is calculated as unique users who performed at least one action (login, notification received, etc.) during the billing period. Users active across multiple apps are counted once toward total MAU.

Usage Alerts

Get alerts when you're approaching or exceeding plan limits:

curl https://api.zyphr.dev/v1/usage/alerts \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response

{
  "data": {
    "alerts": [
      {
        "metric": "emails",
        "level": "warning",
        "threshold": 80,
        "current_percentage": 85,
        "message": "Email usage at 85% of plan limit"
      }
    ]
  }
}

Alert levels:

info (50%) - Halfway through included volume
warning (80%) - Approaching limit
critical (95%) - Near limit, overage charges imminent
overage (100%+) - Overage charges active

Overage Tracking

Current Overage

Check if you're incurring overage charges this period:

curl https://api.zyphr.dev/v1/usage/overage \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Overage Forecast

Project your end-of-period overage based on current usage pace:

curl https://api.zyphr.dev/v1/usage/overage/forecast \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response

{
  "data": {
    "forecast": {
      "emails": { "projected": 120000, "limit": 100000, "overage": 20000, "estimated_cost": "$20.00" },
      "push": { "projected": 45000, "limit": 50000, "overage": 0, "estimated_cost": "$0.00" }
    },
    "days_remaining": 12,
    "based_on_days": 16
  }
}

Overage History

View past overage records:

curl "https://api.zyphr.dev/v1/usage/overage/history?limit=12" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Parameter	Type	Default	Max	Description
`limit`	number	12	24	Number of past periods

Cross-Account Usage (Abuse Prevention)

If you own multiple accounts, Zyphr tracks your aggregate usage across all of them. Free plan accounts are subject to cross-account enforcement — your combined usage cannot exceed the free-tier limits.

Get User Aggregate Usage

curl https://api.zyphr.dev/v1/usage/user-aggregate \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response

{
  "data": {
    "account_count": 2,
    "accounts": [
      {
        "account_id": "acc_123",
        "account_name": "My App",
        "plan": "free",
        "emails_sent": 600,
        "push_sent": 200,
        "sms_sent": 0,
        "in_app_sent": 100,
        "monthly_active_users": 50
      },
      {
        "account_id": "acc_456",
        "account_name": "Side Project",
        "plan": "free",
        "emails_sent": 400,
        "push_sent": 100,
        "sms_sent": 0,
        "in_app_sent": 50,
        "monthly_active_users": 30
      }
    ],
    "totals": {
      "emails_sent": 1000,
      "push_sent": 300,
      "sms_sent": 0,
      "in_app_sent": 150,
      "monthly_active_users": 80
    },
    "free_tier_limits": {
      "emails_per_month": 1000,
      "push_per_month": 1000,
      "sms_per_month": 5000,
      "in_app_per_month": 5000,
      "mau_limit": 1000
    }
  }
}

warning

When your aggregate usage across all free accounts reaches the free-tier limit for any metric, sending will be blocked on all your free accounts for that channel. Upgrade any account to a paid plan to lift the restriction.

Usage Reconciliation

Manually trigger a reconciliation of usage counters against actual message records:

curl -X POST https://api.zyphr.dev/v1/usage/reconcile \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

This is useful if you suspect usage counters are out of sync. The reconciliation counts actual messages from source tables and corrects the usage record using a GREATEST strategy (never decreases counters).

CSV Exports

Export usage data as CSV for reporting and analysis.

Export Current Summary

curl https://api.zyphr.dev/v1/usage/export/summary \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -o usage-summary.csv

Export Usage History

curl "https://api.zyphr.dev/v1/usage/export/history?months=12" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -o usage-history.csv

Export Daily Breakdown

curl "https://api.zyphr.dev/v1/usage/export/daily?start_date=2026-02-01&end_date=2026-02-28" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -o usage-daily.csv

note

Daily exports are limited to a maximum of 90 days per request.

Export MAU by Application

curl https://api.zyphr.dev/v1/usage/export/mau \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -o mau-breakdown.csv

Export Comprehensive Report

Download a complete analytics report covering all metrics:

curl https://api.zyphr.dev/v1/usage/export/all \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -o analytics-report.csv

Dashboard

The Usage section in the Dashboard provides:

Usage overview - Visual progress bars for each metric against plan limits
Daily charts - Line charts showing daily volume trends
Alert badges - Warning indicators when approaching limits
MAU breakdown - Per-application MAU visualization
Export buttons - One-click CSV downloads

Plan Limits Reference

Metric	Free	Starter	Pro	Scale	Enterprise
Emails/mo	1,000	25,000	100,000	500,000	Custom
Push/mo	1,000	25,000	100,000	500,000	Custom
SMS/mo	100	1,000	5,000	25,000	Custom
Auth events/mo	500	5,000	25,000	100,000	Custom
MAU	500	2,500	10,000	50,000	Custom

See Billing & Plans for full plan details and overage pricing.

API Reference

Method	Endpoint	Description
`GET`	`/v1/usage`	Current period usage with limits
`GET`	`/v1/usage/current`	Raw current period usage
`GET`	`/v1/usage/history`	Past billing period usage
`GET`	`/v1/usage/daily`	Daily usage breakdown
`GET`	`/v1/usage/mau`	MAU by application
`GET`	`/v1/usage/alerts`	Current period alerts
`GET`	`/v1/usage/overage`	Current overage
`GET`	`/v1/usage/overage/forecast`	Projected overage
`GET`	`/v1/usage/overage/history`	Historical overage records
`GET`	`/v1/usage/export/summary`	Export current summary (CSV)
`GET`	`/v1/usage/export/history`	Export usage history (CSV)
`GET`	`/v1/usage/export/daily`	Export daily breakdown (CSV)
`GET`	`/v1/usage/export/mau`	Export MAU data (CSV)
`GET`	`/v1/usage/export/all`	Export comprehensive report (CSV)
`GET`	`/v1/usage/user-aggregate`	Cross-account aggregate usage
`POST`	`/v1/usage/reconcile`	Manual usage reconciliation
`GET`	`/v1/usage/waas`	WaaS usage summary

Next Steps

Billing & Plans - Manage your subscription and payments
Rate Limiting - Understand API rate limits
Account Settings - Configure your account

Overview​

Current Period Usage​

Get Usage Summary​

Get Raw Current Usage​

Daily Breakdown​

Query Parameters​

Response​

Usage History​

MAU Tracking​

Response​

Usage Alerts​

Response​

Overage Tracking​

Current Overage​

Overage Forecast​

Response​

Overage History​

Cross-Account Usage (Abuse Prevention)​

Get User Aggregate Usage​

Response​

Usage Reconciliation​

CSV Exports​

Export Current Summary​

Export Usage History​

Export Daily Breakdown​

Export MAU by Application​

Export Comprehensive Report​

Dashboard​

Plan Limits Reference​

API Reference​

Next Steps​

Overview

Current Period Usage

Get Usage Summary

Get Raw Current Usage

Daily Breakdown

Query Parameters

Response

Usage History

MAU Tracking

Response

Usage Alerts

Response

Overage Tracking

Current Overage

Overage Forecast

Response

Overage History

Cross-Account Usage (Abuse Prevention)

Get User Aggregate Usage

Response

Usage Reconciliation

CSV Exports

Export Current Summary

Export Usage History

Export Daily Breakdown

Export MAU by Application

Export Comprehensive Report

Dashboard

Plan Limits Reference

API Reference

Next Steps