Thrift API Definitions

Core Thrift type definitions used across the X Recommendation Algorithm services

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 {
  1: optional i64 userId
  2: optional i64 guestId
  3: optional i64 appId
  4: optional string ipAddress
  5: optional string userAgent
  6: optional string countryCode
  7: optional string languageCode
  9: optional bool isTwoffice
  10: optional set<string> userRoles
  11: optional string deviceId
  12: optional i64 guestIdAds
  13: 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 {
  1: required i64 tweetId
  2: required double score
  3: optional list<MetricTag> metricTags
  4: optional i64 authorId
  5: optional CandidateGenerationKey candidateGenerationKey
  1001: 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.

socialProofByType · map<SocialProofType, list<int64>> · required

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 {
  1: required i64 userId
  2: optional Reason reason
  3: optional AdImpression adImpression
  4: optional string trackingInfo
  5: optional ScoringDetails scoringDetails
  6: optional string recommendationFlowIdentifier
  7: 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

Related Documentation

• 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