Set or clear a run's kill switch
Halts or resumes a run’s sandbox commands; it does not cancel the run. Requires permission switches:use.
Halt a run’s sandboxes
While a run’s kill switch is set, every sandbox command the run issues is refused, so a runaway sandbox stops mid-step. The switch does not cancel the run: to stop the run, request its cancellation. The body is exactly{ "id", "active", "reason"? }. active: true sets the switch and needs a reason of 8 to 1,000 characters; active: false clears it, and reason is optional. Every change is audited with your key’s or app’s principal. The answer is { "id", "active", "triggeredAt" }.
Who may use it
You needswitches:use at the run’s home: its own org unit, else its workflow’s owning org unit. It is an elevated permission that no Forge agent holds.
- A run you cannot read (
runs:readat its home and at every company it carries) answers404like a missing run. - A run you can read but whose home you do not hold
switches:useat answers403.
switches:use at the run’s home (see Idempotency).
Related
Authorizations
Headers
1–255 printable ASCII characters (0x21–0x7E, no spaces), scoped to the calling credential. A repeat with the same key and request never runs the write again, a 5xx included: once the operation's permissions pass again it answers the identical status and body of the first response (Idempotent-Replayed: true, also sent as Idempotency-Replayed: true), unless the operation's own replay policy withholds it; a first response that was not stored (over 32 KiB, or carrying a one-time secret) answers its first status with only data.id (Idempotency-Replay-Disclosure: id-only) when it named one; otherwise 409 idempotency_result_unavailable; a repeat while the first is still running is 409 idempotency_key_in_flight, and the same key with a different request is 422 idempotency_key_reuse. Honoured for External App JWTs and platform and Personal keys; an External App's static companion key is not protected.
1 - 255
