Usage History - Usage Retrieval (System/Tenant/Zone/Room)

Get Usage for a system using a Specific Date

GET

http://localhost:8080

/api/usage-history/date/system-id/{systemId}

Get Usage for a system using a Specific Date › path Parameters

systemId

string · required

Get Usage for a system using a Specific Date › query Parameters

date

string · required

Get Usage for a system using a Specific Date › Responses

Returns usage for a system and date.

UsageHistoryHour[]

UsageHistoryHour

_id

string · required

Primary ID of the UsageHistoryHour

Example: 64b7f1e6f9c9d4e5b8a9f7c3

hour

number · required

No. What Hour (E.g. 7 means 0700 - 0800)

Example: 7

onStatus

string · enum · required

Status of the Plug (ON / OFF)

Enum values:

OFF

INACTIVE

ERROR

ACTIVE

Example: ON

deviceType

string · enum · required

Type of device (PLUG, MCB, etc.)

Enum values:

PLUG

MCB

ENV_SENSOR

SMART_SWITCH

AIRCON_CONTROL

WATER_METER

Example: PLUG

createdAt

string · date-time · required

Date Time of the Creation

Example: 2021-09-01

updatedAt

string · date-time · required

Date Time of the Update

Example: 2021-09-01

actualDate

string · date-time · required

Date Time of the Update

Example: 2021-09-01

macId

string · required

MAC ID of the device

Example: 1092384701928347

device

string · required

Reference to the device

Example: 64b7f1e6f9c9d4e5b8a9f7c3

wifiStrength

number

WiFi signal strength at the time of the hourly record

Example: -65

Get Energy Usage for a system within a date range.

GET

http://localhost:8080

/api/usage-history/date-range/system/{systemId}

Get Energy Usage for a system within a date range. › path Parameters

systemId

string · required

Get Energy Usage for a system within a date range. › query Parameters

from

string · required

till

string · required

Get Energy Usage for a system within a date range. › Responses

Returns a list of energy usage with cost for the last X days for a system.

UsageHistoryDayWithCostBreakdownDto[]

UsageHistoryDayWithCostBreakdownDto

date

string · required

No. Hour of the Usage History

Example: 2023-03-15

totalEnergyUsage

number · required

Total Energy Usage in a Day (kWh)

Example: 12.48

cost

number · required

Energy cost for this day in dollars. Zero (0) if no tariff rate is configured for this day.

Example: 23.1

tariffRate

number | null

Tariff rate applied for this day in cents per kWh/L. Null if no tariff rate is configured.

Example: 10

Get Accumulated Energy Usage across all systems within a date range

GET

http://localhost:8080

/api/usage-history/date-range/accumulated

Returns aggregated energy usage data for all systems combined, summed up by day. This endpoint provides platform-wide energy consumption statistics. Optionally filter by device type (PLUG, MCB, IAQ_SENSOR). Requires SUPERADMIN or ADMIN role.

Get Accumulated Energy Usage across all systems within a date range › query Parameters

from

string · required

till

string · required

Get Accumulated Energy Usage across all systems within a date range › Responses

Accumulated usage data retrieved successfully

UsageHistoryDayBreakdownDto[]

UsageHistoryDayBreakdownDto

date

string · required

No. Hour of the Usage History

Example: 2023-03-15

totalEnergyUsage

number · required

Total Energy Usage in a Day (kWh)

Example: 12.48

Get Energy Usage for a tenant within a date range

GET

http://localhost:8080

/api/usage-history/date-range/tenant/{tenantId}

Get Energy Usage for a tenant within a date range › path Parameters

tenantId

string · required

Get Energy Usage for a tenant within a date range › query Parameters

from

string · required

till

string · required

Get Energy Usage for a tenant within a date range › Responses

Returns a list of energy usage with cost for a tenant within a date range.

UsageHistoryDayWithCostBreakdownDto[]

UsageHistoryDayWithCostBreakdownDto

date

string · required

No. Hour of the Usage History

Example: 2023-03-15

totalEnergyUsage

number · required

Total Energy Usage in a Day (kWh)

Example: 12.48

cost

number · required

Energy cost for this day in dollars. Zero (0) if no tariff rate is configured for this day.

Example: 23.1

tariffRate

number | null

Tariff rate applied for this day in cents per kWh/L. Null if no tariff rate is configured.

Example: 10

Get Energy Usage for a zone within a date range

GET

http://localhost:8080

/api/usage-history/date-range/zone/{zoneId}

Get Energy Usage for a zone within a date range › path Parameters

zoneId

string · required

Get Energy Usage for a zone within a date range › query Parameters

from

string · required

till

string · required

Get Energy Usage for a zone within a date range › Responses

Returns a list of energy usage with cost for a zone within a date range.

UsageHistoryDayWithCostBreakdownDto[]

UsageHistoryDayWithCostBreakdownDto

date

string · required

No. Hour of the Usage History

Example: 2023-03-15

totalEnergyUsage

number · required

Total Energy Usage in a Day (kWh)

Example: 12.48

cost

number · required

Energy cost for this day in dollars. Zero (0) if no tariff rate is configured for this day.

Example: 23.1

tariffRate

number | null

Tariff rate applied for this day in cents per kWh/L. Null if no tariff rate is configured.

Example: 10

Get Energy Usage for a room within a date range

GET

http://localhost:8080

/api/usage-history/date-range/room/{roomId}

Get Energy Usage for a room within a date range › path Parameters

roomId

string · required

Get Energy Usage for a room within a date range › query Parameters

from

string · required

till

string · required

Get Energy Usage for a room within a date range › Responses

Returns a list of energy usage with cost for the last X days for a room.

UsageHistoryDayWithCostBreakdownDto[]

UsageHistoryDayWithCostBreakdownDto

date

string · required

No. Hour of the Usage History

Example: 2023-03-15

totalEnergyUsage

number · required

Total Energy Usage in a Day (kWh)

Example: 12.48

cost

number · required

Energy cost for this day in dollars. Zero (0) if no tariff rate is configured for this day.

Example: 23.1

tariffRate

number | null

Tariff rate applied for this day in cents per kWh/L. Null if no tariff rate is configured.

Example: 10

Get Usage for a system using a Specific Date Range

GET

http://localhost:8080

/api/usage-history/date-range/system-id/{systemId}

Get Usage for a system using a Specific Date Range › path Parameters

systemId

string · required

Get Usage for a system using a Specific Date Range › query Parameters

from

string · required

till

string · required

Get Usage for a system using a Specific Date Range › Responses

200

Returns usage for a system and date.

number[]

Get summed realtime power for all MCBs in a room

GET

http://localhost:8080

/api/usage-history/date-range/realTime/room/{roomId}/mcb

Returns the aggregated total power for all MCB devices in the specified room within the given date range.

Get summed realtime power for all MCBs in a room › path Parameters

roomId

string · required

Get summed realtime power for all MCBs in a room › query Parameters

from

string · required

till

string · required

Get summed realtime power for all MCBs in a room › Responses

200

Summed realtime power for all MCBs in the room.

McbRoomRealtimeResponseDto

McbRealtimeSeriesDto[] · required

One time-series per MCB measurement type found in the room, plus a COMBINED series that sums all types

Get hourly usage for a system within a date range with current tariff rate

GET

http://localhost:8080

/api/usage-history/date-range/system-id/hour/{systemId}

Returns hourly usage breakdown and the current tariff rate for cost calculations.

Get hourly usage for a system within a date range with current tariff rate › path Parameters

systemId

string · required

Get hourly usage for a system within a date range with current tariff rate › query Parameters

from

string · required

till

string · required

Get hourly usage for a system within a date range with current tariff rate › Responses

200

Returns hourly usage data and current tariff rate for a system.

UsageHistoryHourWithTariffResponseDto

UsageHistoryHourBreakdownDto[] · required

Array of hourly usage data

Example: [{"hour":0,"totalEnergyUsage":1.2},{"hour":1,"totalEnergyUsage":1.5}]

currentTariffRate

number | null

Current tariff rate in cost per kWh. Null if no tariff rate is configured. Useful for frontend calculations.

Example: 0.25

Get hourly usage for a tenant within a date range with current tariff rate

GET

http://localhost:8080

/api/usage-history/date-range/tenant-id/hour/{tenantId}

Returns hourly usage breakdown and the current tariff rate for cost calculations.

Get hourly usage for a tenant within a date range with current tariff rate › path Parameters

tenantId

string · required

Get hourly usage for a tenant within a date range with current tariff rate › query Parameters

from

string · required

till

string · required

Get hourly usage for a tenant within a date range with current tariff rate › Responses

200

Returns hourly usage data and current tariff rate for a tenant.

UsageHistoryHourWithTariffResponseDto

UsageHistoryHourBreakdownDto[] · required

Array of hourly usage data

Example: [{"hour":0,"totalEnergyUsage":1.2},{"hour":1,"totalEnergyUsage":1.5}]

currentTariffRate

number | null

Current tariff rate in cost per kWh. Null if no tariff rate is configured. Useful for frontend calculations.

Example: 0.25

Get hourly usage for a zone within a date range with current tariff rate

GET

http://localhost:8080

/api/usage-history/date-range/zone-id/hour/{zoneId}

Returns hourly usage breakdown and the current tariff rate for cost calculations.

Get hourly usage for a zone within a date range with current tariff rate › path Parameters

zoneId

string · required

Get hourly usage for a zone within a date range with current tariff rate › query Parameters

from

string · required

till

string · required

Get hourly usage for a zone within a date range with current tariff rate › Responses

200

Returns hourly usage data and current tariff rate for a zone.

UsageHistoryHourWithTariffResponseDto

UsageHistoryHourBreakdownDto[] · required

Array of hourly usage data

Example: [{"hour":0,"totalEnergyUsage":1.2},{"hour":1,"totalEnergyUsage":1.5}]

currentTariffRate

number | null

Current tariff rate in cost per kWh. Null if no tariff rate is configured. Useful for frontend calculations.

Example: 0.25

Get hourly usage for a room within a date range with current tariff rate

GET

http://localhost:8080

/api/usage-history/date-range/room-id/hour/{roomId}

Returns hourly usage breakdown and the current tariff rate for cost calculations.

Get hourly usage for a room within a date range with current tariff rate › path Parameters

roomId

string · required

Get hourly usage for a room within a date range with current tariff rate › query Parameters

from

string · required

till

string · required

Get hourly usage for a room within a date range with current tariff rate › Responses

200

Returns hourly usage data and current tariff rate for a room.

UsageHistoryHourWithTariffResponseDto

UsageHistoryHourBreakdownDto[] · required

Array of hourly usage data

Example: [{"hour":0,"totalEnergyUsage":1.2},{"hour":1,"totalEnergyUsage":1.5}]

currentTariffRate

number | null

Current tariff rate in cost per kWh. Null if no tariff rate is configured. Useful for frontend calculations.

Example: 0.25

Get Usage and Energy Cost for a system from beginning to date

GET

http://localhost:8080

/api/usage-history/to-date/system-id/{systemId}

Returns total energy usage and calculated cost based on current tariff rate. Cost will be null if no tariff rate is configured for the system.

Get Usage and Energy Cost for a system from beginning to date › path Parameters

systemId

string · required

Get Usage and Energy Cost for a system from beginning to date › Responses

200

Returns usage, cost, and tariff rate for a system. Cost is calculated as totalEnergyUsage * tariffRate.

UsageWithCostResponseDto

totalEnergyUsage

number · required

Total energy usage in kWh

Example: 125.5

totalCost

number | null

Total cost based on current tariff rate. Null if no tariff rate is configured.

Example: 31.375

tariffRate

number | null

Current tariff rate in cost per kWh. Null if no tariff rate is configured.

Example: 0.25

Get Usage and Energy Cost for a tenant from beginning to date

GET

http://localhost:8080

/api/usage-history/to-date/tenant-id/{tenantId}

Returns total energy usage and calculated cost based on current tariff rate. Cost will be null if no tariff rate is configured for the system.

Get Usage and Energy Cost for a tenant from beginning to date › path Parameters

tenantId

string · required

Get Usage and Energy Cost for a tenant from beginning to date › Responses

200

Returns usage, cost, and tariff rate for a tenant. Cost is calculated as totalEnergyUsage * tariffRate.

UsageWithCostResponseDto

totalEnergyUsage

number · required

Total energy usage in kWh

Example: 125.5

totalCost

number | null

Total cost based on current tariff rate. Null if no tariff rate is configured.

Example: 31.375

tariffRate

number | null

Current tariff rate in cost per kWh. Null if no tariff rate is configured.

Example: 0.25

Get Usage and Energy Cost for a zone from beginning to date

GET

http://localhost:8080

/api/usage-history/to-date/zone-id/{zoneId}

Returns total energy usage and calculated cost based on current tariff rate. Cost will be null if no tariff rate is configured for the system.

Get Usage and Energy Cost for a zone from beginning to date › path Parameters

zoneId

string · required

Get Usage and Energy Cost for a zone from beginning to date › Responses

200

Returns usage, cost, and tariff rate for a zone. Cost is calculated as totalEnergyUsage * tariffRate.

UsageWithCostResponseDto

totalEnergyUsage

number · required

Total energy usage in kWh

Example: 125.5

totalCost

number | null

Total cost based on current tariff rate. Null if no tariff rate is configured.

Example: 31.375

tariffRate

number | null

Current tariff rate in cost per kWh. Null if no tariff rate is configured.

Example: 0.25

Get Usage and Energy Cost for a room from beginning to date

GET

http://localhost:8080

/api/usage-history/to-date/room-id/{roomId}

Returns total energy usage and calculated cost based on current tariff rate. Cost will be null if no tariff rate is configured for the system.

Get Usage and Energy Cost for a room from beginning to date › path Parameters

roomId

string · required

Get Usage and Energy Cost for a room from beginning to date › Responses

200

Returns usage, cost, and tariff rate for a room. Cost is calculated as totalEnergyUsage * tariffRate.

UsageWithCostResponseDto

totalEnergyUsage

number · required

Total energy usage in kWh

Example: 125.5

totalCost

number | null

Total cost based on current tariff rate. Null if no tariff rate is configured.

Example: 31.375

tariffRate

number | null

Current tariff rate in cost per kWh. Null if no tariff rate is configured.

Example: 0.25

Usage History - Device-Level Retrieval & Analytics Tenant - Management