Skip to main content
Returns Approvability verdict counts for your workspace, over an interval: a summary in which each pull request is counted once, plus a trend of up to 120 periods. Pull requests and their runs are selected by when each verdict was recorded. To see the runs behind these counts, use List approvability runs.

Authorization

The trend is bounded and has no pagination. Results are live, not a snapshot: a verdict recorded again moves to its new recording time, so counts for a past interval can change.
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.
string
required
Inclusive UTC instant (RFC 3339), matched against each run’s recorded time.
string
required
Exclusive UTC instant (RFC 3339), after startTime and at most 366 days later. The interval is half-open, [startTime, endTime).
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 result.
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. Selects pull requests whose latest run in the interval recorded one of these verdicts; all of their runs in the interval are then counted, including in the trend. See Verdicts.

Response

Counts
Counts for the whole interval, with each pull request counted by its latest run in the interval and each commit by its latest judged run. Always present; an empty object means nothing matched.
Period[]
At most 120 consecutive periods of periodDays UTC days, oldest first, including periods with no runs. The first starts at UTC midnight on or before startTime; the last ends at endTime and can be shorter. Each pull request is counted once per period in which it had runs, so periods do not sum to summary; see Summary and trend. Omitted when no run matches.
integer
Length of each trend period in days: the interval divided into at most 120 periods, rounded up to whole days. Omitted when trend is omitted.
See shared errors and limits. A missing date, an invalid interval or invalid filters return 400, including pullRequestNumber without exactly one repository. Missing workspace access returns 403. Approvability not available for the workspace returns 404.

Counts

Counts are int64 values encoded as strings. A count is omitted when zero; omission means zero.
string
Pull requests whose latest run recorded a verdict, including SKIPPED. A pull request whose latest run recorded no verdict is not counted.
string
Pull requests whose latest verdict is APPROVED.
string
Pull requests whose latest verdict is APPROVED or WOULD_APPROVE: Macroscope approved them, or would have with automatic approval on. This does not mean the pull request can currently be merged.
string
Commits whose eligibility for approval was evaluated, each counted by its latest judged run, excluding runs with a SKIPPED verdict. Commit counts measure eligibility judgments, not code quality.
string
Judged commits found eligible.
number
approvedPullRequests / pullRequestsWithVerdict, a fraction from 0 to 1. Absent when pullRequestsWithVerdict is zero: absent means no denominator, not zero. A present 0 is a measured rate.

Period

string
Period start (RFC 3339).
string
Exclusive period end (RFC 3339).
Counts
Counts for runs recorded in this period. Always present; an empty object means no runs in the period.

Summary and trend

Pull-request counts count each pull request by its latest run in the scope: the whole interval for summary, each period for trend. Commit counts count each commit by its latest run in the same scope that judged eligibility. A pull request whose latest verdict is SKIPPED counts in pullRequestsWithVerdict but not as approved or approvable; skipped runs never count toward commit counts. Periods cannot be summed into summary: a pull request with runs in several periods is counted in each, with that period’s latest verdict, but once in summary, with its latest verdict overall. summary.approvalRate is a distinct metric, not the average shown on the Approvability page’s trend chart. The chart averages its plotted periods, dividing their total approved pull requests by their total pull requests with a verdict. If five pull requests are not approved in one period and approved in the next, the chart average is 50% (5 of 10) and summary.approvalRate is 1 (5 of 5). trend returns every period in the interval. The chart plots a selection: it omits leading periods with no verdicts and a trailing period that is shorter than periodDays, still in progress, or has fewer than five pull requests with a verdict. To reproduce the chart average, apply the same selection and sum approvedPullRequests and pullRequestsWithVerdict over the remaining periods.