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

# States

> Understand workflow status and lifecycle

## Understanding Workflow Status

When you view a workflow in the dashboard or API, you'll see a **status** that tells you what's happening. This status is computed from two underlying values.

### What You See (displayState)

The status shown in the dashboard:

| Status                | Meaning                                                                                                                   | `displayState`             |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
| **Setup**             | You're still configuring this workflow. Finish setup to start the first run.                                              | `DRAFT`                    |
| **Building**          | Kadoa is generating the scraper code for this workflow. You'll be notified when it's ready.                               | `SETUP`                    |
| **Sample Processing** | Kadoa is generating sample data so you can review what the workflow will extract.                                         | `QUEUED` / `PENDING_START` |
| **Needs Review**      | Sample data is ready. Review and approve it to get the full dataset.                                                      | `PREVIEW`                  |
| **In Kadoa Review**   | Run finished extraction and is being reviewed by our team before the data is delivered. Reviews usually take a few hours. | `VALIDATING`               |
| **Running**           | A job is currently extracting data, or a real-time monitor is collecting data normally.                                   | `RUNNING`                  |
| **Scheduled**         | Last run finished successfully, future runs are scheduled.                                                                | `ACTIVE`                   |
| **Complete**          | Last run finished successfully, no future runs scheduled.                                                                 | `ACTIVE`                   |
| **Paused**            | Workflow is paused.                                                                                                       | `PAUSED`                   |
| **Failed**            | Last run encountered an error.                                                                                            | `FAILED`                   |
| **Degraded**          | (Real-time monitors only) No data received for more than 15 minutes.                                                      | `DEGRADED`                 |

### API Response Fields

The API returns three state-related fields:

```json theme={null}
{
  "state": "ACTIVE",
  "runState": "FINISHED",
  "displayState": "ACTIVE"
}
```

| Field          | Purpose                                     | When to Use                            |
| -------------- | ------------------------------------------- | -------------------------------------- |
| `displayState` | What users see in the dashboard             | **Use this for filtering and display** |
| `state`        | Workflow lifecycle (enabled/paused/deleted) | Admin operations                       |
| `runState`     | Latest job result (running/finished/failed) | Job-level debugging                    |

For workflows still in setup, both `state` and `displayState` are `DRAFT` until the workflow leaves the setup lifecycle.

### Filtering Workflows

When filtering workflows via the API, use the `displayState` parameter:

```bash theme={null}
# Get all completed/scheduled workflows (both show as displayState=ACTIVE)
GET /v4/workflows?displayState=ACTIVE

# Get workflows still in setup
GET /v4/workflows?displayState=DRAFT

# Get workflows being reviewed by our team before delivery ("In Kadoa Review")
GET /v4/workflows?displayState=VALIDATING

# Get failed workflows
GET /v4/workflows?displayState=FAILED

# Get paused workflows
GET /v4/workflows?displayState=PAUSED

# Get workflows pending review
GET /v4/workflows?displayState=PREVIEW

# Get degraded monitors
GET /v4/workflows?displayState=DEGRADED
```