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,
      "maxRetries": 2,
      "maxDurationSeconds": 600,
      "sameRegion": true,
      "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.

​
Response Example

{
  "data": [
    {
      "id": "group_123456789",
      "name": "Production API Checks",
      "activated": true,
      "muted": false,
      "tags": ["production", "api"],
      "locations": ["us-east-1", "eu-west-1", "ap-southeast-1"],
      "frequency": 5,
      "environmentVariables": [
        {
          "key": "BASE_URL",
          "value": "https://api.production.com",
          "locked": false
        },
        {
          "key": "API_KEY",
          "value": "***masked***",
          "locked": true
        }
      ],
      "localSetupScript": "// Setup script for all checks in this group\nconsole.log('Setting up API tests');",
      "localTearDownScript": "// Cleanup script\nconsole.log('Cleaning up after tests');",
      "checksCount": 12,
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-20T14:45:00.000Z"
    },
    {
      "id": "group_987654321",
      "name": "E-commerce User Flows",
      "activated": true,
      "muted": false,
      "tags": ["ecommerce", "user-flows"],
      "locations": ["us-east-1", "us-west-2"],
      "frequency": 10,
      "environmentVariables": [
        {
          "key": "SHOP_URL",
          "value": "https://shop.example.com",
          "locked": false
        }
      ],
      "checksCount": 8,
      "createdAt": "2024-01-10T08:15:00.000Z",
      "updatedAt": "2024-01-18T16:20:00.000Z"
    }
  ],
  "meta": {
    "currentPage": 1,
    "totalPages": 1,
    "totalItems": 2,
    "limit": 10
  }
}

​
Check Group Benefits

Apply common settings across multiple checks:
  • Alert channels
  • Monitoring locations
  • Environment variables
  • Runtime settings
  • Retry strategies
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
Define common setup and teardown scripts that run before and after each check in the group, reducing code duplication.

​
Additional Examples

curl -X GET "https://api.checklyhq.com/v1/check-groups?tags=production&activated=true" \
  -H "Authorization: Bearer cu_1234567890abcdef" \
  -H "X-Checkly-Account: 550e8400-e29b-41d4-a716-446655440000"

​
Use Cases

Service Monitoring

Group all checks for a specific microservice or application

Environment Separation

Organize checks by environment (prod, staging, dev)

Team Organization

Create groups for different teams or departments

Batch Management

Manage multiple related checks as a single unit
Check groups are essential for organizing and managing checks at scale. They allow you to apply consistent settings across related checks and simplify maintenance operations.

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

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.