---
title: "Get workflow by ID"
method: GET
path: "/v4/workflows/{workflowId}"
tags: ["Workflows"]
---

# Get workflow by ID

`GET /v4/workflows/{workflowId}`

## Request

- Base URL: `https://api.kadoa.com`
- URL: `https://api.kadoa.com/v4/workflows/{workflowId}`
- Auth: API key in header `x-api-key`

Retrieves detailed information about a specific workflow. This endpoint requires authentication and proper
team access permissions.

## Path parameters

- `workflowId` string, required

## Response `200`

Workflow details retrieved successfully

- object
  - `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.
  - `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
  - `schedules` string[]: Cron schedules for updates
  - `scheduleTimezone` string: IANA timezone used to evaluate cron schedules
  - `nextInvocation` string, date-time: Next scheduled execution time
  - `monitoring` boolean: Whether monitoring is enabled
  - `location` object: Scraping location configuration
    - `type` 'auto' | 'manual'
    - `isoCode` string: Supported country ISO code when type is manual
  - `tags` string[]: Tags associated with the workflow
  - `schemaName` string: Name of the schema used
  - `schemaId` string: ID of the schema used
  - `templateName` string, nullable: Name of the linked workflow template
  - `templateId` string, nullable: ID of the linked workflow template
  - `templateVersion` integer, nullable: Applied template version
  - `templateHasPrompt` boolean: Whether the template controls the workflow prompt
  - `templateHasSchema` boolean: Whether the template controls the extraction schema
  - `templateHasSchemaValidationRules` boolean: Whether the template controls schema validation rules
  - `templateHasNotifications` boolean: Whether the template controls notification settings
  - `templateHasFrequency` boolean: Whether the template controls schedule/frequency
  - `templateHasRecordLimit` boolean: Whether the template controls the output record limit
  - `hasSchemaValidationRules` boolean: Whether this workflow has schema validation rules
  - `channelCounts` object: Notification channel counts grouped by channel type
  - `jobId` string: ID of the latest operational run attempt
  - `publishedJobId` string: ID of the latest finished run that supplies customer-visible data
  - `isFirstRun` boolean: Whether the workflow has not completed a regular run yet
  - `dataQualityIssues` integer: Number of data-quality issues in the latest finished run
  - `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.
  - `dataKey` string: Database key for the workflow data
  - `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
  - `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.
  - `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
  - `transformation` object, nullable: The workflow's transformation: the input fields it reads as context and the output fields it adds or modifies, each with a one-sentence customer summary. Null when the workflow has no transformation.
    - `contextFields` string[]: Input fields the transformation reads as mapping context. Absent when the step reads the full row.
    - `fields` object[]
      - `name` string
      - `summary` string, nullable
      - `type` 'STRING' | 'NUMBER' | 'BOOLEAN' | 'DATE' | 'DATETIME' | 'CURRENCY' | 'MONEY' | 'IMAGE' | 'LINK' | 'OBJECT' | 'ARRAY': Field data type
  - `entity` string: Canonical extracted entity name
  - `extractionSpec` object: Canonical extraction intent for Assistant-built workflows
  - `isSchemaEditable` boolean: Whether the schema can be edited
  - `limit` integer: Maximum number of items to scrape
  - `additionalData` object: Additional static data for the workflow
  - `notificationConfig` object, nullable: Current monitoring configuration. Use these values as the basis for replacement updates.
    - `monitoredFields` object[]
      - `fieldName` string, required
      - `operator` 'changed' | 'added' | 'removed', required
      - `isKeyField` boolean
    - `conditions` object: Persisted AND/OR monitoring condition group
  - `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.
  - `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
  - `extractionStrategySummary` ExtractionStrategySummary
    - `approach` string, required
    - `summary` string, required
    - `dataSource` object, required
      - `type` string, required
      - `endpoints` string[], required
      - `interactionStyle` string, required
      - `selectors` string[], required
    - `intervalSeconds` number, nullable: Realtime polling interval in seconds, when applicable.
  - `assistantSessionId` string, nullable: Newest assistant session linked to this workflow, regardless of status. Null if no assistant session has been created for this workflow.
  - `assistantThreadId` string, nullable: Newest assistant thread within the assistant session.
  - `assistantEligible` boolean: True when this workflow's lane supports the assistant (SHELLY_SCRIPT or SHELLY_REAL_TIME_SCRIPT). Independent of assistantSessionId; combine with !assistantSessionId for start-vs-continue.
  - `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' | 'active' | 'idle' | 'inactive' | 'failed' | 'interrupted' | 'errored' | 'aborted' | 'timed_out', nullable: Low-level status of the latest Assistant conversation. Use it only to decide whether that conversation can accept input. Do not infer workflow progress or whether a reply is needed; use displayState and awaitingUserInput instead.
  - `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

## Other responses

- `400`: Bad Request - Invalid workflowId format
- `401`: Unauthorized - Invalid or missing authentication token
- `403`: Forbidden - User doesn't have required permissions
- `404`: Workflow not found
- `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)