Skip to main content
GET /v1/usage
Authorization: Bearer $TB_KEY
Returns the account’s tier, the daily-window quota counters, the per-tier caps, and the window reset time. Cheap to call; safe to poll from a CI job every few minutes.

​
Example

curl https://api.tunnelbyte.dev/v1/usage \
  -H "Authorization: Bearer $TB_KEY"
Response (anonymous tier)
{
  "tier": "anonymous",
  "bytes_used": 199768576,
  "bytes_limit": 1073741824,
  "session_seconds": 840,
  "session_seconds_limit": 1800,
  "max_session_seconds": 0,
  "bytes_window_resets_at": "2026-06-08T14:32:00Z",
  "seconds_window_resets_at": "2026-06-02T14:32:00Z"
}
Response (free tier, with a default region set)
{
  "tier": "free",
  "bytes_used": 1284321612,
  "bytes_limit": 5368709120,
  "session_seconds": 5234,
  "session_seconds_limit": 7200,
  "max_session_seconds": 0,
  "bytes_window_resets_at": "2026-06-08T14:32:00Z",
  "seconds_window_resets_at": "2026-06-02T14:32:00Z",
  "default_region": "fsn"
}
Response (paid tier)
{
  "tier": "paid",
  "bytes_used": 824311612831,
  "bytes_limit": 0,
  "session_seconds": 9876,
  "session_seconds_limit": 0,
  "max_session_seconds": 0,
  "bytes_window_resets_at": "2026-06-02T14:32:00Z",
  "seconds_window_resets_at": "2026-06-02T14:32:00Z"
}

​
Response shape

FieldTypeNotes
tierstringanonymous, free, or paid.
bytes_usedintegerCumulative bytes across all sessions in the current bytes window.
bytes_limitintegerPer-tier byte cap. 0 for paid (unmetered).
session_secondsintegerCumulative session seconds in the current time window.
session_seconds_limitintegerPer-tier time cap. 0 for paid (unmetered).
max_session_secondsintegerPer-session wall-clock cap. 0 on every tier in v1 - the window counters do the work. Reserved for future tightening.
bytes_window_resets_atstring (RFC 3339)When the bytes counter rolls over. Rolling 7 days on anonymous and free. Irrelevant on paid (unmetered).
seconds_window_resets_atstring (RFC 3339)When the session-seconds counter rolls over. Rolling 24 h on every tier.
default_regionstring, optionalPersisted preference; omitted when the account has none.

​
Notes

  • Two independent rolling windows per account: bytes and seconds advance separately, so a heavy-bandwidth day doesn’t lock out time you haven’t used (and vice versa). On anonymous and free, bytes roll over a 7-day window while time rolls over 24 h - the design point is “predictable daily time budget, weekly bytes budget that takes a deliberate decision to reset by waiting.”
  • There is no calendar-month accounting in v1.
  • bytes_used is updated by node-agent heartbeats roughly every 10-30 seconds. For a live, up-to-the-second view of a single in-flight session, use GET /v1/sessions/{id} instead - its response includes quota_bytes_used / quota_seconds_used (the same values you see here) alongside the per-session bytes_in / bytes_out.
  • Paid tier reports bytes_limit: 0 and session_seconds_limit: 0 to signal “unmetered.” Clients should treat 0 as “no cap,” not as “zero budget.”

​
See also