# 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:

```text
<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

```text
# 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:

```text
<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.

```text
<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](/docs/proxy-errors) for the observable HTTP headers and SOCKS5 limitations. For PPG upstream failures, see [code 16 guidance](/docs/proxy-errors#ppg-upstream-failures).