Skip to content
NextProxyNextProxyDocs

Proxy sub-accounts

Sub-account fields, the status machine, the two-layer traffic cap, and how to use them for team and workload isolation.

A sub-account is the basic unit of proxy access — credentials, traffic caps, whitelists and API keys all hang off it. One user gets up to 10 by default.

Fields

FieldMeaning
proxyUsername / proxyPasswordCredentials for the gateway
productIdThe product line it's bound to. A dynamic residential sub-account can also add type-premium / type-mobile to its username to use the premium residential or mobile balance per connection
trafficUnlimitedWhether to skip its own cap (bounded only by the user's pool)
trafficLimitBytesIts own traffic cap, from 1 MB to 1 TB
trafficUsedBytesConsumed so far
statusactive / disabled / deleted
remarkNote
expiresAtExpiry (present in the model, but the client API exposes no way to set it)

The traffic cap has two layers

Where each configuration fits:

trafficUnlimited: true — bounded only by the pool. Good for your own primary sub-account, where extra limits aren't wanted.

trafficUnlimited: false plus trafficLimitBytes — carve out a ceiling for this sub-account. Good for handing to a team member or dedicating to one workload, so a single job can't drain the whole pool.

Status machine

text
created → active
active ⇄ disabled           (the API toggles both ways)
active/disabled → deleted   (DELETE is a soft delete and is irreversible)

A disabled account with a correct password returns 403 account_disabled. Deleted credentials are no longer valid; a missing account record or incorrect password returns the same 407 invalid_credentials. Copy the original credentials of an active account. Exhausted traffic separately returns 402 and cannot be fixed by re-entering the password.

Deletion is soft — the record and usage history remain, the status simply becomes deleted and it can no longer be used.

Creating one

POST/api/v1/proxy/accounts
shell
curl -X POST 'https://api.example.com/api/v1/proxy/accounts' \
  -H 'Authorization: Bearer at_YOUR_ACCESS_TOKEN' \
  -H 'Origin: https://console.example.com' \
  -H 'Content-Type: application/json' \
  -d '{
    "productId": "residential_dynamic",
    "remark": "scrape job A",
    "trafficUnlimited": false,
    "trafficLimitBytes": 10737418240
  }'

10737418240 is 10 GB.

Listing, updating, deleting

GET/api/v1/proxy/accounts
PATCH/api/v1/proxy/accounts/:id
shell
# Disable a sub-account
curl -X PATCH 'https://api.example.com/api/v1/proxy/accounts/ACCOUNT_ID' \
  -H 'Authorization: Bearer at_YOUR_ACCESS_TOKEN' \
  -H 'Origin: https://console.example.com' \
  -H 'Content-Type: application/json' \
  -d '{"status":"disabled"}'
DELETE/api/v1/proxy/accounts/:id

Quantity limits

At most 10 sub-accounts per user. Exceeding it returns HTTP 409 with code proxy_account_limit_reached.

For the first 24 hours after registration, at most 2 sub-accounts can be created. After that the limit returns to 10.

This is a risk-control measure — bulk-creating sub-accounts immediately after signing up is blocked.

What hangs off each sub-account

ResourceLimit
API key1 (exactly one per account)
IP whitelist10 entries
Concurrent connections5,000 by default

Note that whitelist entries and API keys are per sub-account allowances, not per user. So creating more sub-accounts does grant more whitelist capacity — though you usually don't need it.

Using sub-accounts for isolation

Isolating by workload

text
Sub-account A: scraping, 50 GB cap
Sub-account B: account operations, 5 GB cap
Sub-account C: monitoring probes, 1 GB cap

The benefit is that any single job going wrong (an infinite loop, a target returning huge responses) can't drain the whole pool, and usage statistics stay separable.

Isolating by team member

Give each person a sub-account with their own credentials and cap:

python
def provision_member(client, member: str, quota_gb: int) -> dict:
    """Create a capped sub-account for a team member."""
    return client.post("/api/v1/proxy/accounts", {
        "productId": "residential_dynamic",
        "remark": f"member:{member}",
        "trafficUnlimited": False,
        "trafficLimitBytes": quota_gb * 1024 ** 3,
    })


for name, quota in [("alice", 20), ("bob", 10), ("carol", 10)]:
    account = provision_member(client, name, quota)
    print(name, account["proxyUsername"])

Isolating by region? Not needed

Region is specified per request through username options, not bound to a sub-account. One sub-account can reach every region it's entitled to:

shell
# Same sub-account, different regions
curl -x 'http://SAME_USER-country-US:PASS@GATEWAY_HOST:58971' ...
curl -x 'http://SAME_USER-country-DE:PASS@GATEWAY_HOST:58971' ...

So don't create multiple sub-accounts just to cover multiple regions.

If credentials leak

The fastest response to leaked sub-account credentials is disabling it:

shell
curl -X PATCH 'https://api.example.com/api/v1/proxy/accounts/ACCOUNT_ID' \
  -H 'Authorization: Bearer at_YOUR_ACCESS_TOKEN' \
  -H 'Origin: https://console.example.com' \
  -H 'Content-Type: application/json' \
  -d '{"status":"disabled"}'

Then create a replacement. Traffic already consumed cannot be recovered, but disabling stops further spend immediately.

Did this page solve your problem?