Run Workflow - Dify Docs

post/workflows/run

Request example

curl --request POST \
  --url https://api.dify.ai/v1/workflows/run \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "inputs": {
    "query": "Translate this to French: Hello world"
  },
  "response_mode": "blocking",
  "user": "user_workflow_456"
}'

import requests

url = "https://api.dify.ai/v1/workflows/run"
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json",
}
payload = {
    "inputs": {
        "query": "Translate this to French: Hello world"
    },
    "response_mode": "blocking",
    "user": "user_workflow_456"
}

response = requests.request("POST", url, headers=headers, json=payload)

print(response.text)

const response = await fetch('https://api.dify.ai/v1/workflows/run', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "inputs": {
      "query": "Translate this to French: Hello world"
    },
    "response_mode": "blocking",
    "user": "user_workflow_456"
  })
});

const data = await response.json();
console.log(data);

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => 'https://api.dify.ai/v1/workflows/run',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS => '{
  "inputs": {
    "query": "Translate this to French: Hello world"
  },
  "response_mode": "blocking",
  "user": "user_workflow_456"
}',
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer <token>',
    'Content-Type: application/json',
  ],
]);

$response = curl_exec($curl);
curl_close($curl);

echo $response;

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	url := "https://api.dify.ai/v1/workflows/run"
	payload := strings.NewReader("{\n  \"inputs\": {\n    \"query\": \"Translate this to French: Hello world\"\n  },\n  \"response_mode\": \"blocking\",\n  \"user\": \"user_workflow_456\"\n}")

	req, _ := http.NewRequest("POST", url, payload)
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))
}

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.dify.ai/v1/workflows/run"))
    .header("Authorization", "Bearer <token>")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\n  \"inputs\": {\n    \"query\": \"Translate this to French: Hello world\"\n  },\n  \"response_mode\": \"blocking\",\n  \"user\": \"user_workflow_456\"\n}"))
    .build();

HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());

System.out.println(response.body());

require 'uri'
require 'net/http'

url = URI('https://api.dify.ai/v1/workflows/run')

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = url.scheme == 'https'

request = Net::HTTP::Post.new(url)
request['Authorization'] = 'Bearer <token>'
request['Content-Type'] = 'application/json'
request.body = '{
  "inputs": {
    "query": "Translate this to French: Hello world"
  },
  "response_mode": "blocking",
  "user": "user_workflow_456"
}'

response = http.request(request)
puts response.read_body

Response

{
  "data": {
    "created_at": 1705407629,
    "elapsed_time": 1.23,
    "error": null,
    "finished_at": 1705407630,
    "id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156",
    "outputs": {
      "result": "Bonjour le monde"
    },
    "status": "succeeded",
    "total_steps": 3,
    "total_tokens": 150,
    "workflow_id": "7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345"
  },
  "task_id": "c3800678-a077-43df-a102-53f23ed20b88",
  "workflow_run_id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156"
}

event: ping

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": "paragraph", "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}}

event: ping

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": "reasoning_chunk", "task_id": "c3800678-a077-43df-a102-53f23ed20b88", "workflow_run_id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", "data": {"reasoning": "Let me translate that.", "node_id": "node_1", "is_final": false}}

data: {"event": "reasoning_chunk", "task_id": "c3800678-a077-43df-a102-53f23ed20b88", "workflow_run_id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", "data": {"reasoning": "", "node_id": "node_1", "is_final": true}}

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}}

{
  "code": "completion_request_error",
  "message": "Completion request failed.",
  "status": 400
}

{
  "code": "invalid_param",
  "message": "Arg user must be provided.",
  "status": 400
}

{
  "code": "model_currently_not_support",
  "message": "Dify Hosted OpenAI trial currently not support the GPT-4 model.",
  "status": 400
}

{
  "code": "not_workflow_app",
  "message": "Please check if your app mode matches the right API route.",
  "status": 400
}

{
  "code": "provider_not_initialize",
  "message": "No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials.",
  "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.",
  "status": 400
}

{
  "code": "trigger_workflow_service_mode_unavailable",
  "message": "This workflow uses a trigger entry and cannot be invoked through Web App, Service API, OpenAPI, or MCP.",
  "status": 403
}

{
  "code": "rate_limit_error",
  "message": "Workflow execution quota limit reached for tenant 8f1e2a90-3b7c-4d55-9a01-6c2f4e8b1d33",
  "status": 429
}

{
  "code": "too_many_requests",
  "message": "Too many requests. Please try again later.",
  "status": 429
}

{
  "code": "internal_server_error",
  "message": "Internal Server Error.",
  "status": 500
}

post/workflows/run

Authorization

Authorizationstringheaderrequired#

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).

Keep keys server-side; never embed them in client code. Requests with a missing or invalid key fail with HTTP 401 (unauthorized).

Body

application/json

filesobject[]#

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 and use the returned id as upload_file_id with transfer_method: local_file.

Show child attributes

Any of

transfer_methodenum<string>#

Options:remote_url

urlstringrequired#

transfer_methodenum<string>#

Options:local_file

upload_file_idstringrequired#

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.

File-type variables take an array of file objects with type, transfer_method, and either url or upload_file_id.

Show child attributes

{key}string · number · boolean · object · object[]#

Show child attributes

One of

Any of

transfer_methodenum<string>#

Options:remote_url

urlstringrequired#

transfer_methodenum<string>#

Options:local_file

upload_file_idstringrequired#

response_modeenum<string>#

Response mode. Use blocking for synchronous responses (Cloudflare timeout is 100 s), or streaming for Server-Sent Events. When omitted, defaults to blocking behavior.

Options: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.

Responses

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.

dataobject#

Show child attributes

created_atinteger#

Unix timestamp of when the workflow run was created.

created_byobject#

Creator information. Only present in streaming workflow_finished events.

elapsed_timenumber#

Total time elapsed in seconds.

errorstring#

Error message if the workflow failed.

exceptions_countinteger#

Number of exceptions encountered during execution. Only present in streaming workflow_finished events.

filesobject[]#

Files generated during workflow execution. Only present in streaming workflow_finished events.

finished_atinteger#

Unix timestamp of when the workflow run finished.

idstring#

Workflow run ID.

outputsobject#

Output data from the workflow.

statusstring#

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.

total_stepsinteger#

Total number of workflow steps executed.

total_tokensinteger#

Total tokens consumed across all nodes.

workflow_idstring#

Workflow ID.

task_idstring#

Task ID for the in-progress execution. Use this with Stop Workflow Task to cancel a running workflow. Only valid during execution.

workflow_run_idstring#

Persistent identifier for this workflow run record. Use this with Get Workflow Run Detail to retrieve results after execution.

Stop Completion Message Generation Run Workflow by ID