List runs

Runs in a period, newest first - one row per logical run (a sharded CI run is one row; each job of a CI run that sets a job key is its own run, see jobKey), placed in the period and ordered by the start of its first shard (since 1.0.0-beta.13). CI and local runs both, unless source narrows it. Filter by branch, commit SHA prefix, status or source; page with the cursors. Cheap to moderate: bounded by the period’s runs.

GET/api/v1/projects/{projectId}/runs

Parameters

Parameter	Description
`projectId`string · pathrequired	A project id from GET /projects.
`days`7 \| 14 \| 30 \| 90 · default 30	The period, in days, ending now. Must not exceed the plan’s retention (Standard 60, Pro 90 days); a longer period is refused with 400 invalid_period rather than answered with less data.
`branch`string	Exact branch name.
`sha`string	A commit SHA or a prefix of one (4-40 hex characters). Matches the run’s commitSha - the commit the run is reported under: the pushed commit, or for a pull request its head - or its testedRevision, the application revision the run was told it tested (opt-in, usually null).
`status`passed \| failed \| cancelled \| incomplete \| running	Only runs with this status - the status field’s values. A cancelled run matches cancelled only (since 1.0.0-beta.14; passed and failed were the only values before it, and a cancelled run matched neither).
`source`ci \| local \| all · default all	Which runs are listed, by where they ran: all - every run (the default); ci - runs a shard reported a CI provider for; local - runs no shard did (each run’s local field). Since 1.0.0-beta.14.
`perPage`10 \| 25 \| 50 · default 10	Rows per page.
`cursor`string	Opaque. Pass nextCursor for older runs, or prevCursor together with direction=prev for newer runs.
`direction`next \| prev · default next	Which way the cursor pages.

Request

BASE="https://app.squally.dev/api/v1"
URL="$BASE/projects/$PROJECT/runs"
curl "$URL" \
  -H "Authorization: Bearer $SQUALLY_API_KEY"

const base = "https://app.squally.dev/api/v1";
const key = process.env.SQUALLY_API_KEY;
const url = `${base}/projects/${projectId}`
  + `/runs`;
const response = await fetch(url, {
  headers: { Authorization: `Bearer ${key}` },
});
const data = await response.json();

import os
import requests

base = "https://app.squally.dev/api/v1"
key = os.environ["SQUALLY_API_KEY"]
url = f"{base}/projects/{project_id}/runs"
response = requests.get(
    url,
    headers={"Authorization": f"Bearer {key}"},
)
data = response.json()

{
  "project": {
    "id": "3f7c2a91-5b8e-4d0a-9c61-2e4b7f0d8a…",
    "name": "storefront-web"
  },
  "window": {
    "days": 30,
    "from": "2026-08-25T08:00:00.000Z",
    "to": "2026-09-24T08:00:00.000Z"
  },
  "runs": [
    {
      "id": "b1e0c6d2-7a43-4f19-8d5e-0c3a9e6f…",
      "runNumber": 1284,
      "branch": "main",
      "commitSha": "3b5d8e2f9a1c4e7b0d6f2a8c5…",
      "testedRevision": null,
      "pullRequestNumber": null,
      "status": "passed",
      "cancellation": null,
      "local": false,
      "settled": true,
      "jobKey": null,
      "attempt": 1,
      "rerunOf": null,
      "ciRunUrl": "https://github.com/example…",
      "startedAt": "2026-09-24T07:31:12.000Z",
      "finishedAt": "2026-09-24T07:39:47.000Z",
      "durationMs": 515000,
      "counts": {
        "total": 412,
        "passed": 408,
        "failed": 0,
        "skipped": 3,
        "flaky": 1
      },
      "shards": {
        "received": 2,
        "expected": 2
      }
    },
    {
      "id": "7d2f4b19-3c8e-4a61-9e07-5b1d8c2a…",
      "runNumber": 1283,
      "branch": "feature/saved-carts",
      "commitSha": "8e2c6a0d4f1b9e7c3a5d8f0b2…",
      "testedRevision": "c4f7a1e9b3d5c8e2f0a6…",
      "pullRequestNumber": 318,
      "status": "failed",
      "cancellation": null,
      "local": false,
      "settled": true,
      "jobKey": null,
      "attempt": 1,
      "rerunOf": null,
      "ciRunUrl": "https://github.com/example…",
      "startedAt": "2026-09-23T16:05:40.000Z",
      "finishedAt": "2026-09-23T16:12:02.000Z",
      "durationMs": 382000,
      "counts": {
        "total": 405,
        "passed": 401,
        "failed": 2,
        "skipped": 2,
        "flaky": 0
      },
      "shards": null
    },
    {
      "id": "e4a9c2f7-1b6d-4e83-9f05-7c3b8d1a…",
      "runNumber": 1282,
      "branch": "feature/saved-carts",
      "commitSha": "5f1d9b3e7a2c6e0f8b4d2a9c7…",
      "testedRevision": null,
      "pullRequestNumber": 318,
      "status": "cancelled",
      "cancellation": {
        "source": "reporter",
        "at": "2026-09-23T15:58:31.000Z",
        "byUserId": null
      },
      "local": false,
      "settled": true,
      "jobKey": null,
      "attempt": 1,
      "rerunOf": null,
      "ciRunUrl": "https://github.com/example…",
      "startedAt": "2026-09-23T15:55:02.000Z",
      "finishedAt": "2026-09-23T15:58:31.000Z",
      "durationMs": 209000,
      "counts": {
        "total": 164,
        "passed": 157,
        "failed": 1,
        "skipped": 6,
        "flaky": 0
      },
      "shards": null
    }
  ],
  "total": 57,
  "nextCursor": "MjAyNi0wOS0yM1QxNjowNTo0MC4w…",
  "prevCursor": null
}

{
  "error": "sha must be 4 to 40 hexadecimal c…",
  "code": "invalid_parameter"
}

{
  "error": "Invalid read key.",
  "code": "invalid_key"
}

{
  "error": "This organization has been delete…",
  "code": "organization_deleted"
}

{
  "error": "No project with this id in this o…",
  "code": "project_not_found"
}

{
  "error": "Too many requests with this read …",
  "code": "rate_limited"
}

{
  "error": "Something went wrong on our side.",
  "code": "internal_error"
}

Example values. The shape is generated from the API schema.

Ask about this pageChatGPT Claude

Responses

200400401403404429500

Read API

API reference

List runs

Parameters

Responses