# Aggregated Data

## List aggregated views

> Retrieves all continuous aggregation views configured for a device. Aggregation views provide pre-computed time-series summaries (min/max/avg) at regular intervals for fast long-term trend analysis.\
> \
> \*\*What are Aggregated Views?\*\*\
> Pre-computed time-series aggregations that automatically generate summary statistics at regular intervals. Think of them as scheduled SQL GROUP BY queries that run continuously.\
> \
> \*\*Benefits:\*\*\
> \- \*\*Fast queries:\*\* Retrieve months of data instantly (vs slow raw data queries)\
> \- \*\*Long-term trends:\*\* View hourly/daily summaries for historical analysis\
> \- \*\*Reduced storage:\*\* Downsample old data while keeping insights\
> \- \*\*Dashboard performance:\*\* Charts load faster with aggregated data\
> \
> \*\*Supported Intervals:\*\*\
> \`1h\` (hourly), \`3h\`, \`6h\`, \`12h\`, \`1d\` (daily), \`1w\` (weekly)\
> \
> \*\*Supported Aggregations:\*\*\
> \`MIN\`, \`MAX\`, \`AVG\`, \`SUM\`, \`COUNT\`\
> \
> \*\*Use Cases:\*\*\
> \- Long-term trend analysis (months/years)\
> \- Compliance reporting (daily min/max/avg)\
> \- Performance optimization for dashboards\
> \- Historical data analysis without querying raw data

```json
{"openapi":"3.0.0","info":{"title":"Qubitro Public API","version":"2.0"},"servers":[{"url":"https://api.qubitro.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"description":"Enter your API key with the Bearer prefix, e.g. \"Bearer QB_your_api_key_here\"","type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"contaggr.aggrItem":{"type":"object","properties":{"created":{"description":"View creation timestamp (ISO 8601 format, UTC)","type":"string"},"id":{"description":"Continuous aggregation view ID (UUID format)","type":"string"},"interval":{"description":"Aggregation interval: \"1h\", \"3h\", \"6h\", \"12h\", \"1d\", \"1w\"","type":"string"},"name":{"description":"View name","type":"string"},"tags":{"description":"Optional tags for categorization","type":"array","items":{"type":"string"}}}},"main.ErrorResponse":{"type":"object","properties":{"action":{"description":"Action that was attempted","type":"string"},"code":{"description":"Optional error code","type":"string"},"details":{"description":"Optional additional details","type":"string"},"message":{"description":"Human-readable error message","type":"string"},"success":{"description":"Operation failed","type":"boolean"}}}}},"paths":{"/v2/projects/{project_id}/devices/{device_id}/aggregated-view":{"get":{"description":"Retrieves all continuous aggregation views configured for a device. Aggregation views provide pre-computed time-series summaries (min/max/avg) at regular intervals for fast long-term trend analysis.\n\n**What are Aggregated Views?**\nPre-computed time-series aggregations that automatically generate summary statistics at regular intervals. Think of them as scheduled SQL GROUP BY queries that run continuously.\n\n**Benefits:**\n- **Fast queries:** Retrieve months of data instantly (vs slow raw data queries)\n- **Long-term trends:** View hourly/daily summaries for historical analysis\n- **Reduced storage:** Downsample old data while keeping insights\n- **Dashboard performance:** Charts load faster with aggregated data\n\n**Supported Intervals:**\n`1h` (hourly), `3h`, `6h`, `12h`, `1d` (daily), `1w` (weekly)\n\n**Supported Aggregations:**\n`MIN`, `MAX`, `AVG`, `SUM`, `COUNT`\n\n**Use Cases:**\n- Long-term trend analysis (months/years)\n- Compliance reporting (daily min/max/avg)\n- Performance optimization for dashboards\n- Historical data analysis without querying raw data","tags":["Aggregated Data"],"summary":"List aggregated views","parameters":[{"description":"Project ID (UUID format)","name":"project_id","in":"path","required":true,"schema":{"type":"string"}},{"description":"Device ID (UUID format)","name":"device_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"List of aggregation views - Each view contains interval, tags, and creation date","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/contaggr.aggrItem"}}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/main.ErrorResponse"}}}},"404":{"description":"Device not found - Check project_id and device_id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/main.ErrorResponse"}}}}}}}}}
```

## Get aggregated data

> Retrieves pre-computed time-series statistics (min/max/avg) from a continuous aggregation view. Returns aggregated data points at the configured interval (hourly, daily, etc.).\
> \
> \*\*What You'll Get:\*\*\
> Each data point contains the aggregated statistics for the specified time bucket. For example, with a 1-hour interval, each record represents the min/max/avg values for that hour.\
> \
> \*\*Query Range Types:\*\*\
> \
> \| Range Type | Description | Required Parameters | Example |\
> \|------------|-------------|---------------------|---------|\
> \| \`all\` | Retrieve all available aggregated data | \`page\`, \`limit\` | Get last 168 records (7 days of hourly data) |\
> \| \`time\` | Specific time range | \`page\`, \`limit\`, \`start\`, \`end\` | Get data between 2024-01-01 and 2024-01-31 |\
> \
> \*\*Pagination:\*\*\
> \- \`page\`: Page number (1-based indexing)\
> \- \`limit\`: Records per page (recommended: 100-1000 for aggregated data)\
> \- Results ordered by time (newest first)\
> \
> \*\*Field Filtering:\*\*\
> Use the \`keys\` query parameter to filter specific aggregated fields. Example: \`keys=temperature\_avg,temperature\_max\` will only return those fields.\
> \
> \*\*When to Use vs Raw Data:\*\*\
> \
> \| Use Aggregated View When: | Use Raw Data When: |\
> \|---------------------------|-------------------|\
> \| Querying > 24 hours of data | Need real-time, latest values |\
> \| Need min/max/avg statistics | Need individual data points |\
> \| Building trend dashboards | Debugging specific events |\
> \| Performance matters | Precision matters |\
> \
> \*\*Example Response:\*\*\
> \`\`\`json\
> \[\
> {\
> "time": "2024-01-15T10:00:00Z",\
> "temperature\_min": 18.5,\
> "temperature\_max": 24.3,\
> "temperature\_avg": 21.4,\
> "humidity\_avg": 65.2\
> }\
> ]\
> \`\`\`

````json
{"openapi":"3.0.0","info":{"title":"Qubitro Public API","version":"2.0"},"servers":[{"url":"https://api.qubitro.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"description":"Enter your API key with the Bearer prefix, e.g. \"Bearer QB_your_api_key_here\"","type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"main.ErrorResponse":{"type":"object","properties":{"action":{"description":"Action that was attempted","type":"string"},"code":{"description":"Optional error code","type":"string"},"details":{"description":"Optional additional details","type":"string"},"message":{"description":"Human-readable error message","type":"string"},"success":{"description":"Operation failed","type":"boolean"}}}}},"paths":{"/v2/projects/{project_id}/devices/{device_id}/aggregated-view/{contaggr_id}":{"get":{"description":"Retrieves pre-computed time-series statistics (min/max/avg) from a continuous aggregation view. Returns aggregated data points at the configured interval (hourly, daily, etc.).\n\n**What You'll Get:**\nEach data point contains the aggregated statistics for the specified time bucket. For example, with a 1-hour interval, each record represents the min/max/avg values for that hour.\n\n**Query Range Types:**\n\n| Range Type | Description | Required Parameters | Example |\n|------------|-------------|---------------------|---------|\n| `all` | Retrieve all available aggregated data | `page`, `limit` | Get last 168 records (7 days of hourly data) |\n| `time` | Specific time range | `page`, `limit`, `start`, `end` | Get data between 2024-01-01 and 2024-01-31 |\n\n**Pagination:**\n- `page`: Page number (1-based indexing)\n- `limit`: Records per page (recommended: 100-1000 for aggregated data)\n- Results ordered by time (newest first)\n\n**Field Filtering:**\nUse the `keys` query parameter to filter specific aggregated fields. Example: `keys=temperature_avg,temperature_max` will only return those fields.\n\n**When to Use vs Raw Data:**\n\n| Use Aggregated View When: | Use Raw Data When: |\n|---------------------------|-------------------|\n| Querying > 24 hours of data | Need real-time, latest values |\n| Need min/max/avg statistics | Need individual data points |\n| Building trend dashboards | Debugging specific events |\n| Performance matters | Precision matters |\n\n**Example Response:**\n```json\n[\n{\n\"time\": \"2024-01-15T10:00:00Z\",\n\"temperature_min\": 18.5,\n\"temperature_max\": 24.3,\n\"temperature_avg\": 21.4,\n\"humidity_avg\": 65.2\n}\n]\n```","tags":["Aggregated Data"],"summary":"Get aggregated data","parameters":[{"description":"Project ID (UUID format)","name":"project_id","in":"path","required":true,"schema":{"type":"string"}},{"description":"Device ID (UUID format)","name":"device_id","in":"path","required":true,"schema":{"type":"string"}},{"description":"Continuous Aggregation ID (UUID format)","name":"contaggr_id","in":"path","required":true,"schema":{"type":"string"}},{"description":"Page number for pagination (1-based)","name":"page","in":"query","required":true,"schema":{"type":"integer"}},{"description":"Number of records per page (max: 10000)","name":"limit","in":"query","required":true,"schema":{"type":"integer"}},{"description":"Range type: 'all' (all data) or 'time' (specific period)","name":"range","in":"query","required":true,"schema":{"type":"string"}},{"description":"Start time in ISO 8601 format (UTC) - Required if range=time","name":"start","in":"query","schema":{"type":"string"}},{"description":"End time in ISO 8601 format (UTC) - Required if range=time","name":"end","in":"query","schema":{"type":"string"}},{"description":"Comma-separated list of fields to include (filters response fields)","name":"keys","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Array of aggregated data points - Each point contains time and aggregated statistics (e.g., temperature_min, temperature_max, temperature_avg)","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}},"400":{"description":"Invalid parameters - Check range type, date format (must be ISO 8601), page/limit values","content":{"application/json":{"schema":{"$ref":"#/components/schemas/main.ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/main.ErrorResponse"}}}},"404":{"description":"Aggregation view not found - Check contaggr_id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/main.ErrorResponse"}}}}}}}}}
````

## Delete aggregated data

> \*\*⚠️ DATA ONLY:\*\* Permanently deletes ALL aggregated time-series data from a continuous aggregation view while keeping the view configuration intact. This action CANNOT be undone.\
> \
> \*\*What Gets Deleted:\*\*\
> \- \*\*All aggregated data points\*\* from TimescaleDB continuous aggregation view\
> \- All historical statistics (min/max/avg/sum/count)\
> \- All time buckets and computed values\
> \
> \*\*What is KEPT:\*\*\
> \- ✅ Aggregation view configuration (interval, keys, aggregation types)\
> \- ✅ View metadata (name, tags, creation date)\
> \- ✅ The view definition itself (new data will continue to aggregate)\
> \
> \*\*Impact:\*\*\
> \- Dashboard widgets using this view will show no data (but won't break)\
> \- New device data will continue to aggregate according to the view configuration\
> \- Historical trends and reports will be empty until new data accumulates\
> \
> \*\*Cannot Be Undone:\*\* There is no way to recover purged aggregated data. However, if raw device data still exists, you can recreate the aggregation view to recompute statistics from scratch.\
> \
> \*\*Difference from Device DELETE:\*\*\
> \- This endpoint: Deletes aggregated statistics only, keeps view configuration\
> \- Device DELETE: Deletes device, all raw data, AND all aggregation views\
> \
> \*\*When to Use:\*\*\
> \- Reset aggregation statistics after fixing data quality issues\
> \- Clear old aggregated data while keeping view configuration\
> \- Troubleshoot aggregation issues by starting fresh\
> \
> \*\*Alternative:\*\* To delete the entire aggregation view (configuration + data), delete it via the Qubitro web portal instead.\
> \
> \*\*Success Response:\*\*\
> \`\`\`json\
> {\
> "success": true,\
> "message": "Aggregated data purged successfully",\
> "action": "purge data"\
> }\
> \`\`\`

````json
{"openapi":"3.0.0","info":{"title":"Qubitro Public API","version":"2.0"},"servers":[{"url":"https://api.qubitro.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"description":"Enter your API key with the Bearer prefix, e.g. \"Bearer QB_your_api_key_here\"","type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"main.SuccessResponse":{"type":"object","properties":{"action":{"description":"Action that was performed","type":"string"},"message":{"description":"Human-readable success message","type":"string"},"success":{"description":"Operation completed successfully","type":"boolean"}}},"main.ErrorResponse":{"type":"object","properties":{"action":{"description":"Action that was attempted","type":"string"},"code":{"description":"Optional error code","type":"string"},"details":{"description":"Optional additional details","type":"string"},"message":{"description":"Human-readable error message","type":"string"},"success":{"description":"Operation failed","type":"boolean"}}}}},"paths":{"/v2/projects/{project_id}/devices/{device_id}/aggregated-view/{contaggr_id}":{"delete":{"description":"**⚠️ DATA ONLY:** Permanently deletes ALL aggregated time-series data from a continuous aggregation view while keeping the view configuration intact. This action CANNOT be undone.\n\n**What Gets Deleted:**\n- **All aggregated data points** from TimescaleDB continuous aggregation view\n- All historical statistics (min/max/avg/sum/count)\n- All time buckets and computed values\n\n**What is KEPT:**\n- ✅ Aggregation view configuration (interval, keys, aggregation types)\n- ✅ View metadata (name, tags, creation date)\n- ✅ The view definition itself (new data will continue to aggregate)\n\n**Impact:**\n- Dashboard widgets using this view will show no data (but won't break)\n- New device data will continue to aggregate according to the view configuration\n- Historical trends and reports will be empty until new data accumulates\n\n**Cannot Be Undone:** There is no way to recover purged aggregated data. However, if raw device data still exists, you can recreate the aggregation view to recompute statistics from scratch.\n\n**Difference from Device DELETE:**\n- This endpoint: Deletes aggregated statistics only, keeps view configuration\n- Device DELETE: Deletes device, all raw data, AND all aggregation views\n\n**When to Use:**\n- Reset aggregation statistics after fixing data quality issues\n- Clear old aggregated data while keeping view configuration\n- Troubleshoot aggregation issues by starting fresh\n\n**Alternative:** To delete the entire aggregation view (configuration + data), delete it via the Qubitro web portal instead.\n\n**Success Response:**\n```json\n{\n\"success\": true,\n\"message\": \"Aggregated data purged successfully\",\n\"action\": \"purge data\"\n}\n```","tags":["Aggregated Data"],"summary":"Delete aggregated data","parameters":[{"description":"Project ID (UUID format)","name":"project_id","in":"path","required":true,"schema":{"type":"string"}},{"description":"Device ID (UUID format)","name":"device_id","in":"path","required":true,"schema":{"type":"string"}},{"description":"Continuous Aggregation ID (UUID format)","name":"contaggr_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Aggregated data purged successfully - View configuration preserved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/main.SuccessResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/main.ErrorResponse"}}}},"403":{"description":"Forbidden - Requires 'delete' scope permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/main.ErrorResponse"}}}},"404":{"description":"Aggregation view not found - Check contaggr_id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/main.ErrorResponse"}}}}}}}}}
````

## Get aggregated data keys

> Retrieves all available field names (keys) from an aggregation view. Keys represent the computed statistics (min/max/avg/sum/count) for each configured field.\
> \
> \*\*What are Aggregated Keys?\*\*\
> Field names in your aggregation view that represent computed statistics. Unlike raw data keys which are simple field names like \`temperature\`, aggregated keys include the aggregation type suffix.\
> \
> \*\*Example Aggregated Keys:\*\*\
> \- \`temperature\_min\` - Minimum temperature in time bucket\
> \- \`temperature\_max\` - Maximum temperature in time bucket\
> \- \`temperature\_avg\` - Average temperature in time bucket\
> \- \`humidity\_avg\` - Average humidity in time bucket\
> \- \`sensor\_count\` - Number of data points in time bucket\
> \
> \*\*Key Naming Pattern:\*\*\
> \`{original\_field\_name}\_{aggregation\_type}\`\
> \
> \*\*Available Aggregation Types:\*\*\
> \- \`\_min\` - Minimum value in the interval\
> \- \`\_max\` - Maximum value in the interval\
> \- \`\_avg\` - Average (mean) value in the interval\
> \- \`\_sum\` - Sum of all values in the interval\
> \- \`\_count\` - Count of data points in the interval\
> \
> \*\*Use Cases:\*\*\
> \- \*\*Discover available statistics\*\* before querying aggregated data\
> \- \*\*Build dynamic dashboards\*\* that adapt to aggregation configuration\
> \- \*\*Validate chart widgets\*\* before creating visualizations\
> \- \*\*API integration\*\* to understand aggregation schema\
> \
> \*\*Note:\*\* The \`time\` field is always present but not included in the keys list (it's automatically included in all responses).

```json
{"openapi":"3.0.0","info":{"title":"Qubitro Public API","version":"2.0"},"servers":[{"url":"https://api.qubitro.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"description":"Enter your API key with the Bearer prefix, e.g. \"Bearer QB_your_api_key_here\"","type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"main.ErrorResponse":{"type":"object","properties":{"action":{"description":"Action that was attempted","type":"string"},"code":{"description":"Optional error code","type":"string"},"details":{"description":"Optional additional details","type":"string"},"message":{"description":"Human-readable error message","type":"string"},"success":{"description":"Operation failed","type":"boolean"}}}}},"paths":{"/v2/projects/{project_id}/devices/{device_id}/aggregated-view/{contaggr_id}/keys":{"get":{"description":"Retrieves all available field names (keys) from an aggregation view. Keys represent the computed statistics (min/max/avg/sum/count) for each configured field.\n\n**What are Aggregated Keys?**\nField names in your aggregation view that represent computed statistics. Unlike raw data keys which are simple field names like `temperature`, aggregated keys include the aggregation type suffix.\n\n**Example Aggregated Keys:**\n- `temperature_min` - Minimum temperature in time bucket\n- `temperature_max` - Maximum temperature in time bucket\n- `temperature_avg` - Average temperature in time bucket\n- `humidity_avg` - Average humidity in time bucket\n- `sensor_count` - Number of data points in time bucket\n\n**Key Naming Pattern:**\n`{original_field_name}_{aggregation_type}`\n\n**Available Aggregation Types:**\n- `_min` - Minimum value in the interval\n- `_max` - Maximum value in the interval\n- `_avg` - Average (mean) value in the interval\n- `_sum` - Sum of all values in the interval\n- `_count` - Count of data points in the interval\n\n**Use Cases:**\n- **Discover available statistics** before querying aggregated data\n- **Build dynamic dashboards** that adapt to aggregation configuration\n- **Validate chart widgets** before creating visualizations\n- **API integration** to understand aggregation schema\n\n**Note:** The `time` field is always present but not included in the keys list (it's automatically included in all responses).","tags":["Aggregated Data"],"summary":"Get aggregated data keys","parameters":[{"description":"Project ID (UUID format)","name":"project_id","in":"path","required":true,"schema":{"type":"string"}},{"description":"Device ID (UUID format)","name":"device_id","in":"path","required":true,"schema":{"type":"string"}},{"description":"Continuous Aggregation ID (UUID format)","name":"contaggr_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Array of aggregated field names (e.g., [\\\"temperature_min\\\", \\\"temperature_max\\\", \\\"temperature_avg\\\", \\\"humidity_avg\\\"])","content":{"application/json":{"schema":{"type":"array","items":{"type":"string"}}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/main.ErrorResponse"}}}},"404":{"description":"Aggregation view not found - Check contaggr_id or view may have no data yet","content":{"application/json":{"schema":{"$ref":"#/components/schemas/main.ErrorResponse"}}}}}}}}}
```