Search
ha_searchFind any Home Assistant entity or configuration in one call: search by name, domain, area, or state and locate automations, scripts, scenes, helpers, and dashboards referencing it.
Instructions
Search for entities (lights, sensors, switches, climate, etc.) by name, domain, or area — AND inside automation/script/scene/helper/dashboard configurations — in one call.
Two surfaces run in parallel and return tagged results:
entities: entity-registry matches (entity_id, friendly name, area). Filter with
domain_filter/area_filter/state_filter; omitqueryto enumerate a domain, area, or state.automations / scripts / scenes / helpers / dashboards: matches inside config definitions — triggers, actions, sequences, scene entity-sets, helper bodies, dashboard cards. Driven by
query; narrow withsearch_types.
Use this whenever you need to find something in HA without deciding entity-name vs config-body search up front.
For control requests with exclusions such as "except", "excluding", or
"but not", include is_group and member_entity_ids in result_fields.
Do not control an aggregate whose members include an excluded entity;
prefer leaf entities when the exception cannot be verified safely.
A withheld member list still returns is_group=true; absence of
member_entity_ids must not be interpreted as a leaf entity.
When NOT to use:
To read a known entity_id's state: use
ha_get_state(cheaper).To inspect one automation/script/scene config by id: use the matching
ha_config_get_*.To list installed Apps (add-ons): use
ha_get_app.
Config-body search is skipped when domain_filter/area_filter/
state_filter signal entity-only intent (keeping name lookups off the
expensive backend); a warnings[] entry names the skip. Pass
search_types=[...] to force config search.
Caveats:
partial: Truemeans results are NOT exhaustive — a surface raised, or the config-body branch lost data (per-id time budget exhausted, an individual fetch failed, or a helper-type list fetch failed). Empty buckets withpartial: Truemean "search failed", not "no results". The cause is inpartial_reason, also mirrored intowarnings[]with an "incomplete results: " prefix. Do not treat a partial response as complete.countis items in this response (post-pagination), not corpus totals — useentity_total_matches+config_total_matches.limit/offsetapply per-surface. Flathas_more/next_offsetpage the next call (iterateoffset = next_offset); per-surfaceentity_*/config_*variants show which surface still has results.
For parameters, schema, and worked examples, see ha_get_skill_guide.
Examples: - List sensors in an area: ha_search(domain_filter="sensor", area_filter="Living Room") - Find a light by name: ha_search("kitchen", domain_filter="light") - Find lights safely before an "all except one" control request: ha_search("living room", domain_filter="light", result_fields=["entity_id", "friendly_name", "is_group", "member_entity_ids"]) - Which automations use an entity: ha_search("light.bed_light") - Scenes touching a light: ha_search("light.kitchen", search_types=["scene"]) - Narrow the response to the entity bucket: ha_search("kitchen", fields=["entities"]) - All unavailable entities: ha_search(state_filter="unavailable")
find entities configs lookup discover search lights sensors switches covers climate fans media_player binary_sensor device_tracker person weather automation script helper input_boolean input_number automations scripts scenes helpers dashboards
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum results per surface (entities, configs). Default: 10. | |
| query | No | What to search for (entity name fragment, free-text config term, entity_id). Searches BOTH the entity registry (entity_ids, friendly names, areas) AND configuration bodies (automation triggers/actions, script sequences, scene contents, helper bodies, dashboard cards) in one call. Use this for any find-something-in-HA question — entity OR config. Pass the exact entity_id, not a name fragment, when checking what a rename or delete would break: that form reports automations, scripts and scenes referencing it even when their configuration could not be read. Omit `query` to enumerate by `domain_filter`, `area_filter`, and/or `state_filter` alone (registry-listing mode); configuration-body search is skipped in that mode because there is no term to match against. | |
| fields | No | Project the response to the named top-level keys (e.g. ["entities", "automations"]); None = full response. Diagnostic / pagination keys are always retained so projection cannot hide partial / error state. Distinct from `result_fields` (which projects each entity record's keys). Available keys: success, query, entities, automations, scripts, scenes, helpers, dashboards, search_types, search_type, entity_total_matches, config_total_matches, count, offset, limit, has_more, next_offset, entity_has_more, entity_next_offset, config_has_more, config_next_offset, by_domain, state_filter_note, area_names, domain_filter, area_filter, message, warnings, errors, partial, partial_reason. | |
| offset | No | Number of results to skip for pagination. | |
| area_filter | No | Narrow entity-registry results to an area (id, name, or alias), an exact floor (id, name, or alias), or an unambiguous close-spelling floor match; a floor match expands to all areas on that floor. Does not affect configuration search. | |
| exact_match | No | Exact substring matching (default). Set False for fuzzy matching when the query may have typos. | |
| search_types | No | Configuration types to include in body search: 'automation', 'script', 'scene', 'helper', 'dashboard'. Default = automation+script+scene+helper. Pass as list or JSON-array string. | |
| state_filter | No | Filter entity-registry results to a specific state (e.g. "on", "off", "unavailable"). Case-insensitive. Can be used standalone (no query/domain/area) to enumerate every entity in that state; entity_total_matches reflects the filtered count. | |
| domain_filter | No | Narrow entity-registry results to a single domain (e.g. 'light', 'sensor'). Does not affect configuration search. | |
| result_fields | No | Project each entity-registry record to only the specified keys (e.g. ["entity_id", "state"]). None = full records. Base keys: entity_id, friendly_name, domain, state, score, match_type. Opt-in enrichment/membership keys (computed on request): area, floor, labels, aliases, is_group, member_entity_ids. Membership is recognized only when HA explicitly exposes a valid group_entities or legacy entity_id collection; member IDs are sorted, direct (not recursively expanded), and omitted if visibility/include_hidden excludes a member. is_group remains true when member IDs are withheld; requesting member_entity_ids also retains is_group. An unknown key is rejected. | |
| include_config | No | Include full configuration bodies in body-search results. Default: False (summary only). | |
| include_hidden | No | Include hidden entities in registry results (with a score penalty so they sort below visible matches). Set False to exclude entirely. | |
| group_by_domain | No | Group entity-registry results by domain (entity-side only). Adds a `by_domain` map to the response. | |
| per_domain_limit | No | When `group_by_domain=True`, cap entity-registry results per domain to this number. Ignored otherwise. | |
| config_time_budget | No | Per-call override for the per-id config-fetch wall-clock budget (seconds). Replaces the per-type HAMCP_*_CONFIG_TIME_BUDGET defaults for the automation, script, AND scene branches. Use when a `partial: True` response names time-budget skipping. Stateless per-call: one caller raising the budget doesn't affect others. None = use the per-type env defaults. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||