Run Statuses

Every run has a single status. It is the same value whether you read it from the Run API, a webhook, the SDKs, or the CLI.

Final and non-final statuses

Only three statuses are final. Once a run reports one of them, it does not change on its own. The one exception is a manual re-run of the same session by CloudCruise support, which moves it back to execution.requeued.

Status	Final	Meaning
`execution.success`	Yes	The workflow reached its End node and completed.
`execution.failed`	Yes	The run failed and will not be retried: the error could not be recovered, the retry limit was used up, retries are disabled for the failure, or the run could not be restarted.
`execution.stopped`	Yes	The run was interrupted by a user or the API (Interrupt Run).
`execution.queued`	No	Accepted and waiting for a worker.
`execution.paused`	No	Held before execution by a workflow-level or credential-level pause. It resumes when the pause is lifted.
`execution.start`	No	A worker is executing the run.
`execution.requeued`	No	The run hit a recoverable failure and was scheduled for another attempt. It will return to `execution.start`.

Some webhook events describe progress and are not statuses: execution.step, execution.input_required and execution.password_updated. A run that has sent one of them is not final. execution.input_required means the run is waiting for corrected input. The event’s timeout_seconds field is how long the server waits. The wait also ends when that time runs out, when the run is interrupted, or when the server hits an error, so stop showing an input prompt once the run reports a different status. If a stop request arrives for a run that has already failed, the run reports execution.failed.

Lifecycle

queued ──> start ──> success
  ^          │
  │          ├──> stopped
  │          │
  │          ├──> failed          (final: not retried)
  │          │
  └─ requeued <─┘                 (non-final: retry scheduled)

paused ──> queued                 (when the pause is lifted)

A run can go through start → requeued → start several times. The number of automatic retries is capped by the workflow’s max_retries, and each retry waits longer than the last.

What to expect

A run that is going to be retried never reports execution.failed. When an attempt fails and a retry is scheduled, the status goes straight from execution.start to execution.requeued.
execution.failed is reported once, and only when the run is final. Its webhook is sent at that point and not for intermediate attempts.
execution.requeued is not a failure result. Treat it as “still in progress, retrying”. The webhook payload carries retry_attempt, max_retries and next_execution_time.
A requeued run can end in any final status. After one or more execution.requeued events the run may finish as execution.success, execution.failed (retries exhausted) or execution.stopped.
Statuses follow the lifecycle above. A final status is not replaced by another status unless CloudCruise support manually re-runs the session.

What is not expected

If you see any of these, it is a bug in CloudCruise. Report it with the session_id.

A run reads execution.failed and later reads execution.requeued, execution.start, or execution.success, with no manual re-run from CloudCruise support.
An execution.failed webhook for a run that was then retried.
A final status that changes to a different final status without a manual re-run by CloudCruise support.

Consuming statuses

Prefer webhooks or the SDK stream over polling

Webhooks and the SDK server-sent events deliver most status changes as they happen, but not every one: pausing or unpausing a queued run changes the status without sending an event. If you need the current status, read it from the Run API. See Rate limits.

If you poll, stop only on a final status

Keep polling while the status is execution.queued, execution.paused, execution.start or execution.requeued. Stop when it is execution.success, execution.failed or execution.stopped.

Allow for long gaps while requeued

A requeued run waits before its next attempt, and the wait grows with each retry. Do not apply a short overall timeout to runs on workflows with retries enabled.

const FINAL = new Set([
  "execution.success",
  "execution.failed",
  "execution.stopped",
])

const isFinal = (status: string) => FINAL.has(status)

Getting Started

Concepts

API Reference

SDK

Integrations

Final and non-final statuses

Lifecycle

What to expect

What is not expected

Consuming statuses

​Final and non-final statuses

​Lifecycle

​What to expect

​What is not expected

​Consuming statuses

​Related

Final and non-final statuses

Lifecycle

What to expect

What is not expected

Consuming statuses

Related