> ## 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.

# List Groups

> List the monitor groups in your organization

## Overview

Returns the groups in your organization, newest first, one page at a time.

`GET /api/groups`

## Authentication

`X-API-Key: YOUR_API_KEY` or `Authorization: Bearer YOUR_JWT`. A read-only API key is sufficient.

## Query parameters

| Parameter | Type | Default | Description |
| - | - | - | - |
| `page` | integer | `1` | Page number (minimum 1). |
| `limit` | integer | `10` | Groups per page, 1-100. |

## Example

```bash theme={null}
curl "https://api.uptimeio.com/api/groups?page=1&limit=20" \
  -H "X-API-Key: YOUR_API_KEY"
```

## Response

`200 OK`. This endpoint returns its paging fields inside `data` rather than in a top-level `pagination` object.

```json theme={null}
{
  "success": true,
  "data": {
    "groups": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "organization_id": "0b0f7a0e-2c3d-4f55-9a11-6f1c2f1d9a10",
        "project_id": "7c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
        "created_by": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "name": "Production Services",
        "description": "Critical production monitoring group",
        "created_at": "2026-09-30T10:30:00.000Z",
        "updated_at": "2026-09-30T10:30:00.000Z",
        "check_count": 12,
        "monitors": [],
        "children": [],
        "path": []
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 20
  }
}
```

| Field | Type | Description |
| - | - | - |
| `groups` | array | [Group objects](/api-reference/groups/create#group-object). `monitors`, `children` and `path` are empty here; use [Get Group](/api-reference/groups/get) for details. |
| `total` | number | Total groups in the organization. |
| `page` | number | Page returned. |
| `limit` | number | Page size used. |

## Errors

| Status | Code | When |
| - | - | - |
| `400` | `INVALID_PAGE` | `Page must be a positive integer`. |
| `400` | `INVALID_LIMIT` | `Limit must be between 1 and 100`. |
| `401` | `MISSING_AUTH` / `INVALID_API_KEY` | Missing or invalid credentials. |
| `500` | `INTERNAL_ERROR` | `Failed to get groups`. |

To see groups as a tree, use [Group Hierarchy](/api-reference/groups/hierarchy).


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