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
idstring <uuid>required
namestringrequired
parent_idsstring <uuid>[]required
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 · max: 9223372036854776000
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
idstring <uuid>required
namestringrequired
parent_idsstring <uuid>[]required
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 · max: 9223372036854776000
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 · max: 9223372036854776000
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
scope_queuesobject
Example Response 

                          {
  "scope_queues": {
    "__default__": [
      "550e8400-e29b-41d4-a716-446655440001",
      "550e8400-e29b-41d4-a716-446655440002"
    ]
  },
  "batches": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "parent_ids": [],
      "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"
          ]
        }
      ]
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440002",
      "parent_ids": [
        "550e8400-e29b-41d4-a716-446655440001"
      ],
      "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": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440003",
          "parent_ids": [],
          "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": []
        },
        {
          "id": "550e8400-e29b-41d4-a716-446655440004",
          "parent_ids": [],
          "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>"

Get a pull request in the merge queue

GET /repos/{owner}/{repository}/merge-queue/pull/{pr_number}

Get details about a specific pull request in the merge queue

Authorization (any one of)
Application Key GitHub Token
Path Parameters
pr_number integer required

The pull request number

min: 0 · max: 9223372036854776000

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
numberintegerrequired

The number of the pull request

min: 0 · max: 9223372036854776000
queued_atstring <date-time>required

The timestamp when the pull request entered the queue

estimated_time_of_mergestring <date-time> | nullrequired

The estimated timestamp when this pull request will be merged

positionintegerrequired

The position of the pull request in the queue (0-indexed)

priority_rule_namestringrequired

The name of the priority rule applied to this pull request

queue_rule_namestringrequired

The name of the queue rule

checks_timeout_atstring <date-time> | nullrequired

The timestamp when the checks will timeout for this pull request

queue_ruleQueueRulerequired

The queue rule associated to this pull request

namestringrequired

The name of the queue rule

configobjectrequired

The configuration of the queue rule

mergeability_checkMergeQueueMergeabilityCheck | nullrequired

The current state of the mergeability check

check_type"in_place" | "draft_pr"required

The type of queue check (in_place or draft_pr)

Enum: in_place draft_pr
queue_pull_request_numberintegerrequired

The number of the pull request used by the speculative check

min: 0 · max: 9223372036854776000
started_atstring <date-time> | nullrequired

The timestamp when the checks started for this pull request

ci_ended_atstring <date-time> | nullrequired

The timestamp when the CI ended for this pull request

ci_state"pending" | "success" | "failed"required

The combined state of the CI checks

Enum: pending success failed
statestringrequired

The overall queue check conclusion

checksQueueCheck[]required

The list of pull request checks

namestringrequired

Check name

descriptionstringrequired

Check description

urlstring | nullrequired

Check detail url

state"failure" | "error" | "cancelled" | "action_required" | "timed_out" | "pending" | "neutral" | "skipped" | "stale" | "success"required

Check state

Enum: failure error cancelled action_required timed_out pending neutral skipped stale success
avatar_urlstring | nullrequired

Check avatar_url

conditions_evaluationQueueConditionEvaluationJsonSerialized | nullrequired

The queue rule conditions evaluation

matchbooleanrequired
labelstringrequired
descriptionstring | nullrequired
scheduleScheduleJSON | nullrequired
timezonestringrequired
daysobjectrequired
subconditionsQueueConditionEvaluationJsonSerialized[]required
matchbooleanrequired
labelstringrequired
descriptionstring | nullrequired
scheduleScheduleJSON | nullrequired
timezonestringrequired
daysobjectrequired
subconditionsQueueConditionEvaluationJsonSerialized[]required
QueueConditionEvaluationJsonSerialized (circular)
evaluationsEvaluation[]required
pull_requestintegerrequired
min: 0 · max: 9223372036854776000
matchbooleanrequired
evaluation_errorstring | nullrequired
related_checksstring[]required
next_evaluation_atstring <date-time> | nullrequired
evaluationsEvaluation[]required
pull_requestintegerrequired
min: 0 · max: 9223372036854776000
matchbooleanrequired
evaluation_errorstring | nullrequired
related_checksstring[]required
next_evaluation_atstring <date-time> | nullrequired
Example Response 

                          {
  "number": 0,
  "queued_at": "2024-01-15T09:00:00Z",
  "estimated_time_of_merge": "2024-01-15T09:00:00Z",
  "position": 0,
  "priority_rule_name": "string",
  "queue_rule_name": "string",
  "checks_timeout_at": "2024-01-15T09:00:00Z",
  "queue_rule": {
    "name": "string",
    "config": {}
  },
  "mergeability_check": {
    "check_type": "in_place",
    "queue_pull_request_number": 0,
    "started_at": "2024-01-15T09:00:00Z",
    "ci_ended_at": "2024-01-15T09:00:00Z",
    "ci_state": "pending",
    "state": "string",
    "checks": [
      {}
    ],
    "conditions_evaluation": {
      "match": true,
      "label": "string",
      "description": "string",
      "schedule": {},
      "subconditions": null,
      "evaluations": null
    }
  }
}
403 Forbidden
404 The pull request is not found in any merge queue.
409 Conflict
422 Unprocessable entity
Example Request 
curl -X GET "https://api.mergify.com/v1/repos/:owner/:repository/merge-queue/pull/:pr_number" \
  -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?