Usage Summary
Detailed usage for the calling user — 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: active tunnels (tunnels.status = 'active'), total endpoints, plus the aggregated bandwidth and request counters from the metering pipeline.
Response (200 OK)
account_id int64
The active account whose usage this is (usage is an account property, shared across members).
plan string
Plan slug (
free, pro, …).limits object
Effective limits — same shape as /account/plan but as
max_endpoints / max_tunnels / max_connections / bandwidth_limit (MB) / request_limit. 0 means unlimited.current object
Current billing period:
endpoints (count), tunnels (active), 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. Resets when the subscription anniversary rolls.exceeded object
Boolean flags per resource:
endpoints, tunnels, bandwidth, requests. true means the user is at or beyond the limit. Useful for showing "upgrade now" CTAs without re-doing the math client-side.Errors
401 Unauthorized
Missing auth.
Notes
Bandwidth values are bytes here, not megabytes — divide by 1024² for MB. limits.bandwidth_limit is in MB to match the storage convention; do the conversion before comparing.
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
{
"account_id": 42,
"plan": "pro",
"limits": {
"max_endpoints": 20,
"max_tunnels": 10,
"max_connections": 5000,
"bandwidth_limit": 102400,
"request_limit": 50000
},
"current": {
"endpoints": 4,
"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
}
}