Previous Example

Example 13: Retrieving a historical runtime report

Note on token authentication:

If you have completed the authentication process from Example 1, your access token will be pre-populated in all requests throughout every example.

To specify a different access token, please paste it in the form below and press 'Update'. Alternatively, you can go back to the first example here to re-authenticate. Doing either will save your access token for all future examples.

Access Token:

In this example, we will demonstrate how to obtain historical runtime data from the thermostat. This is accomplished through the GET Runtime Report request.

We will retrieve the heat, cool, and fan run durations, along with the outdoor temperature, and the indoor average temperature between 2015-01-01 to 2015-01-03. Note that the date and time stamp of the requests are in UTC time. Remember to replace the thermostat identifier below with your actual thermostat identifier. 

curl -s --request GET -H "Content-Type: application/json;charset=UTF-8" -H "Authorization: Bearer ACCESS_TOKEN" 'https://api.ecobee.com/1/runtimeReport?format=json&body=\{"startDate":"2015-01-01","endDate":"2015-01-03","columns":"auxHeat1,compCool1,fan,outdoorTemp,zoneAveTemp","selection":\{"selectionType":"thermostats","selectionMatch":"318324702718"\}\}'

The results are tabulated in the rowList property. The property is an array, with each element within the array representing the fetched metrics for a 5 seconds time slot. For each time slot, a comma separated values string denotes the date and time of the time slot followed by the requested metrics.

Note that request date and time are in UTC while the response date and time are in thermostat time.

{
  "columns": "auxHeat1,compCool1,fan,outdoorTemp,zoneAveTemp",
  "reportList": [
    {
      "thermostatIdentifier": "318324702718",
      "rowCount": 863,
      "rowList": [
        "2014-12-31,19:00:00,0,0,0,17.6,71.6,",
        "2014-12-31,19:05:00,0,0,0,17.6,71.7,",
        "2014-12-31,19:10:00,0,0,0,17.6,71.6,",
        "2014-12-31,19:15:00,0,0,0,17.6,71.5,",
        "2014-12-31,19:20:00,0,0,0,17.6,71.5,",
        "2014-12-31,19:25:00,0,0,0,17.6,71.5,",
        "2014-12-31,19:30:00,0,0,0,17.6,71.4,",
        "2014-12-31,19:35:00,0,0,0,17.6,71.1,",
        "2014-12-31,19:40:00,0,0,0,17.6,69.6,",
        "2014-12-31,19:45:00,0,0,0,17.6,69.5,",
        "2014-12-31,19:50:00,0,0,0,17.6,69.5,",
        "2014-12-31,19:55:00,30,0,30,17.6,69.4,",
        "2014-12-31,20:00:00,300,0,300,17.6,68.9,",
        "2014-12-31,20:05:00,300,0,300,17.6,68.3,",
        "2014-12-31,20:10:00,300,0,300,17.6,68.4,",        
		...snipped...
        "2015-01-03,17:50:00,300,0,300,32,69.4,",
        "2015-01-03,17:55:00,165,0,210,32,69.7,",
        "2015-01-03,18:00:00,0,0,0,32,70.3,",
        "2015-01-03,18:05:00,0,0,0,32,70.9,",
        "2015-01-03,18:10:00,0,0,0,32,70.9,",
        "2015-01-03,18:15:00,0,0,0,32,70.9,",
        "2015-01-03,18:20:00,0,0,0,32,71.1,",
        "2015-01-03,18:25:00,0,0,0,32,71.3,",
        "2015-01-03,18:30:00,0,0,0,32,71.6,",
        "2015-01-03,18:35:00,0,0,0,32,70.6,",
        "2015-01-03,18:40:00,0,0,0,32,70.3,",
        "2015-01-03,18:45:00,0,0,0,32,70.2,",
        "2015-01-03,18:50:00,0,0,0,32,70.1,"
      ]
    }
  ],
  "sensorList": [],
  "startDate": "2015-01-01",
  "endDate": "2015-01-03",
  "status": {
    "code": 0,
    "message": ""
  }
}

For exmple, the row: 

"2014-12-31,19:55:00,30,0,30,17.6,69.4,"

Represents the time slot at 7:55pm on December 31, 2014 thermostat time. The heating and fan was on for 30 seconds within this 5 minutes time slot. The outside temperature was 17.6℉ and the average indoor temperature was 69.4℉.

Congratulations, you have now reached the end of all the examples. Feel free to run any of our Sample Apps or visit our API Documentation pages to gain further knowledge.

Previous Example