Merge Queue

Control merge queue state — pause, unpause, and inspect status.

Get the current status of the merge queue

GET /repos/{owner}/{repository}/merge-queue/status

Get the current status of the speculative checks, batches, and queued pull requests in the merge queue

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

The owner of the repository

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

repository string required

The name of the repository

min length: 1 · pattern: ^[\w\-\.]+$

Query Parameters
branch string

The name of the branch

Responses
200 Successful Response
batchesMergeQueueStatusBatchWithSubBatch[]required
namestringrequired
statusBatchStatusrequired
code"running" | "bisecting" | "preparing" | "failed" | "merged" | "waiting_for_merge" | "waiting_for_previous_batches" | "waiting_for_requeue" | "waiting_schedule" | "waiting_for_batch" | "frozen"required
Enum: running bisecting preparing failed merged waiting_for_merge waiting_for_previous_batches waiting_for_requeue waiting_schedule waiting_for_batch frozen
batch_filled_slotsinteger | null
max_batch_slotsinteger | null
batch_max_start_atstring <date-time> | null
started_atstring <date-time> | nullrequired
estimated_merge_atstring <date-time> | nullrequired
scopesstring[]required
checks_summaryBatchChecksSummaryrequired
passedintegerrequired
totalintegerrequired
pull_requestsMergeQueueStatusPullRequest[]required
numberintegerrequired
min: 0
titlestringrequired
urlstringrequired
authorPullRequestAuthorrequired
idintegerrequired
loginstringrequired
queued_atstring <date-time>required
priority_aliasstringrequired
priority_rule_namestringrequired
labelsstring[]required
scopesstring[]required
github_labelsPullRequestLabel[] | null
idintegerrequired
namestringrequired
colorstringrequired
defaultbooleanrequired
estimated_merge_atstring <date-time> | null
sub_batchesMergeQueueStatusBatchBase[] | null
namestringrequired
statusBatchStatusrequired
code"running" | "bisecting" | "preparing" | "failed" | "merged" | "waiting_for_merge" | "waiting_for_previous_batches" | "waiting_for_requeue" | "waiting_schedule" | "waiting_for_batch" | "frozen"required
Enum: running bisecting preparing failed merged waiting_for_merge waiting_for_previous_batches waiting_for_requeue waiting_schedule waiting_for_batch frozen
batch_filled_slotsinteger | null
max_batch_slotsinteger | null
batch_max_start_atstring <date-time> | null
started_atstring <date-time> | nullrequired
estimated_merge_atstring <date-time> | nullrequired
scopesstring[]required
checks_summaryBatchChecksSummaryrequired
passedintegerrequired
totalintegerrequired
pull_requestsMergeQueueStatusPullRequest[]required
numberintegerrequired
min: 0
titlestringrequired
urlstringrequired
authorPullRequestAuthorrequired
idintegerrequired
loginstringrequired
queued_atstring <date-time>required
priority_aliasstringrequired
priority_rule_namestringrequired
labelsstring[]required
scopesstring[]required
github_labelsPullRequestLabel[] | null
idintegerrequired
namestringrequired
colorstringrequired
defaultbooleanrequired
estimated_merge_atstring <date-time> | null
waiting_pull_requestsMergeQueueStatusPullRequest[]required
numberintegerrequired
min: 0
titlestringrequired
urlstringrequired
authorPullRequestAuthorrequired
idintegerrequired
loginstringrequired
queued_atstring <date-time>required
priority_aliasstringrequired
priority_rule_namestringrequired
labelsstring[]required
scopesstring[]required
github_labelsPullRequestLabel[] | null
idintegerrequired
namestringrequired
colorstringrequired
defaultbooleanrequired
estimated_merge_atstring <date-time> | null
Example Response 

                          {
  "batches": [
    {
      "name": "Batch 1",
      "status": {
        "code": "running"
      },
      "started_at": "2025-11-05T14:05:00Z",
      "estimated_merge_at": "2025-11-05T14:35:00Z",
      "scopes": [
        "frontend",
        "backend"
      ],
      "checks_summary": {
        "passed": 45,
        "total": 67
      },
      "pull_requests": [
        {
          "number": 1421,
          "title": "feat(auth): add \"Reset Password\" flow to login UI",
          "url": "https://github.com/org/repo/pull/1421",
          "author": {
            "id": 123,
            "login": "james"
          },
          "queued_at": "2025-11-05T13:30:00Z",
          "priority_alias": "high",
          "priority_rule_name": "hotfix",
          "labels": [
            "feature",
            "auth"
          ],
          "github_labels": [
            {
              "id": 1,
              "name": "feature",
              "color": "0e8a16",
              "default": false
            },
            {
              "id": 2,
              "name": "auth",
              "color": "1d76db",
              "default": false
            }
          ],
          "scopes": [
            "frontend"
          ]
        }
      ]
    },
    {
      "name": "Batch 2",
      "status": {
        "code": "bisecting"
      },
      "started_at": "2025-11-05T13:35:00Z",
      "estimated_merge_at": "2025-11-05T15:35:00Z",
      "scopes": [
        "frontend"
      ],
      "checks_summary": {
        "passed": 15,
        "total": 28
      },
      "sub_batches": [
        {
          "name": "Sub Batch 1",
          "status": {
            "code": "merged"
          },
          "started_at": "2025-11-05T13:40:00Z",
          "estimated_merge_at": "2025-11-05T13:50:00Z",
          "scopes": [
            "frontend"
          ],
          "checks_summary": {
            "passed": 15,
            "total": 15
          },
          "pull_requests": []
        },
        {
          "name": "Sub Batch 2",
          "status": {
            "code": "running"
          },
          "started_at": "2025-11-05T13:50:00Z",
          "estimated_merge_at": "2025-11-05T14:00:00Z",
          "scopes": [
            "frontend"
          ],
          "checks_summary": {
            "passed": 0,
            "total": 13
          },
          "pull_requests": []
        }
      ],
      "pull_requests": []
    }
  ],
  "waiting_pull_requests": []
}
403 Forbidden
404 Not found
409 Conflict
422 Unprocessable entity
Example Request 
curl -X GET "https://api.mergify.com/v1/repos/:owner/:repository/merge-queue/status" \
  -H "Authorization: Bearer <token>"

Pause the merge queue

PUT /repos/{owner}/{repository}/merge-queue/pause

Pause the merge of the requested repository

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

The owner of the repository

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

repository string required

The name of the repository

min length: 1 · pattern: ^[\w\-\.]+$

Request Body
reasonstringrequired

The reason of the merge queue pause

max length: 255
Responses
200 Successful Response
reasonstringrequired

The reason of the merge queue pause

max length: 255
paused_atstring <date-time>required

The date and time when the merge queue was paused

Example Response 

                          {
  "reason": "string",
  "paused_at": "2024-01-15T09:00:00Z"
}
403 Forbidden
404 Not found
409 Conflict
422 Unprocessable entity
Example Request 
curl -X PUT "https://api.mergify.com/v1/repos/:owner/:repository/merge-queue/pause" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "string"
}'

Unpause merge queue

DELETE /repos/{owner}/{repository}/merge-queue/pause

Unpause the merge queue of the requested repository

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

The owner of the repository

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

repository string required

The name of the repository

min length: 1 · pattern: ^[\w\-\.]+$

Responses
204 Successful Response
403 Forbidden
404 The merge queue is not currently paused on this repository
409 Conflict
422 Unprocessable entity
Example Request 
curl -X DELETE "https://api.mergify.com/v1/repos/:owner/:repository/merge-queue/pause" \
  -H "Authorization: Bearer <token>"

Get merge queue pause data

GET /repos/{owner}/{repository}/merge-queue/pause

Checks if the merge queue is paused and returns the pause data

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

The owner of the repository

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

repository string required

The name of the repository

min length: 1 · pattern: ^[\w\-\.]+$

Responses
200 Successful Response
reasonstringrequired

The reason of the merge queue pause

max length: 255
paused_atstring <date-time>required

The date and time when the merge queue was paused

Example Response 

                          {
  "reason": "string",
  "paused_at": "2024-01-15T09:00:00Z"
}
403 Forbidden
404 The merge queue is not currently paused on this repository
409 Conflict
422 Unprocessable entity
Example Request 
curl -X GET "https://api.mergify.com/v1/repos/:owner/:repository/merge-queue/pause" \
  -H "Authorization: Bearer <token>"

Was this page helpful?