Follow Recommendations Service API

API reference for Twitter’s Follow Recommendations Service (FRS), providing personalized account suggestions

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.

Related APIs

• CR Mixer API - Tweet recommendations
• Data Record Formats - ML data format
• Thrift Definitions - Complete type definitions