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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.helodata.com/getting-started/username-format.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.