Workflows

Dify — Workflows

Running Workflow-type apps via the API. These execute a graph of nodes and return structured outputs — no conversation, no query. For auth/base URL see setup; for the SSE node events see the chat-completion skill's references/streaming-events.md.

Chatflow apps are sent via /chat-messages (see chat-completion skill) but emit the same workflow node events. Plain Workflow apps use the /workflows/run endpoints here.

POST /workflows/run — execute a workflow

curl -X POST 'https://api.dify.ai/v1/workflows/run' \
  --header 'Authorization: Bearer app-XXXX' \
  --header 'Content-Type: application/json' \
  --data '{
    "inputs": { "text": "Summarize this paragraph..." },
    "response_mode": "blocking",
    "user": "user-123"
  }'

Blocking response (shape):

{
  "task_id": "...",
  "workflow_run_id": "...",
  "data": {
    "id": "...",
    "workflow_id": "...",
    "status": "succeeded",
    "outputs": { "result": "..." },
    "error": null,
    "elapsed_time": 1.23,
    "total_tokens": 500,
    "total_steps": 5,
    "created_at": 1700000000,
    "finished_at": 1700000002
  }
}

In streaming mode you receive workflow_started → node_started/node_finished … → workflow_finished; the final outputs are on workflow_finished.data.

POST /workflows/run-by-id — run a specific published version

Run a particular workflow id (e.g. a specific published version) rather than the default.

curl -X POST 'https://api.dify.ai/v1/workflows/run-by-id/{workflow_id}' \
  --header 'Authorization: Bearer app-XXXX' \
  --header 'Content-Type: application/json' \
  --data '{ "inputs": {}, "response_mode": "blocking", "user": "user-123" }'

GET /workflows/run/{workflow_run_id} — get run detail

Fetch the result/status of a past run (use workflow_run_id from the run response).

curl 'https://api.dify.ai/v1/workflows/run/{workflow_run_id}' \
  --header 'Authorization: Bearer app-XXXX'

{
  "id": "...",
  "workflow_id": "...",
  "status": "succeeded|running|failed|stopped",
  "inputs": "{...}",
  "outputs": { "...": "..." },
  "error": null,
  "elapsed_time": 1.23,
  "total_tokens": 500,
  "total_steps": 5,
  "created_at": 1700000000,
  "finished_at": 1700000002
}

POST /workflows/tasks/{task_id}/stop — stop a running task

Streaming runs only. user must match the one that started the run.

curl -X POST 'https://api.dify.ai/v1/workflows/tasks/{task_id}/stop' \
  --header 'Authorization: Bearer app-XXXX' \
  --header 'Content-Type: application/json' \
  --data '{ "user": "user-123" }'

Returns { "result": "success" }.

GET /workflows/logs — list workflow runs

curl 'https://api.dify.ai/v1/workflows/logs?page=1&limit=20' \
  --header 'Authorization: Bearer app-XXXX'

Query params: keyword, status (succeeded/failed/stopped/running), page, limit, and (for chatflow) created_by_end_user_session_id, created_by_account. Returns a paginated data array of run summaries.

Endpoint summary

Tips

• status values: running, succeeded, failed, stopped. Always check it before reading outputs.
• task_id (transient, for stop) ≠ workflow_run_id (persistent record, for detail).
• For long workflows prefer streaming — blocking is subject to the ~100s timeout on Cloud.