API — Processes

Read and control long-running background jobs (AI imports, AI improvements, CSV imports). All endpoints require auth:api, auth_session, audit.

Endpoints

GET /processes

List processes for the active workspace, ordered by most recent.

Query params: workspace_id, status (optional filter)

Response 200: Array of process objects with id, type, status, progress, created_at, updated_at.

GET /processes/{id}

Get a single process with full state.

Response 200:

{
  "id": 42,
  "type": "ai_location_import",
  "status": "waiting_review",
  "progress": 100,
  "metadata": { ... },
  "result_summary": { ... }
}

GET /processes/{id}/events

List all ProcessEvent log entries for a process (append-only, ordered by ID).

Response 200: Array of event objects { id, status, message, created_at }.

GET /processes/{id}/stream

Server-Sent Events (SSE) stream for real-time process updates. The connection is held open for 25 seconds maximum; the client must reconnect after that window. The frontend’s useProcessMonitor hook handles reconnection.

Response: text/event-stream with data: lines containing JSON process state updates. Connection closes with a final event: done when the process reaches a terminal status. The frontend’s useProcessMonitor hook handles reconnection and falls back to 2-second polling when SSE is unavailable.

POST /processes/{id}/retry

Retry a failed process. Only valid in failed status.

Response 200: Updated process in pending status.

POST /processes/{id}/cancel

Cancel a running or pending process. Sets status to cancelled.

Response 200: Updated process in cancelled status.

Process statuses

Related pages

• Data model: Process
• Backend: Jobs and processes — state machine, job timeout, SSE implementation