Consume Streaming Responses

Generation endpoints return either one complete response or a Server-Sent Events (SSE) stream, chosen per request with response_mode. Streaming is the usual choice: the reply renders as it generates, and long runs aren’t cut off mid-flight.

Choose a Response Mode#

blocking returns a single JSON body once generation finishes. It’s the simpler integration for short, non-interactive calls, but long generations risk interruption: proxies cut long requests, and on Dify Cloud the edge proxy may end the connection if the upstream response doesn’t arrive within its timeout.

streaming delivers the reply as SSE events. Use it for anything user-facing, for long runs, and for every flow that pauses for Human Input.

Parse the Stream#

Every event except ping arrives as a data: line holding one JSON object, terminated by a blank line.

Read the event field to decide what to do, and skip anything that isn’t a data: line: the keep-alive ping arrives as a bare event: ping line with no data: payload.

Chatflow and Workflow app streams open with a ping as the very first frame, and more arrive roughly every 10 seconds during the run. Treat the first data: event (workflow_started), not the first frame, as the signal that the run was accepted.

import jsonimport requestsbody = {    "query": "What are this month's top issues?",    "inputs": {},    "user": "customer-4821",    "response_mode": "streaming",}with requests.post(url, headers=headers, json=body, stream=True) as r:    for line in r.iter_lines(decode_unicode=True):        if not line or not line.startswith("data: "):            continue  # skips blank separators and ping lines        event = json.loads(line[len("data: "):])        handle(event)

On the wire, a stream looks like this:

event: pingdata: {"event": "workflow_started", "task_id": "c3800678-…", "workflow_run_id": "fb47b2e6-…", "data": {…}}data: {"event": "node_finished", "task_id": "c3800678-…", "workflow_run_id": "fb47b2e6-…", "data": {…}}

Dispatch by Event Type#

Which events arrive depends on the app type. See the event tables on Send Chat Message, Run Workflow, and Send Completion Message for the contract.

The typical minimum:

1. Concatenate reply chunks in order:

   • message events for Chatbot and Chatflow apps
   • agent_message events for Legacy Agent and Agent apps

   For Agent apps, a single closing message event repeats the complete answer; treat it as the final answer, not extra text to append.

2. Close on the right terminal event:

   • message_end for Chatbot, Legacy Agent, and Agent apps
   • message_end then workflow_finished (both arrive, in that order) for Chatflow apps
   • workflow_finished for Workflow apps

3. Surface error.

Handle Errors Mid-Stream#

A failure after the stream opens doesn’t change the HTTP status: the connection stays 200. How the failure surfaces depends on where it happens:

• A workflow node failure arrives as node_finished and workflow_finished events with status: "failed".
• Other failures end the stream with an error event carrying status, code, and message.

Handle both, and treat either as terminal for that request.

Reconnect and Resume#

Two identifiers matter, and they’re easy to mix up:

• task_id controls the in-flight generation and is what the stop endpoints (Stop Chat Message Generation / Stop Workflow Task) take.
• workflow_run_id names the persistent run record.

Both arrive on the stream itself: every event except error carries task_id, and workflow and node events carry workflow_run_id. Save workflow_run_id as soon as it arrives: if the connection drops mid-run, it’s the only handle you have for reconnecting or checking the outcome.

For workflow-backed runs (Workflow and Chatflow apps), a dropped connection isn’t fatal. Reopen the stream with Stream Workflow Events, passing the workflow_run_id and the same user that started the run. A mismatch returns 404.

Add include_state_snapshot=true to first replay the status of nodes that already ran, and continue_on_pause=true to keep one stream open across multiple Human Input pauses.

After reconnecting to a still-running workflow, confirm completion with Get Workflow Run Detail rather than relying on the reconnected stream’s final event alone.

Other replies have no resume endpoint: if the connection drops mid-reply, issue a new request. For chat-style apps, List Conversation Messages shows what was saved to the conversation.

Keep the Connection Alive#

Set your client’s read timeout comfortably above the 10-second ping interval so idle stretches between events don’t kill the connection. The pings themselves need no handling beyond being skipped.