Skip to main content

​
Twitter Streams

Monitor Twitter in real-time with two complementary approaches:
  • Stream Monitors — Watch specific Twitter accounts and get notified when they tweet, reply, retweet, or quote.
  • Filter Rules — Monitor arbitrary Twitter search queries using Advanced Search syntax.
Both deliver tweets via WebSocket and/or Webhook with sub-second latency.

​
Quick comparison

FeatureStream MonitorsFilter Rules
What it watchesSpecific accounts (by username)Search queries (Advanced Search syntax)
BillingPer-account-per-day (volume tiers)Per-rule-per-day (interval tiers)
Max per API key100 accounts per monitor50 rules
DeliveryWebSocket + WebhookWebSocket + Webhook
Polling intervalGlobal (100ms default)Configurable per rule (0.1s — 86400s)

​
How it works

  1. Create a monitor or filter rule via the API (or dashboard)
  2. Configure delivery — attach a webhook URL and/or connect via WebSocket
  3. Receive tweets in real-time as they are detected
  4. Credits are billed automatically every 60 seconds based on your active monitors/rules

​
Delivery methods

​
WebSocket

Connect to wss://scrapebadger.com/v1/twitter/stream with your API key to receive real-time tweet events. 
wscat -c "wss://scrapebadger.com/v1/twitter/stream?api_key=YOUR_API_KEY"
Each message is a JSON object containing the tweet data, monitor/rule metadata, and timing information.

​
Webhooks

Configure an HTTPS webhook URL on your monitor or filter rule. ScrapeBadger sends an HTTP POST for each detected tweet, signed with HMAC-SHA256 so you can verify authenticity. 
POST https://your-server.com/webhooks/tweets
X-Signature-256: sha256=...
Content-Type: application/json

{
  "event": "tweet.detected",
  "monitor_id": "...",
  "tweet": { ... }
}

​
Auto-pause on low balance

When your credit balance drops below the estimated hourly cost, active monitors and filter rules are automatically paused with status_reason: "insufficient_credits". They resume automatically when you top up.

​
Next steps

Stream Monitors

Monitor specific Twitter accounts

Filter Rules

Monitor search queries

WebSocket

Real-time WebSocket delivery

Webhooks

HTTP POST delivery with HMAC signing