> ## Documentation Index
> Fetch the complete documentation index at: https://docs.macroscope.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Query approvability statistics

> See Approvability verdict counts and approval rates

Returns [Approvability](https://docs.macroscope.com/approvability.md) 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](https://docs.macroscope.com/api-reference/endpoint/list-approvability-runs.md).

## 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.

**Authorization** `string` *required*

`Bearer <key>`. See [Authentication](https://docs.macroscope.com/api#authentication).

## Path parameters

**workspaceType** `string` *required*

`GITHUB_ORGANIZATION` or `GITHUB_USER`.

**workspaceId** `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.

**startTime** `string` *required*

Inclusive UTC instant (RFC 3339), matched against each run's recorded time.

**endTime** `string` *required*

Exclusive UTC instant (RFC 3339), after `startTime` and at most 366 days later. The interval is half-open, `[startTime, endTime)`.

**repositoryIds** `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.

**pullRequestNumber** `string`

One pull request number, a positive int64 encoded as a decimal string. Requires exactly one `repositoryIds` value.

**verdicts** `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](https://docs.macroscope.com/approvability.md#verdicts).

## Response

**summary** `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.

**trend** `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](#summary-and-trend). Omitted when no run matches.

**periodDays** `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](https://docs.macroscope.com/api#errors). 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.

**pullRequestsWithVerdict** `string`

Pull requests whose latest run recorded a verdict, including `SKIPPED`. A pull request whose latest run recorded no verdict is not counted.

**approvedPullRequests** `string`

Pull requests whose latest verdict is `APPROVED`.

**approvablePullRequests** `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.

**judgedCommits** `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.

**eligibleCommits** `string`

Judged commits found eligible.

**approvalRate** `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

**startTime** `string`

Period start (RFC 3339).

**endTime** `string`

Exclusive period end (RFC 3339).

**counts** `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.

```bash cURL theme={null}
curl --get https://api.macroscope.com/api/v1/workspaces/GITHUB_ORGANIZATION/12345678/approvability-statistics \
  -H "Authorization: Bearer $MACROSCOPE_API_KEY" \
  --data-urlencode "startTime=2026-09-28T00:00:00Z" \
  --data-urlencode "endTime=2026-10-05T00:00:00Z" \
  --data-urlencode "repositoryIds=123456789"
```

```python Python theme={null}
import os, requests

r = requests.get(
    "https://api.macroscope.com/api/v1/workspaces/GITHUB_ORGANIZATION/12345678/approvability-statistics",
    headers={"Authorization": f"Bearer {os.environ['MACROSCOPE_API_KEY']}"},
    params={
        "startTime": "2026-09-28T00:00:00Z",
        "endTime": "2026-10-05T00:00:00Z",
        "repositoryIds": ["123456789"],
    },
)
summary = r.json()["summary"]
print(summary.get("approvalRate"))
```

```json 200 theme={null}
{
  "summary": {
    "pullRequestsWithVerdict": "18",
    "approvedPullRequests": "9",
    "approvablePullRequests": "11",
    "judgedCommits": "22",
    "eligibleCommits": "13",
    "approvalRate": 0.5
  },
  "trend": [
    {
      "startTime": "2026-09-28T00:00:00Z",
      "endTime": "2026-09-29T00:00:00Z",
      "counts": { "pullRequestsWithVerdict": "4", "approvedPullRequests": "2", "approvablePullRequests": "3", "judgedCommits": "5", "eligibleCommits": "3", "approvalRate": 0.5 }
    },
    {
      "startTime": "2026-09-29T00:00:00Z",
      "endTime": "2026-09-30T00:00:00Z",
      "counts": { "pullRequestsWithVerdict": "5", "approvedPullRequests": "3", "approvablePullRequests": "3", "judgedCommits": "6", "eligibleCommits": "4", "approvalRate": 0.6 }
    },
    {
      "startTime": "2026-09-30T00:00:00Z",
      "endTime": "2026-10-01T00:00:00Z",
      "counts": { "pullRequestsWithVerdict": "3", "approvedPullRequests": "1", "approvablePullRequests": "2", "judgedCommits": "4", "eligibleCommits": "2", "approvalRate": 0.3333333333333333 }
    },
    {
      "startTime": "2026-10-01T00:00:00Z",
      "endTime": "2026-10-02T00:00:00Z",
      "counts": { "pullRequestsWithVerdict": "4", "judgedCommits": "4", "eligibleCommits": "1", "approvalRate": 0 }
    },
    {
      "startTime": "2026-10-02T00:00:00Z",
      "endTime": "2026-10-03T00:00:00Z",
      "counts": { "pullRequestsWithVerdict": "3", "approvedPullRequests": "3", "approvablePullRequests": "3", "judgedCommits": "4", "eligibleCommits": "4", "approvalRate": 1 }
    },
    {
      "startTime": "2026-10-03T00:00:00Z",
      "endTime": "2026-10-04T00:00:00Z",
      "counts": {}
    },
    {
      "startTime": "2026-10-04T00:00:00Z",
      "endTime": "2026-10-05T00:00:00Z",
      "counts": {}
    }
  ],
  "periodDays": 1
}
```

```json 401 theme={null}
{ "code": 16, "message": "unauthenticated" }
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.