Skip to main content
POST
/
v1
/
twitter
/
stream
/
monitors
Create stream monitor
curl --request POST \
  --url https://scrapebadger.com/v1/twitter/stream/monitors \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "name": "Tech Leaders Monitor",
  "usernames": [
    "elonmusk",
    "sama"
  ],
  "webhook_url": "https://example.com/webhooks/twitter",
  "webhook_secret": "<string>",
  "filter_types": [
    "original"
  ]
}
'
{
  "id": "<string>",
  "name": "Tech Leaders Monitor",
  "usernames": [
    "elonmusk",
    "sama"
  ],
  "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,
  "filter_types": [
    "original"
  ],
  "credits_per_account_per_day": 123,
  "estimated_credits_per_day": 123,
  "pricing_tier": "Standard"
}

Authorizations

​
x-api-key
string
header
required

Your ScrapeBadger API key. You can find this in your dashboard at https://scrapebadger.com/dashboard/api-keys.

Body

application/json

Stream monitor configuration.

​
name
string
required

Human-readable name for the stream monitor.

Required string length: 1 - 100
Example:

"Tech Leaders Monitor"

​
usernames
string[]
required

List of Twitter usernames to monitor (without @ symbol).

Required array length: 1 - 100 elements
Example:
["elonmusk", "sama"]
​
webhook_url
string | null

HTTPS URL to receive webhook deliveries. Must use HTTPS.

Example:

"https://example.com/webhooks/twitter"

​
webhook_secret
string | null

Secret used to sign webhook payloads with HMAC-SHA256.

​
filter_types
enum<string>[] | null

Filter which tweet types to deliver. Null or omitted means all types.

Available options:
original,
reply,
retweet,
quote

Response

Stream monitor created successfully.

Stream monitor configuration and status.

​
id
string
required

Unique stream monitor identifier.

​
name
string
required

Human-readable name of the monitor.

Example:

"Tech Leaders Monitor"

​
usernames
string[]
required

List of monitored Twitter usernames.

Example:
["elonmusk", "sama"]
​
status
enum<string>
required

Current status of the monitor. Suspended indicates the monitor was auto-paused due to insufficient credits.

Available options:
active,
paused,
suspended
​
created_at
string<date-time>
required

Timestamp when the monitor was created.

​
updated_at
string<date-time>
required

Timestamp when the monitor was last updated.

​
status_reason
string | null

Reason for the current status, if applicable (e.g., "insufficient_credits").

​
webhook_url
string | null

HTTPS URL receiving webhook deliveries.

​
webhook_secret_set
boolean

Whether a webhook secret is configured. The actual secret is never returned.

​
filter_types
enum<string>[] | null

Tweet types being delivered. Null means all types.

Available options:
original,
reply,
retweet,
quote
​
credits_per_account_per_day
number

Credit cost per monitored account per day.

​
estimated_credits_per_day
number

Estimated total credit cost per day based on current account count.

​
pricing_tier
string

Current pricing tier label.

Example:

"Standard"