Skip to main content

​
Filter Rules

Filter Rules monitor arbitrary Twitter search queries using Advanced Search syntax. Each rule polls independently at a configurable interval, from sub-second (0.1s) to daily (86,400s).

​
Quick start

# Create a filter rule
curl -X POST "https://scrapebadger.com/v1/twitter/stream/filter-rules" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tag": "AI News",
    "query": "\"artificial intelligence\" OR \"machine learning\" lang:en -is:retweet",
    "interval_seconds": 5,
    "webhook_url": "https://example.com/webhooks/tweets"
  }'

​
Features

  • Up to 50 rules per API key
  • Advanced Search syntax — use from:, to:, lang:, is:reply, has:media, and more
  • Configurable polling interval from 0.1s to 86,400s
  • Up to 100 results per poll
  • Webhook + WebSocket delivery
  • Query validation endpoint to check syntax before creating

​
Interval pricing tiers

Faster polling intervals cost more credits per day:
TierMax IntervalCredits / rule / day
Turbo0.5s30,000
Fast5s10,000
Standard60s1,500
Relaxed600s (10min)500
Daily86,400s (24h)100
Fetch current pricing dynamically via the pricing tiers endpoint.

​
Query syntax examples

QueryDescription
from:elonmuskTweets from a specific user
"breaking news" lang:enEnglish tweets containing exact phrase
#bitcoin -is:retweetOriginal tweets with hashtag (no retweets)
to:OpenAI has:mediaReplies to OpenAI that contain media
from:elonmusk OR from:sataborasuTweets from either user

​
Rule lifecycle

  1. Active — Rule is polling and delivering matched tweets
  2. Paused — Manually paused via API or dashboard
  3. Suspended — Auto-paused due to insufficient credits

​
Deduplication

Filter rules automatically deduplicate tweets. If the same tweet matches across multiple polls, it is delivered only once.

​
API endpoints

Create Rule

POST /v1/twitter/stream/filter-rules

List Rules

GET /v1/twitter/stream/filter-rules

Get Rule

GET /v1/twitter/stream/filter-rules/

Update Rule

PATCH /v1/twitter/stream/filter-rules/

Delete Rule

DELETE /v1/twitter/stream/filter-rules/

Validate Query

POST /v1/twitter/stream/filter-rules/validate

Pricing Tiers

GET /v1/twitter/stream/filter-rules-pricing