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

# Sub-accounts and traffic

> Create clients, give and take back traffic, pause and delete them, and read their usage.

A sub-account is one client. It has its own login and a traffic limit that you control.

## ➕  Create

`POST /subaccounts` with a `name`, an optional `external_id` (your client ID) and optional `traffic_gb`. The traffic leaves your pool right away. You can start with 0 GB and add traffic later.

`external_id` is unique in your account, so you can find a client by your own ID with `GET /subaccounts?search=crm-1042`.

## ↔️  Give and take back traffic

| You want to | Call | What happens |
| - | - | - |
| Give more GB | `POST /subaccounts/{id}/allocate` with `gb` | The pool shrinks, the limit grows at once |
| Take back GB | `POST /subaccounts/{id}/reclaim` with `gb` | The limit drops, the GB return to the pool |
| Take back everything unused | `POST /subaccounts/{id}/reclaim` with no body | Returns all available traffic |

You can only take back what the client hasn't used. If the client is sending traffic at the same moment, the part they used before the new limit applied stays with them, and the rest returns.

While a change is being applied, the sub-account shows `"updating": true` and the returning amount is in `traffic_returning_bytes`. It usually takes a second.

## ⏸️  Pause, resume, delete

* `POST /subaccounts/{id}/suspend` stops the login. The traffic stays.
* `POST /subaccounts/{id}/resume` turns it back on.
* `DELETE /subaccounts/{id}` stops the login for good and returns all unused traffic to your pool.

## 🚦  Statuses

| `status` | Meaning |
| - | - |
| `provisioning` | The login is being created |
| `active` | Working |
| `no_traffic` | The limit is used up. Allocate more |
| `suspended` | Paused by you |
| `attention` | Our team is checking it. Changes wait until then |
| `deleting`, `deleted` | Being removed, removed |

`login_warming_until` is set for a brand-new login. Until that time, some gateways may still reject it.

## 📊  Usage

`GET /subaccounts/{id}/usage` returns traffic per day for 30 days. Add `granularity=hour&periods=24` for the last 24 hours. Usage refreshes about once a minute.

`GET /account` shows totals for the whole account, and `GET /traffic/history` lists every purchase and traffic move with the pool balance after it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.