Cancel visibility run

Cancels the queued remainder of an AI Visibility run.

Use this as a killswitch when a run turns out bigger or more expensive than intended. Probes no worker has picked up yet never run, and their reserved credits are released back to your account. Probes a worker has already claimed (workers take probes in small batches) finish and settle normally, and completed results stay available.

This endpoint applies to direct-URL runs created with Create visibility run. Saved-test and scheduled runs are not queue-backed and cannot be cancelled here.

Endpoint

POST /v1/visibility/runs/{run_id}/cancel

Authentication

Header	Required	Value
`Authorization`	Yes	`Bearer sw_api_live_...`

Required scope:

visibility:runs:create

The same scope that can queue a run can stop one. Read-only keys cannot cancel.

Example Request

curl -s -X POST https://api.sleepwalker.ai/v1/visibility/runs/6a75b22b-.../cancel \
  -H "Authorization: Bearer sw_api_live_..."

Response

{
  "run_id": "6a75b22b-...",
  "status": "partially_completed",
  "already_terminal": false,
  "cancelled_now": 31,
  "queued_probe_count": 0,
  "running_probe_count": 0,
  "succeeded_probe_count": 19,
  "errored_probe_count": 0,
  "cancelled_probe_count": 31,
  "settled_credits": "228.00",
  "released_credits": "372.00",
  "billing_pending": false
}

Field	Meaning
`cancelled_now`	Probes this call stopped before they ran.
`released_credits`	Credits returned to your balance by this call.
`billing_pending`	`true` while probes are still executing. Their outcome settles when they finish, and the remaining release normally happens on the last completion. Poll Get AI Visibility Run until the run is terminal; the released amount equals `reserved_credits` minus `settled_credits`.
`already_terminal`	`true` when the run had already finished; nothing changed.

Semantics

Cancelling is idempotent. Repeating the call, or cancelling a finished run, changes nothing and reports the current state.
Probes a worker is actively executing are not interrupted. They finish, settle for their own price, and stay in your results. Runs with in-flight probes report billing_pending: true; how long the drain takes depends on how many probes the worker had already claimed and how slow the selected model is.
The remaining release normally happens automatically when the last in-flight probe finishes. If a worker crashes mid-probe, the run can instead sit in running without progressing; calling cancel again forces the stranded remainder out and releases its credits. Repeat cancels are always safe.
The run ends as cancelled when nothing succeeded, or partially_completed when some probes finished. Completed probe results remain readable.
Reserved credits for cancelled probes always return to your balance. Settled credits for completed probes are not refunded.

Errors

Status	Meaning
`401`	Missing or invalid API key.
`403`	API key is missing `visibility:runs:create`, or this action is unavailable.
`404`	The run does not exist or belongs to another account.