Metrics & Historical Data

Note: These endpoints currently support single-phase devices. Three-phase and two-phase historical endpoints are coming soon.

Current Device Metrics

Rich Device Details

Get comprehensive device information including current metrics:

Endpoint: GET /api/v2/devices/{device_id}/

curl -s \
  -H "X-Qube-API-Key: $QUBE_API_KEY" \
  https://developer.qube.eco/api/v2/devices/QUBE-ONE-<some-id>/

Response includes:

• Device metadata (name, description, space)
• Connectivity status (is_online)
• Current electrical readings (energy, power, voltage, etc.)
• Device state (relay status, mode, balance)
• Configuration (tariffs, user-defined fields)

Flattened Metrics View

Get key metrics in a simplified format:

Endpoint: GET /api/v2/devices/{device_id}/metrics

curl -s \
  -H "X-Qube-API-Key: $QUBE_API_KEY" \
  https://developer.qube.eco/api/v2/devices/QUBE-ONE-<some-id>/metrics

Response:

{
  "success": true,
  "data": {
    "device_id": "QUBE-ONE-<some-id>",
    "eb_tariff": 500,
    "dg_tariff": 800,
    "active_tariff": 1,
    "energy": 1234.56,
    "active_power": 2500.0,
    "voltage": 230.5,
    "balance": 50000,
    "relay_state": true,
    "mode": "PREPAID",
    "pg_enabled": true
  }
}

Available Metrics:

• eb_tariff - Electricity Board tariff (paise)
• dg_tariff - Diesel Generator tariff (paise)
• active_tariff - Active tariff selector (1=EB, 2=DG)
• energy - Cumulative energy reading (kWh)
• active_power - Current active power consumption (W)
• voltage - Line voltage (V)
• balance - Prepaid balance (paise)
• relay_state - Relay status (true=ON, false=OFF)
• mode - Meter mode (PREPAID/POSTPAID/MEASUREMENT/RELAY_OFF)
• pg_enabled - Payment gateway enabled status

Historical Data

Retrieving Historical Metrics

Get time-series data for any device property:

Endpoint: GET /api/v2/devices/{device_id}/metrics/history

Required Parameters:

• property_id - The metric to retrieve (e.g., "energy", "active_power", "voltage")
• from_date - Start date (YYYY-MM-DD format)
• to_date - End date (YYYY-MM-DD format)

Optional Parameters:

• interval - Data aggregation interval (default: "1d")
  • 15m - 15-minute intervals
  • 30m - 30-minute intervals
  • 60m - 1-hour intervals
  • 1d - 1-day intervals

Examples

Daily energy consumption for a month:

curl -s \
  -H "X-Qube-API-Key: $QUBE_API_KEY" \
  "https://developer.qube.eco/api/v2/devices/QUBE-ONE-<some-id>/metrics/history?property_id=energy&from_date=2025-01-01&to_date=2025-01-31&interval=1d"

Hourly power consumption for a day:

curl -s \
  -H "X-Qube-API-Key: $QUBE_API_KEY" \
  "https://developer.qube.eco/api/v2/devices/QUBE-ONE-<some-id>/metrics/history?property_id=active_power&from_date=2025-01-15&to_date=2025-01-15&interval=60m"

Historical Response Format:

{
  "success": true,
  "data": {
    "device_id": "QUBE-ONE-<some-id>",
    "from_date": "2025-01-01",
    "to_date": "2025-01-31",
    "readings": [
      {
        "property_id": "energy",
        "value": 1000.0,
        "unit": "kWh",
        "timestamp": "2025-01-01T23:59:59+05:30"
      },
      {
        "property_id": "energy", 
        "value": 1025.5,
        "unit": "kWh",
        "timestamp": "2025-01-02T23:59:59+05:30"
      }
    ]
  }
}

Calculating Consumption

For cumulative metrics like energy: Historical data returns raw meter readings at the end of each time interval. To calculate actual consumption, subtract the starting value from the ending value.

Formula:

• Total consumption = last_reading - first_reading
• Period consumption = end_period_reading - start_period_reading

Example 1: Monthly Energy Consumption

# Get daily energy readings for January 2025
curl -s -H "X-Qube-API-Key: $QUBE_API_KEY" \
  "https://developer.qube.eco/api/v2/devices/QUBE-ONE-abc123/metrics/history?property_id=energy&from_date=2025-01-01&to_date=2025-01-31&interval=1d"

Response excerpt:

{
  "success": true,
  "data": {
    "readings": [
      {
        "property_id": "energy",
        "value": 1000.0,
        "unit": "kWh",
        "timestamp": "2025-01-01T23:59:59+05:30"
      },
      {
        "property_id": "energy",
        "value": 1028.5,
        "unit": "kWh", 
        "timestamp": "2025-01-02T23:59:59+05:30"
      },
      // ... more readings
      {
        "property_id": "energy",
        "value": 1875.2,
        "unit": "kWh",
        "timestamp": "2025-01-31T23:59:59+05:30"
      }
    ]
  }
}

Calculations:

• Total January consumption: 1875.2 - 1000.0 = 875.2 kWh
• Jan 1-2 consumption: 1028.5 - 1000.0 = 28.5 kWh

Important Notes

• Timezone: All timestamps are in Asia/Kolkata timezone
• Raw Values: Historical data returns raw meter readings at the end of each interval
• Property Discovery: Use GET /api/v2/devices/{device_id}/ to see available property IDs in the readings array

Available Property IDs

Common property IDs you can query historically:

• energy or active_energy - Cumulative energy (kWh)
• active_power - Real-time power (W)
• voltage - Line voltage (V)
• current - Line current (A)
• power_factor - Power factor
• apparent_power - Apparent power (VA)
• reactive_power - Reactive power (VAR)

Note: Available properties may vary by device model. Check the main device endpoint for your specific device's available readings.

Error Handling

Device not found or no access:

{
  "success": false,
  "error": {
    "code": "device_not_found", 
    "detail": "You are not allowed to access the specified device. Or provided device does not exist."
  }
}

Invalid property ID:

{
  "success": false,
  "error": {
    "code": "validation_error",
    "detail": [
      {
        "loc": ["property_id"],
        "msg": "Invalid property ID"
      }
    ]
  }
}

Invalid date format:

{
  "success": false,
  "error": {
    "code": "validation_error",
    "detail": [
      {
        "loc": ["from_date"],
        "msg": "time data '2025-1-1' does not match format '%Y-%m-%d'"
      }
    ]
  }
}