Run workflows through the API

List your workflows, start a Manual workflow for a record, follow the run's progress and logs, and cancel a run, all through the REST API.

  • Verified Nov 17, 2026
  • Classic builder

On this page
  1. Before you start
  2. Endpoints
  3. Find the workflow
  4. Start a run
  5. Follow a run
  6. Cancel a run
  7. Common problems
  8. Scheduled Tasks (older apps)

Start a workflow from your own system, for example when an order arrives in another tool, and watch it run. The Workflows API starts workflows that use the Manual trigger and reads the run history of every workflow in the app.

Before you start #

  • Your plan must include API access, Workflows, and workflows through the API (the Allow Workflows switch shows a plan icon when it does not). Without them the API answers 412.
  • Turn on Allow Workflows on the API key in Settings > API Keys. Without it the API answers 403 "This API key does not have Allow Workflows enabled."
  • Every URL starts with https://api.tadabase.io/api/v1/workflows.
The API key form in Settings with the Allow Workflows switch highlighted

Endpoints #

Method and pathWhat it does
GET workflowsLists workflows
GET workflows/{workflowId}One workflow
POST workflows/run/{workflowId}Starts a Manual workflow
POST workflows/run/{workflowId}/record/{recordId}Starts a Manual workflow for one record
GET workflows/statusRuns that have not finished. Narrow it with /queue/{queueId} or /workflow/{workflowId}
GET workflows/historyAll runs, newest first. Narrow it with /queue/{queueId} or /workflow/{workflowId}
GET workflows/history/queue/{queueId}/recordsThe records one run processed, with the result for each
GET workflows/history/queue/{queueId}/records/{recordId}/logsThe log entries for one record in one run
GET workflows/history/queue/{queueId}/actionsEach step of one run: what ran, how long it took and any error
POST workflows/terminate/queue/{queueId}Cancels a run that has not finished

List endpoints take page and limit (default 20, at most 100) and answer with totalItems, totalPages, page, limit, hasNextPage and hasPreviousPage. IDs are the encoded IDs the API returns.

Find the workflow #

GET workflows accepts status (active or inactive), triggerType, dataTableId, search (part of the name), order (id, name, status, triggerType, stepsCount, createdAt, updatedAt) and orderBy (asc or desc).

JSON
{
  "type": "success",
  "workflows": [
    {
      "workflowId": "DVWQWRNZ49",
      "name": "Send job summary",
      "status": "active",
      "dataTableId": "lGArg7rmR6",
      "triggerType": "manual",
      "apiTriggerable": true,
      "stepsCount": 3,
      "occurrence": null,
      "nextRunAt": null,
      "createdAt": "2026-10-02 14:11:09",
      "updatedAt": "2026-11-12 08:40:51"
    }
  ],
  "totalItems": 1,
  "totalPages": 1,
  "page": 1,
  "limit": 20,
  "hasNextPage": false,
  "hasPreviousPage": false
}

apiTriggerable is true when you can start the workflow through the API: it is active and uses the Manual trigger. For a scheduled workflow, occurrence and nextRunAt say when it runs next.

Start a run #

  1. Use a Manual workflow In the builder, give the workflow the Manual trigger and make it active. Workflows with other triggers run only from their own trigger, and the API answers 422; an inactive workflow answers 412. See Workflow triggers.
  2. Call run Call POST workflows/run/{workflowId}, or POST workflows/run/{workflowId}/record/{recordId} to run it for one record of the workflow's table.
  3. Keep the queueId The API answers 202 with the run's queueId. The run happens in the background.
Shell
curl -X POST https://api.tadabase.io/api/v1/workflows/run/WORKFLOW_ID/record/RECORD_ID \
  -H "X-Tadabase-App-Id: YOUR_APP_ID" \
  -H "X-Tadabase-App-Key: YOUR_API_KEY" \
  -H "X-Tadabase-App-Secret: YOUR_API_SECRET"
JSON
{
  "type": "success",
  "msg": "Workflow run queued.",
  "queueId": "kN8Q3wPrJ1",
  "workflowId": "DVWQWRNZ49",
  "recordId": "4MXQJdrZ6v",
  "status": "active",
  "runMode": "live"
}

Follow a run #

Call GET workflows/history/queue/{queueId}. Each run in runs has:

PropertyWhat it holds
queueId, workflowId, recordIdWhich run, which workflow, and the record it was started for
statusWhere the run is, for example active or processing while it works, then complete, complete_with_errors, error, or terminate after a cancel
runType, runOrigin, runModeHow it started (such as manual or schedule), whether from the builder or the live app, and live or dry
totalRecords, processedRecords, failedRecords, progressHow far it got
message, errorMessageThe run's last message and error, if any
runAt, startAt, endAt, createdAtWhen it was scheduled, started, ended and created

workflows/history also accepts workflowId, status, runType, runMode, runOrigin (builder or app), recordId, and a date range with from and to (a date such as 2026-11-01, or a date and time). workflows/status lists only runs that have not finished and does not take status, runType, runMode, from or to.

To see what happened inside a run, call .../records for the result per record (logId, recordId, status, startAt, endAt) and .../actions for each step (stepId, actionType, actionTitle, status, durationMs, errorCode, errorMessage, retryCount, startedAt, completedAt). The actions list takes status, actionType, stepId and recordId to narrow it. The same history is in the builder; see Workflow history and logs.

Cancel a run #

Call POST workflows/terminate/queue/{queueId}. It is safe to call more than once. The msg says what happened: "Workflow cancellation requested.", "Workflow cancellation has already been requested." or "Workflow run has already finished and cannot be cancelled."

Common problems #

ResponseCause
403 "This API key does not have Allow Workflows enabled."Turn on Allow Workflows on the key
412 with a plan messageYour plan does not include workflows through the API
412 "This workflow is inactive..."Activate the workflow
422 "This workflow cannot be started through the Workflow API..."The workflow does not use the Manual trigger
404 "Record not found in this workflow's data table."The record ID is from another table
400 "The workflowId value is invalid..."Use the encoded ID from GET workflows
423The app is in maintenance; try again later

Scheduled Tasks (older apps) #

Scheduled Tasks is the older automation that scheduled workflows replaced (see Scheduled workflows). Apps that still have Scheduled Tasks can keep running them through the older tasks endpoints, which need Allow Tasks on the API key and a plan that includes them in the API. New integrations should use a Manual workflow and the endpoints above instead.

Method and pathWhat it does (older Scheduled Tasks endpoints)
GET tasksLists the tasks: task_id, name, status, data_table_id, occurrence, next_run_at, type
POST tasks/run/{taskId}Runs the task now and answers with its task_queue_id when the run is done
GET tasks/statusRuns in progress. Narrow it with /queue/{taskQueueId} or /task/{taskId}
GET tasks/historyAll runs. Narrow it with /queue/{taskQueueId} or /task/{taskId}
POST tasks/terminate/queue/{taskQueueId}Stops one run
POST tasks/terminate/task/{taskId}Stops the runs of one task

The older task run entries have task_queue_id, task_id, total_records, total_record_proceed, start_at, run_type and status.

Was this page helpful?

Something wrong or missing on this page? Tell us.