GET Runtime Report

URL: /runtimeReport

Accessible by: Smart, EMS, Utility accounts.

Retrieves the historical runtime report 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).

API USAGE LIMITS

  • 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.

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
columns 1 String Yes A CSV string of column names. See Report Columns. No spaces in CSV.
includeSensors 1 Boolean No Whether to include sensor runtime report data for those thermostats which have it. Default: false.

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.
columns 1 String The CSV list of column names from the request.
reportList 1 RuntimeReport [] A list of runtime reports.
sensorList 1 RuntimeSensorReport [] A list of runtime sensor reports. Will be empty unless requested.

Report Columns

The report requires that the relevant columns of interest be specified in the request. The columns will be returned in the order specified.

The following columns are supported:

Column Name Units / Value Description
auxHeat1 Seconds The auxiliary heat runtime.
auxHeat2 Seconds The auxiliary 2nd stage heat runtime.
auxHeat3 Seconds The auxiliary 3rd stage heat runtime.
compCool1 Seconds The compressor cool runtime.
compCool2 Seconds The compressor 2nd stage cool runtime.
compHeat1 Seconds The compressor heat runtime.
compHeat2 Seconds The compressor 2nd stage heat runtime.
dehumidifier Seconds The dehumidifier runtime.
dmOffset Degrees F The Demand Management temperature adjustment value the thermostat applied to the desired temperature.
economizer Seconds The economizer runtime.
fan Seconds The fan runtime.
humidifier Seconds The humidifier runtime.
hvacMode Hvac Mode The Mode the system was in. Values: auto, auxHeatOnly, cool, heat, off.
outdoorHumidity % The outdoor humidity.
outdoorTemp Degrees F The outdoor temperature.
sky Integer The sky cover.
ventilator Seconds The ventilator runtime.
wind km/h The wind speed.
zoneAveTemp Degrees F The recorded average temperature.
zoneCalendarEvent Name of Event The name of an event if one was running. Empty otherwise.
zoneClimate Name of Climate The name of the running climate.
zoneCoolTemp Degrees F The set cool temperature.
zoneHeatTemp Degrees F The set heat temperature.
zoneHumidity % The average humidity.
zoneHumidityHigh % The high humidity.
zoneHumidityLow % The low humidity.
zoneHvacMode System Mode *The mode the system was in. Values: heatStage10n, heatStage20n, heatStage30n, heatOff, compressorCoolStage10n, compressorCoolStage20n, compressorCoolOff, compressorHeatStage10n, compressorHeatStage20n, compressorHeatOff, economyCycle.
zoneOccupancy    

* Note: heatStage10n, heatStage20n, and heatStage30n are for auxiliary heating. compressorHeatStage10n and compressorHeatStage20n are for the heatpump.

The report information is stored in a CSV format and will contain the Date and Time in UTC as the first and second columns.

Example Request:

Request Body

NOTE: Request body is not encoded for example purposes.

HEADERS:
	Content-Type: application/json;charset=UTF-8
	Authorization: Bearer Rc7JE8P7XUgSCPogLOx2VLMfITqQQrjg
	
REQUEST:                               
	GET https://api.ecobee.com/1/runtimeReport?format=json&body={"startDate":"2010-01-01","endDate":"2010-01-02","columns":"zoneHvacMode,zoneCalendarEvent","selection":{"selectionType":"thermostats","selectionMatch":123456789012"}}
    			

The pretty formatted body of the request is:

{
	"startDate": "2010-01-01",
	"endDate": "2010-01-02",
	"columns": "zoneHvacMode,zoneCalendarEvent",
	"selection": { 
		"selectionType": "thermostats",
		"selectionMatch": "123456789012" 
	}
}    			
    			

Sample API Call

Show code sample in:
curl -s -H 'Content-Type: text/json' -H 'Authorization: Bearer ACCESS_TOKEN' 'https://api.ecobee.com/1/runtimeReport?format=json&body=\{"startDate":"2010-01-01","endDate":"2010-01-02","columns":"zoneHvacMode,zoneCalendarEvent","selection":\{"selectionType":"thermostats","selectionMatch":123456789012"\}\}'
				

Example Response:

{
    "startDate": "2010-01-01",
    "startInterval": 0,
    "endDate": "2010-01-02",
    "endInterval": 287,
    "columns": "zoneHVACmode,zoneCalendarEvent",
    "reportList": [
        {
            "thermostatIdentifier": "123456789012",
            "rowCount": 576,
            "rowList": [   
                "2010-01-01,00:00:00,heatOff,",
                "2010-01-01,00:05:00,heatOff,",
                "2010-01-01,00:10:00,heatOff,",
                "2010-01-01,00:15:00,heatOff,",
                "2010-01-01,00:20:00,heatOff,",
                "2010-01-01,00:25:00,heatOff,",
                "2010-01-01,00:30:00,heatOff,",
                "2010-01-01,00:35:00,heatOff,",
                "2010-01-01,00:40:00,heatOff,",
                "2010-01-01,00:45:00,heatOff,",
                ...snip...
                ]
        }
    ],
    "sensorList": [],
    "status": {
        "code": 0,
        "message": ""
    }
}             
    

Back To Top