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:
- Skip blank lines. They separate events.
iter_lineshands them to you as empty strings. - A status event may have no message. Check before printing, or you'll show "None" to a user.
- Don't assume one shape for the rows. On a fresh question the rows sat at the top level of the
resultevent; on a repeated question they were nested underdata. The linetable = data.get("data") or datahandles both. - Take the answer from wherever it arrives. It can come as its own
explanationevent or insideresult. Keep the first one you see. - An error is an event, not a status code. When a question can't be answered the stream still returns 200. Handle the
errorevent 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?

