How to Run and Monitor Flowmatic Workflow Executions

Learn how to enqueue a Flowmatic workflow run, poll for live status updates, and inspect per-node execution results after completion.

Once you’ve created a workflow, executing it is a single API call away. Flowmatic processes runs asynchronously — when you trigger a run, the API immediately returns a runId and a PENDING status while the engine queues up the work. You then poll a separate endpoint to track progress and, once the run completes, inspect the output produced by every node in the graph. This guide covers the full lifecycle from triggering a run to reading its final results.

Triggering a run

To start an execution, send a POST request to the run endpoint for your workflow. No request body is required.

curl -X POST https://api.flowmatic.io/api/workflows/<workflowId>/run \
  -H "Authorization: Bearer <accessToken>"

Replace <workflowId> with the id returned when you created the workflow (for example, wf_abc123).

The API responds with HTTP 202 Accepted — meaning the run has been accepted and queued, but not yet started:

{ "runId": "run_xyz789", "status": "PENDING" }

Save the runId. You will use it to poll for status updates.

Run status lifecycle

Every Flowmatic run moves through a well-defined set of statuses:

Pending

Accepted and waiting in the queue. No nodes have executed yet.

Running

The engine is executing nodes in graph order. Some may already be complete.

Success

All nodes completed without errors. Per-node outputs are available in the run detail.

Failed

One or more nodes encountered an error. The run detail shows which node failed and why.

Cancelled

The run was manually cancelled before it could complete.

Polling for completion

Because runs execute asynchronously, you need to query the run detail endpoint periodically until the status transitions to a terminal state (SUCCESS, FAILED, or CANCELLED).

curl https://api.flowmatic.io/api/workflows/runs/<runId> \
  -H "Authorization: Bearer <accessToken>"

Example polling loop (bash)

The following script polls every three seconds and exits as soon as the run reaches a terminal status:

RUN_ID="run_xyz789"
FM_TOKEN="<accessToken>"

while true; do
  RESPONSE=$(curl -s \
    -H "Authorization: Bearer $FM_TOKEN" \
    "https://api.flowmatic.io/api/workflows/runs/$RUN_ID")

  STATUS=$(echo "$RESPONSE" | grep -o '"status":"[^"]*"' | head -1 | cut -d'"' -f4)
  echo "Status: $STATUS"

  if [ "$STATUS" = "SUCCESS" ] || [ "$STATUS" = "FAILED" ] || [ "$STATUS" = "CANCELLED" ]; then
    echo "Run finished with status: $STATUS"
    echo "$RESPONSE"
    break
  fi

  sleep 3
done

In production applications, consider using an exponential back-off strategy instead of a fixed interval. Short workflows typically complete in seconds, while large AI-node pipelines may take longer.

Reading the run detail

When the run completes, the full response includes a nodes map with a per-node status and output:

{
  "runId": "run_xyz789",
  "workflowId": "wf_abc123",
  "status": "SUCCESS",
  "nodes": {
    "t":   { "status": "SUCCESS", "output": {} },
    "ds":  { "status": "SUCCESS", "output": { "rows": [...] } },
    "f":   { "status": "SUCCESS", "output": { "items": [...] } },
    "out": { "status": "SUCCESS", "output": { "emailsSent": 3 } }
  }
}

Each key in nodes corresponds to a node id from your workflow graph. For every node you can see:

• status — Whether that specific node succeeded or failed.
• output — The data the node produced. For a DATA_SOURCE node this is the rows array; for a FILTER node it’s the items array; for an OUTPUT node it’s a count of emails dispatched.

If a run status is FAILED, look for the node whose status is "FAILED" in the nodes map. The output field for that node will typically include an error key with a description of what went wrong.

Listing all runs for a workflow

To get a history of all executions for a particular workflow, use the workflow-scoped runs endpoint:

curl https://api.flowmatic.io/api/workflows/<workflowId>/runs \
  -H "Authorization: Bearer <accessToken>"

The response is an array of run summary objects ordered by creation time (most recent first):

[
  { "runId": "run_xyz789", "status": "SUCCESS", "createdAt": "2024-06-01T10:00:00Z" },
  { "runId": "run_xyz788", "status": "FAILED",  "createdAt": "2024-06-01T09:45:00Z" },
  { "runId": "run_xyz787", "status": "SUCCESS", "createdAt": "2024-05-31T18:30:00Z" }
]

This endpoint is useful for building audit logs, dashboards, or debugging patterns in recurring failures.

Queue behavior and concurrent runs

Flowmatic enforces a one-active-run-at-a-time policy per workflow. If a run is already in the PENDING or RUNNING state when you trigger another one, the new run enters the queue and waits.

Sequential execution

Runs for a workflow execute one after another, in enqueue order — preventing race conditions on shared state.

Batch enqueueing

Submit multiple POST /run requests back-to-back. Each returns its own runId and queues automatically.

Batch enqueue example

# Fire off three runs in quick succession
curl -s -X POST https://api.flowmatic.io/api/workflows/wf_abc123/run \
  -H "Authorization: Bearer $FM_TOKEN"

curl -s -X POST https://api.flowmatic.io/api/workflows/wf_abc123/run \
  -H "Authorization: Bearer $FM_TOKEN"

curl -s -X POST https://api.flowmatic.io/api/workflows/wf_abc123/run \
  -H "Authorization: Bearer $FM_TOKEN"

Each call returns its own runId immediately. The first run starts executing right away; the second and third remain PENDING until the run ahead of them in the queue finishes.

Enqueuing a large number of runs at once without a mechanism to drain the queue can cause extended delays for later runs. Monitor your queue depth via the workflow runs list endpoint and throttle enqueue calls in high-volume scenarios.