Stacks

Stacks endpoints for the Mergify API.

Get adoption summary metrics for Stacks

GET /repos/{owner}/stacks/summary

Returns counts, score, period delta, sparklines, top authors, and weekly trend for Mergify Stacks across the org's repositories over a time window (default 30 days, max 90).

Authorization (any one of)
GitHub Token Application Key
Path Parameters
owner string required

The owner of the repository

min length: 1 · max length: 40 · pattern: ^[a-zA-Z0-9\-]+$

Query Parameters
days integer

min: 1 · max: 90

Responses
200 Successful Response
active_stacksintegerrequired

Currently open stacks across the org

stack_prs_in_windowintegerrequired

Total PRs that belong to a stack in the window

repos_with_stacks_in_windowintegerrequired

Repositories with at least one stack in the window

percent_merged_from_stacknumberrequired

Percent of merged PRs in the window that came from a stack

weekly_bucketsWeeklyBucket[]required

Weekly counts of new stacks across the window

week_startstring <date>required

Monday of the bucket week (YYYY-MM-DD)

stacks_createdintegerrequired

Number of stacks whose root PR was created this week

scoreAdoptionScoreResponserequired
totalintegerrequired

Composite 0-100

coverageintegerrequired

Coverage component, 0-50

authorsintegerrequired

Authors component, 0-25

reposintegerrequired

Repos component, 0-25

delta_vs_prior_periodPeriodDeltaResponserequired
active_stacksinteger | nullrequired
stack_prsinteger | nullrequired
repos_with_stacksinteger | nullrequired
percent_merged_from_stack_ppnumber | nullrequired

Delta in percentage points (not percent)

score_totalinteger | nullrequired
sparklinesSparklinesResponserequired
active_stacksinteger[]required
stack_prsinteger[]required
repos_with_stacksinteger[]required
percent_merged_from_stacknumber[]required
top_authorsAuthorResponse[]required
loginstringrequired
avatar_urlstring | nullrequired
stack_pr_countintegerrequired
Example Response 

                          {
  "active_stacks": 0,
  "stack_prs_in_window": 0,
  "repos_with_stacks_in_window": 0,
  "percent_merged_from_stack": 0,
  "weekly_buckets": [
    {
      "week_start": "2024-01-15",
      "stacks_created": 0
    }
  ],
  "score": {
    "total": 0,
    "coverage": 0,
    "authors": 0,
    "repos": 0
  },
  "delta_vs_prior_period": {
    "active_stacks": 0,
    "stack_prs": 0,
    "repos_with_stacks": 0,
    "percent_merged_from_stack_pp": 0,
    "score_total": 0
  },
  "sparklines": {
    "active_stacks": [
      0
    ],
    "stack_prs": [
      0
    ],
    "repos_with_stacks": [
      0
    ],
    "percent_merged_from_stack": [
      0
    ]
  },
  "top_authors": [
    {
      "login": "string",
      "avatar_url": "string",
      "stack_pr_count": 0
    }
  ]
}
403 Forbidden
404 Not found
409 Conflict
422 Unprocessable entity
Example Request 
curl -X GET "https://api.mergify.com/v1/repos/:owner/stacks/summary" \
  -H "Authorization: Bearer <token>"

List recent stacks across the org's repositories

GET /repos/{owner}/stacks/recent

Returns clustered stacks for the org over a time window, newest first. Each entry includes the root PR plus all PRs in the stack with links to GitHub.

Authorization (any one of)
GitHub Token Application Key
Path Parameters
owner string required

The owner of the repository

min length: 1 · max length: 40 · pattern: ^[a-zA-Z0-9\-]+$

Query Parameters
repo string[]
days integer

min: 1 · max: 90

per_page integer

min: 1 · max: 100

cursor integer

min: 0

Responses
200 Successful Response
stacksStackResponse[]required
repostringrequired

Repository full name (owner/repo)

root_prStackPRResponserequired
numberintegerrequired
titlestringrequired
statestringrequired
html_urlstringrequired
authorstring | nullrequired
pr_countintegerrequired
statestringrequired

Aggregate stack state: open, merged, or mixed

created_atstring <date-time>required
updated_atstring <date-time>required
prsStackPRResponse[]required
numberintegerrequired
titlestringrequired
statestringrequired
html_urlstringrequired
authorstring | nullrequired
next_cursorinteger | nullrequired

Offset of the next page (pass back as the `cursor` query param); null if there are no more pages.

Example Response 

                          {
  "stacks": [
    {
      "repo": "string",
      "root_pr": {},
      "pr_count": 0,
      "state": "string",
      "created_at": "2024-01-15T09:00:00Z",
      "updated_at": "2024-01-15T09:00:00Z",
      "prs": null
    }
  ],
  "next_cursor": 0
}
403 Forbidden
404 Not found
409 Conflict
422 Unprocessable entity
Example Request 
curl -X GET "https://api.mergify.com/v1/repos/:owner/stacks/recent" \
  -H "Authorization: Bearer <token>"

Compare stack PRs vs non-stack PRs

GET /repos/{owner}/stacks/impact

Returns median time-to-merge, PR size, time-to-first-review, and review-thread count for stack PRs vs all other merged PRs in the window. Bots and Mergify merge-queue PRs are excluded from the 'other' cohort to keep the comparison honest.

Authorization (any one of)
GitHub Token Application Key
Path Parameters
owner string required

The owner of the repository

min length: 1 · max length: 40 · pattern: ^[a-zA-Z0-9\-]+$

Query Parameters
days integer

min: 1 · max: 90

Responses
200 Successful Response
time_to_merge_hoursCohortMedianResponserequired
stacknumber | nullrequired
othernumber | nullrequired
delta_percentnumber | nullrequired

Signed percent. Positive means the stack cohort's median is lower than the other cohort's (the typical 'win' direction for time-to-merge, PR size, first-review, comments).

pr_size_linesCohortMedianResponserequired
stacknumber | nullrequired
othernumber | nullrequired
delta_percentnumber | nullrequired

Signed percent. Positive means the stack cohort's median is lower than the other cohort's (the typical 'win' direction for time-to-merge, PR size, first-review, comments).

time_to_first_review_hoursCohortMedianResponserequired
stacknumber | nullrequired
othernumber | nullrequired
delta_percentnumber | nullrequired

Signed percent. Positive means the stack cohort's median is lower than the other cohort's (the typical 'win' direction for time-to-merge, PR size, first-review, comments).

review_threadsCohortMedianResponserequired
stacknumber | nullrequired
othernumber | nullrequired
delta_percentnumber | nullrequired

Signed percent. Positive means the stack cohort's median is lower than the other cohort's (the typical 'win' direction for time-to-merge, PR size, first-review, comments).

stack_pr_countintegerrequired
other_pr_countintegerrequired
Example Response 

                          {
  "time_to_merge_hours": {
    "stack": 0,
    "other": 0,
    "delta_percent": 0
  },
  "pr_size_lines": {
    "stack": 0,
    "other": 0,
    "delta_percent": 0
  },
  "time_to_first_review_hours": {
    "stack": 0,
    "other": 0,
    "delta_percent": 0
  },
  "review_threads": {
    "stack": 0,
    "other": 0,
    "delta_percent": 0
  },
  "stack_pr_count": 0,
  "other_pr_count": 0
}
403 Forbidden
404 Not found
409 Conflict
422 Unprocessable entity
Example Request 
curl -X GET "https://api.mergify.com/v1/repos/:owner/stacks/impact" \
  -H "Authorization: Bearer <token>"

Was this page helpful?