WS Data Types & Events

Base Message Format

Every message sent over the websocket follows this base format:

export interface WebsocketWorkerEvent {
    id: string; // Unique ID for this event (use for debouncing and deduplication across multiple connections)
    type: string; // The type of event being sent
}

Tweet Events

tweet.mini.update

The fastest event for any new tweet. Sent immediately with compressed data.

export interface MiniTweetUpdate extends WebsocketWorkerEvent {
    type: 'tweet.mini.update';
    tweet: TwitterMiniTweet;
}

This is always the first event fired for any new tweet. It prioritizes speed over completeness, you get core tweet info instantly, but subtweet data (quotes, retweets, replies) won’t be populated yet.A tweet.update will follow shortly after if the tweet:

Is quoting, replying to, or retweeting another tweet

tweet.update

Full tweet data including subtweets (up to 2 levels deep).

export interface TweetUpdate extends WebsocketWorkerEvent {
    type: 'tweet.update';
    tweet: TwitterTweet;
}

Sent a bit after tweet.mini.update with complete tweet data including resolved subtweets.Note: Subtweet chains are resolved up to 2 levels deep. If a chain is 3+ levels (e.g. a retweet of a reply to another tweet), levels 3+ will have minimal/default data. See tweet.full for fully resolved deep chains.

tweet.update.expanded

Expanded tweet data with full text and article content.

export interface TweetUpdateExpanded extends WebsocketWorkerEvent {
    type: 'tweet.update.expanded';
    tweet: TwitterTweet;
}

Same as tweet.update but with full untruncated text and article content if present.Only sent when:

The tweet text was truncated in tweet.update
The tweet contains an article

tweet.full

Fully resolved deep chain (3-5+ levels) with complete data at every level.

export interface TweetFull extends WebsocketWorkerEvent {
    type: 'tweet.full';
    tweet: TwitterTweet;
}

Sent when a tweet has a subtweet chain 3 or more levels deep. Every level in the chain is fully resolved with complete author data, metrics, media, and body text.Only triggered for chains 3+ levels deep. Standalone tweets, simple retweets, and single-level quotes/replies will not trigger this event.Timeline:

tweet.mini.update arrives first (fastest)
tweet.update arrives ~60ms later (levels 3+ may have empty data)
tweet.full arrives ~200-500ms later (all levels fully resolved)

Example chain (5 levels):

Level 1: @elonmusk (QUOTE) "True"
  └─ Level 2: @DavidSacks (QUOTE) "And guess where those staffers went..."
      └─ Level 3: @beffjezos (QUOTE) "Here's the receipt..."
          └─ Level 4: @mattyglesias (QUOTE) "The hypothetical hypocrisy..."
              └─ Level 5: @beffjezos (TWEET) "Let's be real if the Dems had won..."

In tweet.update, levels 3-5 would have empty/default data. In tweet.full, every level has complete data.Supports up to 6 levels including the main tweet, we might increase it in the future, but 6 levels seems good for most use cases for now

Profile Events

profile.pinned.update

Fired when a tracked user pins a tweet to their profile.

export interface WorkerProfilePinnedUpdateEvent extends WebsocketWorkerEvent {
    type: 'profile.pinned.update';
    user: TwitterUser;
    pinned: TwitterTweet[];
}

profile.unpinned.update

Fired when a tracked user unpins a tweet from their profile.

export interface WorkerProfileUnpinnedUpdateEvent extends WebsocketWorkerEvent {
    type: 'profile.unpinned.update';
    user: TwitterUser;
    pinned: TwitterTweet[];
}

profile.update

Fired when a tracked user updates their profile information.

export interface ProfileUpdate extends WebsocketWorkerEvent {
    type: 'profile.update';
    user: TwitterUser;   // The new profile information
    before: TwitterUser; // The old profile information
}

Activity Events

following.update

Fired when a tracked user follows or unfollows another account.

export interface FollowingUpdate extends WebsocketWorkerEvent {
    type: 'following.update';
    change: 'unfollowed' | 'followed';
    following: TwitterUser; // The target user who was followed/unfollowed
    user: TwitterUser;      // The tracked user who performed the action
}

tweet.deleted

Fired when a tracked user's tweet is deleted.

export interface DeletedTweet extends WebsocketWorkerEvent {
    type: 'tweet.deleted';
    tweet: TwitterTweet; // Metrics may be outdated (likes, replies, retweets, etc)
    deleted_at: number;  // UNIX timestamp in milliseconds
}

Don’t rely on metrics being accurate for deleted tweets — they reflect the last known values before deletion.

Types

TwitterUser

Complete user profile data.

export interface TwitterUser {
    id: string;
    handle: string;
    private: boolean;
    verified: {
        type: 'none' | 'blue' | 'gold' | 'gray';
        label: null | {
            description: string;
            badge: null | string;
            url: null | string;
        };
    };
    sensitive: boolean;
    restricted: boolean;
    joined_at: number;

    profile: {
        name: string;
        location: null | string;
        avatar: null | string;
        banner: null | string;
        pinned: string[];
        url: null | {
            name: string;
            url: string;
            tco: string;
        };
        description: {
            text: string;
            urls: {
                name: string;
                url: string;
                tco: string;
            }[];
        };
    };

    metrics: {
        likes: number;
        media: number;
        tweets: number;
        friends: number;
        followers: number;
        following: number;
    };
}

Field	Description
`id`	The user’s account ID
`handle`	The user’s handle (without @)
`private`	Whether the account is currently private
`verified.type`	`blue` = blue checkmark, `gold` = business/organization, `gray` = government/official, `none` = not verified
`verified.label`	Affiliated organization info (badge, description, profile link) — null if none
`sensitive`	Whether the account is flagged for sensitive content
`restricted`	Whether the account is restricted for unusual activity
`joined_at`	UNIX timestamp in milliseconds
`profile.pinned`	Array of pinned tweet IDs
`metrics.friends`	Mutual followers (people who follow the user and the user follows back)

TwitterMiniUser

Compressed user data for fast delivery.

export interface TwitterMiniUser {
    id: string;
    handle: string;
    verified: {
        type: 'none' | 'blue' | 'gold' | 'gray';
        label: null | {
            description: string;
            badge: null | string;
            url: null | string;
        };
    };
    profile: {
        name: string;
        avatar: null | string;
    };
    metrics: {
        following: number;
        followers: number;
    };
}

TwitterTweet

Complete tweet data with all fields.

export interface TwitterTweet {
    id: string;
    type: 'TWEET' | 'RETWEET' | 'QUOTE' | 'REPLY';
    created_at: number;
    author: TwitterUser;
    subtweet: null | TwitterTweet;

    reply: null | {
        id: string;
        handle: string;
    };

    quoted: null | {
        id: string;
        handle: string;
    };

    body: {
        text: string;
        urls: {
            name: string;
            url: string;
            tco: string;
        }[];
        mentions: {
            id: string;
            name: string;
            handle: string;
        }[];
        components: (
            | { type: 'text'; text: string; bold: boolean; italics: boolean; }
            | { type: 'image'; url: string; }
            | { type: 'video'; url: string; }
        )[];
    };

    media: {
        images: string[];
        videos: string[];
        thumbnails: string[];
        proxied: null | {
            images: string[];
            thumbnails: string[];
        };
    };

    grok: null | {
        id: string;
        conversation: {
            from: 'USER' | 'AGENT';
            message: string;
            images: string[];
        }[];
    };

    card: null | {
        url: string;
        image: string;
        title: string;
        description: string;
    };

    poll: null | {
        ends_at: number;
        updated_at: number;
        choices: {
            label: string;
            count: number;
        }[];
    };

    article: null | {
        id: string;
        title: string;
        thumbnail: null | string;
        created_at: number;
        updated_at: number;
        body: {
            text: string;
            components: (
                | { type: 'divider'; }
                | {
                    type: 'text';
                    variant:
                        | 'header-one'
                        | 'header-two'
                        | 'paragraph'
                        | 'blockquote'
                        | 'ordered-list'
                        | 'unordered-list'
                        | 'latex-box'
                        | 'markdown-box';
                    lines: {
                        text: string;
                        styles: {
                            from: number;
                            to: number;
                            text: 'bold' | 'italics' | 'strikethrough';
                        }[];
                        urls: {
                            from: number;
                            to: number;
                            url: string;
                        }[];
                    }[];
                }
                | {
                    type: 'media';
                    variant: 'image' | 'gif' | 'video';
                    url: string;
                    thumbnail: string;
                    caption: null | string;
                }
                | {
                    type: 'tweet';
                    tweet: {
                        id: string;
                        url: string;
                        object: null | TwitterTweet;
                    };
                }
            )[];
        };
    };

    community: null | object;

    metrics: {
        likes: number;
        quotes: number;
        replies: number;
        retweets: number;
        advanced: null | {
            views: number;
        };
    };
}

Field	Description
`subtweet`	The nested tweet this tweet references (reply parent, quoted tweet, or retweeted tweet). Recursive — can contain its own subtweet.
`reply`	If this is a REPLY, contains the ID and handle of the tweet being replied to
`quoted`	If this is a QUOTE, contains the ID and handle of the tweet being quoted
`body.components`	Rich text components for expanded/long tweets — only populated in `tweet.update.expanded`
`media.proxied`	Proxied media URLs — not always available, fall back to normal URLs
`grok`	Embedded Grok AI conversation preview, if the tweet contains one
`card`	URL card preview (image, title, description) for linked articles
`article`	Full article content if the tweet is a Twitter article
`metrics.advanced`	View count — null until expanded version is fetched

TwitterMiniTweet

Compressed tweet data for fast delivery.

export interface TwitterMiniTweet {
    id: string;
    type: 'TWEET' | 'RETWEET' | 'QUOTE' | 'REPLY';
    created_at: number;
    author: TwitterMiniUser;
    subtweet: null | TwitterMiniTweet;

    reply: null | {
        id: string;
        handle: string;
    };

    quoted: null | {
        id: string;
        handle: string;
    };

    body: {
        text: string;
        urls: {
            name: string;
            url: string;
            tco: string;
        }[];
        mentions: {
            id: string;
            name: string;
            handle: string;
        }[];
    };

    media: {
        images: string[];
        videos: string[];
        thumbnails: string[];
        proxied: null | {
            images: string[];
        };
    };
}

Event Flow

Here’s the order events fire for different tweet types:

Standalone tweet:
tweet.mini.update  (instant)
tweet.update        (a tiny bit later, only if has URL/card)

Quote / Reply / Retweet (2 levels):
tweet.mini.update  (instant)
tweet.update        (a tiny bit later, subtweet fully resolved)

Deep chain (3+ levels):
tweet.mini.update  (instant)
tweet.update        (a tiny bit later, levels 3+ have minimal data)
tweet.full          (a little more later, ALL levels fully resolved)

We are always working on new events — keep an eye on this section for updates!

Getting started

Information

Management API

Data API

Base Message Format

Tweet Events

Profile Events

Activity Events

Types

TwitterUser

TwitterMiniUser

TwitterTweet

TwitterMiniTweet

Event Flow

​Base Message Format

​Tweet Events

​Profile Events

​Activity Events

​Types

​TwitterUser

​TwitterMiniUser

​TwitterTweet

​TwitterMiniTweet

​Event Flow

Base Message Format

Tweet Events

Profile Events

Activity Events

Types

TwitterUser

TwitterMiniUser

TwitterTweet

TwitterMiniTweet

Event Flow