Residential Token Schema: Complete Data Structure Reference

The residential token object is the core object representing a residential proxy plan. Every field is documented with validation rules and default values.

Residential Token Object Schema

Key	Type	Definition
token	string	Unique identifier for the residential proxy token
username	string	Username for proxy authentication
authType	string	Authentication type for the proxy. Always "user" for username/password authentication
password	string	Password for proxy authentication
durationHours	number	Number of hours from creation until the token expires. If set to 0, the token has unlimited duration and only expires when dataUsage >= dataLimit. Maximum value is 87,600 (10 years). Token expiration time is calculated as createdAt + durationHours
status	string	Current status of the token. "active" = ready for use, "expired" = dataUsage reached dataLimit or duration exceeded, "deleted" = manually deleted via DELETE API call
createdAt	number	Unix timestamp when the token was created (in epoch seconds)
updatedAt	number	Unix timestamp when the token was last updated (in epoch seconds)
dataUsage	number	Total data usage in bytes for this token
dataLimit	number	Maximum data limit in bytes. Token expires when dataUsage >= dataLimit. Values must be whole gigabytes (multiples of 1,000,000,000) and at least 1,000,000,000. Decreasing the stored dataLimit is not allowed.
allowedPools	array[string]	Array of allowed proxy pools. If empty, the token can use all available pools
usage	array[object]	(Optional) Array of daily usage statistics. Only included when explicitly requested via the retrieve token endpoint

Residential tokens always authenticate with the generated username/password pair. IP-based authentication is not available for residential proxies.

Usage Statistics Object

When usage statistics are requested, each entry in the usage array contains:

Key	Type	Definition
date	string	Date in YYYY-MM-DD format
usage	number	Data usage in bytes for that specific date

JSON Example of a Residential Token (Without Usage)

{
  "token": "zu8sBXS4gkh7",
  "username": "kGyohRdaGo",
  "authType": "user",
  "password": "bkXBberMQ7",
  "durationHours": 750,
  "status": "active",
  "createdAt": 1752251968,
  "updatedAt": 1754843968,
  "dataUsage": 11574848653,
  "dataLimit": 100000000000,
  "allowedPools": ["us-s", "us-r", "tickets-us-s", "tickets-us-r", "ca-s", "ca-r", "gb-s", "gb-r"]
}

JSON Example of a Residential Token (With Usage Statistics)

{
  "token": "zu8sBXS4gkh7",
  "username": "kGyohRdaGo",
  "authType": "user",
  "password": "bkXBberMQ7",
  "durationHours": 750,
  "status": "active",
  "createdAt": 1752251968,
  "updatedAt": 1754843968,
  "dataUsage": 11574848653,
  "dataLimit": 100000000000,
  "usage": [
    {
      "date": "2025-10-31",
      "usage": 10000000
    },
    {
      "date": "2025-10-30",
      "usage": 222000
    },
    {
      "date": "2025-10-29",
      "usage": 333000
    }
  ],
  "allowedPools": ["us-s", "us-r", "tickets-us-s", "tickets-us-r", "ca-s", "ca-r", "gb-s", "gb-r"]
}

Residential Token Operations

• Create Residential Token - Create a new residential proxy token (credentials are always generated for you)
• Retrieve Residential Token - Get detailed information about a token, optionally with usage statistics
• Modify Residential Token - Update password, pool access, or limits while keeping username/password authentication
• Delete Residential Token - Permanently deactivate a token
• List All Residential Tokens - View all tokens filtered by status