> ## Documentation Index
> Fetch the complete documentation index at: https://www.illusory.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Started

> Connect to Illusory Residential Proxies and make your first request.

You connect to residential proxies with a single endpoint and your account credentials. Targeting (country, city, session) is set right in the username.

## Connection details

| Field              | Value                                 |
| ------------------ | ------------------------------------- |
| Host (recommended) | `proxy.illusory.io`                   |
| IP (alternative)   | `160.202.129.71`                      |
| Port               | `1080`                                |
| Username           | Your Illusory username                |
| Password           | Your proxy secret                     |
| Protocols          | HTTP/HTTPS and SOCKS5 (auto-detected) |

<Note>
  Use the domain or the IP, whichever you prefer. We recommend the domain: it stays stable if our infrastructure changes, while the IP works identically today.
</Note>

<Note>
  During the private beta, we provide your **username** and **proxy secret** directly. Keep your secret private. Anyone with it can use your balance.
</Note>

<Note>
  There is no connection limit: the same endpoint handles unlimited parallel connections, each with its own IP. See [Sessions](/docs/residential/sessions) for rotating vs sticky.
</Note>

## Username format

Your username carries optional targeting tokens. With no tokens, you get a rotating IP from anywhere in the pool:

```
<username>[-country-<cc>][-state-<st>][-city-<city>][-asn-<n>][-session-<id>[-sesstime-<min>]]
```

For example, to request a rotating **US** exit:

```
<username>-country-us
```

See [Targeting](/docs/residential/targeting) for every option and [Sessions](/docs/residential/sessions) for sticky IPs.

## Your first request

Replace `USERNAME` and `SECRET` with your credentials:

```bash theme={null}
curl -x "http://USERNAME-country-us:SECRET@proxy.illusory.io:1080" https://api.ipify.org
```

This prints the residential exit IP your request came from. Run it a few times. With no `-session`, each request rotates to a new IP.

<Check>
  If the returned IP is different from your own and changes between requests, you're connected and rotating correctly.
</Check>

## Verify your location

Check that geo-targeting is working by inspecting the exit IP's location:

```bash theme={null}
curl -x "http://USERNAME-country-gb:SECRET@proxy.illusory.io:1080" https://ipinfo.io/json
```

The `country` field in the response should match the country you targeted (`gb` in this example).

## Troubleshooting

<AccordionGroup>
  <Accordion title="407 Proxy Authentication Required">
    Your username or secret is wrong, or the secret was rotated. Re-check your credentials.
  </Accordion>

  <Accordion title="Connection works but no data / it stalls">
    Sticky sessions pin a single residential peer, whose quality can vary. Try a [rotating](/docs/residential/sessions) request (omit `-session`), or start a new session id.
  </Accordion>

  <Accordion title="Requests fail after working fine">
    You may have run out of balance. Reach out to top up your GB during the beta.
  </Accordion>
</AccordionGroup>