--- title: "getGroups" method: GET path: "/households/{householdId}/groups" tags: ["groups"] --- # getGroups `GET /households/{householdId}/groups` Use the getGroups command in the groups namespace to get information about groups and players in a household. ## Response `200` The groups object in the groups namespace describes the current set of logical players and groups in the household. Use the getGroups command to get a groups object. - Groups — The groups object in the groups namespace describes the current set of logical players and groups in the household. Use the getGroups command to get a groups object. - `groups` Group[], nullable — A list of groups in the household. - `id` string, required — The ID of the group. - `name` string, required — The display name for the group, such as “Living Room” or “Kitchen + 2”. - `coordinatorId` string, required — The ID of the player acting as the group coordinator for the group. This is a playerId value. - `playbackState` 'PLAYBACK_STATE_IDLE' | 'PLAYBACK_STATE_BUFFERING' | 'PLAYBACK_STATE_PAUSED' | 'PLAYBACK_STATE_PLAYING' — No description available - `playerIds` string[], required — The IDs of the primary players in the group. For example, only one player from each set of players bonded as a stereo pair or as satellites to a home theater setup. Each element is the ID of a player. This list includes the coordinatorId. - `areaIds` string[], nullable — List of source areaIds associated with the group. - `players` Player[], nullable — A list of the players in the household. Each element is a player object. The list of players excludes quarantined devices, unless the event/response comes from the quarantined device itself. *Note* This array is a filtered variant of the devices array. This array only includes primary players. Primary players are capable of independent music playback (PLAYBACK capability). - `id` string, required — No description available - `name` string, required — No description available - `websocketUrl` string, required — No description available - `softwareVersion` string, required — No description available - `apiVersion` string, required — No description available - `minApiVersion` string, required — No description available - `isUnregistered` boolean, nullable — Deprecated; use capabilities (CLOUD) instead. - `capabilities` Capability[], required — Deprecated; use deviceInfo object in devices array. - `deviceIds` string[], required — deprecated; use deviceInfo object in devices array - `devices` DeviceInfo[], nullable — A list of the devices that comprise this logical player. Each element is a deviceInfo object. Use this array if you want to access immutable data about a device such as the model number. *Note* The capabilities array in the deviceInfo object should be preferred to the capabilities array in the player object. The two arrays are identical, but the player's array does filter secondary devices. Secondary devices are those that do not play music independently. Satellite speakers in a home theater are examples of secondary devices. - `id` string, required — This is the playerId that is used to address Sonos players in the control API. - `primaryDeviceId` string, nullable — This id identifies the primary player in bonded sets by it's playerId. Primary players leave the value blank, which omits the key from the message. The field is expected for secondary players in stereo pairs and satellites in home theater configurations. - `serialNumber` string, nullable — This is the device serial number that is printed on the device. Includes hex characters, hyphens, and a colon. Example: 00-00-AA-A0-00-00:0 - `deviceId` string, nullable — This is the identifier used to uniquely identify the physical device and is a compact version of the device serial number. Example: 0000AAA00000 - `modelDisplayName` string, nullable — This is a human readable version of the model string. This is the value that should be presented to customers. - `color` string, nullable — This is the primary device color. This field may be omitted from older products that did not encode this information digitally. - `capabilities` Capability[], nullable — A list of capabilities that this player supports. Some capabilities are dynamic and depend on the player's current configuration. Others are fixed based on the attributes of the hardware. The fixed capabilities duplicate information in the deviceFeatures array. The features array is more comprehensive and should be preferred. - `apiVersion` string, nullable — This string stores the latest API version supported by the player. Deprecated: Use versions instead. - `minApiVersion` string, nullable — This string stores the oldest API version supported by the player. Deprecated: Use versions instead. - `versions` SdkVersions — This data type is used to specify the versions of the Control API, Trueplay SDK and audio transport protocol used by the device. - `controlAPI` string[], required — The list of the Control API versions available on the device. This parameter is the only one that MUST be present in the data type. - `trueplaySDK` string[], nullable — (Optional) The list of the trueplay SDK versions available on the device. - `audioTxProtocol` integer[], nullable — (Optional) The list of the audio transport protocol versions available on the device. - `htAudioTxProtocol` integer[], nullable — (Optional) The list of the HT audio transport protocol versions available on the device. - `name` string, nullable — This string stores the human-readable player name. - `websocketUrl` string, nullable — This is the URL where the client developer may find a WebSocket server. Clients may use this interface to receive real time updates from the device. - `softwareVersion` string, nullable — This string stores the softwareVersion the player is running. - `hwVersion` string, nullable — This string stores the hardware version the player is running. The format is: {vendor}.{model}.{submodel}.{revision}-{region}.{variant} Prior to v1.18.9 the variant field was absent. - `swGen` integer, nullable — This integer stores the software generation that the player is running. - `partial` boolean, nullable — Describes whether this is a partial output (where players or groups were dropped). Players and groups can be dropped from the output if they are determined to be invalid according to Sonos household rules. Invalid groups can appear when the household is in a transient state during a grouping operation. ## Other responses - `400` — The groups object in the groups namespace describes the current set of logical players and groups in the household. Use the getGroups command to get a groups object. - `401` — The groups object in the groups namespace describes the current set of logical players and groups in the household. Use the getGroups command to get a groups object. - `403` — The groups object in the groups namespace describes the current set of logical players and groups in the household. Use the getGroups command to get a groups object. - `404` — The groups object in the groups namespace describes the current set of logical players and groups in the household. Use the getGroups command to get a groups object. - `499` — The groups object in the groups namespace describes the current set of logical players and groups in the household. Use the getGroups command to get a groups object. - `500` — The groups object in the groups namespace describes the current set of logical players and groups in the household. Use the getGroups command to get a groups object. - `503` — The groups object in the groups namespace describes the current set of logical players and groups in the household. Use the getGroups command to get a groups object. --- [API](https://skmtc.net/sonos/apis/authorization-api.md) · [All operations](https://skmtc.net/sonos/apis/authorization-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/sonos/authorization-api/revisions/243132628620/schema)