# 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"}}}}}}}}}
````


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.qubitro.com/developers/device-data.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.