getDeviceData – Tuya MiniApp

getDeviceData(params: GetDeviceDataParams)

Requires:

@tuya-miniapp/cloud-api≥1.3.0

Additional notesRead the full notes

This API depends on cloud capabilities. In the Mini App Developer Platform, go to Development Settings - Cloud Capabilities to configure authorization. Before using this API, ensure the product to which the device belongs has enabled the advanced capability **Power Consumption Statistics** on the Tuya IoT Development Platform. Products that have not enabled this capability cannot collect energy consumption/electricity cost data; the API will return empty data or errors. To use it, create a product with energy consumption/electricity cost statistics and enable the corresponding advanced capability in the product details.

Description

Query device energy indicator data by time range. Supports aggregation by hour, day, or month, with aggregation methods (sum, average, max). The response includes the aggregate value, unit, and a segmented breakdown list.

Parameters

Parameter	Type	Required	Description
		Yes	Request parameters

Return Value

Type: Promise<GetDeviceDataResult>

An object containing total (aggregate over the range), unit (metric unit, e.g., kWh), and list (segmented data; each item includes date and value; value is 0 when no data)

Referenced Types

interfaceGetDeviceDataResult

Property	Type	Description
`total`	number	Aggregate value for the interval
`unit`	string	Metric unit, e.g., `kWh`, `元`
		Segmented data list; when no data, the corresponding `value` is `0`

enumIndicatorCode

Value	Actual Value	Description
`IndicatorCode.EleUsage`	`ele_usage`	Electricity consumption
`IndicatorCode.EleCost`	`ele_cost`	Electricity bill

enumDateType

Value	Actual Value	Description
`DateType.Hour`	`hour`	Hour-level granularity; date format is `YYYYMMDDHH`, e.g., `2026010108`
`DateType.Day`	`day`	Daily granularity, date format `YYYYMMDD`, e.g., `20260101`
`DateType.Month`	`month`	Monthly granularity, date format `YYYYMM`, e.g., `202601`

Valid Values

`IndicatorCode`

Value	Description	Since
`ele_usage`	Electricity consumption	-
`ele_cost`	Electricity bill	-

`DateType`

Value	Description	Since
`hour`	Hour-level granularity; date format is `YYYYMMDDHH`, e.g., `2026010108`	-
`day`	Daily granularity, date format `YYYYMMDD`, e.g., `20260101`	-
`month`	Monthly granularity, date format `YYYYMM`, e.g., `202601`	-

`GetDeviceDataParams.aggregationType`

Value	Description	Since
`SUM`	-	-
`AVG`	-	-
`MAX`	-	-

Examples

Request example

import { getDeviceData, IndicatorCode, DateType } from '@tuya-miniapp/cloud-api';

getDeviceData({
  devId: 'vdevo123',
  indicatorCode: IndicatorCode.EleUsage,
  dateType: DateType.Day,
  beginDate: '20260101',
  endDate: '20260131',
})
  .then(result => {
    console.log('Energy data summary:', result.total, result.unit);
    result.list.forEach(item => {
      console.log(`${item.date}: ${item.value} ${result.unit}`);
    });
  })
  .catch(error => {
    console.error('Failed to query energy data:', error);
  });

Response example

{
  "total": 31.2,
  "unit": "kWh",
  "list": [
    { "date": "20260101", "value": 1.2 },
    { "date": "20260102", "value": 0.8 },
    { "date": "20260103", "value": 1.5 }
  ]
}

FAQ

Why does the call to cloud capabilities fail?

Before using this API, please ensure that the product to which the device belongs has enabled the Electricity Statistics advanced capability on the Tuya IoT Development Platform. Products without this capability enabled cannot collect electricity consumption/cost data, and the API will return empty data or an error. If you need to use it, please create a product with electricity consumption/cost statistics functions and enable the corresponding advanced capabilities in the product details. At the same time, the API depends on cloud capabilities, and authorization configuration is required in Development Settings - Cloud Capabilities on the Mini Program Developer Platform.