ecobee API: A Developer's Guide to Smart Thermostat Integration

Learn how to use the ecobee API to read thermostat data, manage settings, and build smart home automations. Includes token handling, example requests, error handling, and best practices for secure, production-ready integrations.

Thermostat Care Team

April 25, 2026·5 min read

Ecobee Thermostat Thermostat Setup Thermostat Maintenance Smart Home Thermostat

Quick AnswerDefinition

The ecobee API is a RESTful interface that lets apps read thermostat data, query status, and issue configuration changes to Ecobee devices. According to Thermostat Care, it relies on OAuth 2.0 for access tokens and uses endpoints like /1/thermostat to fetch data. Developers can build custom dashboards, automations, and energy-saving workflows by integrating ecobee API calls into their apps.

What is the ecobee API and why it matters

The ecobee API provides programmatic access to Ecobee thermostats, enabling developers to read current temperatures, runtime data, and settings, and to push changes such as hold actions. This is essential for building custom dashboards, energy analytics, or home automation rules. According to Thermostat Care, the API is RESTful and relies on OAuth 2.0 for authorization. The most commonly used endpoint is /1/thermostat, which returns thermostat objects and their nested attributes.

Python

# Example: Read thermostat data using the ecobee API (pseudo-implementation)
import requests

ACCESS_TOKEN = 'YOUR_ACCESS_TOKEN'
headers = {'Authorization': f'Bearer {ACCESS_TOKEN}'}
params = {'json': '{"selection": {"selectionType": "registered", "includeRuntime": true}}'}
resp = requests.get('https://api.ecobee.com/1/thermostat', headers=headers, params=params)
print(resp.json())

Bash

# Alternative: cURL to fetch thermostat data
curl -X GET 'https://api.ecobee.com/1/thermostat?json={"selection":{"selectionType":"registered","includeRuntime":true}}' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Workflows you can build: live dashboards, energy analytics, and automation that reacts to runtime changes. Always secure tokens and validate responses before acting on data.

Practical authentication and token management

This section introduces how to obtain and refresh OAuth 2.0 tokens for the ecobee API, plus best practices for storing credentials. The flow typically starts with obtaining a code via user consent, then exchanging it for access and refresh tokens. You should rotate tokens regularly and handle expirations gracefully in production apps.

Python

# Exchange authorization code for tokens (Python)
import requests

token_url = 'https://api.ecobee.com/oauth/token'
payload = {
  'grant_type': 'authorization_code',
  'code': 'AUTH_CODE',
  'client_id': 'YOUR_CLIENT_ID',
  'redirect_uri': 'https://yourapp.example.com/callback'
}
resp = requests.post(token_url, data=payload)
print(resp.json())

Bash

# Refresh the access token (shell)
curl -X POST https://api.ecobee.com/oauth/token \
  -d 'grant_type=refresh_token&refresh_token=REFRESH_TOKEN&client_id=YOUR_CLIENT_ID' \
  -H 'Content-Type: application/x-www-form-urlencoded'

Why this matters? Secure token storage, proper redirect handling, and renewing tokens before expiry prevent disruptions in automation workflows.

Making requests: reading thermostat data

Once you have a valid access token, you can query thermostat data to power dashboards and automations. The ecobee API accepts a JSON payload that specifies the selection criteria for devices. You can request runtime, settings, and energy usage in a single call, which minimizes round trips and keeps apps responsive.

Python

# Read thermostats with runtime and settings
import requests

ACCESS_TOKEN = 'YOUR_ACCESS_TOKEN'
headers = {'Authorization': f'Bearer {ACCESS_TOKEN}'}
payload = {'json': '{"selection": {"selectionType": "registered", "includeRuntime": true, "includeSettings": true}}'}
resp = requests.get('https://api.ecobee.com/1/thermostat', headers=headers, params=payload)
print(resp.json())

Bash

# Quick test with curl
curl -X GET 'https://api.ecobee.com/1/thermostat?json={"selection":{"selectionType":"registered","includeRuntime":true,"includeSettings":true}}' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

What you’ll see: a JSON payload with thermostat objects, their current states, runtime details, and user settings. Variants may include more fields if you request them explicitly.

Updating thermostat settings and actions

Updating a thermostat often involves sending a function or settings payload that changes modes, holds, or setpoints. The ecobee API supports functions such as setting a hold duration or changing HVAC modes. This capability enables automated control from your app, but requires careful validation to avoid unexpected temperature swings.

Python

# Example: Pause auto mode for a hold duration (Python)
import requests

ACCESS_TOKEN = 'YOUR_ACCESS_TOKEN'
headers = {'Authorization': f'Bearer {ACCESS_TOKEN}'}
payload = {
  'json': '{"selection": {"selectionType": "registered"}, "functions": [{"type": "setHoldHours", "holdHours": 4}]}'
}
resp = requests.post('https://api.ecobee.com/1/thermostat', headers=headers, data=payload)
print(resp.json())

Bash

# Alternative update with curl (holding for 6 hours)
curl -X POST 'https://api.ecobee.com/1/thermostat' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -d '{"json": "{\"selection\":{\"selectionType\":\"registered\"},\"functions\":[{\"type\":\"setHoldHours\",\"holdHours\":6}]}"}'

Tips for updating safely: validate payloads, log changes, and consider implementing a dry-run mode before applying settings to production thermostats.

Handling errors, rate limits, and retries

API calls can fail for authentication, network, or server-side reasons. Implement robust error handling with exponential backoff, and respect ecobee’s guidelines for rate limits to avoid temporary blocks. Always inspect the error payload for codes and messages to tailor retry logic.

Python

# Basic retry with backoff (Python)
import requests, time

def fetch_with_retry(url, headers, max_retries=3):
  for attempt in range(1, max_retries + 1):
    resp = requests.get(url, headers=headers)
    if resp.status_code == 200:
      return resp.json()
    time.sleep(2 ** attempt)
  raise Exception('Max retries reached')

ACCESS_TOKEN = 'YOUR_ACCESS_TOKEN'
headers = {'Authorization': f'Bearer {ACCESS_TOKEN}'}
print(fetch_with_retry('https://api.ecobee.com/1/thermostat?json={"selection": {"selectionType": "registered"}}', headers))

Bash

# Curl with simple retry loop (bash)
for i in {1..3}; do
  http_status=$(curl -s -o /dev/null -w "%{http_code}" -X GET 'https://api.ecobee.com/1/thermostat?json={"selection": {"selectionType": "registered"}}' \
    -H 'Authorization: Bearer YOUR_ACCESS_TOKEN')
  if [ "$http_status" = "200" ]; then break; fi
  sleep $((2 ** i))
done

Common errors to handle: 401 for expired tokens, 429 for rate limits, 500/502 for temporary server issues. Centralize error handling and don’t retry on client-side mistakes.

End-to-end example: from auth to data fetch

This section walks through a complete, minimal flow: obtain tokens, query thermostats, and display a lightweight summary. The end-to-end approach helps you validate connectivity and permissions before building larger automations. Start by acquiring a token via the OAuth flow, then call the /1/thermostat endpoint with a registered selection. Finally, parse the response and present key metrics (temperature, hold state, runtime).

Python

# End-to-end sample (pseudo-steps)
import requests

# 1) Obtain tokens (assumes you already have a code)
# 2) Use access token to fetch data
headers = {'Authorization': 'Bearer YOUR_ACCESS_TOKEN'}
params = {'json': '{"selection": {"selectionType": "registered"}}'}
resp = requests.get('https://api.ecobee.com/1/thermostat', headers=headers, params=params)
thermostats = resp.json().get('thermostatList', [])
for t in thermostats:
  name = t.get('name')
  temp = t.get('coolingSetpoint') or 'N/A'
  print(f"{name}: setpoint={temp}")

Bash

# Quick one-liner for the same flow
curl -s -X GET 'https://api.ecobee.com/1/thermostat?json={"selection":{"selectionType":"registered"}}' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' | jq '.thermostatList[] | {name, runtime}'

End-to-end testing tips: run calls against a test account, log the response shape, and iterate on the UI layer before implementing full automation.

Security, testing, and deployment best practices

Security and reliability are paramount when integrating with smart home devices. Use environment variables or secret managers for tokens, implement token rotation, and isolate development tokens from production. Test every endpoint, handle edge cases like devices without runtime data, and document the API usage in your project to support future maintenance.

Python

# Store credentials securely (example)
import os
CLIENT_ID = os.environ.get('ECOBEE_CLIENT_ID')
ACCESS_TOKEN = os.environ.get('ECOBEE_ACCESS_TOKEN')
print(CLIENT_ID is not None and ACCESS_TOKEN is not None)

Bash

# Run a quick health check against the API (no sensitive data in logs)
curl -s -X GET 'https://api.ecobee.com/1/thermostat?json={"selection": {"selectionType": "registered"}}' \
  -H "Authorization: Bearer $ECOBEE_ACCESS_TOKEN" | head -n 5

Operational notes: maintain an audit trail of changes, rotate credentials periodically, and review error logs to identify patterns that require throttling or feature flags in your app.

Practical tips and variations

Every integration varies by platform and use case, so consider these practical variations:

Use server-side storage for tokens; never persist them in client apps.
Implement a fall-back strategy if a thermostat is offline, showing stale data with a clear hint.
Apply semantic versioning to your API client so downstream apps can upgrade smoothly.

Python

# Environment-based config (Python)
import os
API_BASE = 'https://api.ecobee.com'
TOKEN = os.environ.get('ECOBEE_TOKEN')
print(API_BASE, bool(TOKEN))

Bash

# A small, repeatable test using curl and jq (if available)
curl -sS -X GET 'https://api.ecobee.com/1/thermostat?json={"selection": {"selectionType": "registered"}}' \
  -H "Authorization: Bearer $ECOBEE_TOKEN" | jq '.thermostatList[0] | {name, hvacMode}'

By combining these approaches, you can deliver robust, maintainable integrations that empower energy-aware automation across devices.

Final notes on integration strategy

Building with the ecobee API is a balance between capability and reliability. Start with read-only data to validate connectivity, then progressively add write capabilities with strong validation. Keep security top of mind, and align your implementation with the broader smart home architecture you’re building. This approach minimizes risk and accelerates time-to-value for developers and homeowners alike.

Steps

Estimated time: 30-45 minutes

1
Register your app with Ecobee
Create a developer account and obtain client_id and client_secret. Define your redirect URI for the OAuth flow and scope. This establishes your identity with the ecobee API.
Tip: Document credentials securely; never commit them to source control.
2
Request user authorization
Direct the user to authorize your app to access their thermostats. Capture the authorization code from the redirect.
Tip: Use a dedicated, least-privilege OAuth scope for best practices.
3
Exchange code for tokens
Send a token request to obtain access_token and refresh_token. Store tokens securely and set token expiry awareness in your app.
Tip: Prefer server-side token exchange to keep secrets safe.
4
Make your first data call
Call /1/thermostat with a registered selection to fetch current state and runtime.
Tip: Check response structure and handle missing fields gracefully.
5
Update thermostat settings
Implement a safe update path using ecobee functions to adjust hold or mode. Validate inputs before sending to the API.
Tip: Test changes in a non-production thermostat if possible.
6
Handle errors and retries
Add robust error handling with retries and exponential backoff for transient issues.
Tip: Log errors with request details but avoid exposing sensitive data.

Pro Tip: Store tokens in environment variables or a secrets manager rather than in code.

Warning: Never expose access tokens in client-side code or public repos.

Note: Test with a small subset of devices before scaling to multiple thermostats.

Pro Tip: Enable rate-limit awareness in your client to avoid 429 responses.

Prerequisites

Required

Python 3.8+↗
Required
pip package manager↗
Required
Requests library (pip install requests)↗
Required
Ecobee developer account and client credentials↗
Required
Basic OAuth 2.0 knowledge
Required
A thermostat registered to your ecobee account
Required

Optional

cURL or Postman for testing↗
Optional

Commands

Action	Command
Obtain authorization code (manual flow)Used to initiate the OAuth 2.0 authorization code flow from server-side apps	`curl -X POST https://api.ecobee.com/oauth/token -d 'grant_type=authorization_code&code=AUTH_CODE&client_id=CLIENT_ID&redirect_uri=YOUR_URI' -H 'Content-Type: application/x-www-form-urlencoded'`
Exchange code for tokensObtain access_token and refresh_token	`curl -X POST https://api.ecobee.com/oauth/token -d 'grant_type=authorization_code&code=AUTH_CODE&client_id=CLIENT_ID&client_secret=CLIENT_SECRET' -H 'Content-Type: application/x-www-form-urlencoded'`
Refresh access tokenUse when access_token expires	`curl -X POST https://api.ecobee.com/oauth/token -d 'grant_type=refresh_token&refresh_token=REFRESH_TOKEN&client_id=CLIENT_ID' -H 'Content-Type: application/x-www-form-urlencoded'`
Fetch thermostat dataRead current state, runtime, and settings	`curl -X GET 'https://api.ecobee.com/1/thermostat?json={"selection":{"selectionType":"registered","includeRuntime":true,"includeSettings":true}}' -H 'Authorization: Bearer ACCESS_TOKEN'`

Questions & Answers

What is the ecobee API and what can I do with it?

The ecobee API provides a RESTful interface to read thermostat data, fetch runtime, and adjust settings on Ecobee devices. It enables developers to build dashboards, automations, and energy-saving workflows that react to real-time thermostat information. You’ll authenticate with OAuth 2.0 and use endpoints like /1/thermostat.

Do I need a paid plan to use the ecobee API?

Access to the ecobee API requires a developer account and credentials. There are no paid API tiers disclosed publicly for basic access, but production usage should comply with Ecobee’s terms and usage limits. Always review the official docs for current terms.

How do I obtain an access token?

Obtain authorization code via user consent, then exchange it for access and refresh tokens using the OAuth token endpoint. Store tokens securely and refresh before expiry to maintain uninterrupted access.

What data can I access with /1/thermostat?

You can fetch a range of data including current temperature, setpoints, HVAC mode, and runtime details. Use the selection object to limit which thermostats are returned and consider includeRuntime/includeSettings to tailor the payload.

Is it secure to store tokens in environment variables?

Yes, storing tokens in environment variables or a secrets manager is a standard practice. Never commit tokens to source control, and rotate credentials periodically.

How should I test ecobee API integrations?

Test against a development or staging account first. Use verbose logging, validate responses, and simulate token expiry to confirm your retry logic. Reference the Thermostat Care guidelines for best practices.

Can I control multiple thermostats with one app?

Yes. Use the selection object to target all registered devices or specify a subset. Ensure your app handles per-device responses and potential partial failures gracefully.

What to Remember

Register an Ecobee developer app and obtain credentials.
Use OAuth 2.0 to securely obtain access tokens.
Read data with /1/thermostat using a registered selection.
Update settings via functions and validate inputs.
Implement robust error handling and secure token storage.

← More in Smart Thermostats

What is the ecobee API and why it matters

Practical authentication and token management

Making requests: reading thermostat data

Updating thermostat settings and actions

Handling errors, rate limits, and retries

End-to-end example: from auth to data fetch

Security, testing, and deployment best practices

Practical tips and variations

Final notes on integration strategy

Steps

Register your app with Ecobee

Request user authorization

Exchange code for tokens

Make your first data call

Update thermostat settings

Handle errors and retries

Prerequisites

Commands

Questions & Answers

What to Remember

Related Articles