Executions
The connected runs of more than one task: one piece of work as it moves from member to member.
What an execution is
A run is one pass of one task. When a task hands its result to another task, and that one to the next, those runs are one execution: the whole piece of work, however many members and teams it crosses.
Runs join an execution only through an explicit link: a handoff to a successor, a retry, a recovery, or a resume. Two runs about the same issue, or at the same time, are not joined unless one led to the other. A run on its own, or a task retrying itself without ever handing off, is a run and not an execution: it is on Runs, not Executions.
An execution keeps one address for good: the run it started at. Any of its runs' addresses also opens it.
The board
Executions in the portal is a board of five lanes, which you can search and filter by team or member:
| Lane | What is in it |
|---|---|
| Backlog | Items on a team's work list that no run has claimed yet, in the list's order, and a parent whose children are all still there. An item still waiting for a person's approval says so. |
| Ready | Queued, about to start. |
| In Progress | Running now. |
| Blocked | Waiting on you (a gate), or paused because a spend cap was reached; or one of its runs is on Blockers, as a failure nobody has cleared, a blocked run, or a pipeline that stopped; or its work is on Waiting: its last run ended without finishing the work, and nothing has picked it up. See Finished work. |
| Complete | Everything else. Its status still says how it ended: succeeded, failed, cancelled, skipped, or stopped. |
An item with no parent is one card for its whole life. It sits in Backlog until a run claims it. From then on it is part of that run's execution card, which moves through the lanes as the execution does; while the run is on no execution yet, the item's own card stands in the run's lane. A parent card follows its children. It is in In Progress when any child is still in progress, even if another child has already finished, and even if that child's run has ended without closing the item. Otherwise it is in Blocked, otherwise Ready when one is queued, otherwise Backlog. It is in Complete only when every child has finished and the parent itself is closed; an open parent whose children have all finished stays where its own state puts it. The children are inside that card, each with its own state and the run holding it, and a child does not also have a card of its own. The parent's stored state is unchanged, and opening the card still counts the children per lane. Once the work is closed, the card is in Complete, and opening it shows the item and its history. An item closed without ever being worked leaves the board; its page and history stay. See the built-in tools for how a task adds, claims and closes items.
An item's own state always has the last word on its lane. A closed item is never in Blocked, even when the run that held it is still on Blockers: it stands on its own in Complete, and the execution stays in Blocked without it. An open item is never in Complete, even when its run has ended: a held item, which waits on someone to release it, is in Blocked, one in progress is in In Progress, and any other is in Backlog. An execution held in Blocked only because its work is on Waiting moves to Complete once every item it holds is closed, and Close completed closes it with the rest.
You shape the list from a card or from the item's page: approve or decline an item a task proposed (declining asks for a reason, which the proposing task can read on the item), move it to the top, up, down or to the bottom, put it on hold and release it, and drop it. A held item is skipped by every run until it is released, and the item moved to the top is the next one a run claims. An item is also held when the pipeline working it stops short (a run failed, was blocked, hit a loop cap or ended on an outcome with nowhere to go): its card names the run and says the pipeline stopped. Retry on Blockers carries the item on, and Clear or Cancel there puts it back on the list, so a stopped pipeline is never picked up again in the same place by itself. Add work item on the board adds one to a team's list, and Approve all on the Backlog lane approves every proposed item shown in one step. Each action is kept in the item's history with the person who took it. Only a person approves a proposed item or releases a held one: a task cannot, so no run claims an item a task proposed until you have approved it.
Grouped
Grouped, beside Board, shows the work lists instead of the lanes: every open item of each team in view (or
of the team you filter to), nested under its parent, such as a campaign or an epic. An item names one parent on the
same team, one level deep, when it is added (the Parent field of Add work item, a task's
os.add_work_item, the API or MCP) or later through os.update_work_item, the API or MCP; an item with no parent
stands at the top level. Each parent starts collapsed and shows how many items sit under it and a count of them per
state, closed ones included, so the count moves as a child closes. Every row shows the item's state and the status
of the run holding it. In progress shows only the items being worked, with the parents that have one opened and
only those children under them; a parent that is itself in progress with none of its children moving is listed
collapsed. The search field narrows the titles the same way. Turning the filter off brings back the parents you had
opened. A child whose parent is closed still shows under it, with the parent marked closed. Board stays the
view the page opens on.
An execution that crosses several teams appears on each of those teams' boards. A failed attempt that a retry then completes does not make the execution fail; a failed or missing handoff stays visible even when another branch finishes. The board and each execution's page update every few seconds while you are looking at them.
One execution
An execution's page shows the task graph it moved through (every successor the tasks are set to hand to, and which ones it took), the run history with each run's member and team, and the current task. Select a task to see its attempts and open any run. Runs' own logs, gates and actions stay on the run's page.
A task can give its execution a name and attach links (the issue, the pull request, the preview) while it runs; they show on the execution and on its runs. Until one does, an execution is named after its first task.
Cancelling and closing
Cancel stops every open run in the execution.
Close takes a finished execution off the board, so the board shows current work. Only an execution in the Complete lane can be closed: anything queued, running, waiting or still on Blockers cannot, so a close never hides work that needs someone. Closing records who and when, changes nothing about the runs, and can be undone with Reopen. If new work joins a closed execution (a retry, a new handoff), it comes back on the board.
Close completed closes every execution in the Complete lane under the current search and team filter, after confirming how many.
Over the API
With an API token scoped executions:read (and executions:write to change them):
| Call | What it does |
|---|---|
GET /v1/executions |
The executions, as a paginated list. Closed ones only with closed=true. |
GET /v1/executions/board |
Every lane in one read, with the same search, team and member filters. items holds the work items by lane: an item with no parent on its own, a parent with its children in In Progress when any child is still in progress, otherwise Blocked, Ready or Backlog, and in Complete only when every child has finished and it is closed. A closed item is never in Blocked and an open one never in Complete. Each execution lists the items it holds under workItems, except a child that is shown inside its parent. |
GET /v1/work-items/{id}, …/history |
One work item, and every change to it, oldest first (teams:read). |
GET /v1/executions/{id} |
One execution: its runs, links and task graph. Any of its run ids works. |
POST /v1/executions/{id}/cancel |
Stop every open run in it. |
POST /v1/executions/{id}/close, …/reopen |
Take a finished execution off the board, or put it back. A refused close is a 409 that says why. |
POST /v1/executions/close-completed |
Close every execution in the Complete lane under the given filters. |
GET /v1/executions/counts |
How many executions and runs are running, queued, waiting (and of those, waiting on a gate) and blocked. |
Responses leave out run inputs, logs and results; read those on the run.