Browse endpoints

ProxyWing Developer API

Sub-Users

Resell your residential traffic. Create sub-users under a service, move GB to and from them, mint their proxy strings and bill them from their own usage reports.

POST/residential/services/{svc_id}/subusers

Create a sub-user

Creates a sub-user under one of your residential services and moves traffic to it from that service's balance. This is how you resell your own traffic: each sub-user is a separate credential with its own GB balance and its own usage reporting. gb must be a WHOLE number of GB (1, 2, 3 …) on both tiers, minimum 1 — fractional values are rejected with 422. The traffic is deducted from the parent service immediately. On Premium you may choose username and password; on Standard both are set by the platform and supplying either returns 400 unsupported_for_tier. Returns 409 insufficient_unallocated_traffic when the service does not have that much unallocated traffic left. Idempotency-Key is REQUIRED — omitting it returns 400 before any traffic moves.

Auth · BearerIdempotency-Key

Path parameters

svc_idstringrequired
The residential service id, from GET /residential/services.

Body parameters

gbnumberrequired
Whole GB to allocate to the new sub-user. Minimum 1.
labelstringoptional
Your own reference for this sub-user, unique within the service.
usernamestringoptional
Premium only. Used exactly as sent; omit to get a random 12-character name.
passwordstringoptional
Premium only. 12–64 characters; omit and we generate one.

RequestPOST /residential/services/{svc_id}/subusers

curl -X POST "https://api.proxywing.com/v1/residential/services/{svc_id}/subusers" \
  -H "Authorization: Bearer pk_live_XXXXXXXX" \
  -H "Idempotency-Key: b3f2a1c4-7e9d-4a2b-8c6f-1d5e9a0b3c7f" \
  -H "Content-Type: application/json" \
  -d '{"label":"acme-client-01","gb":5}'

Response200 · application/json

{
  "id": "rsub_42",
  "service_id": "resi_100001",
  "tier": "premium",
  "label": "acme-client-01",
  "username": "uexxjq9gp4xn",
  "allocated_gb": 5,
  "used_gb": null,
  "available_gb": null,
  "status": "active",
  "created_at": "2026-07-26T08:12:44Z",
  "password": "MCCk99K80AtGEPY2"
}

GET/residential/services/{svc_id}/subusers

List sub-users

Lists the live sub-users on a residential service with their allocated traffic and status. Deleted and failed sub-users are omitted. Live balances are not included here — read them from GET .../subusers/{subuser_id}/traffic. The password is returned only by create and rotate-password, or from GET .../subusers/{subuser_id}/credentials.

Auth · Bearer

Path parameters

svc_idstringrequired
The residential service id, from GET /residential/services.

Query parameters

limitintegeroptional
Maximum rows to return. Default 50.
offsetintegeroptional
Rows to skip, for paging.

RequestGET /residential/services/{svc_id}/subusers

curl -X GET "https://api.proxywing.com/v1/residential/services/{svc_id}/subusers?limit=50" \
  -H "Authorization: Bearer pk_live_XXXXXXXX"

Response200 · application/json

{
  "subusers": [
    {
      "id": "rsub_42",
      "service_id": "resi_100001",
      "tier": "premium",
      "label": "acme-client-01",
      "username": "uexxjq9gp4xn",
      "allocated_gb": 5,
      "used_gb": null,
      "available_gb": null,
      "status": "active",
      "created_at": "2026-07-26T08:12:44Z",
      "password": null
    }
  ]
}

GET/residential/services/{svc_id}/subusers/{subuser_id}

Get a sub-user

Returns one sub-user, including its current allocation and status. Live balances are not included here — read them from GET .../subusers/{subuser_id}/traffic. The password is returned only by create and rotate-password, or from GET .../subusers/{subuser_id}/credentials.

Auth · Bearer

Path parameters

svc_idstringrequired
The residential service id, from GET /residential/services.
subuser_idstringrequired
The sub-user id, e.g. rsub_42.

RequestGET /residential/services/{svc_id}/subusers/{subuser_id}

curl -X GET "https://api.proxywing.com/v1/residential/services/{svc_id}/subusers/{subuser_id}" \
  -H "Authorization: Bearer pk_live_XXXXXXXX"

Response200 · application/json

{
  "id": "rsub_42",
  "service_id": "resi_100001",
  "tier": "premium",
  "label": "acme-client-01",
  "username": "uexxjq9gp4xn",
  "allocated_gb": 5,
  "used_gb": null,
  "available_gb": null,
  "status": "active",
  "created_at": "2026-07-26T08:12:44Z",
  "password": null
}

PUT/residential/services/{svc_id}/subusers/{subuser_id}

Rename a sub-user

Updates the sub-user's label. The label is your own metadata and is never sent to the upstream network. Live balances are not included here — read them from GET .../subusers/{subuser_id}/traffic. The password is returned only by create and rotate-password, or from GET .../subusers/{subuser_id}/credentials.

Auth · Bearer

Path parameters

svc_idstringrequired
The residential service id, from GET /residential/services.
subuser_idstringrequired
The sub-user id, e.g. rsub_42.

Body parameters

labelstringoptional
New label for this sub-user.

RequestPUT /residential/services/{svc_id}/subusers/{subuser_id}

curl -X PUT "https://api.proxywing.com/v1/residential/services/{svc_id}/subusers/{subuser_id}" \
  -H "Authorization: Bearer pk_live_XXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{"label":"acme-client-renamed"}'

Response200 · application/json

{
  "id": "rsub_42",
  "service_id": "resi_100001",
  "tier": "premium",
  "label": "acme-client-01",
  "username": "uexxjq9gp4xn",
  "allocated_gb": 5,
  "used_gb": null,
  "available_gb": null,
  "status": "active",
  "created_at": "2026-07-26T08:12:44Z",
  "password": null
}

POST/residential/services/{svc_id}/subusers/{subuser_id}/allocate

Add traffic to a sub-user

Moves more traffic from the parent service to this sub-user. gb must be a WHOLE number of GB (1, 2, 3 …), minimum 1; fractional values are rejected with 422. Returns 409 insufficient_unallocated_traffic if the parent service does not hold that much unallocated traffic. Idempotency-Key is REQUIRED — omitting it returns 400 before any traffic moves.

Auth · BearerIdempotency-Key

Path parameters

svc_idstringrequired
The residential service id, from GET /residential/services.
subuser_idstringrequired
The sub-user id, e.g. rsub_42.

Body parameters

gbnumberrequired
Whole GB to move to the sub-user. Minimum 1.

RequestPOST /residential/services/{svc_id}/subusers/{subuser_id}/allocate

curl -X POST "https://api.proxywing.com/v1/residential/services/{svc_id}/subusers/{subuser_id}/allocate" \
  -H "Authorization: Bearer pk_live_XXXXXXXX" \
  -H "Idempotency-Key: b3f2a1c4-7e9d-4a2b-8c6f-1d5e9a0b3c7f" \
  -H "Content-Type: application/json" \
  -d '{"gb":2}'

Response200 · application/json

{
  "id": "rsub_42",
  "service_id": "resi_100001",
  "tier": "premium",
  "label": "acme-client-01",
  "username": "uexxjq9gp4xn",
  "allocated_gb": 7,
  "used_gb": null,
  "available_gb": null,
  "status": "active",
  "created_at": "2026-07-26T08:12:44Z",
  "password": null
}

POST/residential/services/{svc_id}/subusers/{subuser_id}/reclaim

Reclaim traffic from a sub-user

Takes traffic back from a sub-user and returns it to the parent service. Omit gb to reclaim everything the sub-user still holds. Unlike allocation, gb here may be fractional: a sub-user granted 3 GB that has spent 0.4 holds 2.6, and that remainder must be returnable. Requesting more than the sub-user holds returns 409 insufficient_subuser_traffic and states the exact amount available. Idempotency-Key is REQUIRED — omitting it returns 400 before any traffic moves.

Auth · BearerIdempotency-Key

Path parameters

svc_idstringrequired
The residential service id, from GET /residential/services.
subuser_idstringrequired
The sub-user id, e.g. rsub_42.

Body parameters

gbnumberoptional
GB to take back. Omit to reclaim the full remaining balance.

RequestPOST /residential/services/{svc_id}/subusers/{subuser_id}/reclaim

curl -X POST "https://api.proxywing.com/v1/residential/services/{svc_id}/subusers/{subuser_id}/reclaim" \
  -H "Authorization: Bearer pk_live_XXXXXXXX" \
  -H "Idempotency-Key: b3f2a1c4-7e9d-4a2b-8c6f-1d5e9a0b3c7f" \
  -H "Content-Type: application/json" \
  -d '{"gb":2}'

Response200 · application/json

{
  "id": "rsub_42",
  "service_id": "resi_100001",
  "tier": "premium",
  "label": "acme-client-01",
  "username": "uexxjq9gp4xn",
  "allocated_gb": 3,
  "used_gb": null,
  "available_gb": null,
  "status": "active",
  "created_at": "2026-07-26T08:12:44Z",
  "password": null
}

DELETE/residential/services/{svc_id}/subusers/{subuser_id}

Delete a sub-user

Deletes the sub-user. Any traffic it still holds is returned to the parent service first, so nothing is lost. The credential stops working immediately. A Premium username stays reserved after deletion and cannot be re-used. Idempotency-Key is REQUIRED — omitting it returns 400 before any traffic moves.

Auth · BearerIdempotency-Key

Path parameters

svc_idstringrequired
The residential service id, from GET /residential/services.
subuser_idstringrequired
The sub-user id, e.g. rsub_42.

RequestDELETE /residential/services/{svc_id}/subusers/{subuser_id}

curl -X DELETE "https://api.proxywing.com/v1/residential/services/{svc_id}/subusers/{subuser_id}" \
  -H "Authorization: Bearer pk_live_XXXXXXXX" \
  -H "Idempotency-Key: b3f2a1c4-7e9d-4a2b-8c6f-1d5e9a0b3c7f"

Response200 · application/json

{
  "id": "rsub_42",
  "status": "deleted"
}

GET/residential/services/{svc_id}/subusers/{subuser_id}/credentials

Get sub-user credentials

Returns the gateway, ports and credentials for this sub-user — what you hand to your own customer. On Premium the targeting tokens are appended to the PASSWORD; on Standard the username is a fixed shared value and the tokens are appended to the USERNAME, with the password identifying the sub-user. targeting_field tells you which applies.

Auth · Bearer

Path parameters

svc_idstringrequired
The residential service id, from GET /residential/services.
subuser_idstringrequired
The sub-user id, e.g. rsub_42.

RequestGET /residential/services/{svc_id}/subusers/{subuser_id}/credentials

curl -X GET "https://api.proxywing.com/v1/residential/services/{svc_id}/subusers/{subuser_id}/credentials" \
  -H "Authorization: Bearer pk_live_XXXXXXXX"

Response200 · application/json

{
  "id": "rsub_42",
  "tier": "premium",
  "gateway": "premium.proxywing.com",
  "http_ports": [
    12345,
    54321
  ],
  "socks5_ports": [
    12345,
    54321
  ],
  "username": "uexxjq9gp4xn",
  "password": "MCCk99K80AtGEPY2",
  "targeting_field": "password"
}

POST/residential/services/{svc_id}/subusers/{subuser_id}/rotate-password

Rotate a sub-user password

Issues a new password for the sub-user; the old one stops authenticating immediately. On Premium the targeting tokens live in the password, so rotating INVALIDATES every proxy string you have already handed out for this sub-user — re-issue them. On Standard the tokens live in the username, so previously issued strings only need the new password. Idempotency-Key is REQUIRED — omitting it returns 400 before any traffic moves.

Auth · BearerIdempotency-Key

Path parameters

svc_idstringrequired
The residential service id, from GET /residential/services.
subuser_idstringrequired
The sub-user id, e.g. rsub_42.

Body parameters

passwordstringoptional
Premium only. Omit to have one generated.

RequestPOST /residential/services/{svc_id}/subusers/{subuser_id}/rotate-password

curl -X POST "https://api.proxywing.com/v1/residential/services/{svc_id}/subusers/{subuser_id}/rotate-password" \
  -H "Authorization: Bearer pk_live_XXXXXXXX" \
  -H "Idempotency-Key: b3f2a1c4-7e9d-4a2b-8c6f-1d5e9a0b3c7f" \
  -H "Content-Type: application/json" \
  -d '{}'

Response200 · application/json

{
  "id": "rsub_42",
  "service_id": "resi_100001",
  "tier": "premium",
  "label": "acme-client-01",
  "username": "uexxjq9gp4xn",
  "allocated_gb": 5,
  "used_gb": null,
  "available_gb": null,
  "status": "active",
  "created_at": "2026-07-26T08:12:44Z",
  "password": "7Qp2LmXe4RtVbN91"
}

GET/residential/services/{svc_id}/subusers/{subuser_id}/traffic

Get sub-user traffic

The sub-user's live balance, read from the network rather than from our cache. A sub-user whose balance reaches zero is refused at the gateway until you allocate more.

Auth · Bearer

Path parameters

svc_idstringrequired
The residential service id, from GET /residential/services.
subuser_idstringrequired
The sub-user id, e.g. rsub_42.

RequestGET /residential/services/{svc_id}/subusers/{subuser_id}/traffic

curl -X GET "https://api.proxywing.com/v1/residential/services/{svc_id}/subusers/{subuser_id}/traffic" \
  -H "Authorization: Bearer pk_live_XXXXXXXX"

Response200 · application/json

{
  "id": "rsub_42",
  "allocated_gb": 5,
  "used_gb": 1.204,
  "available_gb": 3.796
}

GET/residential/services/{svc_id}/subusers/{subuser_id}/usage-report

Sub-user usage report

Per-sub-user usage over a date range, in the same shape as the service-level report — so you can bill your own customer from it without building anything new.

Auth · Bearer

Path parameters

svc_idstringrequired
The residential service id, from GET /residential/services.
subuser_idstringrequired
The sub-user id, e.g. rsub_42.

Query parameters

date_fromstringrequired
Start date, YYYY-MM-DD.
date_tostringrequired
End date, YYYY-MM-DD.
unitstringoptional
B, KB, MB or GB. Default GB.

RequestGET /residential/services/{svc_id}/subusers/{subuser_id}/usage-report

curl -X GET "https://api.proxywing.com/v1/residential/services/{svc_id}/subusers/{subuser_id}/usage-report?date_from=2026-07-01&date_to=2026-07-26&unit=GB" \
  -H "Authorization: Bearer pk_live_XXXXXXXX"

Response200 · application/json

{
  "tier": "premium",
  "date_from": "2026-07-01",
  "date_to": "2026-07-26",
  "unit": "GB",
  "total": 1.204,
  "rows": [
    {
      "date": "2026-07-24",
      "data": 0.61,
      "requests": 8123
    }
  ]
}

POST/residential/services/{svc_id}/subusers/{subuser_id}/generate-proxy-list

Generate sub-user proxy list

Builds ready-to-use proxy strings for this sub-user — the exact strings you give your own customer. Byte-identical in shape to the service-level generator, so your customer cannot tell which endpoint minted them.

Auth · Bearer

Path parameters

svc_idstringrequired
The residential service id, from GET /residential/services.
subuser_idstringrequired
The sub-user id, e.g. rsub_42.

Body parameters

countintegeroptional
How many strings to generate. 1–1000, default 10.
protocolstringoptional
"http" (default), "socks5", or "mix". "mix" is Standard tier only — one port answering both HTTP and SOCKS5; requesting it on Premium returns 400.
formatstringoptional
Output layout, e.g. hostname:port:username:password.
portintegeroptional
Specific gateway port to use. Must be one of the ports published for that protocol — Premium accepts 102 HTTP and 102 SOCKS5 ports, Standard 111 HTTP, 112 SOCKS5, and 5555 for "mix". Defaults to the tier's rotating or sticky port based on `session` (5555 for "mix").
countrystringoptional
ISO country code(s), comma-separated.
citystringoptional
City to target. Requires exactly ONE `country` — with a comma-separated multi-country value the city is dropped. Available on BOTH tiers; discover valid names with `GET /residential/services/{svc_id}/access?country=US` (Premium carries far more cities than Standard). Spaces are removed, so "Los angeles" is sent as `LosAngeles`.
ispstringoptional
ASN to target, e.g. `7922` for Comcast. Requires exactly ONE `country`, same as `city`, and combines with it to pin both (Comcast in Chicago). Premium accepts an AS number or a provider name; Standard expects an AS number. There is no ASN discovery endpoint — supply the AS number yourself.
sessionstringoptional
rotating or sticky. Default rotating.
session_ttlstringoptional
Sticky session lifetime, e.g. 10m, 1h.
ipv4booleanoptional
Standard tier only: restrict to the IPv4-only pool. Default true.
streamingbooleanoptional
Premium tier only: use the high-end streaming pool. Default false.
directbooleanoptional
Premium tier only: direct connection mode, for protocols such as IMAP that dislike the default path. Default false.
skip_static_ispbooleanoptional
Premium tier only: skip static-ISP exits. Default false.
hoststringoptional
Emit a raw entry IP instead of the DNS gateway hostname. Must be one of the tier's published entry IPs, or the tier gateway name; anything else returns 400. Leave it unset unless you need it — the gateway hostname is geo-routed, so pinning an IP sends every user of that string to a single region. The available IPs come back from the sub-user credentials endpoint as `entry_ips`.

RequestPOST /residential/services/{svc_id}/subusers/{subuser_id}/generate-proxy-list

curl -X POST "https://api.proxywing.com/v1/residential/services/{svc_id}/subusers/{subuser_id}/generate-proxy-list" \
  -H "Authorization: Bearer pk_live_XXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{"count":3,"protocol":"http","session":"rotating","country":"US"}'

Response200 · application/json

{
  "gateway": "premium.proxywing.com",
  "port": 54321,
  "protocol": "http",
  "count": 3,
  "proxies": [
    "premium.proxywing.com:54321:uexxjq9gp4xn:MCCk99K80AtGEPY2_country-US"
  ]
}