API reference

List runs

GET/v1/runs

Scope: runs:read

The runs in the key’s projects, newest first, a page at a time.

curl --fail-with-body -sS https://<workspace>.nightlab.io/v1/runs?external_ref=ci-8812 \
  -H "Authorization: Bearer $NIGHTLAB_API_KEY"

const res = await fetch(
  "https://<workspace>.nightlab.io/v1/runs?external_ref=ci-8812",
  {
    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.get(
    "https://<workspace>.nightlab.io/v1/runs?external_ref=ci-8812",
    headers={"Authorization": f"Bearer {os.environ['NIGHTLAB_API_KEY']}"},
    timeout=30,
)
answer.raise_for_status()

Query

external_refstring
Only runs started with this reference of yours.
projectstring
Only this project’s, by its slug.
statestring
Only runs in this state, like waiting_for_answer.
limitinteger, 1 to 100, default 25
How many on a page.
cursorstring
The next_cursor of the page before.

The answer

200 with runs, a list of runs, and next_cursor: pass it as cursor for the next page, or it’s null on the last.

200 OK

{
  "runs": [
    {
      "id": "run-42",
      "project": "shop",
      "issue": "SHOP-1431",
      "action": "build",
      "state": "queued",
      "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:00:00Z",
      "finished_at": null,
      "links": {
        "api": "/v1/runs/run-42",
        "portal": "https://app.nightlab.io/runs/run-42"
      }
    }
  ],
  "next_cursor": null
}

Refusals

422 for a cursor this API didn’t give, or a state it doesn’t know, and 403 for a key without runs:read.