Manage Workflows

List, retrieve, and manage existing workflows

List Workflows

Node SDK

const workflows = await client.workflow.list({ limit: 100 });

for (const workflow of workflows) {
  console.log(`${workflow.id}: ${workflow.name}`);
}

Find workflows that need attention

Use group:attention for Assistant questions and previews to review. Workflows with open support cases appear in group:support, even when awaiting your reply. See all groups.

awaitingUserInput contains the wait’s start time and optional question text.

Node SDK

import { WorkflowStatusFilter } from "@kadoa/node-sdk";

const needsAttention = await client.workflow.list({
  statusFilters: [WorkflowStatusFilter.Attention],
});

for (const workflow of needsAttention) {
  const question = workflow.awaitingUserInput?.prompt;
  console.log(workflow.name, question ?? "waiting on preview approval");
}

Reply to the Assistant or review the preview. Check availableActions.approve before approving. An incomplete update can block approval even in this group.

statusFilters is available in the Node SDK, the REST API, and the MCP server. The Python SDK does not expose it yet, so call GET /v4/workflows?statusFilters=group:attention directly from Python.

Get Workflow

Node SDK

const workflow = await client.workflow.get('YOUR_WORKFLOW_ID');

Pause & Resume

Only ACTIVE workflows can be paused.

Node SDK

// Pause
await client.workflow.pause('YOUR_WORKFLOW_ID');

// Resume
await client.workflow.resume('YOUR_WORKFLOW_ID');

Update

Node SDK

await client.workflow.update("YOUR_WORKFLOW_ID", {
  name: "New Name",
  updateInterval: "DAILY",
});

Run History

Workflow run history is the execution record for one workflow. It includes outcome, start and finish times, record counts, and public errors.

The Node SDK and MCP Server can filter execution history by success, failed, or in_progress and paginate it.

Node SDK

const history = await client.workflow.listWorkflowRuns("WORKFLOW_ID", {
  page: 1,
  limit: 25,
  status: "failed",
});

for (const run of history.workflowRuns) {
  console.log(run.id, run.state, run.startedAt, run.errors);
}

MCP Server

> Show the last 25 failed runs for my Product Monitor and summarize the errors.

REST API

curl "https://api.kadoa.com/v4/workflows/WORKFLOW_ID/history?page=1&limit=25&status=failed" \
  -H "x-api-key: YOUR_API_KEY"

See workflow run history API reference for the complete response.

Delete

This permanently deletes the workflow and all its data.

Node SDK

await client.workflow.delete('YOUR_WORKFLOW_ID');

Templates

Workflows can be linked to templates that manage their prompt, schema, and notification settings. When linked, those fields become read-only on the workflow.

See Templates for linking, unlinking, and applying template updates via the API.

Fetch Data

Node SDK

const workflows = await client.workflow.list({ limit: 100 });

for (const workflow of workflows) {
  if (!workflow.id) {
    continue;
  }

  const data = await client.extraction.fetchAllData({
    workflowId: workflow.id,
  });
  console.log(`${workflow.name}: ${data.length} records`);
}