Handling streaming responses

Streaming responses let an API Endpoint send multiple updates while it is still running.

This is useful when an API Endpoint would otherwise take a long time and you want your interface to show progress (or display content as it arrives).

When to use streaming

• A long import/export (show progress)
• A file generation workflow (show steps like “preparing”, “generating”, “uploading”)
• AI responses (display text as it arrives)

Streaming in plain terms

Normally, an API Endpoint works like this:

1. You call it.
2. You wait.
3. You get one final response when it’s done.

Streaming changes the “wait” part:

1. You call it once.
2. While it’s working, it sends small updates (like “10% done”, “still working”, or “here’s the next piece of text”).
3. At the end, it finishes like a normal API call.

This is helpful for users because the interface can show what’s happening instead of looking stuck.

How streaming works in WeWeb

In an API Endpoint workflow:

• The first time you run Send streaming response, WeWeb starts the stream.
• Each next Send streaming response adds another message to the same stream.
• The stream ends when the API Endpoint finishes.

Set up a streaming API Endpoint

1. Create or open an API Endpoint in Data & API → Workflows.
2. In your API Endpoint workflow, add Send streaming response wherever you want to send an update.
3. In Event Data, send an object that your interface can use.

Example Event Data objects:

• { "status": "starting" }
• { "status": "progress", "done": 3, "total": 10 }
• { "status": "chunk", "text": "Hello " }
• { "status": "done" }

Receive streaming updates in the interface

To see streaming updates while the API Endpoint runs, you must enable stream handling on the action that calls the API Endpoint:

1. In the Interface tab, create a workflow (for example On click).
2. Click + Add action, then go to Workflows → API and select your API Endpoint.
3. Open the action’s Advanced section and enable Handle stream.

When streaming is enabled, you can use:

• stream.chunk: The latest message received
• stream.chunks: All messages received so far

This makes it easy to bind live progress into your UI (text, progress bars, or a “live output” area).

Practical example: generate a report with live progress

What you’re building

• A button in your interface: “Generate report”
• An API Endpoint that takes ~10–30 seconds
• A progress message in the UI while it runs (and a final download link at the end)

1) API Endpoint workflow (server-side)

In your API Endpoint workflow:

1. Add Send streaming response with:
   • { "status": "starting" }
2. Run your report steps (for example: retrieve records, calculate totals, create a file).
3. After each big step, add another Send streaming response, for example:
   • { "status": "progress", "label": "Retrieving data", "done": 1, "total": 3 }
   • { "status": "progress", "label": "Generating file", "done": 2, "total": 3 }
4. When done, send a last message with what the interface needs next:
   • { "status": "done", "downloadUrl": "https://..." }

KEEP EVENT DATA SMALL

It is recommended to keep Event Data small and consistent so it’s easy to use in bindings.

2) Interface workflow (the button click)

1. Create a workflow on your button (for example On click).
2. Add your API Endpoint action from Workflows → API.
3. Open Advanced and enable Handle stream.

Now you can bind streaming updates into your UI:

• Show the latest update: stream.chunk.status and stream.chunk.label
• Build a progress bar:
  • Value: stream.chunk.done
  • Max: stream.chunk.total
• When the final message arrives, use stream.chunk.downloadUrl to show a “Download” button.

Best practices

• Send small updates: Prefer short objects over large data.
• Give your data a consistent shape: For example, always send a status.
• Avoid too many messages: If you’re looping, send updates every few steps instead of every single item.

Related pages

• Send streaming response action →
• Send response action →
• Executing from interface workflows →