Skip to main content

​
What you’ll build

In this guide you’ll:
  • Get your WebSocket URL from the uTrack dashboard
  • Connect to uTrack over WebSocket
  • Print incoming events (tweets, deletes, profile changes, follow updates, etc.)

​
1) Get your Websocket URL

  1. Log in to the uTrack Dashboard
  2. Add a test account to your tracked accounts
  3. Copy your personal WebSocket URL
Your URL will look like: 
wss://api.utrack.club/ws?token=YOUR_TOKEN
WARNING: Keep your token private. You can always request a reset if you leak it.

​
2) Connect to the websocket

Below are example clients showing how to connect to uTrack’s WebSocket. Choose ONE based on your language — they behave the same.

​
JavaScript / Node.js

const url = "wss://api.utrack.club/ws?token=YOUR_TOKEN";
const ws = new WebSocket(url);

ws.onopen = () => {
  console.log("Connected to uTrack");
};

ws.onmessage = (event) => {
  try {
    const msg = JSON.parse(event.data);
    console.log("Event:", msg.type ?? "(no type)");
    console.log(msg);
  } catch {
    console.log("Message:", event.data);
  }
};

ws.onclose = (e) => {
  console.log("Disconnected:", e.code, e.reason);
};

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

​
Python

import json
import websocket

URL = "wss://api.utrack.club/ws?token=YOUR_TOKEN"

def on_open(ws):
    print("Connected to uTrack")

def on_message(ws, message):
    try:
        msg = json.loads(message)
        print("Event:", msg.get("type", "(no type)"))
        print(msg)
    except Exception:
        print("Message:", message)

def on_error(ws, error):
    print("WebSocket error:", error)

def on_close(ws, code, reason):
    print("Disconnected:", code, reason)

if __name__ == "__main__":
    ws = websocket.WebSocketApp(
        URL,
        on_open=on_open,
        on_message=on_message,
        on_error=on_error,
        on_close=on_close
    )
    ws.run_forever()

​
3) Try it out

Assuming you have added your own X account to your Tracked Accounts you can now send a tweet and you will see atweet.mini.updateevent pop up with all the details about your tweet!

​
What’s next?

  • WebSocket Events: event types and payload examples
  • Tiers: Normal vs High Performance vs Extreme
  • Dashboard: managing accounts and subscriptions
  • Best Practices: reconnects, dedupe, and scaling consumers
Need more help? Join our discord