---
title: "Run Workflow by ID"
method: POST
path: "/workflows/{workflow_id}/run"
tags: ["Workflow Runs"]
---

# Run Workflow by ID

`POST /workflows/{workflow_id}/run`

**Available for**: Workflow apps.

Run a specific published workflow version, identified by the `workflow_id` in the path. Request body, response, and streaming behavior match [Run Workflow](/en/api-reference/workflow-runs/run-workflow); only the executed version differs.

## Path parameters

- `workflow_id` string, required

## Request body

- WorkflowExecutionRequest — unresolved $ref

## Response `200`

Successful response. The content type and structure depend on the `response_mode` parameter in the request.

- If `response_mode` is `blocking`, returns `application/json` with a `WorkflowBlockingResponse` object.
- If `response_mode` is `streaming`, returns `text/event-stream` with a stream of `ChunkWorkflowEvent` objects.

- WorkflowBlockingResponse
  - `task_id` string, uuid — Task ID for the in-progress execution. Use this with [Stop Workflow Task](/en/api-reference/workflow-runs/stop-workflow-task) to cancel a running workflow. Only valid during execution.
  - `workflow_run_id` string, uuid — Persistent identifier for this workflow run record. Use this with [Get Workflow Run Detail](/en/api-reference/workflow-runs/get-workflow-run-detail) to retrieve results after execution.
  - `data` WorkflowFinishedData
    - `id` string, uuid — Workflow run ID.
    - `workflow_id` string, uuid — Workflow ID.
    - `status` string — Workflow execution status. `running` for in-progress executions, `succeeded` when completed successfully, `failed` when execution encountered an error, `stopped` when manually halted, `partial-succeeded` when some nodes succeeded but others failed, `paused` when awaiting human input.
    - `outputs` object, nullable — Output data from the workflow.
    - `error` string, nullable — Error message if the workflow failed.
    - `elapsed_time` number, float — Total time elapsed in seconds.
    - `total_tokens` integer — Total tokens consumed across all nodes.
    - `total_steps` integer — Total number of workflow steps executed.
    - `created_at` integer — Unix timestamp of when the workflow run was created.
    - `finished_at` integer, nullable — Unix timestamp of when the workflow run finished.
    - `created_by` object — Creator information. Only present in streaming `workflow_finished` events.
    - `exceptions_count` integer, nullable — Number of exceptions encountered during execution. Only present in streaming `workflow_finished` events.
    - `files` object[], nullable — Files generated during workflow execution. Only present in streaming `workflow_finished` events.

## Other responses

- `400` — - `not_workflow_app` : App mode does not match the API route. - `bad_request` : Workflow is a draft or has an invalid ID format. - `provider_not_initialize` : No valid model provider credentials found. - `provider_quota_exceeded` : Model provider quota exhausted. - `model_currently_not_support` : Current model unavailable. - `completion_request_error` : Workflow execution request failed. - `invalid_param` : A request parameter is missing or invalid, such as a missing `user`.
- `403` — `workflow_version_execution_not_allowed` : Executing a specific workflow version is not available on the Dify Cloud Sandbox plan.
- `404` — `not_found` : Workflow not found.
- `429` — - `too_many_requests` : Too many concurrent requests for this app. - `rate_limit_error` : The Dify Cloud workflow execution quota for this workspace has been reached.
- `500` — `internal_server_error` : Internal server error.

## Changes

- **2026-07-17** `3ff4555d5dda` — 1 info
  - added the non-success response with the status `403`

[Change history](https://skmtc.dev/langgenius/apis/dify-service-api/changes/workflows/:workflow_id/run/post.md)

---

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