WebSocket Delivery
Connect to the ScrapeBadger WebSocket endpoint to receive real-time tweet events from all your active stream monitors and filter rules.Connection
Using wscat
Using Python
Using Node.js
Messages
Every message is a JSON object with atype field.
Tweet event
"source": "filter_rule", rule_id and tag instead of monitor_id.
Connection behavior
- Authentication is done via the
api_keyquery parameter - Keepalive: the server sends
{"type": "ping"}every 40 seconds. If your client doesn’t reply with{"type": "pong"}within 30 seconds, the connection is closed with code1001 - Restarts: the server closes all connections with code
1001when it restarts. Reconnect right away - All monitors and filter rules for the API key deliver to the same connection
- Up to 5 connections per API key. Every open connection gets every event
Close codes
Missed tweets
WebSocket delivery is live only: tweets aren’t queued or replayed. A tweet detected while none of your connections is open isn’t sent again. ScrapeBadger doesn’t store delivered tweets, so there is no delivery log to backfill from (GET /v1/twitter/stream/logs answers 410 Gone since 2026-11-09). Keep your own log of the tweets you receive. To cover a gap after a disconnect, query Advanced search for the monitored accounts (from:handle) over the window you missed; those calls are billed normally.
Best practices
- Reply to every ping, or the connection is dropped after 70 seconds
- Reconnect on every close with exponential backoff; cover any gap with Advanced search
- Process messages asynchronously so a slow handler doesn’t delay your pong
- Deduplicate by
tweet_id. With several connections open, each one receives every event - Use webhooks when you need guaranteed delivery. Webhooks are retried, WebSocket is not

