CheckGroupV2 Construct

Learn how to configure check groups with the Checkly CLI.

Learn more about Check Groups in the Groups overview.

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

CheckGroupV2 Structure

Basic Example

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

const group = new CheckGroupV2("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",
  },
})

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 CheckGroupV2("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 CheckGroupV2("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 CheckGroupV2("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 CheckGroupV2('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 CheckGroupV2("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 CheckGroupV2("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 CheckGroupV2("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.

alertEscalationPolicy · object

An AlertEscalationPolicy object defines alert-settings for Check runs.

If set to 'global', it overrides the alert settings of all checks in the group to use the global account notification settings. If set to specific values, it overrides the alert settings of all checks in the group. If not set, each Check uses its own alert configuration.

Examples

API Monitoring Group

const apiGroup = new CheckGroupV2("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",
  },
})

Multi-Service Group

const servicesGroup = new CheckGroupV2("services-monitoring", {
  name: "Core Services Monitoring",
  activated: true,
  frequency: Frequency.EVERY_10M,
  locations: ["us-east-1", "eu-west-1"],
  tags: ["services", "infrastructure"],
  alertChannels: [emailChannel, pagerdutyChannel],
  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",
  },
})

Regional Group

const regionalGroup = new CheckGroupV2("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",
  },
})