How do I authenticate with the CleanProxies API?

Send your API key in the Authorization header as a Bearer token (Authorization: Bearer cp_live_...); the x-api-key header works too. Keys are created in the dashboard under Reseller Program > Settings and must stay on your server.

How do I get access to the Reseller API?

Create a CleanProxies account and add a $500 opening balance, which unlocks reseller pricing and API keys. Our team can also approve accounts directly; contact sales to talk about volume.

Is there an OpenAPI specification?

Yes. An OpenAPI 3.1 description of every endpoint is published at https://www.cleanproxies.com/openapi.json, ready for Postman, Swagger UI, code generators and AI agents.

What are the API rate limits?

Limits are per API key per minute: 120 read requests, 60 quotes, 20 writes (orders, renewals, top-ups) and 30 proxy and server actions. Every response carries X-RateLimit headers, and a 429 tells you when to retry.

Can AI agents use the CleanProxies API?

Yes. The API is plain JSON over HTTPS with an OpenAPI 3.1 spec, so AI agents and MCP tools can quote, order and fetch proxy lists on their own, then use the proxies for browsing and scraping.

Developers

Reseller API documentation

The CleanProxies Reseller API v1 is a REST API to buy, deliver and manage ISP proxies (as low as $0.75/IP), rotating residential and mobile proxies, VPS and bare-metal servers from your own code, paid from your account balance.

Create an account Reseller Program

Quick start

Base URL: https://www.cleanproxies.com/api/v1. Every request is JSON over HTTPS, authenticated with an API key.

1
Open a reseller account
Create a CleanProxies account and add a $500 opening balance. It unlocks reseller pricing and API keys, and every API order is paid from it.
2
Create an API key
In the dashboard, open Reseller Program > Settings and create a key. It starts with cp_live_ and is shown once; keep it on your server.
3
Make your first call
curl
1curl "https://www.cleanproxies.com/api/v1/account" \
2 -H "Authorization: Bearer $CLEANPROXIES_API_KEY"
4
Quote, order and fetch your proxies
POST /v1/quote checks price and stock, POST /v1/orders places the order, and GET /v1/orders/{id}?wait=25 returns the connection details once it is active.
curl
1curl -X POST "https://www.cleanproxies.com/api/v1/orders" \
2 -H "Authorization: Bearer $CLEANPROXIES_API_KEY" \
3 -H "Content-Type: application/json" \
4 -H "Idempotency-Key: $(uuidgen)" \
5 -d '{"product":"isp","quantity":10000,"provider":"frontier","autoRenew":true}'

Bodies are JSON (Content-Type: application/json, at most 16 KB). Unknown fields are rejected, so typos fail loudly.
Money is in integer US cents (balanceCents: 1250000 is $12,500.00) and times are ISO 8601 in UTC.
A success response is the resource itself; lists are { data, hasMore, nextCursor } (pass nextCursor as cursor).
Every response carries an X-Request-Id header; include it when you contact support.
New orders go paid, then provisioning, then active (or failed, refunded to your balance automatically). Monthly orders run 30 days; GB never expire.

Authentication

Send your API key in the Authorization header as a Bearer token on every request (the x-api-key header is accepted too). Keys are stored as a hash, can be renamed, reset and revoked in the dashboard, and stop working within 10 seconds of being revoked. The API does not allow calls from browsers (no CORS): a key can spend your balance, so keep it on your server.

http

1Authorization: Bearer cp_live_your_key_here

2Content-Type: application/json

Products you can order

Prices, providers, configurations and OS ids are live in GET /v1/products and follow the same volume tiers as the dashboard.

Product	Order fields	Billing	Price
`isp`	quantity (5-10,000), provider	Monthly, per IP	as low as $0.75/IP
`isp-subnet`	quantity (255, 510 or 1020), provider	Monthly, per IP	from $1.19/IP
`rotating-residential`	gb (5+)	One-time, per GB, never expires	as low as $0.63/GB
`mobile`	gb (5+)	One-time, per GB, never expires	as low as $0.79/GB
`vps`	configId, osId	Monthly, per server	from $24/month
`bare-metal`	configId, osId	Monthly, per server	from $125/month

Account and catalog

Your balance, the live catalog and prices, and proxy targeting options.

GET/v1/accountGet account
GET/v1/productsList products
GET/v1/locationsList proxy locations
POST/v1/quoteGet a quote

Get account

120/min

GET/v1/account

Your account balance (what orders are paid from), the API key making the call, and your rate limits.

Request

1curl "https://www.cleanproxies.com/api/v1/account" \

2 -H "Authorization: Bearer $CLEANPROXIES_API_KEY"

Response 200

2 "id": "Xy12AbCdEf",

3 "email": "you@example.com",

4 "balanceCents": 1250000,

5 "currency": "usd",

6 "key": {

7 "id": "key_9QmT2xLp7VbRnA1c",

8 "name": "Production",

9 "prefix": "cp_live_7Hq2…x9Lm"

10 },

11 "rateLimits": {

12 "readPerMinute": 120,

13 "quotePerMinute": 60,

14 "writePerMinute": 20,

15 "actionPerMinute": 30

16 }

17}

List products

120/min

GET/v1/products

The live catalog: retail price tiers, ISP providers with availability, gateway hosts, and VPS / bare-metal configurations with their OS ids. API orders are charged reseller prices (resellerPricing): your whole volume sets the tier, not the order size. Volume is your active IPs on isp / isp-subnet, or the GB you bought in the last 30 days on rotating-residential / mobile, plus the order itself; every order is charged the tier your volume reaches, and never more than retail for that order. customUnitPriceCents, when set, is a price agreed for your account.

Request

1curl "https://www.cleanproxies.com/api/v1/products" \

2 -H "Authorization: Bearer $CLEANPROXIES_API_KEY"

Response 200

2 "data": [

3 {

4 "id": "isp",

5 "name": "ISP Proxies",

6 "billing": "monthly",

7 "unit": "ip",

8 "available": true,

9 "minQuantity": 5,

10 "maxQuantity": 10000,

11 "tiers": [

12 {

13 "minQuantity": 5000,

14 "unitPriceCents": 84

15 },

16 {

17 "minQuantity": 10000,

18 "unitPriceCents": 75

19 }

20 ],

21 "resellerPricing": {

22 "basis": "active_ips",

23 "volume": 340,

24 "customUnitPriceCents": null,

25 "tiers": [

26 {

27 "minVolume": 1,

28 "unitPriceCents": 129

29 },

30 {

31 "minVolume": 1000,

32 "unitPriceCents": 110

33 },

34 {

35 "minVolume": 2500,

36 "unitPriceCents": 100

37 },

38 {

39 "minVolume": 5000,

40 "unitPriceCents": 90

41 },

42 {

43 "minVolume": 10000,

44 "unitPriceCents": 80

45 }

46 ]

47 },

48 "defaultProvider": "frontier",

49 "providers": [

50 {

51 "key": "frontier",

52 "name": "Frontier",

53 "country": "US",

54 "available": true

55 }

56 ]

57 },

58 {

59 "id": "rotating-residential",

60 "name": "Rotating Residential",

61 "billing": "one_time",

62 "unit": "gb",

63 "available": true,

64 "minQuantity": 5,

65 "maxQuantity": 100000,

66 "tiers": [

67 {

68 "minQuantity": 5000,

69 "unitPriceCents": 74

70 },

71 {

72 "minQuantity": 10000,

73 "unitPriceCents": 63

74 }

75 ],

76 "gateway": {

77 "host": "resipro.cleanproxies.com",

78 "port": 5555

79 }

80 },

81 {

82 "id": "vps",

83 "name": "VPS",

84 "billing": "monthly",

85 "unit": "config",

86 "available": true,

87 "location": "Virginia, USA",

88 "defaultConfig": "4x8",

89 "defaultOs": "ubuntu",

90 "configs": [

91 {

92 "id": "4x8",

93 "label": "4 vCPU / 8 GB",

94 "priceCents": 2400,

95 "available": true,

96 "specs": [

97 "4 vCPU",

98 "8 GB RAM"

99 ]

100 }

101 ],

102 "os": [

103 {

104 "id": "ubuntu",

105 "name": "Ubuntu 24.04"

106 }

107 ]

108 }

109 ]

110}

List proxy locations

30/min

GET/v1/locations

Countries, and for one country its regions, cities and ASNs, for generating rotating residential or mobile proxies. Region and city targeting are rotating residential only.

Parameter	In	Type	Description
`product`	query	`string`	rotating-residential (default) or mobile
`country`	query	`string`	ISO 3166 alpha-2 code; adds regions, cities and ASNs

Request

1curl "https://www.cleanproxies.com/api/v1/locations?product=rotating-residential&country=us" \

2 -H "Authorization: Bearer $CLEANPROXIES_API_KEY"

Response 200

2 "product": "rotating-residential",

3 "cityTargeting": true,

4 "countries": [

5 {

6 "code": "us",

7 "name": "United States",

8 "hasAsns": true

9 }

10 ],

11 "country": "us",

12 "regions": [

13 {

14 "code": "california",

15 "name": "California"

16 }

17 ],

18 "cities": [

19 {

20 "code": "los_angeles",

21 "name": "Los Angeles",

22 "region": "california"

23 }

24 ],

25 "citiesTruncated": false,

26 "asns": [

27 {

28 "code": "7922",

29 "name": "Comcast"

30 }

31 ]

32}

Get a quote

60/min

POST/v1/quote

The server price for a product and configuration, whether it is in stock, and whether your balance covers it. Takes the same product fields as Create an order.

Parameter	In	Type	Description
`product *`	body	`string`	isp, isp-subnet, rotating-residential, mobile, vps or bare-metal
`quantity`	body	`integer`	isp / isp-subnet: number of IPs (isp-subnet: 255, 510 or 1020)
`provider`	body	`string`	isp / isp-subnet: provider key from List products (default: the catalog default)
`gb`	body	`integer`	rotating-residential / mobile: GB
`configId, osId`	body	`string`	vps / bare-metal: configuration and OS ids

Request

1curl -X POST "https://www.cleanproxies.com/api/v1/quote" \

2 -H "Authorization: Bearer $CLEANPROXIES_API_KEY" \

3 -H "Content-Type: application/json" \

4 -d '{"product":"isp","quantity":10000,"provider":"frontier"}'

Response 200

2 "product": "isp",

3 "planName": "ISP Proxies - Frontier",

4 "details": "10000 IPs ~ Frontier ~ United States",

5 "billing": "monthly",

6 "unitPriceCents": 75,

7 "subtotalCents": 750000,

8 "totalCents": 750000,

9 "currency": "usd",

10 "inStock": true,

11 "balanceCents": 1250000,

12 "balanceSufficient": true,

13 "shortfallCents": 0

14}

Orders

Place, list, renew and top up orders. Every order is paid from your account balance.

POST/v1/ordersCreate an order
GET/v1/ordersList orders
GET/v1/orders/{id}Get an order
POST/v1/orders/{id}/renewRenew an order
POST/v1/orders/{id}/topupTop up GB
POST/v1/orders/{id}/auto-renewSet auto-renew

Create an order

Idempotency-Key required20/min

POST/v1/orders

Places an order paid in full from your account balance; no card step. Answers 402 INSUFFICIENT_BALANCE (with shortfallCents) when the balance doesn't cover the whole price. The order starts as paid and becomes active once it is set up (seconds for rotating/mobile, up to a few minutes for ISP and servers): poll Get an order with ?wait=25. Monthly products last 30 days; renew them or set autoRenew.

Parameter	In	Type	Description
`product *`	body	`string`	isp, isp-subnet, rotating-residential, mobile, vps or bare-metal
`quantity`	body	`integer`	isp / isp-subnet: number of IPs (isp: 5-10,000; isp-subnet: 255, 510 or 1020)
`provider`	body	`string`	isp / isp-subnet: provider key (frontier, atnt, comcast, cox, rcn, tmobile, verizon, telus, ...)
`gb`	body	`integer`	rotating-residential / mobile: GB (minimum 5)
`configId`	body	`string`	vps / bare-metal: configuration id from List products
`osId`	body	`string`	vps / bare-metal: operating system id
`autoRenew`	body	`boolean`	Monthly products: renew from your balance 24 h before expiry
`customer`	body	`string`	Your customer label (a-z, 0-9, _ and -); created if new
`reference`	body	`string`	Your own reference, up to 100 characters

Request

1curl -X POST "https://www.cleanproxies.com/api/v1/orders" \

2 -H "Authorization: Bearer $CLEANPROXIES_API_KEY" \

3 -H "Content-Type: application/json" \

4 -H "Idempotency-Key: $(uuidgen)" \

5 -d '{"product":"isp","quantity":10000,"provider":"frontier","autoRenew":true,"customer":"customer-001","reference":"inv-1042"}'

Response 201

2 "id": "OcK3x9Qm2LpZt7Vb1RnA",

3 "product": "isp",

4 "type": "isp",

5 "status": "paid",

6 "planName": "ISP Proxies - Frontier",

7 "details": "10000 IPs ~ Frontier ~ United States",

8 "billing": "monthly",

9 "quantity": 10000,

10 "gb": null,

11 "provider": "frontier",

12 "country": "US",

13 "configId": null,

14 "osId": null,

15 "autoRenew": true,

16 "cardSubscription": false,

17 "createdAt": "2026-10-19T12:00:00.000Z",

18 "paidAt": "2026-10-19T12:00:01.000Z",

19 "activatedAt": null,

20 "expiresAt": null,

21 "pricing": {

22 "currency": "usd",

23 "subtotalCents": 750000,

24 "couponDiscountCents": 0,

25 "walletAppliedCents": 750000,

26 "amountDueCents": 0

27 },

28 "source": "api",

29 "customer": "customer-001",

30 "reference": "inv-1042",

31 "service": null

32}

List orders

120/min

GET/v1/orders

Your orders, newest first (dashboard and API orders alike; balance deposits are not listed). Pass nextCursor as cursor for the next page. Connection details are only on Get an order.

Parameter	In	Type	Description
`limit`	query	`integer`	1-100, default 25
`cursor`	query	`string`	nextCursor from the previous page
`product`	query	`string`	Only this product (also trial)
`status`	query	`string`	pending_payment, paid, provisioning, active, failed, abandoned, expired, cancelled or refunded
`customer`	query	`string`	Only orders tagged with this customer

Request

1curl "https://www.cleanproxies.com/api/v1/orders?status=active&limit=2" \

2 -H "Authorization: Bearer $CLEANPROXIES_API_KEY"

Response 200

2 "data": [

3 {

4 "id": "OcK3x9Qm2LpZt7Vb1RnA",

5 "product": "isp",

6 "type": "isp",

7 "status": "active",

8 "planName": "ISP Proxies - Frontier",

9 "details": "10000 IPs ~ Frontier ~ United States",

10 "billing": "monthly",

11 "quantity": 10000,

12 "gb": null,

13 "provider": "frontier",

14 "country": "US",

15 "configId": null,

16 "osId": null,

17 "autoRenew": true,

18 "cardSubscription": false,

19 "createdAt": "2026-10-19T12:00:00.000Z",

20 "paidAt": "2026-10-19T12:00:01.000Z",

21 "activatedAt": "2026-10-19T12:00:40.000Z",

22 "expiresAt": "2026-11-18T12:00:40.000Z",

23 "pricing": {

24 "currency": "usd",

25 "subtotalCents": 750000,

26 "couponDiscountCents": 0,

27 "walletAppliedCents": 750000,

28 "amountDueCents": 0

29 },

30 "source": "api",

31 "customer": "customer-001",

32 "reference": "inv-1042"

33 }

34 ],

35 "hasMore": false,

36 "nextCursor": null

37}

Get an order

120/min

GET/v1/orders/{id}

One order with its connection details in `service` once it is active: ISP username/password (the IP list is at /proxies), the rotating/mobile gateway and password, or the server IP and login. `wait` long-polls up to that many seconds until the order is active or has ended.

Parameter	In	Type	Description
`id *`	path	`string`	Order id
`wait`	query	`integer`	0-25 seconds to wait for the order to become active

Request

1curl "https://www.cleanproxies.com/api/v1/orders/OcK3x9Qm2LpZt7Vb1RnA?wait=25" \

2 -H "Authorization: Bearer $CLEANPROXIES_API_KEY"

Response 200

2 "id": "OcK3x9Qm2LpZt7Vb1RnA",

3 "product": "isp",

4 "type": "isp",

5 "status": "active",

6 "planName": "ISP Proxies - Frontier",

7 "details": "10000 IPs ~ Frontier ~ United States",

8 "billing": "monthly",

9 "quantity": 10000,

10 "gb": null,

11 "provider": "frontier",

12 "country": "US",

13 "configId": null,

14 "osId": null,

15 "autoRenew": true,

16 "cardSubscription": false,

17 "createdAt": "2026-10-19T12:00:00.000Z",

18 "paidAt": "2026-10-19T12:00:01.000Z",

19 "activatedAt": "2026-10-19T12:00:40.000Z",

20 "expiresAt": "2026-11-18T12:00:40.000Z",

21 "pricing": {

22 "currency": "usd",

23 "subtotalCents": 750000,

24 "couponDiscountCents": 0,

25 "walletAppliedCents": 750000,

26 "amountDueCents": 0

27 },

28 "source": "api",

29 "customer": "customer-001",

30 "reference": "inv-1042",

31 "service": {

32 "type": "isp",

33 "authType": "user",

34 "username": "cpuser",

35 "password": "s3cr3tPass",

36 "authorizedIps": [],

37 "quantity": 10000,

38 "proxiesEndpoint": "/api/v1/orders/OcK3x9Qm2LpZt7Vb1RnA/proxies"

39 }

40}

Renew an order

Idempotency-Key required20/min

POST/v1/orders/{id}/renew

Adds one 30-day period to an active monthly order (isp, isp-subnet, vps, bare-metal) at your current reseller price, paid from your balance. Allowed until 24 hours after expiry. Orders billed by a card subscription renew by themselves.

Parameter	In	Type	Description
`id *`	path	`string`	Order id

Request

1curl -X POST "https://www.cleanproxies.com/api/v1/orders/OcK3x9Qm2LpZt7Vb1RnA/renew" \

2 -H "Authorization: Bearer $CLEANPROXIES_API_KEY" \

3 -H "Content-Type: application/json" \

4 -H "Idempotency-Key: $(uuidgen)" \

5 -d '{}'

Response 200

2 "renewal": {

3 "id": "OcK4aB7Qm2LpZt7Vb1Rn",

4 "status": "applied",

5 "amountCents": 750000

6 },

7 "order": {

8 "id": "OcK3x9Qm2LpZt7Vb1RnA",

9 "product": "isp",

10 "type": "isp",

11 "status": "active",

12 "planName": "ISP Proxies - Frontier",

13 "details": "10000 IPs ~ Frontier ~ United States",

14 "billing": "monthly",

15 "quantity": 10000,

16 "gb": null,

17 "provider": "frontier",

18 "country": "US",

19 "configId": null,

20 "osId": null,

21 "autoRenew": true,

22 "cardSubscription": false,

23 "createdAt": "2026-10-19T12:00:00.000Z",

24 "paidAt": "2026-10-19T12:00:01.000Z",

25 "activatedAt": "2026-10-19T12:00:40.000Z",

26 "expiresAt": "2026-12-18T12:00:40.000Z",

27 "pricing": {

28 "currency": "usd",

29 "subtotalCents": 750000,

30 "couponDiscountCents": 0,

31 "walletAppliedCents": 750000,

32 "amountDueCents": 0

33 },

34 "source": "api",

35 "customer": "customer-001",

36 "reference": "inv-1042"

37 }

38}

Top up GB

Idempotency-Key required20/min

POST/v1/orders/{id}/topup

Adds GB to an active rotating residential or mobile order. The credentials stay the same. Priced at your reseller GB price (your GB bought in the last 30 days plus this top-up sets the tier); minimum 5 GB.

Parameter	In	Type	Description
`id *`	path	`string`	Order id
`gb *`	body	`integer`	GB to add

Request

1curl -X POST "https://www.cleanproxies.com/api/v1/orders/OcK3x9Qm2LpZt7Vb1RnA/topup" \

2 -H "Authorization: Bearer $CLEANPROXIES_API_KEY" \

3 -H "Content-Type: application/json" \

4 -H "Idempotency-Key: $(uuidgen)" \

5 -d '{"gb":250}'

Response 200

2 "topup": {

3 "id": "OcK4bC8Rn3MqAu8Wc2So",

4 "status": "applied",

5 "amountCents": 23500,

6 "gb": 250

7 },

8 "order": {

9 "id": "OcK3x9Qm2LpZt7Vb1RnA",

10 "product": "rotating-residential",

11 "status": "active",

12 "gb": 300

13 }

14}

Set auto-renew

20/min

POST/v1/orders/{id}/auto-renew

Turns automatic renewal from your balance on or off for a monthly order. Turning it off is how you cancel: the order then ends at expiresAt.

Parameter	In	Type	Description
`id *`	path	`string`	Order id
`enabled *`	body	`boolean`	true or false

Request

1curl -X POST "https://www.cleanproxies.com/api/v1/orders/OcK3x9Qm2LpZt7Vb1RnA/auto-renew" \

2 -H "Authorization: Bearer $CLEANPROXIES_API_KEY" \

3 -H "Content-Type: application/json" \

4 -d '{"enabled":false}'

Response 200

2 "id": "OcK3x9Qm2LpZt7Vb1RnA",

3 "autoRenew": false

Proxies

Proxy lists, generated rotating/mobile lines, authentication and usage of delivered orders.

GET/v1/orders/{id}/proxiesGet proxies
POST/v1/orders/{id}/authSet ISP authentication
GET/v1/orders/{id}/usageGet usage

Get proxies

30/min

GET/v1/orders/{id}/proxies

ISP / ISP subnet orders: the IP list, as ip:port:username:password (or ip:port under IP authentication). Rotating residential / mobile orders: generated proxy lines for the targeting you ask for; sticky sessions keep the same IP for ttl minutes.

Parameter	In	Type	Description
`id *`	path	`string`	Order id
`country`	query	`string`	Rotating/mobile: ISO alpha-2 code, or global (default)
`region, city`	query	`string`	Rotating residential: codes from List proxy locations (need country)
`asn`	query	`string`	Rotating/mobile: ASN such as 7922 (needs country; not with region/city)
`session`	query	`string`	rotating (default) or sticky
`ttl`	query	`integer`	Sticky session minutes, 1-1440
`count`	query	`integer`	Lines to generate, 1-1000 (default 10)
`format`	query	`string`	host:port:user:pass (default), user:pass@host:port or user:pass:host:port

Request

1curl "https://www.cleanproxies.com/api/v1/orders/OcK3x9Qm2LpZt7Vb1RnA/proxies?country=us&session=sticky&ttl=30&count=2" \

2 -H "Authorization: Bearer $CLEANPROXIES_API_KEY"

Response 200

2 "orderId": "OcK3x9Qm2LpZt7Vb1RnA",

3 "type": "gb",

4 "gateway": {

5 "host": "resipro.cleanproxies.com",

6 "port": 5555

7 },

8 "sessionType": "sticky",

9 "ttlMinutes": 30,

10 "count": 2,

11 "format": "host:port:user:pass",

12 "proxies": [

13 "resipro.cleanproxies.com:5555:pkg-res1-country-us-session-a1b2c3-ttl-30:s3cr3t",

14 "resipro.cleanproxies.com:5555:pkg-res1-country-us-session-d4e5f6-ttl-30:s3cr3t"

15 ]

16}

Set ISP authentication

30/min

POST/v1/orders/{id}/auth

Switches an ISP / ISP subnet order between username/password authentication and an IP whitelist of 1-20 IPv4 addresses.

Parameter	In	Type	Description
`id *`	path	`string`	Order id
`authType *`	body	`string`	user or ip
`ips`	body	`string[]`	authType ip: 1-20 IPv4 addresses

Request

1curl -X POST "https://www.cleanproxies.com/api/v1/orders/OcK3x9Qm2LpZt7Vb1RnA/auth" \

2 -H "Authorization: Bearer $CLEANPROXIES_API_KEY" \

3 -H "Content-Type: application/json" \

4 -d '{"authType":"ip","ips":["203.0.113.7"]}'

Response 200

2 "orderId": "OcK3x9Qm2LpZt7Vb1RnA",

3 "authType": "ip",

4 "authorizedIps": [

5 "203.0.113.7"

6 ]

Get usage

30/min

GET/v1/orders/{id}/usage

GB bought, used and left on a rotating residential or mobile order, with daily usage for the last 30 days (UTC).

Parameter	In	Type	Description
`id *`	path	`string`	Order id

Request

1curl "https://www.cleanproxies.com/api/v1/orders/OcK3x9Qm2LpZt7Vb1RnA/usage" \

2 -H "Authorization: Bearer $CLEANPROXIES_API_KEY"

Response 200

2 "orderId": "OcK3x9Qm2LpZt7Vb1RnA",

3 "limitGb": 300,

4 "usedGb": 41.27,

5 "remainingGb": 258.73,

6 "daily": [

7 {

8 "date": "2026-10-18",

9 "gb": 3.12

10 }

11 ],

12 "range": {

13 "start": "2026-09-19",

14 "end": "2026-10-19"

15 }

16}

Servers

Power state and control of VPS and bare-metal servers.

GET/v1/orders/{id}/serverGet server state
POST/v1/orders/{id}/powerPower control
POST/v1/orders/{id}/reinstallReinstall OS

Get server state

30/min

GET/v1/orders/{id}/server

Live power state of a VPS or bare-metal server: running, stopped, stopping, starting, pending, error, terminated or unknown.

Parameter	In	Type	Description
`id *`	path	`string`	Order id

Request

1curl "https://www.cleanproxies.com/api/v1/orders/OcK3x9Qm2LpZt7Vb1RnA/server" \

2 -H "Authorization: Bearer $CLEANPROXIES_API_KEY"

Response 200

2 "orderId": "OcK3x9Qm2LpZt7Vb1RnA",

3 "state": "running",

4 "ip": "198.51.100.24"

Power control

30/min

POST/v1/orders/{id}/power

Starts, stops or reboots a server. One action per server every 30 seconds (429 ACTION_COOLDOWN otherwise).

Parameter	In	Type	Description
`id *`	path	`string`	Order id
`action *`	body	`string`	start, stop or reboot

Request

1curl -X POST "https://www.cleanproxies.com/api/v1/orders/OcK3x9Qm2LpZt7Vb1RnA/power" \

2 -H "Authorization: Bearer $CLEANPROXIES_API_KEY" \

3 -H "Content-Type: application/json" \

4 -d '{"action":"reboot"}'

Response 202

2 "orderId": "OcK3x9Qm2LpZt7Vb1RnA",

3 "action": "reboot",

4 "status": "requested"

Reinstall OS

30/min

POST/v1/orders/{id}/reinstall

Reinstalls a bare-metal server with an OS from its configuration's list and answers the new login. Erases the disks. At most once every 10 minutes.

Parameter	In	Type	Description
`id *`	path	`string`	Order id
`osId *`	body	`string`	OS id from List products

Request

1curl -X POST "https://www.cleanproxies.com/api/v1/orders/OcK3x9Qm2LpZt7Vb1RnA/reinstall" \

2 -H "Authorization: Bearer $CLEANPROXIES_API_KEY" \

3 -H "Content-Type: application/json" \

4 -d '{"osId":"ubuntu"}'

Response 202

2 "orderId": "OcK3x9Qm2LpZt7Vb1RnA",

3 "status": "reinstalling",

4 "osId": "ubuntu",

5 "username": "root",

6 "password": "n3wPassw0rd"

Customers (sub-users)

Labels for your own customers. Tag orders with a customer to group and look them up; each rotating or mobile order already has its own isolated credentials.

POST/v1/usersCreate a customer
GET/v1/usersList customers
GET/v1/users/{username}Get a customer
DELETE/v1/users/{username}Delete a customer

Create a customer

20/min

POST/v1/users

Creates a customer label (201), or answers the existing one (200). Orders created with this customer are listed under it.

Parameter	In	Type	Description
`username *`	body	`string`	1-64 characters: a-z, 0-9, _ and -
`note`	body	`string`	Up to 200 characters

Request

1curl -X POST "https://www.cleanproxies.com/api/v1/users" \

2 -H "Authorization: Bearer $CLEANPROXIES_API_KEY" \

3 -H "Content-Type: application/json" \

4 -d '{"username":"customer-001","note":"Acme Ltd"}'

Response 201

2 "username": "customer-001",

3 "note": "Acme Ltd",

4 "createdAt": "2026-10-19T12:00:00.000Z",

5 "orderCount": 0

List customers

120/min

GET/v1/users

Your customer labels in alphabetical order.

Parameter	In	Type	Description
`limit`	query	`integer`	1-100, default 50
`cursor`	query	`string`	nextCursor from the previous page

Request

1curl "https://www.cleanproxies.com/api/v1/users?limit=50" \

2 -H "Authorization: Bearer $CLEANPROXIES_API_KEY"

Response 200

2 "data": [

3 {

4 "username": "customer-001",

5 "note": "Acme Ltd",

6 "createdAt": "2026-10-19T12:00:00.000Z",

7 "orderCount": 2

8 }

9 ],

10 "hasMore": false,

11 "nextCursor": null

12}

Get a customer

120/min

GET/v1/users/{username}

A customer with its latest 100 orders and totals: active orders, active ISP IPs, GB bought on active rotating/mobile orders, and active servers.

Parameter	In	Type	Description
`username *`	path	`string`	Customer label

Request

1curl "https://www.cleanproxies.com/api/v1/users/customer-001" \

2 -H "Authorization: Bearer $CLEANPROXIES_API_KEY"

Response 200

2 "username": "customer-001",

3 "note": "Acme Ltd",

4 "createdAt": "2026-10-19T12:00:00.000Z",

5 "orderCount": 1,

6 "summary": {

7 "activeOrders": 1,

8 "activeIps": 10000,

9 "gbPurchased": 0,

10 "activeServers": 0

11 },

12 "orders": [

13 {

14 "id": "OcK3x9Qm2LpZt7Vb1RnA",

15 "product": "isp",

16 "type": "isp",

17 "status": "active",

18 "planName": "ISP Proxies - Frontier",

19 "details": "10000 IPs ~ Frontier ~ United States",

20 "billing": "monthly",

21 "quantity": 10000,

22 "gb": null,

23 "provider": "frontier",

24 "country": "US",

25 "configId": null,

26 "osId": null,

27 "autoRenew": true,

28 "cardSubscription": false,

29 "createdAt": "2026-10-19T12:00:00.000Z",

30 "paidAt": "2026-10-19T12:00:01.000Z",

31 "activatedAt": "2026-10-19T12:00:40.000Z",

32 "expiresAt": "2026-11-18T12:00:40.000Z",

33 "pricing": {

34 "currency": "usd",

35 "subtotalCents": 750000,

36 "couponDiscountCents": 0,

37 "walletAppliedCents": 750000,

38 "amountDueCents": 0

39 },

40 "source": "api",

41 "customer": "customer-001",

42 "reference": "inv-1042"

43 }

44 ]

45}

Delete a customer

20/min

DELETE/v1/users/{username}

Deletes the label. Refused (409 CUSTOMER_HAS_ACTIVE_ORDERS) while the customer has pending or active orders. Orders themselves are never changed.

Parameter	In	Type	Description
`username *`	path	`string`	Customer label

Request

1curl -X DELETE "https://www.cleanproxies.com/api/v1/users/customer-001" \

2 -H "Authorization: Bearer $CLEANPROXIES_API_KEY"

Response 200

2 "username": "customer-001",

3 "deleted": true

Errors

Errors use the HTTP status and a stable machine code. Extra fields (such as field, or shortfallCents) sit next to the message.

Response 402

2 "error": {

3 "code": "INSUFFICIENT_BALANCE",

4 "message": "Your account balance ($1000.00) doesn't cover this ($7500.00). Add at least $6500.00 at /dashboard/balance/deposit and retry.",

5 "requestId": "req_8Zt2Lq9Xb3Vn1Ma7Kc4P",

6 "requiredCents": 750000,

7 "balanceCents": 100000,

8 "shortfallCents": 650000

9 }

10}

Code	Status	Meaning
`UNAUTHENTICATED`	401	Missing, malformed or unknown API key.
`KEY_REVOKED`	401	The key was revoked or rotated.
`ACCOUNT_BLOCKED`	403	The account is blocked or disabled.
`VALIDATION_ERROR`	400	A field is missing, has the wrong type, or is unknown (see field).
`INVALID_JSON / UNSUPPORTED_MEDIA_TYPE`	400	The body isn't a JSON object sent as application/json (415).
`INVALID_QUANTITY, BELOW_MINIMUM, INVALID_PROVIDER, INVALID_CONFIG_ID, INVALID_OS`	400	The catalog rejected the configuration.
`NOT_SUPPORTED`	400	The action doesn't apply to this product (501 for VPS reinstall).
`INSUFFICIENT_BALANCE`	402	The balance doesn't cover the whole price. requiredCents, balanceCents and shortfallCents tell you how much to add.
`NOT_FOUND`	404	No such order, customer or endpoint on your account.
`SOLD_OUT`	409	Out of stock right now.
`NOT_RENEWABLE, NOT_TOPUPABLE, SUBSCRIPTION_MANAGED, ORDER_NOT_ACTIVE`	409	The order is not in a state that allows this (some are 400).
`REQUEST_IN_PROGRESS`	409	Another money request on your account, or the same Idempotency-Key, is still running. Retry after Retry-After.
`IDEMPOTENCY_KEY_REQUIRED / IDEMPOTENCY_KEY_INVALID`	400	Send an Idempotency-Key on this POST.
`IDEMPOTENCY_MISMATCH`	422	The Idempotency-Key was used for a different request.
`RATE_LIMITED, ACTION_COOLDOWN`	429	Too many requests. Wait for Retry-After seconds.
`OUTCOME_UNKNOWN`	503	No answer in time. Retry with the same Idempotency-Key: you get the result, never a second charge.
`UPSTREAM_UNAVAILABLE, STOCK_UNAVAILABLE`	503	A provider is briefly unavailable. Retry shortly.
`INTERNAL`	500	Our error. Retry, and send us the requestId if it persists.

Rate limits and idempotency

Limits apply per API key, per minute. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (seconds); a 429 also carries Retry-After. Order, renewal and top-up requests run one at a time per account; a second one waits up to 10 seconds, then gets 409 REQUEST_IN_PROGRESS.

Class	Requests per minute	Endpoints
read	120	GET account, products, orders, users
quote	60	POST quote
write	20	POST orders, renew, topup, auto-renew, users; DELETE users
action	30	locations, proxies, auth, usage, server, power, reinstall

Send an Idempotency-Key header (1-100 letters, digits, - and _; a UUID is ideal) to make a POST safe to retry. It is required on create order, renew and top-up. For 24 hours, retrying with the same key returns the original response with Idempotent-Replayed: true instead of charging again; reusing a key for a different request returns 422. After a 503 OUTCOME_UNKNOWN, retry with the same key: you get the order that was placed, or it is placed once.

OpenAPI specification

The full API is described in OpenAPI 3.1 at https://www.cleanproxies.com/openapi.json. Import it into Postman, Insomnia or Swagger UI, generate a client in your language, or hand it to an AI agent as a tool definition. Questions? Email help@cleanproxies.com, 24/7.

Reseller API FAQs

Yes. The CleanProxies Reseller API v1 is a REST API at https://www.cleanproxies.com/api/v1 that buys, delivers and manages ISP proxies, ISP subnets, rotating residential and mobile proxies, VPS and bare-metal servers from your own code. Orders are paid from your account balance and delivered instantly.

Resell the cleanest ISP proxies

Sell CleanProxies ISP proxies from $0.75/IP, residential from $0.63/GB and mobile from $0.79/GB to your own customers, with instant delivery and 24/7 support.

Create an account Talk to sales

Reseller API documentation

Quick start

Open a reseller account

Create an API key

Make your first call

Quote, order and fetch your proxies

Authentication

Products you can order

Account and catalog

Get account

List products

List proxy locations

Get a quote

Orders

Create an order

List orders

Get an order

Renew an order

Top up GB

Set auto-renew

Proxies

Get proxies

Set ISP authentication

Get usage

Servers

Get server state

Power control

Reinstall OS

Customers (sub-users)

Create a customer

List customers

Get a customer

Delete a customer

Errors

Rate limits and idempotency

OpenAPI specification

Reseller API FAQs

Resell the cleanest ISP proxies