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:

{
  "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:

# 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