Skip to content

Analytics ​

Analytics records how your accessories' characteristics change over time — temperature curves, humidity, light level, when doors opened, how long the heating ran — and turns them into charts you can browse room by room.

Analytics showing one room's lighting, temperature and humidity

It is off by default. Homecast does not store accessory states, sensor readings, or activity history unless you explicitly turn Analytics on for a home.

Where your data lives ​

EditionStorage
CommunityOnly on your own Mac (in the relay's local database). It never leaves your home.
CloudIn your Homecast Cloud account. You can export or delete it at any time; deleting your account deletes it too.

Turning it on ​

  1. Open Settings → Homes and pick a home
  2. In the Analytics section, turn on Analytics

Only the home's owner or an admin can change this switch. Once it is on, the section shows how much has been recorded so far.

Recording starts with sensible defaults: sensors (temperature, humidity, light, air quality), on/off states (lights, switches, motion, contact, locks), batteries, and modes (thermostat, security) are recorded; noisy characteristics like colour hue are off; metadata like accessory names and firmware versions is never recorded at all.

Recording is change-based: a value is stored only when it actually changes (with per-type minimum intervals and thresholds to absorb sensor jitter). A light that stays off all day costs nothing.

Seeing charts ​

One accessory ​

Open an accessory's Analytics to get a compact chart of everything it records:

  • With a mouse (Mac app, browser, Windows/Linux): right-click the tile → Analytics.
  • On touch (iPhone, iPad, Android): tap the tile to expand it, then tap Analytics in its action bar. A long press enters Edit Layout instead — touch has no context menus.

Numeric characteristics chart as lines; on/off and mode characteristics show as state timelines. Ranges run 6h · 24h · 7d · 30d · 1y · All (All covers the last two years). Open in Analytics takes you to the full-screen view, scoped to that accessory. Groups work the same way: the group tile opens the same popup with its members' data combined.

The Analytics option only appears on accessories with something recordable, in a home that is recording.

The whole home ​

Open the full-screen Analytics from the dashboard's top-right ⋯ menu (with a home or a room selected), from a home or room's right-click menu in the sidebar, or at /analytics. The address updates as you move around, so a view can be bookmarked or sent to anyone who already has access to the home.

Analytics is arranged around your home, not around data types:

  • The tree on the left lists the home, its room groups, rooms, and the accessories in each, with Across rooms for accessory groups. Type in Find a room or accessory to jump straight to one. On a phone, the tree opens from the ☰ button. If more than one of your homes records, you can switch between them here.
  • A home or room group shows one averaged line per room for each measure, with a line saying what it was built from ("9 rooms · averaged from 30 sensors").
  • A room stacks one panel per measure — Temperature, Humidity, Light, CO₂, Power, Energy, Battery, blinds, doors and windows, and so on — each captioned with its minimum, average and maximum. A Lighting panel counts how many lights were on, and an Activity panel shows motion, doors and locks as timelines with time-in-state totals. States that never left their resting value fold into one summary line.
  • An accessory shows each of its own characteristics. A group reads like one accessory with its members combined.
  • Virtual accessories record too — numbers and counters as lines, modes and timers as named-state timelines.

Pick a range (6h · 24h · 7d · 30d · 1y) in the top bar; it stays as you navigate. Hover a chart to see the same moment across every panel, click a line or legend entry to pin it, and use the chips on a panel (such as Targets or Humidity) to overlay related series. Zoom with the slider under the last chart.

Controlling what's recorded ​

One toggle per home: Analytics is on or off for the whole home — the sensible defaults decide what is worth keeping (see above). Individual characteristics can still be excluded through the API (setHistorySeriesConfig in GraphQL) if you need finer control; a disabled characteristic stops recording immediately and existing samples stay until you delete them.

Retention: everything is kept indefinitely — every recorded sample, plus hourly and daily summaries (minimum, average, maximum, time-in-state) that make long-range charts fast.

  • Cloud: nothing is ever pruned automatically; only your own delete (or deleting your account) removes history.
  • Community: the same, with one safety limit — if storage on the Mac grows past 500 MB, the oldest raw samples are removed first. The hourly and daily summaries are kept, so long-range charts are unaffected.

Export & delete: while Analytics is on, the same section has Export CSV (every raw sample, timestamped, as homecast-analytics-<home>.csv) and Delete data…, which asks you to confirm with Delete all data before removing everything recorded for the home. Both work in either edition. Cloud exports stop at 200,000 rows.

While Analytics is on, the section has a second switch, Analytics on shared links. It is off by default. Turn it on and anyone holding a share link for this home can open Analytics for what that link shows — a shared room shows that room's charts, nothing else. Link holders cannot export or delete anything.

Turning Analytics off hides it from share links too; this switch keeps its setting for when you turn Analytics back on. Home members are not affected by this switch: they always see the home's Analytics.

For developers and AI assistants ​

History is part of every Homecast API surface:

  • MCP — query_history gives an AI assistant bulk, flexible access to everything recorded: any subset of accessories and characteristics, any date range, at raw/hourly/daily resolution, many series per call — the raw material for analysing patterns and behaviour ("what are the patterns in my home?", "when is the house usually active?"). get_history is the quick single-accessory version: "what was the temperature in the bedroom last night?".
  • REST — GET /rest/history?accessory=<name>&hours=24 returns the same compact series.
  • GraphQL — history, historySeries, and historyStorageStats queries serve downsampled series for charting, plus mutations for configuration and deletion.

All three respect the opt-in: if Analytics is off, they return nothing and say why.

Privacy ​

  • Recording is opt-in per home and off by default.
  • Only characteristics with a recording profile are ever stored — accessory names, models, serial numbers, and firmware versions are excluded by construction.
  • In the Community Edition nothing leaves your Mac. In Cloud, history is tied to your account and covered by the Privacy Policy.
  • Export and full deletion are always available, and account deletion removes all recorded history.