Retrieving Entities & States

Use the API to retrieve the current state of any entity in Home Assistant.

Terminology

Hassette uses precise terminology:

State Value: The raw value (e.g., "on", "23.5").
State: A snapshot including value, attributes, and last changed time.
Entity: A rich object wrapping the state with helper methods (e.g., .turn_off()).

Retrieving States

Use get_state to retrieve a typed state object.

from typing import cast

from hassette import App, states


class LightApp(App):
    async def on_initialize(self):
        # Get typed state (raises EntityNotFoundError if missing)
        light = cast("states.LightState", await self.api.get_state("light.kitchen"))

        # Access typed attributes
        print(light.attributes.brightness)

Raw vs Typed

Most methods return typed Pydantic models. You can use get_state_raw if you want a dict.

from hassette import App


class LightApp(App):
    async def on_initialize(self):
        # Raw dict
        data = await self.api.get_state_raw("light.kitchen")
        self.logger.info("Raw data: %s", data)

Checking Existence

Use get_state_or_none to safely check for an entity.

from hassette import App


class GhostApp(App):
    async def on_initialize(self):
        if await self.api.get_state_or_none("light.ghost"):
            print("It exists!")

Retrieving Multiple States

Use get_states to fetch all states at once. This is more efficient than calling get_state in a loop.

from hassette import App


class StateApp(App):
    async def on_initialize(self):
        all_states = await self.api.get_states()
        lights = [s for s in all_states if s.domain == "light"]
        self.logger.info("Found %d lights", len(lights))

Entities

Entities wrap the state object. Currently BaseEntity and LightEntity are available.

from hassette import App
from hassette.models import entities


class EntityApp(App):
    async def on_initialize(self):
        light = await self.api.get_entity("light.kitchen", entities.LightEntity)
        await light.turn_off()

API vs StateManager

The API methods above fetch states directly from Home Assistant over the network. Prefer self.states instead — it gives you instant, synchronous access from a local cache:

self.states.light["kitchen"] — Domain-specific typed access
self.states.get("light.kitchen") — Direct lookup by entity ID, no await needed

Prefer domain access for better typing

When you know the domain at write time, use self.states.light instead of self.states.get(). Domain access returns fully typed state objects (e.g., LightState) with autocomplete for domain-specific attributes. get() returns BaseState | None, so you lose attribute-level type safety.

Use the API when you need guaranteed fresh data from Home Assistant — otherwise, self.states is faster and simpler.

See States for full details.