> For the complete documentation index, see [llms.txt](https://docs.helodata.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.helodata.com/getting-started/username-format.md).

# 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](/products/overview-2/proxy-list-format.md) 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](/troubleshooting/407.md).

## 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:PASSWORD@gate.helodata.io: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](/resources/proxy-tester.md) that parses any username and tells you which segments it interpreted. Use it when a request returns an unexpected geo or a 407.