> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudcruise.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Run Statuses

> The statuses a run can report, which are final, and how to consume them from the API, webhooks, and SDKs

Every run has a single `status`. It is the same value whether you read it from the [Run API](/run-api/retrieve-run-results), a [webhook](/concepts/webhooks), 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](/run-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`](/concepts/workflow-dsl/workflow-settings#maximum-error-recovery-attempts), 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

<Steps>
  <Step title="Prefer webhooks or the SDK stream over polling">
    Webhooks and the [SDK](/sdk/js/overview) 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](/run-api/retrieve-run-results). See [Rate limits](/concepts/rate-limits).
  </Step>

  <Step title="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`.
  </Step>

  <Step title="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.
  </Step>
</Steps>

```ts theme={null}
const FINAL = new Set([
  "execution.success",
  "execution.failed",
  "execution.stopped",
])

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

## Related

* [Webhooks](/concepts/webhooks)
* [Workflow settings: retry behavior](/concepts/workflow-dsl/workflow-settings#retry-settings)
* [Service unavailable recovery](/concepts/maintenance-agent#service-and-logged-out-session-recovery)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.