From db943245755206efb27d7120c11144742b333cce Mon Sep 17 00:00:00 2001 From: miliberlin Date: Wed, 13 May 2026 16:19:45 +0200 Subject: [PATCH 1/5] docs: document PWCS cancellation feature [RED-511] - New concepts/cancellation.mdx covering cancellation surfaces, post-cancel flow, and API versioning - New api-reference/cancel/cancel-a-session.mdx for POST /v1/cancel - New v2 check-session reference pages (trigger, retrieve, await completion) - Sidebar entries in docs.json for the above - Cross-links from concepts/results.mdx, communicate/alerts/configuration.mdx - Ctrl+C cancellation sections in cli/checkly-{pw-test,test,trigger,deploy}.mdx Co-Authored-By: Claude Opus 4.7 (1M context) --- api-reference/cancel/cancel-a-session.mdx | 5 + ...t-the-completion-of-a-check-session-v2.mdx | 3 + .../retrieve-a-check-session-v2.mdx | 3 + .../trigger-a-new-check-session-v2.mdx | 3 + cli/checkly-deploy.mdx | 9 ++ cli/checkly-pw-test.mdx | 9 ++ cli/checkly-test.mdx | 9 ++ cli/checkly-trigger.mdx | 9 ++ communicate/alerts/configuration.mdx | 6 +- concepts/cancellation.mdx | 99 +++++++++++++++++++ concepts/results.mdx | 4 + docs.json | 12 ++- 12 files changed, 169 insertions(+), 2 deletions(-) create mode 100644 api-reference/cancel/cancel-a-session.mdx create mode 100644 api-reference/check-sessions/await-the-completion-of-a-check-session-v2.mdx create mode 100644 api-reference/check-sessions/retrieve-a-check-session-v2.mdx create mode 100644 api-reference/check-sessions/trigger-a-new-check-session-v2.mdx create mode 100644 concepts/cancellation.mdx diff --git a/api-reference/cancel/cancel-a-session.mdx b/api-reference/cancel/cancel-a-session.mdx new file mode 100644 index 00000000..4a28cd12 --- /dev/null +++ b/api-reference/cancel/cancel-a-session.mdx @@ -0,0 +1,5 @@ +--- +openapi: post /v1/cancel +title: Cancel a check or test session +sidebarTitle: Cancel a session +--- diff --git a/api-reference/check-sessions/await-the-completion-of-a-check-session-v2.mdx b/api-reference/check-sessions/await-the-completion-of-a-check-session-v2.mdx new file mode 100644 index 00000000..d24029a8 --- /dev/null +++ b/api-reference/check-sessions/await-the-completion-of-a-check-session-v2.mdx @@ -0,0 +1,3 @@ +--- +openapi: get /v2/check-sessions/{checkSessionId}/completion +--- diff --git a/api-reference/check-sessions/retrieve-a-check-session-v2.mdx b/api-reference/check-sessions/retrieve-a-check-session-v2.mdx new file mode 100644 index 00000000..10ee5c0d --- /dev/null +++ b/api-reference/check-sessions/retrieve-a-check-session-v2.mdx @@ -0,0 +1,3 @@ +--- +openapi: get /v2/check-sessions/{checkSessionId} +--- diff --git a/api-reference/check-sessions/trigger-a-new-check-session-v2.mdx b/api-reference/check-sessions/trigger-a-new-check-session-v2.mdx new file mode 100644 index 00000000..72deac5a --- /dev/null +++ b/api-reference/check-sessions/trigger-a-new-check-session-v2.mdx @@ -0,0 +1,3 @@ +--- +openapi: post /v2/check-sessions/trigger +--- diff --git a/cli/checkly-deploy.mdx b/cli/checkly-deploy.mdx index 1ad5c0cf..f8b30777 100644 --- a/cli/checkly-deploy.mdx +++ b/cli/checkly-deploy.mdx @@ -178,6 +178,15 @@ The Checkly CLI evaluates Git information from your local or CI environment on a +## Cancelling a deploy + +{/* TODO: confirm CLI version that ships deploy Ctrl+C handling and fill in the Note below. */} +Available in CLI vX.X+. + +`checkly deploy` may run [Playwright Check Suites](/detect/synthetic-monitoring/playwright-checks/overview) as part of post-deploy verification. Pressing Ctrl+C during that phase prompts you to either **cancel** the recorded check session or **detach** and let it finish in the background. Detach is the default. + +See [Cancellation](/concepts/cancellation) for the full flow. + ## Related Commands - [`checkly login`](/cli/checkly-login) - Log in to your Checkly account diff --git a/cli/checkly-pw-test.mdx b/cli/checkly-pw-test.mdx index 53c97251..80e4f723 100644 --- a/cli/checkly-pw-test.mdx +++ b/cli/checkly-pw-test.mdx @@ -432,6 +432,15 @@ npx checkly pw-test -- test.spec.ts - Test sessions are recorded by default with full logs, traces, and videos - View all artifacts in Checkly's UI +## Cancelling a run + +{/* TODO: confirm CLI version that ships pw-test Ctrl+C handling and fill in the Note below. */} +Available in CLI vX.X+. + +Press Ctrl+C during a `checkly pw-test` run to cancel the test session. The CLI sends a cancel request and waits for the runner to stop. Pressing Ctrl+C a second time exits the CLI without waiting. + +See [Cancellation](/concepts/cancellation) for the full flow. + ## Related Commands - [`checkly test`](/cli/checkly-test) - Test your setup before deployment diff --git a/cli/checkly-test.mdx b/cli/checkly-test.mdx index 6c14729a..b6b9640f 100644 --- a/cli/checkly-test.mdx +++ b/cli/checkly-test.mdx @@ -380,6 +380,15 @@ Specify [environment variables](/cli/environment-variables) to dry run checks wi npx checkly test --env ENVIRONMENT_URL="https://preview.acme.com" --env PASSWORD=doremiabc123 ``` +## Cancelling a run + +{/* TODO: confirm CLI version that ships test Ctrl+C handling and fill in the Note below. */} +Available in CLI vX.X+. + +When you started the run with `--record`, pressing Ctrl+C prompts you to either **cancel** the recorded test session in Checkly or **detach** and let it finish in the background. Detach is the default. Cancellation only applies to Playwright Check Suite runs inside the session. + +See [Cancellation](/concepts/cancellation) for the full flow. + ## Related Commands - [`checkly pw-test`](/cli/checkly-pw-test) - Run Playwright tests in the Checkly cloud diff --git a/cli/checkly-trigger.mdx b/cli/checkly-trigger.mdx index 9b0e4fd0..20ef811b 100644 --- a/cli/checkly-trigger.mdx +++ b/cli/checkly-trigger.mdx @@ -372,6 +372,15 @@ npx checkly trigger --tags staging --record --test-session-name "Pre-prod valida If your production deployment includes monitoring changes and updates, [use `npx checkly test`](/cli/checkly-test) to validate your preview environment with the updated monitoring configuration. +## Cancelling a run + +{/* TODO: confirm CLI version that ships trigger Ctrl+C handling and fill in the Note below. */} +Available in CLI vX.X+. + +When you started the run with `--record`, pressing Ctrl+C prompts you to either **cancel** the recorded test session in Checkly or **detach** and let it finish in the background. Detach is the default. Cancellation only applies to Playwright Check Suite runs inside the session. + +See [Cancellation](/concepts/cancellation) for the full flow. + ## Related Commands - [`checkly deploy`](/cli/checkly-deploy) - Deploy your Checkly configuration diff --git a/communicate/alerts/configuration.mdx b/communicate/alerts/configuration.mdx index d80d81c8..09cba830 100644 --- a/communicate/alerts/configuration.mdx +++ b/communicate/alerts/configuration.mdx @@ -44,6 +44,10 @@ Understanding how settings cascade through the hierarchy: + +Runs you [cancel](/concepts/cancellation) never trigger alerts. No failure, degraded, or recovery notification is sent for a cancelled run, regardless of the settings above. + + ## Alert Configuration ### Account-Level @@ -70,7 +74,7 @@ Configure alerts for teams and service categories: ![Group-level alert settings](/images/docs/images/alerting/alert-settings-group.png) -#### Group Override +### Group Override Configure how group settings interact with individual checks: **If checked, Group settings override individual check settings** diff --git a/concepts/cancellation.mdx b/concepts/cancellation.mdx new file mode 100644 index 00000000..340416a8 --- /dev/null +++ b/concepts/cancellation.mdx @@ -0,0 +1,99 @@ +--- +title: 'Cancellation' +description: 'Stop in-flight Playwright Check Suite runs from the UI, API, or CLI. Other check types cannot be cancelled.' +sidebarTitle: 'Cancellation' +--- + +Cancellation lets you stop an in-progress [Playwright Check Suite](/detect/synthetic-monitoring/playwright-checks/overview) run. Cancelled results are flagged with `isCancelled: true`, do not trigger alerts, and are excluded from availability and performance metrics. A session that contains at least one cancelled run ends in a terminal `CANCELLED` status. + +## What you can cancel + +You can cancel two kinds of sessions, and the behaviour differs: + +**Check sessions** — created by the UI "Schedule now" button and `checkly deploy`. A check session is one execution of a single Playwright Check Suite, fanned out across the locations you configured. Cancelling the session stops every in-progress run; cancelling a single run leaves the rest of the session going. + +**Test sessions** — created by `checkly test`, `checkly trigger`, and `checkly pw-test`. A test session can contain multiple checks of different types. Cancelling the test session stops only the Playwright Check Suite runs inside it; any URL, API, Browser, Multistep, Heartbeat, TCP, DNS, or ICMP runs in the same session continue until they finish normally. You can also cancel a single Playwright run within the session. + + +**Only Playwright Check Suite runs are cancellable.** Other check types cannot be cancelled, even when they appear inside a test session alongside Playwright runs. Scheduled runs are also excluded; cancellation is for user-initiated runs only. + + +## How to cancel + + + +On a check session or test session page, click **Cancel session** in the header to stop the whole session. To stop just a single run, use the cancel button on its row. + + + +Send a `POST` request to [`/v1/cancel`](/api-reference/cancel/cancel-a-session) with either a `checkSessionId` or a `testSessionId`. Pass an optional `sequenceId` (or array) to cancel only specific runs within the session. + +```bash Cancel a whole check session +curl -X POST https://api.checklyhq.com/v1/cancel \ + -H "Authorization: Bearer $CHECKLY_API_KEY" \ + -H "X-Checkly-Account: $CHECKLY_ACCOUNT_ID" \ + -H "Content-Type: application/json" \ + -d '{"checkSessionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"}' +``` + +```bash Cancel specific runs in a test session +curl -X POST https://api.checklyhq.com/v1/cancel \ + -H "Authorization: Bearer $CHECKLY_API_KEY" \ + -H "X-Checkly-Account: $CHECKLY_ACCOUNT_ID" \ + -H "Content-Type: application/json" \ + -d '{"testSessionId": "a1b2c3d4-...", "sequenceId": ["b2c3d4e5-..."]}' +``` + + + +Press Ctrl+C during `checkly pw-test`, `checkly test`, `checkly trigger`, or `checkly deploy`. The CLI prompts you to either cancel the running session or detach (let it finish in the background). + +See the [CLI reference](/cli/overview) for command-specific behavior. + + + +## What happens after a run is cancelled + + + +The runner receives the cancellation signal, aborts the in-flight Playwright run, and reports the result back to Checkly. + + + +Each cancelled run's result has `isCancelled: true`. Once the session has stopped (any remaining non-Playwright checks finish normally), the session's status becomes `CANCELLED` because at least one of its runs was cancelled. + + + +Cancelled runs never produce failure or recovery alerts, regardless of your alert settings. See [Alert configuration](/communicate/alerts/configuration). + + + +Availability, response time percentiles, and success ratios exclude cancelled runs. Your check status does not change. Public and private dashboards omit cancelled runs from their summary counts. + + + +Because no alert is sent and the check status does not change, [automated incidents](/communicate/incidents/overview) are not opened from a cancelled run. + + + +## API versioning + +Cancellation introduces two API additions: a new `CANCELLED` value on the check-session status enum, and a new `isCancelled` boolean on individual check results. The status enum change is breaking for clients that switch on status values exhaustively, so it's only exposed through the v2 check-session endpoints; v1 clients continue to work unchanged. The `isCancelled` flag is additive and ships on the existing check-result endpoints without a version bump. + + +[`POST /v1/check-sessions/trigger`](/api-reference/check-sessions/trigger-a-new-check-session), [`GET /v1/check-sessions/{checkSessionId}`](/api-reference/check-sessions/retrieve-a-check-session), and [`GET /v1/check-sessions/{checkSessionId}/completion`](/api-reference/check-sessions/await-the-completion-of-a-check-session) never return `CANCELLED` in `status` and do not include `isCancelled` on per-result objects. + + + +[`POST /v2/check-sessions/trigger`](/api-reference/check-sessions/trigger-a-new-check-session-v2), [`GET /v2/check-sessions/{checkSessionId}`](/api-reference/check-sessions/retrieve-a-check-session-v2), and [`GET /v2/check-sessions/{checkSessionId}/completion`](/api-reference/check-sessions/await-the-completion-of-a-check-session-v2) return `CANCELLED` in `status` and include `isCancelled` on each per-result object. + + + +[`GET /v1/check-results/{checkId}/{checkResultId}`](/api-reference/check-results/retrieve-a-check-result) and the list endpoints include `isCancelled` on every result. + + + +[`POST /v1/cancel`](/api-reference/cancel/cancel-a-session) is the action endpoint itself. It accepts either a `checkSessionId` or a `testSessionId` in the body, so a single endpoint covers both. + + +If you build automation against check sessions and want to handle cancelled runs explicitly, switch to the v2 endpoints. diff --git a/concepts/results.mdx b/concepts/results.mdx index 8e07ea57..e868bacc 100644 --- a/concepts/results.mdx +++ b/concepts/results.mdx @@ -10,6 +10,10 @@ Each time a Check executes—whether it's testing an API endpoint, clicking thro **Results** are more than just pass or fail indicators. They're comprehensive records that include performance metrics, error details, screenshots, network traces, and any other telemetry that helps you understand not just whether something worked, but how well it worked and why it might have failed. + +Playwright Check Suite runs can also be [cancelled](/concepts/cancellation) while they are in progress. Cancelled results are excluded from availability and performance metrics. + + ## Understanding Result Data You can select any check on the main Checkly dashboard to get an overview of the results they have produced so far. diff --git a/docs.json b/docs.json index 8d54a130..f9a8994e 100644 --- a/docs.json +++ b/docs.json @@ -68,6 +68,7 @@ "concepts/locations", "concepts/scheduling", "concepts/results", + "concepts/cancellation", "concepts/metrics" ] }, @@ -726,8 +727,17 @@ "group": "Check Sessions", "pages": [ "api-reference/check-sessions/trigger-a-new-check-session", + "api-reference/check-sessions/trigger-a-new-check-session-v2", "api-reference/check-sessions/retrieve-a-check-session", - "api-reference/check-sessions/await-the-completion-of-a-check-session" + "api-reference/check-sessions/retrieve-a-check-session-v2", + "api-reference/check-sessions/await-the-completion-of-a-check-session", + "api-reference/check-sessions/await-the-completion-of-a-check-session-v2" + ] + }, + { + "group": "Cancel", + "pages": [ + "api-reference/cancel/cancel-a-session" ] }, { From 82da71986f82b2d4576caa67037d38dd8f9f3920 Mon Sep 17 00:00:00 2001 From: miliberlin Date: Wed, 13 May 2026 16:31:25 +0200 Subject: [PATCH 2/5] docs: mark v1 check-session endpoints as deprecated Match the convention used by check-groups and check-results: v1 MDX pages get deprecated: true when a v2 equivalent exists. Updates the matching ResponseField label in concepts/cancellation.mdx from backwards-compatible to deprecated for consistency. Co-Authored-By: Claude Opus 4.7 (1M context) --- .../check-sessions/await-the-completion-of-a-check-session.mdx | 3 ++- api-reference/check-sessions/retrieve-a-check-session.mdx | 3 ++- api-reference/check-sessions/trigger-a-new-check-session.mdx | 3 ++- concepts/cancellation.mdx | 2 +- 4 files changed, 7 insertions(+), 4 deletions(-) diff --git a/api-reference/check-sessions/await-the-completion-of-a-check-session.mdx b/api-reference/check-sessions/await-the-completion-of-a-check-session.mdx index 6e93205c..3c14b799 100644 --- a/api-reference/check-sessions/await-the-completion-of-a-check-session.mdx +++ b/api-reference/check-sessions/await-the-completion-of-a-check-session.mdx @@ -1,3 +1,4 @@ --- openapi: get /v1/check-sessions/{checkSessionId}/completion ---- \ No newline at end of file +deprecated: true +--- diff --git a/api-reference/check-sessions/retrieve-a-check-session.mdx b/api-reference/check-sessions/retrieve-a-check-session.mdx index 9b732e76..7df50494 100644 --- a/api-reference/check-sessions/retrieve-a-check-session.mdx +++ b/api-reference/check-sessions/retrieve-a-check-session.mdx @@ -1,3 +1,4 @@ --- openapi: get /v1/check-sessions/{checkSessionId} ---- \ No newline at end of file +deprecated: true +--- diff --git a/api-reference/check-sessions/trigger-a-new-check-session.mdx b/api-reference/check-sessions/trigger-a-new-check-session.mdx index c5dcbf9b..8c304e6a 100644 --- a/api-reference/check-sessions/trigger-a-new-check-session.mdx +++ b/api-reference/check-sessions/trigger-a-new-check-session.mdx @@ -1,3 +1,4 @@ --- openapi: post /v1/check-sessions/trigger ---- \ No newline at end of file +deprecated: true +--- diff --git a/concepts/cancellation.mdx b/concepts/cancellation.mdx index 340416a8..21f41114 100644 --- a/concepts/cancellation.mdx +++ b/concepts/cancellation.mdx @@ -80,7 +80,7 @@ Because no alert is sent and the check status does not change, [automated incide Cancellation introduces two API additions: a new `CANCELLED` value on the check-session status enum, and a new `isCancelled` boolean on individual check results. The status enum change is breaking for clients that switch on status values exhaustively, so it's only exposed through the v2 check-session endpoints; v1 clients continue to work unchanged. The `isCancelled` flag is additive and ships on the existing check-result endpoints without a version bump. - + [`POST /v1/check-sessions/trigger`](/api-reference/check-sessions/trigger-a-new-check-session), [`GET /v1/check-sessions/{checkSessionId}`](/api-reference/check-sessions/retrieve-a-check-session), and [`GET /v1/check-sessions/{checkSessionId}/completion`](/api-reference/check-sessions/await-the-completion-of-a-check-session) never return `CANCELLED` in `status` and do not include `isCancelled` on per-result objects. From 82c0fb69c08184baf3c04a712eb3d6c24e43a469 Mon Sep 17 00:00:00 2001 From: miliberlin Date: Wed, 13 May 2026 16:38:05 +0200 Subject: [PATCH 3/5] docs: add descriptions to v2 check-session reference pages The v2 OpenAPI entries have no description fields, so the auto-rendered pages were blank. Carry the v1 description text forward in the MDX body and add a What's new in v2 note covering the CANCELLED status value and isCancelled result flag. Co-Authored-By: Claude Opus 4.7 (1M context) --- .../await-the-completion-of-a-check-session-v2.mdx | 10 ++++++++++ .../check-sessions/retrieve-a-check-session-v2.mdx | 10 ++++++++++ .../trigger-a-new-check-session-v2.mdx | 12 ++++++++++++ 3 files changed, 32 insertions(+) diff --git a/api-reference/check-sessions/await-the-completion-of-a-check-session-v2.mdx b/api-reference/check-sessions/await-the-completion-of-a-check-session-v2.mdx index d24029a8..5b2f4e6a 100644 --- a/api-reference/check-sessions/await-the-completion-of-a-check-session-v2.mdx +++ b/api-reference/check-sessions/await-the-completion-of-a-check-session-v2.mdx @@ -1,3 +1,13 @@ --- openapi: get /v2/check-sessions/{checkSessionId}/completion --- + +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, 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 [retrieve a check session](/api-reference/check-sessions/retrieve-a-check-session-v2) endpoint's response for a completed check session. + + +**What's new in v2:** `status` may return the new `CANCELLED` value for sessions that were [cancelled](/concepts/cancellation), and every per-result object includes an `isCancelled` boolean. v1 clients continue to work unchanged and never see these additions. + diff --git a/api-reference/check-sessions/retrieve-a-check-session-v2.mdx b/api-reference/check-sessions/retrieve-a-check-session-v2.mdx index 10ee5c0d..092e7c6d 100644 --- a/api-reference/check-sessions/retrieve-a-check-session-v2.mdx +++ b/api-reference/check-sessions/retrieve-a-check-session-v2.mdx @@ -1,3 +1,13 @@ --- openapi: get /v2/check-sessions/{checkSessionId} --- + +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 [retrieve a check result](/api-reference/check-results/retrieve-a-check-result) endpoint. + + +**What's new in v2:** `status` may return the new `CANCELLED` value for sessions that were [cancelled](/concepts/cancellation), and every per-result object includes an `isCancelled` boolean. v1 clients continue to work unchanged and never see these additions. + diff --git a/api-reference/check-sessions/trigger-a-new-check-session-v2.mdx b/api-reference/check-sessions/trigger-a-new-check-session-v2.mdx index 72deac5a..7e9da64f 100644 --- a/api-reference/check-sessions/trigger-a-new-check-session-v2.mdx +++ b/api-reference/check-sessions/trigger-a-new-check-session-v2.mdx @@ -1,3 +1,15 @@ --- openapi: post /v2/check-sessions/trigger --- + +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 [await completion](/api-reference/check-sessions/await-the-completion-of-a-check-session-v2) or [retrieve check session](/api-reference/check-sessions/retrieve-a-check-session-v2) endpoints to track progress if needed. + +Standard alerting rules apply to finished check runs. + +Equivalent to the _Schedule Now_ button in the UI. + + +**What's new in v2:** `status` may return the new `CANCELLED` value for sessions that were [cancelled](/concepts/cancellation), and every per-result object includes an `isCancelled` boolean. v1 clients continue to work unchanged and never see these additions. + From ffa704684c3653a6fb861e8c0cdee2c645a1fcbd Mon Sep 17 00:00:00 2001 From: miliberlin Date: Wed, 13 May 2026 16:40:11 +0200 Subject: [PATCH 4/5] docs: add description to the cancel endpoint reference page The /v1/cancel OpenAPI entry has no description, so the auto-rendered page only showed the request schema. Add MDX body content explaining the discriminated body (checkSessionId vs testSessionId), the optional sequenceId narrowing, and the Playwright-only constraint, with a link out to the cancellation concept page. Co-Authored-By: Claude Opus 4.7 (1M context) --- api-reference/cancel/cancel-a-session.mdx | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/api-reference/cancel/cancel-a-session.mdx b/api-reference/cancel/cancel-a-session.mdx index 4a28cd12..5ee7e40e 100644 --- a/api-reference/cancel/cancel-a-session.mdx +++ b/api-reference/cancel/cancel-a-session.mdx @@ -3,3 +3,12 @@ openapi: post /v1/cancel title: Cancel a check or test session sidebarTitle: Cancel a session --- + +Stops an in-progress check session or test session by ID. The request body discriminates by which ID you pass: + +- Pass a `checkSessionId` to cancel a [check session](/api-reference/check-sessions/retrieve-a-check-session-v2) (UI "Schedule now" or `checkly deploy`). +- Pass a `testSessionId` to cancel a [test session](/detect/testing/overview) (`checkly test`, `checkly trigger`, or `checkly pw-test`). + +Optionally pass `sequenceId` (a single UUID or an array) to cancel only specific runs within the session. Omit it to cancel every in-progress run. + +Only Playwright Check Suite runs are cancellable. If a test session also contains URL, API, Browser, Multistep, Heartbeat, TCP, DNS, or ICMP runs, those continue executing until they finish normally. See [Cancellation](/concepts/cancellation) for the full flow, the effect on alerts and metrics, and how the `CANCELLED` status and `isCancelled` flag surface in responses. From 3574b3d2463444169628b0458bb9dc2b8f45a1e6 Mon Sep 17 00:00:00 2001 From: miliberlin Date: Fri, 15 May 2026 15:02:50 +0200 Subject: [PATCH 5/5] docs: clarify v1 vs v2 check-session cancellation behavior The only v2-only addition is the CANCELLED status enum value; v1 maps cancelled sessions to TIMED_OUT. The isCancelled boolean on per-result objects is additive and present in both versions. Co-Authored-By: Claude Opus 4.7 (1M context) --- .../await-the-completion-of-a-check-session-v2.mdx | 2 +- .../check-sessions/retrieve-a-check-session-v2.mdx | 2 +- .../check-sessions/trigger-a-new-check-session-v2.mdx | 2 +- concepts/cancellation.mdx | 8 ++++---- 4 files changed, 7 insertions(+), 7 deletions(-) diff --git a/api-reference/check-sessions/await-the-completion-of-a-check-session-v2.mdx b/api-reference/check-sessions/await-the-completion-of-a-check-session-v2.mdx index 5b2f4e6a..cd6b113e 100644 --- a/api-reference/check-sessions/await-the-completion-of-a-check-session-v2.mdx +++ b/api-reference/check-sessions/await-the-completion-of-a-check-session-v2.mdx @@ -9,5 +9,5 @@ If the check session takes a long time to complete, the endpoint will return a t The successful response of this endpoint is equivalent to the [retrieve a check session](/api-reference/check-sessions/retrieve-a-check-session-v2) endpoint's response for a completed check session. -**What's new in v2:** `status` may return the new `CANCELLED` value for sessions that were [cancelled](/concepts/cancellation), and every per-result object includes an `isCancelled` boolean. v1 clients continue to work unchanged and never see these additions. +**v2 vs v1:** v2 returns the new `CANCELLED` value in `status` for sessions that were [cancelled](/concepts/cancellation). v1 reports the same sessions as `TIMED_OUT` for backward compatibility. The response shape is otherwise identical, including the `isCancelled` boolean on per-result objects. diff --git a/api-reference/check-sessions/retrieve-a-check-session-v2.mdx b/api-reference/check-sessions/retrieve-a-check-session-v2.mdx index 092e7c6d..335d452f 100644 --- a/api-reference/check-sessions/retrieve-a-check-session-v2.mdx +++ b/api-reference/check-sessions/retrieve-a-check-session-v2.mdx @@ -9,5 +9,5 @@ Once a check session has finished, results will include at least one check resul 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 [retrieve a check result](/api-reference/check-results/retrieve-a-check-result) endpoint. -**What's new in v2:** `status` may return the new `CANCELLED` value for sessions that were [cancelled](/concepts/cancellation), and every per-result object includes an `isCancelled` boolean. v1 clients continue to work unchanged and never see these additions. +**v2 vs v1:** v2 returns the new `CANCELLED` value in `status` for sessions that were [cancelled](/concepts/cancellation). v1 reports the same sessions as `TIMED_OUT` for backward compatibility. The response shape is otherwise identical, including the `isCancelled` boolean on per-result objects. diff --git a/api-reference/check-sessions/trigger-a-new-check-session-v2.mdx b/api-reference/check-sessions/trigger-a-new-check-session-v2.mdx index 7e9da64f..992d9357 100644 --- a/api-reference/check-sessions/trigger-a-new-check-session-v2.mdx +++ b/api-reference/check-sessions/trigger-a-new-check-session-v2.mdx @@ -11,5 +11,5 @@ Standard alerting rules apply to finished check runs. Equivalent to the _Schedule Now_ button in the UI. -**What's new in v2:** `status` may return the new `CANCELLED` value for sessions that were [cancelled](/concepts/cancellation), and every per-result object includes an `isCancelled` boolean. v1 clients continue to work unchanged and never see these additions. +**v2 vs v1:** v2 returns the new `CANCELLED` value in `status` for sessions that were [cancelled](/concepts/cancellation). v1 reports the same sessions as `TIMED_OUT` for backward compatibility. The response shape is otherwise identical, including the `isCancelled` boolean on per-result objects. diff --git a/concepts/cancellation.mdx b/concepts/cancellation.mdx index 21f41114..cb567c7e 100644 --- a/concepts/cancellation.mdx +++ b/concepts/cancellation.mdx @@ -78,14 +78,14 @@ Because no alert is sent and the check status does not change, [automated incide ## API versioning -Cancellation introduces two API additions: a new `CANCELLED` value on the check-session status enum, and a new `isCancelled` boolean on individual check results. The status enum change is breaking for clients that switch on status values exhaustively, so it's only exposed through the v2 check-session endpoints; v1 clients continue to work unchanged. The `isCancelled` flag is additive and ships on the existing check-result endpoints without a version bump. +Cancellation introduces two API additions: a new `CANCELLED` value on the check-session status enum, and a new `isCancelled` boolean on individual check results. The `isCancelled` flag is additive and ships on every check-result and check-session response without a version bump. The status enum change is breaking for clients that switch on status values exhaustively, so the new `CANCELLED` value is only returned by the v2 check-session endpoints; v1 maps cancelled sessions to `TIMED_OUT` in `status` so existing clients continue to work unchanged. -[`POST /v1/check-sessions/trigger`](/api-reference/check-sessions/trigger-a-new-check-session), [`GET /v1/check-sessions/{checkSessionId}`](/api-reference/check-sessions/retrieve-a-check-session), and [`GET /v1/check-sessions/{checkSessionId}/completion`](/api-reference/check-sessions/await-the-completion-of-a-check-session) never return `CANCELLED` in `status` and do not include `isCancelled` on per-result objects. +[`POST /v1/check-sessions/trigger`](/api-reference/check-sessions/trigger-a-new-check-session), [`GET /v1/check-sessions/{checkSessionId}`](/api-reference/check-sessions/retrieve-a-check-session), and [`GET /v1/check-sessions/{checkSessionId}/completion`](/api-reference/check-sessions/await-the-completion-of-a-check-session) report cancelled sessions as `TIMED_OUT` in `status` rather than `CANCELLED`. Per-result objects still include `isCancelled`, so individual cancelled runs remain identifiable. -[`POST /v2/check-sessions/trigger`](/api-reference/check-sessions/trigger-a-new-check-session-v2), [`GET /v2/check-sessions/{checkSessionId}`](/api-reference/check-sessions/retrieve-a-check-session-v2), and [`GET /v2/check-sessions/{checkSessionId}/completion`](/api-reference/check-sessions/await-the-completion-of-a-check-session-v2) return `CANCELLED` in `status` and include `isCancelled` on each per-result object. +[`POST /v2/check-sessions/trigger`](/api-reference/check-sessions/trigger-a-new-check-session-v2), [`GET /v2/check-sessions/{checkSessionId}`](/api-reference/check-sessions/retrieve-a-check-session-v2), and [`GET /v2/check-sessions/{checkSessionId}/completion`](/api-reference/check-sessions/await-the-completion-of-a-check-session-v2) return `CANCELLED` in `status` for cancelled sessions. Response shape is otherwise the same as v1. @@ -96,4 +96,4 @@ Cancellation introduces two API additions: a new `CANCELLED` value on the check- [`POST /v1/cancel`](/api-reference/cancel/cancel-a-session) is the action endpoint itself. It accepts either a `checkSessionId` or a `testSessionId` in the body, so a single endpoint covers both. -If you build automation against check sessions and want to handle cancelled runs explicitly, switch to the v2 endpoints. +If you build automation against check sessions and need to distinguish cancelled sessions from genuine timeouts at the session level, switch to the v2 endpoints. Otherwise, the `isCancelled` flag on per-result objects is available in both versions.