Username format

Applies to gateway products only — Residential and Mobile. ISP proxies use a different credential model: each IP is delivered as a ip:port:user:pass line in a downloadable list. See Proxy list format for ISP details.

For the gateway products, helodata encodes all targeting parameters — sub-user, product type, geo, ASN, sticky session — into a single proxy username string. The password stays the same; only the username changes when you want to target a different country, a different sub-user, or open a sticky session.

Full grammar

helo_{username}-type-{type}-region-{region}[-state-{state}][-city-{city}][-asn-{asn}][-session-{session_id}-sesstime-{ttl}]

Segment	Required	Description
helo_	yes	Fixed prefix. Identifies the credential as helodata-format.
{username}	yes	Your sub-user name as shown in Dashboard → Sub-users (e.g. s1a2b3c4d5e).
-type-{type}	yes	Product type. res (residential) or mob (mobile).
-region-{region}	yes	ISO-3166 alpha-2 country code, lowercase (e.g. us, de, jp).
-state-{state}	optional	State / province code for finer targeting. US states use 2-letter codes (ca, ny).
-city-{city}	optional	City slug (lowercase, no spaces — e.g. la, newyork, tokyo).
-asn-{asn}	optional	AS number to pin the carrier or ISP (e.g. 2516 for KDDI).
-session-{session_id}-sesstime-{ttl}	optional	Open a sticky session. {session_id} is any string you choose (max 32 chars, [a-z0-9]); {ttl} is the session lifetime in minutes (1–30 for residential/ISP, 1–60 for mobile). Both segments must appear together or not at all.

Segments are concatenated with a single - and must appear in the order shown above. Unknown or out-of-order segments cause a 407 at the gateway — see 407 Proxy Authentication Required.

Examples

Goal	Username
Basic proxy (any US residential exit)	helo_s1a2b3c4d5e-type-res-region-us
US residential, California, Los Angeles	helo_s1a2b3c4d5e-type-res-region-us-state-ca-city-la
Mobile, Japan, KDDI (ASN 2516)	helo_s1a2b3c4d5e-type-mob-region-jp-asn-2516
Sticky residential session, US, 30 min	helo_s1a2b3c4d5e-type-res-region-us-session-abc-sesstime-30
Sticky mobile session, US, 60 min	helo_s1a2b3c4d5e-type-mob-region-us-session-job42-sesstime-60

Rotation vs sticky

• Omit the session segment → every TCP connection gets a fresh exit IP (rotating mode).
• Include session-XXX-sesstime-N → connections that share the same session_id reuse the same exit IP for up to N minutes (sticky mode).

Two requests with the same session_id but different other parameters will be treated as separate sessions. Treat the full username string — not just the session_id — as the session key.

Where the username goes

In a proxy URL:

http://helo_s1a2b3c4d5e-type-res-region-us:[e-mail]:7777

In a Proxy-Authorization header (Basic auth, base64 of username:password):

Proxy-Authorization: Basic aGVsb19zMWEyYjNjNGQ1ZS10eXBlLXJlcy1yZWdpb24tdXM6UEFTU1dPUkQ=

Validating your string

The dashboard ships a Proxy tester that parses any username and tells you which segments it interpreted. Use it when a request returns an unexpected geo or a 407.