WebSocket

WebSocket Streaming

Connect via WebSocket to receive real-time tweet events from your Stream Monitors and Filter Rules as they are detected.

Protocol:WebSocket (wss://)
Auth:API key (header or query param)
Max connections:5 / API key

Connection URL

ws://localhost:8000/v1/twitter/stream?api_key=YOUR_API_KEY

# Or via header:
x-api-key: YOUR_API_KEY

Authentication can be provided via the api_key query parameter or the x-api-key header.

Event Types

connectedConnection Established

Sent immediately after successful authentication.

{
  "type": "connected",
  "connection_id": "abc-123",
  "api_key_id": "key-456"
}

new_tweetTweet from Stream Monitor

Sent when a monitored account posts a new tweet.

{
  "type": "new_tweet",
  "source": "monitor",
  "monitor_id": "mon-123",
  "monitor_name": "Tech Leaders",
  "tweet_id": "1234567890123456789",
  "author_username": "elonmusk",
  "tweet_text": "The future is electric...",
  "tweet_type": "original",
  "latency_ms": 850,
  "detected_at": "2026-03-04T12:00:00Z"
}

new_tweetTweet from Filter Rule

Sent when a tweet matches a filter rule query.

{
  "type": "new_tweet",
  "source": "filter_rule",
  "rule_id": "rule-456",
  "rule_tag": "bitcoin-mentions",
  "tweet_id": "1234567890123456789",
  "author_username": "cryptonews",
  "tweet_text": "Bitcoin hits new ATH...",
  "tweet_type": "original",
  "latency_ms": 1200,
  "detected_at": "2026-03-04T12:00:00Z"
}

errorConnection Error

Sent when authentication fails or connection limit is exceeded.

{
  "type": "error",
  "code": 4001,
  "message": "Invalid or missing API key"
}

// Error codes:
// 4001 - Invalid or missing API key
// 4003 - Connection limit exceeded

Code Examples

JavaScript

// JavaScript WebSocket connection
// Replace with your actual domain (wss:// for production, ws:// for local dev)
const ws = new WebSocket(
  'ws://localhost:8000/v1/twitter/stream?api_key=YOUR_API_KEY'
);

ws.onopen = () => {
  console.log('Connected to stream');
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);

  if (data.type === 'connected') {
    console.log('Connection ID:', data.connection_id);
  }

  if (data.type === 'new_tweet') {
    console.log('New tweet from', data.author_username);
    console.log('Source:', data.source); // "monitor" or "filter_rule"
    console.log('Latency:', data.latency_ms, 'ms');
  }
};

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

Python

import asyncio
import json
import websockets

async def stream():
    # Replace with your actual domain (wss:// for production, ws:// for local dev)
    uri = "ws://localhost:8000/v1/twitter/stream?api_key=YOUR_API_KEY"
    async with websockets.connect(uri) as ws:
        async for message in ws:
            data = json.loads(message)
            if data["type"] == "new_tweet":
                print(f"@{data['author_username']}: {data['tweet_text']}")

asyncio.run(stream())

Best Practices

Reconnection

Implement exponential backoff for reconnection. Start at 1 second and double up to 30 seconds. The server will close idle connections after extended periods of inactivity.

Distinguish Sources

Check the source field to differentiate between monitor events ("monitor") and filter rule events ("filter_rule").

Connection Limits

Each API key supports up to 5 concurrent WebSocket connections. All monitors and filter rules for the same API key deliver to the same WebSocket channel.