Dify Octri Demo
POST/workflows/{workflow_id}/run

Run Workflow by ID

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; only the executed version differs.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

1 parameter · 4 body fields
workflow_idstringrequired
Published workflow version to run. Returned in the `workflow_id` field of [Run Workflow](/en/api-reference/workflow-runs/run-workflow) responses and [Get Workflow Run Detail](/en/api-reference/workflow-runs/get-workflow-run-detail). Must reference a published version; a draft version ID is rejected with `bad_request`.
filesarray<object>optional
File list. Suitable when files need to be combined with text for input, available only when the model supports Vision capability. To attach a local file, first upload it via [Upload File](/en/api-reference/files/upload-file) and use the returned `id` as `upload_file_id` with `transfer_method: local_file`.
inputsobjectrequired
Key-value pairs for workflow input variables. Discover the variable names and types your app expects from the `user_input_form` field of [Get App Parameters](/en/api-reference/applications/get-app-parameters). File-type variables take an array of file objects with `type`, `transfer_method`, and either `url` or `upload_file_id`.
response_modestringoptional
Response mode. Use `blocking` for synchronous responses (Cloudflare timeout is `100 s`), or `streaming` for Server-Sent Events. When omitted, defaults to blocking behavior.
Allowed:streamingblocking
userstringrequired
End-user identifier, defined by your app and unique within it. Scopes data access: a workflow run and its files are only visible to later requests that carry the same `user`. See [End User Identity](/en/api-reference/guides/end-user-identity).

6 status codes
200Successful 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.
dataobjectoptional
task_idstringoptional
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_idstringoptional
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.
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`.

7 documented failures

  • bad_request

    Cannot use draft workflow version. Workflow ID: 7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345. Please use a published workflow version or leave workflow_id empty.

    bad_request

  • completion_request_error

    Completion request failed.

    completion_request_error

  • invalid_param

    Arg user must be provided.

    invalid_param

  • model_currently_not_support

    Dify Hosted OpenAI trial currently not support the GPT-4 model.

    model_currently_not_support

  • not_workflow_app

    Please check if your app mode matches the right API route.

    not_workflow_app

  • provider_not_initialize

    No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials.

    provider_not_initialize

  • provider_quota_exceeded

    Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials.

    provider_quota_exceeded

403- `workflow_version_execution_not_allowed` : Executing a specific workflow version is not available on the Dify Cloud Sandbox plan. - `trigger_workflow_service_mode_unavailable` : The selected workflow version starts from a trigger node, so it runs only from its trigger events. Only the selected version is checked, so a version that starts from a User Input node can still be run by ID.

2 documented failures

  • trigger_workflow_service_mode_unavailable

    This workflow uses a trigger entry and cannot be invoked through Web App, Service API, OpenAPI, or MCP.

    trigger_workflow_service_mode_unavailable

  • workflow_version_execution_not_allowed

    Workflow version execution is not available on your current plan. Please upgrade to a paid plan.

    workflow_version_execution_not_allowed

404`not_found` : Workflow not found.

One documented failure

  • not_found

    Workflow not found with id: 7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345

    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.

2 documented failures

  • rate_limit_error

    Workflow execution quota limit reached for tenant 8f1e2a90-3b7c-4d55-9a01-6c2f4e8b1d33

    rate_limit_error

  • too_many_requests

    Too many requests. Please try again later.

    too_many_requests

500`internal_server_error` : Internal server error.

One documented failure

  • internal_server_error

    Internal Server Error.

    internal_server_error

Error handling

A 400 is returned: - 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. A 403 is returned: - workflow_version_execution_not_allowed : Executing a specific workflow version is not available on the Dify Cloud Sandbox plan.
  • trigger_workflow_service_mode_unavailable : The selected workflow version starts from a trigger node, so it runs only from its trigger events. Only the selected version is checked, so a version that starts from a User Input node can still be run by ID. A 404 is returned: not_found : Workflow not found. A 429 is returned: - 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. A 500 is returned: internal_server_error : Internal server error.