CR Mixer API

API reference for CR Mixer (Candidate Recommendation Mixer), Twitter’s candidate generation service

Overview

CR-Mixer is a candidate generation service that speeds up iteration and development of candidate generation and light ranking. It acts as a lightweight coordinating layer that delegates candidate generation tasks to underlying compute services.

The service provides:

• Centralized platform for fetching and mixing candidate sources
• Light ranking layer for candidates
• Common filtering and deduplication
• Feature switch management and version control
• Performance optimization and caching

Service Definition

CR Mixer is defined in cr-mixer/thrift/src/main/thrift/cr_mixer.thrift

service CrMixer {
  CrMixerTweetResponse getTweetRecommendations(1: CrMixerTweetRequest request)
  RelatedTweetResponse getRelatedTweetsForQueryTweet(1: RelatedTweetRequest request)
  RelatedTweetResponse getRelatedTweetsForQueryAuthor(1: RelatedTweetRequest request)
  UtegTweetResponse getUtegTweetRecommendations(1: UtegTweetRequest request)
  FrsTweetResponse getFrsBasedTweetRecommendations(1: FrsTweetRequest request)
  RelatedVideoTweetResponse getRelatedVideoTweetsForQueryTweet(1: RelatedVideoTweetRequest request)
  AdsResponse getAdsRecommendations(1: AdsRequest request)
  TopicTweetResponse getTopicTweetRecommendations(1: TopicTweetRequest request)
}

getTweetRecommendations

Returns personalized tweet recommendations for a user.

Request

clientContext · ClientContext · required

Client context containing user identification and device information

userId · int64

User ID requesting recommendations (optional for logged-out users)

guestId · int64

Guest ID for logged-out users

appId · int64

Application identifier

countryCode · string

User’s country code

languageCode · string

User’s language preference

product · Product · required

Product surface requesting recommendations. Enum values:

• Home (1) - Home timeline
• Notifications (2) - Notification recommendations
• Email (3) - Email recommendations
• MoreTweetsModule (4) - Related tweets module
• ImmersiveMediaViewer (5) - Media viewer
• VideoCarousel (6) - Video recommendations
• ExploreTopics (7) - Topic exploration
• Ads (8) - Ads recommendations
• HomeRealTime (9) - Real-time home tab
• TopicLandingPage (10) - Topic pages

productContext · ProductContext

Product-specific parameters and configuration options

excludedTweetIds · list<int64>

Tweet IDs to exclude from recommendations (already seen or dismissed tweets)

Response

tweets · list<TweetRecommendation>

List of recommended tweets with scores and metadata

tweetId · int64 · required

Unique identifier for the recommended tweet

score · double · required

Recommendation score (higher is better)

metricTags · list<MetricTag>

Tags for tracking and attribution

authorId · int64

User ID of the tweet author

candidateGenerationKey · CandidateGenerationKey

Information about how the candidate was generated (source algorithm, similarity engine)

latestSourceSignalTimestampInMillis · int64

Timestamp of the most recent engagement signal used (null if not from engagement signals)

Exceptions

validationErrors · ValidationExceptionList

Validation errors with details reported to clients

serverError · ServerError

Server errors (details not reported to clients)

getRelatedTweetsForQueryTweet

Returns tweets related to a specific query tweet.

Request

internalId · InternalId · required

Internal identifier (tweet ID or user ID) to find related content for

product · Product · required

Product surface making the request

clientContext · ClientContext · required

Client context (userId may be None for logged-out users)

excludedTweetIds · list<int64>

Tweet IDs to exclude from results

Response

tweets · list<RelatedTweet>

List of related tweets

tweetId · int64 · required

Tweet identifier

score · double

Similarity/relevance score

authorId · int64

Tweet author’s user ID

getRelatedTweetsForQueryAuthor

Returns tweets related to a specific author’s content. Uses the same request/response structure as getRelatedTweetsForQueryTweet.

getUtegTweetRecommendations

Returns tweet recommendations based on User Tweet Entity Graph (UTEG) engagement signals.

Request

clientContext · ClientContext · required

Client context

product · Product · required

Product surface

productContext · ProductContext

Product-specific parameters

excludedTweetIds · list<int64>

Tweets to exclude

Response

tweets · list<UtegTweet>

UTEG-based tweet recommendations

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.

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

User social proofs grouped by engagement type (likes, retweets, replies, etc.)

getTopicTweetRecommendations

Returns tweet recommendations for specific topics.

Request

clientContext · ClientContext · required

Client context

product · Product · required

Product surface

topicIds · list<int64> · required

List of topic IDs to get recommendations for

productContext · ProductContext

Product-specific parameters

excludedTweetIds · list<int64>

Tweets to exclude

Response

tweets · map<int64, list<TopicTweet>> · required

Map from topic ID to list of recommended tweets for that topic

tweetId · int64 · required

Tweet identifier

score · double · required

Recommendation score

similarityEngineType · SimilarityEngineType · required

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

getFrsBasedTweetRecommendations

Returns tweet recommendations based on Follow Recommendations Service (FRS) suggestions - tweets from accounts the user may be interested in following.

See Thrift Definitions for complete type definitions.

Related APIs

• Home Mixer API - Main consumer of CR Mixer
• Follow Recommendations Service - Account recommendations
• Thrift Definitions - Complete API type definitions