GET Runtime Report
URL: /runtimeReport
Accessible by: Smart and EMS 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
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": ""
}
}