Skip to main content

​
Overview

Retrieve a paginated list of all monitor groups in your organization.

​
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" \
  -H "X-API-Key: YOUR_API_KEY"

​
Query Parameters

ParameterTypeDefaultDescription
pageinteger1Page number for pagination
limitinteger10Number of groups per page (1-100)

​
Response

Returns a paginated list of groups with metadata. 
{
  "success": true,
  "data": {
    "groups": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Production Services",
        "description": "Critical production monitoring group",
        "parent_group_id": null,
        "check_count": 12,
        "created_at": "2024-12-26T10:30:00Z",
        "created_by": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      },
      {
        "id": "660e8400-e29b-41d4-a716-446655440001",
        "name": "Development Services",
        "description": "Development environment services",
        "parent_group_id": null,
        "check_count": 8,
        "created_at": "2024-12-25T15:20:00Z",
        "created_by": null
      }
    ],
    "total": 42,
    "page": 1,
    "limit": 10
  }
}

​
Response Fields

Data Object:
FieldTypeDescription
groupsarrayList of group objects
totalintegerTotal number of groups
pageintegerCurrent page number
limitintegerNumber of items per page
Groups Array - List of group objects:
FieldTypeDescription
idUUIDUnique identifier for the group
namestringGroup name
descriptionstringGroup description
parent_group_idUUID | nullParent group ID if nested
check_countnumberNumber of checks in this group
created_attimestampCreation timestamp
created_byUUID | nullUser who created the group (optional)

​
Status Codes

StatusDescription
200Successfully retrieved groups
400Invalid query parameters
401Unauthorized (missing or invalid token)

​
Examples

​
Get All Groups

curl -X GET https://api.uptimeio.com/api/groups \
  -H "X-API-Key: YOUR_API_KEY"

​
Error Codes

​
Invalid Page

{
  "success": false,
  "error": {
    "code": "INVALID_PAGE",
    "message": "Page must be a positive integer"
  }
}

​
Invalid Limit

{
  "success": false,
  "error": {
    "code": "INVALID_LIMIT",
    "message": "Limit must be between 1 and 100"
  }
}

​
Unauthorized

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