WebSockets

WebSockets provide a real-time, bi-directional communication channel between your application and the Triverse API. This is the most efficient way to monitor task progress without the overhead of repeated HTTP polling.

Connection & Authentication

To establish a WebSocket connection, use the following URL format with your API key as a query parameter:

Endpoint

WSS wss://api.triverse.ai/api/v1/tasks/watch/{task_uuid}?token=<YOUR_API_KEY>

Message Format

WebSocket messages are text frames containing Server-Sent Events (SSE) formatted payloads.

event: <event_type>
data: <json_data>

Event Types

update: Sent whenever there is a change in the task's progress or status.
finalized: Sent when the task reaches a terminal state (SUCCESS, FAILED, or CANCELLED). The connection is typically closed after this event.

Data Structure

The json_data uses the same public task status payload documented in Task Status. WebSocket frames do not expose internal frame metadata such as user_id, flow_run_id, is_terminal, changed, scheduler state, worker queue names, deployment IDs, pricing snapshots, or analytics context.

Example data payload:

{
  "task_uuid": "92483a80-236c-4889-9a95-4c90bb64dfd8",
  "flow_name": "image-to-model",
  "status": "RUNNING",
  "progress": 40,
  "created_at": "2026-05-27T00:00:00Z",
  "started_at": "2026-05-27T00:00:12Z",
  "completed_at": null,
  "input": {
    "image_url": "https://.../input.png",
    "model_version": "v2"
  },
  "output": null,
  "error": null,
  "queue": {
    "is_queued": false,
    "position": null,
    "estimated_wait_seconds": null
  }
}

Watch All Tasks

You can also monitor all tasks for the authenticated user through a single connection.

Endpoint

WSS wss://api.triverse.ai/api/v1/tasks/watch/all?token=<YOUR_API_KEY>

Catch-up Mechanism

Use the since parameter with a UTC ISO 8601 timestamp to receive the current state of tasks created after that time:

wss://api.triverse.ai/api/v1/tasks/watch/all?token=<YOUR_API_KEY>&since=2026-02-09T00:00:00Z

Upon connection, the server immediately sends latest status frames for tasks whose created_at timestamp is after the specified since value. This is a creation-time catch-up filter; it does not replay every update that occurred while the client was offline.

Example Implementation

Watch Single Task (JavaScript)

JavaScript

const task = "92483a80-236c-4889-9a95-4c90bb64dfd8";
const apiKey = "YOUR_API_KEY";
const ws = new WebSocket(
  `wss://api.triverse.ai/api/v1/tasks/watch/${task}?token=${apiKey}`,
);

ws.onmessage = (event) => {
  // Parse SSE format
  const lines = event.data.split("\n");
  const eventType = lines[0].replace("event: ", "");
  const data = JSON.parse(lines[1].replace("data: ", ""));

  console.log(`Event: ${eventType}`, data);

  if (eventType === "finalized") {
    console.log("Task finished, closing connection.");
    ws.close();
  }
};

ws.onerror = (error) => {
  console.error("WebSocket Error:", error);
};

Watch Single Task (Python)

Python

import asyncio
import websockets
import json

async def watch_task(task_uuid, api_key):
    uri = f"wss://api.triverse.ai/api/v1/tasks/watch/{task_uuid}?token={api_key}"
    async with websockets.connect(uri) as websocket:
        async for message in websocket:
            # Parse SSE format
            lines = message.split("\n")
            event_type = lines[0].replace("event: ", "")
            data = json.loads(lines[1].replace("data: ", ""))

            print(f"Event: {event_type}", data)

            if event_type == "finalized":
                print("Task finished, closing connection.")
                break

if __name__ == "__main__":
    TASK_UUID = "92483a80-236c-4889-9a95-4c90bb64dfd8"  # Replace with your task UUID
    API_KEY = "<YOUR_API_KEY>"  # Replace with your API Key
    asyncio.run(watch_task(TASK_UUID, API_KEY))

On this page