Usage & limits

Byte convention

Everything is metered in bytes, where 1 GB = 1,000,000,000 bytes (decimal, not 2³⁰). A “10 GB” balance is exactly 10000000000 bytes.

Usage counts both directions: bytes sent upstream plus bytes received.

Checking your balance

With your API key:

curl -H "Authorization: Bearer $HYPERCALL_KEY" https://api.hypercall.dev/api/me

{
  "id": "6f1c1f8e-6f0a-4b8f-9a5e-2f9d1c3b7a10",
  "parent_id": null,
  "can_resell": true,
  "name": "acme",
  "status": "active",
  "proxy_username": "acme",
  "proxy_password": "<your proxy password>",
  "stats_token": "<opaque token>",
  "max_bytes": 500000000000,
  "allocated_bytes": 0,
  "bytes_used": 2885007,
  "remaining_bytes": 499997114993,
  "thread_cap": null,
  "speed_limit_mbps": null,
  "expires_at": null,
  "ip_auths": [],
  "ip_restrictions": [],
  "created_at": "2026-01-12T09:30:00Z"
}

Field	Meaning
`max_bytes`	Your total budget. `null` = unlimited
`bytes_used`	Consumed by your own proxy traffic
`allocated_bytes`	Handed down to sub-users (see below)
`remaining_bytes`	`max_bytes − allocated_bytes − bytes_used`
`status`	`active`, `suspended`, `depleted`, or `expired`

The public stats endpoint

Each account has an opaque stats_token for unauthenticated usage checks. This is useful for dashboards, or for handing a customer a read-only link without giving them an API key.

curl https://api.hypercall.dev/stats/<stats_token>
curl 'https://api.hypercall.dev/stats/<stats_token>?format=txt'

used=2885007 total=500000000000 remaining=499997114993

On unlimited accounts, total and remaining read unlimited.

The token exposes usage only: no credentials, no ability to change anything.

Limits

Limit	Effect when hit
Byte budget	Requests stop with `402`
`thread_cap`	Concurrent connections over the cap get `429`
`speed_limit_mbps`	Throughput shaped to the cap; requests still succeed
`expires_at`	After this time the account stops serving

Limits apply the moment they’re hit. In-flight connections are cut when a budget runs out, not just new ones.

Sub-users

If your account can resell, you can create sub-users and carve your budget between them:

curl -H "Authorization: Bearer $HYPERCALL_KEY" -X POST \
  -H 'Content-Type: application/json' \
  -d '{"name": "customer-a", "gb": 50}' \
  https://api.hypercall.dev/api/users

That moves 50 GB out of your balance into theirs: your allocated_bytes rises, your remaining_bytes falls. Sub-users get their own credentials, their own stats token, and their own limits.

Allocated data belongs to the sub-user: their consumption does not draw on your bytes_used again, and you can only reclaim what they haven’t spent:

# Take back everything unused
curl -H "Authorization: Bearer $HYPERCALL_KEY" -X POST \
  https://api.hypercall.dev/api/users/<id>/refund

If you allocate your entire budget out, you stop serving (your remaining is 0) while your sub-users keep running, because they already own those bytes.