> ## Documentation Index > Fetch the complete documentation index at: https://docs.flowmaticai.in/llms.txt > Use this file to discover all available pages before exploring further. # 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. ```bash theme={null} curl -X POST https://api.flowmatic.io/api/workflows//run \ -H "Authorization: Bearer " ``` Replace `` 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: ```json theme={null} { "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: Accepted and waiting in the queue. No nodes have executed yet. The engine is executing nodes in graph order. Some may already be complete. All nodes completed without errors. Per-node outputs are available in the run detail. One or more nodes encountered an error. The run detail shows which node failed and why. 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`). ```bash theme={null} curl https://api.flowmatic.io/api/workflows/runs/ \ -H "Authorization: Bearer " ``` ### Example polling loop (bash) The following script polls every three seconds and exits as soon as the run reaches a terminal status: ```bash theme={null} RUN_ID="run_xyz789" FM_TOKEN="" 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: ```json theme={null} { "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: ```bash theme={null} curl https://api.flowmatic.io/api/workflows//runs \ -H "Authorization: Bearer " ``` The response is an array of run summary objects ordered by creation time (most recent first): ```json theme={null} [ { "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. Runs for a workflow execute one after another, in enqueue order — preventing race conditions on shared state. Submit multiple `POST /run` requests back-to-back. Each returns its own `runId` and queues automatically. ### Batch enqueue example ```bash theme={null} # 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.