> ## Documentation Index > Fetch the complete documentation index at: https://docs.dify.ai/llms.txt > Use this file to discover all available pages before exploring further. # Run Workflow > Execute a workflow. Cannot be executed without a published workflow. ## OpenAPI ````yaml /en/api-reference/openapi_workflow.json post /workflows/run openapi: 3.0.1 info: title: Workflow App API description: >- Workflow applications offer non-session support and are ideal for translation, article writing, summarization AI, and more. version: 1.0.0 servers: - url: '{api_base_url}' description: >- The base URL for the Workflow App API. Replace {api_base_url} with the actual API base URL. variables: api_base_url: default: https://api.dify.ai/v1 description: Actual base URL of the API security: - ApiKeyAuth: [] tags: - name: Workflows description: Operations for executing and managing workflows. - name: Files description: File upload and download operations. - name: End Users description: Operations related to end user information. - name: TTS description: Audio-to-text and text-to-audio conversion. - name: Applications description: Application settings, parameters, and metadata. - name: Human Input description: Endpoints for resuming paused workflows that require human input. paths: /workflows/run: post: tags: - Workflows summary: Run Workflow description: Execute a workflow. Cannot be executed without a published workflow. operationId: executeWorkflow requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WorkflowExecutionRequest' examples: streaming_example: summary: Request Example - Streaming mode value: inputs: query: >- Summarize this text: The quick brown fox jumps over the lazy dog. response_mode: streaming user: user_workflow_123 blocking_example: summary: Request Example - Blocking mode value: inputs: query: 'Translate this to French: Hello world' response_mode: blocking user: user_workflow_456 with_file_array_variable: summary: Request Example - File array input value: inputs: my_documents: - type: document transfer_method: local_file upload_file_id: a1b2c3d4-5678-90ab-cdef-1234567890ab - type: image transfer_method: remote_url url: https://example.com/image.jpg response_mode: blocking user: user_workflow_789 responses: '200': description: >- 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. content: application/json: schema: $ref: '#/components/schemas/WorkflowBlockingResponse' examples: blockingResponse: summary: Response Example - Blocking mode value: task_id: c3800678-a077-43df-a102-53f23ed20b88 workflow_run_id: fb47b2e6-5e43-4f90-be01-d5c5a088d156 data: id: fb47b2e6-5e43-4f90-be01-d5c5a088d156 workflow_id: 7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345 status: succeeded outputs: result: Bonjour le monde error: null elapsed_time: 1.23 total_tokens: 150 total_steps: 3 created_at: 1705407629 finished_at: 1705407630 text/event-stream: schema: type: string description: >- A stream of Server-Sent Events (SSE). **Parsing**: Each line begins with `data: ` followed by a JSON object, terminated by `\n\n`. Strip the `data: ` prefix before parsing the JSON, then read the `event` field to determine the event type. Ignore `ping` events, which fire every 10 seconds to keep the connection alive. **Stream lifecycle**: The stream closes when a `workflow_finished`, `workflow_paused`, or `error` event is received. Errors are delivered in-stream with HTTP status `200`; inspect the event payload for details rather than relying on the status code. **Human Input events**: - `human_input_required`: Fires together with `workflow_paused` when the workflow reaches a Human Input node. Use the `form_token` from the payload to drive the form-handling flow via the [Human Input API](/api-reference/human-input/get-human-input-form). - `human_input_form_filled`: A recipient submitted the form; workflow execution resumes. - `human_input_form_timeout`: The form expired without a response. Workflow follows the timeout fallback edge if defined. examples: streamingResponse: summary: Response Example - Streaming mode value: >- data: {"event": "workflow_started", "task_id": "c3800678-a077-43df-a102-53f23ed20b88", "workflow_run_id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", "data": {"id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", "workflow_id": "7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345", "inputs": {"query": "Translate this"}, "created_at": 1705407629, "reason": "initial"}} data: {"event": "node_started", "task_id": "c3800678-a077-43df-a102-53f23ed20b88", "workflow_run_id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", "data": {"id": "node_exec_1", "node_id": "node_1", "node_type": "llm", "title": "LLM Node", "index": 1, "created_at": 1705407629}} data: {"event": "text_chunk", "task_id": "c3800678-a077-43df-a102-53f23ed20b88", "workflow_run_id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", "data": {"text": "Bonjour", "from_variable_selector": ["node_1", "text"]}} data: {"event": "workflow_finished", "task_id": "c3800678-a077-43df-a102-53f23ed20b88", "workflow_run_id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", "data": {"id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", "workflow_id": "7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345", "status": "succeeded", "outputs": {"result": "Bonjour le monde"}, "elapsed_time": 1.23, "total_tokens": 150, "total_steps": 3, "created_at": 1705407629, "finished_at": 1705407630}} humanInputPause: summary: Response Example - Human Input pause value: >- data: {"event": "workflow_started", "task_id": "c3800678-a077-43df-a102-53f23ed20b88", "workflow_run_id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", "data": {"id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", "workflow_id": "7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345", "inputs": {"draft": "Hello"}, "created_at": 1705407629, "reason": "initial"}} data: {"event": "human_input_required", "task_id": "c3800678-a077-43df-a102-53f23ed20b88", "workflow_run_id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", "data": {"form_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "form_token": "tok_abc123", "node_id": "approval_node", "node_title": "Approval", "form_content": "Please review the draft.", "inputs": [{"type": "text_input", "output_variable_name": "comment", "default": null}], "actions": [{"id": "approve", "title": "Approve", "button_style": "primary"}], "display_in_ui": false, "resolved_default_values": {"comment": ""}, "expiration_time": 1705494029}} data: {"event": "workflow_paused", "task_id": "c3800678-a077-43df-a102-53f23ed20b88", "workflow_run_id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", "data": {"workflow_run_id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", "status": "paused", "created_at": 1705407629, "elapsed_time": 0.5}} '400': description: >- - `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` : Invalid parameter value. content: application/json: examples: not_workflow_app: summary: not_workflow_app value: status: 400 code: not_workflow_app message: Please check if your app mode matches the right API route. provider_not_initialize: summary: provider_not_initialize value: status: 400 code: provider_not_initialize message: >- No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials. provider_quota_exceeded: summary: provider_quota_exceeded value: status: 400 code: provider_quota_exceeded message: >- Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials. model_currently_not_support: summary: model_currently_not_support value: status: 400 code: model_currently_not_support message: >- Dify Hosted OpenAI trial currently not support the GPT-4 model. completion_request_error: summary: completion_request_error value: status: 400 code: completion_request_error message: Completion request failed. invalid_param: summary: invalid_param value: status: 400 code: invalid_param message: Arg user must be provided. '429': description: >- - `too_many_requests` : Too many concurrent requests for this app. - `rate_limit_error` : The upstream model provider rate limit was exceeded. content: application/json: examples: too_many_requests: summary: too_many_requests value: status: 429 code: too_many_requests message: Too many requests. Please try again later. rate_limit_error: summary: rate_limit_error value: status: 429 code: rate_limit_error message: Rate Limit Error '500': description: '`internal_server_error` : Internal server error.' content: application/json: examples: internal_server_error: summary: internal_server_error value: status: 500 code: internal_server_error message: Internal Server Error. components: schemas: WorkflowExecutionRequest: type: object required: - inputs - user properties: inputs: type: object description: >- Key-value pairs for workflow input variables. Values for file-type variables should be arrays of file objects with `type`, `transfer_method`, and either `url` or `upload_file_id`. Refer to the `user_input_form` field in the [Get App Parameters](/api-reference/applications/get-app-parameters) response to discover the variable names and types expected by your app. additionalProperties: oneOf: - type: string - type: number - type: boolean - type: object - type: array items: $ref: '#/components/schemas/InputFileObject' response_mode: type: string enum: - streaming - blocking description: >- Response mode. Use `blocking` for synchronous responses (Cloudflare timeout is `100 s`), or `streaming` for Server-Sent Events. When omitted, defaults to blocking behavior. user: type: string description: >- User identifier, defined by the developer's rules, must be unique within the application. This identifier scopes data access — workflow runs and files are only visible when queried with the same `user` value. files: type: array items: $ref: '#/components/schemas/InputFileObject' nullable: true description: >- 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](/api-reference/files/upload-file) and use the returned `id` as `upload_file_id` with `transfer_method: local_file`. WorkflowBlockingResponse: type: object properties: task_id: type: string format: uuid description: >- Task ID for the in-progress execution. Use this with [Stop Workflow Task](/api-reference/workflows/stop-workflow-task) to cancel a running workflow. Only valid during execution. workflow_run_id: type: string format: uuid description: >- Persistent identifier for this workflow run record. Use this with [Get Workflow Run Detail](/api-reference/workflows/get-workflow-run-detail) to retrieve results after execution. data: $ref: '#/components/schemas/WorkflowFinishedData' InputFileObject: type: object required: - type - transfer_method properties: type: type: string enum: - document - image - audio - video - custom description: File type. transfer_method: type: string enum: - remote_url - local_file description: >- Transfer method: `remote_url` for file URL, `local_file` for uploaded file. url: type: string format: url description: File URL (when `transfer_method` is `remote_url`). upload_file_id: type: string description: >- Uploaded file ID obtained from the [Upload File](/api-reference/files/upload-file) API (when `transfer_method` is `local_file`). WorkflowFinishedData: type: object properties: id: type: string format: uuid description: Workflow run ID. workflow_id: type: string format: uuid description: Workflow ID. status: type: string description: >- 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: type: object additionalProperties: true nullable: true description: Output data from the workflow. error: type: string nullable: true description: Error message if the workflow failed. elapsed_time: type: number format: float description: Total time elapsed in seconds. total_tokens: type: integer description: Total tokens consumed across all nodes. total_steps: type: integer description: Total number of workflow steps executed. created_at: type: integer format: int64 description: Unix timestamp of when the workflow run was created. finished_at: type: integer format: int64 nullable: true description: Unix timestamp of when the workflow run finished. created_by: type: object additionalProperties: true description: >- Creator information. Only present in streaming `workflow_finished` events. exceptions_count: type: integer nullable: true description: >- Number of exceptions encountered during execution. Only present in streaming `workflow_finished` events. files: type: array items: type: object additionalProperties: true nullable: true description: >- Files generated during workflow execution. Only present in streaming `workflow_finished` events. securitySchemes: ApiKeyAuth: type: http scheme: bearer bearerFormat: API_KEY description: >- API Key authentication. For all API requests, include your API Key in the `Authorization` HTTP Header, prefixed with `Bearer `. Example: `Authorization: Bearer {API_KEY}`. **Strongly recommend storing your API Key on the server-side, not shared or stored on the client-side, to avoid possible API-Key leakage that can lead to serious consequences.** ````