for agents: this page is markdown at https://switchyard.so/docs/queue-health.md; every page is listed in llms.txt.
Read the merge queue's health
Read, in one answer, whether the merge queue is merging, how long a task takes from submit to merged, what waits, and whether a person has to do something.
You will have: the merge queue's state in a word, one sentence that says it, and the one thing that needs a person when there is one. Works with: the board, yard, MCP (yard_queue_health), REST. Any key of the project reads it, and reading it changes nothing.
What one read answers
Switchyard works the answer out from the project's own history, over a window: the newest 200 decisions, none older than 24 hours. A decision is a task merged or a task sent back. Every reader of a project gets the same answer.
The answer carries:
stateandlevel: the state in a word, and how serious it is (green,amber,red, ornonewhere nothing is judged).sentence: one sentence that Switchyard writes. The board,yardand MCP show it unchanged.needsPerson: at most one thing that a person has to do, ornull.submitToMerged: how long merged tasks took from their submit to their merge, as a typical value (the median) and a high value.sentBack: how many of the window's decisions were tasks sent back, and why, by cause.waiting: how many tasks wait in the merge queue, how many of them are held, and the oldest.machineWait: how long finished tests waited for a free check machine.merging: whether merging is paused, held, frozen or not moving, and when a task last merged.lanes: the same numbers for each merge lane, always in the merge queue's order:hotfix,priority,normal. A lane with no task is listed too.limits: the thresholds each level was judged by.notKnown: the fields Switchyard's records cannot give. A field listed there is not known. It is never zero.
The REST API page has the route, and the OpenAPI document has every field.
Read it on the board
Open the project's merge queue page. A strip under the page's title shows the state as a mark and a word, Switchyard's sentence, and four numbers: submit to merged, sent back, waiting, and check machines. A quiet merge queue, where each of the four would read none, shows the sentence alone; a number that is not known always keeps its place.
The strip is one button. A click, Enter or Space opens the numbers in full below it: the window, each number with its counts, what merging is doing, a row for each lane, what each level means, and a list headed not known from the records. Escape or close closes it.
When something needs a person, a line headed needs a person under the strip shows Switchyard's sentence, a link to the place that shows it, and the command to copy when there is one. On app.switchyard.so, the link for a spending limit or a card opens the organization's billing page.
The project's overview shows the state and the sentence on one line in its merge queue box.
Read it from the terminal
In a clone of the project, run:
yard queue health
Output
merge queue: healthy
14 tasks are in the merge queue; submit to merged is typically 1m 36s.
needs a person: nothing
submit to merged typical 1m 36s · 99th percentile 4m 11s healthy
193 tasks merged since 10:26 UTC on 17 November · 6 waited for an approval
sent back 7 of 200 (3.5%) healthy
causes not known
waiting 14 tasks · oldest 44m (task 790)
14 free, oldest 44m (task 790) · 0 held · 6 under test
check machines 22 of 193 finished tests waited · typical 35s · slowest 58s
merging not paused · not held
lane waiting oldest merged typical high
hotfix 0 none not known not known not known
priority 0 none not known not known not known
normal 14 44m not known not known not known
not known, not zero: spending holds in window, lane of merged, send back cause
The first line is the state in a word. The second is Switchyard's sentence. The third is the one thing that needs a person, or nothing. The last line lists what is not known.
When a person has to act, the third line says who, and a fourth gives the command when there is one:
Output
merge queue: held
Nothing merges: the organization is at its spending limit, which an owner, admin or billing member can raise; new work is still taken until 09:00 UTC on 20 November; 3 tasks wait.
needs a person: An owner, admin or billing member of the organization can raise the spending limit.
command: yard org limit
yard queue health --json prints the answer as Switchyard sent it. The exit status is 0 for any state, because a slow merge queue is not a failed command. A script reads state from the JSON.
Read it as an agent or a script
Over MCP, call yard_queue_health. It takes no input and returns the answer unchanged.
Over REST, send a key of the project. A task's key, an agent group key and the project admin key all read it:
curl -sS https://app.switchyard.so/v1/projects/your-project/queue-health \
-H "Authorization: Bearer $SWITCHYARD_TOKEN"
Durations are whole milliseconds, and times are ISO 8601 in UTC. The answer holds no age: work an age out from a time in the answer and your own clock.
The states
The state is the first of these that is true, from top to bottom.
| State | Word on the board and in yard | What it means | What to do |
|---|---|---|---|
frozen | frozen | Nothing merges: main failed its checks after a merge. merging.frozen.since says when | Wait. When Switchyard could not put main right automatically, needsPerson says that a project admin decides what main becomes |
held | held; held, work refused | Nothing merges: the organization is at its spending limit, needs a card on file, or has a payment that failed. While merging.held.state is held, new work is still taken until merging.held.graceEndsAt. Once it is refused, new work is refused | Tell the person that needsPerson names. Do not send a refused submit again in a loop |
paused | paused | A project admin paused merging. merging.paused says who, why and until when. Hotfix tasks still merge | Keep working. With no end set, a project admin runs yard resume |
stalled | not moving | The merge queue has not moved on since merging.stalled.since, and merging.stalled.reason says why | A project admin looks at what holds it on the merge queue page |
quiet | quiet | No task waits, and no task merged or was sent back in the last 24 hours | Nothing |
not_known | not known | The submit time of a merged task in the window can no longer be read, so submit to merged is not known. It is never shown as healthy | Read the other numbers. submitToMerged.submitNotKnown counts the tasks |
too_few | too few to judge | Fewer than 10 tasks merged in the window, so submit to merged gets no level | Nothing. The sentence still gives the typical time when there is one |
slow | slow; very slow | Submit to merged is past a threshold. The sentence names the number that set the level | Read machineWait, window.overlap and lanes for where the time went |
many_sent_back | many sent back; very many sent back | The share of decisions that were tasks sent back is past a threshold | Read sentBack.causes, and fix the cause before you submit more |
healthy | healthy | Submit to merged is judged and within the first threshold, and few tasks are sent back | Nothing |
A state at level red has the stronger word: very slow, very many sent back, or held, work refused. frozen and stalled are always red. paused, quiet, too_few and not_known have the level none.
When submit to merged and the share sent back are both past a threshold, the state is slow and its sentence says both. When the share sent back is at the worse level of the two, the state is many_sent_back.
The answer's limits carries the thresholds, so a client never hard-codes them. Today they are:
| Level | Typical submit to merged | Slowest or 99th percentile | Sent back |
|---|---|---|---|
| healthy | up to 2m | up to 5m | under 5% |
| slow, or many sent back | up to 4m | up to 10m | 5% to 15% |
| very slow, or very many sent back | beyond that | beyond that | over 15% |
Submit to merged is healthy only when both its typical value and its high value are within the healthy threshold.
Small samples
Switchyard does not judge a handful of tasks:
- With fewer than 10 merged tasks in the window, submit to merged has a typical value, no high value and no level. With fewer than 10 decisions, the share sent back has counts, no rate and no level.
- From 10 to 99 merged tasks, the high value is the slowest task (
highisslowest). - The high value is the 99th percentile from 100 merged tasks (
highisp99).
Each lane (hotfix, priority, normal) is judged from its own merged tasks in the same way. Move a task ahead in the merge queue says what each lane does.
What is not known
A number that Switchyard's records cannot give is null, and its code is in notKnown. It is never 0. The board says not known, and yard prints not known and lists the codes on its last line. A null that means "none" has no code: no task waits, or nothing is held.
| Code | What is not known |
|---|---|
under_test | how many waiting tasks are under test |
oldest_free | which is the oldest waiting task that nothing holds |
for_person | how many held tasks wait for a person |
paused_time | how long merging was paused in the window |
spending_holds_in_window | whether a spending limit, a card or a payment held merging in the window, and for how long |
hold_since | since when the hold that runs now has held merging |
waited_for_approval | how many merged tasks waited for an approval |
lane_of_merged | which lane each merged task merged in |
send_back_cause | why the tasks sent back were sent back |
machine_wait | how long finished tests waited for a check machine |
submit_time | when some merged tasks were submitted, and so how long submit to merged took |
oldest_waiting | when the oldest waiting task was submitted |
held_count | how many waiting tasks are held |
A field that is known in part is not null and has no code. sentBack.causeNotKnown counts the tasks sent back with no cause recorded, and laneNotKnown counts the merged tasks with no lane recorded. waitingLaneNotKnown counts the waiting tasks whose lane is not known.
These limits are the ones you are most likely to meet:
- Tasks that wait for a person are not counted. When any waiting task is held,
waiting.forPersonisnullwithfor_person.needsPersonnever names a task that waits for review, so read the review inbox for those. - Holds are known only from when they were recorded. A project records when a hold began and ended, from the moment it first read its organization's state after this feature reached it. While the window reaches back before that moment,
window.overlap.spendingHoldsandspendingHeldMsarenullwithspending_holds_in_window. So a project's first answers can say that the window's holds are not known. They are also not known past 50 hold records in 24 hours. - A hold's time is when the project learned of it.
merging.held.sinceis the time of the project's own record, andmerging.held.sinceBasisislearned. That can be later than the moment the organization reached its limit. For a hold that was already there when the project began to record holds,sinceisnullwithhold_since. - After a rewind, a window that reaches across it is not known. When Switchyard's operators restore a project's history to an earlier moment, the holds of every window that reaches back before the moment the rewind was done are not known. When a hold was running at the rewind, no window's holds are known until the project next reads its organization's state. After a rewind, the window can still count a decision or a pause that the restored history no longer holds.
- An old submit can no longer be read. Switchyard archives old history. A merged task whose submit was archived still counts as merged, and its submit time is
submit_time. Submit to merged then has no typical value and no level, because a number over the other tasks would read better than the truth. - A task's lane is the lane the merge queue is using for it. That is the lane set on the task, or the higher lane it rides because a
[merge_queue] priorityrule names its key or because a task in a higher lane is stacked on it. A waiting task is counted in that lane (lanes[].waitingandoldest), and a merged task is counted in the lane it merged in. When the rule or the stack no longer applies, the task is counted in its lower lane again once the merge queue has next gone through its tasks. - A waiting task's lane can be not known for a short time.
waitingLaneNotKnowncounts the waiting tasks whose lane Switchyard does not know. It is above zero after the merge queue restarts, until it has next gone through its tasks and read the rules. Until then these tasks are inwaiting.countand in no lane. They are never counted innormal, and such a task has nolanewhere the answer names it (waiting.oldest,waiting.oldestFree). A hotfix set on a task is always known. The lanes'waitingandwaitingLaneNotKnownalways add up towaiting.count.yard queue healthprints the count under the lanes aswaiting with no lane known, and the board shows the same row in the numbers in full. - A merged task's lane can be missing from its record. A merged task whose lane Switchyard did not know when it wrote the record is counted in
laneNotKnown, never in a lane. - Records made before a fact was recorded do not carry it. A merged task's lane and a send-back's cause come only from the record's own field. Switchyard never works one out from words or from other records.
The one thing that needs a person
needsPerson is null, or the first of these that applies:
kind | When | place | command |
|---|---|---|---|
frozen | main failed its checks after a merge and could not be put right automatically | merge_queue | none |
held | the organization is at its spending limit, needs a card, or has a payment that failed | spending_limit | yard org limit at the spending limit; yard org card for a card and for a payment that failed |
stalled | the merge queue has not moved on | merge_queue | none |
paused | merging is paused with no end set | merge_queue | yard resume |
Its fields:
sentencesays what is so and who acts. It names no place.whois a role in words, such asa project admin. It is never a person's name.placeis the kind of place that shows it, never an address:merge_queue,overvieworspending_limit. Each client finds its own address for it. A client that does not know a place shows the sentence with no link.commandis theyardcommand that does it, ornull.
The answer carries no amount of money, no person's name from billing and no link that acts. The hold's whole reason, said by role, is in merging.held.reason.
yard org limit and yard org card show a person where the limit and the card stand. Only a person signed in in a browser raises a limit or adds a card. No agent and no key does.
The answer's type also has the kind waiting, with the place overview, for tasks that wait for a person. No answer gives it, because that count is not known (for_person). Pay and set a spending limit has the steps.
How fresh the answer is
- One answer is kept for 5 seconds. Every reader of a project inside that time gets the same answer, and
computedAtsays when it was worked out.seqis the position in the project's history that it was worked out at. - The answer has an
ETag. Send it back inIf-None-Match. A304means that nothing in the answer changed butcomputedAt. - A
503withRetry-Aftermeans that the answer is not ready. For a project that existed before this feature, Switchyard first puts the window's records together, and it answersunavailableuntil they are whole. It never answers from records that are not whole. Wait the seconds thatRetry-Aftergives, then read again. A window too large to read within Switchyard's bound answers the same way. The board says Switchyard is still putting the merge queue's health together for this project meanwhile. - Switchyard sets no polling interval. Asking more often than every 5 seconds returns the same kept answer. The board reads the answer when a page shows it and again when the project's status changes, never on a timer. Do the same: read when you need to decide something, and send
If-None-Matchwhen you read again. The request limits for one key apply.
For agents
Read the merge queue's health before you bring more agents to a project, and when a submit of yours waits longer than you expect.
- Read
state,sentenceandneedsPersonfirst. Passsentenceon unchanged. - When
needsPersonis notnull, tell your person itssentenceand itscommand. Run the command only when your key has the role thatwhonames. An agent never raises a limit or adds a card. - Check
notKnownbefore you use a number. A field listed there is not0. - Then act on the state:
| State | What an agent does |
|---|---|
healthy, quiet, too_few | Submit as usual |
not_known | Submit as usual. Do not report the merge queue as healthy |
slow | Submit as usual, and expect a longer wait. When machineWait shows tests waiting for a check machine, more agents wait for the same machines |
many_sent_back | Read sentBack.causes. Fix that cause in your own task before you submit |
paused | Keep working and submit. Submitted tasks are still tested, and they merge when merging resumes |
held, with merging.held.state held | Keep working. Switchyard takes and keeps new work until merging.held.graceEndsAt. Tell your person |
held, with merging.held.state refused | Stop submitting. Keep your commits in your checkout, tell your person, and read again later. Never retry a refused submit in a loop |
frozen, stalled | Do not start more agents. Tell a project admin, and read again later |
Next
- Write rules and checks: the checks whose time is most of submit to merged.
- Review a change: the tasks that wait for an approval.
- Limits: how many check machines run at once.
- Pay and set a spending limit: what a hold is, and how a person lifts it.
- The yard CLI:
yard queue health. - MCP tools:
yard_queue_health.