Step 2: Ranking

Apply scoring logic to prioritize which candidates surface to the top. Once you've gathered a pool of potential content, this step ranks it using scoring algorithms. The goal: highlight the most relevant and engaging content for the user.

Scoring Algorithms

`scoring`

Select the ranking algorithm to personalize the feed.

Available Algorithms:

No Ranking:

none - No ranking applied; candidates remain in generation order

Trending & Popularity:

trending_v0.0.1 - Order by trending signals
popular_v0.0.1 - Order by popularity metrics

Affinity-Based (Social Graph):

user_affinity_all_following_v0.0.1 - Recommend items based on all of the user's followings
user_affinity_closest_following_v0.0.1 - Recommend items based on followings, with "closer" users (more frequent interaction) ranked higher

Interest-Based (User Behavior):

user_interest_all_v0.0.1 - Recommend items based on user interests, inferred from all past interactions
user_interest_recent_v0.0.1 - Recommend items based on user interests, inferred from past interactions with a recency bias
user_interest_all_v0.0.2 - Recommend items based on user interests (v0.0.2), inferred from all past interactions
user_interest_recent_v0.0.2 - Recommend items based on user interests (v0.0.2), inferred from past interactions with a recency bias

Topic-Based:

user_topics_v0.0.1 - Recommend items based on user topics

Balanced (Default):

balanced_feed_v0.0.1 - DEFAULT - Balanced mix of interest and affinity based scoring
balanced_feed_interest_bias_v0.0.1 - Balanced mix with a bias towards interest-based scoring
balanced_feed_affinity_bias_v0.0.1 - Balanced mix with a bias towards affinity-based scoring
balanced_feed_v0.0.2 - Balanced mix (v0.0.2)
balanced_feed_interest_bias_v0.0.2 - Balanced mix with interest bias (v0.0.2)
balanced_feed_affinity_bias_v0.0.2 - Balanced mix with affinity bias (v0.0.2)

Custom Weighted:

linear_boost_v0.0.1 - Build your own algorithm by weighting ranking features (requires weighted_scorings property)

Example:

{
  "scoring": "balanced_feed_v0.0.1"
}

Use Cases:

Balanced feeds: Default choice for most use cases, combines interest and social signals
Interest-focused: For users with rich interaction history
Affinity-focused: For social discovery and network-based recommendations
Trending: For discovery of popular content
Custom: For fine-tuned control over ranking factors

Custom Weighted Scoring

`weighted_scorings`

Build custom ranking algorithms by weighting specific features.

Required when: scoring is set to linear_boost_v0.0.1

Available Features:

interest_scores_all_v2 - All-time interest scores (v2)
interest_scores_recent_v2 - Recent interest scores (v2)
interest_scores_all_v1 - All-time interest scores (v1)
interest_scores_recent_v1 - Recent interest scores (v1)
trending_score - Trending signals
popular_score - Popularity metrics
affinity_score - User affinity scores
topic_scores - Topic relevance
cast_length - Post length
cast_image - Posts containing images
cast_video - Posts containing videos
cast_miniapp - Posts containing mini-apps
cast_zora - Posts containing Zora content

Weight Range: Each weight must be between 1 and 100

Example:

{
  "scoring": "linear_boost_v0.0.1",
  "weighted_scorings": [
    {
      "feature": "interest_scores_all_v2",
      "weight": 50
    },
    {
      "feature": "trending_score",
      "weight": 30
    },
    {
      "feature": "topic_scores",
      "weight": 70
    }
  ]
}

Use Cases:

Fine-tuned ranking control
A/B testing different ranking strategies
Platform-specific ranking requirements

Time Decay

`time_decay`

Control how content age affects ranking.

Properties:

enabled (boolean) - Whether time decay is applied to scoring
decay_rate (number) - Decay parameter from 0 to 1 (increments of 0.01). Higher values mean older posts receive lower scores more quickly.

Example:

{
  "time_decay": {
    "enabled": true,
    "decay_rate": 0.75
  }
}

Use Cases:

Keep feeds fresh
Prioritize recent content
Balance recency with quality

Diversity Controls

`diversity`

Ensure varied content in the feed, preventing over-representation of individual authors or topics.

Properties:

max_posts_per_author (integer, minimum: 1) - Maximum number of posts from a single author in the feed
min_distance_between_posts_from_same_author (integer, minimum: 0) - Minimum distance between posts from the same author. For example, if set to 5, then 2 posts from the same author must be separated by at least 5 posts in between.

Example:

{
  "diversity": {
    "max_posts_per_author": 3,
    "min_distance_between_posts_from_same_author": 5
  }
}

Use Cases:

Prevent author dominance in feeds
Ensure content variety
Improve feed diversity