Skip to main content

Usage API

Monitor your proxy usage, track bandwidth consumption, and analyze request patterns.

Get Usage Summary​

Get an overview of usage across all subscriptions.

GET /api/v1/usage

Parameters​

ParameterTypeDescription
periodstringtoday, week, month, all

Example Request​

curl -X GET "https://api.weproxies.com/api/v1/usage?period=month" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Example Response​

{
  "data": {
    "period": {
      "start": "2024-01-01T00:00:00Z",
      "end": "2024-01-31T23:59:59Z"
    },
    "total": {
      "bytes_used": 5368709120,
      "gb_used": 5.0,
      "requests": 125000,
      "success_rate": 98.7
    },
    "by_subscription": [
      {
        "subscription_id": "sub_abc123",
        "product_name": "Residential 10GB",
        "bytes_used": 4294967296,
        "gb_used": 4.0,
        "requests": 100000
      },
      {
        "subscription_id": "sub_def456",
        "product_name": "Residential 5GB",
        "bytes_used": 1073741824,
        "gb_used": 1.0,
        "requests": 25000
      }
    ],
    "by_country": [
      {"country": "US", "requests": 50000, "bytes": 2147483648},
      {"country": "GB", "requests": 30000, "bytes": 1288490189},
      {"country": "DE", "requests": 25000, "bytes": 1073741824}
    ]
  },
  "success": true
}

Get Usage History​

Get historical usage data with various granularities.

GET /api/v1/usage/history

Parameters​

ParameterTypeDescription
start_datestringStart date (ISO 8601)
end_datestringEnd date (ISO 8601)
granularitystringhourly, daily, weekly, monthly
subscription_idstringFilter by subscription (optional)

Example Request​

curl -X GET "https://api.weproxies.com/api/v1/usage/history?start_date=2024-01-01&end_date=2024-01-31&granularity=daily" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Example Response​

{
  "data": {
    "period": {
      "start": "2024-01-01T00:00:00Z",
      "end": "2024-01-31T23:59:59Z"
    },
    "granularity": "daily",
    "data_points": [
      {
        "timestamp": "2024-01-01T00:00:00Z",
        "bytes": 171798692,
        "requests": 4500,
        "success_rate": 99.2
      },
      {
        "timestamp": "2024-01-02T00:00:00Z",
        "bytes": 193273528,
        "requests": 5100,
        "success_rate": 98.8
      }
    ]
  },
  "success": true
}

Get Real-Time Usage​

Get current usage metrics updated in real-time.

GET /api/v1/usage/realtime

Example Response​

{
  "data": {
    "timestamp": "2024-01-15T14:30:00Z",
    "current_minute": {
      "requests": 45,
      "bytes": 4718592,
      "active_sessions": 12
    },
    "last_hour": {
      "requests": 2500,
      "bytes": 268435456,
      "avg_response_time_ms": 245
    },
    "active_connections": {
      "total": 12,
      "by_country": {
        "US": 5,
        "GB": 3,
        "DE": 4
      }
    }
  },
  "success": true
}

Get Usage by Country​

Get usage breakdown by country.

GET /api/v1/usage/by-country

Parameters​

ParameterTypeDescription
start_datestringStart date (ISO 8601)
end_datestringEnd date (ISO 8601)
limitintegerNumber of countries to return

Example Response​

{
  "data": {
    "countries": [
      {
        "country_code": "US",
        "country_name": "United States",
        "requests": 50000,
        "bytes": 2147483648,
        "percentage": 40.0
      },
      {
        "country_code": "GB",
        "country_name": "United Kingdom",
        "requests": 30000,
        "bytes": 1288490189,
        "percentage": 24.0
      },
      {
        "country_code": "DE",
        "country_name": "Germany",
        "requests": 25000,
        "bytes": 1073741824,
        "percentage": 20.0
      }
    ]
  },
  "success": true
}

Usage Alerts​

Set Usage Alert​

Create an alert for usage thresholds.

POST /api/v1/usage/alerts

Request Body​

{
  "subscription_id": "sub_abc123",
  "threshold_percent": 80,
  "notification_method": "email"
}

Example Response​

{
  "data": {
    "id": "alert_xyz789",
    "subscription_id": "sub_abc123",
    "threshold_percent": 80,
    "notification_method": "email",
    "created_at": "2024-01-15T10:30:00Z"
  },
  "success": true
}

Code Examples​

Python - Monitor Usage​

import requests
from datetime import datetime, timedelta

API_TOKEN = "your_api_token"
BASE_URL = "https://api.weproxies.com"

headers = {"Authorization": f"Bearer {API_TOKEN}"}

def get_usage_summary():
    response = requests.get(
        f"{BASE_URL}/api/v1/usage",
        headers=headers,
        params={"period": "month"}
    )
    return response.json()["data"]

def get_daily_usage(days=30):
    end_date = datetime.now()
    start_date = end_date - timedelta(days=days)
    
    response = requests.get(
        f"{BASE_URL}/api/v1/usage/history",
        headers=headers,
        params={
            "start_date": start_date.isoformat(),
            "end_date": end_date.isoformat(),
            "granularity": "daily"
        }
    )
    return response.json()["data"]["data_points"]

# Get summary
summary = get_usage_summary()
print(f"Total used this month: {summary['total']['gb_used']} GB")
print(f"Total requests: {summary['total']['requests']}")
print(f"Success rate: {summary['total']['success_rate']}%")

# Get daily breakdown
daily = get_daily_usage()
for day in daily[-7:]:  # Last 7 days
    print(f"{day['timestamp'][:10]}: {day['bytes'] / 1e9:.2f} GB")

Node.js - Usage Dashboard​

const axios = require('axios');

const API_TOKEN = 'your_api_token';
const client = axios.create({
  baseURL: 'https://api.weproxies.com',
  headers: { 'Authorization': `Bearer ${API_TOKEN}` }
});

async function getDashboardData() {
  const [summary, realtime, countries] = await Promise.all([
    client.get('/api/v1/usage', { params: { period: 'month' } }),
    client.get('/api/v1/usage/realtime'),
    client.get('/api/v1/usage/by-country', { params: { limit: 10 } })
  ]);
  
  return {
    summary: summary.data.data,
    realtime: realtime.data.data,
    topCountries: countries.data.data.countries
  };
}

getDashboardData().then(data => {
  console.log('Monthly Usage:', data.summary.total.gb_used, 'GB');
  console.log('Active Connections:', data.realtime.active_connections.total);
  console.log('Top Countries:', data.topCountries.map(c => c.country_code).join(', '));
});

Usage Monitoring Script​

import requests
import time

API_TOKEN = "your_api_token"
BASE_URL = "https://api.weproxies.com"
ALERT_THRESHOLD = 80  # Percentage

headers = {"Authorization": f"Bearer {API_TOKEN}"}

def check_usage():
    response = requests.get(
        f"{BASE_URL}/api/v1/subscriptions",
        headers=headers,
        params={"status": "active"}
    )
    
    subscriptions = response.json()["data"]
    
    for sub in subscriptions:
        used_percent = (sub["traffic_used_gb"] / sub["traffic_limit_gb"]) * 100
        
        if used_percent >= ALERT_THRESHOLD:
            print(f"⚠️  WARNING: {sub['product']['name']} is at {used_percent:.1f}% usage")
        else:
            print(f"✅ {sub['product']['name']}: {used_percent:.1f}% used")

# Run check
check_usage()