Skip to main content

​
Subscription Message Format

{
  "type": "subscribe",
  "subscription_type": "user_timeline",
  "subscription_id": "custom-id-123",  // Optional
  "params": {
    // Parameters specific to subscription type
  }
}

​
Available Subscription Types

​
1. User Timeline

Stream tweets from a specific user’s timeline with real-time updates. Parameters:
ParameterTypeRequiredDefaultDescription
user_idstring*-User ID number
usernamestring*-Username (without @)
countnumber20Number of historical tweets to fetch (max: 100)
include_repliesbooleanfalseInclude reply tweets
stream_updatesbooleantrueContinue streaming new tweets after initial fetch
update_intervalnumber-Update frequency in seconds
*One of user_id or username is required Example: 
{
  "type": "subscribe",
  "subscription_type": "user_timeline",
  "params": {
    "username": "elonmusk",
    "count": 50,
    "include_replies": true,
    "stream_updates": true
  }
}

​
2. Tweet Details

Monitor specific tweets for updates (metrics, edits, replies). Parameters:
ParameterTypeRequiredDefaultDescription
tweet_idstring*-Single tweet ID to monitor
tweet_idsarray*-Array of tweet IDs to monitor (max 20)
include_repliesbooleantrueInclude reply tweets in stream
include_metricsbooleantrueInclude metrics updates
update_intervalnumber-Update frequency in seconds
*One of tweet_id or tweet_ids is required Example: 
{
  "type": "subscribe",
  "subscription_type": "tweet_details",
  "params": {
    "tweet_ids": ["1234567890123456789", "9876543210987654321"],
    "include_replies": true,
    "include_metrics": true
  }
}

​
3. User Replies

Stream replies from a specific user with real-time updates. Parameters:
ParameterTypeRequiredDefaultDescription
usernamestring✓-Username (without @)
countnumber20Number of historical replies to fetch (max: 100)
stream_updatesbooleantrueContinue streaming new replies
update_intervalnumber-Update frequency in seconds
Example: 
{
  "type": "subscribe",
  "subscription_type": "user_replies",
  "params": {
    "username": "naval"
  }
}

​
4. User Following

Monitor for NEW follow events only (follows that occur after monitoring starts).
Only detects new follows after subscription starts.
Parameters:
ParameterTypeRequiredDefaultDescription
user_idstring✓-User ID number
update_intervalnumber-Update frequency in seconds
Example: 
{
  "type": "subscribe",
  "subscription_type": "user_following",
  "params": {
    "user_id": "44196397"
  }
}

​
5. Multi-User Timeline

Stream tweets from multiple users in a unified, sorted timeline. Parameters:
ParameterTypeRequiredDefaultDescription
user_idsarray✓-Array of user IDs (max 10)
countnumber10Tweets per user to fetch (max: 50)
stream_updatesbooleantrueContinue streaming new tweets
update_intervalnumber-Update frequency in seconds
Example: 
{
  "type": "subscribe",
  "subscription_type": "multi_user_timeline",
  "params": {
    "user_ids": ["44196397", "2244994945", "14520320"]
  }
}

​
6. Engagement Stream

Monitor real-time engagement metrics with velocity tracking and viral detection. Parameters:
ParameterTypeRequiredDefaultDescription
tweet_idsarray✓-Array of tweet IDs (max 20)
update_intervalnumber-Update frequency in seconds
track_velocitybooleantrueCalculate engagement rate of change
viral_thresholdobjectSee belowThresholds for viral signal detection
Viral Threshold Defaults: 
{
  "likes_per_minute": 100,
  "retweets_per_minute": 50,
  "total_engagement": 10000
}
Example: 
{
  "type": "subscribe",
  "subscription_type": "engagement_stream",
  "params": {
    "tweet_ids": ["1234567890123456789", "9876543210987654321"],
    "track_velocity": true,
    "viral_threshold": {
      "likes_per_minute": 50,
      "retweets_per_minute": 20,
      "total_engagement": 5000
    }
  }
}
Returns: Engagement metrics with velocity (rate of change): 
{
  "type": "data",
  "subscription_id": "sub_123",
  "data": {
    "tweet_id": "1234567890123456789",
    "metrics": {
      "likes": 1500,
      "retweets": 250,
      "replies": 45,
      "views": 50000
    },
    "velocity": {
      "likes_per_minute": 12.5,
      "retweets_per_minute": 2.3,
      "viral_score": 0.85
    }
  }
}

​
Managing Subscriptions

​
Subscribe

ws.send(JSON.stringify({
  type: 'subscribe',
  subscription_type: 'user_timeline',
  subscription_id: 'my-custom-id',  // Optional
  params: { username: 'elonmusk' }
}));

​
Unsubscribe

ws.send(JSON.stringify({
  type: 'unsubscribe',
  subscription_id: 'my-custom-id'  // Or auto-generated ID
}));

​
Subscription Confirmation

{
  "type": "subscription_confirmed",
  "subscription_id": "sub_abc123",
  "subscription_type": "user_timeline",
  "params": { "username": "elonmusk" },
  "message": "Subscription created successfully"
}

​
Data Message Format

All subscriptions send data in this format: 
{
  "type": "data",
  "subscription_id": "sub_abc123",
  "data": {
    // Subscription-specific data
  },
  "timestamp": "2025-08-15T10:30:00Z"
}

​
Limits & Best Practices

Maximum 20 subscriptions per connection. Create multiple connections for more.
Use custom subscription_id values to easily manage multiple subscriptions.

​
Tips:

  • Group related subscriptions on the same connection
  • Use multi_user_timeline instead of multiple user_timeline subscriptions
  • Monitor engagement_stream for viral content detection
  • Implement backoff when receiving rate limit errors