Pay-per-GB proxy parameters
PPG proxy selection parameters are suffixes appended to the proxy username. Use Configure & export in the dashboard to choose the pool, hub, protocol, location, and session. For what counts as billed traffic and how to cut it, see How pay-per-GB traffic is counted.
Connection scope#
One PPG credential works with each eligible hub and with HTTP or SOCKS5. The selected pool determines routing and price. A flexible token selects its pool with _pool-.... A fixed token uses its saved pool and does not need that suffix; a different pool suffix is rejected.
UDP#
Pools marked UDP carry UDP through the SOCKS5 endpoint. HTTP proxies carry TCP only. The pay-per-GB pools API reports this as udp. UDP can reach any destination port except a few commonly abused services, such as SNMP, NetBIOS, SIP, SSDP and memcached.
Browsers can't use UDP through their proxy setting: Chrome's SOCKS5 support relays TCP only, so HTTP/3 falls back to HTTP/2 and WebRTC can go around the proxy. To give a browser or a whole device UDP (HTTP/3, WebRTC calls), link the proxy to a VPN profile. UDP proxies lists the pools that carry UDP.
Username grammar#
Append zero or more underscore-delimited segments to the base proxy username:
<base-username>_pool-residential-kilo_country-us_region-california_city-los-angeles_sid-crawl-42_sttl-600
| Parameter | Syntax | Rules |
|---|---|---|
pool |
_pool-<auth-key> |
Required in exported credentials. Lowercase pool key from the dashboard; maximum 80 characters. |
country |
_country-<slug> |
Lowercase geo slug, maximum 80 characters. uk normalizes to gb. |
region |
_region-<slug> |
Requires country when used as a canonical geo path. |
state |
_state-<slug> |
Compatibility alias for region. Do not send state and region together. |
city |
_city-<slug> |
Requires both country and region. |
sid |
_sid-<session-id> |
Letters, numbers, and hyphens after sanitization; at least 3 characters. Only the first 15 are used, so keep session IDs unique within their first 15 characters. |
sttl |
_sttl-<seconds> |
1–86400 is honored. 0 or 86401–999999 currently falls back to 600; seven or more digits are invalid. |
Use lowercase dashboard slugs. City targeting requires both country and region. state is a compatibility alias for region; do not provide both. The lowercase country alias uk normalizes to gb in this username grammar, unlike the free-proxy API.
Geography examples#
# country
<base-username>_pool-residential-kilo_country-us
# region inside a country
<base-username>_pool-residential-kilo_country-us_region-california
# city inside a region
<base-username>_pool-residential-kilo_country-us_region-california_city-los-angeles
Use the geography options shown for the selected pool in the dashboard. A syntactically valid slug can still be unavailable from that pool.
Invalid or ambiguous examples:
<base-username>_city-los-angeles
<base-username>_region-california_city-los-angeles
<base-username>_country-us_region-california_state-california
Sticky sessions#
sid requests session affinity. After sanitization, the session ID contains letters, numbers, and hyphens and must be at least 3 characters. Only the first 15 characters are used, so keep session IDs unique within their first 15 characters.
<base-username>_pool-residential-kilo_country-de_sid-cart-17_sttl-900
sttl controls the requested sticky lifetime in seconds. Values 1–86400 are honored. Current compatibility behavior maps 0 and values 86401–999999 to 600 seconds; seven or more digits are invalid. Prefer an explicit valid value and do not rely on fallback behavior.
Traffic cap and expiry#
Each pay-per-GB proxy can have its own traffic cap and expiry date. Both are optional. Use them to give a customer, a team member, or a tool a fixed amount of traffic or a fixed time.
- Dashboard. Add or edit a proxy on the Pay-per-GB page. Traffic limit (GB) is the cap in gigabytes; write decimals with a dot or a comma (
2.5or2,5). Expires is a date, and the proxy stops at the end of that day (UTC). In the proxy list, the Traffic stats box shows how much of the limit has been counted, which can run slightly ahead of the traffic delivered. - API. Send
expiresAtandallowanceByteswhen you create or change a proxy. Both are returned on every token.
The cap counts all traffic between your client and the hub, in both directions, protocol overhead included, so it is never less than the traffic you are charged. A proxy can stop a little short of its cap, never over it. The cap only refuses traffic; what you are charged doesn't change. See Traffic cap for the details.
A proxy that has used all of its cap is refused with proxy error 24. Adding, changing, or removing a cap ends the proxy's open connections once, and clients reconnect under the new cap.
Proxy addresses#
Settings > Proxy addresses has one checkbox, Use neutral addresses. It is off by default. When it is on:
- proxy lists, the proxy generator, and the API show neutral hostnames and neutral pool names;
- change-IP links use the neutral address;
- HTTPS proxy lines keep
litport.net, because the HTTPS certificate is issued for that name.
It changes the names we show you for your own account. It doesn't change the proxies' IP addresses, VPN profiles, emails, or the dashboard's own address. Where a neutral name is the same as the standard one, nothing changes for that name.
Errors and retries#
PPG selection failures are normally HTTP proxy error code 11 with a specific message. A traffic-accounting failure is code 12. Insufficient balance is code 13 with HTTP 402 and requires checking or adding balance rather than a network retry. A proxy that has used its traffic cap is code 24 with HTTP 403; code 25 with HTTP 503 means the cap could not be read in time, and a brief retry is fine.
Read Proxy error reference for the observable HTTP headers and SOCKS5 limitations. For PPG upstream failures, see code 16 guidance.