Create Check Group

Create a new check group to organize related checks

Overview

Create a new check group to organize related checks and apply shared settings. Check groups help you manage multiple checks efficiently by providing common configuration, environment variables, and alert channels.

Request Example

{
  "name": "Production API Monitoring",
  "activated": true,
  "muted": false,
  "tags": ["production", "api", "critical"],
  "locations": ["us-east-1", "eu-west-1", "ap-southeast-1"],
  "frequency": 5,
  "environmentVariables": [
    {
      "key": "BASE_URL",
      "value": "https://api.production.com",
      "locked": false
    },
    {
      "key": "API_TOKEN",
      "value": "your-secret-token",
      "locked": true
    }
  ],
  "localSetupScript": "// Global setup for all checks in this group\nconst setupData = {\n  timestamp: Date.now(),\n  environment: 'production'\n};\nconsole.log('Setup completed:', setupData);",
  "localTearDownScript": "// Global cleanup\nconsole.log('Teardown completed');",
  "alertSettings": {
    "escalationType": "RUN_BASED",
    "runBasedEscalation": {
      "failedRunThreshold": 1
    },
    "timeBasedEscalation": {
      "minutesFailingThreshold": 5
    },
    "reminders": {
      "amount": 2,
      "interval": 5
    },
    "sslCertificates": {
      "enabled": true,
      "alertThreshold": 30
    }
  },
  "useGlobalAlertSettings": false,
  "alertChannelSubscriptions": [
    {
      "channelId": 123,
      "activated": true
    },
    {
      "channelId": 456,
      "activated": true
    }
  ]
}

Response Example

{
  "id": "group_789123456",
  "name": "Production API Monitoring",
  "activated": true,
  "muted": false,
  "tags": ["production", "api", "critical"],
  "locations": ["us-east-1", "eu-west-1", "ap-southeast-1"],
  "frequency": 5,
  "environmentVariables": [
    {
      "key": "BASE_URL",
      "value": "https://api.production.com",
      "locked": false
    },
    {
      "key": "API_TOKEN",
      "value": "***masked***",
      "locked": true
    }
  ],
  "localSetupScript": "// Global setup for all checks in this group\nconst setupData = {\n  timestamp: Date.now(),\n  environment: 'production'\n};\nconsole.log('Setup completed:', setupData);",
  "localTearDownScript": "// Global cleanup\nconsole.log('Teardown completed');",
  "alertSettings": {
    "escalationType": "RUN_BASED",
    "runBasedEscalation": {
      "failedRunThreshold": 1
    },
    "reminders": {
      "amount": 2,
      "interval": 5
    },
    "sslCertificates": {
      "enabled": true,
      "alertThreshold": 30
    }
  },
  "useGlobalAlertSettings": false,
  "alertChannelSubscriptions": [
    {
      "channelId": 123,
      "activated": true
    }
  ],
  "checksCount": 0,
  "createdAt": "2024-01-25T10:30:00.000Z",
  "updatedAt": "2024-01-25T10:30:00.000Z"
}

Configuration Options

Basic Settings

Required Fields:

• name (string): Display name for the check group

Optional Fields:

• activated (boolean): Whether checks in this group are active (default: true)
• muted (boolean): Whether alerts are muted (default: false)
• tags (array): Tags for organization and filtering
• locations (array): Default monitoring locations for checks
• frequency (integer): Default check frequency in minutes

Environment Variables

Define shared environment variables for all checks in the group:

{
  "environmentVariables": [
    {
      "key": "API_URL",
      "value": "https://api.example.com",
      "locked": false
    },
    {
      "key": "SECRET_KEY",
      "value": "sensitive-value",
      "locked": true
    }
  ]
}

• locked: true means the value is encrypted and masked in responses

Setup and Teardown Scripts

Define JavaScript code that runs before and after each check:

Setup Script:

• Runs before each check execution
• Can prepare test data or environment
• Available to all checks in the group

Teardown Script:

• Runs after each check execution
• Can clean up resources or log results
• Executes regardless of check success/failure

Alert Settings

Configure how and when alerts are triggered:

Escalation Types:

• RUN_BASED: Alert after N failed runs
• TIME_BASED: Alert after failing for N minutes

SSL Certificate Monitoring:

• Monitor SSL certificates in the group
• Set days before expiration to alert

Reminders:

• Send follow-up alerts if issues persist
• Configure frequency and count

Code Examples

cURL

curl -X POST "https://api.checklyhq.com/v1/check-groups" \
  -H "Authorization: Bearer cu_1234567890abcdef" \
  -H "X-Checkly-Account: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "E-commerce User Flows",
    "tags": ["ecommerce", "critical"],
    "locations": ["us-east-1", "eu-west-1"],
    "frequency": 10,
    "environmentVariables": [
      {
        "key": "SHOP_URL",
        "value": "https://shop.example.com",
        "locked": false
      }
    ]
  }'

Best Practices

Naming Convention

Use descriptive names that indicate:

• The purpose or service being monitored
• The environment (production, staging)
• The type of checks (API, UI, health)

Examples:

• “Production Payment API”
• “Staging User Authentication”
• “E-commerce Checkout Flow”

Environment Variables

• Use environment variables for URLs, API keys, and configuration
• Mark sensitive values as locked: true
• Use consistent naming conventions across groups
• Consider using different groups for different environments

Alert Configuration

• Set appropriate escalation thresholds based on criticality
• Use different alert channels for different severity levels
• Configure reminders for persistent issues
• Enable SSL certificate monitoring for HTTPS endpoints

Setup and Teardown Scripts

• Keep scripts focused and lightweight
• Use setup scripts for common test data preparation
• Use teardown scripts for cleanup and logging
• Test scripts thoroughly before deployment

After creating a check group, you can add checks to it and they will inherit the group’s default settings. You can always override group settings at the individual check level when needed.