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: a reverse proxy or load balancer in front of your deployment may cut the connection if the response doesn’t arrive within its timeout. streaming delivers the reply as SSE events. Use it for anything user-facing and for long runs.

Agent apps stream only.

Parse the Stream

Each event 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, every 10 seconds.

import json
import requests

body = {
    "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:

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

event: ping

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:

Concatenate reply chunks in order:
- message events for Chatbot and Chatflow apps
- agent_message events for Agent apps
Close on the right terminal event:
- message_end for Chatbot and Agent apps
- message_end then workflow_finished (both arrive, in that order) for Chatflow apps
- workflow_finished for Workflow apps
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 After Drops

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 checking the outcome. For workflow-backed runs (Workflow and Chatflow apps), if the connection drops mid-run, confirm the outcome with Get Workflow Run Detail using the saved workflow_run_id. 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.

Guides

App APIs

Knowledge APIs

Choose a Response Mode

Parse the Stream

Dispatch by Event Type

Handle Errors Mid-Stream

Reconnect After Drops

Keep the Connection Alive

​Choose a Response Mode

​Parse the Stream

​Dispatch by Event Type

​Handle Errors Mid-Stream

​Reconnect After Drops

​Keep the Connection Alive

Choose a Response Mode

Parse the Stream

Dispatch by Event Type

Handle Errors Mid-Stream

Reconnect After Drops

Keep the Connection Alive