Skip to main content
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

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

ParameterTypeRequiredDefaultDescription
namestring✅-Friendly name for your check group
activatedboolean❌trueWhether checks in the group are running
apiCheckDefaultsobject❌-Default settings for API checks in the group
alertEscalationPolicyAlertEscalationPolicy❌-Advanced alert escalation settings
alertChannelsAlertChannel[]❌[]Alert channels for all checks in the group
environmentVariablesobject[]❌[]Group-level environment variables
concurrencynumber❌10Number of concurrent Checks to run when a group is triggered
frequencyFrequency❌-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
locationsstring[]❌-Public locations for all checks in the group
mutedboolean❌falseWhether alert notifications are muted
privateLocationsstring[]❌-Private Location slugs
retryStrategyRetryStrategy❌-Strategy for configured retries
runtimeIdstring❌-Runtime ID for all checks in the group
runParallelboolean❌-Whether to run checks in parallel across locations
tagsstring[]❌[]Tags to organize all checks in the group
browserChecksobject❌-Settings for Browser Checks in the group
multistepChecksobject❌-Settings for Multistep Checks in the group
If you want the group’s alert settings to override check-level alert settings, you must set the alertEscalationPolicy. Otherwise, the alert settings of individual checks will be used, even if alertChannels is defined in your 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.

​
Reference an existing group by ID

To add checks to an existing group in your account, find the group ID in the Checkly web UI or via the API and reference it using CheckGroupV2.fromId().
  • Web UI
  • API
Navigate to the group in the Checkly UI and copy the group ID from the URL or the group details.
Using Existing Group
// Reference an existing group by ID
const existingGroup = CheckGroupV2.fromId(123)

new ApiCheck("existing-group-check", {
  name: "Check with Existing Group",
  group: existingGroup,
  request: {
    method: "GET",
    url: "https://api.example.com/endpoint",
  },
})
When referencing existing groups with fromId(), note:
  • You cannot filter tests by group tags since group properties aren’t available locally
  • Checks won’t inherit the group’s frequency. This only works for groups defined in the CLI project
If you need these features, you can either import the group using the Checkly import feature (e.g. npx checkly import check-group:123) or define a new group directly in your project.

​
Shared Settings in Groups with Different Monitor Types

With CheckGroupV2 you can group uptime monitors (e.g. URL, TCP, DNS) and synthetic checks (e.g. API, Multistep, Playwright Check Suites). Depending on your plan type, some group settings (such as parallel runs or advanced retry strategies) may not be supported across both monitor types. To avoid conflicts, Checkly validates group settings against the lowest common denominator of supported features in the group. See Mixing Checks and Monitors in a Group for details.

​
Examples

  • API Monitoring Group
  • Multi-Service Group
  • Regional 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" },
  ],
  alertEscalationPolicy: 'global',
  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",
  },
})