How it works

How to Design a Social Media Timeline Algorithm

Design a social media timeline algorithm: sourcing, scoring, hard and soft filters, ranked and chronological tabs, and rules to ship.

By the GetFame team, reviewed by Aditya Bhimrajka Updated 14 min read

Short answer

To design a social media timeline algorithm, build five separate stages: candidate sourcing, a few stored features, scoring, filters and mixing. Apply hard rules such as blocks and mutes before ranking, soft rules such as author caps after it, keep a chronological tab, and log why each post was shown. X's open code is a useful structural reference, not a live formula.

Key takeaways

  • Treat the timeline as a ranked list built on demand from separate stages: sourcing, features, scoring, filters and mixing.
  • Apply hard rules (blocks, mutes, suspended accounts) before ranking and soft balancing rules (author caps, repeats) after it.
  • A small network can start with followed accounts plus a one-line weighted score you can compute by hand and explain.
  • Record negative signals as carefully as likes, or the feed learns to favor provocative posts.
  • Decide in writing whether paid status can touch reach, and disclose it; a hidden boost damages trust.
  • X's published code is a historical snapshot that shows structure, not the weights or experiments running today.
On this page 11 sections
  1. How a social media timeline algorithm builds a ranked list
  2. The five-stage pipeline X published
  3. Candidate sources: in-network and out-of-network
  4. Signals worth recording, and how each gets abused
  5. Hard filters before ranking, soft filters after
  6. A timeline score you can compute by hand
  7. Ranked or chronological: the design tradeoffs
  8. A rule set a small network can ship
  9. Should paying change reach?
  10. How our platform builds the timelines
  11. Choose your first tab, then plan the launch
How to design a social media timeline algorithm: sculptural connected speech tiles representing public conversation
Conceptual illustration of public conversations connected on a text-based social platform; it is not an X interface or a ranking result.

How to design a social media timeline algorithm is a question every microblogging founder hits in the first month, and the best public reference is the timeline pipeline X has published as open code. That code is a historical architecture snapshot, not a verified description of the live system, so it teaches structure rather than weights. Structure is what a founder needs: which stages exist, which ones can be skipped at small scale, which rules must run before ranking, and who is allowed to change them.

This guide reads the published pipeline as a design spec, labels what is general recommender practice, and ends with a rule set a small network can ship. If you want a working base to tune, our white-label Twitter clone ships three named timelines, so you have a ranking to adjust from the first day.

How a social media timeline algorithm builds a ranked list

Nobody stores a finished feed per member and waits for it to be opened. When a member opens the app, the system asks a set of sources for posts that might interest them, scores those candidates, removes the ones that should not appear and returns a page. That framing separates two things founders often blur. The follow graph is data: who follows whom, who blocked whom. The ranking layer is logic: given a pool of posts, what order suits this person right now. You can change the second without touching the first, which is why one set of posts can power several tabs.

X's help center distinguishes personalized recommendations from followed-account content, and the Home Mixer overview in its repository describes For You, Following and Lists. Do not assume the live Following surface is an unfiltered time query: ads, reposts and conversation context need separate handling, and your own product will need the same care.

The five-stage pipeline X published

The repository README and the Home Mixer overview describe the same shape. The table summarizes it in our words; read the sources for exact wording.

StageWhat the documents describeWhat a small network can do instead
Candidate sourcingSeveral services retrieve posts: an index for in-network posts, a graph service for out-of-network posts, and a follow-recommendation serviceFollowed accounts plus one simple out-of-network list, such as most-replied posts of the day
Feature hydrationThe overview says a large set of features is fetched to support scoringA handful of counters stored on the post: replies, reposts, likes, age
Scoring and rankingA light ranker prunes, then a heavy neural ranker scores the shortlistA weighted sum you can write on one line
Filters and heuristicsAuthor diversity, content balance, fatigue, de-duplication and visibility filteringAn author cap per page and a repeat limit
Mixing and servingAds, follow suggestions and prompts are combined with posts, then paginated for the clientInsert ads and suggestions at fixed positions you control

Two details are worth remembering. The README says about half of the For You timeline comes from in-network posts, which is a statement in a snapshot and not a guaranteed current ratio. And it places the heavy-ranker model in a separate repository, so the public code shows how the pieces connect more than it shows final weights. Anyone who claims to know the exact reach penalty for a link, a hashtag or a time of day is guessing.

Candidate sources: in-network and out-of-network

In-network candidates are safe: the member chose the author, so relevance is likely and surprises are rare. Out-of-network candidates are where growth comes from, because they let a post reach people who do not follow the author. They are also where the risk sits, since a bad recommendation looks like the platform endorsing the post.

The README names an index service for in-network posts, a graph service that walks recent interactions, and models for communities, embeddings, relationship strength and account reputation. Treat those as four ideas any network can copy at smaller scale: groups of accounts that follow the same people, numeric summaries that place similar items close together, how likely one account is to interact with another, and a reputation score. On a network with 500 members, a graph service has almost nothing to walk. Your out-of-network source can be trending hashtags or the most-replied posts of the day, and it is easy to explain to members.

Ranking a network with very few posts

A new network has the opposite problem from a large one: too few candidates, not too many. If 40 members post a handful of times a day, a ranker has little to choose between, and a strict score can leave the page nearly empty or show the same three posts all afternoon. Three adjustments help while the pool is small.

  • Lower the bar for what counts as a candidate. Include replies to posts the member follows, not only top-level posts, so the page has something to show.
  • Widen the time window. A post that would be stale on a busy network is still fresh on a quiet one. Let the age penalty grow slowly at first and tighten it as volume rises.
  • Seed the out-of-network list by hand. An editor who picks a few good posts each day does more for a young feed than any scoring rule, and it teaches you what members respond to before you automate anything.

Revisit these settings each time the daily post count doubles. A rule that suited 40 members will feel too loose at 4,000.

Signals worth recording, and how each gets abused

The published code summary mentions explicit signals such as likes and implicit ones such as profile visits. It does not list every signal and weight, so the table is general recommender practice, not a description of X's scoring. Use it to decide what your own system should log, and what fraud to expect.

SignalWhy it mattersAbuse risk
RecencyConversation decays quickly, so old posts rarely satisfyLow, but rewards constant posting if used alone
RepliesA reply costs effort, so it signals interest more than a likeReply farming, where accounts bait arguments
Reposts and quotesMembers spend their own reputation, a strong endorsementCoordinated amplification by groups of accounts
LikesCheap and frequent: volume without nuanceBought or scripted likes
Relationship strengthPosts from accounts you often engage with deserve a boostEntrenches the same voices
Blocks, mutes and reportsThe clearest negative signal you will getMass reporting used to silence someone
Dwell timeTime on a post shows attention without a tapInflated by clickbait length

Negative signals deserve as much design as positive ones. A feed that only learns from taps learns to show provocative posts, because provocative posts get tapped. Blocks, mutes, a not-interested action and reports should lower the score of similar content for that member.

Hard filters before ranking, soft filters after

The Home Mixer overview lists filtering as a separate step after scoring, and a separate set of visibility filters enforces policy. Order matters, and this is where homemade feeds fail. Consider two designs. If you filter and then rank, blocked and muted authors are removed from the pool and the scorer never sees them, which is cheap and safe. If you rank and then filter, the scorer sees everything and a bug in the filter exposes a post the member blocked.

The safest pattern is to apply hard rules before ranking, such as blocks, mutes, suspended accounts and age limits, and apply soft balancing rules after it, such as author diversity and de-duplication. Hard rules protect people. Soft rules protect the page. Cover the hard rules with a test, because a regression there is a safety incident and not a cosmetic bug.

Author cap example with illustrative numbers

Suppose a ranker returns 20 posts for a member and 9 come from one prolific account. With no diversity rule the member reads nine posts from one voice. With a cap of three per author per page, six of those drop to later pages, and the page holds fourteen posts unless the system fetches replacements. Nothing was deleted; the rule only spreads the page out. The figures are illustrative, but they show why diversity filters exist, and why a busy account's post sometimes appears later than its author expects.

Failure modes to watch for in a filter chain

Filters fail quietly, so it helps to know the shapes the failures take. Each one below is a pattern seen in feed systems generally, not a claim about any one network.

  • The empty page. Stacked filters remove nearly every candidate, and the member sees a blank feed or a spinner. Count how many candidates enter and leave each stage, and alert when the final page is short.
  • The stale mute. A member mutes an account, but a cached candidate list still holds that account's posts for several minutes. Apply block and mute checks at read time, not only when the list is built.
  • The invisible author. A soft rule such as an author cap or a repeat limit pushes a quiet account's only post off every page. Cap the maximum, but also reserve a place for accounts that rarely post.
  • The echo. A strong relationship boost keeps showing the same handful of voices. Mix in a share of fresh accounts, and review that share when members complain that the feed feels repetitive.
  • The silent default. A new rule ships with a default nobody reviewed, and it changes reach for thousands of posts. Write the default into the change note and name the person who approved it.

The common defense is the same in every case: log what enters and leaves each stage, and look at those counts each week. A flat line is usually fine; a sudden step usually points to the change that caused it.

A timeline score you can compute by hand

To see how a small network could rank without a learned model, take an illustrative formula. Each candidate gets 10 points for being from a followed account, 6 more for an account the member replied to in the last week, 4 for each reply received in the first hour capped at 12, and minus 2 per hour of age.

  • Post A, from a followed account, 3 hours old with 2 replies: 10 plus 8 minus 6 gives 12.
  • Post B, from a stranger, 1 hour old with 3 replies: 0 plus 12 minus 2 gives 10.

Post A wins narrowly. Post B has already reached the twelve-point reply cap, so extra replies do not raise its score. If Post B came from a muted account, the hard filter would remove it before scoring and the comparison would never happen. The numbers are not a recommendation. What matters is that you can write the rule down, compute it by hand and explain a result to a member who asks.

Ranked or chronological: the design tradeoffs

Neither mode is better; they answer different questions.

QuestionChronologicalRanked
Does a new account get seen?Only by its followersYes, if the ranker picks it as out-of-network
Can the member predict what appears?Yes, newest from chosen peopleLess so; the order is the system's judgment
What happens to a heavy poster?They dominate the topDiversity rules can limit them
Does it miss good posts?Yes, if the member was awayLess often; strong older posts can resurface
Is it easy to explain?YesNeeds a why-am-I-seeing-this cue

This is why most networks with both keep a ranked tab and a chronological tab. Mastodon's site goes the other way and promises chronological feeds with no ranking algorithm or ads, while Bluesky describes several feed choices; we compare the models in Mastodon vs Bluesky vs a private network. For the video version of the same problem, see our guide on recommendation algorithms for short video apps. On a tiny graph a ranked feed feels random, so with fewer than a few hundred active members lead with the chronological tab and use the ranked one for suggestions.

A rule set a small network can ship

You do not need X's machinery. You need a few rules you can explain and change.

  1. Start with Following. Time-ordered posts from followed accounts form the baseline everything else is compared against.
  2. Add a simple score for the second tab. Recency, a boost for accounts the member interacts with, a boost for replies.
  3. Apply hard filters first. Blocks, mutes, suspended accounts and anything under a safety hold.
  4. Apply soft filters last. Author cap per page, de-duplication, a limit on repeats across sessions.
  5. Log every decision. Store the score, candidate source and rule that placed each shown post, or you cannot answer a creator who asks why a post got no reach.
  6. Show a reason. Two words such as "from someone you follow" or "popular in your topics" build trust.
  7. Let members choose the first tab. A stored preference costs nothing and avoids a fight over defaults.
  8. Add a learned model last, only when your simple rule clearly leaves value behind.

Testing a ranking change before members see it

Every change to a score is a bet about what people want, and the cheapest way to lose the bet is to ship it to everyone at once. A small network does not have the traffic for formal experiments, but it can still be careful.

  1. Replay first. Take the last day of posts and interactions, run the old and new rules over them, and compare the top ten for a handful of real members. If the new order surprises you, it will surprise them.
  2. Change one thing at a time. If you alter the reply boost and the age penalty together and engagement moves, you will not know which change did it.
  3. Use a small group. Give the new rule to staff and a few volunteers for a week and ask what felt different, before widening it.
  4. Pick the measure before the test. Replies per session, return visits the next day and reports per thousand posts tell different stories. Decide which one counts and which one is a warning sign.
  5. Keep a way back. A setting you can flip in minutes is worth more than a clever rule you cannot undo.

Explaining feed decisions to creators

Sooner or later a creator writes in to ask why a post got little reach. A support team with no answer will say "the algorithm", and that phrase costs trust. A team that logs the candidate source, the score and the rule that placed each post can answer in a few lines: the post was shown to followers on the Following tab, it ranked low on the second tab because it was four hours old, and no filter removed it.

Write three or four stock explanations in advance, one for each common cause: the post was filtered by a hard rule, it was outscored, it was shown but not opened, or it was never a candidate. Pair each with what the creator can do next, such as posting when followers are active or inviting replies. Be honest when the cause is a safety rule, and never invent a reason. Members forgive a plain "this was held for review" far more readily than a vague answer that later proves false.

Operators also need a view of their own feed rules. In the Twitter clone, the audit log records the administrator, action, target and reason on privileged operations, so a moderation decision that affects reach can be explained months later. Reading that log alongside your ranking notes shows whether a drop in reach came from a rule change or from a moderation action.

Should paying change reach?

X's Premium help documents reply prioritization for subscribers. That is evidence about replies, not a universal main-feed multiplier or a reach guarantee. For your own network this is a policy decision more than a technical one. There are three honest options: no reach benefit for paying, a small disclosed benefit on specific surfaces such as replies, or an ad product where reach is sold and labeled. The dishonest option is a hidden boost, which members eventually notice and read as betrayal. Our guide to paid verification and tiers covers how to package the entitlement either way.

How our platform builds the timelines

Our Twitter clone offers three named timelines, which are For You, Following and Bookmarks. Following lists the accounts a member follows. For You is a ranked feed the operator can tune. Each member stores which timeline opens first. Follows, lists, blocks and mutes are explicit records, so they can be enforced the same way everywhere, and the report queue offers five resolution actions (hide, unhide, delete, suspend, ban) with an audit log that records who did what and why. Operators also get typed ad campaigns with budgets and daily caps, so the ranked feed and the ad surface can be planned together.

The stack is Next.js with a Flutter mobile app and Firebase Firestore underneath, with an operator console on a separate login. Full source code, branded deployment within 6 working days, a year of updates at no charge, a two-month technical support window and six months of fixes for timeline bugs come with the ready-made platform at a one-time $3,699. Payment integrations or automated moderation are available as tailored work that typically takes 2 to 8 weeks, and we agree the scope in writing. We do not claim the build copies X's pipeline; it is original software with dials for you to turn. The Twitter clone features page lists everything around the timeline, and the business model page shows how timelines, tiers and ads fit together.

Limits of reading open-source ranking code

  • It is a snapshot. It cannot show weights, thresholds or experiments running today.
  • The heavy model lives elsewhere. The README points to a separate repository for it.
  • It does not explain behavior. Knowing a fatigue filter exists does not tell you how many repeats it allows.
  • It describes one very large network. A few thousand members need a simpler design.

The useful reading is architectural. Sourcing, scoring, filtering and mixing are separate steps, each with its own owner, log and switch, and that separation lets a team change one stage without breaking the others.

Choose your first tab, then plan the launch

Write the ranking rule in three sentences, decide which tab opens first, and decide in advance whether anything paid can touch reach. Then put the timeline choice in sequence with moderation and seeding using our microblogging launch checklist. To see a working base, open the demo from the Twitter clone page, compare the package on pricing, and contact us with the feed rules you want; we will separate the standard setup from the tailored work.

Questions and answers

How do I design a social media timeline algorithm for a small network?

Start with a Following tab in time order. Add a second tab scored by recency, a boost for accounts the member interacts with and a boost for replies. Run hard filters such as blocks and mutes before scoring, then apply an author cap. Log the reason each post was shown so you can explain reach to creators.

Is the Twitter algorithm public?

Partly. X published source code for its recommendation system on GitHub, including the Home Mixer service that builds timelines. The README says the heavy ranking model lives in a separate repository, and the code does not include live training data or every production setting. You can learn the structure from it, not the exact weights in use today.

Should I offer both ranked and chronological timelines?

Usually yes. A chronological tab is predictable and easy to explain, while a ranked tab helps new accounts reach strangers. Until you have a few hundred active members, lead with chronological, because ranking on a tiny graph feels random. Let each member choose which tab opens first and store the preference.

Can paying members get more reach?

That is a policy decision. X documents reply prioritization for Premium subscribers, which is not the same as a universal main-feed boost. You can offer no reach benefit, a small disclosed benefit on specific surfaces, or a labeled ad product. Avoid a hidden boost, because members tend to notice and lose trust.

Why run blocks and mutes before ranking?

If the scorer never sees blocked or muted authors, a bug in a later filter cannot expose their posts. Filtering after ranking can also leave holes in the page. Treat hard rules as safety controls that run first and are covered by tests, and use soft rules such as author caps and de-duplication after scoring.

What does your Twitter clone give me for the timeline?

It ships three named timelines, namely For You, Following and Bookmarks, that the operator can tune, with each member choosing which opens first. Each member's follows, lists, blocks and mutes are stored as explicit records. Beside it sit a report queue offering five resolution actions, plus an audit log. The ready-made platform is sold at a one-time $3,699.

Sources

  1. GitHub: twitter/the-algorithm (README)
  2. GitHub: the-algorithm, Home Mixer overview
  3. X Help Center: About X Premium
  4. Mastodon: joinmastodon.org
  5. Bluesky: about
  6. X Help: For You and Following timelines

Checked in October 2026. Rules, fees and programme terms change; confirm on the source before you rely on them.

Twitter guides All articles

Up next / Social networks and communities / 14 min How to Start a Microblogging Platform: A Launch Checklist

→Start here

Tell us about the microblogging platform you want to launch.

Share the platform and your market. You get a walkthrough of the live demo, the exact scope of what ships, and a fixed price in writing. First response in under 2 hours, Monday to Saturday, 10:00 to 19:00 IST.

We reply to every inquiry. No newsletters, no shared data. See our privacy policy.