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

# Build a Rotating Proxy Connection

> Generate a copy-paste rotating proxy URL from location and rotation options.

Use this endpoint when a customer needs one usable rotating proxy connection string.

<Note>
  Subusers are optional. Omit `subuserId` to use your account's default proxy credentials. Set it only when you want to organize proxy traffic into groups for separate reporting or replace exposed credentials. See [Manage Rotating Proxy Subusers](/docs/guides/subusers).
</Note>

## 1. Choose a Location

```bash theme={null}
curl --request GET \
  --url "$FLOPPY_BASE_URL/v2/proxy/rotating/locations?type=residential" \
  --header "X-Api-Key: $FLOPPY_API_KEY"
```

The response lists countries with country-level `cities` and `states`. It is not a city-under-state mapping.

## 2. Build the Connection

```bash theme={null}
curl --request POST \
  --url "$FLOPPY_BASE_URL/v2/proxy/rotating/connections" \
  --header "Content-Type: application/json" \
  --header "X-Api-Key: $FLOPPY_API_KEY" \
  --data '{
    "type": "residential",
    "country": "US",
    "city": "New York",
    "protocol": "socks5",
    "rotation": 15,
    "udp": true
  }'
```

Copy `connection.connectionString` from the response.

```json theme={null}
{
  "connection": {
    "protocol": "socks5",
    "host": "geo.g-w.info",
    "port": 10800,
    "username": "user-USERNAME-type-residential-country-US-city-New_York-rotation-15-udp-1",
    "password": "PASSWORD",
    "connectionString": "socks5://user-USERNAME-type-residential-country-US-city-New_York-rotation-15-udp-1:PASSWORD@geo.g-w.info:10800"
  },
  "parameters": {
    "type": "residential",
    "country": "US",
    "city": "New York",
    "rotation": 15,
    "protocol": "socks5",
    "udp": true
  }
}
```

## Request Rules

| Field       | Notes                                                                                                                            |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `subuserId` | Optional. ID from `GET /v2/proxy/rotating/subusers`. Omit it to use the account's default proxy credentials.                     |
| `type`      | `residential`, `mobile`, or `datacenter`.                                                                                        |
| `country`   | Two-letter country code.                                                                                                         |
| `state`     | Optional. Takes precedence over `city` when both are supplied.                                                                   |
| `city`      | Optional. Used when `state` is not supplied.                                                                                     |
| `rotation`  | `-1` for every request, `0` for sticky session, or `1..60` minutes.                                                              |
| `protocol`  | `http`, `https`, or `socks5`.                                                                                                    |
| `udp`       | Optional. Use `true` only with `protocol: "socks5"` and `type: "residential"` or `"mobile"`. Adds `udp-1` to the proxy username. |

## 3. Use the Connection

```bash theme={null}
curl --proxy "socks5://USERNAME:PASSWORD@geo.g-w.info:10800" \
  "https://example.com"
```

## Usage Tips

| Situation                           | Tip                                                                                                   |
| ----------------------------------- | ----------------------------------------------------------------------------------------------------- |
| You want one ready-to-use proxy URL | Copy `connection.connectionString`; it already includes protocol, username, password, host, and port. |
| You need country targeting          | Send `country` as a two-letter code such as `US`.                                                     |
| You need regional targeting         | Use `state` or `city`; if both are supplied, `state` takes precedence.                                |
| You want a new IP often             | Use `rotation: -1` for rotation on every request.                                                     |
| You want a sticky session           | Use `rotation: 0`.                                                                                    |
| You want timed rotation             | Use `rotation` from `1` to `60` minutes.                                                              |
| You need UDP traffic                | Use `protocol: "socks5"` with residential or mobile proxies and set `udp: true`.                      |
| You are unsure about proxy type     | Start with `residential`; use `mobile` or `datacenter` only when that matches the target workflow.    |

<Tip>
  Generate one connection per call. If your app needs several proxy URLs, call the connections endpoint several times and store each returned `connection.connectionString`.
</Tip>

<CardGroup cols={3}>
  <Card title="Run connections in API Reference" icon="play" href="/docs/api-reference/v2/endpoint/rotating-connection">
    Generate a live connection string from the docs.
  </Card>

  <Card title="Manage subusers" icon="users" href="/docs/guides/subusers">
    Organize proxy groups or replace exposed credentials.
  </Card>

  <Card title="Check the proxy" icon="circle-check" href="/docs/guides/check-proxy">
    Validate the connection string returned by the API.
  </Card>
</CardGroup>