# How Monitor Groups Organize Monitors in Uptime Kuma: Database Design and Implementation

> Discover how Uptime Kuma organizes monitors with monitor groups using a many-to-many database relationship and a special group monitor type. Understand the database design and implementation for efficient monitoring.

- Repository: [Louis Lam/uptime-kuma](https://github.com/louislam/uptime-kuma)
- Tags: internals
- Published: 2026-02-28

---

**Uptime Kuma bundles individual service monitors into logical monitor groups using a many-to-many database relationship and a specialized group monitor type that aggregates the health status of all child services.**

Monitor groups in Uptime Kuma serve as the primary organizational layer for managing large infrastructure deployments. By linking monitors to groups through a relational schema and supporting a synthetic monitor type that reports aggregated status, the application enables both logical dashboard organization and high-level service health monitoring.

## Database Architecture for Monitor Groups

The relationship between monitors and groups is implemented through a junction table defined in [`db/knex_init_db.js`](https://github.com/louislam/uptime-kuma/blob/main/db/knex_init_db.js). The `monitor_group` table stores `monitor_id` and `group_id` as foreign keys, along with a `weight` field that controls display ordering on status pages.

Additional columns include `send_url` and `custom_url`, which are utilized when a monitor is configured as a group-type monitor. This schema allows a single monitor to belong to multiple groups while maintaining sort priority through the weight integer.

## Group Model and Public API

The [`server/model/group.js`](https://github.com/louislam/uptime-kuma/blob/main/server/model/group.js) file defines the `Group` class, which provides two critical methods for group operations:

- `getMonitorList()` – Executes a SQL join against the `monitor_group` table to retrieve all monitors associated with a specific group ID.
- `toPublicJSON()` – Serializes the group into a public-facing format containing the group's `id`, `name`, `weight`, and an embedded array of child monitors.

The API router in [`server/routers/api-router.js`](https://github.com/louislam/uptime-kuma/blob/main/server/routers/api-router.js) exposes endpoints that interact with these model methods. Creating a group inserts a record into the `group` table, while assigning a monitor to a group updates both the `monitor.parent` field and the `monitor_group` junction table.

## Frontend Integration

The monitor editing interface binds the group relationship through the `parent` field. In [`src/pages/EditMonitor.vue`](https://github.com/louislam/uptime-kuma/blob/main/src/pages/EditMonitor.vue), the UI renders a selector populated with existing groups, storing the selected group ID in the monitor's `parent` property.

When a user saves a monitor with a selected group, the application persists this relationship through the API layer, which updates the database schema accordingly. This allows the monitor to appear within the group's context on both the dashboard and public status pages.

## Aggregated Status Monitoring

Uptime Kuma implements a specialized monitor type for groups in [`server/monitor-types/group.js`](https://github.com/louislam/uptime-kuma/blob/main/server/monitor-types/group.js). This synthetic monitor aggregates the status of all active child monitors to provide a high-level health overview.

The `GroupMonitorType.check()` method retrieves child monitors using `Monitor.getChildren(parentId)`, then evaluates their last heartbeat status. The aggregation logic reports the worst available status following the hierarchy: **UP** → **PENDING** → **DOWN**.

When children are down or pending, the monitor generates descriptive messages such as:

```

Child monitors down: Monitor C; pending: Monitor D

```

This allows operators to treat an entire service stack as a single logical unit while maintaining visibility into individual component failures.

## Status Page Rendering

Public status pages leverage the group model to organize displays. In [`server/model/status_page.js`](https://github.com/louislam/uptime-kuma/blob/main/server/model/status_page.js), the rendering logic calls `groupBean.toPublicJSON()` to embed grouped monitors into the page response.

The `monitor_group` weight field determines the sort order of monitors within each group section. Real-time updates to group ordering are handled by the socket handler in [`server/socket-handlers/status-page-socket-handler.js`](https://github.com/louislam/uptime-kuma/blob/main/server/socket-handlers/status-page-socket-handler.js), which manipulates `monitor_group` rows via SQL when users reorder monitors on the status page.

## Summary

- **Database Layer**: The `monitor_group` junction table links monitors to groups with ordering weights and optional URL configurations.
- **Backend Logic**: [`server/model/group.js`](https://github.com/louislam/uptime-kuma/blob/main/server/model/group.js) provides data retrieval and JSON serialization, while [`server/monitor-types/group.js`](https://github.com/louislam/uptime-kuma/blob/main/server/monitor-types/group.js) implements aggregated health checking.
- **Frontend Binding**: The `parent` field in [`src/pages/EditMonitor.vue`](https://github.com/louislam/uptime-kuma/blob/main/src/pages/EditMonitor.vue) connects monitors to their groups in the UI.
- **API Surface**: REST endpoints in [`server/routers/api-router.js`](https://github.com/louislam/uptime-kuma/blob/main/server/routers/api-router.js) handle CRUD operations for group assignments.
- **Public Display**: Status pages render grouped monitors using `toPublicJSON()` with weight-based sorting.

## Frequently Asked Questions

### How do I assign an existing monitor to a monitor group?

Send a PUT request to `/api/monitor/{id}` with a JSON body containing `"parent": {group_id}`. The API updates the monitor's `parent` field and the `monitor_group` junction table to establish the relationship.

### What is the difference between a regular monitor and a group-type monitor?

A regular monitor checks a specific endpoint or service directly. A **group-type monitor** is a synthetic monitor that aggregates the status of all monitors assigned to a specific group, reporting the worst health status (UP → PENDING → DOWN) among its children.

### How does Uptime Kuma determine the order of monitors within a group on status pages?

The `weight` field in the `monitor_group` junction table controls display ordering. When rendering status pages, the server sorts monitors by this integer value, and real-time reordering operations update these weights via the status page socket handler.

### Can a monitor belong to multiple groups simultaneously?

The database schema supports many-to-many relationships through the `monitor_group` junction table. However, the UI typically manages a single `parent` relationship per monitor for dashboard organization, while status pages may leverage the junction table for more complex display scenarios.