Sign in
Runs

Filter a Project's Runs by date range, module, status and executor, with matching pass/fail totals

Changed on

Bearer atc:read (or cookie session). The PAT scope catalog has no run-read scope, so run reporting reuses the read scope rather than minting a fifth one (BK-499, superseding this story Key Contract Decision that deferred the question). One SECURITY DEFINER RPC (bunkai_report_project_runs) resolves the Project's workspace and re-checks ACTIVE membership in-band; any role reads, viewers included. Every filter is AND-composed and every filter composes with pagination server-side. Unlike GET /api/v1/tests/{id}/runs, rows are NOT restricted to terminal statuses — a currently-running Run is a legitimate row — and totals is recomputed from the SAME filtered set as the rows (not all-time), so the numbers change as filters narrow (Business Rule #3 / Technical Decision D2). Pagination is KEYSET on (started_at desc, id desc), reusing the same opaque cursor contract as the run-history endpoint. A Project with no matching Runs returns an empty items with zeroed totals (never a 404) — a 404 means the Project itself is missing, foreign, or unreadable.

get/api/v1/projects/{id}/runs/report

Request

  • Base URL: http://localhost:3000
  • URL: http://localhost:3000/api/v1/projects/{id}/runs/report
  • Auth: one of:
    • API key in cookie sb-fmbpikzpkafptqximhxn-auth-token
    • HTTP bearer

Path parameters

idstring uuid required

The Project whose Run report to read.

Query parameters

date_fromstring date

Inclusive lower bound on started_at, matched as a UTC calendar day (YYYY-MM-DD). No projects.timezone column exists to interpret against (Technical Decision D3).

date_tostring date

Inclusive upper bound on started_at, matched as a UTC calendar day (YYYY-MM-DD). Rejected (422) when earlier than date_from.

module_idstring uuid

Narrow the report to Runs whose snapshotted module matches this Project module.

statusstring[]

Narrow to one or more statuses, repeatable (?status=passed&status=failed). running is NOT an accepted filter value (422) — an in-progress Run can still appear as a row, it just is not a selectable filter target (Technical Decision D4).

executorstring[]

Narrow to one or more executor modes, repeatable (?executor=human&executor=agent).

limitinteger

Page size, 1..50 (default 50). Out of range is rejected (422); the RPC additionally clamps for direct callers.

cursorstring

Opaque page token taken verbatim from the previous response's next_cursor. The token is base64url and therefore URL-safe as issued — it needs no escaping and must not be re-encoded. A malformed token returns 400 — it never silently falls back to the first page.

Response

One page of the Run report (possibly empty).

next_cursorstring nullable required

Opaque token for the next (older) page, or null when this is the last page. base64url, so it is URL-safe as-is: echo it back verbatim as ?cursor=; never construct or parse one.

Changes

  • 4528999528c6Revision changes
    • warning

      added the new test_outside_plan_project enum value to the / response property for the response status

    • warning

      added the new test_outside_plan_project enum value to the / response property for the response status

    • warning

      added the new test_outside_plan_project enum value to the / response property for the response status

    • warning

      added the new test_outside_plan_project enum value to the / response property for the response status

    • warning

      added the new test_outside_plan_project enum value to the / response property for the response status

  • 2ca74ff5fec5Revision changes
    • info

      removed the test_outside_plan_project enum value from the / response property for the response status

    • info

      removed the test_outside_plan_project enum value from the / response property for the response status

    • info

      removed the test_outside_plan_project enum value from the / response property for the response status

    • info

      removed the test_outside_plan_project enum value from the / response property for the response status

    • info

      removed the test_outside_plan_project enum value from the / response property for the response status