> ## Documentation Index
> Fetch the complete documentation index at: https://www.checklyhq.com/docs/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](https://www.checklyhq.com/docs/platform/groups.md).

> [!WARNING]
>
> `CheckGroup` is deprecated. Please use `CheckGroupV2` instead. See [CheckGroupV2 documentation](https://www.checklyhq.com/docs/constructs/check-group-v2.md) 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.

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

## 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` | ❌ | [`singleRetry()`](https://www.checklyhq.com/docs/constructs/retry-strategy#default-retry-strategy) | 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:**

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

```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.

**muted** `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.

**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:**

```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.

**locations** `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.

**browserChecks** `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.

**multiStepChecks** `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.

## Examples

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

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

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.