Skip to main content

Usage & Statistics

Track device activity, monitor message volumes, and analyze bandwidth usage across your IoT platform.

Get Usage Statistics​

Retrieve detailed usage statistics with optional date range filtering.

Endpoint​

GET /v1/iot/usage

Query Parameters​

ParameterTypeDescriptionRequired
start_datestringStart date (YYYY-MM-DD)No
end_datestringEnd date (YYYY-MM-DD)No
device_idstringFilter by specific deviceNo

Request Example​

# Get usage for the last 7 days
curl -X GET "https://api.wayscloud.services/v1/iot/usage?start_date=2025-10-29&end_date=2025-11-05" \
  -H "Authorization: Bearer wayscloud_iot_prod_YOUR_API_KEY"

Response​

{
  "period": {
    "start_date": "2025-10-29",
    "end_date": "2025-11-05"
  },
  "summary": {
    "total_messages": 1523456,
    "total_bandwidth_mb": 4521.8,
    "active_devices": 38,
    "total_devices": 42
  },
  "daily_breakdown": [
    {
      "date": "2025-11-05",
      "messages": 245123,
      "bandwidth_mb": 726.4,
      "active_devices": 38
    },
    {
      "date": "2025-11-04",
      "messages": 238901,
      "bandwidth_mb": 708.2,
      "active_devices": 37
    }
  ],
  "top_devices": [
    {
      "device_id": "iot_dev_abc123",
      "name": "Temperature Sensor 01",
      "messages": 52341,
      "bandwidth_mb": 156.2
    },
    {
      "device_id": "iot_dev_xyz789",
      "name": "Smart Gateway 02",
      "messages": 48923,
      "bandwidth_mb": 145.7
    }
  ]
}

Python Example​

import requests
from datetime import datetime, timedelta

API_KEY = 'wayscloud_iot_prod_YOUR_API_KEY'
API_URL = 'https://api.wayscloud.services/v1/iot'

def get_usage_stats(days=7):
    headers = {'Authorization': f'Bearer {API_KEY}'}

    end_date = datetime.now().date()
    start_date = end_date - timedelta(days=days)

    params = {
        'start_date': start_date.isoformat(),
        'end_date': end_date.isoformat()
    }

    response = requests.get(
        f'{API_URL}/usage',
        headers=headers,
        params=params
    )

    return response.json()

# Get usage for last 7 days
usage = get_usage_stats(7)

print(f"Total messages: {usage['summary']['total_messages']:,}")
print(f"Total bandwidth: {usage['summary']['total_bandwidth_mb']:.2f} MB")
print(f"Active devices: {usage['summary']['active_devices']}/{usage['summary']['total_devices']}")

print("\nTop devices:")
for device in usage['top_devices'][:5]:
    print(f"  {device['name']}: {device['messages']:,} messages")

Get Platform Statistics​

Retrieve real-time platform statistics and overview metrics.

Endpoint​

GET /v1/iot/stats

Request Example​

curl -X GET https://api.wayscloud.services/v1/iot/stats \
  -H "Authorization: Bearer wayscloud_iot_prod_YOUR_API_KEY"

Response​

{
  "platform": {
    "total_devices": 42,
    "active_devices": 38,
    "inactive_devices": 4,
    "devices_with_errors": 0
  },
  "messages": {
    "total_today": 245123,
    "total_this_month": 6821456,
    "average_per_device": 162675,
    "peak_messages_per_hour": 12456
  },
  "bandwidth": {
    "total_today_mb": 726.4,
    "total_this_month_gb": 20.2,
    "average_per_device_mb": 481.3
  },
  "connectivity": {
    "currently_connected": 35,
    "connection_success_rate": 98.5,
    "average_uptime_hours": 23.2
  },
  "timestamp": "2025-11-05T10:45:00Z"
}

Node.js Example​

const axios = require('axios');

const API_KEY = 'wayscloud_iot_prod_YOUR_API_KEY';
const API_URL = 'https://api.wayscloud.services/v1/iot';

async function getPlatformStats() {
  try {
    const response = await axios.get(`${API_URL}/stats`, {
      headers: {
        'Authorization': `Bearer ${API_KEY}`
      }
    });

    const stats = response.data;

    console.log('=== Platform Statistics ===');
    console.log(`Total Devices: ${stats.platform.total_devices}`);
    console.log(`Active: ${stats.platform.active_devices}`);
    console.log(`Currently Connected: ${stats.connectivity.currently_connected}`);
    console.log(`\nMessages Today: ${stats.messages.total_today.toLocaleString()}`);
    console.log(`Bandwidth Today: ${stats.bandwidth.total_today_mb.toFixed(2)} MB`);
    console.log(`Uptime: ${stats.connectivity.connection_success_rate}%`);

    return stats;
  } catch (error) {
    console.error('Error fetching stats:', error.message);
  }
}

getPlatformStats();

Get Device-Specific Usage​

Retrieve usage statistics for a specific device.

Request Example​

# Get usage for specific device
curl -X GET "https://api.wayscloud.services/v1/iot/usage?device_id=iot_dev_abc123&start_date=2025-10-29&end_date=2025-11-05" \
  -H "Authorization: Bearer wayscloud_iot_prod_YOUR_API_KEY"

Response​

{
  "device_id": "iot_dev_abc123",
  "name": "Temperature Sensor 01",
  "period": {
    "start_date": "2025-10-29",
    "end_date": "2025-11-05"
  },
  "summary": {
    "total_messages": 52341,
    "total_bandwidth_mb": 156.2,
    "average_messages_per_day": 7477,
    "uptime_percentage": 99.2
  },
  "daily_breakdown": [
    {
      "date": "2025-11-05",
      "messages": 8234,
      "bandwidth_mb": 24.5,
      "uptime_hours": 24.0,
      "errors": 0
    },
    {
      "date": "2025-11-04",
      "messages": 7891,
      "bandwidth_mb": 23.5,
      "uptime_hours": 23.8,
      "errors": 0
    }
  ],
  "message_types": {
    "telemetry": 48234,
    "events": 3567,
    "status": 540
  }
}

Python Dashboard Example​

import requests
import pandas as pd
from datetime import datetime, timedelta

def create_usage_dashboard(device_id=None, days=30):
    headers = {'Authorization': f'Bearer {API_KEY}'}

    end_date = datetime.now().date()
    start_date = end_date - timedelta(days=days)

    params = {
        'start_date': start_date.isoformat(),
        'end_date': end_date.isoformat()
    }

    if device_id:
        params['device_id'] = device_id

    response = requests.get(
        f'{API_URL}/usage',
        headers=headers,
        params=params
    )

    data = response.json()

    # Create DataFrame from daily breakdown
    df = pd.DataFrame(data['daily_breakdown'])
    df['date'] = pd.to_datetime(df['date'])

    # Calculate statistics
    print(f"=== Usage Report ({days} days) ===")
    print(f"Total Messages: {data['summary']['total_messages']:,}")
    print(f"Total Bandwidth: {data['summary']['total_bandwidth_mb']:.2f} MB")
    print(f"Active Devices: {data['summary']['active_devices']}")

    print(f"\nDaily Average:")
    print(f"  Messages: {df['messages'].mean():.0f}")
    print(f"  Bandwidth: {df['bandwidth_mb'].mean():.2f} MB")

    print(f"\nPeak Day:")
    peak_day = df.loc[df['messages'].idxmax()]
    print(f"  Date: {peak_day['date'].date()}")
    print(f"  Messages: {peak_day['messages']:,}")

    return df

# Generate dashboard
df = create_usage_dashboard(days=30)

# Optional: Plot with matplotlib
# import matplotlib.pyplot as plt
# df.plot(x='date', y='messages', kind='line', title='Daily Messages')
# plt.show()

Monitoring Best Practices​

Set Up Alerts​

Monitor critical metrics and set up alerts:

def check_device_health():
    stats = requests.get(
        f'{API_URL}/stats',
        headers={'Authorization': f'Bearer {API_KEY}'}
    ).json()

    # Alert if devices are offline
    if stats['platform']['inactive_devices'] > 5:
        send_alert(f"⚠️ {stats['platform']['inactive_devices']} devices offline!")

    # Alert if connection rate drops
    if stats['connectivity']['connection_success_rate'] < 95:
        send_alert(f"⚠️ Low connection rate: {stats['connectivity']['connection_success_rate']}%")

    # Alert if bandwidth usage is high
    if stats['bandwidth']['total_this_month_gb'] > 80:
        send_alert(f"⚠️ High bandwidth usage: {stats['bandwidth']['total_this_month_gb']:.1f} GB")

# Run every 5 minutes
import schedule
schedule.every(5).minutes.do(check_device_health)

Track Device Activity​

Monitor when devices last connected:

def check_inactive_devices():
    headers = {'Authorization': f'Bearer {API_KEY}'}

    response = requests.get(
        f'{API_URL}/devices',
        headers=headers
    )

    devices = response.json()['devices']

    print("Devices not seen in 24+ hours:")

    now = datetime.now()
    for device in devices:
        last_seen = datetime.fromisoformat(device['last_seen'].replace('Z', '+00:00'))
        hours_since = (now - last_seen).total_seconds() / 3600

        if hours_since > 24:
            print(f"  {device['name']}: {hours_since:.1f} hours ago")

check_inactive_devices()

Export Usage Data​

Export usage data for external analysis:

import csv

def export_usage_to_csv(filename='iot_usage.csv', days=30):
    usage = get_usage_stats(days)

    with open(filename, 'w', newline='') as csvfile:
        writer = csv.DictWriter(
            csvfile,
            fieldnames=['date', 'messages', 'bandwidth_mb', 'active_devices']
        )

        writer.writeheader()
        for day in usage['daily_breakdown']:
            writer.writerow(day)

    print(f"Usage data exported to {filename}")

export_usage_to_csv('iot_usage_november.csv')

Rate Limits​

  • GET /v1/iot/usage: 100 requests/minute
  • GET /v1/iot/stats: 100 requests/minute

Next Steps​