Proxy sub-accounts

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

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

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

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

# 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"}'

Quantity limits

What hangs off each sub-account

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

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:

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:

# 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:

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.

Related

• How traffic is counted → Traffic accounting
• How to inspect usage → Usage statistics
• Whitelist and passwordless access → IP whitelist and passwordless ports
• Every limit → Limits and quotas