# Device Data

## Get device data

> Retrieves time-series data from a device with flexible pagination and time range filtering. Data is returned in reverse chronological order (newest first).\
> \
> \*\*Range Types:\*\*\
> \- \`all\`: Returns all data with pagination\
> \- \`time\`: Returns data within specified start and end timestamps (requires start and end parameters)\
> \- \`last\`: Returns most recent data points (requires limit parameter)\
> \
> \*\*Pagination:\*\*\
> \- page: Page number starting from 1\
> \- limit: Number of records per page (max 1000)\
> \- Results are sorted by timestamp descending\
> \
> \*\*Time Format:\*\*\
> Use ISO 8601 format in UTC: \`2024-01-15T10:30:00Z\`\
> \
> \*\*Storage Views:\*\*\
> If a storage function (data transformation) is applied, use the \`storage\` parameter with the function identifier to retrieve transformed data instead of raw data\
> \
> \*\*Example Queries:\*\*\
> \- Last 100 records: \`?page=1\&limit=100\&range=all\`\
> \- Specific time range: \`?page=1\&limit=100\&range=time\&start=2024-01-01T00:00:00Z\&end=2024-01-02T00:00:00Z\`

```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.DataPoint":{"type":"object","properties":{"battery":{"description":"Example sensor field (varies by device)","type":"number"},"humidity":{"description":"Example sensor field (varies by device)","type":"number"},"temperature":{"description":"Example sensor field (varies by device)","type":"number"},"time":{"description":"Timestamp in ISO 8601 format (UTC)","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}/data":{"get":{"description":"Retrieves time-series data from a device with flexible pagination and time range filtering. Data is returned in reverse chronological order (newest first).\n\n**Range Types:**\n- `all`: Returns all data with pagination\n- `time`: Returns data within specified start and end timestamps (requires start and end parameters)\n- `last`: Returns most recent data points (requires limit parameter)\n\n**Pagination:**\n- page: Page number starting from 1\n- limit: Number of records per page (max 1000)\n- Results are sorted by timestamp descending\n\n**Time Format:**\nUse ISO 8601 format in UTC: `2024-01-15T10:30:00Z`\n\n**Storage Views:**\nIf a storage function (data transformation) is applied, use the `storage` parameter with the function identifier to retrieve transformed data instead of raw data\n\n**Example Queries:**\n- Last 100 records: `?page=1&limit=100&range=all`\n- Specific time range: `?page=1&limit=100&range=time&start=2024-01-01T00:00:00Z&end=2024-01-02T00:00:00Z`","tags":["Device Data"],"summary":"Get device data","parameters":[{"description":"Project ID (UUID format)","name":"project_id","in":"path","required":true,"schema":{"type":"string"}},{"description":"Device ID","name":"device_id","in":"path","required":true,"schema":{"type":"string"}},{"description":"Page number (starts at 1)","name":"page","in":"query","required":true,"schema":{"type":"integer"}},{"description":"Records per page (max 1000)","name":"limit","in":"query","required":true,"schema":{"type":"integer"}},{"description":"Range type: 'all', 'time', or 'last'","name":"range","in":"query","required":true,"schema":{"type":"string"}},{"description":"Start time in ISO 8601 format (required if range=time)","name":"start","in":"query","schema":{"type":"string"}},{"description":"End time in ISO 8601 format (required if range=time)","name":"end","in":"query","schema":{"type":"string"}},{"description":"Storage view identifier for transformed data","name":"storage","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Array of data points - Each object contains 'time' field plus device-specific sensor fields (e.g., temperature, humidity). Field names vary by device.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/main.DataPoint"}}}}},"400":{"description":"Invalid parameters - Check range type, time format, or pagination 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":"Device not found or access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/main.ErrorResponse"}}}}}}}}}
```

## Purge all device data

> \*\*⚠️ DATA ONLY:\*\* Permanently deletes ALL time-series data for a device while keeping the device configuration, functions, and settings intact. This action CANNOT be undone.\
> \
> \*\*What Gets Deleted:\*\*\
> \- \*\*All time-series measurements\*\* from TimescaleDB\
> \- All historical data points\
> \- All timestamps and values\
> \
> \*\*What is KEPT:\*\*\
> \- ✅ Device configuration and metadata\
> \- ✅ Device credentials (MQTT/HTTP)\
> \- ✅ Functions (decoder, transform, rules, storage, schedules)\
> \- ✅ Storage views\
> \- ✅ Dashboard widgets (will show no data)\
> \
> \*\*After Purge:\*\*\
> \- Device can immediately start sending new data\
> \- Functions continue to execute on new data\
> \- Dashboards show empty state until new data arrives\
> \
> \*\*Use Cases:\*\*\
> \- Clear test data before production deployment\
> \- Start fresh after configuration changes\
> \- Remove corrupted data while keeping device setup\
> \- Compliance: Delete old data while maintaining device structure\
> \
> \*\*Alternative:\*\* Use Device DELETE to remove both device and data\
> \
> \*\*Success Response:\*\*\
> \`\`\`json\
> {\
> "success": true,\
> "message": "Device data purged successfully",\
> "action": "delete device 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}/data":{"delete":{"description":"**⚠️ DATA ONLY:** Permanently deletes ALL time-series data for a device while keeping the device configuration, functions, and settings intact. This action CANNOT be undone.\n\n**What Gets Deleted:**\n- **All time-series measurements** from TimescaleDB\n- All historical data points\n- All timestamps and values\n\n**What is KEPT:**\n- ✅ Device configuration and metadata\n- ✅ Device credentials (MQTT/HTTP)\n- ✅ Functions (decoder, transform, rules, storage, schedules)\n- ✅ Storage views\n- ✅ Dashboard widgets (will show no data)\n\n**After Purge:**\n- Device can immediately start sending new data\n- Functions continue to execute on new data\n- Dashboards show empty state until new data arrives\n\n**Use Cases:**\n- Clear test data before production deployment\n- Start fresh after configuration changes\n- Remove corrupted data while keeping device setup\n- Compliance: Delete old data while maintaining device structure\n\n**Alternative:** Use Device DELETE to remove both device and data\n\n**Success Response:**\n```json\n{\n\"success\": true,\n\"message\": \"Device data purged successfully\",\n\"action\": \"delete device data\"\n}\n```","tags":["Device Data"],"summary":"Purge all device data","parameters":[{"description":"Project ID (UUID format)","name":"project_id","in":"path","required":true,"schema":{"type":"string"}},{"description":"Device ID","name":"device_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Device data purged successfully - Device 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 - Insufficient permissions (requires delete scope)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/main.ErrorResponse"}}}},"404":{"description":"Device not found or access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/main.ErrorResponse"}}}}}}}}}
````

## Get device data keys

> Retrieves all available data keys (field names) from the device's telemetry data. Data keys are the field names in the JSON payload sent by the device.\
> \
> \*\*What are Data Keys?\*\*\
> Field names in your device's telemetry data. For example, if your device sends \`{"temperature": 25, "humidity": 60, "battery": 3.7}\`, the data keys are \`\["temperature", "humidity", "battery"]\`.\
> \
> \*\*Use Cases:\*\*\
> \- \*\*Discover available fields\*\* before querying data\
> \- \*\*Build dynamic UIs\*\* that adapt to device data structure\
> \- \*\*Validate widget configurations\*\* before creating dashboards\
> \- \*\*API integration\*\* to understand device data schema\
> \
> \*\*Returns:\*\* Array of string field names from the most recent data point\
> \
> \*\*Example Response:\*\*\
> \`\`\`json\
> \["temperature", "humidity", "battery\_level", "rssi", "snr", "timestamp"]\
> \`\`\`

````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}/data/keys":{"get":{"description":"Retrieves all available data keys (field names) from the device's telemetry data. Data keys are the field names in the JSON payload sent by the device.\n\n**What are Data Keys?**\nField names in your device's telemetry data. For example, if your device sends `{\"temperature\": 25, \"humidity\": 60, \"battery\": 3.7}`, the data keys are `[\"temperature\", \"humidity\", \"battery\"]`.\n\n**Use Cases:**\n- **Discover available fields** before querying data\n- **Build dynamic UIs** that adapt to device data structure\n- **Validate widget configurations** before creating dashboards\n- **API integration** to understand device data schema\n\n**Returns:** Array of string field names from the most recent data point\n\n**Example Response:**\n```json\n[\"temperature\", \"humidity\", \"battery_level\", \"rssi\", \"snr\", \"timestamp\"]\n```","tags":["Device Data"],"summary":"Get device data keys","parameters":[{"description":"Project ID (UUID format)","name":"project_id","in":"path","required":true,"schema":{"type":"string"}},{"description":"Device ID","name":"device_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Data keys retrieved successfully - Returns array of field names","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":"Device not found or no data available yet","content":{"application/json":{"schema":{"$ref":"#/components/schemas/main.ErrorResponse"}}}}}}}}}
````