> ## Documentation Index
> Fetch the complete documentation index at: https://docs.roundproxies.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sub-Users

> Create, list, and top up the gateway accounts you hand to your customers.

A sub-user is a gateway account belonging to one of your customers: a username, a password, and a data limit drawn from your pool. Creating one debits your unassigned data immediately.

## Creating a sub-user

### POST /reseller/users

```bash cURL theme={null}
curl -X POST https://api.roundproxies.com/reseller/users \
  -H "x-reseller-key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{"dataGB": 5, "username": "customer_0001"}'
```

### Request Fields

| Field      | Required | Rules                                                                                          |
| ---------- | -------- | ---------------------------------------------------------------------------------------------- |
| `dataGB`   | yes      | Whole GB, 1–10,000. Must not exceed your unassigned data.                                      |
| `username` | no       | 6–32 chars, lowercase `a-z 0-9 _ -`. Auto-generated if omitted. Usernames are globally unique. |
| `password` | no       | 8–64 chars, `a-z A-Z 0-9 _ -`. Auto-generated if omitted.                                      |

**200 OK**

```json theme={null}
{
  "message": "Sub-user created",
  "subUser": {
    "username": "customer_0001",
    "password": "9f8e7d6c...",
    "dataBytes": 5368709120,
    "dataGB": 5,
    "createdAt": "..."
  },
  "remainingBytes": 1073741824
}
```

<Note>
  Credentials stay retrievable from the list and detail endpoints. This is not a one-time reveal, so you don't have to store the password yourself.
</Note>

### Errors

| Status | Meaning                                                                               |
| ------ | ------------------------------------------------------------------------------------- |
| `400`  | Not enough unassigned data. The message includes your remaining balance.              |
| `409`  | Username already taken — pick another.                                                |
| `502`  | The gateway temporarily rejected the request. **Nothing was charged — retry safely.** |

## Listing your sub-users

### GET /reseller/users

Paginated. Accepts `page` and `limit` (max `100`).

```bash cURL theme={null}
curl "https://api.roundproxies.com/reseller/users?page=1&limit=25" \
  -H "x-reseller-key: $KEY"
```

Add `includeUsage=true` to include each sub-user's **live consumption** from the gateway. This costs one gateway lookup per row, so the request gets slower as the page grows — use it for dashboard views, not high-frequency polling.

**200 OK**

```json theme={null}
{
  "subUsers": [
    {
      "username": "customer_0001",
      "password": "9f8e7d6c...",
      "dataBytes": 5368709120,
      "dataGB": 5,
      "createdAt": "...",
      "usage": {
        "used": "1.2 GB",
        "total": "5.37 GB",
        "rawUsed": 1288490188,
        "rawTotal": 5368709120
      }
    }
  ],
  "total": 8,
  "page": 1,
  "limit": 25
}
```

If a live lookup fails for one row, that row comes back with `"usage": null` and a `usageError` note rather than failing the whole request. Handle `null` usage as "unknown", not as zero.

## Checking one sub-user

### GET /reseller/users/:username

A single sub-user with live usage — this is the endpoint for "how much data has this customer consumed?"

```bash cURL theme={null}
curl https://api.roundproxies.com/reseller/users/customer_0001 \
  -H "x-reseller-key: $KEY"
```

**200 OK**

```json theme={null}
{
  "subUser": {
    "username": "customer_0001",
    "password": "...",
    "dataBytes": 5368709120,
    "dataGB": 5
  },
  "usage": {
    "used": "1.2 GB",
    "total": "5.37 GB",
    "rawUsed": 1288490188,
    "rawTotal": 5368709120
  }
}
```

When `rawUsed >= rawTotal` the account is exhausted and stops working. Top it up to reactivate it.

## Topping up a sub-user

### POST /reseller/users/:username/data

```bash cURL theme={null}
curl -X POST https://api.roundproxies.com/reseller/users/customer_0001/data \
  -H "x-reseller-key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{"dataGB": 10}'
```

**200 OK**

```json theme={null}
{
  "message": "Added 10GB",
  "username": "customer_0001",
  "dataBytes": 16106127360,
  "remainingBytes": 42949672960
}
```

This debits your unassigned pool and extends the account on the gateway. Error behavior matches creation — a `502` means nothing was charged and a retry is safe.

<Warning>
  Sub-users cannot be deleted or paused, and data assigned to a sub-user cannot be moved back to your pool. Assign conservatively and top up as needed.
</Warning>