POST /api/workflows/:workflowId/run — Enqueue a Workflow Run

POST /api/workflows/:workflowId/run — Trigger an asynchronous run of a workflow. Returns HTTP 202 immediately with a runId and PENDING status.

Triggering a workflow run in Flowmatic is a non-blocking operation. When you call this endpoint, Flowmatic immediately accepts the request and places the run into an execution queue, returning a runId you can use to track progress. The workflow itself does not start synchronously — you receive a 202 Accepted response the moment your request is queued, regardless of how long the workflow ultimately takes to complete.

Endpoint

POST /api/workflows/:workflowId/run

Authentication

All requests must include a valid Bearer token in the Authorization header.

Authorization: Bearer <accessToken>

Path Parameters

workflowId · string · required

The unique identifier of the workflow you want to run. You can find this ID in the Flowmatic dashboard or from the workflow creation response. Example: wf_abc123.

Request Body

This endpoint does not accept a request body.

Response

A successful request returns HTTP 202 Accepted with a JSON body containing the new run’s ID and its initial status.

runId · string

A unique identifier assigned to this specific execution of the workflow. Use this value to poll the run’s progress via GET /api/workflows/runs/:runId.

status · string

The initial status of the enqueued run. This is always "PENDING" at the moment of enqueue, indicating the run has been accepted and is waiting in the execution queue.

Example Response

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

An HTTP 202 response means your run has been accepted and queued — it does not mean the workflow has finished executing, or even started yet. Flowmatic processes runs asynchronously. Use the runId from this response to poll GET /api/workflows/runs/:runId and track when the status advances from PENDING → RUNNING → SUCCESS (or FAILED).

Execution Queue Behavior

Flowmatic enforces sequential execution per workflow. Each workflow maintains its own queue, and runs drain one at a time in the order they were enqueued. If a previous run is still RUNNING when you enqueue a new one, the new run waits as PENDING until the current execution finishes.

This guarantees that runs for a given workflow never overlap or interfere with each other, which is especially important for workflows that write to shared resources (such as a Google Sheet or external database).

You can enqueue multiple runs in rapid succession — for example, in a loop or in response to multiple events — and Flowmatic will queue them all up and execute them in order. This is useful for batch processing: fire off all your enqueue requests immediately, then use GET /api/workflows/:workflowId/runs to watch the queue drain sequentially, or poll individual run IDs for fine-grained status tracking.

curl Example

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

What To Do After Enqueuing

Once you have a runId, you have two main options for monitoring progress:

• Poll a single run — use GET /api/workflows/runs/:runId to retrieve the current status and per-node output of that specific run.
• List all runs — use GET /api/workflows/:workflowId/runs to see the full queue for a workflow, including which runs are PENDING, RUNNING, or already SUCCESS.