---
title: "Build ready-to-use residential proxy URLs"
method: POST
path: "/api/v1/residential/proxy-url"
---

# Build ready-to-use residential proxy URLs

`POST /api/v1/residential/proxy-url`

## Request

- Base URL: `https://ipmusk.com`
- URL: `https://ipmusk.com/api/v1/residential/proxy-url`
- Auth: HTTP bearer

protocol://username:password@host:port URLs targeting a country, optionally a state and a city (a city needs its state). sticky keeps one exit IP for sticky_minutes (1, 3, 10 or 30; default 10) and each of the count URLs gets its own session, so its own IP. rotating changes IP on every request, so every URL would be identical: rotating returns exactly one item whatever count says. A misspelt state is not caught here; the connection then fails. 404 not_found when there is no usable residential traffic.

## Request body

- object
  - `country` string, required: ISO 3166-1 alpha-2 exit country, e.g. US.
  - `state` string: State or region of the country, in English, e.g. "California".
  - `city` string: City under the state, in English. Needs state.
  - `session` 'rotating' | 'sticky', required: rotating: new exit IP per request. sticky: one IP for sticky_minutes.
  - `sticky_minutes` union: How long a sticky session keeps its IP. Default 10. Sticky only.
    - 1
    - 3
    - 10
    - 30
  - `protocol` 'http' | 'socks5'
  - `count` integer: How many sticky URLs, each its own IP. Rotating always returns one.

## Response `200`

Build ready-to-use residential proxy URLs

- object
  - `data` object, required
    - `protocol` 'http' | 'socks5', required
    - `session` 'rotating' | 'sticky', required
    - `sticky_minutes` union, required
      - 1
      - 3
      - 10
      - 30
    - `items` object[], required
      - `url` string, required
      - `host` string, required
      - `port` integer, required
      - `username` string, required
      - `password` string, required
  - `request_id` string, required

## Other responses

- `default`: Any failure: 400 validation_error, 401 authentication_required, 403 forbidden / capability_unavailable, 404 not_found, 409 invalid_state_transition / idempotency_conflict, 422 product_unavailable, 429 rate_limited, 500 internal_error.

---

[API](https://skmtc.dev/ipmusk/apis/ipmusk-customer-api.md) · [All operations](https://skmtc.dev/ipmusk/apis/ipmusk-customer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ipmusk/apis/ipmusk-customer-api/revisions/89f8b46fda61?raw)