GET Meter Report

URL: /meterReport

Accessible by: Smart, EMS, Utility accounts.

Restrictions: Thermostat needs to be paired with a ZigBee meter.

Retrieves the historical meter reading information for a selection of thermostats.

The data in the report is formatted as a time-series of 5 minute intervals for a whole day. There are 288 intervals per day. The values supplied for any given 5-minute interval is the value at the start of the interval and is not an average.

The report request is limited to retrieving information for up to 25 thermostats with a maximum period of 31 days, per request.

When making this request, ensure your client supports GZIP compression. The amount of data returned is considerable for 31 days of data for 25 thermostats (25 thermostats * 288 intervals per day * 31 days = 223,200 rows of data).


  • Use the Thermostat Summary (Polling) request to determine if the Runtime Revision value has changed before making repeated requests for runtime reports.
  • DO NOT request report data at an interval quicker than once every 15 minutes, which is the shortest interval at which report data can change. There may also be a delay of up to an hour before the most recent report data is made available via the API.
  • DO NOT have more than 1 open HTTP request for reports at any given time; wait until the ecobee server has responded before issuing additional API requests.

Report Start/End Intervals

Report data is stored in 5 minute intervals. To compute the desired interval, take the interval and multiply it by 5 (minutes). For example interval 0 is 00:00:00, interval 12 is 60min or 01:00:00 and interval 264 is 1320min or 22:00:00. See the What is a runtime interval? FAQ article for additional calculation help.

Report start & end intervals are based on UTC however the timestamps in the report data are in thermostat time.

Report Dates & Times

The times returned by the report are in thermostat time and Daylight Savings (DST) is applied to the date and time returned in the report if the thermostat's settings indicate that DST is enabled.

Report Temperature Readings

Temperature value readings will be returned in degrees F.

Utility Pricing Information

Utility pricing information is defined by the utility. If none is available, pricing and tier information will be unavailable.

Request Properties

Property Version Type Required Description
selection 1 Object Yes The Selection Object. Must be selectionType = 'thermostats' and selectionMatch = a CSV of thermostat identifiers.
startDate 1 Date Yes The UTC report start date.
startInterval 1 Integer No The 5 minute interval to begin the report on. The interval can be determined by multiplying the interval by 5. Range: 0-287 Default: 0
endDate 1 Date Yes The UTC report end date.
endInterval 1 Integer No The 5 minute interval to end the report on. The interval can be determined by multiplying the interval by 5. Range: 0-287 Default: 287
meters 1 String Yes A CSV string of meter types. See Meter Types

Response Properties

Property Version Type Description
startDate 1 Date The report UTC start date.
startInterval 1 Integer The report start interval.
endDate 1 Date The report UTC end date.
endInterval 1 Integer The report end interval.
meters 1 String The CSV list of meter types from the request.
reportList 1 MeterReport [] A list of thermostat meter reports.

Meter Types

The following meter types are supported:

Column Name Description
energy Energy meter

Meter Data Columns

The following columns may be returned in the report data.

Column Name Data Type Units Description
date Date n/a The date in thermostat local time.
time Time n/a The time in thermostat local time.
tier String n/a The tier name or empty value if no tier pricing has been defined by the utility.
energyConsumption Float kWh The energy consumption as reported by the meter in the interval period.
energyCost Float $0.01 (cents) The energy cost will only appear only if the utility has defined tier pricing information. Cost is for the interval period.

Example Request:

Request Body

NOTE: Request body is not encoded for example purposes.

	Content-Type: application/json;charset=UTF-8
	Authorization: Bearer Rc7JE8P7XUgSCPogLOx2VLMfITqQQrjg
	GET{"startDate": "2010-01-01","endDate": "2010-01-02","meters": "energy","selection":{"selectionType":"thermostats","selectionMatch":"123456789012"}}

The pretty formatted body of the request is:

	"startDate": "2013-04-04",
	"endDate": "2013-04-04",
	"meters": "energy",
	"selection": { 
		"selectionType": "thermostats",
		"selectionMatch": "123456789012" 

Sample API Call

Show code sample in:
curl -s -H 'Content-Type: text/json' -H 'Authorization: Bearer ACCESS_TOKEN' '\{"startDate":"2010-01-01","endDate":"2010-01-02","meters":"energy","selection":\{"selectionType":"thermostats","selectionMatch":"123456789012"\}\}'

Example Response:


Back To Top