States & SSE events
Exact payloads for every job state and every event emitted on the SSE stream.
The contract for integrating against the job stream — bots, dashboards, alerting, AI assistants.
States — full enum
| Value | Terminal | Result files available | Re-runnable |
|---|---|---|---|
pending |
no | no | n/a |
running |
no | no | n/a |
done |
yes | yes (7 days) | yes |
failed |
yes | partial | yes |
cancelled |
yes | partial | yes |
expired |
yes | no (purged) | no |
A pending or running job cannot be deleted, only cancelled.
SSE stream
GET /api/jobs/{id}/stream
Accept: text/event-stream
Standard SSE; each event:
event: <name>
data: <json-payload>
status event
Every 2 seconds while non-terminal, plus once at terminal state.
{
"id": "j_abc123",
"status": "running",
"processed_points": 412,
"grid_points_count": 1280,
"results_count": 387,
"error_count": 2,
"download_available": false,
"query_stats": {
"bakery": { "found_pct": 92 },
"dentist": { "found_pct": 78 }
}
}
| Field | Type | Description |
|---|---|---|
id |
string | Job id |
status |
enum | See table above |
processed_points |
int | Items finished |
grid_points_count |
int | Items planned |
results_count |
int | Result rows so far |
error_count |
int | Items that failed (job can still reach done) |
download_available |
bool | true once the result file is ready |
query_stats |
object | Per-query stats; depends on module |
log event
Emitted as new log lines accumulate (bundled, polled internally every 0.5 s).
{
"message": "Picked up 12 POIs in Lyon centre",
"level": "info",
"timestamp": "2026-05-27T14:21:08Z"
}
level ∈ debug · info · warn · error.
done event
Emitted once, then the stream closes. Same event for failed and cancelled — check status.
{
"id": "j_abc123",
"status": "done",
"results_count": 1820,
"duration_seconds": 1342
}
error event
Stream-level errors (auth, not-found). Different from a job ending in failed (that one comes via done with status: "failed").
{ "code": "forbidden", "message": "Not your job" }
Polling intervals (no SSE)
| Endpoint | Min poll interval |
|---|---|
/api/jobs/{id} |
2 seconds |
/api/jobs |
5 seconds |
Internal state refreshes every 2 s; faster polling brings no benefit.
Timeouts
| Thing | Value |
|---|---|
| SSE stream max duration | 6 hours |
| Job overall timeout | 6 hours |
| Idle worker reconnect window | 30 seconds |
Result file retention after done |
7 days |