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

Source: https://tadabase.com/docs/developers/workflows-api  
Status: Verified Nov 17, 2026. Checked against the current product

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](https://tadabase.com/docs-shots/developers-api-key-allow-workflows.webp)

## Endpoints

| Method and path | What it does |
| --- | --- |
| `GET workflows` | Lists 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/status` | Runs that have not finished. Narrow it with `/queue/{queueId}` or `/workflow/{workflowId}` |
| `GET workflows/history` | All runs, newest first. Narrow it with `/queue/{queueId}` or `/workflow/{workflowId}` |
| `GET workflows/history/queue/{queueId}/records` | The records one run processed, with the result for each |
| `GET workflows/history/queue/{queueId}/records/{recordId}/logs` | The log entries for one record in one run |
| `GET workflows/history/queue/{queueId}/actions` | Each 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](https://tadabase.com/docs/workflows/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.

```bash
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"
}
```

> **Test with a dry run:** Send `runMode=dry` to do a **Dry run**, as in the workflow editor: the steps run but nothing is really changed or sent. The answer says "Dry run queued. External side effects are disabled."

## Follow a run

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

| Property | What it holds |
| --- | --- |
| `queueId`, `workflowId`, `recordId` | Which run, which workflow, and the record it was started for |
| `status` | Where the run is, for example `active` or `processing` while it works, then `complete`, `complete_with_errors`, `error`, or `terminate` after a cancel |
| `runType`, `runOrigin`, `runMode` | How it started (such as `manual` or `schedule`), whether from the builder or the live app, and `live` or `dry` |
| `totalRecords`, `processedRecords`, `failedRecords`, `progress` | How far it got |
| `message`, `errorMessage` | The run's last message and error, if any |
| `runAt`, `startAt`, `endAt`, `createdAt` | When 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](https://tadabase.com/docs/workflows/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

| Response | Cause |
| --- | --- |
| `403` "This API key does not have Allow Workflows enabled." | Turn on **Allow Workflows** on the key |
| `412` with a plan message | Your 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` |
| `423` | The app is in maintenance; try again later |

## Scheduled Tasks (older apps)

Scheduled Tasks is the older automation that scheduled workflows replaced (see [Scheduled workflows](https://tadabase.com/docs/workflows/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 path | What it does (older Scheduled Tasks endpoints) |
| --- | --- |
| `GET tasks` | Lists 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/status` | Runs in progress. Narrow it with `/queue/{taskQueueId}` or `/task/{taskId}` |
| `GET tasks/history` | All 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`.
