Sub-accounts

A sub-account is a label you add to your proxy username so the traffic sent with it is counted on its own. Use one per customer, project or team to see who used what, without separate plans or credentials.

Sub-accounts are available on Residential Proxies plans.

Using a sub-account

Add -subaccount-NAME right after your username. Targeting and session options follow it as usual:

customer-USERNAME-subaccount-client_a-country-us-sid-abc123-ttl-600:PASSWORD@p.shifter.io:443

curl -x customer-USERNAME-subaccount-client_a:PASSWORD@p.shifter.io:443 \
  http://ip-info.com/json

In the panel, open a Residential plan and go to Sub-accounts: type a name and it shows the full username and proxy line, ready to copy. The Proxy Generator on the same page also has a Sub-account field for building endpoints with targeting and sessions.

Rule	Detail
Characters	1 to 16 letters, digits or underscores (A-Z, a-z, 0-9, _). No hyphens: the hyphen separates the username options
Case	Case-sensitive: Client_A and client_a are two sub-accounts
Scope	Per plan: the same name on two plans is two separate sub-accounts
Creation	None needed. A sub-account appears a few minutes after its first request
Retention	Listed until 365 days after its last request. A name reused within that window continues its old history

Caution

Sub-accounts are for tracking only. They use your plan’s password and bandwidth, and no limits are enforced per sub-account: if you resell access, apply limits and billing on your own platform using the figures below. Sub-account traffic is not a billing figure; your plan’s usage is.

In the panel, the plan page lists every sub-account with its traffic for today, the last 7 days and the last 30 days, and the traffic chart on the plan page and the dashboard can switch between the main account and any sub-account.

Authentication

Both endpoints take your account’s api_token as a query parameter, the same as the Usage & Quota API. Generate it in the panel under Account → API Tokens. Each is rate limited to 30 requests per minute.

The {membership} path parameter accepts the Membership ID shown on the plan page (for example 68057) or the short code from the plan’s URL (for example Rxqk).

List sub-accounts

GET https://shifter.io/api/v1/memberships/{membership}/subaccounts

Returns every sub-account seen on the plan in the last 365 days, sorted by name.

Parameter	In	Required	Description
membership	path	yes	Membership ID or short code
api_token	query	yes	Your account API token

Example:

curl "https://shifter.io/api/v1/memberships/68057/subaccounts?api_token=YOUR_API_TOKEN"

Response:

{
  "error": null,
  "code": 200,
  "data": {
    "id": "Rxqk",
    "subaccounts": ["BigReseller_7", "client_a", "client_b"]
  }
}

A plan that has never sent sub-account traffic returns an empty list.

Sub-account usage over a time range

GET https://shifter.io/api/v1/memberships/{membership}/subaccounts/{subaccount}/usage

Traffic one sub-account used between two points in time.

Parameter	In	Required	Description
membership	path	yes	Membership ID or short code
subaccount	path	yes	Sub-account name, exact case
api_token	query	yes	Your account API token
start	query	yes	Start of the window, inclusive
end	query	yes	End of the window, exclusive

start and end accept a date (2026-10-01) or a full timestamp (2026-10-01T09:00:00), at most 366 days apart. Times are read on Paris time, the clock the traffic counters run on.

Example:

curl "https://shifter.io/api/v1/memberships/68057/subaccounts/client_a/usage?start=2026-10-01&end=2026-11-01&api_token=YOUR_API_TOKEN"

Response:

{
  "error": null,
  "code": 200,
  "data": {
    "id": "Rxqk",
    "subaccount": "client_a",
    "start": "2026-10-01T00:00:00",
    "end": "2026-11-01T00:00:00",
    "granularity": "day",
    "bytes": 412380000000,
    "gb": 412.38,
    "upload_bytes": 18230000000,
    "download_bytes": 394150000000,
    "requests": 9184402
  }
}

Granularity

Traffic is counted in buckets, and every bucket the window touches is counted whole:

• Windows that start within the last 7 days use hourly buckets ("granularity": "hour").
• Older windows use daily buckets ("granularity": "day"), so a window from 2026-09-01T15:00:00 counts all of September 1.

For exact per-day figures, use whole days as windows.

A sub-account with no traffic in the window, or one that has expired, returns zeros.

Errors

Status	Meaning
400	The plan is not a Residential Proxies plan, the sub-account name is invalid, or start/end are missing, out of order, or more than 366 days apart
401	Missing or invalid api_token
403	The plan is in a workspace you do not belong to
404	Plan not found
429	Rate limit reached, retry with backoff
503	Sub-account data is temporarily unavailable, retry with backoff