Trigger a new check session

Starts a check session for each check that matches the provided target filters. If no filters are given, matches all eligible checks.

This endpoint does not wait for the check session to complete. Use the GET /v1/check-sessions/{checkSessionId}/completion or GET /v1/check-sessions/{checkSessionId} endpoints to track progress if needed.

Standard alerting rules apply to finished check runs.

Equivalent to the Schedule Now button in the UI.

POST /v1/check-sessions/trigger

Try it

Trigger a new check session

cURL

curl --request POST \
  --url https://api.checklyhq.com/v1/check-sessions/trigger \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "target": {
    "matchTags": [
      [
        "production",
        "!skip-e2e"
      ]
    ],
    "checkId": [
      "a4cd4ad9-4815-4a9e-92d2-0a7c562ee69a"
    ]
  }
}
'

201

{
  "sessions": [
    {
      "checkSessionId": "8166fa86-c9b4-4162-8541-d380c6c212d8",
      "checkSessionLink": "https://app.checklyhq.com/accounts/1397c172-1938-4973-a225-5862298e571a/checks/a4cd4ad9-4815-4a9e-92d2-0a7c562ee69a/check-sessions/8166fa86-c9b4-4162-8541-d380c6c212d8",
      "checkId": "a4cd4ad9-4815-4a9e-92d2-0a7c562ee69a",
      "checkType": "API",
      "status": "PASSED",
      "startedAt": "2025-08-28T18:23:40.262Z",
      "timeElapsed": 300731,
      "runLocations": [
        "us-east-1",
        "eu-central-1"
      ],
      "name": "Example API Check",
      "stoppedAt": "2025-08-28T18:28:40.993Z"
    }
  ]
}

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]"

Body

application/json

target · object

Show child attributes

target. matchTags · string[][]

Match checks with the given tags. Group tags also match.

The value is a two-dimensional array. The top level array defines OR conditions, and the second level AND conditions. Tags can also be prefixed with ! to only match checks without those tags.

Example: [[a, b], [a, c, !d]] means (a && b) || (a && c && !d).

Example:

[["production", "!skip-e2e"]]

target. checkId · string[]

Match checks with the given identifiers.

Example:

["a4cd4ad9-4815-4a9e-92d2-0a7c562ee69a"]

Response

201

application/json

Returns a check session for each check matching target conditions.

Returns a check session for each check matching target conditions.

sessions · object[] · required

A list of check sessions, with one check session for each check.

Show child attributes

sessions. checkSessionId · string · required

The unique identifier of the check session.

Example:

"8166fa86-c9b4-4162-8541-d380c6c212d8"

sessions. checkSessionLink · string · required

A link to the check session.

Example:

"https://app.checklyhq.com/accounts/1397c172-1938-4973-a225-5862298e571a/checks/a4cd4ad9-4815-4a9e-92d2-0a7c562ee69a/check-sessions/8166fa86-c9b4-4162-8541-d380c6c212d8"

sessions. checkId · string · required

The ID of the check.

Example:

"a4cd4ad9-4815-4a9e-92d2-0a7c562ee69a"

sessions. checkType · enum<string> · required

Available options: API, BROWSER, MULTI_STEP, TCP, PLAYWRIGHT, URL, DNS

Example:

"API"

sessions. status · enum<string> · required

The status of the check session.

Available options: STARTED, PROGRESS, FAILED, PASSED, DEGRADED, PROGRESS_FAILED, PROGRESS_DEGRADED, TIMED_OUT

Example:

"PASSED"

sessions. startedAt · string<date-time> · required

The date and time when the session started.

Example:

"2025-08-28T18:23:40.262Z"

sessions. timeElapsed · number · required

The time the check session took, in milliseconds.

Example:

300731

sessions. runLocations · string[] · required

The run locations of the check session.

Example:

["us-east-1", "eu-central-1"]

sessions. name · string

Example:

"Example API Check"

sessions. stoppedAt · string<date-time> | null

The date and time when the session stopped.

Example:

"2025-08-28T18:28:40.993Z"