Checkly Check sessions API
The Check sessions API from Checkly — 7 operation(s) for check sessions.
The Check sessions API from Checkly — 7 operation(s) for check sessions.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/checkly-check-sessions-api"
curl "https://apis.io/api/v1/apis?limit=25"
Discovery needs no key. Ratings and market analysis are Pro.
openapi: 3.2.0
info:
title: Checkly Public Check sessions API
version: v1
description: These are the docs for the newly released Checkly Public API.<br />If you have any questions, please do not hesitate to get in touch with us.
servers:
- url: https://api.checklyhq.com
security:
- Bearer: []
tags:
- name: Check sessions
paths:
/v1/check-sessions/trigger:
post:
summary: Trigger a new check session
operationId: postV1ChecksessionsTrigger
description: '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.'
tags:
- Check sessions
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TriggerCheckSessionRequestPayload'
responses:
'201':
description: Returns a check session for each check matching target conditions.
content:
application/json:
schema:
$ref: '#/components/schemas/TriggerCheckSessionResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'402':
description: Payment Required
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentRequiredError'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
'404':
description: Returned when there are no matching checks.
content:
application/json:
schema:
$ref: '#/components/schemas/NoMatchingChecksFoundErrorResponse'
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/TooManyRequestsError'
deprecated: true
/v1/check-sessions/{checkSessionId}:
get:
summary: Retrieve a check session
operationId: getV1ChecksessionsChecksessionid
description: 'Retrieves a check session. Results may be incomplete if the check session is still in progress.
Once a check session has finished, results will include at least one check result for each run location: one result with `resultType` equal to `"FINAL"`, and zero or more results with `resultType` equal to `"ATTEMPT"` (one for each failed attempt, if any).
Each result contains just enough information to quickly determine whether the check run was successful or not. To dive even deeper into individual results, use the `GET /v1/check-results/{checkId}/{checkResultId}` endpoint to retrieve detailed data about a specific result.'
parameters:
- name: checkSessionId
in: path
schema:
type: string
description: The unique identifier of the check session.
x-format:
guid: true
description: The unique identifier of the check session.
required: true
tags:
- Check sessions
responses:
'200':
description: The current state of the check session.
content:
application/json:
schema:
$ref: '#/components/schemas/FindOneCheckSessionResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
'404':
description: No such check session exists.
content:
application/json:
schema:
$ref: '#/components/schemas/CheckSessionNotFoundErrorResponse'
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/TooManyRequestsError'
deprecated: true
/v1/check-sessions/{checkSessionId}/cancel:
post:
summary: Cancel a check session
operationId: postV1ChecksessionsChecksessionidCancel
description: 'Cancels in-progress Playwright Check Suite runs within the specified check session. Use the optional `sequenceId` field in the request body to cancel only specific parallel runs within the session; omit it to cancel everything still running.
Returns `204 No Content` once the cancellation requests have been dispatched. Returns `404 Not Found` if the check session does not exist.'
tags:
- Check sessions
responses:
'204':
description: Cancellation accepted.
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
parameters:
- schema:
type: string
format: uuid
description: Check session ID.
required: true
description: Check session ID.
name: checkSessionId
in: path
- schema:
type: string
format: uuid
description: Your Checkly account ID, you can find it at https://app.checklyhq.com/settings/account/general
required: false
description: Your Checkly account ID, you can find it at https://app.checklyhq.com/settings/account/general
name: x-checkly-account
in: header
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CheckSessionsV1CancelRequest'
/v1/check-sessions/{checkSessionId}/completion:
get:
summary: Await the completion of a check session
operationId: getV1ChecksessionsChecksessionidCompletion
description: '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.'
parameters:
- name: checkSessionId
in: path
schema:
type: string
description: The unique identifier of the check session.
x-format:
guid: true
description: The unique identifier of the check session.
required: true
- name: maxWaitSeconds
in: query
schema:
type: number
description: The maximum time to wait for completion, in seconds.
example: 30
minimum: 1
maximum: 30
description: The maximum time to wait for completion, in seconds.
tags:
- Check sessions
responses:
'200':
description: Returned when the check session has finished running.
content:
application/json:
schema:
$ref: '#/components/schemas/AwaitCheckSessionCompletionResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
'404':
description: No such check session exists.
content:
application/json:
schema:
$ref: '#/components/schemas/CheckSessionNotFoundErrorResponse'
'408':
description: 'The check session is still pending, but the server requests a quick break. You should call the endpoint again. Optionally, try to respect the `Retry-After` header.
This error code is one of the transient error codes supported by *curl*''s `--retry` option.'
content:
application/json:
schema:
$ref: '#/components/schemas/AwaitCheckSessionCompletionTryAgainResponse'
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/TooManyRequestsError'
deprecated: true
/v2/check-sessions/trigger:
post:
summary: Trigger a new check session
operationId: postV2ChecksessionsTrigger
description: '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 /v2/check-sessions/{checkSessionId}/completion` or `GET /v2/check-sessions/{checkSessionId}` endpoints to track progress.
Use `POST /v1/check-sessions/{checkSessionId}/cancel` to cancel an in-progress check session.
Standard alerting rules apply to finished check runs.
Equivalent to the _Schedule Now_ button in the UI.'
tags:
- Check sessions
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/CheckSessionsV2TriggerResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'402':
description: Payment Required
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
parameters:
- schema:
type: string
format: uuid
description: Your Checkly account ID, you can find it at https://app.checklyhq.com/settings/account/general
required: false
description: Your Checkly account ID, you can find it at https://app.checklyhq.com/settings/account/general
name: x-checkly-account
in: header
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CheckSessionsV2TriggerRequest'
/v2/check-sessions/{checkSessionId}:
get:
summary: Retrieve a check session
operationId: getV2ChecksessionsChecksessionid
description: 'Retrieves a check session. Results may be incomplete if the check session is still in progress.
Once a check session has finished, results will include at least one check result for each run location: one result with `resultType` equal to `"FINAL"`, and zero or more results with `resultType` equal to `"ATTEMPT"` (one for each failed attempt, if any).
Each result contains just enough information to quickly determine whether the check run was successful or not. To dive even deeper into individual results, use the `GET /v1/check-results/{checkId}/{checkResultId}` endpoint to retrieve detailed data about a specific result.
The `status` field may return `CANCELLED` for sessions cancelled via `POST /v1/check-sessions/{checkSessionId}/cancel`, and each per-result object includes an `isCancelled` boolean.'
tags:
- Check sessions
responses:
'200':
description: Successful
content:
application/json:
schema:
$ref: '#/components/schemas/CheckSessionsV2FindOneResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
parameters:
- schema:
type: string
format: uuid
description: Check session ID.
required: true
description: Check session ID.
name: checkSessionId
in: path
- schema:
type: string
format: uuid
description: Your Checkly account ID, you can find it at https://app.checklyhq.com/settings/account/general
required: false
description: Your Checkly account ID, you can find it at https://app.checklyhq.com/settings/account/general
name: x-checkly-account
in: header
/v2/check-sessions/{checkSessionId}/completion:
get:
summary: Await the completion of a check session
operationId: getV2ChecksessionsChecksessionidCompletion
description: '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, fails, degrades, or is cancelled).
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 /v2/check-sessions/{checkSessionId}` endpoint''s response for a completed check session.
The `status` field may return `CANCELLED` for sessions cancelled via `POST /v1/check-sessions/{checkSessionId}/cancel`, and each per-result object includes an `isCancelled` boolean.'
tags:
- Check sessions
responses:
'200':
description: Successful
content:
application/json:
schema:
$ref: '#/components/schemas/CheckSessionsV2CompletionResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'408':
description: Request Timeout
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'429':
description: Too Many Requests
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
parameters:
- schema:
type: string
format: uuid
description: Check session ID.
required: true
description: Check session ID.
name: checkSessionId
in: path
- schema:
type: integer
minimum: 1
maximum: 30
description: Maximum time to wait for completion before returning a retryable timeout response.
required: false
description: Maximum time to wait for completion before returning a retryable timeout response.
name: maxWaitSeconds
in: query
- schema:
type: string
format: uuid
description: Your Checkly account ID, you can find it at https://app.checklyhq.com/settings/account/general
required: false
description: Your Checkly account ID, you can find it at https://app.checklyhq.com/settings/account/general
name: x-checkly-account
in: header
components:
schemas:
attributes:
type: object
TriggerCheckSessionResponse:
type: object
description: Returns a check session for each check matching target conditions.
properties:
sessions:
$ref: '#/components/schemas/sessions'
required:
- sessions
Model30:
type: string
description: The final status of the check session.
example: PASSED
enum:
- FAILED
- PASSED
- DEGRADED
- TIMED_OUT
- CANCELLED
TriggerCheckSessionRequestPayload:
type: object
properties:
target:
$ref: '#/components/schemas/TriggerCheckSessionTarget'
refreshCache:
type: boolean
description: If true, the runner will skip existing caches and install dependencies from scratch. This applies only to Playwright Check Suites.
default: false
CheckSessionsV2FindOneResponse:
type: object
properties:
checkSessionId:
type: string
format: uuid
checkSessionLink:
type: string
format: uri
checkId:
type: string
format: uuid
checkType:
type: string
enum:
- AGENTIC
- API
- BROWSER
- HEARTBEAT
- ICMP
- MULTI_STEP
- TCP
- PLAYWRIGHT
- URL
- DNS
- SSL
- GRPC
- TRACEROUTE
name:
type: string
status:
type: string
enum:
- STARTED
- PROGRESS
- FAILED
- PASSED
- DEGRADED
- PROGRESS_FAILED
- PROGRESS_DEGRADED
- TIMED_OUT
- CANCELLED
startedAt:
type: string
format: date-time
stoppedAt:
type:
- string
- 'null'
format: date-time
timeElapsed:
type: number
runLocations:
type: array
items:
type: string
runSource:
type:
- string
- 'null'
enum:
- CLI_DEPLOY
- DEPLOYMENT
- DEPLOYMENT_CACHE_WARMER
- EDITOR
- GROUP_RUN_ALL
- LEGACY_TRIGGER
- SCHEDULER
- SCHEDULE_NOW
- TEST_NO_RECORD
- TEST_RECORD
- TRIGGER_NO_RECORD
- TRIGGER_RECORD
- TRIGGER_API
- null
results:
type: array
items:
$ref: '#/components/schemas/CheckSessionsV2CheckResult'
required:
- checkSessionId
- checkSessionLink
- checkId
- checkType
- status
- startedAt
- stoppedAt
- timeElapsed
- runLocations
- runSource
- results
checkId:
type: array
description: Match checks with the given identifiers.
example:
- a4cd4ad9-4815-4a9e-92d2-0a7c562ee69a
x-constraint:
single: true
items:
type: string
x-format:
guid: true
Model23:
type: array
x-constraint:
single: true
items:
type: string
Model2:
type: string
enum:
- Too Many Requests
UnauthorizedError:
type: object
properties:
statusCode:
type: number
enum:
- 401
error:
$ref: '#/components/schemas/error'
message:
type: string
example: Bad Token
attributes:
$ref: '#/components/schemas/attributes'
required:
- statusCode
- error
TooManyRequestsError:
type: object
properties:
statusCode:
type: number
enum:
- 429
error:
$ref: '#/components/schemas/Model2'
message:
type: string
example: Too Many Requests
attributes:
$ref: '#/components/schemas/attributes'
required:
- statusCode
- error
Model24:
type: string
example: API
enum:
- AGENTIC
- API
- BROWSER
- ICMP
- MULTI_STEP
- TCP
- PLAYWRIGHT
- TRACEROUTE
- URL
- DNS
- SSL
- GRPC
CheckSessionsV1CancelRequest:
type: object
properties:
sequenceId:
type: array
items:
type: string
format: uuid
minItems: 1
description: Subset of sequence IDs to cancel. Omit to cancel all in-progress sequences.
additionalProperties: false
CheckSessionsV2CheckSession:
type: object
properties:
checkSessionId:
type: string
format: uuid
checkSessionLink:
type: string
format: uri
checkId:
type: string
format: uuid
checkType:
type: string
enum:
- AGENTIC
- API
- BROWSER
- HEARTBEAT
- ICMP
- MULTI_STEP
- TCP
- PLAYWRIGHT
- URL
- DNS
- SSL
- GRPC
- TRACEROUTE
name:
type: string
status:
type: string
enum:
- STARTED
- PROGRESS
- FAILED
- PASSED
- DEGRADED
- PROGRESS_FAILED
- PROGRESS_DEGRADED
- TIMED_OUT
- CANCELLED
startedAt:
type: string
format: date-time
stoppedAt:
type:
- string
- 'null'
format: date-time
timeElapsed:
type: number
runLocations:
type: array
items:
type: string
runSource:
type:
- string
- 'null'
enum:
- CLI_DEPLOY
- DEPLOYMENT
- DEPLOYMENT_CACHE_WARMER
- EDITOR
- GROUP_RUN_ALL
- LEGACY_TRIGGER
- SCHEDULER
- SCHEDULE_NOW
- TEST_NO_RECORD
- TEST_RECORD
- TRIGGER_NO_RECORD
- TRIGGER_RECORD
- TRIGGER_API
- null
required:
- checkSessionId
- checkSessionLink
- checkId
- checkType
- status
- startedAt
- stoppedAt
- timeElapsed
- runLocations
- runSource
PaymentRequiredError:
type: object
properties:
statusCode:
type: number
enum:
- 402
error:
$ref: '#/components/schemas/Model3'
message:
type: string
example: Payment Required
attributes:
$ref: '#/components/schemas/attributes'
required:
- statusCode
- error
results:
type: array
description: The results of the check session. Only partial results are available until the check session has completed.
items:
$ref: '#/components/schemas/CheckSessionConciseCheckResult'
CheckSessionNotFoundErrorResponse:
type: object
description: No such check session exists.
properties:
statusCode:
type: number
enum:
- 404
error:
type: string
example: Not Found
message:
type: string
example: No such check session.
required:
- statusCode
resultType:
type:
- string
- 'null'
description: The type of the result.
example: FINAL
enum:
- FINAL
- ATTEMPT
- ALL
Model27:
type: string
description: The status of the check session.
example: PASSED
enum:
- STARTED
- PROGRESS
- FAILED
- PASSED
- DEGRADED
- PROGRESS_FAILED
- PROGRESS_DEGRADED
- TIMED_OUT
- CANCELLED
FindOneCheckSessionResponse:
type: object
description: The current state of the check session.
properties:
checkSessionId:
type: string
description: The unique identifier of the check session.
example: 8166fa86-c9b4-4162-8541-d380c6c212d8
x-format:
guid: true
checkSessionLink:
type: string
description: 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
x-format:
uri: true
checkId:
type: string
description: The ID of the check.
example: a4cd4ad9-4815-4a9e-92d2-0a7c562ee69a
x-format:
guid: true
checkType:
$ref: '#/components/schemas/Model26'
name:
type: string
example: Example API Check
status:
$ref: '#/components/schemas/Model27'
startedAt:
type: string
format: date-time
description: The date and time when the session started.
example: '2025-08-28T18:23:40.262Z'
stoppedAt:
type:
- string
- 'null'
format: date-time
description: The date and time when the session stopped.
example: '2025-08-28T18:28:40.993Z'
timeElapsed:
type: number
description: The time the check session took, in milliseconds.
example: 300731
runLocations:
$ref: '#/components/schemas/runLocations'
runSource:
$ref: '#/components/schemas/runSource'
results:
$ref: '#/components/schemas/results'
required:
- checkSessionId
- checkSessionLink
- checkId
- checkType
- status
- startedAt
- timeElapsed
- runLocations
Model25:
type: string
description: The status of the check session.
example: PASSED
enum:
- STARTED
- PROGRESS
- FAILED
- PASSED
- DEGRADED
- PROGRESS_FAILED
- PROGRESS_DEGRADED
- TIMED_OUT
- CANCELLED
runLocations:
type: array
description: The run locations of the check session.
example:
- us-east-1
- eu-central-1
items:
type: string
NoMatchingChecksFoundErrorResponse:
type: object
description: Returned when there are no matching checks.
properties:
statusCode:
type: number
enum:
- 404
error:
type: string
example: Not Found
message:
type: string
example: No matching checks were found.
required:
- statusCode
CheckSessionsV2CompletionResponse:
type: object
properties:
checkSessionId:
type: string
format: uuid
checkSessionLink:
type: string
format: uri
checkId:
type: string
format: uuid
checkType:
type: string
enum:
- AGENTIC
- API
- BROWSER
- HEARTBEAT
- ICMP
- MULTI_STEP
- TCP
- PLAYWRIGHT
- URL
- DNS
- SSL
- GRPC
- TRACEROUTE
name:
type: string
status:
type: string
enum:
- PASSED
- FAILED
- DEGRADED
- TIMED_OUT
- CANCELLED
startedAt:
type: string
format: date-time
stoppedAt:
type: string
format: date-time
timeElapsed:
type: number
runLocations:
type: array
items:
type: string
runSource:
type:
- string
- 'null'
enum:
- CLI_DEPLOY
- DEPLOYMENT
- DEPLOYMENT_CACHE_WARMER
- EDITOR
- GROUP_RUN_ALL
- LEGACY_TRIGGER
- SCHEDULER
- SCHEDULE_NOW
- TEST_NO_RECORD
- TEST_RECORD
- TRIGGER_NO_RECORD
- TRIGGER_RECORD
- TRIGGER_API
- null
results:
type: array
items:
$ref: '#/components/schemas/CheckSessionsV2CheckResult'
required:
- checkSessionId
- checkSessionLink
- checkId
- checkType
- status
- startedAt
- stoppedAt
- timeElapsed
- runLocations
- runSource
- results
sessions:
type: array
description: A list of check sessions, with one check session for each check.
items:
$ref: '#/components/schemas/CheckSession'
Model31:
type: array
description: The results of the check session.
items:
$ref: '#/components/schemas/CheckSessionConciseCheckResult'
Model26:
type: string
example: API
enum:
- AGENTIC
- API
- BROWSER
- ICMP
- MULTI_STEP
- TCP
- PLAYWRIGHT
- TRACEROUTE
- URL
- DNS
- SSL
- GRPC
runSource:
type:
- string
- 'null'
description: The source that triggered the check session.
example: TRIGGER_API
enum:
- 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
CheckSessionsV2CheckResult:
type: object
properties:
checkResultId:
type: string
format: uuid
checkResultLink:
type: string
format: uri
checkId:
type: string
format: uuid
checkType:
type: string
enum:
- AGENTIC
- API
- BROWSER
- HEARTBEAT
- ICMP
- MULTI_STEP
- TCP
- PLAYWRIGHT
- URL
- DNS
-
# --- truncated at 32 KB (44 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/checkly/refs/heads/main/openapi/checkly-check-sessions-api-openapi.yml