> ## Documentation Index
> Fetch the complete documentation index at: https://checkly-422f444a-playwright-vs-cypress-2026.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# CheckGroup Construct

> Learn how to configure check groups with the Checkly CLI.

<Tip>
  Learn more about Check Groups in [the Groups overview](/platform/groups).
</Tip>

<Warning>`CheckGroup` is deprecated. Please use `CheckGroupV2` instead. See [CheckGroupV2 documentation](/constructs/check-group-v2) for details.</Warning>

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

<CodeGroup>
  ```ts Basic Example theme={null}
  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",
    },
  })
  ```

  ```ts Advanced Example theme={null}
  import {
    ApiCheck,
    CheckGroup,
    EmailAlertChannel,
    Frequency,
  } from "checkly/constructs"
  import { secret } from "checkly/util"

  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",
    },
  })
  ```
</CodeGroup>

## 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

<ResponseField name="name" type="string" required>
  Friendly name for your check group that will be displayed in the Checkly dashboard and used for organization.

  **Usage:**

  ```ts highlight={2} theme={null}
  const group = new CheckGroup("api-monitoring-group", {
    name: "API Monitoring Group",
  })
  ```

  **Use cases**: Group organization, dashboard display, team coordination.
</ResponseField>

<ResponseField name="activated" type="boolean" default="true">
  Whether checks in the group are running. When false, all checks in the group are paused.

  **Usage:**

  ```ts highlight={3} theme={null}
  const group = new CheckGroup("api-monitoring-group", {
    name: "API Monitoring Group",
    activated: false,
  })
  ```

  **Use cases**: Environment-specific checks, maintenance windows, temporary disabling.
</ResponseField>

<ResponseField name="muted" type="boolean" default="false">
  Whether to mute alerts for all checks in the group. Checks will still run but won't send notifications.

  **Usage:**

  ```ts highlight={3} theme={null}
  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.
</ResponseField>

<ResponseField name="frequency" type="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:**

  ```ts highlight={5} theme={null}
  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`

  <Tip>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.</Tip>
</ResponseField>

<ResponseField name="locations" type="string[]" default="[]">
  Public locations for all checks in the group. Checks inherit these locations unless they specify their own.

  **Usage:**

  ```ts highlight={3} theme={null}
  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.
</ResponseField>

<ResponseField name="browserChecks" type="object">
  Setting to automatically create and apply Browser Checks to a group.

  **Usage:**

  ```ts highlight={3-5} theme={null}
  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.
</ResponseField>

<ResponseField name="multiStepChecks" type="object">
  Setting to automatically create and apply MultiStep Checks to a group.

  **Usage:**

  ```ts highlight={3-5} theme={null}
  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.
</ResponseField>

## Examples

<Tabs>
  <Tab title="API Monitoring Group">
    ```ts theme={null}
    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",
      },
    })
    ```
  </Tab>

  <Tab title="Multi-Service Group">
    ```ts theme={null}
    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",
      },
    })
    ```
  </Tab>

  <Tab title="Regional Group">
    ```ts theme={null}
    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",
      },
    })
    ```
  </Tab>
</Tabs>