A question about your data can take ten seconds or more to answer properly. Ten seconds of spinner feels broken. Ten seconds of visible progress feels like work being done.

This post shows how to read a streamed answer with nothing but requests: progress lines first, then the rows, then the answer. It uses server-sent events (SSE), so the same pattern applies to any API that streams this way.

The format in 30 seconds

An SSE response is plain text. Each event is two lines, then a blank line:

event: status data: {"stage": "generating_sql", "message": "Generating SQL..."} 

So the reader is a small loop: remember the last event: line, parse the next data: line as JSON, act on the pair.

The code

This runs as is, with no signup: it borrows FactQL's public sample key, which points at a demo film-rental shop.

# pip install requests import json, time, requests FACTQL = "https://api.factql.ai" sample = requests.get(f"{FACTQL}/sample", timeout=30).json() # public demo key, no signup KEY, CLIENT_ID = sample["api_key"], sample["client_id"] def ask(question, end_user="demo-user-1"): start = time.time() with requests.post( f"{FACTQL}/clients/{CLIENT_ID}/ask/stream", headers={"X-API-Key": KEY, "X-End-User-Id": end_user}, json={"query": question, "new_session": True}, stream=True, timeout=180, ) as resp: resp.raise_for_status() event, answer = None, None for line in resp.iter_lines(decode_unicode=True): if not line: continue if line.startswith("event:"): event = line[6:].strip() elif line.startswith("data:"): data = json.loads(line[5:]) stamp = f"{time.time() - start:5.1f}s" if event == "status" and data.get("message"): print(stamp, "..", data["message"]) elif event == "sql": print(stamp, "query ready") elif event == "result": table = data.get("data") or data # rows can sit at the top level or under "data" print(stamp, "rows:", table.get("rows", [])[:3]) answer = answer or data.get("explanation") elif event == "explanation": answer = data["text"] elif event == "error": print(stamp, "couldn't answer:", data.get("message")) print("answer:", answer) ask("Which film category brings in the most revenue?") 

What it prints

A real run against the sample data (I've cut the middle of the progress list):

 1.2s .. Gathering schema and history... 1.8s .. Understanding your question… 3.3s .. Searching the schema for “film category revenue”… 6.5s .. Inspecting payment… 6.6s .. Inspecting film_category… ... 13.2s query ready 13.2s rows: [['Action', 26505.44000000441]] 

Thirteen seconds, and the user had something new to read every second or two. When I ran the same question again, the rows came back in 1.4 seconds.

Five things the docs example won't tell you

I hit each of these while testing:

  1. Skip blank lines. They separate events. iter_lines hands them to you as empty strings.
  2. A status event may have no message. Check before printing, or you'll show "None" to a user.
  3. Don't assume one shape for the rows. On a fresh question the rows sat at the top level of the result event; on a repeated question they were nested under data. The line table = data.get("data") or data handles both.
  4. Take the answer from wherever it arrives. It can come as its own explanation event or inside result. Keep the first one you see.
  5. An error is an event, not a status code. When a question can't be answered the stream still returns 200. Handle the error event or the UI will wait forever.

Turning it into a UI

Each branch maps to one UI update:

Event What the user sees
status Replace the spinner text with the message
sql Show a "query ready" tick
result Draw the table
explanation Show the answer above the table
error Show the message and stop

In a browser you'd read the same stream with fetch and a TextDecoder, splitting on blank lines. Send a stable id for the signed-in person in X-End-User-Id so each user gets their own chats.

Is streaming worth it?

For answers under two seconds, no: just wait and render. For anything that reads a schema, runs a query and writes an explanation, yes. People forgive slow when they can see what's happening.

What's the longest your users wait on a spinner today?