Skip to main content

​
Overview

Retrieve detailed information about a specific group including its monitors, child groups, and position in the hierarchy. This endpoint includes basic monitor information and complete nested structure.

​
Authentication

Requires API Key authentication via the X-API-Key header. 
X-API-Key: YOUR_API_KEY

​
Request

curl -X GET https://api.uptimeio.com/api/groups/550e8400-e29b-41d4-a716-446655440000 \
  -H "X-API-Key: YOUR_API_KEY"

​
Path Parameters

ParameterTypeDescription
groupIdUUIDThe ID of the group to retrieve

​
Response

Returns the group object with monitors and child groups. 
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "organization_id": "660e8400-e29b-41d4-a716-446655440001",
    "project_id": "770e8400-e29b-41d4-a716-446655440002",
    "name": "Production Services",
    "description": "Critical production monitoring group",
    "parent_group_id": null,
    "created_by": "880e8400-e29b-41d4-a716-446655440003",
    "check_count": 12,
    "created_at": "2024-12-26T10:30:00Z",
    "monitors": [
      {
        "id": "770e8400-e29b-41d4-a716-446655440010",
        "name": "API Server",
        "target_url": "https://api.example.com/health",
        "type": "http",
        "status": "active",
        "group_id": "550e8400-e29b-41d4-a716-446655440000"
      },
      {
        "id": "770e8400-e29b-41d4-a716-446655440011",
        "name": "Database Server",
        "target_url": "tcp://db.example.com:5432",
        "type": "port",
        "status": "active",
        "group_id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "children": [
      {
        "id": "880e8400-e29b-41d4-a716-446655440020",
        "organization_id": "660e8400-e29b-41d4-a716-446655440001",
        "project_id": "770e8400-e29b-41d4-a716-446655440002",
        "name": "Web Services",
        "description": "Frontend and web services",
        "parent_group_id": "550e8400-e29b-41d4-a716-446655440000",
        "check_count": 5,
        "created_at": "2024-12-26T11:00:00Z"
      },
      {
        "id": "880e8400-e29b-41d4-a716-446655440021",
        "organization_id": "660e8400-e29b-41d4-a716-446655440001",
        "project_id": "770e8400-e29b-41d4-a716-446655440002",
        "name": "Cache Layer",
        "description": "Redis and caching services",
        "parent_group_id": "550e8400-e29b-41d4-a716-446655440000",
        "check_count": 3,
        "created_at": "2024-12-26T11:05:00Z"
      }
    ],
    "path": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Production Services"
      }
    ]
  }
}

​
Response Fields

Group Object:
FieldTypeDescription
idUUIDUnique identifier
organization_idUUIDOrganization this group belongs to
project_idUUIDProject this group belongs to
namestringGroup name
descriptionstringGroup description (optional)
parent_group_idUUID | nullParent group ID (optional)
created_byUUID | nullUser who created the group
check_countnumberTotal monitors in this group
created_attimestampCreation timestamp
Monitors Array - List of monitors assigned to this group:
FieldTypeDescription
idUUIDMonitor ID
namestringMonitor name
target_urlstringThe URL or target being monitored
typestringMonitor type (http, port, ping, dns, keyword)
statusstringMonitor status: active or paused
group_idUUIDThe group this monitor belongs to
Children Array - List of child groups with the same structure as parent group. Child groups do not include their own nested monitors or children arrays. Path Array - Breadcrumb trail from root to this group:
FieldTypeDescription
idUUIDGroup ID
namestringGroup name

​
Status Codes

StatusDescription
200Successfully retrieved group
401Unauthorized (missing or invalid token)
403Forbidden (no permission to view group)
404Group not found

​
Error Codes

​
Group Not Found

{
  "success": false,
  "error": {
    "code": "GROUP_NOT_FOUND",
    "message": "Group not found or access denied"
  }
}

​
Unauthorized

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  }
}