Skip to main content
POST
Streaming (SSE) natural-language Q&A over a US coordinate
Same request body as POST /v1/ask, same credit cost, same planner and synthesizer. The difference is delivery: the answer arrives as Server-Sent Events while it is being written, so a chat UI can render the first sentence at around five to seven seconds instead of sitting on a spinner for the full synthesis. Use the buffered route for pipelines and batch jobs. Use this one whenever a person is watching.

Frames

A terminal error frame means there is no final frame coming. Discard any delta text you have already accumulated rather than presenting it as the answer — a mid-stream ask_answer_incomplete means the model was cut off, so the text on the wire is a fragment, not a short answer. The credits for that request are refunded, best-effort.
The final frame is the one to trust. It carries the full body — answer, confidence, citations, fields_used — identical to what the buffered endpoint would have returned. Do not assemble your citations from delta frames; concatenated deltas give you the prose, not the audit trail.

Call it

Failure modes

A failure before the first byte surfaces as a real HTTP status — a 429 with Retry-After under ask_busy back-pressure, or a 4xx/5xx from Errors. Your normal error handling catches it. A failure after the stream has opened cannot change the status code, so it arrives as a terminal error frame on a connection that already returned 200. Treat a stream that ends without a final frame as a failure, not as a short answer. Both routes share the same 110-second deadline.

Body

application/json
question
string
required
Required string length: 1 - 2000
lat
number | null
lng
number | null
address
string | null
Required string length: 1 - 256
include_trace
boolean
default:false

Response

Successful Response