Skip to main content

​
WebSocket Delivery

Connect to the ScrapeBadger WebSocket endpoint to receive real-time tweet events from all your active stream monitors and filter rules.

​
Connection

wss://scrapebadger.com/v1/twitter/stream?api_key=YOUR_API_KEY

​
Using wscat

npm install -g wscat
wscat -c "wss://scrapebadger.com/v1/twitter/stream?api_key=YOUR_API_KEY"

​
Using Python

import asyncio
import websockets
import json

async def listen():
    uri = "wss://scrapebadger.com/v1/twitter/stream?api_key=YOUR_API_KEY"
    async with websockets.connect(uri) as ws:
        async for message in ws:
            event = json.loads(message)
            print(f"New tweet from @{event['author_username']}: {event['tweet_url']}")

asyncio.run(listen())

​
Using Node.js

const WebSocket = require('ws');

const ws = new WebSocket(
  'wss://scrapebadger.com/v1/twitter/stream?api_key=YOUR_API_KEY'
);

ws.on('message', (data) => {
  const event = JSON.parse(data);
  console.log(`New tweet from @${event.author_username}: ${event.tweet_url}`);
});

ws.on('error', console.error);

​
Event format

Each WebSocket message is a JSON object: 
{
  "event": "tweet.detected",
  "monitor_id": "abc-123",
  "monitor_name": "Tech Leaders",
  "tweet_id": "1234567890",
  "author_username": "elonmusk",
  "tweet_text": "Just announced...",
  "tweet_url": "https://x.com/elonmusk/status/1234567890",
  "tweet_published_at": "2026-03-13T12:00:00Z",
  "detected_at": "2026-03-13T12:00:00.150Z",
  "latency_ms": 150
}

​
Connection behavior

  • Authentication is done via the api_key query parameter
  • Heartbeat pings are sent every 30 seconds to keep the connection alive
  • Auto-reconnect is recommended in your client code — the server may close idle connections
  • All monitors and filter rules for the API key deliver to the same WebSocket connection
  • Multiple connections are supported per API key

​
Best practices

  1. Always implement reconnection logic with exponential backoff
  2. Process messages asynchronously to avoid blocking the WebSocket receive loop
  3. Use webhooks as a backup — WebSocket connections can drop, but webhooks retry delivery