Events

Follow job progress over a streaming connection.

Job events stream status changes for one job in the API key's workspace. Use them when your client can keep a connection open; use status polling for simpler scripts.

Open a stream

GET /api/v1/jobs/{jobId}/events requires jobs:read. Set JOB_ID to an existing job ID:

Bash

curl --fail-with-body --silent --show-error --no-buffer \
  -H "Authorization: Bearer $PROTEINIQ_API_KEY" \
  "https://proteiniq.io/api/v1/jobs/$JOB_ID/events"

A successful response uses Content-Type: text/event-stream. Authentication or access failures return an HTTP error before the stream opens.

Event types

Each event has an event: name and JSON in its data: field:

status: The current job resource, sent on connection and when job state changes.
terminal: The final job resource, followed by stream closure.
ping: A timestamp heartbeat, normally every 15 seconds.
error: A stream error with a message; inspect status again or reconnect as appropriate.

This is an abbreviated status event:

Text

event: status
data: {"id":"job_123","object":"job","status":"PROCESSING","progress":40}

SSE frames end with a blank line. A network chunk can contain part of a frame or several frames, so use an SSE parser instead of parsing each chunk as JSON.

Terminal states

Stop listening when the payload status is COMPLETED, FAILED, TIMEOUT, CANCELLED, or BUDGET_EXCEEDED. A job already in a terminal state sends its current status and terminal event immediately.

The same state can appear in both status and terminal events. Handle repeated snapshots without triggering duplicate actions. Result availability depends on the outcome and stored output.

Reconnect after a disconnect

Connection closure alone does not prove that the job finished. If no terminal state was received, read status or reopen the stream after a delay.

The stream advertises retry: 3000, a three-second reconnect delay. If the HTTP response is throttled, honor Retry-After instead. Reconnection returns a current snapshot; the endpoint does not provide event IDs or historical replay through Last-Event-ID.

Client authentication

Browser EventSource cannot set a custom Authorization header. Keep the workspace key in your server or local integration and use an authenticated SSE client there. Do not place an API key in a URL or ship it to browser code.