v1

latestOpenAPI 3.1.02026-07-26180242448.0 KB

Filter Rules

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.

post/v1/twitter/stream/filter-rules

Request body

tagstring required

Human-readable label for the filter rule.

querystring required

Twitter Advanced Search query. Supports operators like from:, to:, min_faves:, lang:, etc.

interval_secondsnumber required

Polling interval in seconds. Lower intervals detect tweets faster but cost more credits per day.

max_results_per_pollinteger

Maximum number of tweets to return per poll cycle.

webhook_urlstring nullable

HTTPS URL to receive webhook deliveries. Must use HTTPS.

webhook_secretstring nullable

Secret used to sign webhook payloads with HMAC-SHA256.

Example request

{
  "tag": "AI news tracker",
  "query": "(\"artificial intelligence\" OR \"machine learning\") min_faves:100 lang:en",
  "interval_seconds": 60,
  "webhook_url": "https://example.com/webhooks/filter-rules"
}

Response

Filter rule created successfully.

idstring required

Unique filter rule identifier.

tagstring required

Human-readable label for the rule.

querystring required

Twitter Advanced Search query.

interval_secondsnumber required

Polling interval in seconds.

max_results_per_pollinteger required

Maximum number of tweets returned per poll cycle.

status'active' | 'paused' | 'suspended' required

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

status_reasonstring nullable

Reason for the current status, if applicable.

webhook_urlstring nullable

HTTPS URL receiving webhook deliveries.

webhook_secret_setboolean

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

credits_per_rule_per_daynumber

Credit cost per day for this rule at the current interval.

pricing_tierstring

Current pricing tier label based on interval.

created_atstring date-time required

Timestamp when the rule was created.

updated_atstring date-time required

Timestamp when the rule was last updated.

Example response

{
  "tag": "AI news tracker",
  "query": "(\"artificial intelligence\" OR \"machine learning\") min_faves:100 lang:en",
  "interval_seconds": 60,
  "max_results_per_poll": 20,
  "pricing_tier": "1-minute"
}