Skip to main content

​
Overview

The Follow Recommendations Service (FRS) is a robust recommendation engine designed to provide users with personalized suggestions for accounts to follow. FRS supports Who-To-Follow (WTF) module recommendations across various Twitter product interfaces and delivers FutureGraph tweet recommendations (tweets from accounts users may want to follow). The service implements a multi-stage pipeline:
  1. Candidate Generation - Use various signals and algorithms to identify candidate accounts
  2. Filtering - Apply quality and health filters
  3. Ranking - Score candidates using ML models and heuristics
  4. Transform - Add social proof, tracking tokens, and other metadata
  5. Truncation - Trim to optimal result size

​
Service Definition

FRS is defined in follow-recommendations-service/thrift/src/main/thrift/follow-recommendations-service.thrift 
service FollowRecommendationsThriftService {
  RecommendationResponse getRecommendations(1: RecommendationRequest request)
  RecommendationDisplayResponse getRecommendationDisplayResponse(1: RecommendationRequest request)
  ScoringUserResponse scoreUserCandidates(1: ScoringUserRequest request)
  RecommendationResponse debugCandidateSource(1: DebugCandidateSourceRequest request)
  PipelineExecutionResult executePipeline(1: RecommendationRequest request)
}

​
getRecommendations

Returns personalized account recommendations for a user.

​
Request

​
clientContext
ClientContext
required
Client context containing caller/client level information
​
userId
int64
User ID requesting recommendations
​
guestId
int64
Guest ID for logged-out users
​
appId
int64
Application identifier
​
ipAddress
string
Client IP address
​
userAgent
string
Client user agent string
​
countryCode
string
Inferred country code
​
languageCode
string
Inferred language code
​
deviceId
string
Device identifier
​
displayLocation
DisplayLocation
required
Location where recommendations will be displayed. Key values:
  • HOME_TIMELINE (39) - Home timeline WTF module
  • PROFILE_SIDEBAR (2) - Profile page sidebar
  • EXPLORE_TAB (57) - Explore tab recommendations
  • NUX_PYMK (67) - New user experience “People You May Know”
  • NUX_INTERESTS (68) - New user interest-based recommendations
  • POST_NUX_FOLLOW_TASK (75) - Post-NUX follow task
  • HOME_TIMELINE_TWEET_RECS (83) - Tweet author recommendations in Home
  • MagicRecs (59) - Account recommendations in notifications
See complete list in display_location.thrift
​
displayContext
DisplayContext
Additional context about the display surface
​
maxResults
int32
Maximum number of recommendations to return
​
cursor
string
Cursor for pagination to continue returning results
​
excludedIds
list<int64>
User IDs to exclude from recommendations (already following, dismissed, etc.)
​
fetchPromotedContent
bool
Whether to include promoted (advertised) accounts in results
​
debugParams
DebugParams
Debug parameters for testing and development
​
userLocationState
string
User’s inferred location state

​
Response

​
recommendations
list<Recommendation>
required
List of account recommendations
​
user
UserRecommendation
User account recommendation
​
userId
int64
required
Recommended user’s ID
​
reason
Reason
Reason for the suggestion (e.g., social context like “Followed by X”)
​
adImpression
AdImpression
Present if this is a promoted account; used for ad impression tracking
​
trackingInfo
string
Tracking token for attribution and analytics
​
scoringDetails
ScoringDetails
Details about how the candidate was scored
​
recommendationFlowIdentifier
string
Identifier for which recommendation flow generated this candidate
​
featureOverrides
map<string, FeatureValue>
Feature switch overrides for this candidate

​
Exceptions

​
serverError
ServerError
Server-side error occurred
​
unknownClientIdError
UnknownClientIdError
Client ID is not recognized
​
noClientIdError
NoClientIdError
No client ID was provided

​
getRecommendationDisplayResponse

Returns recommendations with additional display metadata (headers, footers, presentation settings).

​
Request

Same as getRecommendations

​
Response

​
hydratedRecommendation
list<HydratedRecommendation>
required
Recommendations with hydrated display information
​
userId
int64
required
Recommended user ID
​
socialProof
string
Social proof text (e.g., “Followed by Alice and Bob”)
​
adImpression
AdImpression
Ad impression data if promoted account
​
trackingInfo
string
Tracking token
​
header
Header
Header component for the WTF module
​
footer
Footer
Footer component for the WTF module
​
wtfPresentation
WTFPresentation
Presentation settings for Who To Follow module

​
scoreUserCandidates

Scores a provided list of user candidates. Used for feature hydration and logging during data collection.

​
Request

​
clientContext
ClientContext
required
Client context
​
displayLocation
DisplayLocation
required
Display location
​
candidates
list<UserRecommendation>
required
List of user candidates to score
​
debugParams
DebugParams
Debug parameters

​
Response

​
candidates
list<UserRecommendation>
required
Scored candidates (currently returns empty list - used primarily for logging)

​
debugCandidateSource

Debug endpoint for getting recommendations from a single candidate source. Useful for testing and debugging individual candidate generation algorithms.

​
Request

​
clientContext
ClientContext
required
Client context
​
candidateSource
DebugCandidateSourceIdentifier
required
Identifier for the specific candidate source to test
​
uttInterestIds
list<int64>
User-Topic-Tweet (UTT) interest IDs
​
debugParams
DebugParams
Additional debug parameters
​
recentlyFollowedUserIds
list<int64>
Recently followed user IDs for context
​
recentlyEngagedUserIds
list<RecentlyEngagedUserId>
Recently engaged user IDs with engagement metadata
​
byfSeedUserIds
list<int64>
Based-on-your-follows seed user IDs
​
similarToUserIds
list<int64>
“Similar to” seed user IDs
​
applySgsPredicate
bool
required
Whether to apply Social Graph Service predicate filtering
​
maxResults
int32
Maximum results to return

​
Response

​
recommendations
list<Recommendation>
required
Recommendations from the specified candidate source

​
executePipeline

Executes a recommendation pipeline and returns the full execution log. Used by debugging tools to understand pipeline behavior.

​
Request

Same as getRecommendations

​
Response

​
pipelineExecutionResult
PipelineExecutionResult
Complete execution trace including:
  • Candidate sources called
  • Filters applied
  • Ranking scores
  • Transform operations
  • Timing information
  • Feature values

​
Machine Learning Pipeline

FRS uses ML models for ranking candidates:
  1. Feature Hydration - Fetch user and candidate features
  2. DataRecord Construction - Build DataRecord for each (user, candidate) pair
  3. ML Prediction - Send to ML prediction service
  4. Scoring - Weighted sum of p(follow|recommendation) and p(engagement|follow)
See Data Record Formats for details on the ML data format.

​
Candidate Sources

FRS supports multiple candidate generation algorithms:
  • Social graph-based (follow-of-follows, mutual follows)
  • Interest-based (topic affinity, entity graphs)
  • Geo-based (popular in region)
  • Engagement-based (profile visits, search clicks)
  • Model-based (SimClusters, embeddings)
Each display location can configure which candidate sources to use.

Build docs developers (and LLMs) love

Get started for freeTalk to us