Sub-Users

A sub-user is a residential proxy account for one of your customers: a username, a password and a data limit taken from your pool. Your customer connects with these credentials as described in Proxy Access.

Data you assign to a sub-user comes out of your unassigned pool right away. The pool is tracked, not enforced, so you never get a “not enough data” error. remainingBytes just goes negative.

Method	Endpoint	What it does
`POST`	`/reseller/users`	Create a sub-user
`GET`	`/reseller/users`	List your sub-users
`GET`	`/reseller/users/:username`	Get one sub-user with live usage
`POST`	`/reseller/users/:username/data`	Add or remove data
`POST`	`/reseller/users/:username/password`	Set a new password
`DELETE`	`/reseller/users/:username`	Delete a sub-user and refund unused data

All examples read your key from the RESELLER_KEY environment variable. See Authentication.

Create a Sub-User

POST /reseller/users

Node.js
Python
cURL

Node.js

const res = await fetch("https://api.roundproxies.com/reseller/users", {
  method: "POST",
  headers: {
    "x-reseller-key": process.env.RESELLER_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ dataGB: 5, username: "acme_customer1" }),
});
console.log(await res.json());

Python

import os
import requests

res = requests.post(
    "https://api.roundproxies.com/reseller/users",
    headers={"x-reseller-key": os.environ["RESELLER_KEY"]},
    json={"dataGB": 5, "username": "acme_customer1"},
)
print(res.json())

cURL

curl -X POST https://api.roundproxies.com/reseller/users \
  -H "x-reseller-key: $RESELLER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dataGB": 5, "username": "acme_customer1"}'

Request Parameters

Parameter	Type	Default	Description
`dataGB`	`number`	required	Data limit in GB, from `0.01` to `10000`, up to two decimals.
`username`	`string`	generated	6 to 32 characters, lowercase `a-z 0-9 _ -`. Must be unique across all accounts.
`password`	`string`	generated	8 to 64 characters, `a-z A-Z 0-9 _ -`.

Response

{
  "message": "Sub-user created",
  "subUser": {
    "username": "acme_customer1",
    "password": "9f8e7d6c5b4a...",
    "dataBytes": 5368709120,
    "dataGB": 5,
    "createdAt": "..."
  },
  "remainingBytes": 59055800320
}

Field	Type	Description
`subUser.username`	`string`	The proxy username.
`subUser.password`	`string`	The proxy password. You can get it again later, so you don’t have to store it.
`subUser.dataBytes`	`number`	Data limit in bytes.
`subUser.dataGB`	`number`	Data limit in GB.
`remainingBytes`	`number`	Your unassigned pool after this change. Can be negative.

Errors

Username taken (409)

The message is Username "x" is already taken. Pick another one. Choose a different username, or leave it out to get a generated one.

Proxy network rejected the account (502)

Nothing was created and no data was taken. You can safely retry.

Invalid request (400)

A field breaks the rules above. message is a list of strings, one for each problem.

List Sub-Users

GET /reseller/users

Node.js
Python
cURL

Node.js

const res = await fetch(
  "https://api.roundproxies.com/reseller/users?page=1&limit=25",
  { headers: { "x-reseller-key": process.env.RESELLER_KEY } },
);
console.log(await res.json());

Python

import os
import requests

res = requests.get(
    "https://api.roundproxies.com/reseller/users",
    headers={"x-reseller-key": os.environ["RESELLER_KEY"]},
    params={"page": 1, "limit": 25},
)
print(res.json())

cURL

curl "https://api.roundproxies.com/reseller/users?page=1&limit=25" \
  -H "x-reseller-key: $RESELLER_KEY"

Query Parameters

Parameter	Type	Default	Description
`page`	`number`	first page	Page number.
`limit`	`number`	`25`	Sub-users per page, at most `100`.
`includeUsage`	`boolean`	`false`	Add each sub-user’s live usage. Slower, because every row is looked up.

Response

{
  "subUsers": [
    {
      "username": "acme_customer1",
      "password": "...",
      "dataBytes": 5368709120,
      "dataGB": 5,
      "createdAt": "...",
      "usage": {
        "used": "1.2 GB",
        "total": "5 GB",
        "rawUsed": 1288490188,
        "rawTotal": 5368709120
      }
    }
  ],
  "total": 8,
  "page": 1,
  "limit": 25
}

Field	Type	Description
`subUsers`	`array`	Your sub-users on this page, with their credentials.
`subUsers[].usage`	`object` or `null`	Only with `includeUsage=true`. `null` with a `usageError` note if that row’s lookup failed. Treat `null` as unknown, not zero.
`total`	`number`	Number of sub-users on your account.
`page`, `limit`	`number`	The page you asked for.

Get One Sub-User

GET /reseller/users/:username Returns one sub-user with live usage. Use it to see how much data a customer has used.

Node.js
Python
cURL

Node.js

const res = await fetch(
  "https://api.roundproxies.com/reseller/users/acme_customer1",
  { headers: { "x-reseller-key": process.env.RESELLER_KEY } },
);
console.log(await res.json());

Python

import os
import requests

res = requests.get(
    "https://api.roundproxies.com/reseller/users/acme_customer1",
    headers={"x-reseller-key": os.environ["RESELLER_KEY"]},
)
print(res.json())

cURL

curl https://api.roundproxies.com/reseller/users/acme_customer1 \
  -H "x-reseller-key: $RESELLER_KEY"

Response

{
  "subUser": {
    "username": "acme_customer1",
    "password": "...",
    "dataBytes": 5368709120,
    "dataGB": 5
  },
  "usage": {
    "used": "1.2 GB",
    "total": "5 GB",
    "rawUsed": 1288490188,
    "rawTotal": 5368709120
  }
}

Field	Type	Description
`usage.rawUsed`	`number`	Bytes used so far.
`usage.rawTotal`	`number`	Data limit in bytes. When `rawUsed` reaches it, the account stops working until you add data.
`usage.used`, `usage.total`	`string`	The same values, formatted for display.

If usage can’t be looked up, you still get the credentials, with "usage": null and a usageError note.

Change Data

POST /reseller/users/:username/data Send a GB amount to add or remove. A positive number adds data from your pool. A negative number takes unused data back.

Node.js
Python
cURL

Node.js

const res = await fetch(
  "https://api.roundproxies.com/reseller/users/acme_customer1/data",
  {
    method: "POST",
    headers: {
      "x-reseller-key": process.env.RESELLER_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ dataGB: 10 }),
  },
);
console.log(await res.json());

Python

import os
import requests

res = requests.post(
    "https://api.roundproxies.com/reseller/users/acme_customer1/data",
    headers={"x-reseller-key": os.environ["RESELLER_KEY"]},
    json={"dataGB": 10},
)
print(res.json())

cURL

curl -X POST https://api.roundproxies.com/reseller/users/acme_customer1/data \
  -H "x-reseller-key: $RESELLER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dataGB": 10}'

Request Parameters

Parameter	Type	Default	Description
`dataGB`	`number`	required	GB to add (positive) or remove (negative). Up to 10,000 either way, up to two decimals. Zero is not allowed.

Response

{
  "message": "Added 10GB",
  "username": "acme_customer1",
  "dataBytes": 16106127360,
  "remainingBytes": 42949672960
}

Field	Type	Description
`dataBytes`	`number`	The sub-user’s new data limit in bytes.
`remainingBytes`	`number`	Your unassigned pool after this change.

Errors

Too much removed, or zero (400)

An account’s data can’t go below zero, and you can only take back data that hasn’t been used. Lower the amount.

Proxy network rejected the change (502)

Nothing was charged or changed. You can safely retry.

Change Password

POST /reseller/users/:username/password Sets a new password. Send the password you want, or an empty body to get a strong generated one. The username stays the same.

Node.js
Python
cURL

Node.js

const res = await fetch(
  "https://api.roundproxies.com/reseller/users/acme_customer1/password",
  {
    method: "POST",
    headers: {
      "x-reseller-key": process.env.RESELLER_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ password: "NewSecret_2026" }),
  },
);
console.log(await res.json());

Python

import os
import requests

res = requests.post(
    "https://api.roundproxies.com/reseller/users/acme_customer1/password",
    headers={"x-reseller-key": os.environ["RESELLER_KEY"]},
    json={"password": "NewSecret_2026"},
)
print(res.json())

cURL

curl -X POST https://api.roundproxies.com/reseller/users/acme_customer1/password \
  -H "x-reseller-key: $RESELLER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"password": "NewSecret_2026"}'

Request Parameters

Parameter	Type	Default	Description
`password`	`string`	generated	8 to 64 characters, `a-z A-Z 0-9 _ -`.

Response

{
  "message": "Password changed. The new password is accepted by the proxy within about 60 seconds; open connections are not affected.",
  "subUser": {
    "username": "acme_customer1",
    "password": "NewSecret_2026",
    "dataBytes": 5368709120,
    "dataGB": 5,
    "createdAt": "..."
  }
}

The new password works within about 60 seconds. Until then the old password keeps working, and open connections are never cut. You can give your customer the new password right away.

Errors

Invalid password (400)

The password doesn’t follow the rules above.

Change already in progress (409)

Another change to this sub-user is still running. Try again in a moment.

Proxy network rejected the change (502)

Nothing changed. You can safely retry.

Delete a Sub-User

DELETE /reseller/users/:username Ends a customer’s access and returns their unused data to your pool.

Node.js
Python
cURL

Node.js

const res = await fetch(
  "https://api.roundproxies.com/reseller/users/acme_customer1",
  {
    method: "DELETE",
    headers: { "x-reseller-key": process.env.RESELLER_KEY },
  },
);
console.log(await res.json());

Python

import os
import requests

res = requests.delete(
    "https://api.roundproxies.com/reseller/users/acme_customer1",
    headers={"x-reseller-key": os.environ["RESELLER_KEY"]},
)
print(res.json())

cURL

curl -X DELETE https://api.roundproxies.com/reseller/users/acme_customer1 \
  -H "x-reseller-key: $RESELLER_KEY"

Response

{
  "username": "acme_customer1",
  "refundedBytes": 4080218931,
  "refundedGB": 3.8
}

Field	Type	Description
`refundedBytes`	`number`	Unused data returned to your pool, in bytes.
`refundedGB`	`number`	The same amount in GB.

What happens, in order:

The account’s unused data is removed, so the credentials stop working.
The unused data goes back to your unassigned pool.
The sub-user is removed from your account. Its usage stays in your usage history.

You can’t undo a deletion. To give the same customer access again, create a new sub-user, preferably with a new username, because the old account still exists in an emptied state.

Errors

Proxy network unreachable (502)

The deletion stopped and nothing changed. The credentials still work and nothing was refunded. Try again later.

Errors on Every Endpoint

Sub-user not found (404)

The message is Sub-user "x" not found. Check the username. You can only see your own sub-users.

Invalid or rotated key (401)

See Authentication.

Limits

Data per sub-user: 0.01 to 10000 GB when you create it, changed by up to 10,000 GB per call.
Page size: at most 100 sub-users per list request.
Password changes: take effect within about 60 seconds.
Used data: can’t be refunded, by a data change or by a deletion.

Proxy Access

How your customers connect with a sub-user’s credentials.

Usage History

Usage over time for your pool and for each sub-user.

Getting Started

Residential Proxies

ISP Proxies

Datacenter Proxies

Reseller

Create a Sub-User

Request Parameters

Response

Errors

List Sub-Users

Query Parameters

Response

Get One Sub-User

Response

Change Data

Request Parameters

Response

Errors

Change Password

Request Parameters

Response

Errors

Delete a Sub-User

Response

Errors

Errors on Every Endpoint

Limits

Proxy Access

Usage History

Create a Sub-User

Request Parameters

Response

Errors

List Sub-Users

Query Parameters

Response

Get One Sub-User

Response

Change Data

Request Parameters

Response

Errors

Change Password

Request Parameters

Response

Errors

Delete a Sub-User

Response

Errors

Errors on Every Endpoint

Limits

Related

Proxy Access

Usage History