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

# Workflows

> Chain multiple tasks into a single execution with conditions and loops.

<Note>
  Workflows are in preview and not yet available in the product. The API shape is likely to change before launch.
</Note>

Move multi-step orchestration off your server and into Deck. Instead of polling for results, parsing output, deciding what to do next, and firing off another request, define the entire sequence as a workflow. Deck runs it end-to-end with built-in conditions, loops, and failure recovery. No queues to wire. No schedulers to tune.

## How workflows fit in

A workflow is a sequence of [task runs](/concepts/task-runs) that Deck orchestrates for you. Each step references a [task](/concepts/tasks) by `task_id` and accepts `credential_id`, `source_id`, and `input`, the same fields as the task run endpoint. When you run the workflow, you pass these per step, and Deck executes each one as a full task run. A single workflow can pull data from one source and act on it in another.

## Steps

A step is the unit of work inside a workflow. It's either a task invocation or a control-flow primitive. Every step has a unique `name` within its workflow, which is how you reference its output from later steps and target it with run-time values.

Deck executes steps one at a time, top to bottom. Nothing runs in parallel.

All steps in a workflow share a session, so the agent stays logged in across steps and doesn't re-authenticate between them.

A task step runs as a full task run under the hood, so it behaves exactly like `POST /v2/tasks/{task_id}/run` and emits the same [events](/events/events). Any step accepts an optional `if` modifier that skips it when the condition evaluates false.

## Step types

Every step has a `type` discriminator.

| `type`     | What it does                                                          |
| ---------- | --------------------------------------------------------------------- |
| `task`     | Runs a task as a task run, optionally authenticated with a credential |
| `for_each` | Iterates over an array, running the inner step for each item          |

Steps execute in order. Later steps can reference earlier step outputs with `{{ path }}` inside their `input`, so data moves through the workflow without round-trips to your server.

## Workflow run statuses

When you run a workflow, Deck creates a workflow run (`wrun_`) that tracks every step.

| Status      | Meaning                                                                                                               |
| ----------- | --------------------------------------------------------------------------------------------------------------------- |
| `queued`    | Waiting to start                                                                                                      |
| `running`   | Executing a step                                                                                                      |
| `paused`    | The current step is blocked on external input (MFA, review, etc.). The step's own status carries the specific reason. |
| `completed` | All steps finished                                                                                                    |
| `failed`    | A step failed and the workflow stopped                                                                                |
| `canceling` | Cancellation requested, the current step is stopping                                                                  |
| `canceled`  | You canceled the workflow before it completed                                                                         |

## Failure behavior

| Option     | What happens                                                    |
| ---------- | --------------------------------------------------------------- |
| `stop`     | The workflow fails immediately (default)                        |
| `continue` | Skip the failed step and continue. Dependents are also skipped. |
| `retry`    | Retry the failed step before stopping                           |

## When to use workflows

If you're chaining API calls, polling for completion, or writing retry logic on your server, that's a workflow. Define it once, and let Deck handle the rest. If you only need a single task, use the [task run](/concepts/task-runs) endpoint directly.

## Deep dives

<CardGroup cols={2}>
  <Card title="Workflows guide" icon="diagram-project" href="/guides/workflows">
    Full examples with templating, conditions, loops, and failure handling.
  </Card>

  <Card title="Task runs" icon="play" href="/concepts/task-runs">
    The execution primitive that each task step wraps.
  </Card>
</CardGroup>