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:

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

Message Format

All messages sent from the server follow the Server-Sent Events (SSE) format:

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 is a JSON string identical to the payload returned by the Query Task Status endpoint.

Watch All Tasks

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

Endpoint

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

Catch-up Mechanism

If you need to receive updates that occurred while your client was disconnected, use the since parameter with a UTC ISO 8601 timestamp:

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

Upon connection, the server will immediately push the latest status of all tasks that have been updated since the specified time.

Example Implementation

Watch Single Task (JavaScript)

JavaScript

const taskUuid = "92483a80-236c-4889-9a95-4c90bb64dfd8";
const apiKey = "YOUR_API_KEY";
const ws = new WebSocket(
  `wss://api.triverse.ai/api/v1/tasks/watch/${taskUuid}?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