Groups help you organize your checks (e.g. by team or feature) and apply shared configuration such as API defaults, scheduling & location overrides, and other properties. Check group screenshot Groups serve multiple purposes: they act as organizational folders, configuration templates, and execution units. Think of them as the filing system for your monitoring infrastructure that transforms scattered checks into a coherent system reflecting your application architecture and team responsibilities. You can populate a group by moving existing checks into it or by creating new checks directly within the group.
By default, newly created check groups behave like folders, with no group-level configuration applied. To get started:

​
Configuration

Groups let you apply shared configuration to standardize how checks behave. Group-level configurations override check-level settings when applied.

​
Check Membership

Moving a check into a group: If the group has group-level configuration defined, adding a check may change how it runs. Settings like API defaults, locations & scheduling, or retries & alerting can override the check’s configuration. Removing check from group: Any group-level configuration will no longer apply, and the check will use its own configuration going forward.
To prevent issues (e.g. broken references to group variables), the check will be automatically deactivated after being added to or removed from a group. Make sure to review its settings before reactivating.
Using a set of shared defaults for API checks helps you manage checks that go to the same basic endpoint, share headers and other settings.

​
API request defaults

You can set defaults for many aspects of an API request, see the separate paragraphs below. The following properties are still controlled at the check level:
  • HTTP method & body
  • response time limits

​
Base URL

Use the base url to define the shared protocol, domain and path for URLs in your group’s API checks. This works as follows:
  1. Set the base URL, i.e. https://api.example.com/v1
  2. The base URL is now available in the {{GROUP_BASE_URL}} variable
  3. In your API check, append path and query params, i.e. {{GROUP_BASE_URL}}/customers?page=1

​
Headers & query parameters

Any headers and query parameters defined in the API check defaults are injected into each API check.
Headers and query parameters at the check level override those at the group level with the same name.
An example:
  1. At the group level, you define the header X-Custom: with value 123
  2. At the API check level, you define the same header X-Custom just with the value abc
  3. Checkly will call your API with the X-Custom: abc header

​
Basic Auth

Use the basic auth username and password to inject it into each API check in the group.

​
Assertions

Any assertions are injected into each API check’s assertion list. Use this to always assert common response codes or headers for your API checks.

​
Setup & teardown scripts

You can add setup and teardown scripts at the group level as well as the individual group level. This is the execution flow:
  1. Group level setup script
  2. Check level setup script
  3. Execute your API check
  4. Check level teardown script
  5. Group level teardown script
A common scenario for having two levels of setup scripts is the following:
  1. Group level setup: Fetch a token from a common authentication endpoint.
  2. Check level: prep some specific test data for this individual check.

​
Variables

You can set both variables and secrets for a Group of checks. For browser and multistep checks, you can set variables at the check level. See browser check variables and secrets for more details.
Secrets are fully supported starting with runtime version 2024.09 and later. For Private Locations, secrets are available in agent version 3.3.4 and later, and for the CLI, in version 4.9.0 and later.

​
Variable hierarchy

As checks are scheduled, Checkly merges the check, group and global environment variables into one data set and exposes them to the runtime environment. During merging, any check variable with the same name as a global or group variable overrides that variable. Or, in other words: check variables trump group variables trump global variables. You can make use of this by providing a default value for a specific variable at the global or group level, but allow that variable to be overridden at the group level or check level.

​
Scheduling & Locations

  • Locations: Override location settings for all checks in the group with selected public or private locations
  • Scheduling strategy: Override scheduling strategy (parallel, round-robin) for all checks in the group
  • Frequency: Set a default scheduling interval for new checks created in the group

​
Retries & Alerting

  • Retries: Configure retry strategy for failed checks (fixed, linear, exponential)
  • Alert settings: Set up alert channels for the group - email, SMS, Slack, webhooks, etc.

​
Testing & Runtimes

  • Testing: Run checks in this group as E2E tests locally or from CI/CD pipelines
  • Runtimes: Set the JavaScript runtime environment for browser checks and scripts if different from account default

​
How Grouped Checks Execute

Understanding how grouped checks run is important for sophisticated monitoring setups:
  1. Individual scheduling: Checks are scheduled as individual checks, not “as a group”
  2. Group triggers: Calling a “group run” using CLI or GitHub integration runs all checks in the group
  3. No group state: The group itself does not have an explicit runtime state
  4. Individual results: No results or metrics are collected at the group level
  5. Independent timing: Checks in a group maintain their individual scheduling settings
Groups are primarily configuration containers that provide shared settings and organizational structure. This approach ensures flexibility while enabling powerful configuration management at scale.

​
Flexible Configuration Strategy

Groups can serve different organizational needs:
  • Strict templates: Enforce consistency through shared configurations
  • Loose containers: Provide structure without imposing shared settings
  • Team boundaries: Enable clear ownership and delegation of monitoring responsibilities
  • Scaling mechanism: Manage complexity through logical decomposition as your infrastructure grows