--- title: "Get a list of workflows" method: GET path: "/v4/workflows" tags: ["Workflows"] --- # Get a list of workflows `GET /v4/workflows` ## Request - Base URL: `https://api.kadoa.com` - URL: `https://api.kadoa.com/v4/workflows` - Auth: API key in header `x-api-key` Retrieves a list of workflows with pagination and search capabilities ## Query parameters - `search` string - `skip` integer - `limit` integer - `state` 'ACTIVE' | 'DRAFT' | 'PAUSED' | 'PREVIEW' | 'QUEUED' | 'SETUP' | 'COMPLIANCE_REVIEW' | 'COMPLIANCE_REJECTED' | 'NOT_SUPPORTED' | 'ERROR' | 'DELETED' - `runState` 'FAILED' | 'FINISHED' | 'RUNNING' | 'STOPPED' - `displayState` 'ACTIVE' | 'DRAFT' | 'PAUSED' | 'PREVIEW' | 'FAILED' | 'RUNNING' | 'VALIDATING' | 'PENDING_START' | 'COMPLIANCE_REVIEW' | 'COMPLIANCE_REJECTED' - `inSupport` string - `tags` string[] - `statusFilters` string[] - `view` 'dashboard' - `groupWindows` string - `userId` string[] - `channelId` string[] - `monitoring` 'true' | 'false' - `updateInterval` 'HOURLY' | 'DAILY' | 'WEEKLY' | 'MONTHLY' | 'REAL_TIME' - `scheduleType` 'RUN_ONCE' | 'RECURRING' - `templateId` string[] - `includeDeleted` string - `format` 'json' | 'csv' ## Response `200` Successfully retrieved workflows - object - `workflows` object[]: List of workflows - `id` string: Unique identifier for the workflow - `name` string: Name of the workflow - `description` string: Description of the workflow - `state` 'ACTIVE' | 'DRAFT' | 'ERROR' | 'PAUSED' | 'NOT_SUPPORTED' | 'PREVIEW' | 'COMPLIANCE_REVIEW' | 'COMPLIANCE_REJECTED' | 'QUEUED' | 'SETUP' | 'DELETED': Persisted state of the long-lived workflow. It may describe setup or a control state such as ACTIVE or PAUSED. Use displayState for operational status UI. - `displayState` 'ACTIVE' | 'DRAFT' | 'ERROR' | 'PAUSED' | 'NOT_SUPPORTED' | 'PREVIEW' | 'QUEUED' | 'SETUP' | 'PENDING_START' | 'RUNNING' | 'VALIDATING' | 'FAILED' | 'DEGRADED' | 'COMPLIANCE_REVIEW' | 'COMPLIANCE_REJECTED' | 'DELETED' | 'STOPPED': Computed operational summary based on workflow state, the latest run, and monitor health. It does not indicate pending user input or support ownership; use awaitingUserInput and inSupport for those. ACTIVE may be presented as Complete, Scheduled, or Running depending on workflow type and schedule. - `reviewReason` 'COMPLIANCE_REVIEW' | 'HARD_FAIL' | 'TRANSFORMATION_REPAIR_REQUIRED' | 'MINIMUM_HUMAN_APPROVALS' | 'DATA_QUALITY_SCHEMA_ADHERENCE' | 'DATA_QUALITY_SCHEMA_VALIDATION' | 'DATA_QUALITY_COMPLETENESS' | 'DATA_QUALITY_SEMANTIC_PLAUSIBILITY' | 'ROW_COUNT_CHANGED' | 'WORKFLOW_REVISION_DRIFT' | 'ZERO_RESULTS': Why the latest run is being verified. Only present while displayState is VALIDATING. - `openSupportRequests` object[]: List of open support requests for this workflow. Only present when there are open requests. - `issueId` string, nullable: Linear issue identifier (e.g., KAD-123) - `requestedAt` string, date-time: When the support request was created - `status` string: Customer-visible ticket status synced from Linear (e.g., In Progress). Absent until the first sync. - `statusType` string: Status category backing `status` (e.g., unstarted, started, completed) - `inSupport` boolean: True when Kadoa support has an open ticket on this workflow. Same predicate as the inSupport query filter. Independent of state/displayState: this answers who is handling the workflow, while displayState answers whether it is delivering data. Prefer this over recomputing from openSupportRequests. - `awaitingUserInput` object, nullable: Present when the workflow cannot progress without the requesting user's next input. Scoped to that user; do not infer this from sessionStatus. - `since` string, date-time, required: When the workflow began waiting for user input - `prompt` string: The assistant's explicit question, when it paused on one - `userId` string: ID of the user who owns the workflow - `userName` string: Display name of the workflow owner - `userEmail` string, email: Email of the workflow owner - `createdAt` string, date-time: Timestamp when the workflow was created - `updateInterval` string: Update frequency - `isRealTime` boolean: Whether this workflow should be displayed as realtime - `lastDataChangedAt` string, date-time, nullable: Most recent persisted customer-visible data change for a real-time workflow - `assistantEligible` boolean: Whether this workflow mode supports the workflow Assistant. - `assistantSessionId` string, nullable: Most recent customer-facing Assistant session linked to this workflow. - `assistantThreadId` string, nullable: Most recent customer-facing Assistant thread within assistantSessionId. - `assistantState` WorkflowAssistantState - `status` 'ready' | 'running' | 'awaiting_input' | 'interrupted' | 'error' | 'aborted', required - `lastSettlement` object, nullable, required: Last recorded customer-thread settlement; null for historical threads without this evidence. Private work never overwrites it. - `status` string, required - `at` string, date-time, required - `hasFailure` boolean - `presentation` WorkflowPresentation: The status selects one operational notice. Badges separate lifecycle, activity and binary support ownership. Published data remains available independently. - `status` 'DRAFT' | 'ERROR' | 'PAUSED' | 'NOT_SUPPORTED' | 'PREVIEW' | 'QUEUED' | 'SETUP' | 'PENDING_START' | 'RUNNING' | 'FAILED' | 'COMPLIANCE_REVIEW' | 'COMPLIANCE_REJECTED' | 'DEGRADED' | 'DELETED' | 'STOPPED' | 'COMPLETE' | 'SCHEDULED' | 'UPDATING' | 'AWAITING_REVIEW' | 'REPLY_NEEDED' | 'UPDATE_FAILED', required - `badges` object[], required - `kind` 'lifecycle' | 'activity' | 'support', required - `status` 'DRAFT' | 'ERROR' | 'PAUSED' | 'NOT_SUPPORTED' | 'PREVIEW' | 'QUEUED' | 'SETUP' | 'PENDING_START' | 'RUNNING' | 'FAILED' | 'COMPLIANCE_REVIEW' | 'COMPLIANCE_REJECTED' | 'DEGRADED' | 'DELETED' | 'STOPPED' | 'COMPLETE' | 'SCHEDULED' | 'UPDATING' | 'AWAITING_REVIEW' | 'REPLY_NEEDED' | 'UPDATE_FAILED' | 'ASSISTANT_WORKING' | 'IN_SUPPORT', required - `group` 'attention' | 'working' | 'support' | 'failed' | 'active' | 'complete' | 'paused', required - `execution` WorkflowExecutionState - `phase` 'RUNNING' | 'VALIDATING' | 'FINISHED' | 'FAILED' | 'STOPPED' | 'null', nullable, required - `inProgress` boolean, required - `previewAvailable` boolean, required: A finished published preview exists, including empty results. Independent of new runs or workspace activity. - `updating` boolean, required: Workflow execution or assistant/repair work is in progress. - `availableActions` WorkflowAvailableActions: Customer lifecycle eligibility at read time. Authorization, quotas, template restrictions and mutation-time validation still apply. This is not an execution reservation. - `approve` union, required - object - `allowed` true, required - object - `allowed` false, required - `reason` 'ASSISTANT_ACTIVE' | 'REPAIR_ACTIVE' | 'RUN_IN_PROGRESS' | 'INITIAL_SETUP' | 'NOT_IN_PREVIEW' | 'NO_RUNNING_JOB' | 'WORKFLOW_UNAVAILABLE', required - `run` union, required - object - `allowed` true, required - object - `allowed` false, required - `reason` 'ASSISTANT_ACTIVE' | 'REPAIR_ACTIVE' | 'RUN_IN_PROGRESS' | 'INITIAL_SETUP' | 'NOT_IN_PREVIEW' | 'NO_RUNNING_JOB' | 'WORKFLOW_UNAVAILABLE', required - `pause` union, required - object - `allowed` true, required - object - `allowed` false, required - `reason` 'ASSISTANT_ACTIVE' | 'REPAIR_ACTIVE' | 'RUN_IN_PROGRESS' | 'INITIAL_SETUP' | 'NOT_IN_PREVIEW' | 'NO_RUNNING_JOB' | 'WORKFLOW_UNAVAILABLE', required - `resume` union, required - object - `allowed` true, required - object - `allowed` false, required - `reason` 'ASSISTANT_ACTIVE' | 'REPAIR_ACTIVE' | 'RUN_IN_PROGRESS' | 'INITIAL_SETUP' | 'NOT_IN_PREVIEW' | 'NO_RUNNING_JOB' | 'WORKFLOW_UNAVAILABLE', required - `rerun` union, required - object - `allowed` true, required - object - `allowed` false, required - `reason` 'ASSISTANT_ACTIVE' | 'REPAIR_ACTIVE' | 'RUN_IN_PROGRESS' | 'INITIAL_SETUP' | 'NOT_IN_PREVIEW' | 'NO_RUNNING_JOB' | 'WORKFLOW_UNAVAILABLE', required - `edit` union, required - object - `allowed` true, required - object - `allowed` false, required - `reason` 'ASSISTANT_ACTIVE' | 'REPAIR_ACTIVE' | 'RUN_IN_PROGRESS' | 'INITIAL_SETUP' | 'NOT_IN_PREVIEW' | 'NO_RUNNING_JOB' | 'WORKFLOW_UNAVAILABLE', required - `stop` union, required - object - `allowed` true, required - object - `allowed` false, required - `reason` 'ASSISTANT_ACTIVE' | 'REPAIR_ACTIVE' | 'RUN_IN_PROGRESS' | 'INITIAL_SETUP' | 'NOT_IN_PREVIEW' | 'NO_RUNNING_JOB' | 'WORKFLOW_UNAVAILABLE', required - `delete` union, required - object - `allowed` true, required - object - `allowed` false, required - `reason` 'ASSISTANT_ACTIVE' | 'REPAIR_ACTIVE' | 'RUN_IN_PROGRESS' | 'INITIAL_SETUP' | 'NOT_IN_PREVIEW' | 'NO_RUNNING_JOB' | 'WORKFLOW_UNAVAILABLE', required - `workspaceActivity` 'idle' | 'assistant' | 'repair': Current workspace execution lane, independent of preview readiness. - `assistantFinishedAt` string, date-time, nullable - `sessionStatus` 'pending' | 'created' | 'active' | 'idle' | 'inactive' | 'failed' | 'interrupted' | 'errored' | 'aborted' | 'timed_out', nullable: Current status of the listed customer-facing Assistant session. - `tags` string[]: Tags associated with the workflow - `limit` integer: Maximum number of items to scrape - `finishedAt` string, date-time: When the last job finished - `startedAt` string, date-time: When the last job started - `estimatedFinishedAtUtc` string, date-time, nullable: Estimated UTC finish time for the active job, when available. - `jobId` string: ID of the latest operational run attempt - `publishedJobId` string: ID of the latest finished run that supplies customer-visible data - `dataKey` string: Database key for the workflow data - `location` object: Scraping location configuration - `type` 'auto' | 'manual' - `isoCode` 'DE' | 'US' | 'GB' | 'NL' | 'CA' - `runState` 'RUNNING' | 'FINISHED' | 'FAILED' | 'STOPPED': State of the latest execution attempt. Use this for run diagnostics or workflow history, not as the workflow lifecycle or status label. - `templateId` string, nullable: Linked workflow template identifier. - `templateVersion` integer, nullable: Version pinned to the workflow's template linkage. - `templateLatestVersion` integer, nullable: Most recent published version of the linked template. - `templateIsOutdated` boolean: Whether a newer template version exists than the workflow's pinned version. - `totalRecords` integer: Total number of records extracted - `url` string: Primary URL being scraped - `urls` string[]: List of URLs being scraped - `browserActions` object[]: Optional browser actions to perform before extraction - `type` string: Action type (e.g., CLICK, TYPE, WAIT, GOTO) - `selector` string: CSS selector for element-based actions - `text` string: Text to type for TYPE actions - `timeMs` integer: Milliseconds to wait for WAIT actions - `url` string: URL to navigate to for GOTO actions - `schema` object[]: Extraction schema fields - `name` string - `description` string - `example` string - `dataType` 'STRING' | 'NUMBER' | 'BOOLEAN' | 'DATE' | 'DATETIME' | 'CURRENCY' | 'MONEY' | 'IMAGE' | 'LINK' | 'OBJECT' | 'ARRAY' - `isKey` boolean - `isRequired` boolean - `isUnique` boolean - `schemaName` string: Name of the schema used - `schemaId` string: ID of the schema used - `errors` object[]: Errors from the last job run - `errorCode` string: Error code identifying the type of error - `message` string: Human-readable error message - `timestamp` string, date-time: When the error occurred - `screenshot` string: Optional screenshot URL - `context` object: Additional context about the error - `url` string: The URL where the error occurred - `httpStatus` integer: HTTP status code if applicable - `retryCount` integer: Number of retry attempts made - `details` string: Additional error-specific details - `timestamp` string, date-time: When the error context was captured - `monitoring` boolean: Whether monitoring is enabled - `notificationConfig` object: Monitoring configuration - `enabled` boolean - `fields` object[] - `fieldName` string - `operator` 'changed' | 'added' | 'removed' - `observerHealth` object, nullable: Health status for monitored workflows. Only present when health monitoring is active and detects issues. - `healthTier` 'HEALTHY' | 'WARNING' | 'DEGRADED' | 'UNHEALTHY' | 'FAILED': Current health tier - `reason` string: Human-readable explanation of the health status - `issueStartedAt` string, date-time: When the current degradation episode started - `lastCheckedAt` string, date-time: When health was last evaluated - `pagination` object: Pagination information - `totalCount` integer: Total number of workflows matching the filter criteria - `page` integer: Current page number - `totalPages` integer: Total number of pages - `limit` integer: Number of items per page - `groupPagination` object: Per-group counts and window metadata. Present only when groupWindows is requested. ## Other responses - `401`: Unauthorized - Authentication required - `403`: Forbidden - Insufficient permissions - `500`: Internal server error --- [API](https://skmtc.dev/kadoa/apis/kadoa-api.md) · [All operations](https://skmtc.dev/kadoa/apis/kadoa-api/llms.txt) · [OpenAPI document](https://skmtc.dev/kadoa/apis/kadoa-api/revisions/bf7803c927b4?raw)