---
title: Groups API
description: Create and manage groups to organize monitors and perform bulk operations via the Cronitor API.
---

The Groups API allows you to programmatically create and manage groups of monitors. Groups help organize related monitors and enable bulk operations like pausing all monitors in a group at once. {% .lead %}

## Authentication

The Groups API requires API key authentication with monitor scopes:
- **`monitor:read`** - Required to list and retrieve groups
- **`monitor:write`** - Required to create, update, and delete groups

Create an API key with the appropriate scopes from the [API Settings](/app/settings/api) page. For more information about API authentication and scopes, see the [API documentation](/docs/api).

---

## Quick Start

### Create a Group
```bash
curl --user API_KEY: \
    --header "Content-Type: application/json" \
    --request POST \
    --data '{
        "name": "Production Services",
        "key": "production-services",
        "monitors": ["api-health", "database-backup", "web-server"]
    }' \
    https://cronitor.io/api/groups
```

### List All Groups
```bash
curl https://cronitor.io/api/groups -u API_KEY:
```

### Pause All Monitors in a Group
```bash
curl https://cronitor.io/api/groups/production-services/pause/24 -u API_KEY:
```

---

## Groups

### List Groups

Retrieve all groups for your organization.

#### Endpoint
```bash
GET https://cronitor.io/api/groups
```

#### Query Parameters
- **`page`** (integer) - Page number for pagination (default: 1)
- **`pageSize`** (integer) - Number of results per page (default: 50)
- **`env`** (string) - Filter by environment key
- **`withStatus`** (boolean) - Include status information for each group

#### Examples

##### List All Groups
```bash
curl https://cronitor.io/api/groups -u API_KEY:
```

##### List Groups with Status
```bash
curl "https://cronitor.io/api/groups?withStatus=true" -u API_KEY:
```

#### Response
```json
{
  "page": 1,
  "page_size": 50,
  "count": 3,
  "groups": [
    {
      "key": "production-services",
      "name": "Production Services",
      "monitors": ["api-health", "database-backup", "web-server"],
      "created": "2023-06-15T10:30:00Z",
      "latest_event": {
        "stamp": 1702900000,
        "state": "complete"
      },
      "latest_issue": null
    },
    {
      "key": "staging-services",
      "name": "Staging Services",
      "monitors": ["staging-api", "staging-web"],
      "created": "2023-07-20T14:00:00Z",
      "latest_event": null,
      "latest_issue": null
    }
  ]
}
```

---

### Create a Group

Create a new group to organize monitors.

#### Endpoint
```bash
POST https://cronitor.io/api/groups
```

#### Request Body
```json
{
  "name": "Production Services",
  "key": "production-services",
  "monitors": ["api-health", "database-backup"]
}
```

#### Parameters
- **`name`** (string, required) - Display name for the group
- **`key`** (string, optional) - Unique identifier for the group. If not provided, one will be generated from the name
- **`monitors`** (array of strings, optional) - Array of monitor keys to add to this group

#### Example
```bash
curl --user API_KEY: \
    --header "Content-Type: application/json" \
    --request POST \
    --data '{
        "name": "Backend Services",
        "key": "backend-services",
        "monitors": ["user-api", "payment-service", "notification-worker"]
    }' \
    https://cronitor.io/api/groups
```

#### Response
```json
{
  "key": "backend-services",
  "name": "Backend Services",
  "monitors": ["user-api", "payment-service", "notification-worker"],
  "created": "2023-12-01T10:00:00Z",
  "latest_event": null,
  "latest_issue": null
}
```

---

### Get a Group

Retrieve details for a specific group.

#### Endpoint
```bash
GET https://cronitor.io/api/groups/:key
```

#### Query Parameters
- **`env`** (string) - Environment key for status filtering
- **`withStatus`** (boolean) - Include status information
- **`sort`** (string) - Sort order for monitors in the group

#### Example
```bash
curl https://cronitor.io/api/groups/production-services -u API_KEY:
```

#### Response
```json
{
  "key": "production-services",
  "name": "Production Services",
  "monitors": ["api-health", "database-backup", "web-server"],
  "created": "2023-06-15T10:30:00Z",
  "latest_event": {
    "stamp": 1702900000,
    "state": "complete",
    "message": "Backup completed successfully"
  },
  "latest_issue": null
}
```

---

### Update a Group

Update a group's name or modify which monitors belong to it.

#### Endpoint
```bash
PUT https://cronitor.io/api/groups/:key
```

#### Request Body
```json
{
  "name": "Production Backend Services",
  "monitors": ["api-health", "database-backup", "web-server", "cache-service"]
}
```

#### Parameters
- **`name`** (string) - Updated display name
- **`monitors`** (array of strings) - Complete list of monitor keys. This replaces the existing list—monitors not included will be removed from the group

#### Example
```bash
curl --user API_KEY: \
    --header "Content-Type: application/json" \
    --request PUT \
    --data '{
        "name": "Core Production Services",
        "monitors": ["api-health", "database-backup", "web-server", "cache-service"]
    }' \
    https://cronitor.io/api/groups/production-services
```

#### Response
Returns the updated group object.

---

### Delete a Group

Delete a group. Monitors in the group are not deleted—they become ungrouped.

#### Endpoint
```bash
DELETE https://cronitor.io/api/groups/:key
```

#### Example
```bash
curl --request DELETE https://cronitor.io/api/groups/old-services -u API_KEY:
```

#### Response
Returns HTTP 204 No Content on success.

---

## Pause Operations

### Pause All Monitors in a Group

Temporarily pause monitoring for all monitors in a group. This is useful during planned maintenance or deployments.

#### Endpoint
```bash
GET https://cronitor.io/api/groups/:key/pause/:hours
```

#### Parameters
- **`:key`** (string) - The group key
- **`:hours`** (integer) - Number of hours to pause. Use `0` to resume immediately

#### Examples

##### Pause for 2 Hours
```bash
curl https://cronitor.io/api/groups/production-services/pause/2 -u API_KEY:
```

##### Pause Indefinitely
```bash
curl https://cronitor.io/api/groups/production-services/pause -u API_KEY:
```

##### Resume All Monitors
```bash
curl https://cronitor.io/api/groups/production-services/pause/0 -u API_KEY:
```

#### Response
Returns the group object with updated monitor states.

---

## Group Attributes

{% attribute name="key" context="[string]" /%}
Unique identifier for the group. Used in API requests and for referencing the group when assigning monitors.

{% attribute name="name" context="[string] **required**" /%}
Display name for the group. Shown in the Cronitor dashboard and alerts.

{% attribute name="monitors" context="[array of strings]" /%}
Array of monitor keys belonging to this group. When updating, provide the complete list—monitors not included will be removed from the group.

{% attribute name="created" context="[timestamp] read-only" /%}
ISO 8601 formatted timestamp of when the group was created.

{% attribute name="latest_event" context="[object] read-only" /%}
The most recent telemetry event from any monitor in this group.

{% attribute name="latest_issue" context="[object] read-only" /%}
The most recent issue from any monitor in this group.

---

## Best Practices

- **Organize by service or team**: Group related monitors together for easier management
- **Use meaningful keys**: Choose descriptive keys like `payment-services` rather than generic names
- **Leverage pause operations**: Use group pause during deployments to avoid false alerts
- **Keep groups focused**: Smaller, focused groups are easier to manage than large catch-all groups