CHchecklyhq
Check sessions

Await the completion of a check session

Changed on

Call this endpoint to await the completion of a check session. A successful response will be returned once the check session reaches its final state (i.e. when it passes or fails).

If the check session takes a long time to complete, the endpoint will return a timeout error code. You should keep calling the endpoint until you receive a successful response, or a non-timeout related error code. If using curl, its --retry option is suitable.

The successful response of this endpoint is equivalent to the GET /v1/check-sessions/{checkSessionId} endpoint's response for a completed check session.

get/v1/check-sessions/{checkSessionId}/completion

Request

Path parameters

checkSessionIdstring required

The unique identifier of the check session.

Query parameters

maxWaitSecondsnumber

The maximum time to wait for completion, in seconds.

Example:30

Response

Returned when the check session has finished running.

checkSessionIdstring required

The unique identifier of the check session.

checkSessionLinkstring required

A link to the check session.

checkIdstring required

The ID of the check.

checkType'AGENTIC' | 'API' | 'BROWSER' | 'ICMP' | 'MULTI_STEP' | 'TCP' | 'PLAYWRIGHT' | 'TRACEROUTE' | 'URL' | 'DNS' | 'SSL' | 'GRPC' required
namestring
status'FAILED' | 'PASSED' | 'DEGRADED' | 'TIMED_OUT' | 'CANCELLED' required

The final status of the check session.

startedAtstring date-time required

The date and time when the session started.

stoppedAtstring date-time required

The date and time when the session stopped.

timeElapsednumber required

The time the check session took, in milliseconds.

runLocationsstring[] required

The run locations of the check session.

runSource'CLI_DEPLOY' | 'DEPLOYMENT' | 'DEPLOYMENT_CACHE_WARMER' | 'EDITOR' | 'GROUP_RUN_ALL' | 'LEGACY_TRIGGER' | 'SCHEDULER' | 'SCHEDULE_NOW' | 'SLACK_RERUN' | 'TEST_NO_RECORD' | 'TEST_RECORD' | 'TRIGGER_NO_RECORD' | 'TRIGGER_RECORD' | 'TRIGGER_API' nullable

The source that triggered the check session.

Example response

{
  "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",
  "name": "Example API Check",
  "status": "PASSED",
  "startedAt": "2025-08-28T18:23:40.262Z",
  "stoppedAt": "2025-08-28T18:28:40.993Z",
  "timeElapsed": 300731,
  "runLocations": [
    "us-east-1",
    "eu-central-1"
  ],
  "runSource": "TRIGGER_API",
  "results": [
    {
      "checkResultId": "22be3b52-5ec2-4894-9086-b5b4a8b00a89",
      "checkResultLink": "https://app.checklyhq.com/accounts/1397c172-1938-4973-a225-5862298e571a/checks/a4cd4ad9-4815-4a9e-92d2-0a7c562ee69a/check-sessions/8166fa86-c9b4-4162-8541-d380c6c212d8/results/22be3b52-5ec2-4894-9086-b5b4a8b00a89",
      "checkId": "a4cd4ad9-4815-4a9e-92d2-0a7c562ee69a",
      "checkType": "API",
      "name": "Example API Check",
      "runLocation": "us-east-1",
      "resultType": "FINAL",
      "responseTime": 1234,
      "startedAt": "2025-08-28T18:23:40.262Z",
      "stoppedAt": "2025-08-28T18:23:41.496Z"
    }
  ]
}

Changes

  • bc90d1bfa738Revision changes
    • info

      added the optional property to the response with the status

  • a4fea1ad9b9aRevision changes
    • warning

      added the new GRPC enum value to the response property for the response status

    • warning

      added the new GRPC enum value to the // response property for the response status

    • warning

      added the new SSL enum value to the response property for the response status

    • warning

      added the new SSL enum value to the // response property for the response status

    • warning

      added the new TRACEROUTE enum value to the response property for the response status

    • warning

      added the new TRACEROUTE enum value to the // response property for the response status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status