​
Aggregate usage

curl https://api.atlasvpn.live/api/v1/proxy/usage \
     -H "Authorization: Bearer $SUPABASE_JWT"
Returns a snapshot across all your keys for the current calendar month: 
{
  "totalBandwidthBytes": 1234567890,
  "totalRequests": 4200,
  "activeKeys": 3,
  "tierBreakdown": {
    "developer": 2,
    "team": 1
  }
}
FieldMeaning
totalBandwidthBytesSum of bytesIn + bytesOut across all your keys this period
totalRequestsCONNECT count (not individual HTTP requests within a tunnel)
activeKeysKeys where active=true
tierBreakdown{tier: count} — how many keys you hold per tier
totalRequests counts CONNECTs. A single tunnel can multiplex many HTTP requests after the 200 Connection Established line — those downstream requests are free to you. What the gateway meters is tunnel count + bytes.

​
Refresh cadence

The gateway flushes in-memory byte counters to the DB every 60 seconds. So totalBandwidthBytes is accurate to within the last 60s of traffic. A nightly reconciliation cron recomputes totalBandwidthBytes from the raw proxy_usage_events rows and overwrites any drift.

​
Per-key event log (paginated)

Coming 2026-Q2 — GET /api/v1/proxy/keys/:keyId/events?page=1&limit=50 will return per-request rows: target host, method, status code, bytesSent, bytesReceived, durationMs, servedByNodeId. For now, the aggregate endpoint is the only programmatic surface. If you need per-request detail for billing reconciliation, email support@atlasvpn.live and we can export a CSV from our side.

​
Usage alerts

Configure notification thresholds in your /developer account settings:
DefaultBehaviour
80% of tier capEmail alert: “you’re 80% through this month’s bandwidth”
95% of tier capEmail alert: “you’re 95% through — upgrade or requests will 402 soon”
100% of tier capGateway returns 402 (unless overage opt-in is enabled)
Slack / Discord / PagerDuty webhook notifications are on the roadmap for Q3 2026.