Skip to main content
Returns recorded Approvability runs, one entry per GitHub check run, newest recordTime first. Each run carries its verdict, outcome and the eligibility and correctness reasoning behind it.
Follow nextPageToken until it is absent. Results are live, not a snapshot: a verdict recorded again moves the run to a newer recordTime, and a listing already in progress can miss it.

How to analyze with your coding agent

The listing carries the same data the Approvability page shows, so a coding agent can answer questions the page’s charts do not. For example, to judge what Macroscope would have approved while automatic approval was off:
  1. List runs with verdicts=WOULD_APPROVE for the period. These pull requests were eligible, but approval was withheld.
  2. For each pull request, list its runs with repositoryIds and pullRequestNumber and no verdicts filter. A later NOT_APPROVED run means a subsequent commit changed the verdict; pullRequestRunCount says how many runs to expect.
  3. Join the pull requests to List code review comments and List commits to see what reviewers and authors changed before merge.
A prompt such as “Using the Macroscope API, find pull requests Macroscope would have approved last quarter, and tell me which ones later needed code changes and why” is enough for an agent that has an API key and these reference pages.

Authorization

string
required
Bearer <key>. See Authentication.

Path parameters

string
required
GITHUB_ORGANIZATION or GITHUB_USER.
string
required
Numeric GitHub ID of the organization or user. Must match the key’s workspace.

Query parameters

Repeat list parameters, for example verdicts=APPROVED&verdicts=WOULD_APPROVE. Omit a list to select all values; _UNSPECIFIED enum values are invalid filter inputs. Supplied lists must contain distinct values.
string
Inclusive UTC instant (RFC 3339), matched against recordTime. Defaults to 90 days before the resolved endTime, and must be before it and at most 366 days earlier. Without endTime, it must be in the past and within the last 366 days.
string
Exclusive UTC instant (RFC 3339), after startTime. Defaults to now. The interval is half-open, [startTime, endTime). Continuations keep the window the first page resolved.
string[]
Up to 100 GitHub repository IDs, each 1–128 characters, including removed repositories. Omit for every repository in the workspace. An ID with no runs yields an empty page.
string
One pull request number, a positive int64 encoded as a decimal string. Requires exactly one repositoryIds value.
string[]
SKIPPED, NOT_APPROVED, WOULD_APPROVE or APPROVED, matched against each run’s recorded verdict. Runs without a verdict match only when this list is omitted. See Verdicts.
string[]
RUN_COMPLETED, RUN_SKIPPED or RUN_FAILED. Runs without a recorded outcome match only when this list is omitted.
integer
default:"50"
Maximum runs per page, 1–200.
string
Opaque nextPageToken. Bound to workspace, operation and filters; expires after 24 hours. Repeat original filters; pageSize may change. Invalid, expired, altered or mismatched tokens return 400; restart without the token.

Response

Run[]
Matching runs on this page, newest recordTime first. Omitted for an empty page.
string
Opaque continuation. Omitted when no more matching runs remain.
See shared errors and limits. Invalid filters, dates, page sizes or tokens return 400, including pullRequestNumber without exactly one repository. Missing workspace access returns 403. Approvability not available for the workspace returns 404. Reasoning is never truncated. A page larger than the 50 MiB response limit returns 400 with code 9; repeat the request with the same pageToken and a smaller pageSize.

Run

False, zero and empty values are omitted unless a field says otherwise.
string
GitHub repository ID.
string
Repository owner login. Omitted when the repository record no longer exists.
string
Repository name without the owner, for example backend. Omitted when the repository record no longer exists.
string
GitHub pull request number (int64 as string).
string
Link to the pull request on GitHub. Omitted when the repository owner or name is unknown.
string
GitHub login of the pull request author. Omitted when unknown.
string
Pull request head branch, without refs/heads/. Omitted when unknown.
string
The commit the run judged.
string
RUN_COMPLETED (at least one hurdle was evaluated), RUN_SKIPPED (skipped before evaluating; see skippedReason) or RUN_FAILED (failed with an error). Omitted only for a run that recorded no outcome.
string
SKIPPED, NOT_APPROVED (shown as Needs Human Approval), WOULD_APPROVE or APPROVED. See Verdicts. Omitted when the run recorded no verdict: it failed, or it predates stored verdicts. An omitted verdict is not SKIPPED.
string
When the GitHub check run started (RFC 3339).
string
When the verdict was recorded (RFC 3339). The sort key and the time startTime and endTime filter on. Moves when a verdict is recorded again.
string
Why the run was skipped. Present only with RUN_SKIPPED.
string
When the run failed (RFC 3339). Present only with RUN_FAILED.
Hurdle
Whether the change was eligible for approval. Omitted when eligibility was never evaluated.
Hurdle
Whether the change was judged correct. Omitted when correctness was never evaluated.
boolean
true when the repository’s custom eligibility rules decided eligibility. Omitted when false.
boolean
true when those rules were read from front-matter configuration. Omitted when false.
integer
Agent credits billed for the run. 0 when the run was free. Omitted when the run was not billed or its credits are unknown. See Agent pricing.
boolean
true when the run was billed, false when it was not. Omitted when billing is unknown, so an omitted value is not false.
string
Every run recorded for this pull request (int64 as string), regardless of the request’s filters and dates. It can exceed the runs this listing returns for the pull request.

Hurdle

One hurdle’s recorded judgment. An object with no fields means the hurdle was evaluated and did not pass, with no recorded explanation.
boolean
true when the hurdle passed. Omitted when false.
boolean
true when the hurdle could not be evaluated and did not block approval. Omitted when false.
string
Macroscope’s explanation, in Markdown. Omitted when empty.