Data Types - Core X Tracker API

Message Structure

All WebSocket messages follow a consistent wrapper structure:

{
  "type": "data",
  "subscription_id": "sub_123",
  "data": { /* actual content */ },
  "timestamp": "2025-08-15T10:30:00Z",
  "sequence": 1
}

Tweet Object

The complete tweet object structure with all possible fields:

{
  "id": "1735678901234567890",
  "text": "Just landed Starship booster! 🚀",
  "created_at": "2025-08-15T14:30:00.000Z",
  "author_id": "44196397",
  "conversation_id": "1735678901234567890",
  "lang": "en",
  
  "author": {
    "id": "44196397",
    "name": "Elon Musk",
    "username": "elonmusk",
    "verified": true,
    "profile_image_url": "https://pbs.twimg.com/..."
  },
  
  "stats": {
    "retweet_count": 5420,
    "reply_count": 1250,
    "like_count": 45200,
    "quote_count": 890,
    "view_count": 1250000
  },
  
  "entities": {
    "hashtags": [...],
    "mentions": [...],
    "urls": [...],
    "cashtags": [...]
  },
  
  "attachments": {
    "media_keys": ["3_1735678901234567891"],
    "poll_ids": []
  },
  
  "referenced_tweets": [
    {
      "type": "replied_to",
      "id": "1735678801234567890"
    }
  ],
  
  "in_reply_to_user_id": "34743251",
  "possibly_sensitive": false,
  "reply_settings": "everyone",
  "source": "Twitter for iPhone"
}

Author Object

User/Author information structure:

{
  "id": "44196397",
  "name": "Elon Musk",
  "username": "elonmusk",
  "verified": true,
  "profile_image_url": "https://pbs.twimg.com/profile_images/...",
  "profile_banner_url": "https://pbs.twimg.com/profile_banners/...",
  "description": "CEO of Tesla, SpaceX",
  "followers_count": 150000000,
  "following_count": 250,
  "tweet_count": 25000,
  "listed_count": 95000,
  "created_at": "Tue Jun 02 20:12:29 +0000 2009",
  "location": "Texas",
  "url": "https://www.tesla.com",
  "protected": false,
  "pinned_tweet_ids": ["1234567890123456789"]
}

Entities

Hashtags

{
  "hashtags": [
    {
      "start": 35,
      "end": 45,
      "tag": "Starship"
    }
  ]
}

Mentions

{
  "mentions": [
    {
      "start": 50,
      "end": 59,
      "username": "SpaceX",
      "id": "34743251"
    }
  ]
}

URLs

{
  "urls": [
    {
      "start": 65,
      "end": 88,
      "url": "https://t.co/abc123",
      "expanded_url": "https://www.spacex.com/launches",
      "display_url": "spacex.com/launches",
      "images": [
        {
          "url": "https://pbs.twimg.com/news_img/...",
          "width": 1200,
          "height": 600
        }
      ],
      "status": 200,
      "title": "SpaceX Launches",
      "description": "Latest launch information"
    }
  ]
}

Media Types

Photo

{
  "media_key": "3_1735678901234567891",
  "type": "photo",
  "url": "https://pbs.twimg.com/media/abc123.jpg",
  "width": 1920,
  "height": 1080,
  "alt_text": "Starship booster landing"
}

Video

{
  "media_key": "7_1735678901234567892",
  "type": "video",
  "preview_image_url": "https://pbs.twimg.com/media/def456.jpg",
  "duration_ms": 45000,
  "width": 1280,
  "height": 720,
  "variants": [
    {
      "bit_rate": 2176000,
      "content_type": "video/mp4",
      "url": "https://video.twimg.com/ext_tw_video/..."
    },
    {
      "bit_rate": 832000,
      "content_type": "video/mp4",
      "url": "https://video.twimg.com/ext_tw_video/..."
    }
  ]
}

Animated GIF

{
  "media_key": "16_1735681001234567891",
  "type": "animated_gif",
  "url": "https://pbs.twimg.com/tweet_video/abc.mp4",
  "preview_image_url": "https://pbs.twimg.com/tweet_video_thumb/abc.jpg",
  "width": 498,
  "height": 280
}

Referenced Tweets

Reply

{
  "referenced_tweets": [
    {
      "type": "replied_to",
      "id": "1735678801234567890"
    }
  ],
  "in_reply_to_user_id": "34743251"
}

Retweet

{
  "referenced_tweets": [
    {
      "type": "retweeted",
      "id": "1735678801234567890"
    }
  ]
}

Quote Tweet

{
  "referenced_tweets": [
    {
      "type": "quoted",
      "id": "1735678801234567890"
    }
  ]
}

All Message Types

Common Message Types

These message types can appear in any subscription:

User Info

{
  "type": "data",
  "subscription_id": "sub_123",
  "data": {
    "type": "user_info",
    "user": {
      "id": "44196397",
      "name": "Elon Musk",
      "username": "elonmusk",
      "verified": true
    }
  }
}

Error

{
  "type": "data",
  "subscription_id": "sub_123",
  "data": {
    "type": "error",
    "message": "Failed to fetch tweet: Rate limit exceeded"
  }
}

Warning

{
  "type": "data",
  "subscription_id": "sub_123",
  "data": {
    "type": "warning",
    "message": "Tweet not found: 1234567890"
  }
}

Historical Complete

{
  "type": "data",
  "subscription_id": "sub_123",
  "data": {
    "type": "historical_complete",
    "total_tweets": 50,
    "message": "Historical tweets loaded"
  }
}

Heartbeat

{
  "type": "data",
  "subscription_id": "sub_123",
  "data": {
    "type": "heartbeat",
    "message": "Stream active",
    "checked_at": "2025-08-15T14:35:00Z"
  }
}

Subscription-Specific Messages

User Timeline Tweet

{
  "type": "data",
  "subscription_id": "sub_timeline_123",
  "data": {
    "id": "1735678901234567890",
    "text": "New tweet text here",
    "author_id": "44196397",
    "author": { /* author object */ },
    "created_at": "2025-08-15T14:30:00.000Z",
    "stats": { /* stats object */ },
    "entities": { /* entities */ },
    "attachments": { /* attachments */ }
  }
}

Engagement Stream - Initial Info

{
  "type": "data",
  "subscription_id": "sub_engagement_123",
  "data": {
    "type": "tweet_info",
    "tweet_id": "1735678901234567890",
    "tweet": {
      "id": "1735678901234567890",
      "text": "Tweet text preview...",
      "author": {
        "id": "44196397",
        "username": "elonmusk"
      }
    },
    "metrics": {
      "likes": 1500,
      "retweets": 250,
      "replies": 45,
      "views": 50000,
      "quotes": 23
    }
  }
}

Engagement Stream - Metrics Update

{
  "type": "data",
  "subscription_id": "sub_engagement_123",
  "data": {
    "type": "metrics_update",
    "tweet_id": "1735678901234567890",
    "changes": {
      "likes": {
        "delta": 500,
        "current": 2000
      },
      "retweets": {
        "delta": 50,
        "current": 300
      },
      "replies": {
        "delta": 10,
        "current": 55
      },
      "views": {
        "delta": 10000,
        "current": 60000
      }
    },
    "velocity": {
      "likes_per_minute": 8.3,
      "retweets_per_minute": 0.8,
      "replies_per_minute": 0.2,
      "views_per_minute": 166.7
    },
    "viral_signals": [
      "High like velocity: 150/min",
      "High retweet velocity: 75/min",
      "High total engagement: 15000"
    ]
  }
}

Multi-User Timeline - Historical Tweet

{
  "type": "data",
  "subscription_id": "sub_multi_123",
  "data": {
    "type": "historical_tweet",
    "tweet": {
      "id": "1735678901234567890",
      "text": "Historical tweet text",
      "author_id": "44196397",
      "author": { /* author object */ },
      "created_at": "2025-08-15T14:30:00.000Z",
      "stats": { /* stats object */ }
    }
  }
}

Multi-User Timeline - New Tweet

{
  "type": "data",
  "subscription_id": "sub_multi_123",
  "data": {
    "type": "new_tweet",
    "tweet": {
      "id": "1735678901234567890",
      "text": "New tweet detected",
      "author_id": "44196397",
      "author": { /* author object */ },
      "created_at": "2025-08-15T14:30:00.000Z",
      "stats": { /* stats object */ }
    },
    "timestamp": "2025-08-15T14:30:01Z"
  }
}

User Following - New Follow Event

{
  "type": "data",
  "subscription_id": "sub_following_123",
  "data": {
    "type": "follow",
    "event": "follow",
    "user": {
      "id": "44196397",
      "name": "Elon Musk",
      "username": "elonmusk",
      "verified": true
    },
    "timestamp": "2025-08-15T14:30:00Z"
  }
}

Monitoring Started

{
  "type": "data",
  "subscription_id": "sub_following_123",
  "data": {
    "type": "monitoring_started",
    "message": "Monitoring for new follow events",
    "timestamp": "2025-08-15T14:30:00Z"
  }
}

Error

{
  "type": "data",
  "subscription_id": "sub_123",
  "data": {
    "type": "error",
    "message": "Stream error: Rate limit exceeded"
  }
}

Complete Example: Tweet with Everything

View Complete Tweet Example

{
  "type": "data",
  "subscription_id": "sub_timeline_456",
  "data": {
    "id": "1735678901234567890",
    "text": "Just landed Starship booster! 🚀 @SpaceX #Starship $TSLA\nCheck it out: https://t.co/abc123",
    "created_at": "2025-08-15T14:30:00.000Z",
    "author_id": "44196397",
    "conversation_id": "1735678801234567890",
    "lang": "en",
    
    "author": {
      "id": "44196397",
      "name": "Elon Musk",
      "username": "elonmusk",
      "verified": true,
      "profile_image_url": "https://pbs.twimg.com/profile_images/..."
    },
    
    "entities": {
      "hashtags": [
        {
          "start": 35,
          "end": 44,
          "tag": "Starship"
        }
      ],
      "mentions": [
        {
          "start": 28,
          "end": 35,
          "username": "SpaceX",
          "id": "34743251"
        }
      ],
      "urls": [
        {
          "start": 65,
          "end": 88,
          "url": "https://t.co/abc123",
          "expanded_url": "https://www.spacex.com/launches/starship",
          "display_url": "spacex.com/launches/star…"
        }
      ],
      "cashtags": [
        {
          "start": 45,
          "end": 50,
          "tag": "TSLA"
        }
      ]
    },
    
    "attachments": {
      "media_keys": ["3_1735678901234567891", "7_1735678901234567892"]
    },
    
    "includes": {
      "media": [
        {
          "media_key": "3_1735678901234567891",
          "type": "photo",
          "url": "https://pbs.twimg.com/media/abc123.jpg",
          "width": 1920,
          "height": 1080,
          "alt_text": "Starship booster landing on launch tower"
        },
        {
          "media_key": "7_1735678901234567892",
          "type": "video",
          "preview_image_url": "https://pbs.twimg.com/media/def456.jpg",
          "duration_ms": 45000,
          "width": 1280,
          "height": 720,
          "variants": [
            {
              "bit_rate": 2176000,
              "content_type": "video/mp4",
              "url": "https://video.twimg.com/ext_tw_video/high.mp4"
            },
            {
              "bit_rate": 832000,
              "content_type": "video/mp4",
              "url": "https://video.twimg.com/ext_tw_video/low.mp4"
            }
          ]
        }
      ],
      "tweets": [
        {
          "id": "1735678801234567890",
          "text": "Preparing for Starship landing attempt",
          "author_id": "34743251"
        }
      ]
    },
    
    "referenced_tweets": [
      {
        "type": "replied_to",
        "id": "1735678801234567890"
      }
    ],
    
    "in_reply_to_user_id": "34743251",
    
    "stats": {
      "retweet_count": 5420,
      "reply_count": 1250,
      "like_count": 45200,
      "quote_count": 890,
      "view_count": 1250000
    },
    
    "context_annotations": [
      {
        "domain": {
          "id": "65",
          "name": "Interests and Hobbies Vertical"
        },
        "entity": {
          "id": "834828264786898944",
          "name": "Space & astronomy"
        }
      }
    ],
    
    "possibly_sensitive": false,
    "reply_settings": "everyone",
    "source": "Twitter for iPhone"
  },
  "timestamp": "2025-08-15T14:30:01Z",
  "sequence": 1
}

TypeScript Definitions

interface WebSocketMessage {
  type: "data" | "error" | "subscription_confirmed";
  subscription_id: string;
  data: any;
  timestamp: string;
  sequence?: number;
}

interface Tweet {
  id: string;
  text: string;
  created_at: string;
  author_id: string;
  conversation_id?: string;
  lang?: string;
  author?: Author;
  stats?: Stats;
  entities?: Entities;
  attachments?: Attachments;
  referenced_tweets?: ReferencedTweet[];
  in_reply_to_user_id?: string;
  includes?: Includes;
}

interface Author {
  id: string;
  name: string;
  username: string;
  verified?: boolean;
  profile_image_url?: string;
  profile_banner_url?: string;
  description?: string;
  followers_count: number;
  following_count: number;
  tweet_count: number;
  listed_count: number;
  created_at?: string;
  location?: string;
  url?: string;
  protected?: boolean;
  pinned_tweet_ids?: string[];
}

interface Stats {
  retweet_count: number;
  reply_count: number;
  like_count: number;
  quote_count: number;
  view_count: number;
}

interface Media {
  media_key: string;
  type: "photo" | "video" | "animated_gif";
  url?: string;
  preview_image_url?: string;
  width?: number;
  height?: number;
  duration_ms?: number;
  alt_text?: string;
  variants?: VideoVariant[];
}

interface VideoVariant {
  bit_rate?: number;
  content_type: string;
  url: string;
}

interface ReferencedTweet {
  type: "replied_to" | "quoted" | "retweeted";
  id: string;
}

interface EngagementUpdate {
  type: "metrics_update";
  tweet_id: string;
  changes: MetricChanges;
  velocity?: Velocity;
  viral_signals?: ViralSignals;
}

interface MetricChanges {
  likes?: ChangeDetail;
  retweets?: ChangeDetail;
  replies?: ChangeDetail;
  views?: ChangeDetail;
  quotes?: ChangeDetail;
}

interface ChangeDetail {
  delta: number;
  current: number;
}

interface Velocity {
  likes_per_minute: number;
  retweets_per_minute: number;
  replies_per_minute: number;
  views_per_minute: number;
}

type ViralSignals = string[];

WebSocket Streaming

​Message Structure

​Tweet Object

​Author Object

​Entities

​Hashtags

​Mentions

​URLs

​Media Types

​Photo

​Video

​Animated GIF

​Referenced Tweets

​Reply

​Retweet

​Quote Tweet

​All Message Types

​Common Message Types

​User Info

​Error

​Warning

​Historical Complete

​Heartbeat

​Subscription-Specific Messages

​User Timeline Tweet

​Engagement Stream - Initial Info

​Engagement Stream - Metrics Update

​Multi-User Timeline - Historical Tweet

​Multi-User Timeline - New Tweet

​User Following - New Follow Event

​Monitoring Started

​Error

​Complete Example: Tweet with Everything

​TypeScript Definitions

Message Structure

Tweet Object

Author Object

Entities

Hashtags

Mentions

URLs

Media Types

Photo

Video

Animated GIF

Referenced Tweets

Reply

Retweet

Quote Tweet

All Message Types

Common Message Types

User Info

Error

Warning

Historical Complete

Heartbeat

Subscription-Specific Messages

User Timeline Tweet

Engagement Stream - Initial Info

Engagement Stream - Metrics Update

Multi-User Timeline - Historical Tweet

Multi-User Timeline - New Tweet

User Following - New Follow Event

Monitoring Started

Error

Complete Example: Tweet with Everything

TypeScript Definitions