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

# Lifecycle

> Workflow states in the dashboard and API

A workflow defines what to collect and when. Each execution is a run. Kadoa tracks workflow, run, Assistant, and support states separately.

## States

These diagrams show the common transitions.

### Workflow

```mermaid actions={false} theme={null}
flowchart LR
    A[Setup] --> B[Preview]
    B -->|Approve| C[Active]
    C -->|Pause| D[Paused]
    D -->|Resume| C
```

Active workflows run once, on a schedule, or continuously. An active workflow can be waiting between runs.

### Run

```mermaid actions={false} theme={null}
%%{init: {"flowchart": {"nodeSpacing": 20, "rankSpacing": 45}}}%%
flowchart TB
    A[Running] -->|Hold| B[Verifying data]
    B -->|Release| A
    A --> C[Finished]
    A --> D[Failed]
    A --> E[Stopped]
```

Kadoa combines [data quality checks](/docs/data-quality) with agent review. Runs that meet the approval requirements pass automatically. Unresolved issues or required human checks go to a Kadoa reviewer before delivery. Previous results stay visible.

### Assistant activity

```mermaid actions={false} theme={null}
flowchart LR
    A[Assistant working] -->|Finish| B[Idle]
    B -->|Request| A
    B -->|Repair| C[Repairing]
    C -->|Finish| B
```

When the Assistant needs input, it is idle and shows **Reply needed**. Repairs appear as **Updating** in the UI.

### Support

```mermaid actions={false} theme={null}
flowchart LR
    A[No open cases] -->|Open case| B[In support]
    B -->|Close last case| A
```

Support is independent of the other states. An open case does not mean a repair is running.

## UI states

Badges show each state separately. For example, **Preview + Updating + In support** means a preview is being updated and a support case is open.

| Badge                  | Meaning                                                                                                                       |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| Setup                  | Kadoa is preparing the workflow.                                                                                              |
| Assistant working      | The Assistant is handling your request.                                                                                       |
| Preview ready          | Review and approve, or request changes.                                                                                       |
| Preview                | Preview data exists, but approval is currently unavailable. The banner explains why.                                          |
| Running                | Collecting data or monitoring continuously.                                                                                   |
| Verifying data         | Delivery is on hold for [Kadoa review](/docs/ui/workflows/human-in-the-loop#data-verification). No review is needed from you. |
| Updating               | Kadoa is changing or repairing the workflow.                                                                                  |
| Reply needed           | Answer the Assistant's question.                                                                                              |
| Scheduled              | Waiting for the next run.                                                                                                     |
| Complete               | Finished, with no further runs scheduled.                                                                                     |
| Paused                 | Scheduled runs are paused.                                                                                                    |
| Failed / Update failed | The latest attempt failed. Check run details.                                                                                 |
| In support             | At least one support case is open.                                                                                            |

Previous data stays visible during updates and after failures. The banner explains the current activity or action needed.

## API states

Use `presentation` to display states and `availableActions` to enable controls. List and detail responses include:

| Field                              | Meaning                                                                    |
| ---------------------------------- | -------------------------------------------------------------------------- |
| `state`                            | Workflow lifecycle, such as `PREVIEW`, `ACTIVE`, or `PAUSED`.              |
| `runState` / `execution`           | Latest run state, progress, and preview availability.                      |
| `workspaceActivity`                | `idle`, `assistant`, or `repair`.                                          |
| `assistantState` / `sessionStatus` | Assistant conversation state.                                              |
| `awaitingUserInput`                | The Assistant needs your reply.                                            |
| `inSupport`                        | At least one support case is open.                                         |
| `presentation`                     | Banner status, badges, and dashboard group.                                |
| `availableActions`                 | Each action's `allowed` flag and a `reason` when blocked.                  |
| `publishedJobId` / `jobId`         | Run supplying displayed data / latest run. These can differ.               |
| `dataStale`                        | Batch Assistant data no longer matches the current configuration or build. |
| `displayState`                     | Combined workflow and run state, used for filtering.                       |

A preview being updated returns:

```json theme={null}
{
  "state": "PREVIEW",
  "displayState": "PREVIEW",
  "workspaceActivity": "assistant",
  "presentation": {
    "status": "UPDATING",
    "badges": [
      { "kind": "lifecycle", "status": "PREVIEW" },
      { "kind": "activity", "status": "UPDATING" }
    ],
    "group": "working"
  },
  "availableActions": {
    "approve": { "allowed": false, "reason": "ASSISTANT_ACTIVE" }
  }
}
```

The API rechecks permissions and state when you submit an action.

Outdated batch Assistant previews block approval with reason `PREVIEW_OUT_OF_DATE`. Approval requests return HTTP 409 until Kadoa refreshes the preview.

## Filtering workflows

Filter by dashboard group, `displayState`, or lifecycle `state`:

```bash theme={null}
GET /v4/workflows?statusFilters=group:attention
GET /v4/workflows?statusFilters=group:attention,group:failed
GET /v4/workflows?displayState=RUNNING
```

Groups are `attention`, `working`, `support`, `failed`, `active`, `complete`, and `paused`. Open support cases always place workflows in `support`.

You cannot filter by `presentation.status`.