---
title: "POST /v1/workflows/{id}/run"
method: POST
path: "/v1/workflows/{id}/run"
---

# POST /v1/workflows/{id}/run

`POST /v1/workflows/{id}/run`

Run a workflow with optional payload. Works for draft, active, and paused workflows. Does not count against maxRuns or enforce cooldown.

## Path parameters

- `id` string, required

## Request body

- union
  - object
  - RunParams
    - `chatMessageId` string — Optional assistant chat message that launched this run.
    - `dustTest` boolean — When true, run with auto-calculated dust amounts (~$0.01 USD). Mutually exclusive with Simulate.
    - `payload` object — Optional payload
    - `runId` string — Optional run ID. If provided, must start with "run_" prefix. Use this to subscribe to SSE stream before triggering the run.
    - `simulate` boolean — When true, run the workflow in simulation mode (dry-run).
    - `triggerNodeId` string — For multi-trigger ("forest") workflows: which trigger node should be recorded as the firing trigger for this run. Optional — when omitted the workflow's manual trigger is resolved by type, matching the historical single-trigger behavior. The trigger picker in the editor sends this so the resulting run is attributed to the trigger the user actually clicked.
    - `version` integer — Optional version number. When set, run this specific version instead of the default (which prioritizes draft). Useful for testing the live version while a draft exists.

## Response `200`

OK

- RunSuccessResponse
  - `code` integer
  - `data` RunResponse
    - `runId` string
  - `message` string
  - `requestId` string

## Other responses

- `400` — Bad request or workflow is archived
- `404` — Workflow not found

---

[API](https://skmtc.dev/b3os/apis/b3os-workflow-api.md) · [All operations](https://skmtc.dev/b3os/apis/b3os-workflow-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/b3os/b3os-workflow-api/revisions/a8c7af3c66a1/schema)