> ## Documentation Index
> Fetch the complete documentation index at: https://docs.uptimeio.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Group Hierarchy

> Retrieve all groups in your project as a nested tree

## Overview

Returns the top-level groups of your project, each with its descendants nested under `child_groups`.

`GET /api/groups/hierarchy`

## Authentication

`X-API-Key: YOUR_API_KEY` or `Authorization: Bearer YOUR_JWT`. A read-only API key is sufficient. Add `X-Project-ID: PROJECT_ID` to read a project other than your default.

## Example

```bash theme={null}
curl https://api.uptimeio.com/api/groups/hierarchy \
  -H "X-API-Key: YOUR_API_KEY"
```

## Response

`200 OK`. `data` is an array of top-level [group objects](/api-reference/groups/create#group-object), each with a `child_groups` array and `check_count`.

```json theme={null}
{
  "success": true,
  "data": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "name": "Production",
      "check_count": 4,
      "child_groups": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "Web Services",
          "parent_group_id": "660e8400-e29b-41d4-a716-446655440001",
          "check_count": 2,
          "child_groups": []
        }
      ]
    }
  ]
}
```

(Other group fields such as `organization_id`, `project_id` and `created_at` are omitted from the example for brevity.)

## Errors

| Status | Code | When |
| - | - | - |
| `401` | `MISSING_AUTH` / `INVALID_API_KEY` | Missing or invalid credentials. |
| `500` | `INTERNAL_ERROR` | `Failed to get group hierarchy`. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.