Runs
One run of a task, start to finish: what each status means, what you can do with a run, and why one lands on Blockers.
What a run is
A task is a definition, and it never runs. A run is one pass of one version of it: an input, a member doing the work, the tool calls it made, its cost, and how it ended. Runs in the portal lists every run; Executions groups the runs that handed work to each other (see Executions).
A run keeps the version of the task it started on. Publishing a new version while it runs changes nothing for it. A run still waiting its turn has not started, so it starts on whichever version is current then, and its log shows the change.
Statuses
| Status | What it means |
|---|---|
pending |
Waiting for its turn, holding nothing: a start, successor, retry or recovery whose task or member is busy, or a successor with a delay that has not passed. It is queued when the task and member are free. |
queued |
Ready to start. It starts when there is room under your concurrent-run limits. |
running |
The member is working: calling the model and its tools. |
waiting_on_gate |
Stopped before a gated call, or at a question, until you decide. See Gates. |
paused_spend |
Held before it starts because a spend cap was reached. It is queued again when you raise a day cap or turn spend limits off. See Spend and models. |
blocked |
Parked for a reason outside the task, such as a refused credential or a provider outage, or because it needs a person. See Blocked runs. |
succeeded |
Finished. It may have named an outcome. |
failed |
Finished with a failure that belongs to the task, with a reason. |
cancelled |
Stopped: by a person, by a rejected gate, or by a decision that waited too long. |
skipped_overlap |
A scheduled start that found the task busy, or every member holding its role busy. It never ran. It is kept for 24 hours. |
A run at a gate holds neither its task nor its member: while it waits for you, other work can start.
How many run at once
A task has one run under way at a time, and so does a member. A run waiting at a gate does not count.
Across the enterprise, Concurrent runs on Enterprise sets how many runs may be running at once, 1 unless
you change it. A team can have its own, lower limit. A run counts on every team of the member doing it, the teams
they sit on or lead, and starts only when each of them has room. A run over a limit stays queued until a slot frees.
The run page
A run's page shows:
- the task and version it ran (and whether that is still the current version), its execution and the links the work produced, and its cost, top right;
- what came before it and what it hands to next, including successors that are waiting, delayed, or were not started and why;
- its status and how long it ran;
- Run events, newest first: every step, tool call and decision, each with its details. A run that failed, was blocked or was skipped says why at the top;
- any gate waiting on you, with its decision buttons in place.
Show log opens the run's full record. The page updates every few seconds while you are looking at it.
What you can do with a run
| Action | On | What it does |
|---|---|---|
| Cancel | A run that is pending, queued, running, waiting, paused or blocked | Stops it. A gated call it was waiting on never runs, and it starts no successors. |
| Retry as new run | A run that has finished, was skipped, or is blocked | Starts a new run with the same input, on the task's current version, linked to the old one. It starts fresh: it does not carry on the old run's conversation. If the task or member is busy, it waits as pending. A blocked run you retry is cancelled. |
| Clear | A failed run, or a pipeline that stopped, on Blockers | Takes it off Blockers. The run and its history stay on Runs, unchanged. |
Clear all on Blockers clears every failed run in one go. Retry all and Cancel all on its Blocked (resumes automatically) section retry or cancel every run there, each as its own Retry or Cancel would. A run that cannot be retried or cancelled is named with its reason, and the rest still go. Runs under Needs a decision are not touched.
A run cancelled while it waited on a gate or a question leaves a note on Blockers that a decision was stopped, so the work is not silently dropped.
Blocked runs
A failure the task could not have prevented does not fail the run. It blocks it: the run holds nothing, starts no successors, and resumes as a continuation, carrying on the same conversation, when the cause clears.
| Cause | Examples | When it resumes |
|---|---|---|
| Credentials | A model key or tool connection refused or missing; no model connected | As soon as a credential in your enterprise changes, and hourly. With no model connected, as soon as a model connection the run can use is added |
| Provider outage | A timeout, a rate limit, a 5xx from the model or a tool, a tool server that cannot be reached | Automatically after 2, 5, 15 and 30 minutes, or as soon as credentials change. After an hour it stops trying and waits for you |
| Model | The chosen model does not exist or is unavailable | When the model answers again; after an hour it waits for you |
| Capacity | A Claude seat's usage limit is used up | When the limit resets |
| Definition | The task, as written, cannot run | After you edit the task |
| A decision | A loop cap, a question that timed out, a decision that was cancelled | Never by itself: a person retries or cancels it |
On Blockers, Retry starts a new run and Cancel closes the blocked one. When you retry work about an issue or pull request, its loop caps and the number of times tasks may retry it both start again.
A tool call that fails is retried a few times first. What happens then depends on the failure: an outage blocks the run; an error in the call itself (a bad argument, a refusal from the tool) goes back to the model to correct.
Failed runs
A run fails when the failure is the task's own. Some of the reasons you will see:
| Reason | What happened |
|---|---|
run_stalled |
The run recorded nothing for 30 minutes and was stopped. |
llm_max_steps |
The run used every step it is allowed without finishing. See Steps for how many a run gets and how a task asks for more. |
tool_not_on_task |
The model called a tool the task does not list. |
unresolved_tool_errors |
The model finished while a tool call it needed had never gone through, even after one chance to correct it. The reason names the tools, then the first one's error text as the tool gave it. |
A failed run starts its successors on failed and terminal, if the task has any.
Steps
Each model turn of a run is one step. A run that reaches its last step fails with llm_max_steps, even if it has
already done most of its work. How many steps a run gets is the first of these that is set:
- The run's own input
maxSteps. A run it hands work on to is not given it. A task that declares a number inputmaxStepswith a default starts each run with that default. - The operator's
LLM_MAX_STEPSsetting, for every run on the deployment. - The task version's
spend.maxSteps, next to its other spend limits. Set it on the task form, or send it with the version'sspend. It applies to every run of that version, a run started by a handoff included. - The default for the task's tools: 120 steps for a task that works in a repository or drives a browser, 24 for any other task.
No run gets more than 400 steps, whatever is set. A version's spend.maxSteps must be a whole number from 1 to 400:
publishing any other value is refused with spend_max_steps_invalid, and nothing is rounded or capped for you. It can
lower the default as well as raise it. Leave it out to keep the default.
The run is told its step budget beside its spend limit. Once it has used 80% of its steps, it gets one note saying how many it has used and how many are left, so it can finish its handoff and name its outcome before the last step.
When the worker is lost
If the process running a run disappears (a restart, a crash, a deploy), the run is marked failed with the reason
worker_lost and one continuation starts, carrying on the same conversation from its last completed step. Edits
it had not pushed are gone, and a call that was in flight when the worker went may or may not have landed. If the
continuation is lost too, it is blocked, as an outage.
The failure also says why the worker went, in its cause. The reason stays worker_lost whatever the cause, and the
continuation and the block work the same way for each. If the cause cannot be looked up at that moment, the failure
has no cause, and the continuation still starts.
cause |
What happened |
|---|---|
killed |
The worker was told it was being replaced and had started finishing its runs, but it was stopped before this one ended. The failure says when the worker was told and when it was due to be stopped. |
replaced |
A release replaced the worker without warning it first. The failure names the worker and build that took over. |
host_lost |
Nothing recorded explains it: a crash, the machine running out of memory, the machine itself going, or a restart on the same build. |
Blockers
Blockers is the list of what cannot move without someone:
| Section | What is in it |
|---|---|
| No LLM capacity | A model connection with a limit used up: which limit (a rate limit, a spend limit with its period, or a balance) and when it resets, with Raise limit or Add credits. |
| Models unavailable | A model a tier runs that the provider says does not exist, when no other model could be chosen for the tier. |
| Task definitions | Active tasks that will not run cleanly as written. |
| Team health | A team with no lead or an overdue weekly retro, and a KPI someone has to fix: a team with no key KPI, a key KPI with no target, a KPI overdue for a reading, or a proposal waiting on the CEO. A KPI that is only amber or red is not listed here: its light shows on Enterprise in the menu. |
| Needs a decision | Work that stopped for a person: it reached its loop cap, waits on the CEO, or escalated. When a gate holds the decision, Decide opens it. |
| Pipeline stopped | Work whose newest run failed, or ended on an outcome nothing routes, in the last 14 days. |
| Blocked (resumes automatically) | Blocked runs, each with its cause. Most resume by themselves; the table above says which wait for you. Retry all and Cancel all act on every one. |
| Failed | Failed runs nobody has cleared or retried. |
| Stalled | Runs that have recorded nothing for 30 minutes, with Cancel. |
| Paused spend | Runs paused by a spend cap, with Raise cap. |
Each run row names its task and the teammate it worked as (or its team), says what happened in one plain sentence, such as "Keyword research finished, but nothing was set to run next.", and offers the fix as a button: Choose what runs next opens the task, Retry and Cancel act on the run. Open run shows the run itself, with its full reason. An escalated run reads Needs a human decision, with what the open gate asks and Decide, which opens the run that asked, where you answer it. The gate can be one asked about an earlier run of the same issue or PR, since each retry replaces the row.
A failed run leaves Failed when you clear it, or when a retry, recovery or resume starts from it. Gates are not on Blockers; they are on Gates. Self-improvement proposals are not either; they are on Self-Improvement.
Over the API
With an API token:
| Call | Scope | What it does |
|---|---|---|
POST /v1/tasks/{id}/runs |
tasks:write |
Start a run, with its input as the body. The run waits as pending if the task, or every member holding its role, is busy. |
GET /v1/runs |
runs:read |
Runs, filtered by taskId, taskVersionId or status. |
GET /v1/runs/{id} |
runs:read |
One run and its events. |
GET /v1/runs/{id}/log |
runs:read |
Its full log, once stored. |
POST /v1/runs/{id}/retry |
runs:write |
Retry as a new run. |
POST /v1/runs/{id}/cancel |
runs:write |
Cancel it. |
POST /v1/runs/{id}/clear |
runs:write |
Clear it from Blockers. |
GET /v1/blockers |
blockers:read |
Everything on Blockers. |