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

# List approvability runs

> Recorded Approvability runs with verdicts, eligibility and correctness reasoning

Returns recorded [Approvability](https://docs.macroscope.com/approvability.md) runs, one entry per GitHub check run, newest `recordTime` first. Each run carries its verdict, outcome and the eligibility and correctness reasoning behind it.

> [!NOTE]
>
> 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](https://docs.macroscope.com/api-reference/endpoint/list-code-review-comments.md) and [List commits](https://docs.macroscope.com/api-reference/endpoint/list-commits.md) 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

**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. Supplied lists must contain distinct values.

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

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

**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 page.

**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`, matched against each run's recorded verdict. Runs without a verdict match only when this list is omitted. See [Verdicts](https://docs.macroscope.com/approvability.md#verdicts).

**outcomes** `string[]`

`RUN_COMPLETED`, `RUN_SKIPPED` or `RUN_FAILED`. Runs without a recorded outcome match only when this list is omitted.

**pageSize** `integer` (default: 50)

Maximum runs per page, 1–200.

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

**runs** `Run[]`

Matching runs on this page, newest `recordTime` first. Omitted for an empty page.

**nextPageToken** `string`

Opaque continuation. Omitted when no more matching runs remain.

See [shared errors and limits](https://docs.macroscope.com/api#errors). 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.

**repositoryId** `string`

GitHub repository ID.

**repositoryOwner** `string`

Repository owner login. Omitted when the repository record no longer exists.

**repositoryName** `string`

Repository name without the owner, for example `backend`. Omitted when the repository record no longer exists.

**pullRequestNumber** `string`

GitHub pull request number (int64 as string).

**githubUrl** `string`

Link to the pull request on GitHub. Omitted when the repository owner or name is unknown.

**authorLogin** `string`

GitHub login of the pull request author. Omitted when unknown.

**branch** `string`

Pull request head branch, without `refs/heads/`. Omitted when unknown.

**commitSha** `string`

The commit the run judged.

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

**verdict** `string`

`SKIPPED`, `NOT_APPROVED` (shown as **Needs Human Approval**), `WOULD_APPROVE` or `APPROVED`. See [Verdicts](https://docs.macroscope.com/approvability.md#verdicts). Omitted when the run recorded no verdict: it failed, or it predates stored verdicts. An omitted verdict is not `SKIPPED`.

**startTime** `string`

When the GitHub check run started (RFC 3339).

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

**skippedReason** `string`

Why the run was skipped. Present only with `RUN_SKIPPED`.

**failureTime** `string`

When the run failed (RFC 3339). Present only with `RUN_FAILED`.

**eligibility** `Hurdle`

Whether the change was eligible for approval. Omitted when eligibility was never evaluated.

**correctness** `Hurdle`

Whether the change was judged correct. Omitted when correctness was never evaluated.

**customEligibilityPolicy** `boolean`

`true` when the repository's [custom eligibility rules](https://docs.macroscope.com/approvability.md#custom-eligibility-rules) decided eligibility. Omitted when `false`.

**customEligibilityPolicyFrontMatter** `boolean`

`true` when those rules were read from front-matter configuration. Omitted when `false`.

**agentCredits** `integer`

Agent credits billed for the run. `0` when the run was [free](https://docs.macroscope.com/approvability.md#pricing). Omitted when the run was not billed or its credits are unknown. See [Agent pricing](https://docs.macroscope.com/pricing.md#agent).

**agentCreditsBilled** `boolean`

`true` when the run was billed, `false` when it was not. Omitted when billing is unknown, so an omitted value is not `false`.

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

**passed** `boolean`

`true` when the hurdle passed. Omitted when `false`.

**skipped** `boolean`

`true` when the hurdle could not be evaluated and did not block approval. Omitted when `false`.

**reason** `string`

Macroscope's explanation, in Markdown. Omitted when empty.

```bash cURL theme={null}
curl --get https://api.macroscope.com/api/v1/workspaces/GITHUB_ORGANIZATION/12345678/approvability-runs \
  -H "Authorization: Bearer $MACROSCOPE_API_KEY" \
  --data-urlencode "startTime=2026-07-01T00:00:00Z" \
  --data-urlencode "endTime=2026-10-01T00:00:00Z" \
  --data-urlencode "verdicts=APPROVED" \
  --data-urlencode "pageSize=50"
```

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

url = "https://api.macroscope.com/api/v1/workspaces/GITHUB_ORGANIZATION/12345678/approvability-runs"
headers = {"Authorization": f"Bearer {os.environ['MACROSCOPE_API_KEY']}"}
params = {
    "startTime": "2026-07-01T00:00:00Z",
    "endTime": "2026-10-01T00:00:00Z",
    "verdicts": ["APPROVED"],
}
runs = []
while True:
    body = requests.get(url, headers=headers, params=params).json()
    runs.extend(body.get("runs", []))
    if "nextPageToken" not in body:
        break
    params["pageToken"] = body["nextPageToken"]
print(len(runs))
```

```json 200 theme={null}
{
  "runs": [
    {
      "repositoryId": "123456789",
      "repositoryOwner": "acme",
      "repositoryName": "backend",
      "pullRequestNumber": "42",
      "githubUrl": "https://github.com/acme/backend/pull/42",
      "authorLogin": "example-developer",
      "branch": "fix-cancellation",
      "commitSha": "0123456789abcdef0123456789abcdef01234567",
      "outcome": "RUN_COMPLETED",
      "verdict": "APPROVED",
      "startTime": "2026-09-30T17:58:12Z",
      "recordTime": "2026-09-30T18:02:45Z",
      "eligibility": {
        "passed": true,
        "reason": "Small, well-tested change to cancellation handling in one module."
      },
      "correctness": {
        "passed": true,
        "reason": "No outstanding correctness findings."
      },
      "agentCredits": 30,
      "agentCreditsBilled": true,
      "pullRequestRunCount": "2"
    },
    {
      "repositoryId": "123456789",
      "repositoryOwner": "acme",
      "repositoryName": "backend",
      "pullRequestNumber": "41",
      "githubUrl": "https://github.com/acme/backend/pull/41",
      "authorLogin": "example-developer",
      "branch": "bump-dependencies",
      "commitSha": "89abcdef0123456789abcdef0123456789abcdef",
      "outcome": "RUN_COMPLETED",
      "verdict": "APPROVED",
      "startTime": "2026-09-30T16:40:03Z",
      "recordTime": "2026-09-30T16:41:10Z",
      "eligibility": {
        "passed": true,
        "reason": "Every changed path matches the repository's routine paths."
      },
      "correctness": {
        "passed": true
      },
      "customEligibilityPolicy": true,
      "customEligibilityPolicyFrontMatter": true,
      "agentCredits": 0,
      "agentCreditsBilled": true,
      "pullRequestRunCount": "1"
    }
  ],
  "nextPageToken": "opaque-continuation-token"
}
```

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


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