Skip to content
Tutorials Center
My learning

Topics

Lesson 28 of 50 ยท Async and concurrency

Streaming, SSE and WebSockets

Stream large or slow responses with StreamingResponse and async generators, send Server-Sent Events, and learn WebSocket endpoints with a connection manager.

A normal response is built completely, then sent. That is perfect for most endpoints, but not for a 2 GB export, a chat message that an AI model is still writing, or a dashboard that needs a new number every second. For those you want the server to send data piece by piece, or to keep a connection open and talk in both directions.

FastAPI offers three tools, from simplest to most powerful: streaming responses (one long response sent in chunks), Server-Sent Events (a standard format for the server to push events to a browser) and WebSockets (a two-way channel). You will run the first two live here and study the third with a runnable stand-in.

Three ways to send data over time

Streaming One response, sent in chunks.
SSE Server pushes events; browser listens.
WebSocket Both sides send whenever they like.
1 / 2

StreamingResponse and async generators

StreamingResponse takes an async generator (or any iterator) and sends every value it yields as a chunk. The client can start processing the first chunk while the server is still producing the rest, and the server never needs the whole payload in memory.

Python
from fastapi.responses import StreamingResponse

async def numbers():
    for i in range(1, 6):
        yield f"{i}\n"          # each yield becomes a chunk

@app.get("/numbers")
async def stream_numbers():
    return StreamingResponse(numbers(), media_type="text/plain")

An async def generator can await between yields, for example to read the next page from a database or the next token from a model. The generator is the code that runs after your endpoint has returned, which means errors inside it cannot change the status code: the headers are already gone.

The in-process client collects the chunks as they arrive, so aiter_text() lets us see them one by one. (A real network client sees them over time; here they arrive almost instantly.)

Python Streaming a CSV export in chunks

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

There is no content-length header: the server does not know the size in advance, so it uses chunked transfer. Whatever the chunking on the wire, joining the pieces gives the full CSV. Real clients can write each chunk to disk as it arrives.

For files that already exist on disk, use FileResponse instead; it streams efficiently and sets length and type headers for you.

Server-Sent Events

Server-Sent Events (SSE) is a tiny standard on top of a streaming response. The server sends text/event-stream and writes events as plain text lines. Browsers read it with the built-in EventSource object and even reconnect automatically.

An event is a block of lines ending with a blank line:

TEXT
event: progress
id: 3
data: {"percent": 60}

Common fields: data: (the payload; send JSON as a string), event: (a name that lets the client pick a handler), id: (so a reconnecting client can say where it stopped through the Last-Event-ID header) and lines starting with : (comments, handy as keep-alive pings so proxies do not close an idle connection).

JavaScript
// Read-only browser code
const source = new EventSource("/progress");
source.addEventListener("progress", (event) => {
  console.log(JSON.parse(event.data).percent);
});

The server side is an async generator that formats each event. We wrap that in a helper, then parse the stream the way a client would.

Python A progress feed with Server-Sent Events

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The output lists four progress events with ids 1 to 4, then a done event. The comment line is skipped by the parser, as a browser would skip it.

Two practical headers: Cache-Control: no-cache keeps intermediaries from storing the stream, and X-Accel-Buffering: no tells nginx not to buffer it (otherwise events arrive in clumps). SSE is one-directional (server to browser) and travels over normal HTTP, so it works with ordinary authentication, proxies and load balancers. That makes it the right choice for progress bars, notifications and streaming AI answers.

WebSockets

When both sides need to send messages at any time (chat, multiplayer games, collaborative editing) use a WebSocket. The browser opens one long-lived connection with a special HTTP upgrade request, and after that either side can send text or binary messages.

In FastAPI a WebSocket endpoint uses @app.websocket and a WebSocket parameter. You must accept() the connection, then loop receiving and sending until the client disconnects, which raises WebSocketDisconnect.

Python
# Read-only: the in-browser runner has no network server
from fastapi import FastAPI, WebSocket, WebSocketDisconnect

app = FastAPI()

@app.websocket("/ws")
async def echo(websocket: WebSocket):
    await websocket.accept()
    try:
        while True:
            message = await websocket.receive_text()
            await websocket.send_text(f"you said: {message}")
    except WebSocketDisconnect:
        print("client left")

For chat-like apps you need to know all open connections so you can broadcast. The usual pattern is a small connection manager:

Python
# Read-only sketch
class ConnectionManager:
    def __init__(self):
        self.active: list[WebSocket] = []

    async def connect(self, websocket: WebSocket):
        await websocket.accept()
        self.active.append(websocket)

    def disconnect(self, websocket: WebSocket):
        self.active.remove(websocket)

    async def broadcast(self, text: str):
        for connection in list(self.active):
            await connection.send_text(text)

manager = ConnectionManager()

@app.websocket("/chat/{room}")
async def chat(websocket: WebSocket, room: str):
    await manager.connect(websocket)
    try:
        while True:
            text = await websocket.receive_text()
            await manager.broadcast(f"{room}: {text}")
    except WebSocketDisconnect:
        manager.disconnect(websocket)

The manager's logic is ordinary Python, so we can run it here with fake sockets that record what they receive.

Python A connection manager with fake sockets

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Ada receives the first two broadcasts but not the last, because she disconnected; Linus joined after the first message, so he sees only the second and third.

WebSocket cautions

  • Authentication cannot use custom headers from browser JavaScript. Typical choices are a short-lived token in the query string or a cookie; validate it before accept() and close with a policy-violation code if it is wrong.
  • State is per process. The manager above only knows connections to this worker. With several workers or servers you need a shared pub/sub layer such as Redis.
  • Limit message sizes and rates, and clean up on disconnect.
  • Prefer SSE when the data only flows server to client; it is simpler to run and scale.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does StreamingResponse accept to produce its chunks?

    Each value yielded by the generator becomes a chunk of the response body.
  2. 2. What ends a Server-Sent Event in the stream?

    Events are blocks of field: value lines terminated by an empty line. Without the blank line the client keeps waiting.
  3. 3. Which tool fits a live chat where users send and receive messages at any time?

    WebSockets give a long-lived two-way channel. SSE is one-way, and normal endpoints answer once.
  4. 4. Why can't a streaming endpoint change its status code after an error halfway through?

    HTTP sends the status line and headers before the body. Once streaming has begun, you can only stop or send an error marker in the data.
  5. 5. A connection manager lives in one Python process. What follows?

    In-memory state is per process. A message broker such as Redis pub/sub lets workers broadcast to each other's clients.

Summary

  • StreamingResponse sends what an (async) generator yields, chunk by chunk, so big or slow data never has to sit in memory.
  • Status code and headers are fixed before the first chunk; errors mid-stream cannot change them.
  • Server-Sent Events use text/event-stream, blocks of event:, id:, data: lines and a blank line after each event.
  • WebSocket endpoints use @app.websocket, accept(), a receive/send loop and handle WebSocketDisconnect.
  • A connection manager keeps track of open sockets for broadcasting, but its state is per process.
  • Choose streaming for payloads, SSE for one-way live feeds, WebSockets for two-way conversation.

Next, protect your API with Password hashing and user accounts.