Create Stream Monitor

Create a new stream monitor to track one or more Twitter accounts in real time. New tweets from monitored accounts are delivered via WebSocket and optionally via webhook. Each monitored account consumes credits per day based on volume pricing.

POST /v1/twitter/stream/monitors

Create stream monitor

cURL

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": []
}
'

201

{
  "id": "<string>",
  "name": "Tech Leaders Monitor",
  "usernames": [
    "elonmusk",
    "sama"
  ],
  "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": [],
  "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

201

application/json

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"