Pay-per-GB API

Pay-per-GB (PPG) pools, geo targeting values, and account balance.

Pools#

GET /api/v1/pay-per-gb/pools
Authorization: Bearer lit_...

A complete list: every pool the account can select, always with page.nextCursor: null. Takes no limit or cursor.

{
  "data": [
    {
      "name": "Residential",
      "proxiesType": "residential",
      "authKey": "residential-main",
      "pricePerGb": "4.50",
      "httpPort": 1337,
      "socks5Port": 5337,
      "hubs": [
        { "id": "us-11", "name": "New York, NY", "hostname": "hub-us-11-1.litport.net" },
        { "id": "eu-1", "name": "Amsterdam", "hostname": "hub-eu-1.litport.net" }
      ],
      "geoLevels": ["country", "region", "city"]
    }
  ],
  "page": { "nextCursor": null }
}

authKey is the only pool identifier this API exposes, and the value to put in the proxy username; no internal catalog ID is returned. pricePerGb is a base-10 decimal string already adjusted for the account's plan discount. It is the full effective rate, not a rounded display price, so a charge can be reproduced from billed bytes and this value. httpPort and socks5Port are the ingress ports for that pool's proxy type. hubs lists the hubs this pool can be routed through. geoLevels lists the levels this pool supports for geo targeting, broadest first, or [] when the pool has no geo targeting.

Example identifiers and hubs in this documentation are illustrative.

Geo#

GET /api/v1/pay-per-gb/geo
Authorization: Bearer lit_...

A paged list of geo targeting values: the country, region, or city values a set of pools actually supports, so a geo-blocked proxy request (a country/region/city parameter Litport does not recognize or does not have exit capacity for) can be corrected instead of guessed at again.

curl --get 'https://litport.net/api/v1/pay-per-gb/geo' \
  -H "Authorization: Bearer $LITPORT_API_KEY" \
  --data-urlencode 'pool=residential-main' \
  --data-urlencode 'level=region' \
  --data-urlencode 'country=us' \
  --data-urlencode 'limit=50'

{
  "data": [
    { "value": "california", "label": "California" },
    { "value": "new-york", "label": "New York" }
  ],
  "page": { "nextCursor": null }
}

data is the intersection of values every requested pool supports at the given level, so a returned value is guaranteed usable with all of them together. Each option's value is the exact lowercase slug to send as the corresponding country, region, or city proxy-username parameter; label is a display name, and country-level options may also carry emoji. q filters data by a case-insensitive, punctuation-insensitive substring match against value or label.

Geo errors#

Check a pool's geoLevels first to avoid the two GEO_ errors.

Balance#

GET /api/v1/pay-per-gb/balance
Authorization: Bearer lit_...

Use this to explain a proxy request that failed with insufficient balance (code 13) without guessing at the cause.

{
  "data": {
    "balance": {
      "unitsActive": "12.345678901234",
      "unitsReserved": "0.5",
      "unitsAvailable": "11.845678901234",
      "unitsExpireAt": "2026-12-01T00:00:00.000Z"
    },
    "plan": {
      "id": "pro-monthly",
      "expiresAt": "2026-10-01T00:00:00.000Z"
    }
  }
}

unitsActive, unitsReserved, and unitsAvailable are base-10 decimal strings so clients never lose precision to floating-point rounding. unitsReserved is non-negative and currently held by in-flight billing transactions, not yet final. unitsAvailable is unitsActive minus unitsReserved and is signed: it goes negative when reservations exceed the active balance, or when a finished run had to be charged beyond the available balance. Treat a request as at risk of an insufficient-balance error when unitsAvailable is at or near zero. unitsExpireAt is the timestamp of the soonest-expiring active balance, or null when none is scheduled to expire.

plan.id is the active plan identifier, or null when the account has no active plan. plan.expiresAt is that plan's expiration timestamp, or null when there is no active plan.

This endpoint reports balance only. It does not return email, name, or any other account profile field.

Pay-per-GB tokens#

A PPG token's poolSelection (see Tokens) names its fixed pool, or reports that the proxy username must select one. List an account's PPG tokens with GET /tokens?type=ppg. See Pay-per-GB proxies for the full username grammar, including how the pool, geo, and session parameters combine.