Ask (streaming)

Streaming variant of Ask: the same request and behavior, delivered as Server-Sent Events while the research runs.

Each SSE data: line is one JSON object with a type field. There are no named SSE event: frames — parse the JSON rather than using addEventListener.

Events arrive in order:

• stage — a phase begins: retrieval, then synthesis (when answer is true).
• sub_query — the agent issued one search against the corpus; sub_query_result follows with its hit count, matched by seq.
• retrieval_done — evidence gathering finished.
• sources — the full ranked evidence set, the same objects the blocking endpoint returns. Sent before synthesis, so you can render evidence immediately.
• answer_delta — incremental answer text; only when answer is true.
• done — terminal: the final answer (treat it as the canonical text; answer_delta events are for display), plus note_type, note, and took_ms. Sources are NOT repeated here — keep the earlier sources event.
• ping — keep-alive during quiet stretches; ignore.
• error — terminal; replaces done on failure.

Consuming the stream (Python):

import json, requests
sources = []
with requests.post(
    "https://api.sonicalpha.ai/v1/insights/ask/stream",
    headers={"Authorization": f"Bearer {KEY}"},
    json={"query": "How have investor views on NVDA changed since June?",
          "answer": True},
    stream=True,
) as r:
    r.raise_for_status()
    for line in r.iter_lines():
        if not line.startswith(b"data: "):
            continue
        event = json.loads(line[len(b"data: "):])
        if event["type"] == "ping":
            continue
        if event["type"] == "error":
            raise RuntimeError(event.get("message"))
        if event["type"] == "sources":
            sources = event["sources"]  # the ranked evidence set
        if event["type"] == "answer_delta":
            print(event["text"], end="", flush=True)
        if event["type"] == "done":
            # canonical answer + note + took_ms; sources arrived above
            final = {**event, "sources": sources}