Browse endpoints

ProxyWing Developer API

Residential

Buy residential traffic per GB, top up existing plans, pull usage reports and build proxy lists.

GET/residential/products

List residential tiers

Returns the residential proxy tiers available for purchase. Residential traffic is sold per gigabyte; bulk-volume discounts apply automatically at checkout.

Auth · Bearer

RequestGET /residential/products

curl -X GET "https://api.proxywing.com/v1/residential/products" \
  -H "Authorization: Bearer pk_live_XXXXXXXX"

Response200 · application/json

{
  "tiers": [
    {
      "tier": "premium",
      "per_gb": 6
    },
    {
      "tier": "standard",
      "per_gb": 2.5
    }
  ]
}

POST/residential/orders

Order residential traffic

Purchases residential proxy traffic (in GB) on the chosen tier using the account balance. This is a one-time purchase — there is no billing cycle or recurring charge; the traffic stays on the service until used. The invoice total is computed by billing — bulk-volume discounts are applied automatically, so larger orders can cost less than gb × per_gb. Once paid, the service provisions immediately and appears in GET /residential/services. Supply an Idempotency-Key header so retries never double-charge.

Auth · BearerIdempotency-Key

Body parameters

tierstringrequired
"premium" or "standard", from GET /residential/products.
gbintegerrequired
Gigabytes of traffic to purchase (1–1000).
promo_codestringoptional
Optional promo code. Only percentage-discount promo codes under 100% off apply via the API (a code that would zero the total is rejected).

RequestPOST /residential/orders

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

Response200 · application/json

{
  "order_id": "ord_100003",
  "invoice_id": "inv_200004",
  "tier": "standard",
  "gb": 5,
  "status": "paid"
}

POST/residential/services/{svc_id}/top-up

Add bandwidth to a service

Adds GB of traffic to an EXISTING residential service — no new order or new credentials, the extra traffic lands on the same service. An invoice is created for the added GB (bulk-volume discounts apply, so larger top-ups cost less per GB) and, if the balance covers it, paid automatically and the traffic is credited immediately. If the balance is short the invoice stays open (awaiting_payment) and can be settled from the dashboard. Supply an Idempotency-Key header so retries never double-buy.

Auth · BearerIdempotency-Key

Path parameters

svc_idstringrequired
The residential service id, e.g. resi_100001, from GET /residential/services.

Body parameters

gbintegerrequired
Gigabytes of traffic to add (1–10000).

RequestPOST /residential/services/{svc_id}/top-up

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

Response200 · application/json

{
  "service_id": "resi_100001",
  "gb_added": 5,
  "old_gb": 3,
  "new_gb": 8,
  "invoice_id": "inv_200020",
  "total": 11.25,
  "status": "paid"
}

GET/residential/services

List residential services

Returns every active residential service on the account, with its tier and the gateway hostname it connects through.

Auth · Bearer

RequestGET /residential/services

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

Response200 · application/json

{
  "services": [
    {
      "id": "resi_100001",
      "tier": "standard",
      "status": "active",
      "gateway": "quality.proxywing.com"
    },
    {
      "id": "resi_100002",
      "tier": "premium",
      "status": "active",
      "gateway": "premium.proxywing.com"
    }
  ]
}

GET/residential/services/{svc_id}/credentials

Get connection credentials

Returns the gateway, available ports, and the username/password for a residential service. targeting_field tells you which credential carries geo-targeting and session tokens when you build proxy strings by hand — use POST /residential/services/{svc_id}/generate-proxy-list to have them built for you.

Auth · Bearer

Path parameters

svc_idstringrequired
The service id, e.g. resi_100001, from GET /residential/services.

RequestGET /residential/services/{svc_id}/credentials

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

Response200 · application/json

{
  "id": "resi_100001",
  "tier": "standard",
  "gateway": "quality.proxywing.com",
  "http_ports": [
    8888,
    7000,
    7001,
    7002,
    7003,
    7004,
    7005
  ],
  "socks5_ports": [
    1080,
    6000,
    6001,
    6002,
    6003,
    6004,
    6005
  ],
  "username": "pkg-private2",
  "password": "sample_password",
  "targeting_field": "username"
}

GET/residential/services/{svc_id}/traffic

Get traffic usage

Returns the traffic balance for a residential service in gigabytes. Fields not tracked for a given tier are null.

Auth · Bearer

Path parameters

svc_idstringrequired
The service id, e.g. resi_100001.

RequestGET /residential/services/{svc_id}/traffic

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

Response200 · application/json

{
  "tier": "standard",
  "total_gb": 20,
  "used_gb": 1.21,
  "available_gb": 18.79
}

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

Get a usage report

Returns per-hostname traffic usage for a residential service over a date window. Values are in the requested unit; total is the sum across all rows.

Auth · Bearer

Path parameters

svc_idstringrequired
The service id, e.g. resi_100001.

Query parameters

date_fromstringrequired
Start date, YYYY-MM-DD.
date_tostringrequired
End date, YYYY-MM-DD.
unitstringoptional
Measurement unit for the data values: "B", "KB", "MB" or "GB" (default GB).

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

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

Response200 · application/json

{
  "tier": "standard",
  "date_from": "2026-06-01",
  "date_to": "2026-07-01",
  "unit": "GB",
  "total": 3.42,
  "rows": [
    {
      "date": "2026-06-15",
      "hostname": "example.com",
      "data": 2.1,
      "requests": 1840
    },
    {
      "date": "2026-06-16",
      "hostname": "api.example.com",
      "data": 1.32,
      "requests": 910
    }
  ]
}

GET/residential/access

List countries & cities

Returns the geo-targeting options for a tier: every available country, or — when country is supplied — the cities available inside it. Use the returned codes in generate-proxy-list.

Auth · Bearer

Query parameters

tierstringrequired
"premium" or "standard".
countrystringoptional
ISO country code, e.g. US. When set, returns that country's cities instead of the country list.

RequestGET /residential/access

curl -X GET "https://api.proxywing.com/v1/residential/access" \
  -H "Authorization: Bearer pk_live_XXXXXXXX"

Response200 · application/json

{
  "tier": "premium",
  "countries": [
    {
      "code": "US",
      "name": "United States"
    },
    {
      "code": "GB",
      "name": "United Kingdom"
    },
    {
      "code": "DE",
      "name": "Germany"
    }
  ]
}

GET/residential/services/{svc_id}/auto-topup

Get auto-topup settings

Returns the auto-topup configuration for a residential service. When enabled, the account buys more traffic automatically once the remaining balance falls below the threshold.

Auth · Bearer

Path parameters

svc_idstringrequired
The service id, e.g. resi_100001.

RequestGET /residential/services/{svc_id}/auto-topup

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

Response200 · application/json

{
  "service_id": "resi_100001",
  "enabled": true,
  "threshold_gb": 2,
  "amount_gb": 5,
  "payment_source": "balance",
  "last_topup_at": null
}

PUT/residential/services/{svc_id}/auto-topup

Set auto-topup

Enables or disables auto-topup for a residential service. When enabling, both threshold_gb and amount_gb are required and top-ups are paid from the account balance. (Card-funded auto-topup is configured from the dashboard.)

Auth · Bearer

Path parameters

svc_idstringrequired
The service id, e.g. resi_100001.

Body parameters

enabledbooleanrequired
true to enable auto-topup, false to disable.
threshold_gbnumberoptional
Top up when remaining traffic drops below this many GB (1–10000). Required when enabling.
amount_gbnumberoptional
How many GB to buy each time (1–10000). Required when enabling.

RequestPUT /residential/services/{svc_id}/auto-topup

curl -X PUT "https://api.proxywing.com/v1/residential/services/{svc_id}/auto-topup" \
  -H "Authorization: Bearer pk_live_XXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true,"threshold_gb":2,"amount_gb":5}'

Response200 · application/json

{
  "service_id": "resi_100001",
  "enabled": true,
  "threshold_gb": 2,
  "amount_gb": 5,
  "payment_source": "balance",
  "last_topup_at": null
}

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

Generate a proxy list

Builds ready-to-use proxy strings for a residential service with the geo-targeting and session behaviour you specify. Rotating sessions get a new exit IP on every request; sticky sessions keep the same exit IP for the session TTL. This endpoint only formats credentials — it never charges the account.

Auth · Bearer

Path parameters

svc_idstringrequired
The service id, e.g. resi_100001.

Body parameters

countintegeroptional
Number of proxy strings to generate, 1–1000. Default 10.
protocolstringoptional
"http" (default) or "socks5".
formatstringoptional
Output format. One of "hostname:port:username:password" (default), "hostname:port@username:password", "username:password@hostname:port", "username:password:hostname:port".
portintegeroptional
Specific gateway port to use. Defaults to the tier's rotating or sticky port based on `session`.
countrystringoptional
ISO country code(s) to target, e.g. "US" or "US,GB" for a multi-country pool. Omit for random.
citystringoptional
City to target (single-country only), from GET /residential/access.
ispstringoptional
ISP / ASN to target (single-country only).
sessionstringoptional
"rotating" (default) or "sticky".
session_ttlstringoptional
How long a sticky session keeps its exit IP, e.g. "30s", "10m", "2h", "1d".
ipv4booleanoptional
Standard tier only: restrict to the IPv4-only pool. Default true.
streamingbooleanoptional
Premium tier only: use the high-end streaming pool. Default false.

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

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

Response200 · application/json

{
  "gateway": "quality.proxywing.com",
  "port": 8888,
  "protocol": "http",
  "count": 2,
  "proxies": [
    "quality.proxywing.com:8888:pkg-private2-pool-onlyipv4-country-US-session-a1b2c3d4-ttl-10:sample_password",
    "quality.proxywing.com:8888:pkg-private2-pool-onlyipv4-country-US-session-e5f6g7h8-ttl-10:sample_password"
  ]
}