Workflow Runs: Async Execution and Status Lifecycle

A run is a single execution of a workflow. When you enqueue a run, Flowmatic acknowledges the request immediately and queues the work to be processed asynchronously — your API call returns in milliseconds regardless of how long the actual pipeline takes to execute. You then poll a status endpoint to track progress, inspect per-node results, and detect any failures. This page explains everything you need to know about run lifecycle, queuing behavior, and monitoring patterns.

What Is a Run?

Each time you trigger a workflow, Flowmatic creates a run record that tracks:

The overall execution status (PENDING, RUNNING, SUCCESS, or FAILED)
A per-node status breakdown showing how each node in the graph fared
Timestamps for when the run was enqueued and when it completed
Error details if any node failed

A single workflow can have any number of runs over its lifetime. Runs are independent of each other — re-running a workflow creates a brand new run record and does not affect previous run history.

Enqueueing a Run

To start a run, send a POST request to the runs endpoint for your workflow:

Enqueue a run

curl -X POST https://api.flowmatic.io/api/workflows/wf_xyz789/run \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Flowmatic responds immediately with 202 Accepted:

202 Accepted — run enqueued

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

The 202 status code is intentional — it signals that the request was accepted but execution has not yet begun. Save the runId; you’ll use it to poll for status updates.

Flowmatic never blocks on run completion. Even if a workflow has dozens of nodes and processes thousands of CSV rows, the enqueue call always returns within milliseconds.

Run Status Lifecycle

Every run moves through a defined set of statuses as it progresses from enqueue to completion.

PENDING → RUNNING → SUCCESS
                  ↘ FAILED

PENDING

The run has been accepted and is waiting in the queue. No nodes have started executing yet. This status persists until the workflow runner picks up the job.

RUNNING

The workflow runner has picked up the run and is actively executing nodes. The run will remain in this state until all nodes complete (or one fails fatally).

SUCCESS

All nodes executed successfully and the pipeline completed without errors. All emails have been sent (if an OUTPUT node was present).

FAILED

One or more nodes encountered an error that halted the pipeline. The per-node status breakdown will identify which node failed and provide error details.

The SKIPPED Status

In addition to the four run-level statuses above, individual nodes within a run can have a SKIPPED status. This occurs when a workflow contains conditional branch nodes and the execution path did not pass through a particular branch. Skipped nodes are not errors — they simply were not needed for this execution path.

SKIPPED only applies to per-node statuses, not to the overall run status. A run that completes with some nodes SKIPPED can still end in SUCCESS.

Per-Node Status

When you fetch a run’s details, the response includes a nodes array with the execution status of every node in the workflow. This granular breakdown is invaluable for debugging failures and understanding pipeline performance. Each node status entry includes:

string

The id of the node as defined in the workflow graph.

string

The node type (TRIGGER, DATA_SOURCE, AI, FILTER, or OUTPUT).

string

One of PENDING, RUNNING, SUCCESS, FAILED, or SKIPPED.

string | null

If the node’s status is FAILED, this field contains a human-readable error message describing what went wrong. null for all other statuses.

string | null

ISO 8601 timestamp of when this node began executing. null if the node hasn’t started yet.

string | null

ISO 8601 timestamp of when this node finished executing. null if the node hasn’t completed yet.

Example Run Detail Response

GET /api/workflows/runs/run_def456 — SUCCESS

{
  "runId":       "run_def456",
  "workflowId":  "wf_xyz789",
  "status":      "SUCCESS",
  "enqueuedAt":  "2024-06-01T10:00:00.000Z",
  "startedAt":   "2024-06-01T10:00:02.341Z",
  "completedAt": "2024-06-01T10:00:18.892Z",
  "nodes": [
    {
      "nodeId":      "trigger",
      "type":        "TRIGGER",
      "status":      "SUCCESS",
      "error":       null,
      "startedAt":   "2024-06-01T10:00:02.341Z",
      "completedAt": "2024-06-01T10:00:02.355Z"
    },
    {
      "nodeId":      "ds",
      "type":        "DATA_SOURCE",
      "status":      "SUCCESS",
      "error":       null,
      "startedAt":   "2024-06-01T10:00:02.356Z",
      "completedAt": "2024-06-01T10:00:03.120Z"
    },
    {
      "nodeId":      "ai",
      "type":        "AI",
      "status":      "SUCCESS",
      "error":       null,
      "startedAt":   "2024-06-01T10:00:03.121Z",
      "completedAt": "2024-06-01T10:00:14.775Z"
    },
    {
      "nodeId":      "f",
      "type":        "FILTER",
      "status":      "SUCCESS",
      "error":       null,
      "startedAt":   "2024-06-01T10:00:14.776Z",
      "completedAt": "2024-06-01T10:00:14.801Z"
    },
    {
      "nodeId":      "out",
      "type":        "OUTPUT",
      "status":      "SUCCESS",
      "error":       null,
      "startedAt":   "2024-06-01T10:00:14.802Z",
      "completedAt": "2024-06-01T10:00:18.892Z"
    }
  ]
}

And a run that encountered a failure at the AI node:

GET /api/workflows/runs/run_ghi012 — FAILED

{
  "runId":       "run_ghi012",
  "workflowId":  "wf_xyz789",
  "status":      "FAILED",
  "enqueuedAt":  "2024-06-01T11:00:00.000Z",
  "startedAt":   "2024-06-01T11:00:01.883Z",
  "completedAt": "2024-06-01T11:00:09.441Z",
  "nodes": [
    {
      "nodeId":      "trigger",
      "type":        "TRIGGER",
      "status":      "SUCCESS",
      "error":       null,
      "startedAt":   "2024-06-01T11:00:01.883Z",
      "completedAt": "2024-06-01T11:00:01.894Z"
    },
    {
      "nodeId":      "ds",
      "type":        "DATA_SOURCE",
      "status":      "SUCCESS",
      "error":       null,
      "startedAt":   "2024-06-01T11:00:01.895Z",
      "completedAt": "2024-06-01T11:00:02.670Z"
    },
    {
      "nodeId":      "ai",
      "type":        "AI",
      "status":      "FAILED",
      "error":       "LLM response did not conform to the declared output schema. Expected field 'customers' to be an array, got string.",
      "startedAt":   "2024-06-01T11:00:02.671Z",
      "completedAt": "2024-06-01T11:00:09.441Z"
    },
    {
      "nodeId":      "f",
      "type":        "FILTER",
      "status":      "SKIPPED",
      "error":       null,
      "startedAt":   null,
      "completedAt": null
    },
    {
      "nodeId":      "out",
      "type":        "OUTPUT",
      "status":      "SKIPPED",
      "error":       null,
      "startedAt":   null,
      "completedAt": null
    }
  ]
}

Notice that when ai fails, all downstream nodes (f and out) are set to SKIPPED — the execution path through those nodes was never taken.

Queue Behavior

Runs for the same workflow are serialized — only one run executes at a time per workflow. If you enqueue a second run while the first is still RUNNING, the second run enters the queue with a status of PENDING and waits until the first run reaches a terminal state (SUCCESS or FAILED).

This serialization is per-workflow. You can run multiple different workflows concurrently without any queuing constraints between them.

This behavior has some important implications:

Long-running AI nodes can cause queue backup if you enqueue many runs in quick succession. Monitor queue depth if latency is a concern.
Batch testing (enqueueing many runs at once) works fine — runs will execute sequentially in the order they were enqueued.
A FAILED run does not block the queue. The next PENDING run will be picked up immediately after the failure is recorded.

Polling for Run Completion

Since execution is asynchronous, you need to poll the run status endpoint until the run reaches a terminal state (SUCCESS or FAILED). The recommended approach is exponential backoff with a maximum interval.

Polling Endpoint

GET /api/workflows/runs/:runId

Bash Polling Example

Poll until completion (bash)

RUN_ID="run_def456"
API_KEY="YOUR_API_KEY"
INTERVAL=2

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

  STATUS=$(echo "$RESPONSE" | jq -r '.status')
  echo "$(date -u +%H:%M:%S) — Run status: $STATUS"

  if [ "$STATUS" = "SUCCESS" ] || [ "$STATUS" = "FAILED" ]; then
    echo "Run reached terminal state: $STATUS"
    echo "$RESPONSE" | jq .
    break
  fi

  sleep $INTERVAL
  # Double the interval up to a maximum of 30 seconds
  INTERVAL=$(( INTERVAL < 30 ? INTERVAL * 2 : 30 ))
done

Polling Example with Node.js

Poll until completion (Node.js)

async function pollRunUntilComplete(runId, apiKey) {
  const url = `https://api.flowmatic.io/api/workflows/runs/${runId}`;
  let intervalMs = 2000;
  const maxIntervalMs = 30000;

  while (true) {
    const response = await fetch(url, {
      headers: { Authorization: `Bearer ${apiKey}` }
    });

    if (!response.ok) {
      throw new Error(`Unexpected response: ${response.status}`);
    }

    const run = await response.json();
    console.log(`[${new Date().toISOString()}] Run status: ${run.status}`);

    if (run.status === "SUCCESS" || run.status === "FAILED") {
      return run;
    }

    await new Promise(resolve => setTimeout(resolve, intervalMs));
    intervalMs = Math.min(intervalMs * 2, maxIntervalMs);
  }
}

// Usage
const run = await pollRunUntilComplete("run_def456", process.env.FLOWMATIC_API_KEY);
if (run.status === "FAILED") {
  const failedNode = run.nodes.find(n => n.status === "FAILED");
  console.error(`Pipeline failed at node '${failedNode.nodeId}': ${failedNode.error}`);
}

Start polling 1–2 seconds after enqueueing rather than immediately. A brand new run will always be PENDING for at least a brief moment, so the first request is rarely useful if made instantly.

Batch Testing: Enqueuing Multiple Runs

You can enqueue multiple runs against the same workflow in rapid succession — for example, to test a pipeline with several different CSV uploads. Each enqueue call returns immediately with a unique runId. Flowmatic queues them all and processes them one by one in order.

Enqueue three runs in parallel

WORKFLOW_ID="wf_xyz789"
API_KEY="YOUR_API_KEY"

# Enqueue run 1
RUN1=$(curl -s -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  "https://api.flowmatic.io/api/workflows/$WORKFLOW_ID/run")
echo "Enqueued: $(echo $RUN1 | jq -r '.runId')"

# Enqueue run 2
RUN2=$(curl -s -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  "https://api.flowmatic.io/api/workflows/$WORKFLOW_ID/run")
echo "Enqueued: $(echo $RUN2 | jq -r '.runId')"

# Enqueue run 3
RUN3=$(curl -s -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  "https://api.flowmatic.io/api/workflows/$WORKFLOW_ID/run")
echo "Enqueued: $(echo $RUN3 | jq -r '.runId')"

All three runs will be in PENDING state initially. You can poll each runId independently to track their individual progress.

Be mindful of rate limits when enqueuing many runs. If you’re batch-testing, introduce a small delay (e.g., 100ms) between enqueue calls to avoid hitting the API rate limit for the enqueue endpoint.

End-to-End Run Workflow

Upload your CSV

Send a POST /api/uploads request with your CSV file. Save the returned uploadId — you’ll reference it in your DATA_SOURCE node.

Create or update your workflow

Send a POST /api/workflows (or PATCH /api/workflows/:workflowId) with your workflow graph, including the uploadId in the DATA_SOURCE node’s data object.

Enqueue a run

Send POST /api/workflows/:workflowId/run. Save the runId from the 202 response.

Poll for completion

Call GET /api/workflows/runs/:runId in a loop with exponential backoff until status is SUCCESS or FAILED.

Inspect results

On SUCCESS, your emails have been sent. On FAILED, check the nodes array for the failed node’s error field to understand what went wrong, then fix your workflow or data and enqueue a new run.

Get Started

Core Concepts

Guides

Workflow Runs: Async Execution and Status Lifecycle

What Is a Run?

Enqueueing a Run

Run Status Lifecycle

PENDING

RUNNING

SUCCESS

FAILED

The SKIPPED Status

Per-Node Status

Example Run Detail Response

Queue Behavior

Polling for Run Completion

Polling Endpoint

Bash Polling Example

Polling Example with Node.js

Batch Testing: Enqueuing Multiple Runs

End-to-End Run Workflow

Next Steps

Workflows

Node Types

​What Is a Run?

​Enqueueing a Run

​Run Status Lifecycle

PENDING

RUNNING

SUCCESS

FAILED

​The SKIPPED Status

​Per-Node Status

​Example Run Detail Response

​Queue Behavior

​Polling for Run Completion

​Polling Endpoint

​Bash Polling Example

​Polling Example with Node.js

​Batch Testing: Enqueuing Multiple Runs

​End-to-End Run Workflow

​Next Steps

Workflows

Node Types

What Is a Run?

Enqueueing a Run

Run Status Lifecycle

The SKIPPED Status

Per-Node Status

Example Run Detail Response

Queue Behavior

Polling for Run Completion

Polling Endpoint

Bash Polling Example

Polling Example with Node.js

Batch Testing: Enqueuing Multiple Runs

End-to-End Run Workflow

Next Steps