For the complete documentation index, see llms.txt. This page is also available as Markdown.

How it works

Accounts, subscriptions, sub-users and quotas.

Data model

  • Account: you, the reseller. One login for the whole API.

  • Subscription: one per purchased product (residential, mobile, ...). Has its own traffic quota, period and sub-user limit.

  • Sub-user: a proxy user that draws traffic from exactly one subscription.

  • Sub-user quota (optional): a personal cap for one sub-user. See Sub-user quotas.

Limits

A request through a sub-user is allowed only if every applicable limit has room:

All sub-users of a subscription share its quota. A sub-user quota only adds a cap; it never extends the subscription.

Blocked reasons

blocked_reason

Meaning

USER_DISABLED

Sub-user disabled by you

USER_QUOTA_EXCEEDED

Sub-user or subscription quota used up, or a non-recurring sub-user quota period has ended

SUBSCRIPTION_INACTIVE

Subscription expired or cancelled

SUBSCRIPTION_MISSING

Subscription no longer exists

PARENT_BLOCKED

Your account is blocked

Usage

quota_used_gb on a sub-user is its traffic in the current period: the sub-user quota period if it has one, otherwise the subscription period. Refreshed every few minutes.

Sub-user quotas

A sub-user quota caps one sub-user on top of its subscription. Manage it with /api/v3/reseller/subuser-quotas.

Settings

Field
Meaning

quota_gb

Cap in GB, greater than 0

period_start_at

Start of the current period. Default now; not in the future

period_seconds

Period length, at least 3600. Omit for a lifetime quota

recurring

Start a new period automatically when one ends. Needs period_seconds

Modes

Counts all traffic since period_start_at (up to 450 days back).

Counts traffic within one period. After it ends the sub-user stays blocked until you change or remove the quota.

Counts traffic per period and starts a new one automatically; each new period counts only its own traffic.

Lifecycle

Rules

  • Usage is the sub-user's traffic from period_start_at until now (at most period_seconds). Changing period_start_at or period_seconds recalculates it for the new window, so it can go down or up (e.g. moving the start back counts older traffic). Changing quota_gb or recurring keeps current usage.

  • PATCH with period_seconds: 0 turns the quota into a lifetime quota.

  • A blocked sub-user shows blocked: true and blocked_reason: USER_QUOTA_EXCEEDED.

  • A quota larger than the subscription quota is allowed; the subscription limit applies first.

  • Sub-users that still have a legacy API traffic limit can't get a quota (409 legacy_limit); remove the legacy limit first.

Was this helpful?