---
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 and active workflows. Does not count against maxRuns or enforce cooldown.

## Path parameters

- `id` string, required

## Request body

- union
  - object
  - RunParams
    - `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.
    - `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 not runnable (paused/archived)
- `404` — Workflow not found

---

[API](https://skmtc.net/b3-fun/apis/b3os-workflow-api.md) · [All operations](https://skmtc.net/b3-fun/apis/b3os-workflow-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/b3-fun/b3os-workflow-api/versions/5a750a5a9596/schema)