Lifecycle

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

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

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

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

Foundations

Security & Compliance

Build with UI

Build with Code

Integrations

Workflow status

Workflow, run, and assistant state

Example

Filtering workflows

​Workflow status

​Workflow, run, and assistant state

​Example

​Filtering workflows

Workflow status

Workflow, run, and assistant state

Example

Filtering workflows