Dify Octri Demo
POST/workflows/run

Run Workflow

Available for: Workflow apps.

Run the app's published workflow and return its outputs, either in a single blocking response or as a streaming Server-Sent Events feed. Requires a published workflow.

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

4 body fields
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).

5 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. - `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` or an unpublished workflow.

6 documented failures

  • 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`trigger_workflow_service_mode_unavailable` : The workflow starts from a trigger node, so it runs only from its trigger events. Only workflows that start from a User Input node can be run through the API.

One documented failure

  • 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

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.

  • 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 or an unpublished workflow. A 403 is returned: trigger_workflow_service_mode_unavailable : The workflow starts from a trigger node, so it runs only from its trigger events. Only workflows that start from a User Input node can be run through the API. 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.