WebSocket API

Connect to /ws for real-time session events.

Connection

const ws = new WebSocket('ws://127.0.0.1:9090/ws')

The WebSocket endpoint is public (no auth required even when api_key is set).

Event Types

Type	Trigger	Payload
Created	Session created	session_id
Navigated	Session navigated to URL	session_id, url
Closed	Session closed	session_id
Executed	JS executed in session	session_id, result
Error	Session error	session_id, error

Event Format

{"type": "Created", "session_id": "sess_a1b2c3d4"}
{"type": "Navigated", "session_id": "sess_a1b2c3d4", "url": "https://example.com"}
{"type": "Closed", "session_id": "sess_a1b2c3d4"}
{"type": "Executed", "session_id": "sess_a1b2c3d4", "result": "Example Domain"}
{"type": "Error", "session_id": "sess_a1b2c3d4", "error": "Navigation timeout"}

Example Client

const ws = new WebSocket('ws://127.0.0.1:9090/ws')

ws.onmessage = (event) => {
  const data = JSON.parse(event.data)
  console.log(`[${data.type}] Session: ${data.session_id}`)

  if (data.type === 'Error') {
    console.error(`Error: ${data.error}`)
  }
}

ws.onclose = () => {
  console.log('WebSocket disconnected')
}

Use Cases

• Monitor active scraping jobs in real-time
• Trigger follow-up actions when a session navigates
• Log errors for debugging
• Build dashboards showing session activity