Geographic targeting
Use region and country clauses in your proxy username to restrict the exits eligible for a new connection. Filters select from available exits; they do not reserve capacity or guarantee availability in a location.
The same geographic clauses work with HTTP and SOCKS5 proxy authentication. They belong in the routing username, while the full proxy key is the password.
Target a country
Section titled “Target a country”Use a two-letter ISO country code:
v1_rotate_countries_USTo allow several countries, separate codes with commas:
v1_rotate_countries_US,GBThis permits an exit in either the United States or the United Kingdom. The singular spelling country is accepted as an alias for countries:
v1_rotate_country_USUse countries consistently when generating usernames programmatically.
Target a region
Section titled “Target a region”Use NA, SA, AF, AS, or EU. Multiple region codes use hyphens:
v1_rotate_regions_NA-EUThis permits exits in North America or Europe. See the region table for names.
Exits in Oceania, such as Australia and New Zealand, have no region code. Target them by country, with AU or NZ.
Combine filters
Section titled “Combine filters”Selections within one list are combined with OR. Different filter clauses are combined with AND. Exclusions are applied to the resulting set.
v1_rotate_regions_NA_countries_US,MX_exclude_MXThe exit must match North America and must be in either the US or Mexico, then Mexico is removed. The resulting selection permits only matching US exits.
| Username filters | Eligible geography |
|---|---|
| No geographic clauses | Any eligible exit |
_countries_US,GB |
US or United Kingdom |
_regions_NA-EU |
North America or Europe |
_regions_EU_countries_DE,FR |
Europe and either Germany or France |
_countries_US,GB_exclude_GB |
US only |
_countries_US_exclude_US |
Empty selection |
The last example is syntactically valid but cannot match an exit. Similarly, contradictory region and country requirements can produce an empty selection.
Apply targeting to a session
Section titled “Apply targeting to a session”The same filter clauses work with sticky and fixed strategies:
v1_sticky_session_checkout-42_countries_USv1_fixed_session_audit-42_regions_EU_countries_DE,FRKeep the strategy and geographic policy stable for an existing session ID. Create a new session ID when changing its policy. Reusing an active ID with different filters can produce a session policy conflict during connection setup.
Handle unavailable locations
Section titled “Handle unavailable locations”When no eligible exit matches the request, HTTP proxying returns 502 no_exit_available; SOCKS5 returns a general-failure CONNECT reply (0x01). A valid country code can still have no active exits. See Troubleshooting for protocol-specific errors.
Review contradictory clauses first, then consider a broader selection appropriate to your application. Do not silently broaden geography when your application requires a specific location.
The username grammar currently has no city, state, postal-code, ASN, or carrier selector. A region or country filter refers to the exit’s location metadata, not the destination website’s location.