> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scrapebadger.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Filter Rules

> Monitor Twitter search queries in real-time

# 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

```bash theme={null}
# 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:

| Tier | Max Interval | Credits / rule / day |
| - | - | - |
| Turbo | 0.5s | 30,000 |
| Fast | 5s | 10,000 |
| Standard | 60s | 1,500 |
| Relaxed | 600s (10min) | 500 |
| Daily | 86,400s (24h) | 100 |

<Note>
  Fetch current pricing dynamically via the [pricing tiers endpoint](/api-reference/endpoint/filter-rules/get-filter-rule-pricing).
</Note>

## Query syntax examples

| Query | Description |
| - | - |
| `from:elonmusk` | Tweets from a specific user |
| `"breaking news" lang:en` | English tweets containing exact phrase |
| `#bitcoin -is:retweet` | Original tweets with hashtag (no retweets) |
| `to:OpenAI has:media` | Replies to OpenAI that contain media |
| `from:elonmusk OR from:sataborasu` | Tweets 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

<CardGroup cols={2}>
  <Card title="Create Rule" icon="plus" href="/api-reference/endpoint/filter-rules/create-filter-rule">
    POST /v1/twitter/stream/filter-rules
  </Card>

  <Card title="List Rules" icon="list" href="/api-reference/endpoint/filter-rules/list-filter-rules">
    GET /v1/twitter/stream/filter-rules
  </Card>

  <Card title="Get Rule" icon="eye" href="/api-reference/endpoint/filter-rules/get-filter-rule">
    GET /v1/twitter/stream/filter-rules/{rule_id}
  </Card>

  <Card title="Update Rule" icon="pen" href="/api-reference/endpoint/filter-rules/update-filter-rule">
    PATCH /v1/twitter/stream/filter-rules/{rule_id}
  </Card>

  <Card title="Delete Rule" icon="trash" href="/api-reference/endpoint/filter-rules/delete-filter-rule">
    DELETE /v1/twitter/stream/filter-rules/{rule_id}
  </Card>

  <Card title="Validate Query" icon="check" href="/api-reference/endpoint/filter-rules/validate-filter-rule">
    POST /v1/twitter/stream/filter-rules/validate
  </Card>

  <Card title="Pricing Tiers" icon="credit-card" href="/api-reference/endpoint/filter-rules/get-filter-rule-pricing">
    GET /v1/twitter/stream/filter-rules-pricing
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.