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.
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.
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; 3–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 3–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.
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 and requires checking or adding balance rather than a network retry.
Read Proxy error reference for the observable HTTP headers and SOCKS5 limitations. For PPG upstream failures, see code 16 guidance.