getDeviceConsumeBudget – Tuya MiniApp

getDeviceConsumeBudget(params: GetDeviceConsumeBudgetParams)

Requires:

@tuya-miniapp/cloud-api≥1.3.0

Additional notesRead the full notes

This API relies on cloud capabilities. You must grant authorization in Development Settings - Cloud Capabilities on the Mini App Developer Platform. Before using this API, ensure the device’s product has enabled the **Energy Statistics** advanced capability on the Tuya IoT Development Platform. Products without this capability cannot collect energy consumption/cost data; the API will return empty data or an error. To use this feature, create a product with energy consumption/cost statistics and enable the corresponding advanced capability in the product details.

Description

Query the device energy consumption budget list. Only budget items with energyAction set to consume are returned. Can be used to display budget progress or threshold alerts in the UI.

Parameters

Parameter	Type	Required	Description
		Yes	Request parameters

Return Value

Type: Promise<GetDeviceConsumeBudgetResult>

Energy consumption budget list (energyAction is fixed to consume). Each item includes dateType (budget dimension: day/week/month), budget (budget value, unit kWh), entityId (device ID), etc. If a dimension is not set, it is omitted from the list.

Referenced Types

typeGetDeviceConsumeBudgetResult`getDeviceConsumeBudget` return value, electricity consumption budget list

export type GetDeviceConsumeBudgetResult = DeviceBudget[];

interfaceDeviceBudget

Property	Type	Description
`bizId`	string	Business ID
`budget`	string	Budget value; unit depends on `energyAction` (kWh or currency)
`dateType`	BudgetDataType	Budget time dimension
`energyAction`	EnergyAction	Energy action type (`consume` or `cost`)
`entityId`	string	Entity ID (i.e., device ID)
`entityType`	string	Entity type
`projectId`	string	Project ID
`projectType`	string	Project type

enumBudgetDataType

Value	Actual Value	Description
`BudgetDataType.Day`	`day`	Daily
`BudgetDataType.Week`	`week`	Weekly
`BudgetDataType.Month`	`month`	Monthly

enumEnergyAction

Value	Actual Value	Description
`EnergyAction.Cost`	`cost`	Electricity cost
`EnergyAction.Consume`	`consume`	Electricity consumption

Examples

Request example

import { getDeviceConsumeBudget } from '@tuya-miniapp/cloud-api';

getDeviceConsumeBudget({ devId: 'vdevo123' })
  .then(result => {
    result.forEach(item => {
      console.log(`${item.dateType} consumption budget: ${item.budget} kWh`);
    });
  })
  .catch(error => {
    console.error('Failed to query consumption budget:', error);
  });

Response example

[
  {
    "dateType": "day",
    "budget": "5",
    "energyAction": "consume",
    "bizId": "biz_001",
    "entityId": "vdevo123",
    "entityType": "device",
    "projectId": "proj_001",
    "projectType": "smartenergy"
  },
  {
    "dateType": "month",
    "budget": "80",
    "energyAction": "consume",
    "bizId": "biz_002",
    "entityId": "vdevo123",
    "entityType": "device",
    "projectId": "proj_001",
    "projectType": "smartenergy"
  }
]

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.