Skip to main content

Bucket Analytics

Get detailed analytics and statistics for a specific bucket.

Endpoint​

GET /api/analytics/buckets/:bucketId

Authentication​

Key TypeAllowed
Admin (dakkio_a_)✅ Yes
Write (dakkio_w_)✅ Yes
Read (dakkio_r_)✅ Yes

All key types can access analytics for their respective bucket.

Request​

Headers​

HeaderTypeRequiredDescription
X-API-Keystring✅ YesYour API key (Admin, Write, or Read)

Path Parameters​

ParameterTypeRequiredDescription
bucketIdstring✅ YesThe bucket ID (24-character hex string)

Query Parameters​

ParameterTypeRequiredDescription
periodstring❌ NoTime period: 24h, 7d, 30d, 90d (default: 7d)

Example Request​

curl -X GET "https://api.dakkio.io/api/analytics/buckets/507f1f77bcf86cd799439011?period=7d" \
  -H "X-API-Key: dakkio_r_your_read_key..."

Response​

Success Response (200 OK)​

{
  "analytics": {
    "bucket": {
      "_id": "507f1f77bcf86cd799439011",
      "name": "Home Sensors"
    },
    "period": "7d",
    "summary": {
      "totalDataPoints": 50420,
      "dataPointsInPeriod": 12605,
      "avgDataPointsPerDay": 1801,
      "dataSources": 3,
      "activeAlerts": 2
    },
    "dataSourceStats": [
      {
        "_id": "507f1f77bcf86cd799439015",
        "name": "Temperature Sensor",
        "dataPointCount": 8403,
        "lastDataPoint": "2024-01-15T14:30:00Z",
        "avgValues": {
          "temperature": 22.3,
          "humidity": 65.2
        },
        "minValues": {
          "temperature": 18.5,
          "humidity": 45.0
        },
        "maxValues": {
          "temperature": 28.7,
          "humidity": 82.0
        }
      },
      {
        "_id": "507f1f77bcf86cd799439016",
        "name": "Pressure Sensor",
        "dataPointCount": 4202,
        "lastDataPoint": "2024-01-15T14:25:00Z",
        "avgValues": {
          "pressure": 1013.2
        },
        "minValues": {
          "pressure": 998.5
        },
        "maxValues": {
          "pressure": 1025.8
        }
      }
    ],
    "ingestionRate": {
      "dataPointsPerHour": [
        { "hour": "2024-01-15T00:00:00Z", "count": 75 },
        { "hour": "2024-01-15T01:00:00Z", "count": 72 },
        { "hour": "2024-01-15T02:00:00Z", "count": 78 }
      ]
    },
    "alertActivity": {
      "totalTriggered": 5,
      "byRule": [
        { "name": "High Temperature Alert", "count": 3 },
        { "name": "Low Humidity Warning", "count": 2 }
      ]
    }
  }
}

Error Responses​

401 Unauthorized​

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}

403 Forbidden​

{
  "error": "Forbidden",
  "message": "API key does not have access to this bucket"
}

404 Not Found​

{
  "error": "Not Found",
  "message": "Bucket not found"
}

Code Examples​

JavaScript/Node.js​

const axios = require('axios');

async function getBucketAnalytics(bucketId, period = '7d') {
  const response = await axios.get(
    `https://api.dakkio.io/api/analytics/buckets/${bucketId}?period=${period}`,
    {
      headers: {
        'X-API-Key': process.env.DAKKIO_READ_KEY
      }
    }
  );

  return response.data.analytics;
}

// Get 7-day analytics
const analytics = await getBucketAnalytics('507f1f77bcf86cd799439011', '7d');

console.log(`Bucket: ${analytics.bucket.name}`);
console.log(`Period: ${analytics.period}`);
console.log(`Total data points: ${analytics.summary.totalDataPoints.toLocaleString()}`);
console.log(`Data points in period: ${analytics.summary.dataPointsInPeriod.toLocaleString()}`);

console.log('\nData Source Stats:');
analytics.dataSourceStats.forEach(ds => {
  console.log(`- ${ds.name}: ${ds.dataPointCount.toLocaleString()} points`);
  console.log(`  Avg values: ${JSON.stringify(ds.avgValues)}`);
});

Python​

import requests
import os

def get_bucket_analytics(bucket_id, period='7d'):
    response = requests.get(
        f'https://api.dakkio.io/api/analytics/buckets/{bucket_id}',
        params={'period': period},
        headers={
            'X-API-Key': os.environ['DAKKIO_READ_KEY']
        }
    )

    if response.status_code == 200:
        return response.json()['analytics']
    else:
        print('Error:', response.json())
        return None

# Get 30-day analytics
analytics = get_bucket_analytics('507f1f77bcf86cd799439011', '30d')

if analytics:
    print(f"Bucket: {analytics['bucket']['name']}")
    print(f"Period: {analytics['period']}")
    print(f"Total data points: {analytics['summary']['totalDataPoints']:,}")

    print('\nData Source Stats:')
    for ds in analytics['dataSourceStats']:
        print(f"- {ds['name']}: {ds['dataPointCount']:,} points")
        print(f"  Avg values: {ds['avgValues']}")

Response Fields​

Summary​

FieldTypeDescription
totalDataPointsnumberAll-time data points in bucket
dataPointsInPeriodnumberData points in selected period
avgDataPointsPerDaynumberAverage daily ingestion rate
dataSourcesnumberNumber of data sources
activeAlertsnumberNumber of active alert rules

Data Source Stats​

FieldTypeDescription
_idstringData source ID
namestringData source name
dataPointCountnumberData points in period
lastDataPointstringLast data point timestamp
avgValuesobjectAverage value for each field
minValuesobjectMinimum value for each field
maxValuesobjectMaximum value for each field

Ingestion Rate​

FieldTypeDescription
dataPointsPerHourarrayHourly data point counts
hourstringHour timestamp
countnumberData points in that hour

Alert Activity​

FieldTypeDescription
totalTriggerednumberTotal alerts triggered in period
byRulearrayBreakdown by alert rule

Time Periods​

PeriodDescription
24hLast 24 hours
7dLast 7 days
30dLast 30 days
90dLast 90 days

Use Cases​

Dashboard Widget​

// Get analytics for a dashboard widget
const analytics = await getBucketAnalytics(bucketId, '24h');

// Display current values
const tempSensor = analytics.dataSourceStats.find(
  ds => ds.name === 'Temperature Sensor'
);

console.log(`Current avg temperature: ${tempSensor.avgValues.temperature}°C`);
console.log(`Range: ${tempSensor.minValues.temperature}°C - ${tempSensor.maxValues.temperature}°C`);

Monitoring Ingestion Rate​

// Check if data is being ingested regularly
const analytics = await getBucketAnalytics(bucketId, '24h');
const hourlyRates = analytics.ingestionRate.dataPointsPerHour;

// Check for gaps (hours with 0 data points)
const gaps = hourlyRates.filter(h => h.count === 0);
if (gaps.length > 0) {
  console.warn(`Warning: ${gaps.length} hours with no data`);
}

Alert Report​

// Weekly alert report
const analytics = await getBucketAnalytics(bucketId, '7d');

console.log(`Alerts triggered this week: ${analytics.alertActivity.totalTriggered}`);
analytics.alertActivity.byRule.forEach(rule => {
  console.log(`- ${rule.name}: ${rule.count} times`);
});