Cronitor API

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

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 page. For more information about API authentication and scopes, see the API documentation.

Quick Start

Create a Group

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

curl https://cronitor.io/api/groups -u API_KEY:

Pause All Monitors in a Group

curl https://cronitor.io/api/groups/production-services/pause/24 -u API_KEY:

Groups

List Groups

Retrieve all groups for your organization.

Endpoint

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
curl https://cronitor.io/api/groups -u API_KEY:
List Groups with Status
curl "https://cronitor.io/api/groups?withStatus=true" -u API_KEY:

Response

{
  "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

POST https://cronitor.io/api/groups

Request Body

{
  "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

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

{
  "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

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

curl https://cronitor.io/api/groups/production-services -u API_KEY:

Response

{
  "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

PUT https://cronitor.io/api/groups/:key

Request Body

{
  "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

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

DELETE https://cronitor.io/api/groups/:key

Example

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

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
curl https://cronitor.io/api/groups/production-services/pause/2 -u API_KEY:
Pause Indefinitely
curl https://cronitor.io/api/groups/production-services/pause -u API_KEY:
Resume All Monitors
curl https://cronitor.io/api/groups/production-services/pause/0 -u API_KEY:

Response

Returns the group object with updated monitor states.

Group Attributes

key[string]

Unique identifier for the group. Used in API requests and for referencing the group when assigning monitors.

name[string] **required**

Display name for the group. Shown in the Cronitor dashboard and alerts.

monitors[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.

created[timestamp] read-only

ISO 8601 formatted timestamp of when the group was created.

latest_event[object] read-only

The most recent telemetry event from any monitor in this group.

latest_issue[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
Previous
Monitors
Next
Notifications