Usage Account

Usage Summary

GET /v1/account/usage

Detailed usage for the active account — current-period totals (current billing cycle), lifetime totals, plan limits, and a per-resource exceeded map for the dashboard's "you're at 87% of your bandwidth quota" warnings. Also returns the resolved billing-period boundaries so clients can render "X days left in this cycle".

Counts are computed live from the database, and each one is the count its limit is enforced on: reserved endpoints (the max_endpoints count; ephemeral endpoints are reported apart, they have their own quota), online plus quota-paused tunnels (the max_tunnels count; an offline tunnel takes no slot), plus the aggregated bandwidth and request counters from the metering pipeline.

Response (200 OK)

account_uuid string (uuid)

The uuid of the active account whose usage this is (usage is an account property, shared across members).

plan string

Plan slug (free, team, enterprise, …).

limits object

The account's effective limits for endpoints, tunnels, connections, bandwidth and requests — the values /account/plan returns in plan_limits, under this endpoint's own names: max_endpoints, max_tunnels, max_connections, bandwidth_limit (= max_bandwidth, bytes) and request_limit (= max_requests). -1 means unlimited (0 means none). For every other quota read plan_limits on /account/plan.

current object

Current billing period: endpoints (reserved endpoints — the count max_endpoints caps, endpoints paused over the limit included), ephemeral_endpoints (live ephemeral endpoints — their own quota, never counted in endpoints), tunnels (online tunnels plus tunnels paused over the limit — the count max_tunnels caps; an offline tunnel isn't counted), bandwidth_used (bytes — sum of in+out), requests_used (count).

totals object

Lifetime totals (across all billing periods): bandwidth (bytes), requests.

period object

Current billing cycle bounds: start, end as RFC 3339 datetimes (null until the account has usage). Resets when the subscription anniversary rolls.

exceeded object

Boolean flags per resource: endpoints, tunnels, bandwidth, requests, computed from current against limits. true means the account is at or beyond the limit. Useful for showing "upgrade now" CTAs without re-doing the math client-side.

Deprecated: until the sunset this response also carries the legacy integer account_id. Don't use it; read account_uuid.

Errors

401 Unauthorized

Missing auth.

Notes

Bandwidth values are bytes here, not megabytes — divide by 1024² for MB. limits.bandwidth_limit is in bytes too, so it compares directly with current.bandwidth_used.

Request
curl "https://api.ngris.com/v1/account/usage" \
  -H "X-API-KEY: <your_api_key>"

Python
from ngris import Ngris

client = Ngris(api_key="<your_api_key>")
usage = client.users.get_usage()
print(f"Endpoints: {usage['current']['endpoints']}/{usage['limits']['max_endpoints']}")
print(f"Bandwidth used: {usage['current']['bandwidth_used'] / 1024**2:.1f} MB")

Response — 200 OK (abridged)
{
  "account_uuid": "019a68b9-1a79-7820-a884-41f554aba6bd",
  "plan": "team",
  "current": {
    "endpoints": 4,
    "ephemeral_endpoints": 1,
    "tunnels": 2,
    "bandwidth_used": 1296384000,
    "requests_used": 8742
  },
  "totals": {
    "bandwidth": 5123456789,
    "requests": 142567
  },
  "period": {
    "start": "2026-04-15T00:00:00Z",
    "end": "2026-05-15T00:00:00Z"
  },
  "exceeded": {
    "endpoints": false,
    "tunnels": false,
    "bandwidth": false,
    "requests": false
  }
}

Was this helpful?

PreviousEntitlements NextBilling

On this page

Usage Summary

Was this helpful?