API Reference

Your account's overall bandwidth balance — not per sub-user, see the usage endpoint below for that.

curl https://globproxy.com/api/v1/account/bandwidth \
  -H "Authorization: Bearer YOUR_KEY"

Response

{
  "total_gb": 500,
  "used_gb": 128.4,
  "available_gb": 371.6,
  "expires": "never"
}

All proxy credentials (sub-users) on your account, newest first.

curl https://globproxy.com/api/v1/sub-users \
  -H "Authorization: Bearer YOUR_KEY"

Response

{
  "sub_users": [
    {
      "id": "3f1a...",
      "label": "Client A",
      "status": "active",
      "gb_allocated": 5,
      "gb_used": 1.2,
      "country": "us",
      "state": "california",
      "city": null,
      "asn": null,
      "session_type": "rotating",
      "protocol": "http",
      "sticky_duration": null,
      "host": "proxy.globproxy.com",
      "port": 9000,
      "geonode_username": "geonode_xxx",
      "connection_username": "geonode_xxx-type-residential-country-us-state-california",
      "activated_at": "2026-08-01T12:00:00.000Z",
      "created_at": "2026-08-01T12:00:00.000Z"
    }
  ]
}

Use connection_username (not geonode_username) as the proxy username — it has your targeting baked in. For a sticky session, generate a fresh -session-* suffix per connection rather than reusing this one indefinitely; that logic lives client-side, this endpoint just returns the base credential.

Creates a new proxy credential and reserves the requested bandwidth from your account balance atomically — a burst of concurrent creates can't oversubscribe your balance.

curl -X POST https://globproxy.com/api/v1/sub-users \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Client A",
    "gb_allocated": 5,
    "country": "us",
    "state": "california",
    "protocol": "http",
    "session_type": "rotating"
  }'

Body parameters

Response — 201 Created

{
  "id": "3f1a...",
  "label": "Client A",
  "status": "active",
  "host": "proxy.globproxy.com",
  "port": 9000,
  "username": "geonode_xxx",
  "connection_username": "geonode_xxx-type-residential-country-us-state-california",
  "gb_allocated": 5,
  "country": "us"
}

status can come back "pending" instead of "active" if the upstream provisioning step is briefly unavailable — the credential and bandwidth reservation are still created, it just activates shortly after rather than instantly. Poll the sub-user via the list endpoint if you need to confirm it's live before using it.

Current usage for a single sub-user, synced live from the upstream provider when the credential is active.

curl https://globproxy.com/api/v1/sub-users/SUB_USER_ID/usage \
  -H "Authorization: Bearer YOUR_KEY"

Response

{
  "id": "3f1a...",
  "label": "Client A",
  "status": "active",
  "protocol": "http",
  "session_type": "rotating",
  "gb_allocated": 5,
  "gb_used": 1.2,
  "gb_remaining": 3.8,
  "country": "us",
  "state": "california",
  "city": null,
  "host": "proxy.globproxy.com",
  "port": 9000,
  "username": "geonode_xxx"
}

Deletes a sub-user and releases whatever portion of its bandwidth reservation was never used back to your account balance. Already-consumed usage isn't refunded — only the unused remainder.

curl -X DELETE https://globproxy.com/api/v1/sub-users/SUB_USER_ID \
  -H "Authorization: Bearer YOUR_KEY"

Response

{ "success": true }

A sub-user that a reseller allocated to you (rather than one you created yourself) can't be deleted through the API, same as in the dashboard — 403 if you try.

Adds bandwidth to a sub-user you already have, instead of creating a new one. Reserves the amount from your balance atomically, same guarantee as creation.

curl -X POST https://globproxy.com/api/v1/sub-users/SUB_USER_ID/topup \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "gb_amount": 5 }'

Body parameters

Response

{ "success": true, "gb_allocated": 10 }

gb_allocated is the sub-user's new total cap, not the amount just added. 402 if your account balance can't cover the top-up.

Turns automatic top-up on or off for a sub-user — when its remaining bandwidth drops to threshold_gb, amount_gb is added automatically from your balance, checked on the same cycle that syncs usage.

curl -X PATCH https://globproxy.com/api/v1/sub-users/SUB_USER_ID/auto-topup \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true, "threshold_gb": 1, "amount_gb": 5 }'

Body parameters

Send { "enabled": false } to turn it off — threshold_gb/amount_gb aren't required (or stored) in that case.

IP addresses currently allowed to use this sub-user's credentials.

curl https://globproxy.com/api/v1/sub-users/SUB_USER_ID/whitelist \
  -H "Authorization: Bearer YOUR_KEY"

Response

{
  "ips": [
    { "ip": "203.0.113.4", "description": "Office IP" }
  ]
}

curl -X POST https://globproxy.com/api/v1/sub-users/SUB_USER_ID/whitelist \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "ip": "203.0.113.4", "description": "Office IP" }'

Body parameters

Returns the sub-user's full updated whitelist, same shape as the GET above.

curl -X DELETE "https://globproxy.com/api/v1/sub-users/SUB_USER_ID/whitelist?ip=203.0.113.4" \
  -H "Authorization: Bearer YOUR_KEY"

ip is a query parameter here, not a body field.

curl -X POST https://globproxy.com/api/v1/sub-users/SUB_USER_ID/whitelist/bulk \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "ip": "203.0.113.4", "description": "Office IP" },
      { "ip": "198.51.100.9", "description": "Home IP" }
    ]
  }'

Up to 150 IPs per request. All-or-nothing — the first invalid entry rejects the whole batch.

curl -X DELETE https://globproxy.com/api/v1/sub-users/SUB_USER_ID/whitelist/bulk \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "ips": ["203.0.113.4", "198.51.100.9"] }'

A POST-shaped body on a DELETE — deliberate, so it can carry an arbitrary-length list rather than being limited to what fits in a query string.