---
title: "List the subgroups of list of groups"
method: GET
path: "/api/v2/subgroups/"
tags: ["esper_cloud_api_Device Group"]
---

# List the subgroups of list of groups

`GET /api/v2/subgroups/`

Returns a list of subgroup UUIDs for one or more parent groups. Use the parent_group_ids parameter to specify which parent groups to query, and the immediate parameter to control whether the response includes only direct children or all descendants at every level of the hierarchy.

Note that the response contains only subgroup UUIDs — not full group objects. Use GET /enterprise/{enterprise_id}/devicegroup/{group_id}/ to retrieve full details for any returned group ID.

Query parameters

parent_group_ids (optional) — Comma-separated list of parent group UUIDs to query; omitting this parameter may return subgroups across all groups
immediate (optional, default: false) — When false, returns all descendant subgroups at every level; when true, returns only the immediate (direct) children of the specified parent groups

**Common Use Cases**

Traversing a group hierarchy to discover all subgroups beneath one or more parent groups
Checking whether a group has children before deciding to delete or restructure it
Collecting a full list of descendant group IDs to use as targets for bulk operations

**Best Practices**

When only direct children are needed, set immediate=true to avoid retrieving the full descendant tree, which may be large in deep hierarchies
Since the response returns UUIDs only, plan for follow-up calls to GET /devicegroup/{group_id}/ if group names, device counts, or other metadata are required
Use parent_group_ids to scope the query — querying without it may return more data than expected

## Query parameters

- `parent_group_ids` string
- `immediate` boolean

## Response `200`

successful operation

- object
  - `content` EsperCloudApiDeviceSubGroup[], required
    - `subgroups` string[]

## Other responses

- `400` — Bad Request.
- `401` — Authorization information is missing or invalid.
- `500` — Internal server error.

---

[API](https://skmtc.net/esper/apis/esper-api-reference.md) · [All operations](https://skmtc.net/esper/apis/esper-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/esper/esper-api-reference/revisions/e1f64cbb488e/schema)