WebSocket

IvyWebSocket lets you stream a job's progress in real time, pushing phase, percentage, and status changes to your app as the computation runs instead of polling for them. Reach for it when you want live updates and are willing to manage the connection yourself; it handles reconnection, keepalive, and multiple subscribers per job for you. In React apps you'd typically consume it through the useIvyWebSocket hook rather than instantiating this class directly.

SDK WebSocket Reference

The IvyWebSocket class provides real-time job progress updates via WebSocket connections. It handles automatic reconnection, keepalive pings, and multi-listener subscriptions.

Access via ivy.websocket or instantiate directly.

Overview

External clients cannot open a job WebSocket today (see WebSocket Protocol), so until the SDK ships, follow jobs with the SSE job event stream; the Python tabs below use it. Inside the platform, the backend pushes status updates whenever a job's phase, progress percentage, or status changes — typically every 1-5 seconds during active computation.

Features

• Automatic reconnection with exponential backoff on unexpected disconnection
• 25-second keepalive pings to prevent proxy/load balancer timeouts
• Multi-listener support (multiple subscribers per job)
• Transparent URL scheme conversion (https→wss, http→ws)

Constructor

new IvyWebSocket(
  baseUrl: string,
  getToken: () => Promise<string>,
  options?: WebSocketOptions
)

WebSocketOptions

websocket.connect(jobId)

Connect to the authenticated WebSocket endpoint for a specific job.

async connect(jobId: string): Promise<void>

No public WebSocket URL serves job updates. Until the SDK ships, follow a job with the SSE stream GET /api/v1/jobs/{jobId}/events (SSE Streaming).

Parameters:

Throws: IvyWebSocketError if the connection fails.

Examples

await ivy.websocket.connect("job_abc123")
console.log(ivy.websocket.isConnected) // true

websocket.subscribe(jobId, callback)

Subscribe to progress updates for a specific job.

subscribe(jobId: string, callback: (data: JobProgress) => void): () => void

Multiple subscribers can listen to the same job simultaneously.

Parameters:

Returns: An unsubscribe function — call it to stop receiving events.

Examples

const unsub = ivy.websocket.subscribe("job_abc123", (progress) => {
  console.log(`${progress.phase}: ${progress.progress}%`)
  if (progress.status === "COMPLETED") {
    console.log("Done!", progress.result)
    unsub()
  }
})

await ivy.websocket.connect("job_abc123")

websocket.disconnect()

Gracefully disconnect the WebSocket connection.

disconnect(): void

Sends close code 1000 (normal closure) to the server, stops keepalive pings, and clears connection state. Does not trigger auto-reconnect.

websocket.isConnected

Whether the WebSocket is currently in the OPEN state.

get isConnected(): boolean

Reconnection Strategy

When the connection drops unexpectedly (non-1000 close code):

Attempt 1: wait reconnectInterval ms         (1s)
Attempt 2: wait reconnectInterval * 2 ms     (2s)
Attempt 3: wait reconnectInterval * 4 ms     (4s)
Attempt 4: wait reconnectInterval * 8 ms     (8s)
Attempt 5: wait reconnectInterval * 16 ms    (16s)
— Give up after maxReconnectAttempts —

The onReconnect callback fires on each attempt, useful for showing UI indicators.

Message Format

The WebSocket receives JSON messages with this structure:

{
  "job_id": "job_abc123",
  "status": "PROCESSING",
  "progress": 45,
  "phase_name": "main_computation",
  "result": null,
  "error_message": null
}

The SDK normalizes this to a JobProgress object:

{
  jobId: "job_abc123",
  status: "PROCESSING",
  progress: 45,
  phase: "main_computation",
  result: undefined,
  error: undefined,
}

WebSocket Close Codes

Full Example

const ivy = createIvyClient({ apiKey: "ivy_..." })

// Subscribe BEFORE connecting (messages arrive immediately after open)
const unsub = ivy.websocket.subscribe("job_abc123", (progress) => {
  console.log(`[${progress.phase}] ${progress.progress}% — ${progress.status}`)

  if (progress.status === "COMPLETED") {
    console.log("Results:", progress.result)
    unsub()
    ivy.websocket.disconnect()
  }
})

// Connect with custom options
await ivy.websocket.connect("job_abc123")

// Later: manual disconnect
// ivy.websocket.disconnect()