CheckGroup Construct - Checkly Docs

Learn more about Check Groups in the Groups overview.

CheckGroup is deprecated. Please use CheckGroupV2 instead. See CheckGroupV2 documentation for details.

Use CheckGroup to organize your checks into logical groups. This provides better organization, shared configuration, and group-level controls for your monitoring setup.

import { ApiCheck, CheckGroup, Frequency } from "checkly/constructs"

const group = new CheckGroup("api-group-1", {
  name: "API Endpoints Group",
  activated: true,
  muted: false,
  frequency: Frequency.EVERY_15M,
  locations: ["us-east-1", "eu-west-1"],
  tags: ["api-group"],
})

new ApiCheck("api-check-1", {
  name: "API check #1",
  group,
  request: {
    method: "GET",
    url: "https://api.example.com/health",
  },
})

import {
  ApiCheck,
  CheckGroup,
  EmailAlertChannel,
  Frequency,
} from "checkly/constructs"

const emailChannel = new EmailAlertChannel("team-email", {
  address: "team@example.com",
})

const group = new CheckGroup("comprehensive-group", {
  name: "Comprehensive Monitoring Group",
  activated: true,
  muted: false,
  frequency: Frequency.EVERY_10M,
  locations: ["us-east-1", "eu-west-1"],
  tags: ["production", "critical"],
  concurrency: 5,
  environmentVariables: [
    { key: "API_BASE_URL", value: "https://api.example.com" },
    { key: "API_KEY", value: "{{SECRET_API_KEY}}", secret: true },
  ],
  alertChannels: [emailChannel],
  browserChecks: {
    frequency: Frequency.EVERY_30M,
    testMatch: "*.spec.js",
  },
})

new ApiCheck("api-check-1", {
  name: "API check #1",
  group,
  request: {
    method: "GET",
    url: "https://api.example.com/health",
  },
})

Configuration

Parameter	Type	Required	Default	Description
`name`	`string`	✅	-	Friendly name for your check group
`activated`	`boolean`	❌	`true`	Whether checks in the group are running
`apiCheckDefaults`	`object`	❌	-	Default settings for API checks in the group
`alertEscalationPolicy`	`AlertEscalationPolicy`	❌	-	Advanced alert escalation settings
`alertChannels`	`AlertChannel[]`	❌	`[]`	Alert channels for all checks in the group
`environmentVariables`	`object[]`	❌	`[]`	Group-level environment variables
`concurrency`	`number`	❌	`10`	Number of concurrent Checks to run when a group is triggered
`frequency`	`Frequency`	❌	-	How often to run checks within the group
`localSetupScript` (deprecated)	`string`	❌	-	Code to run before each check/monitor in this group
`localTearDownScript` (deprecated)	`string`	❌	-	Code to run after each check/monitor in this group
`locations`	`string[]`	❌	-	Public locations for all checks in the group
`muted`	`boolean`	❌	`false`	Whether alert notifications are muted
`privateLocations`	`string[]`	❌	-	Private Location slugs
`retryStrategy`	`RetryStrategy`	❌	-	Strategy for configured retries
`runtimeId`	`string`	❌	-	Runtime ID for all checks in the group
`runParallel`	`boolean`	❌	-	Whether to run checks in parallel across locations
`tags`	`string[]`	❌	`[]`	Tags to organize all checks in the group
`browserChecks`	`object`	❌	-	Settings for Browser Checks in the group
`multistepChecks`	`object`	❌	-	Settings for Multistep Checks in the group

Group Options

name

string

required

Friendly name for your check group that will be displayed in the Checkly dashboard and used for organization.Usage:

const group = new CheckGroup("api-monitoring-group", {
  name: "API Monitoring Group",
})

Use cases: Group organization, dashboard display, team coordination.

activated

boolean

default:"true"

Whether checks in the group are running. When false, all checks in the group are paused.Usage:

const group = new CheckGroup("api-monitoring-group", {
  name: "API Monitoring Group",
  activated: false,
})

Use cases: Environment-specific checks, maintenance windows, temporary disabling.

muted

boolean

default:"false"

Whether to mute alerts for all checks in the group. Checks will still run but won’t send notifications.Usage:

const group = new CheckGroup("api-monitoring-group", {
  name: "API Monitoring Group",
  muted: true, // Silence all alerts
})

Use cases: Non-production environments, testing phases, scheduled maintenance.

frequency

Frequency

How often to run checks within the group. This frequency applies to all checks in the group unless overridden at the check level.Usage:

import { Frequency } from 'checkly/constructs'

const group = new CheckGroup("api-monitoring-group", {
  name: "API Monitoring Group",
  frequency: Frequency.EVERY_10M,
})

Available frequencies: EVERY_10S, EVERY_20S, EVERY_30S, EVERY_1M, EVERY_2M, EVERY_5M, EVERY_10M, EVERY_15M, EVERY_30M, EVERY_1H, EVERY_2H, EVERY_6H, EVERY_12H, EVERY_24H

Generally, Check Groups support all available frequencies, but if a group includes a check type that doesn’t support high frequencies, npx checkly deploy will fail. We recommend separating high-frequency ones into their own groups.

locations

string[]

default:"[]"

Public locations for all checks in the group. Checks inherit these locations unless they specify their own.Usage:

const group = new CheckGroup("api-monitoring-group", {
  name: "API Monitoring Group",
  locations: ["us-east-1", "eu-west-1", "ap-southeast-1"],
})

Use cases: Global monitoring, regional service coverage, user experience testing.

browserChecks

object

Setting to automatically create and apply Browser Checks to a group.Usage:

const group = new CheckGroup("api-monitoring-group", {
  name: "API Monitoring Group",
  browserChecks: {
    testMatch: "./*.spec.ts",
  },
})

Use cases: Automated test discovery, E2E test organization, user flow monitoring.

multiStepChecks

object

Setting to automatically create and apply MultiStep Checks to a group.Usage:

const group = new CheckGroup("api-multistep-group", {
  name: "API Multistep Monitoring Group",
  multiStepChecks: {
    testMatch: "./*.multi-step.spec.ts",
  },
})

Use cases: Automated test discovery, E2E test organization, user flow monitoring.

Examples

API Monitoring Group
Multi-Service Group
Regional Group

const apiGroup = new CheckGroup("api-monitoring-group", {
  name: "API Monitoring",
  activated: true,
  frequency: Frequency.EVERY_5M,
  locations: ["us-east-1", "eu-west-1"],
  tags: ["api", "production"],
  environmentVariables: [
    { key: "API_BASE_URL", value: "https://api.example.com" },
    { key: "API_VERSION", value: "v2" },
  ],
  alertChannels: [slackChannel],
})

new ApiCheck("users-api", {
  name: "Users API",
  group: apiGroup,
  request: {
    method: "GET",
    url: "{{API_BASE_URL}}/{{API_VERSION}}/users",
  },
})

new ApiCheck("orders-api", {
  name: "Orders API",
  group: apiGroup,
  request: {
    method: "GET",
    url: "{{API_BASE_URL}}/{{API_VERSION}}/orders",
  },
})

const servicesGroup = new CheckGroup("services-monitoring", {
  name: "Core Services Monitoring",
  activated: true,
  frequency: Frequency.EVERY_10M,
  locations: ["us-east-1", "eu-west-1"],
  tags: ["services", "infrastructure"],
  alertChannels: [emailChannel],
  retryStrategy: RetryStrategyBuilder.linearStrategy({
    baseBackoffSeconds: 30,
    maxRetries: 3,
    sameRegion: false,
  }),
})

// API checks
new ApiCheck("database-health", {
  name: "Database Health",
  group: servicesGroup,
  request: {
    method: "GET",
    url: "https://api.example.com/health/database",
  },
})

// TCP monitors
new TcpMonitor("redis-connectivity", {
  name: "Redis Connectivity",
  group: servicesGroup,
  request: {
    hostname: "redis.example.com",
    port: 6379,
  },
})

// URL monitors
new UrlMonitor("cdn-availability", {
  name: "CDN Availability",
  group: servicesGroup,
  request: {
    url: "https://cdn.example.com/health",
  },
})

const regionalGroup = new CheckGroup("us-east-monitoring", {
  name: "US East Region Monitoring",
  activated: true,
  frequency: Frequency.EVERY_2M,
  locations: ["us-east-1"], // Single region focus
  tags: ["us-east", "regional"],
  runParallel: false, // Sequential execution
  alertEscalationPolicy: AlertEscalationBuilder.runBasedEscalation(2, {
    interval: 5,
    amount: 2,
  }),
})

new ApiCheck("us-east-api", {
  name: "US East API Endpoint",
  group: regionalGroup,
  request: {
    method: "GET",
    url: "https://us-east-api.example.com/health",
  },
})

​Configuration

​Group Options

​Examples

Configuration

Group Options

Examples