GET Thermostats

URL: /thermostat

Accessible by: Smart, EMS, Utility accounts.

Retrieves a selection of thermostat data for one or more thermostats. The type of data retrieved is determined by the Selection object in the request. The include* properties of the selection retrieve specific portions of the thermostat. When retrieving thermostats, request only the parts of the thermostat you require as the whole thermostat with everything can be quite large and generally unnecessary.

API USAGE LIMITS

  • Use /thermostatSummary to poll for changes in thermostat state; DO NOT poll using /thermostat.
  • DO NOT have more than 2-3 open HTTP requests with the ecobee API at any given time; wait until the ecobee server has responded before issuing additional API requests.
  • If you are a Utility or EMS account and you are using management sets as your selection target, DO NOT have more than 1 open HTTP request with the ecobee API at any given time; wait until the ecobee server has responded before issuing additional API requests.

Utility Restrictions

GET Thermostat calls made by Utility users are restricted to certain include* properties of the Selection object to protect the Thermostat owner's private information. For more information see the Selection object for a list.

Request Properties

Property Version Type Read Only Required Description
selection 1 Selection No Yes The selection criteria for update.
page 1 Page No No The page object if requesting subsequent page. Just the page property is need to indicate the page requested.

Response Properties

Property Version Type Read Only Required Description
page 1 Page Yes n/a The page information for the response.
thermostatList 1 Thermostat [] Yes n/a The list of thermostats returned by the request.
status 1 Status Yes n/a The api response code.

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/thermostat?json={"selection":{"includeAlerts":"true","selectionType":"registered","selectionMatch":"","includeEvents":"true","includeSettings":"true","includeRuntime":"true"}}
    			

Sample API Call

Show code sample in:
curl -s -H 'Content-Type: text/json' -H 'Authorization: Bearer ACCESS_TOKEN' 'https://api.ecobee.com/1/thermostat?json=\{"selection":\{"includeAlerts":"true","selectionType":"registered","selectionMatch":"","includeEvents":"true","includeSettings":"true","includeRuntime":"true"\}\}'
				

Example Response:

{
    "page": {
        "page": 1,
        "totalPages": 1,
        "pageSize": 1,
        "total": 1
    },
    "thermostatList": [
        {
            "identifier": "161775386723",
            "name": "",
            "thermostatRev": "110128234025",
            "isRegistered": true,
            "modelNumber": "Smart",
            "serialNumber": "1",
            "productCode": "1",
            "lastModified": "2011-01-28 23:40:25",
            "alerts": [],
            "settings": {
                "hvacMode": "heat",
                "lastServiceDate": "2011-01-28",
                "serviceRemindMe": false,
                ...snip...
        }
    ],
    "status": {
        "code": 0,
        "message": ""
   	}
}
    

Back To Top