curl --request POST \
--url https://scrapebadger.com/v1/twitter/stream/filter-rules \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"tag": "AI news tracker",
"query": "(\"artificial intelligence\" OR \"machine learning\") min_faves:100 lang:en",
"interval_seconds": 60,
"max_results_per_poll": 20,
"webhook_url": "https://example.com/webhooks/filter-rules",
"webhook_secret": "<string>"
}
'import requests
url = "https://scrapebadger.com/v1/twitter/stream/filter-rules"
payload = {
"tag": "AI news tracker",
"query": "(\"artificial intelligence\" OR \"machine learning\") min_faves:100 lang:en",
"interval_seconds": 60,
"max_results_per_poll": 20,
"webhook_url": "https://example.com/webhooks/filter-rules",
"webhook_secret": "<string>"
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
tag: 'AI news tracker',
query: '("artificial intelligence" OR "machine learning") min_faves:100 lang:en',
interval_seconds: 60,
max_results_per_poll: 20,
webhook_url: 'https://example.com/webhooks/filter-rules',
webhook_secret: '<string>'
})
};
fetch('https://scrapebadger.com/v1/twitter/stream/filter-rules', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://scrapebadger.com/v1/twitter/stream/filter-rules",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'tag' => 'AI news tracker',
'query' => '("artificial intelligence" OR "machine learning") min_faves:100 lang:en',
'interval_seconds' => 60,
'max_results_per_poll' => 20,
'webhook_url' => 'https://example.com/webhooks/filter-rules',
'webhook_secret' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://scrapebadger.com/v1/twitter/stream/filter-rules"
payload := strings.NewReader("{\n \"tag\": \"AI news tracker\",\n \"query\": \"(\\\"artificial intelligence\\\" OR \\\"machine learning\\\") min_faves:100 lang:en\",\n \"interval_seconds\": 60,\n \"max_results_per_poll\": 20,\n \"webhook_url\": \"https://example.com/webhooks/filter-rules\",\n \"webhook_secret\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://scrapebadger.com/v1/twitter/stream/filter-rules")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"tag\": \"AI news tracker\",\n \"query\": \"(\\\"artificial intelligence\\\" OR \\\"machine learning\\\") min_faves:100 lang:en\",\n \"interval_seconds\": 60,\n \"max_results_per_poll\": 20,\n \"webhook_url\": \"https://example.com/webhooks/filter-rules\",\n \"webhook_secret\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://scrapebadger.com/v1/twitter/stream/filter-rules")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"tag\": \"AI news tracker\",\n \"query\": \"(\\\"artificial intelligence\\\" OR \\\"machine learning\\\") min_faves:100 lang:en\",\n \"interval_seconds\": 60,\n \"max_results_per_poll\": 20,\n \"webhook_url\": \"https://example.com/webhooks/filter-rules\",\n \"webhook_secret\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"id": "<string>",
"tag": "AI news tracker",
"query": "(\"artificial intelligence\" OR \"machine learning\") min_faves:100 lang:en",
"interval_seconds": 60,
"max_results_per_poll": 20,
"status": "active",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"status_reason": "<string>",
"webhook_url": "<string>",
"webhook_secret_set": true,
"credits_per_rule_per_day": 123,
"pricing_tier": "1-minute"
}{
"error": "Invalid or missing API key"
}{
"error": "Insufficient credits"
}{
"error": "Rate limit exceeded. Please retry after a short delay."
}Create Filter Rule
Create a new filter rule that monitors Twitter using an Advanced Search query at a configurable polling interval. Matching tweets are delivered via WebSocket and optionally via webhook. Pricing is based on the polling interval tier.
curl --request POST \
--url https://scrapebadger.com/v1/twitter/stream/filter-rules \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"tag": "AI news tracker",
"query": "(\"artificial intelligence\" OR \"machine learning\") min_faves:100 lang:en",
"interval_seconds": 60,
"max_results_per_poll": 20,
"webhook_url": "https://example.com/webhooks/filter-rules",
"webhook_secret": "<string>"
}
'import requests
url = "https://scrapebadger.com/v1/twitter/stream/filter-rules"
payload = {
"tag": "AI news tracker",
"query": "(\"artificial intelligence\" OR \"machine learning\") min_faves:100 lang:en",
"interval_seconds": 60,
"max_results_per_poll": 20,
"webhook_url": "https://example.com/webhooks/filter-rules",
"webhook_secret": "<string>"
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
tag: 'AI news tracker',
query: '("artificial intelligence" OR "machine learning") min_faves:100 lang:en',
interval_seconds: 60,
max_results_per_poll: 20,
webhook_url: 'https://example.com/webhooks/filter-rules',
webhook_secret: '<string>'
})
};
fetch('https://scrapebadger.com/v1/twitter/stream/filter-rules', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://scrapebadger.com/v1/twitter/stream/filter-rules",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'tag' => 'AI news tracker',
'query' => '("artificial intelligence" OR "machine learning") min_faves:100 lang:en',
'interval_seconds' => 60,
'max_results_per_poll' => 20,
'webhook_url' => 'https://example.com/webhooks/filter-rules',
'webhook_secret' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://scrapebadger.com/v1/twitter/stream/filter-rules"
payload := strings.NewReader("{\n \"tag\": \"AI news tracker\",\n \"query\": \"(\\\"artificial intelligence\\\" OR \\\"machine learning\\\") min_faves:100 lang:en\",\n \"interval_seconds\": 60,\n \"max_results_per_poll\": 20,\n \"webhook_url\": \"https://example.com/webhooks/filter-rules\",\n \"webhook_secret\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://scrapebadger.com/v1/twitter/stream/filter-rules")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"tag\": \"AI news tracker\",\n \"query\": \"(\\\"artificial intelligence\\\" OR \\\"machine learning\\\") min_faves:100 lang:en\",\n \"interval_seconds\": 60,\n \"max_results_per_poll\": 20,\n \"webhook_url\": \"https://example.com/webhooks/filter-rules\",\n \"webhook_secret\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://scrapebadger.com/v1/twitter/stream/filter-rules")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"tag\": \"AI news tracker\",\n \"query\": \"(\\\"artificial intelligence\\\" OR \\\"machine learning\\\") min_faves:100 lang:en\",\n \"interval_seconds\": 60,\n \"max_results_per_poll\": 20,\n \"webhook_url\": \"https://example.com/webhooks/filter-rules\",\n \"webhook_secret\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"id": "<string>",
"tag": "AI news tracker",
"query": "(\"artificial intelligence\" OR \"machine learning\") min_faves:100 lang:en",
"interval_seconds": 60,
"max_results_per_poll": 20,
"status": "active",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"status_reason": "<string>",
"webhook_url": "<string>",
"webhook_secret_set": true,
"credits_per_rule_per_day": 123,
"pricing_tier": "1-minute"
}{
"error": "Invalid or missing API key"
}{
"error": "Insufficient credits"
}{
"error": "Rate limit exceeded. Please retry after a short delay."
}Authorizations
Your ScrapeBadger API key. You can find this in your dashboard at https://scrapebadger.com/dashboard/api-keys.
Body
Filter rule configuration.
Human-readable label for the filter rule.
1 - 100"AI news tracker"
Twitter Advanced Search query. Supports operators like from:, to:, min_faves:, lang:, etc.
1 - 1024"(\"artificial intelligence\" OR \"machine learning\") min_faves:100 lang:en"
Polling interval in seconds. Lower intervals detect tweets faster but cost more credits per day.
0.1 <= x <= 8640060
Maximum number of tweets to return per poll cycle.
1 <= x <= 100HTTPS URL to receive webhook deliveries. Must use HTTPS.
"https://example.com/webhooks/filter-rules"
Secret used to sign webhook payloads with HMAC-SHA256.
Response
Filter rule created successfully.
Filter rule configuration and status.
Unique filter rule identifier.
Human-readable label for the rule.
"AI news tracker"
Twitter Advanced Search query.
"(\"artificial intelligence\" OR \"machine learning\") min_faves:100 lang:en"
Polling interval in seconds.
60
Maximum number of tweets returned per poll cycle.
20
Current status of the rule. Suspended indicates the rule was auto-paused due to insufficient credits.
active, paused, suspended Timestamp when the rule was created.
Timestamp when the rule was last updated.
Reason for the current status, if applicable.
HTTPS URL receiving webhook deliveries.
Whether a webhook secret is configured. The actual secret is never returned.
Credit cost per day for this rule at the current interval.
Current pricing tier label based on interval.
"1-minute"

