Get a merge queue's dispatch order

curl --request GET \
  --url https://api.trunk.io/v2/merge-queues/{id}/order \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.trunk.io/v2/merge-queues/{id}/order', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.trunk.io/v2/merge-queues/{id}/order",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.trunk.io/v2/merge-queues/{id}/order"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.trunk.io/v2/merge-queues/{id}/order")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "mode": "queue",
  "queueState": "running",
  "batchingEnabled": true,
  "isolationResolved": true,
  "hasCycle": false,
  "batches": [
    {
      "verificationRunId": "4f3e2d1c-0b9a-4876-9543-210fedcba987",
      "state": "testing",
      "isBisection": false,
      "pullRequests": [
        {
          "id": "6f1d2c3b-4a59-4e6f-8a7b-9c0d1e2f3a4b",
          "number": 4901,
          "sha": "9c58bf40e5c1a2b3d4e5f60718293a4b5c6d7e8f",
          "title": "Add the widget endpoint",
          "url": "https://github.com/acme/widgets/pull/4901"
        }
      ]
    }
  ],
  "pending": [
    {
      "pullRequest": {
        "id": "6f1d2c3b-4a59-4e6f-8a7b-9c0d1e2f3a4b",
        "number": 4901,
        "sha": "9c58bf40e5c1a2b3d4e5f60718293a4b5c6d7e8f",
        "title": "Add the widget endpoint",
        "url": "https://github.com/acme/widgets/pull/4901"
      },
      "schedulability": "schedulable",
      "directlyAhead": [
        {
          "id": "6f1d2c3b-4a59-4e6f-8a7b-9c0d1e2f3a4b",
          "number": 4901,
          "sha": "9c58bf40e5c1a2b3d4e5f60718293a4b5c6d7e8f",
          "title": "Add the widget endpoint",
          "url": "https://github.com/acme/widgets/pull/4901"
        }
      ],
      "heldBy": [
        {
          "id": "6f1d2c3b-4a59-4e6f-8a7b-9c0d1e2f3a4b",
          "number": 4901,
          "sha": "9c58bf40e5c1a2b3d4e5f60718293a4b5c6d7e8f",
          "title": "Add the widget endpoint",
          "url": "https://github.com/acme/widgets/pull/4901"
        }
      ],
      "predictedBatch": 1
    }
  ],
  "awaitingAdmission": [
    {
      "id": "6f1d2c3b-4a59-4e6f-8a7b-9c0d1e2f3a4b",
      "number": 4901,
      "sha": "9c58bf40e5c1a2b3d4e5f60718293a4b5c6d7e8f",
      "title": "Add the widget endpoint",
      "url": "https://github.com/acme/widgets/pull/4901"
    }
  ],
  "awaitingAdmissionTotal": 0
}

Queue order

Get a merge queue's dispatch order

Returns the queue’s batches with a verification run, what is admitted and waiting in the order the engine will consider it, and what has not been admitted yet.

A batch in batches is not necessarily still testing — one that has passed, is merging, or is holding others back after a failure still has a run and is still listed. Read its state.

The order is one of consideration, not of execution, and array position is not a wait estimate. predictedBatch repeats across every pull request predicted to start testing together, and in graph mode several predicted batches commonly start at once — so the pull requests ahead of yours may all start with it, and may sit on unrelated branches that never block yours. directlyAhead is what actually precedes a pull request; use it rather than counting.

It is a point-in-time prediction. A new submission, a priority change or a failure regroups it, and four things outside this response still gate dispatch: queueState: paused stops it entirely, the queue’s testing-concurrency cap bounds how many start, a batch whose predecessors have no usable test branch is skipped over rather than blocking, and bisections dispatch on their own budget.

Pull requests that are not ready are deliberately absent — they are not admitted, so they hold no position. Read one through GET /v2/pull-requests/{id}.

Unpaginated: the engine caps its own graph, so the admitted set is bounded. awaitingAdmission is not, and is truncated.

GET

merge-queues

{id}

order

Get a merge queue's dispatch order

curl --request GET \
  --url https://api.trunk.io/v2/merge-queues/{id}/order \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.trunk.io/v2/merge-queues/{id}/order', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.trunk.io/v2/merge-queues/{id}/order",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.trunk.io/v2/merge-queues/{id}/order"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.trunk.io/v2/merge-queues/{id}/order")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "mode": "queue",
  "queueState": "running",
  "batchingEnabled": true,
  "isolationResolved": true,
  "hasCycle": false,
  "batches": [
    {
      "verificationRunId": "4f3e2d1c-0b9a-4876-9543-210fedcba987",
      "state": "testing",
      "isBisection": false,
      "pullRequests": [
        {
          "id": "6f1d2c3b-4a59-4e6f-8a7b-9c0d1e2f3a4b",
          "number": 4901,
          "sha": "9c58bf40e5c1a2b3d4e5f60718293a4b5c6d7e8f",
          "title": "Add the widget endpoint",
          "url": "https://github.com/acme/widgets/pull/4901"
        }
      ]
    }
  ],
  "pending": [
    {
      "pullRequest": {
        "id": "6f1d2c3b-4a59-4e6f-8a7b-9c0d1e2f3a4b",
        "number": 4901,
        "sha": "9c58bf40e5c1a2b3d4e5f60718293a4b5c6d7e8f",
        "title": "Add the widget endpoint",
        "url": "https://github.com/acme/widgets/pull/4901"
      },
      "schedulability": "schedulable",
      "directlyAhead": [
        {
          "id": "6f1d2c3b-4a59-4e6f-8a7b-9c0d1e2f3a4b",
          "number": 4901,
          "sha": "9c58bf40e5c1a2b3d4e5f60718293a4b5c6d7e8f",
          "title": "Add the widget endpoint",
          "url": "https://github.com/acme/widgets/pull/4901"
        }
      ],
      "heldBy": [
        {
          "id": "6f1d2c3b-4a59-4e6f-8a7b-9c0d1e2f3a4b",
          "number": 4901,
          "sha": "9c58bf40e5c1a2b3d4e5f60718293a4b5c6d7e8f",
          "title": "Add the widget endpoint",
          "url": "https://github.com/acme/widgets/pull/4901"
        }
      ],
      "predictedBatch": 1
    }
  ],
  "awaitingAdmission": [
    {
      "id": "6f1d2c3b-4a59-4e6f-8a7b-9c0d1e2f3a4b",
      "number": 4901,
      "sha": "9c58bf40e5c1a2b3d4e5f60718293a4b5c6d7e8f",
      "title": "Add the widget endpoint",
      "url": "https://github.com/acme/widgets/pull/4901"
    }
  ],
  "awaitingAdmissionTotal": 0
}

Authorizations

Authorization

string

header

required

An API key, sent as Authorization: Bearer <key>. An organization admin creates one in the Trunk app under Settings → Developer → API Keys and chooses the merge-queue permissions it holds; a key with none can read merge queues but change nothing. Those permissions scope merge queue only: every key can use the Flaky Tests and Dynamic CI endpoints, including their writes, whatever permissions it holds.

Path Parameters

string

required

The merge queue's id.

Example:

"xK9mP2nQ"

Response

The queue's dispatch order

The queue's dispatch order: what is testing, what is admitted and waiting, and what has not been admitted. Pull requests that are not ready are deliberately absent — they hold no position — and are readable through GET /v2/pull-requests/{id}.

mode

enum<string>

required

The engine a queue runs. queue tests entries in strict arrival order, one line. graph builds a dependency graph and may test entries speculatively in parallel, which merges faster but can require bisection to attribute a failure. Changing mode is a real conversion, not a flag flip — see mergeQueues.switchModes.

Available options:

queue,

graph

Example:

"queue"

queueState

enum<string>

required

The queue's lifecycle state. switchingModes is a transient conversion state during which config and mode writes are refused.

Available options:

running,

paused,

draining,

switchingModes

Example:

"running"

batchingEnabled

boolean

required

Batching is configured. When false every pull request forms its own predicted batch, and directlyAhead is empty throughout.

Example:

true

isolationResolved

boolean

required

False when an ISOLATE batching rule could apply to this queue. Resolving those costs one impacted-target lookup per pull request, so this read skips it — which can move an isolated pull request into an earlier predicted batch, and so earlier in pending, than the engine will actually consider it.

Example:

true

hasCycle

boolean

required

The queue's graph has a cycle and the engine fell back to a degraded ordering. directlyAhead and heldBy are empty, and a held pull request reports as schedulable.

Example:

false

batches

object[]

required

Batches that have a verification run, in dependency order — a batch appears after the batches it builds on, with bisections last. Not start order, and not all of them are still testing: read each batch's state.

Maximum array length: 10000

Show child attributes

pending

object[]

required

Admitted pull requests, in the order the engine will consider them; held ones come after schedulable ones. A schedulable entry's index is the number of admitted, schedulable pull requests the engine will consider before it — with batching off that is exactly the index — but that is not a wait: see predictedBatch.

Maximum array length: 10000

Show child attributes

awaitingAdmission

object[]

required

Pull requests past the engine's graph soft cap, which hold no position yet. Ordered by a DIFFERENT comparator than pending, so the two lists are not one sequence, and truncated — see awaitingAdmissionTotal.

Maximum array length: 10000

Show child attributes

awaitingAdmissionTotal

integer

required

How many are awaiting admission in total. The engine truncates the list, so compare this with awaitingAdmission.length to detect it; read a specific pull request through GET /v2/pull-requests/{id} rather than scanning.

Example:

0