CI roll-up for a page of pull requests

GET/api/repos/{owner}/{repo}/pulls/checks

listPullRequestChecksRollup

Returns one check roll-up per PR for the same page the sibling list endpoint returns, in the same order. Two statements for the whole page regardless of page size. Each roll-up is the newest-run-per-context collapse over that PR's CURRENT head — the same set the PR's own checks endpoint and the merge gate judge, so a list row can never contradict the PR it links to. Separate from the list payload on purpose: check state churns while a run is in flight and the rest of a PR row does not, so the two carry different cache lifetimes. Takes the list's `cursor`/`offset` with the same meaning, so a cursor names the same page here.

Authentication is not described for this operation in the spec — that does not mean it is public. Check tokens and scopes.

curl

curl -X GET 'https://neosource.dev/api/repos/OWNER/REPO/pulls/checks'

fetch

fetch("https://neosource.dev/api/repos/OWNER/REPO/pulls/checks", {
  method: "GET",
});

Path parameters

ownerrequired: Repository owner or organization slug.
string
reporequired: Repository name.
string

Query parameters

status: Filter by status.
PullRequestStatus
string
Lifecycle status of a pull request.
"open""merged""closed"
limit: Maximum number of results.
integerint64
default30
offset: Deprecated: pass `cursor` instead. Rows to skip before the page; still honoured, and a request carrying it still gets `counts`. Sending a positive `offset` together with `cursor` is a 400.
integerint64
default0
cursor: Opaque pagination cursor from a previous response's `next_cursor`: the next (older) page. A request with a cursor gets `counts: null`.
string

Responses

200Per-PR check roll-ups

application/json

PullRequestChecksListResponse

object

Roll-ups for one page of PRs, in the same order the sibling list returns them.

pull_requestsrequired

array

items

PullRequestChecksRollup

object

One PR's CI roll-up, keyed by its repo-scoped `number`. Deliberately NOT a field on [`PullRequestResponse`]. A PR's title, branches and author change when somebody edits them; its check state changes every few seconds while a run is in flight. Folding the second into the first would make every CI heartbeat invalidate the whole list payload — the client would refetch titles and branches to learn that a dot went green, and a prerendered snapshot would bake in a verdict that expires before anyone reads it. Two payloads, two cache postures.

checks_summaryrequired: ChecksSummary
head_commit: string | null
The head the roll-up was computed against (40-char Git OID hex), or `null` before the first push resolves one. Present so a client can tell "checked, nothing ran" from "there is nothing to check yet".
numberrequired: integerint32
Repo-scoped PR number — the join key back to the list payload.
queue_candidate: string | null
The merge-queue candidate (40-char Git OID hex) `checks_summary` was computed against: the PR's live queue entry is speculative, frozen on the PR's current head, and its candidate has reported at least one check. `null` when the roll-up is the head's.
workflows: array
The roll-up split by workflow, over the same commit and the same collapse as `checks_summary`: each workflow's newest surviving run, in row order (by path, then id). What a PR row paints one icon per.
itemsWorkflowCheck

Standard errors

Bodies documented once for the whole API — see standard errors.

400Bad Request — one of: invalid_input
403Forbidden — one of: forbidden
404Not Found — one of: not_found
423Locked — one of: busy
429Rate limited — retry after the `Retry-After` header
500Internal server error
503Service temporarily unavailable / at capacity — retry after the `Retry-After` header
504Gateway timeout — the request exceeded the server's handling budget

Schemas

Referenced above. Listed here rather than expanded inline, so the same definition is not repeated at every level.

`ChecksSummary`

object

Roll-up of the check states for the merge box. Counted over the newest-run-per-context set (`neosource_forge::head_checks`), so a run that a re-run superseded is not a second check.

failedrequired: integerint32
`failure` + `error` states — both render red and both block.
pendingrequired: integerint32
skipped: integerint32
Checks whose job never ran (gated off by a job-level `if:`, or a `needs:` predecessor did not succeed). Counted separately from `success`; `success + failed + pending + skipped == total`.
successrequired: integerint32
Checks that ran and passed. Deliberately EXCLUDES skipped ones: a skipped check carries `state: success` so it cannot block a merge, but counting it as "passed" would tell the reader that work happened when it did not — the same claim the per-check `skipped` flag exists to stop the UI making.
superseded: integerint32
Checks the merge queue superseded (`CheckRun::superseded`, ADR 0160): a SUBSET of `pending` (`superseded <= pending`) — they are counted in `pending` too, so a reader that ignores this field still sees the head as not green — never in `failed` (nothing failed). Render `pending - superseded` as in flight and these as superseded.
totalrequired: integerint32

`WorkflowCheck`

object

One workflow's newest run on a commit — one icon of a commit or PR row, beside the workflow's siblings, where a single roll-up would hide which workflow was red (`WorkflowVerdict` in neosource-core). Rows receive these already ordered: by `workflow_path`, then `workflow_id`, an unregistered workflow last — never by state.

run_idrequired: string
The newest run (latest attempt) of this workflow on the commit (UUID).
run_numberrequired: integerint64
skippedrequired: boolean
Every job of the run was skipped: `status` is `succeeded`, but no work ran.
statusrequired: WorkflowRunStatus
string
Lifecycle of a workflow run. Mirrors the GHA-shaped surface that the SPA renders. The serde `snake_case` strings are the wire vocabulary the API emits (pinned by the `enum_wire_consistency` tests).
"pending_approval""queued""quota_blocked""concurrency_blocked""running""cancelling""succeeded""failed""cancelled"
supersededrequired: boolean
The merge queue superseded and cancelled this run (ADR 0160): render neutral, neither red nor in flight.
workflow_idrequired: string
Workflow id (UUID).
workflow_namerequired: string
The workflow's declared `name:` as the run pinned it.
workflow_path: string | null
The workflow file's repo path; `null` when the workflow is no longer registered.