> ## 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

> Understand workflow status, runs, and when action is needed

A workflow is a saved setup for collecting a dataset. Kadoa's agent creates it from your instructions. You can run it on demand or on a schedule; each execution is a run.

```mermaid actions={false} theme={null}
flowchart TB
    A[Create and set up] --> B[Build and preview]
    B --> C{Approve preview?}
    C -->|Iterate| H[Adjust setup]
    H --> B
    C -->|Approve| D[Active workflow]

    D --> E[Run]
    E --> F{Result}
    F -->|Finished| D
    F -->|Failed| G[Recover or retry]
    G --> E

    D -. Pause .-> P[Paused]
    P -. Resume .-> D
```

A workflow may temporarily need your input, be handled by Kadoa Support, or fail during one of these phases. These conditions tell you who needs to act. They are not additional lifecycle steps.

## Workflow status

The dashboard organizes workflows by who should act and what is happening:

| Category                 | Meaning                                                      |
| ------------------------ | ------------------------------------------------------------ |
| **Needs your attention** | Reply to the Assistant or approve preview data.              |
| **In progress**          | Kadoa is building, running, or reviewing the workflow.       |
| **With support**         | Kadoa Support owns the next action.                          |
| **Failed**               | The latest run or real-time monitor needs recovery.          |
| **Active**               | The workflow is complete, scheduled, or monitoring normally. |
| **Paused**               | Runs are disabled until the workflow is resumed.             |

Within a category, the workflow can show a more specific status such as **Building**, **Running**, **Verifying Data**, **Scheduled**, or **Complete**.

**Verifying Data** means Kadoa is checking the run before delivery. If the checks find a possible data quality issue, a Kadoa operator reviews it. No action is needed from you. Chat input is paused to prevent workflow changes during verification and reopens when it ends.

Use **Needs your attention** as the single action queue for replies and preview approvals. Kadoa removed the separate Inbox because it duplicated the same workflows without their list context.

## Workflow, run, and assistant state

The API exposes several fields because they describe different objects. For most integrations, start with `displayState` and only read the more specific fields when you need them.

| Field               | Use it for                                                                                                                             |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `displayState`      | The best single summary of the workflow's current operational state. Use it for status badges and exact-state filtering.               |
| `awaitingUserInput` | Whether the requesting user must reply. When the Assistant asked an explicit question, `prompt` contains its text.                     |
| `inSupport`         | Whether Kadoa Support owns the next action. This is independent of workflow and run state.                                             |
| `runState`          | Diagnosing the latest execution attempt. Use [workflow history](/api-reference/workflows/get-the-workflow-history) for earlier runs.   |
| `state`             | The persisted state of the long-lived workflow. Use it for lifecycle and control operations, not as a status label.                    |
| `sessionStatus`     | Whether the latest Assistant conversation can accept input. Do not use it to determine workflow progress or whether a reply is needed. |

### Example

```json theme={null}
{
  "state": "SETUP",
  "displayState": "SETUP",
  "runState": "FINISHED",
  "awaitingUserInput": {
    "since": "2026-08-20T08:30:00Z",
    "prompt": "Which country should I scrape?"
  },
  "inSupport": false
}
```

This workflow has not finished setup. Its latest run attempt finished, but the workflow cannot continue until the requesting user answers the Assistant.

## Filtering workflows

Use `statusFilters` to match the same categories as the dashboard:

```bash theme={null}
# Workflows where the requesting user must act
GET /v4/workflows?statusFilters=group:attention

# Workflows that need attention or have failed
GET /v4/workflows?statusFilters=group:attention,group:failed
```

The available category filters are `group:attention`, `group:working`, `group:support`, `group:failed`, `group:active`, and `group:paused`.

Use `displayState` when you need one exact operational state instead:

```bash theme={null}
# Workflows with a run in progress
GET /v4/workflows?displayState=RUNNING

# Workflows whose latest run failed
GET /v4/workflows?displayState=FAILED
```

Use `state` only when you specifically need the persisted workflow state, such as `ACTIVE` or `PAUSED`.