> ## Documentation Index > Fetch the complete documentation index at: https://enterprise-docs.dify.ai/llms.txt > Use this file to discover all available pages before exploring further. # Run Workflow > **Available for**: Workflow Runs the deployed Workflow version, in blocking or streaming mode. **Standard API equivalent**: [Run Workflow](/en/3.13.x/develop/api/workflow-runs/run-workflow). Differences: - `workflow_id` and any unknown body field are ignored. - `trace_id` and `trace_session_id` are accepted. - The request body is capped at 8 MiB. - The stream omits TTS, human-input, agent-log, and retrieval-resource events. A run that reaches a human-input step fails. - Error codes differ. ## OpenAPI ````yaml /en/3.13.x/develop/api/openapi_service.json post /v2/workflows/run openapi: 3.0.1 info: title: Dify Service API description: >- REST API for Dify applications and knowledge bases. Application endpoints authenticate with an app API key; knowledge endpoints authenticate with a dataset API key. version: 1.0.0 servers: - url: https://{api_base_url} description: >- Base URL of the Dify Service API. Replace it with your deployment's API endpoint. variables: api_base_url: default: api.example.com/v1 description: Host and path of the API base URL, without the `https://` prefix. security: - ApiKeyAuth: [] tags: - name: Chat Messages description: Operations related to chat messages and interactions. - name: Files description: File upload and preview operations. - name: End Users description: Operations related to end user information. - name: Feedback description: User feedback operations. - name: Conversations description: Operations related to managing conversations. - name: Audio description: Text-to-Speech and Speech-to-Text operations. - name: Applications description: Operations to retrieve application settings and information. - name: Annotations description: Operations related to managing annotations for direct replies. - name: Human Input description: Endpoints for resuming paused workflows that require human input. - name: Workflow Runs description: Operations for executing and managing workflows. - name: Completion Messages description: Operations related to text generation and completion. - name: Knowledge Bases description: >- Operations for managing knowledge bases, including creation, configuration, and retrieval. - name: Documents description: >- Operations for creating, updating, and managing documents within a knowledge base. - name: Chunks description: Operations for managing document chunks and child chunks. - name: Metadata description: >- Operations for managing knowledge base metadata fields and document metadata values. - name: Tags description: Operations for managing knowledge base tags and tag bindings. - name: Models description: Operations for retrieving available models. - name: Knowledge Pipeline description: >- Operations for managing and running knowledge pipelines, including datasource plugins and pipeline execution. - name: Deployed Environments description: >- Endpoints served by deployed environments over the `v2` base URL. Deployed environments serve only the endpoints in this group; calling any other path there returns `404 not_found`. Authentication and errors differ from the standard Service API; each page here is authoritative for deployed environments. paths: /v2/workflows/run: post: tags: - Deployed Environments summary: Run Workflow description: >- **Available for**: Workflow Runs the deployed Workflow version, in blocking or streaming mode. **Standard API equivalent**: [Run Workflow](/en/3.13.x/develop/api/workflow-runs/run-workflow). Differences: - `workflow_id` and any unknown body field are ignored. - `trace_id` and `trace_session_id` are accepted. - The request body is capped at 8 MiB. - The stream omits TTS, human-input, agent-log, and retrieval-resource events. A run that reaches a human-input step fails. - Error codes differ. operationId: runDeployedWorkflow parameters: - name: X-Trace-Id in: header required: false schema: type: string description: Same as the `trace_id` body field, checked first. - name: trace_id in: query required: false schema: type: string description: Same as the `trace_id` body field, checked after the header. - name: X-Trace-Session-Id in: header required: false schema: type: string description: Same as the `trace_session_id` body field, checked first. - name: trace_session_id in: query required: false schema: type: string description: Same as the `trace_session_id` body field, checked after the header. requestBody: required: true content: application/json: schema: type: object required: - inputs - user properties: inputs: type: object description: >- Values for the app's input variables, keyed by variable name. Use the input variables defined in the version currently deployed to the target environment. Pass a file object for a single-file variable, or an array of file objects for a file-list variable. Each file object has the same structure as an item in `files`. additionalProperties: oneOf: - type: string - type: number - type: boolean - type: object - type: array items: type: object required: - type properties: type: type: string enum: - image - document - audio - video - custom description: >- File type. For an uploaded file it must match the type Dify detected when the file was stored, unless you declare `custom`. transfer_method: type: string enum: - remote_url - local_file description: >- Transfer method: `remote_url` for a file URL, `local_file` for an uploaded file. An entry that omits this field is ignored rather than rejected. url: type: string format: url description: File URL for a `remote_url` entry. upload_file_id: type: string description: >- The `id` from [Upload File](/en/3.13.x/develop/api/deployed-environments/upload-file). Required when `transfer_method` is `local_file`. response_mode: type: string enum: - streaming - blocking description: >- How the response is delivered. - `streaming`: events arrive as the run produces them. Use it for anything longer than a quick reply. - `blocking`: one response once the run completes. default: blocking user: type: string description: >- 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/3.13.x/develop/api/guides/end-user-identity). files: type: array items: type: object required: - type properties: type: type: string enum: - image - document - audio - video - custom description: >- File type. For an uploaded file it must match the type Dify detected when the file was stored, unless you declare `custom`. transfer_method: type: string enum: - remote_url - local_file description: >- Transfer method: `remote_url` for a file URL, `local_file` for an uploaded file. An entry that omits this field is ignored rather than rejected. url: type: string format: url description: File URL for a `remote_url` entry. upload_file_id: type: string description: >- The `id` from [Upload File](/en/3.13.x/develop/api/deployed-environments/upload-file). Required when `transfer_method` is `local_file`. nullable: true description: >- Files to pass to the workflow. For a local file, first upload it via [Upload File](/en/3.13.x/develop/api/deployed-environments/upload-file), then reference the returned `id` as `upload_file_id` with `transfer_method: local_file`. The workflow's own file settings decide what is accepted, such as the allowed types and how many files. A workflow that accepts no files ignores these entries. trace_id: type: string description: >- Trace identifier propagated to observability data. Letters, digits, hyphens, and underscores are accepted, up to 128 characters. A value that does not match is skipped, not rejected. trace_session_id: type: string description: >- Trace session identifier propagated to observability data, 1 to 200 characters after trimming. minLength: 1 maxLength: 200 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 files: - type: image transfer_method: remote_url url: https://cloud.dify.ai/logo/logo-site.png 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: >- 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: type: object properties: task_id: type: string format: uuid description: >- Task ID for this run. In blocking mode it arrives only in this final body, so [Stop Workflow Task](/en/3.13.x/develop/api/deployed-environments/stop-workflow-task) is practical only with streaming. workflow_run_id: type: string format: uuid description: The workflow run's ID. data: 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: >- `succeeded`, `failed`, `partial-succeeded`, or `stopped`. 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. 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: examples: streaming: summary: Response Example - Streaming mode value: >+ event: ping data: {"event": "workflow_started", "task_id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f", "workflow_run_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "data": {"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "workflow_id": "b0e1d1a8-6c2f-4c8e-9d3e-1f2a3b4c5d6e", "inputs": {"query": "Summarize this text: The quick brown fox jumps over the lazy dog.", "sys.files": [], "sys.user_id": "user_workflow_123", "sys.app_id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "sys.workflow_id": "b0e1d1a8-6c2f-4c8e-9d3e-1f2a3b4c5d6e", "sys.workflow_run_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"}, "created_at": 1787788860, "reason": "initial"}} data: {"event": "text_chunk", "task_id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f", "workflow_run_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "data": {"text": "The sentence describes a fox jumping over a lazy dog.", "from_variable_selector": ["end", "result"]}} data: {"event": "workflow_finished", "task_id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f", "workflow_run_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "data": {"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a", "workflow_id": "b0e1d1a8-6c2f-4c8e-9d3e-1f2a3b4c5d6e", "status": "succeeded", "outputs": {"result": "The sentence describes a fox jumping over a lazy dog."}, "error": null, "elapsed_time": 1.2, "total_tokens": 31, "total_steps": 3, "created_by": {"id": "7d4e2f1b-8a9c-5b3d-9e6f-1a2b3c4d5e6f", "user": "user_workflow_123"}, "created_at": 1787788860, "finished_at": 1787788862, "exceptions_count": 0, "files": []}} schema: type: string description: >- Server-sent events; parse them per [SSE Streaming](/en/3.13.x/develop/api/guides/streaming). **Events**: `workflow_started` comes first. The node events follow: `node_started`, `node_finished`, `node_retry`, and the iteration and loop variants. `text_chunk` deltas arrive alongside them. Concatenate the `text_chunk` deltas in order to build the output. The closing frames depend on the outcome: - Success, partial success, or a stop: `workflow_finished` carries that `status`. - Workflow failure: `workflow_finished` with `status: failed` and the reason in `data.error`. - A failure discovered after the stream opened, such as a timeout, a cancel, or an internal error: an `error` frame, then the stream ends. A failure raised before the stream opened returns an ordinary HTTP error response even in streaming mode. 500 `execution_failed` and 504 `request_timeout` can only occur after the stream has opened. In streaming mode they therefore arrive as `error` frames, never as HTTP statuses. **Add-ons**: `ping` frames carry no data. One arrives when the stream opens, and another about every 10 s, including mid-output. When the model emits reasoning, `reasoning_chunk` deltas carry it. **Common fields**: apart from `ping` and `error`, every event carries `task_id` and `workflow_run_id`, with its payload under `data`. **`error` frames**: each carries `workflow_run_id` alongside `code`, `status`, and `message`. '400': description: >- - `invalid_param`: `inputs` or `user` is missing. Messages `inputs is required` and `user is required`. - `invalid_param`: `response_mode` is neither `blocking` nor `streaming`. Message `response_mode must be blocking or streaming`. - `invalid_param`: `trace_session_id` is the wrong type or the wrong length. Messages `trace_session_id must be a string` and `trace_session_id must be 1 to 200 characters after trimming`. - `invalid_request`: the body could not be parsed. Message `invalid request body`. - `invalid_request`: the API key belongs to an app that is not a Workflow. Message `run route does not match the deployed app mode`. - `invalid_request`: a file entry failed validation. The message names the problem, for example `unsupported file type`, `too many files`, `invalid upload_file_id`, `declared file type does not match the file`, `file input takes a single file`, or `file list input takes a list of files`. - `invalid_request`: `user` contains a NUL character. Message `workflow file is invalid`. - `invalid_request`: `user` starts or ends with whitespace. Message `workflow run identity is invalid`. - `invalid_request`: the body was rejected as too large. Message `request payload is too large`. content: application/json: examples: invalid_param: summary: invalid_param value: code: invalid_param message: inputs is required status: 400 invalid_request: summary: invalid_request value: code: invalid_request message: run route does not match the deployed app mode status: 400 invalid_request_file: summary: invalid_request (file entry) value: code: invalid_request message: declared file type does not match the file status: 400 '401': description: >- - `token_invalid`: the API key is missing, malformed, or unknown. - `unauthorized`: the API key has been revoked. - `runtime_identity_invalid`: the request's signed identity expired before the run was admitted. A slow upload can take long enough for that, so send the request again. content: application/json: examples: token_invalid: summary: token_invalid value: code: token_invalid message: invalid api token status: 401 unauthorized: summary: unauthorized value: code: unauthorized message: Access token is invalid status: 401 runtime_identity_invalid: summary: runtime_identity_invalid value: code: runtime_identity_invalid message: runtime identity is invalid status: 401 '403': description: '`forbidden`: the app''s API access is turned off in **Access Point**.' content: application/json: examples: forbidden: summary: forbidden value: code: forbidden message: The app's API service has been disabled. status: 403 '404': description: >- `not_found`: a file the request references by `upload_file_id` does not exist or belongs to another `user`. content: application/json: examples: not_found: summary: not_found value: code: not_found message: workflow file was not found status: 404 '409': description: >- - `request_canceled`: a stop arrived after the run started, and the run didn't end cleanly in time. Otherwise, a stop ends the run with status `stopped` instead of this error. - `request_canceled`: the deployment changed while the run was in flight, so the run was canceled. Retry against the current deployment. content: application/json: examples: request_canceled_mid_run: summary: request_canceled (stopped) value: code: request_canceled message: request canceled status: 409 request_canceled_deployment_changed: summary: request_canceled (deployment changed) value: code: request_canceled message: deployment changed; retry against the current deployment status: 409 '413': description: >- `request_too_large`: the request body exceeds 8 MiB. A second size check later in the run reports the same message as a 400 `invalid_request`. content: application/json: examples: request_too_large: summary: request_too_large value: code: request_too_large message: request payload is too large status: 413 '429': description: >- `queue_full`: the environment's run queue is full; retry with backoff. content: application/json: examples: queue_full: summary: queue_full value: code: queue_full message: worker queue is full status: 429 '500': description: >- - `execution_failed`: the workflow couldn't be executed. A run that reaches a human-input step fails this way. Check the run in **Invocation Logs** and fix the workflow before retrying. - `internal_error`: the environment hit an error unrelated to your request; retry, and contact your administrator if it persists. - `internal_error`: in blocking mode, the run ended without a result. Retry, and contact your administrator if it persists. - `internal_server_error`: in streaming mode, the run ended without a result. It arrives in the stream as an `error` event with `status: 500`. Retry, and contact your administrator if it persists. content: application/json: examples: execution_failed: summary: execution_failed value: code: execution_failed message: workflow execution failed status: 500 execution_failed_request: summary: execution_failed (request failed) value: code: execution_failed message: workflow request failed status: 500 internal_error: summary: internal_error value: code: internal_error message: internal error status: 500 internal_server_error: summary: internal_server_error value: code: internal_server_error message: Internal Server Error, please contact support. status: 500 '503': description: >- - `deployment_undeployed`: the app is undeployed from this environment. - `deployment_not_ready`: a deployment is in progress; retry shortly. - `apprunner_not_deployed`: the environment is not available, for example while it is being deleted. - `enterprise_unavailable`: a platform-side routing service is temporarily unavailable; retry shortly. - `service_not_ready`: the deployed version isn't ready to serve in this environment; retry shortly. - `service_not_ready`: `user` is longer than 512 bytes, or the run references more than 100 different files. Message `run admission is temporarily unavailable`. Retrying doesn't help: shorten `user` or send fewer files. content: application/json: examples: deployment_undeployed: summary: deployment_undeployed value: code: deployment_undeployed message: deployment is not deployed status: 503 deployment_not_ready: summary: deployment_not_ready value: code: deployment_not_ready message: deployment is in progress status: 503 apprunner_not_deployed: summary: apprunner_not_deployed value: code: apprunner_not_deployed message: apprunner not deployed for this environment status: 503 enterprise_unavailable: summary: enterprise_unavailable value: code: enterprise_unavailable message: enterprise routing service unavailable status: 503 service_not_ready: summary: service_not_ready value: code: service_not_ready message: revision is not serving status: 503 service_not_ready_admission: summary: service_not_ready (oversized request) value: code: service_not_ready message: run admission is temporarily unavailable status: 503 '504': description: >- `request_timeout`: the run exceeded the platform's maximum execution time for a workflow run and was stopped. Your platform's administrators set this limit. content: application/json: examples: request_timeout: summary: request_timeout value: code: request_timeout message: request timed out status: 504 servers: - url: https://{deployed_api_base_url} description: >- Base URL shared by every deployed environment: the standard Service API address, with `/v2` in place of `/v1`. variables: deployed_api_base_url: default: api.example.com description: >- On the app's **Access Point** tab, copy the full URL from any deployed environment's **Backend Service API** card, then remove the `https://` prefix and the trailing `/v2`. components: securitySchemes: ApiKeyAuth: type: http scheme: bearer bearerFormat: API_KEY description: >- Every request authenticates with an API key: `Authorization: Bearer {API_KEY}`. App endpoints take an app API key; knowledge endpoints take a knowledge base API key ([Get Started](/en/3.13.x/develop/api/guides/get-started)). Keep keys server-side; never embed them in client code. Requests with a missing or invalid key fail with HTTP `401` (`unauthorized`). ````