Skip to main content
GET
/
v1
/
check-groups
List all check groups
curl --request GET \
  --url https://api.checklyhq.com/v1/check-groups \
  --header 'Authorization: <api-key>'
[
  {
    "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

Check groups allow you to organize related checks together and apply shared settings like alert channels, locations, and environment variables. This endpoint returns all check groups in your account.

​
Check Group Benefits

Apply common settings across multiple checks:
  • Alert channels
  • Monitoring locations
  • Environment variables
  • Runtime settings
  • Retry strategies
  • API check settings, like request settings and setup/teardown scripts
Group related checks by:
  • Application or service
  • Environment (production, staging)
  • Team ownership
  • Criticality level
  • Testing type
Perform actions on multiple checks simultaneously:
  • Enable/disable all checks in a group
  • Update shared environment variables
  • Change monitoring frequency
  • Modify alert subscriptions

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

​
limit
integer
default:10

Limit the number of results

Required range: 1 <= x <= 100
​
page
number
default:1

Page number

​
tag
string[]

Filters check groups by tags. Returns check groups that have at least one of the specified tags.

​
name
string[]

Filters check groups by exact name match. Accepts one or more names and returns groups that match any of the specified names.

Response

Successful

​
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