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

# 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

```bash theme={null}
POST /api/workflows/:workflowId/run
```

## Authentication

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

```bash theme={null}
Authorization: Bearer <accessToken>
```

## Path Parameters

<ParamField path="workflowId" type="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`.
</ParamField>

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

<ResponseField name="runId" type="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](/api-reference/runs/get).
</ResponseField>

<ResponseField name="status" type="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.
</ResponseField>

### Example Response

```json theme={null}
{
  "runId": "run_xyz789abc",
  "status": "PENDING"
}
```

<Note>
  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](/api-reference/runs/get) and track when the status advances from `PENDING` → `RUNNING` → `SUCCESS` (or `FAILED`).
</Note>

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

<Tip>
  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](/api-reference/runs/list) to watch the queue drain sequentially, or poll individual run IDs for fine-grained status tracking.
</Tip>

## curl Example

```bash theme={null}
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](/api-reference/runs/get) to retrieve the current status and per-node output of that specific run.
* **List all runs** — use [GET /api/workflows/:workflowId/runs](/api-reference/runs/list) to see the full queue for a workflow, including which runs are `PENDING`, `RUNNING`, or already `SUCCESS`.