Thrift API Definitions

Overview

The X Recommendation Algorithm uses Apache Thrift for service definitions and data serialization. This page documents the key Thrift types used across multiple services.

Common Types

ClientContext

Client context containing caller identification and device information. Used across all services.

struct ClientContext {
optional i64 userId
optional i64 guestId
optional i64 appId
optional string ipAddress
optional string userAgent
optional string countryCode
optional string languageCode
optional bool isTwoffice
optional set<string> userRoles
optional string deviceId
optional i64 guestIdAds
optional i64 guestIdMarketing
}

userId

int64

User ID for authenticated users (personalDataType=‘UserId’)

guestId

int64

Guest ID for logged-out users (personalDataType=‘GuestId’)

appId

int64

Application identifier (personalDataType=‘AppId’)

ipAddress

string

Client IP address (personalDataType=‘IpAddress’)

userAgent

string

Client user agent string (personalDataType=‘UserAgent’)

countryCode

string

Inferred country code (personalDataType=‘InferredCountry’)

languageCode

string

Inferred language code (personalDataType=‘InferredLanguage’)

deviceId

string

Device identifier (personalDataType=‘DeviceId’)

CR Mixer Types

Product

Enum identifying which product surface is making the request.

enum Product {
  Home = 1
  Notifications = 2
  Email = 3
  MoreTweetsModule = 4  # aka RUX (Related User eXperience)
  ImmersiveMediaViewer = 5
  VideoCarousel = 6
  ExploreTopics = 7
  Ads = 8
  HomeRealTime = 9
  TopicLandingPage = 10
  HomeTopicsBackfill = 11
  TopicTweetsStrato = 12
}

TweetRecommendation

A single tweet recommendation with score and metadata.

struct TweetRecommendation {
required i64 tweetId
required double score
optional list<MetricTag> metricTags
optional i64 authorId
optional CandidateGenerationKey candidateGenerationKey
optional i64 latestSourceSignalTimestampInMillis
}

tweetId

int64

required

Tweet identifier (personalDataType=‘TweetId’)

score

double

required

Recommendation score - higher values indicate stronger recommendations

metricTags

list<MetricTag>

Tags for metrics tracking and attribution

authorId

int64

Tweet author’s user ID (personalDataType=‘UserId’)

candidateGenerationKey

CandidateGenerationKey

Information about which algorithm generated this candidate

latestSourceSignalTimestampInMillis

int64

Latest timestamp of engagement signals used (null if not from engagement signals)

RelatedTweet

A tweet related to a query tweet or author.

struct RelatedTweet {
  1: required i64 tweetId
  2: optional double score
  3: optional i64 authorId
}

UtegTweet

Tweet recommendation from User Tweet Entity Graph with social proof.

struct UtegTweet {
  1: required i64 tweetId
  2: required double score
  3: required map<SocialProofType, list<i64>> socialProofByType
}

tweetId

int64

required

Tweet identifier

score

double

required

Sum of weights of seed users who engaged with the tweet. If a user engaged multiple times (e.g., liked and retweeted), their weight is counted for each engagement type.

Map from engagement type to list of user IDs who engaged in that way. Key is engagement type (like, retweet, reply), value is list of user IDs.

TopicTweet

Tweet recommendation for a specific topic.

struct TopicTweet {
  1: required i64 tweetId
  2: required double score
  3: required SimilarityEngineType similarityEngineType
}

similarityEngineType

SimilarityEngineType

required

Algorithm used to generate this recommendation (SimClustersANN, TwHINANN, UTEG, etc.)

Follow Recommendations Types

DisplayLocation

Enum specifying where recommendations will be displayed.

enum DisplayLocation {
  SIDEBAR = 0
  PROFILE_SIDEBAR = 2
  HOME_TIMELINE = 39              # Home timeline WTF module
  EXPLORE_TAB = 57
  MagicRecs = 59                  # Notification recommendations
  NUX_PYMK = 67                   # New User: People You May Know
  NUX_INTERESTS = 68              # New User: Interest-based
  POST_NUX_FOLLOW_TASK = 75
  HOME_TIMELINE_TWEET_RECS = 83   # Tweet author recommendations
  # ... (50+ total display locations)
}

Key display locations:

HOME_TIMELINE (39) - WTF module in Home timeline
NUX_PYMK (67) - New user “People You May Know”
HOME_TIMELINE_TWEET_RECS (83) - FutureGraph tweet author recommendations
MagicRecs (59) - Account recommendations in notifications

UserRecommendation

A recommended user account.

struct UserRecommendation {
required i64 userId
optional Reason reason
optional AdImpression adImpression
optional string trackingInfo
optional ScoringDetails scoringDetails
optional string recommendationFlowIdentifier
optional map<string, FeatureValue> featureOverrides
}

userId

int64

required

Recommended user’s ID (personalDataType=‘UserId’)

reason

Reason

Reason for the recommendation (social context, e.g., “Followed by X”)

adImpression

AdImpression

Present if this is a promoted account; used for ad impression tracking

trackingInfo

string

Opaque tracking token for attribution

scoringDetails

ScoringDetails

Information about the candidate’s score and ranking

recommendationFlowIdentifier

string

Identifier for which recommendation flow generated this candidate

Source Signals

SourceType

Enum identifying the type of user signal used for candidate generation.

enum SourceType {
  // Tweet engagement signals
  TweetFavorite = 0
  Retweet = 1
  OriginalTweet = 3
  Reply = 4
  TweetShare = 5
  GoodTweetClick = 6              # Dwell time > N seconds
  VideoTweetQualityView = 7
  VideoTweetPlayback50 = 8
  
  // User relationship signals
  UserFollow = 101
  UserRepeatedProfileVisit = 102
  RealGraphOon = 104
  FollowRecommendation = 105
  
  // Notification signals
  NotificationClick = 201
  
  // Home timeline signals
  HomeTweetClick = 301
  HomeVideoView = 302
  
  // Negative signals
  TweetReport = 1101
  TweetDontLike = 1102
  AccountBlock = 1104
  AccountMute = 1105
}

SimilarityEngineType

Enum identifying which similarity/recommendation algorithm was used.

enum SimilarityEngineType {
  SimClustersANN = 1                    # SimClusters Approximate Nearest Neighbor
  TweetBasedUserTweetGraph = 2
  TweetBasedTwHINANN = 3               # TwHIN (Twitter Heterogeneous Information Network)
  Follow2VecANN = 4
  UTEG = 17                            # User Tweet Entity Graph
  ConsumerEmbeddingBasedTwoTowerANN = 14
  TwhinCollabFilter = 12
  EarlybirdRecencyBasedSimilarityEngine = 21
  EarlybirdModelBasedSimilarityEngine = 22
  # ... (35+ total engine types)
}

Key algorithms:

SimClustersANN - Community-based clustering and similarity
TweetBasedTwHINANN - Heterogeneous graph neural network
UTEG - User Tweet Entity Graph engagement-based
TwhinCollabFilter - Collaborative filtering with TwHIN embeddings
Earlybird* - Real-time search index-based

Error Types

ValidationExceptionList

List of validation errors with details reported to clients.

struct ValidationExceptionList {
  1: required list<ValidationException> errors
}

struct ValidationException {
  1: required string message
  2: optional string field
}

ServerError

Generic server error. Details are not reported to clients for security.

exception ServerError {
  1: string message
}

Data Annotations

Thrift definitions include personal data annotations for privacy compliance:

personalDataType='UserId' - Twitter user identifier
personalDataType='TweetId' - Tweet identifier
personalDataType='IpAddress' - IP address
personalDataType='DeviceId' - Device identifier
hasPersonalData='true' - Struct contains personal data
persisted='true' - Data may be persisted to storage

CR Mixer API - CR Mixer service endpoints
Follow Recommendations Service API - FRS service endpoints
Data Record Formats - ML data format

Source Files

Thrift definitions can be found in the source repository:

cr-mixer/thrift/src/main/thrift/ - CR Mixer definitions
follow-recommendations-service/thrift/src/main/thrift/ - FRS definitions
src/thrift/com/twitter/ - Shared common definitions

Services

Data Models

Overview

Common Types

ClientContext

CR Mixer Types

Product

TweetRecommendation

RelatedTweet

UtegTweet

TopicTweet

Follow Recommendations Types

DisplayLocation

UserRecommendation

Source Signals

SourceType

SimilarityEngineType

Error Types

ValidationExceptionList

ServerError

Data Annotations

Source Files

Build docs developers (and LLMs) love

Services

Data Models

​Overview

​Common Types

​ClientContext

​CR Mixer Types

​Product

​TweetRecommendation

​RelatedTweet

​UtegTweet

​TopicTweet

​Follow Recommendations Types

​DisplayLocation

​UserRecommendation

​Source Signals

​SourceType

​SimilarityEngineType

​Error Types

​ValidationExceptionList

​ServerError

​Data Annotations

​Related Documentation

​Source Files

Build docs developers (and LLMs) love

Overview

Common Types

ClientContext

CR Mixer Types

Product

TweetRecommendation

RelatedTweet

UtegTweet

TopicTweet

Follow Recommendations Types

DisplayLocation

UserRecommendation

Source Signals

SourceType

SimilarityEngineType

Error Types

ValidationExceptionList

ServerError

Data Annotations

Related Documentation

Source Files