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

Using wscat

Using Python

Using Node.js

Messages

Every message is a JSON object with a type field.

Tweet event

Tweets from a filter rule also carry "source": "filter_rule", rule_id and tag instead of monitor_id.

Connection behavior

  • Authentication is done via the api_key query 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 code 1001
  • Restarts: the server closes all connections with code 1001 when 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

  1. Reply to every ping, or the connection is dropped after 70 seconds
  2. Reconnect on every close with exponential backoff; cover any gap with Advanced search
  3. Process messages asynchronously so a slow handler doesn’t delay your pong
  4. Deduplicate by tweet_id. With several connections open, each one receives every event
  5. Use webhooks when you need guaranteed delivery. Webhooks are retried, WebSocket is not