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, up to a few seconds old. 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.
Authorizations
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 permissions it holds. A new key starts with no permissions: it can read merge queues but change nothing in them, and it cannot get a Dynamic CI plan. Each endpoint that needs a permission names it in its description; the Dynamic CI plan endpoints need Generate Dynamic CI plans.
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}.
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.
queue, graph "queue"
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.
true
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.
10000