Monitor Groups API

Monitor groups let you organize monitors into color-coded categories for easier dashboard management. Each group has a name, color, and sort order. Monitors can be assigned to a group via the groupId field when creating or updating a monitor.

Monitor Group Object

{
  "id": "grp_01j5a7b8c9d0e1f2g3h4i5j6",
  "name": "Production APIs",
  "color": "cyan",
  "sortOrder": 1,
  "monitorCount": 12,
  "createdAt": "2025-06-10T14:20:00.000Z",
  "updatedAt": "2025-06-10T14:20:00.000Z"
}

Field	Type	Description
id	string	Unique group identifier
name	string	Group name (must be unique within the organization)
color	string	Display color for the group (default: cyan)
sortOrder	number	Display order on the dashboard
monitorCount	number	Number of monitors assigned to this group (list endpoint only)
createdAt	string	ISO 8601 creation timestamp
updatedAt	string	ISO 8601 last update timestamp
monitors	array	Monitors in this group (single group endpoint only)

---

List Monitor Groups

GET /v1/monitor-groups

Returns all monitor groups belonging to your organization, including a count of monitors in each group.

Query Parameters

Parameter	Type	Default	Description
limit	number	50	Number of groups to return (max 200)
offset	number	0	Number of groups to skip for pagination

Response

{
  "data": [
    {
      "id": "grp_01j5a7b8c9d0e1f2g3h4i5j6",
      "name": "Production APIs",
      "color": "cyan",
      "sortOrder": 1,
      "monitorCount": 12,
      "createdAt": "2025-06-10T14:20:00.000Z",
      "updatedAt": "2025-06-10T14:20:00.000Z"
    },
    {
      "id": "grp_01j5a8c9d0e1f2g3h4i5j6k7",
      "name": "Staging Servers",
      "color": "purple",
      "sortOrder": 2,
      "monitorCount": 5,
      "createdAt": "2025-06-12T09:15:00.000Z",
      "updatedAt": "2025-06-12T09:15:00.000Z"
    }
  ],
  "meta": {
    "total": 2
  }
}

⚡Try it

Fetch all monitor groups in your organization.

GET/v1/monitor-groups?limit=50&offset=0

Query Parameters

limit — Number of groups to return (max 200)

offset — Number of groups to skip

Click ⚙ to configure your API key, then hit Send.

---

Get Monitor Group

GET /v1/monitor-groups/:id

Returns a single monitor group with its associated monitors.

Path Parameters

Parameter	Type	Description
id	string	The group ID

Response

{
  "data": {
    "id": "grp_01j5a7b8c9d0e1f2g3h4i5j6",
    "name": "Production APIs",
    "color": "cyan",
    "sortOrder": 1,
    "createdAt": "2025-06-10T14:20:00.000Z",
    "updatedAt": "2025-06-10T14:20:00.000Z",
    "monitors": [
      {
        "id": "cly1abc2d0001abcdef012345",
        "name": "Payment Service",
        "url": "https://payments.example.com/health",
        "status": "ACTIVE",
        "monitorType": "HTTP"
      },
      {
        "id": "cly2def3e0002abcdef678901",
        "name": "User Service",
        "url": "https://users.example.com/health",
        "status": "ACTIVE",
        "monitorType": "HTTP"
      }
    ]
  }
}

Error

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Monitor group with id 'grp_invalid' not found"
  }
}

⚡Try it

Get a single monitor group with its monitors.

GET/v1/monitor-groups/:id

Path Parameters

:id

Click ⚙ to configure your API key, then hit Send.

---

Create Monitor Group

POST /v1/monitor-groups

Creates a new monitor group. Requires a READ_WRITE API key.

Request Body

Field	Type	Required	Description
name	string	Yes	Group name (1-100 characters, unique within your org)
color	string	No	Display color (default: cyan)
sortOrder	number	No	Display order (default: 0)

Example Request

{
  "name": "Production APIs",
  "color": "cyan",
  "sortOrder": 1
}

Response 201 Created

{
  "data": {
    "id": "grp_01j5a7b8c9d0e1f2g3h4i5j6",
    "name": "Production APIs",
    "color": "cyan",
    "sortOrder": 1,
    "createdAt": "2025-06-10T14:20:00.000Z",
    "updatedAt": "2025-06-10T14:20:00.000Z"
  }
}

Validation Error

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid monitor group data",
    "details": {
      "name": ["Group name is required"]
    }
  }
}

⚡Try it

Create a new monitor group. Requires a READ_WRITE API key.

POST/v1/monitor-groups

Request Body

{ "name": "Production APIs", "color": "cyan", "sortOrder": 1 }

Click ⚙ to configure your API key, then hit Send.

---

Update Monitor Group

PATCH /v1/monitor-groups/:id

Updates an existing monitor group. Only the fields you include in the request body will be updated. Requires a READ_WRITE API key.

Path Parameters

Parameter	Type	Description
id	string	The group ID

Request Body

All fields are optional. Include only the fields you want to change.

Field	Type	Description
name	string	Updated group name
color	string	Updated display color
sortOrder	number	Updated display order

Example Request

{
  "name": "Prod APIs (Critical)",
  "color": "magenta"
}

Response 200 OK

{
  "data": {
    "id": "grp_01j5a7b8c9d0e1f2g3h4i5j6",
    "name": "Prod APIs (Critical)",
    "color": "magenta",
    "sortOrder": 1,
    "createdAt": "2025-06-10T14:20:00.000Z",
    "updatedAt": "2025-06-15T11:45:00.000Z"
  }
}

⚡Try it

Update specific fields on an existing monitor group. Requires a READ_WRITE API key.

PATCH/v1/monitor-groups/:id

Path Parameters

:id

Request Body

{ "name": "Prod APIs (Critical)", "color": "magenta" }

Click ⚙ to configure your API key, then hit Send.

---

Delete Monitor Group

DELETE /v1/monitor-groups/:id

Permanently deletes a monitor group. Monitors assigned to this group will be unassigned (not deleted). Requires a READ_WRITE API key.

Path Parameters

Parameter	Type	Description
id	string	The group ID

Response 200 OK

{
  "data": {
    "id": "grp_01j5a7b8c9d0e1f2g3h4i5j6",
    "deleted": true
  }
}

Error

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Monitor group with id 'grp_invalid' not found"
  }
}

⚡Try it

Permanently delete a monitor group. Monitors in the group will be unassigned.

DELETE/v1/monitor-groups/:id

Path Parameters

:id

Click ⚙ to configure your API key, then hit Send.