POST
/
v1
/
check-groups
Create a check group
curl --request POST \
  --url https://api.checklyhq.com/v1/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
    }
  ],
  "doubleCheck": true,
  "useGlobalAlertSettings": true,
  "alertSettings": {
    "escalationType": "RUN_BASED",
    "runBasedEscalation": {
      "failedRunThreshold": 1
    },
    "reminders": {
      "amount": 0,
      "interval": 5
    },
    "parallelRunFailureThreshold": {
      "enabled": false,
      "percentage": 10
    }
  },
  "alertChannelSubscriptions": [],
  "setupSnippetId": "null",
  "tearDownSnippetId": "null",
  "localSetupScript": "null",
  "localTearDownScript": "null",
  "privateLocations": [
    "data-center-eu"
  ],
  "runParallel": false,
  "retryStrategy": {
    "type": "FIXED",
    "baseBackoffSeconds": 60,
    "maxRetries": 2,
    "maxDurationSeconds": 600,
    "sameRegion": true,
    "onlyOn": [
      "NETWORK_ERROR"
    ]
  }
}'
{
  "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

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.

​
Request Example

{
  "name": "Production API Monitoring",
  "activated": true,
  "muted": false,
  "tags": ["production", "api", "critical"],
  "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_TOKEN",
      "value": "your-secret-token",
      "locked": true
    }
  ],
  "localSetupScript": "// Global setup for all checks in this group\nconst setupData = {\n  timestamp: Date.now(),\n  environment: 'production'\n};\nconsole.log('Setup completed:', setupData);",
  "localTearDownScript": "// Global cleanup\nconsole.log('Teardown completed');",
  "alertSettings": {
    "escalationType": "RUN_BASED",
    "runBasedEscalation": {
      "failedRunThreshold": 1
    },
    "timeBasedEscalation": {
      "minutesFailingThreshold": 5
    },
    "reminders": {
      "amount": 2,
      "interval": 5
    },
    "sslCertificates": {
      "enabled": true,
      "alertThreshold": 30
    }
  },
  "useGlobalAlertSettings": false,
  "alertChannelSubscriptions": [
    {
      "channelId": 123,
      "activated": true
    },
    {
      "channelId": 456,
      "activated": true
    }
  ]
}

​
Response Example

{
  "id": "group_789123456",
  "name": "Production API Monitoring",
  "activated": true,
  "muted": false,
  "tags": ["production", "api", "critical"],
  "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_TOKEN",
      "value": "***masked***",
      "locked": true
    }
  ],
  "localSetupScript": "// Global setup for all checks in this group\nconst setupData = {\n  timestamp: Date.now(),\n  environment: 'production'\n};\nconsole.log('Setup completed:', setupData);",
  "localTearDownScript": "// Global cleanup\nconsole.log('Teardown completed');",
  "alertSettings": {
    "escalationType": "RUN_BASED",
    "runBasedEscalation": {
      "failedRunThreshold": 1
    },
    "reminders": {
      "amount": 2,
      "interval": 5
    },
    "sslCertificates": {
      "enabled": true,
      "alertThreshold": 30
    }
  },
  "useGlobalAlertSettings": false,
  "alertChannelSubscriptions": [
    {
      "channelId": 123,
      "activated": true
    }
  ],
  "checksCount": 0,
  "createdAt": "2024-01-25T10:30:00.000Z",
  "updatedAt": "2024-01-25T10:30:00.000Z"
}

​
Configuration Options

Required Fields:
  • name (string): Display name for the check group
Optional Fields:
  • activated (boolean): Whether checks in this group are active (default: true)
  • muted (boolean): Whether alerts are muted (default: false)
  • tags (array): Tags for organization and filtering
  • locations (array): Default monitoring locations for checks
  • frequency (integer): Default check frequency in minutes
Define shared environment variables for all checks in the group:
{
  "environmentVariables": [
    {
      "key": "API_URL",
      "value": "https://api.example.com",
      "locked": false
    },
    {
      "key": "SECRET_KEY",
      "value": "sensitive-value",
      "locked": true
    }
  ]
}
  • locked: true means the value is encrypted and masked in responses
Define JavaScript code that runs before and after each check:Setup Script:
  • Runs before each check execution
  • Can prepare test data or environment
  • Available to all checks in the group
Teardown Script:
  • Runs after each check execution
  • Can clean up resources or log results
  • Executes regardless of check success/failure
Configure how and when alerts are triggered:Escalation Types:
  • RUN_BASED: Alert after N failed runs
  • TIME_BASED: Alert after failing for N minutes
SSL Certificate Monitoring:
  • Monitor SSL certificates in the group
  • Set days before expiration to alert
Reminders:
  • Send follow-up alerts if issues persist
  • Configure frequency and count

​
Code Examples

curl -X POST "https://api.checklyhq.com/v1/check-groups" \
  -H "Authorization: Bearer cu_1234567890abcdef" \
  -H "X-Checkly-Account: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "E-commerce User Flows",
    "tags": ["ecommerce", "critical"],
    "locations": ["us-east-1", "eu-west-1"],
    "frequency": 10,
    "environmentVariables": [
      {
        "key": "SHOP_URL",
        "value": "https://shop.example.com",
        "locked": false
      }
    ]
  }'

​
Best Practices

Use descriptive names that indicate:
  • The purpose or service being monitored
  • The environment (production, staging)
  • The type of checks (API, UI, health)
Examples:
  • “Production Payment API”
  • “Staging User Authentication”
  • “E-commerce Checkout Flow”
  • Use environment variables for URLs, API keys, and configuration
  • Mark sensitive values as locked: true
  • Use consistent naming conventions across groups
  • Consider using different groups for different environments
  • Set appropriate escalation thresholds based on criticality
  • Use different alert channels for different severity levels
  • Configure reminders for persistent issues
  • Enable SSL certificate monitoring for HTTPS endpoints
  • Keep scripts focused and lightweight
  • Use setup scripts for common test data preparation
  • Use teardown scripts for cleanup and logging
  • Test scripts thoroughly before deployment
After creating a check group, you can add checks to it and they will inherit the group’s default settings. You can always override group settings at the individual check level when needed.

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
​
doubleCheck
boolean
default:true

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

​
useGlobalAlertSettings
boolean
default:true

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.

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
default:false

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

​
retryStrategy
object

The strategy to determine how failed checks are retried.

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.