Skip to main content
POST
/
v2
/
check-groups
Create a check group (V2)
curl --request POST \
  --url https://api.checklyhq.com/v2/check-groups \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Check group",
  "activated": true,
  "muted": false,
  "tags": [
    "production"
  ],
  "locations": [
    "us-east-1",
    "eu-central-1"
  ],
  "concurrency": 3,
  "apiCheckDefaults": {
    "url": "https://api.example.com/v1",
    "headers": [
      {
        "key": "Cache-Control",
        "value": "no-store"
      }
    ],
    "queryParameters": [
      {
        "key": "Page",
        "value": "1"
      }
    ],
    "assertions": [
      {
        "source": "STATUS_CODE",
        "comparison": "NOT_EMPTY",
        "target": "200"
      }
    ],
    "basicAuth": {
      "username": "admin",
      "password": "abc12345"
    }
  },
  "browserCheckDefaults": "<string>",
  "runtimeId": null,
  "environmentVariables": [
    {
      "key": "API_KEY",
      "value": "bAxD7biGCZL6K60Q",
      "locked": false,
      "secret": false
    }
  ],
  "alertChannelSubscriptions": [],
  "setupSnippetId": "null",
  "tearDownSnippetId": "null",
  "localSetupScript": "null",
  "localTearDownScript": "null",
  "privateLocations": [
    "data-center-eu"
  ],
  "runParallel": null,
  "alertSettings": null,
  "retryStrategy": {
    "type": "FIXED",
    "baseBackoffSeconds": 60,
    "sameRegion": true,
    "maxRetries": 5.5,
    "maxDurationSeconds": 300,
    "onlyOn": [
      "NETWORK_ERROR"
    ]
  },
  "useGlobalAlertSettings": null,
  "doubleCheck": false
}'
{
  "id": 1,
  "name": "Check group",
  "activated": true,
  "muted": true,
  "tags": [
    "production"
  ],
  "locations": [
    "us-east-1",
    "eu-central-1"
  ],
  "concurrency": 3,
  "apiCheckDefaults": {
    "url": "https://api.example.com/v1",
    "headers": [
      {
        "key": "Cache-Control",
        "value": "no-store"
      }
    ],
    "queryParameters": [
      {
        "key": "Page",
        "value": "1"
      }
    ],
    "assertions": [
      {
        "source": "STATUS_CODE",
        "comparison": "NOT_EMPTY",
        "target": "200"
      }
    ],
    "basicAuth": {
      "username": "admin",
      "password": "abc12345"
    }
  },
  "browserCheckDefaults": "<string>",
  "environmentVariables": [
    {
      "key": "API_KEY",
      "value": "<string>",
      "locked": false,
      "secret": false
    }
  ],
  "doubleCheck": true,
  "useGlobalAlertSettings": true,
  "alertSettings": {
    "escalationType": "RUN_BASED",
    "runBasedEscalation": {
      "failedRunThreshold": 1
    },
    "reminders": {
      "amount": 0,
      "interval": 5
    },
    "parallelRunFailureThreshold": {
      "enabled": false,
      "percentage": 10
    }
  },
  "alertChannelSubscriptions": [
    {
      "alertChannelId": 123,
      "activated": true
    }
  ],
  "setupSnippetId": "null",
  "tearDownSnippetId": "null",
  "localSetupScript": "null",
  "localTearDownScript": "null",
  "runtimeId": "null",
  "privateLocations": [
    "data-center-eu"
  ],
  "retryStrategy": {
    "type": "FIXED",
    "baseBackoffSeconds": 60,
    "sameRegion": true,
    "maxRetries": 5.5,
    "maxDurationSeconds": 300,
    "onlyOn": [
      "NETWORK_ERROR"
    ]
  },
  "created_at": "2023-12-25",
  "updated_at": "2023-11-07T05:31:56Z",
  "runParallel": false
}

​
Overview

Create a new check group to organize related checks and apply shared settings. Check groups help you manage multiple checks efficiently by providing common configuration, environment variables, and alert channels.
You can add checks to a group by setting the groupId property of individual checks.

Authorizations

​
Authorization
string
header
required

The Checkly Public API uses API keys to authenticate requests. You can get the API Key here. Your API key is like a password: keep it secure! Authentication to the API is performed using the Bearer auth method in the Authorization header and using the account ID. For example, set Authorization header while using cURL: curl -H "Authorization: Bearer [apiKey]" "X-Checkly-Account: [accountId]"

Headers

​
x-checkly-account
string

Your Checkly account ID, you can find it at https://app.checklyhq.com/settings/account/general

Query Parameters

​
autoAssignAlerts
boolean
default:true

Determines whether a new check will automatically be added as a subscriber to all existing alert channels when it gets created.

Body

application/json
​
name
string
required

The name of the check group.

Example:

"Check group"

​
activated
boolean
default:true

Determines if the checks in the group are running or not.

​
muted
boolean
default:false

Determines if any notifications will be send out when a check in this group fails and/or recovers.

​
tags
string[]

Tags for organizing and filtering checks.

Example:
["production"]
​
locations
enum<string>[]

An array of one or more data center locations where to run the checks.

Example:
["us-east-1", "eu-central-1"]
​
concurrency
number
default:3

Determines how many checks are invoked concurrently when triggering a check group from CI/CD or through the API.

Required range: x >= 1
​
apiCheckDefaults
object
Example:
{
  "url": "https://api.example.com/v1",
  "headers": [
    {
      "key": "Cache-Control",
      "value": "no-store"
    }
  ],
  "queryParameters": [{ "key": "Page", "value": "1" }],
  "assertions": [
    {
      "source": "STATUS_CODE",
      "comparison": "NOT_EMPTY",
      "target": "200"
    }
  ],
  "basicAuth": {
    "username": "admin",
    "password": "abc12345"
  }
}
​
browserCheckDefaults
string
​
runtimeId
enum<string>

The runtime version, i.e. fixed set of runtime dependencies, used to execute checks in this group.

Available options:
2025.04,
2024.09,
2024.02,
2023.09,
2023.02,
2022.10
​
environmentVariables
object[]
Maximum length: 50
​
alertChannelSubscriptions
object[]

List of alert channel subscriptions.

Example:
[]
​
setupSnippetId
number

An ID reference to a snippet to use in the setup phase of an API check in this group.

Example:

null

​
tearDownSnippetId
number

An ID reference to a snippet to use in the teardown phase of an API check in this group.

Example:

null

​
localSetupScript
string

A valid piece of Node.js code to run in the setup phase of an API check in this group.

Example:

null

​
localTearDownScript
string

A valid piece of Node.js code to run in the teardown phase of an API check in this group.

Example:

null

​
privateLocations
string[]

An array of one or more private locations where to run the checks.

Example:
["data-center-eu"]
​
runParallel
boolean

When true, the checks in the group will run in parallel in all selected locations.

​
alertSettings
object

Alert settings.

​
retryStrategy
object

The strategy to determine how failed checks are retried.

​
useGlobalAlertSettings
boolean

When true, the checks in the group will use the alert settings that are configured on the account

​
doubleCheck
boolean
default:false

Response

Created

​
name
string
required

The name of the check group.

Example:

"Check group"

​
activated
boolean
required

Determines if the checks in the group are running or not.

​
concurrency
number
default:3
required

Determines how many checks are invoked concurrently when triggering a check group from CI/CD or through the API.

Required range: x >= 1
​
apiCheckDefaults
object
required
​
id
number
Example:

1

​
muted
boolean

Determines if any notifications will be send out when a check in this group fails and/or recovers.

​
tags
string[]

Tags for organizing and filtering checks.

Example:
["production"]
​
locations
enum<string>[]

An array of one or more data center locations where to run the checks.

Example:
["us-east-1", "eu-central-1"]
​
browserCheckDefaults
string
​
environmentVariables
object[]
Maximum length: 50
​
doubleCheck
boolean

[Deprecated] Retry failed check runs. This property is deprecated, and retryStrategy can be used instead.

​
useGlobalAlertSettings
boolean

When true, the account level alert setting will be used, not the alert setting defined on this check group.

​
alertSettings
object

Alert settings.

​
alertChannelSubscriptions
object[]

List of alert channel subscriptions.

​
setupSnippetId
number

An ID reference to a snippet to use in the setup phase of an API check in this group.

Example:

null

​
tearDownSnippetId
number

An ID reference to a snippet to use in the teardown phase of an API check in this group.

Example:

null

​
localSetupScript
string

A valid piece of Node.js code to run in the setup phase of an API check in this group.

Example:

null

​
localTearDownScript
string

A valid piece of Node.js code to run in the teardown phase of an API check in this group.

Example:

null

​
runtimeId
enum<string>

The runtime version, i.e. fixed set of runtime dependencies, used to execute checks in this group.

Available options:
2025.04,
2024.09,
2024.02,
2023.09,
2023.02,
2022.10
Example:

null

​
privateLocations
string[]

An array of one or more private locations where to run the check.

Example:
["data-center-eu"]
​
retryStrategy
object

The strategy to determine how failed checks are retried.

​
created_at
string<date>
​
updated_at
string<date-time>
​
runParallel
boolean
default:false

When true, the checks in the group will run in parallel in all selected locations.

⌘I