Skip to main content
This example demonstrates how to create a proxy user with custom metadata and a bandwidth limit. This is useful for organizing proxy users by department, tracking usage, and managing bandwidth allocation.
This example creates a proxy user with unrestricted access to all your proxies. For restricted access to specific services or proxies, see:
import requests

# API credentials
API_PUBLIC_KEY = "your_public_key"
API_PRIVATE_KEY = "your_private_key"
BASE_URL = "https://api.pingproxies.com/1.0/public"

# Headers for authentication
headers = {
    "X-API-Public-Key": API_PUBLIC_KEY,
    "X-API-Private-Key": API_PRIVATE_KEY,
    "Content-Type": "application/json"
}

def create_proxy_user(user_id, password, bandwidth_limit_gb, metadata):
    """
    Create a proxy user with metadata and bandwidth limits.

    Args:
        user_id: ID for the proxy user
        password: Password for the proxy user
        bandwidth_limit_gb: Residential bandwidth limit in GB
        metadata: Dictionary of metadata key-value pairs

    Returns:
        Created proxy user details or None if creation failed
    """
    # Convert GB to bytes
    bandwidth_limit_bytes = bandwidth_limit_gb * 1024 * 1024 * 1024

    # Create the request payload
    payload = {
        "proxy_user_id": user_id,
        "proxy_user_password": password,
        "proxy_user_residential_bytes_limit": bandwidth_limit_bytes,
        "proxy_user_metadata": metadata
    }

    # Make request to create the proxy user
    response = requests.post(
        f"{BASE_URL}/user/proxy_user/create",
        json=payload,
        headers=headers
    )

    if response.status_code != 201:
        print(f"Error: {response.status_code}")
        print(response.text)
        return None

    data = response.json()
    print(f"Successfully created proxy user: {user_id}")
    return data

# Example usage
if __name__ == "__main__":
    # Define parameters
    USER_ID = "seo_department"
    PASSWORD = "strongpassword123"
    BANDWIDTH_LIMIT_GB = 10

    # Custom metadata for organization
    METADATA = {
        "department": "SEO",
        "team_lead": "Jane Smith",
        "created_by": "api",
        "purpose": "keyword_research",
        "cost_center": "MKTG-001"
    }

    # Create the proxy user
    result = create_proxy_user(
        user_id=USER_ID,
        password=PASSWORD,
        bandwidth_limit_gb=BANDWIDTH_LIMIT_GB,
        metadata=METADATA
    )

    if result:
        print("\nProxy User Details:")
        print(f"  ID: {result['data']['proxy_user_id']}")
        print(f"  Password: {result['data']['proxy_user_password']}")
        print(f"  Access Type: all (unrestricted)")
        print(f"  Bandwidth Limit: {BANDWIDTH_LIMIT_GB}GB")

​
Key Features Explained

​
1. Custom Metadata

Metadata allows you to store custom information with each proxy user for organization and tracking: 
"proxy_user_metadata": {
  "department": "SEO",
  "team_lead": "Jane Smith",
  "created_by": "api",
  "purpose": "keyword_research",
  "cost_center": "MKTG-001"
}
Metadata constraints:
  • Flat JSON object (no nested objects)
  • Maximum 30 keys
  • Each value ≤ 300 characters
  • Total size ≤ 32KB
  • Supports string, boolean, float, and integer values

​
2. Bandwidth Limits

Set residential bandwidth limits in bytes. The example uses 10GB: 
10GB = 10 × 1024 × 1024 × 1024 bytes = 10,737,418,240 bytes
This limit applies only to residential proxy usage through this proxy user.

​
3. Unrestricted Access

By default (when proxy_user_access_type is not specified or set to "all"), the proxy user has unrestricted access to all proxies in your account.

​
Access Control Options

If you need to restrict which proxies this user can access, see these guides:
Access TypeDescriptionGuide
Service-RestrictedLimit access to specific servicesCreate with Service Access
Proxy-RestrictedLimit access to specific individual proxiesCreate with Proxy Access

​
Common Use Cases

​
Department Organization

Create proxy users for different teams with custom metadata:
  • SEO Team: Track keyword research usage
  • Marketing Team: Monitor ad verification activities
  • Research Team: Measure data collection bandwidth

​
Customer Bandwidth Management

Assign bandwidth limits based on customer plans:
  • Basic Plan: 5GB limit
  • Pro Plan: 25GB limit
  • Enterprise Plan: 100GB+ limit

​
Cost Center Tracking

Use metadata to track usage by cost center or project for billing: 
{
  "cost_center": "MKTG-001",
  "project": "Q1-Campaign",
  "budget_code": "FY2024-DIGITAL"
}