API reference

Cancel a run

POST/v1/runs/{run_id}/cancel

Scope: runs:write

Stops a run that’s queued, running, or waiting for a person’s answer.

curl --fail-with-body -sS -X POST https://<workspace>.nightlab.io/v1/runs/run-42/cancel \
  -H "Authorization: Bearer $NIGHTLAB_API_KEY"

const res = await fetch(
  "https://<workspace>.nightlab.io/v1/runs/run-42/cancel",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.NIGHTLAB_API_KEY}`,
    },
  },
);
if (!res.ok) throw new Error(await res.text());
const answer = await res.json();

import os, requests

answer = requests.post(
    "https://<workspace>.nightlab.io/v1/runs/run-42/cancel",
    headers={"Authorization": f"Bearer {os.environ['NIGHTLAB_API_KEY']}"},
    timeout=30,
)
answer.raise_for_status()

Path

run_idstringRequired
The run’s id.

The answer

200 with the run, now cancelled, and run.cancelled goes to your webhooks.

200 OK

{
  "id": "run-42",
  "project": "shop",
  "issue": "SHOP-1431",
  "action": "build",
  "state": "cancelled",
  "outcome": null,
  "no_pr_reason": null,
  "pr_url": null,
  "pr_state": null,
  "external_ref": "ci-8812",
  "summary": null,
  "created_at": "2026-11-01T10:00:00Z",
  "updated_at": "2026-11-01T10:02:00Z",
  "finished_at": "2026-11-01T10:02:00Z",
  "links": {
    "api": "/v1/runs/run-42",
    "portal": "https://app.nightlab.io/runs/run-42"
  }
}

Refusals

409 for a run that has already ended, or one waiting for approval: a person declines that in the portal. 404 for a run outside the key’s projects, and 403 for a key without runs:write.