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
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 20 results per poll (set a lower limit with
max_results_per_poll) - Webhook + WebSocket delivery
- Query validation endpoint to check syntax before creating
Pricing
Filter rules are billed per poll, not per day. Each poll is one live search on X.
Three things decide what a rule costs:
- Every tweet a poll returns is charged, including tweets an earlier poll already returned. Deduplication decides what is delivered to you, not what is billed. A query that always matches, such as a
from:list of active accounts, returns a full page on every poll. - Rates are in pay-as-you-go credits. Filter rules cost the same in dollars on every plan, so subscription credits are deducted at the pay-as-you-go equivalent. On a plan whose credits cost 40% of the pay-as-you-go price, a poll that returns 20 tweets takes about 50 plan credits.
- Cost scales with how often you poll. Credits per day = polls per day × credits per poll.
The dashboard shows each rule’s measured credits per day once it has been running, and the possible range before that.
Keeping the cost down
- Poll less often. Cost is proportional to the number of polls.
- Lower
max_results_per_poll. A poll that returns 10 tweets costs half of one that returns 20. Values above 20 have no effect.
max_results_per_poll. If more new tweets arrive between two polls than that, the older ones are not delivered. Choose the interval and limit for the busiest hour of your query, not the average.
Read the current rates from the pricing endpoint.
Query syntax examples
Rule lifecycle
- Active — Rule is polling and delivering matched tweets
- Paused — Manually paused via API or dashboard
- 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. It is still charged on each poll that returns it: see Pricing.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
GET /v1/twitter/stream/filter-rules-pricing

