Skip to main content

Documentation Index

Fetch the complete documentation index at: https://documentation.byteful.com/llms.txt

Use this file to discover all available pages before exploring further.

Unlike datacenter and ISP proxies that operate on a per-proxy model, residential and mobile proxies use a data-based allocation system. This guide explains how residential and mobile data is managed in the Byteful API.

​
Data Fundamentals

Residential and mobile data in Byteful works as follows:
  • Account-Wide Pool: Data is added to your customer account as a shared resource
  • No Expiration: Once data is added to your account, it never expires until it is consumed
  • Proxy User Allocation: Data can be allocated to different proxy users with specific limits
  • Usage Tracking: All data usage is tracked and can be monitored via the API

​
Managing Data via API

​
Checking Data Usage

To check your current residential data status: 
curl --request GET \
  --url 'https://api.byteful.com/1.0/public/user/residential/summary' \
  --header 'X-API-Public-Key: your_public_key' \
  --header 'X-API-Private-Key: your_private_key'
Response: 
{
  "data": {
    "residential_bytes": 10737418240,     // Total allocated data (10 GB)
    "residential_bytes_used": 3221225472, // Used data (3 GB)
    "residential_bytes_left": 7516192768, // Remaining data (7 GB)
    "residential_requests": 145022,       // Total number of requests
    "proxy_user_ids": ["default_user", "stevejobs"] // Any other proxy users which have access to the data
  },
  "message": "Residential summary successfully generated."
}
To check your current mobile data status: 
curl --request GET \
  --url 'https://api.byteful.com/1.0/public/user/mobile/summary' \
  --header 'X-API-Public-Key: your_public_key' \
  --header 'X-API-Private-Key: your_private_key'
Response: 
{
  "data": {
    "mobile_bytes": 10737418240,     // Total allocated data (10 GB)
    "mobile_bytes_used": 3221225472, // Used data (3 GB)
    "mobile_bytes_left": 7516192768, // Remaining data (7 GB)
    "mobile_requests": 145022,       // Total number of requests
    "proxy_user_ids": ["default_user", "stevejobs"] // Any other proxy users which have access to the data
  },
  "message": "Mobile summary successfully generated."
}

​
Setting Proxy User Data Limits

While the total data is purchased through the dashboard, you can control how much data each proxy user can consume via the API: 
curl --request PATCH \
  --url 'https://api.byteful.com/1.0/public/user/proxy_user/edit/stevejobs' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Public-Key: your_public_key' \
  --header 'X-API-Private-Key: your_private_key' \
  --data '{
    "proxy_user_residential_bytes_limit": 2147483648
  }'
This sets a 2 GB limit for the “stevejobs” proxy user, preventing them from using more than that amount from the account’s total residential data. proxy_user_mobile_bytes_limit can be used to set this for mobile.

​
Creating Proxy Users with Data Limits

When creating a new proxy user, you can set their data limit immediately: 
curl --request POST \
  --url 'https://api.byteful.com/1.0/public/user/proxy_user/create' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Public-Key: your_public_key' \
  --header 'X-API-Private-Key: your_private_key' \
  --data '{
    "proxy_user_id": "research_team",
    "proxy_user_password": "secure_password",
    "proxy_user_residential_bytes_limit": 3221225472
  }'
This creates a new proxy user with a 3 GB data limit. You can use null for unlimited data. proxy_user_mobile_bytes_limit can be used to set this for mobile.

​
Viewing Individual Proxy User Data Usage

To check a specific proxy user’s data usage: 
curl --request GET \
  --url 'https://api.byteful.com/1.0/public/user/proxy_user/retrieve/research_team' \
  --header 'X-API-Public-Key: your_public_key' \
  --header 'X-API-Private-Key: your_private_key'
Response includes data fields: 
{
  "data": {
    "proxy_user_id": "research_team",
    // Residential
    "proxy_user_residential_bytes_limit": 3221225472,
    "proxy_user_residential_bytes_used": 1073741824,
    "residential_bytes_left": 2147483648,
    // Mobile
    "proxy_user_mobile_bytes_limit": 3221225472,
    "proxy_user_mobile_bytes_used": 1073741824,
    "mobile_bytes_left": 2147483648,
    // ... other proxy user fields
  },
  "message": "Proxy User successfully retrieved."
}

​
Topping Up Data

While data limits can be managed via the API, purchasing additional data must be done through the dashboard:
  1. Log into your Byteful dashboard
  2. Click “Add Data” next to your residential or mobile data total on the summary page
  3. Choose the amount of data to add
  4. Complete the purchase
Once purchased, the additional data is immediately added to your account’s pool and never expires.