How the Twitter Algorithm Works: Timeline Ranking Explained

The Twitter algorithm, now run by X, is not one formula. It is a pipeline that gathers candidate posts, scores them, filters them and then mixes in ads and follow suggestions. The For You tab shows the ranked result. The Following tab shows the accounts you chose, newest first.

This post walks through the stages X documents in its open-sourced code, labels everything that is general recommender practice rather than documented fact, and ends with a way to design a timeline for a smaller network. If you plan to run one, our white-label Twitter clone ships three named timelines so you have a ranking to tune from day one.

What a timeline actually is

A timeline is a ranked list built on demand. Nobody stores a ready-made feed per person 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 people 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 is best for this person right now. You can change the second without touching the first. That is why X can offer more than one tab over the same posts.

X's Home Mixer documentation says the service builds three views: For You, which is personalized recommendations; Following, which is reverse chronological; and Lists, which is chronological posts from list members. Only one of the three is ranked by a learned model. The other two are simple queries sorted by time.

The pipeline X documents

The repository README and the Home Mixer overview describe the same shape. We summarize them here in our own words, and you should read the sources if you need the exact wording.

Two details are worth remembering. First, the README states that about half of the For You timeline comes from in-network posts, meaning accounts the member follows, with the rest from out-of-network sources. Second, it says the heavy-ranker model sits in a separate repository, so the code here shows how the pieces connect more than it shows the final scoring weights.

Candidate sourcing: where posts come from

The README names several sources. A search index service called Earlybird retrieves and ranks in-network posts. A graph service named User-Tweet-Entity-Graph keeps an in-memory graph of interactions and finds candidates by walking it. A follow-recommendation service suggests accounts and their posts. A coordinating service gathers out-of-network candidates.

Underneath sit models that describe people and posts. The README lists SimClusters for community detection, TwHIN for embeddings of the social graph, Real-Graph for predicting interactions between two accounts, and Tweepcred for account reputation. Treat these as names for four ideas that any network can reproduce at smaller scale:

• Communities: groups of accounts that tend to follow and engage with the same people.
• Embeddings: numeric summaries of accounts and posts so that similar ones sit close together.
• Relationship strength: how likely one account is to interact with another.
• Reputation: a score that makes an account's output count for more or less.

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 new post reach people who do not follow the author. They are also where the risk sits. A bad recommendation looks like the platform endorsing the post.

On a small network the split matters more than the models. If you have 500 members, a graph service has almost nothing to walk. Your out-of-network source might be a plain list of trending hashtags or the most-replied posts of the day. That is a legitimate candidate source, and it is easy to explain to members.

Signals commonly used to rank

The code summary says the system uses explicit signals such as likes and implicit ones such as profile visits, gathered by a user-signal service. It does not list every signal and weight in the pages we read. The table below is therefore general recommender practice, not a description of X's current scoring. Use it to decide what your own system should record.

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, "not interested" and reports tell you what the member did not want, and they should reduce the score of similar content for that person.

Filters and safety passes

The Home Mixer overview lists the filtering stage as a separate step after scoring: author diversity, content balance, fatigue, de-duplication and visibility rules based on user settings. A separate set of visibility filters enforces policy and quality, and the README lists trust-and-safety models alongside the ranking models.

Order matters, and this is where many homemade feeds fail. Consider two designs.

1. Filter, then rank. Blocked and muted authors are removed from the candidate pool. The scorer never sees them. This is cheap and safe.
2. Rank, then filter. The scorer sees everything and the filter removes items afterward. This can leave a page with holes, and it means 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.

A worked example

Say a ranker returns 20 posts for a member and 9 are from one prolific account. With no diversity rule the member sees nine posts from one voice, then eleven from everyone else. With a cap of three per author per page, the extra six drop to later pages, and the member sees seventeen posts from at least six accounts. Nothing was deleted. The rule only spreads the page out. This is an invented example, but it shows why diversity filters exist and why creators sometimes see a post from a busy account appear later than expected.

Chronological versus ranked: the trade-off

Neither mode is better. They answer different questions.

This is why X, and most networks with both, keep a ranked tab and a chronological tab. Mastodon's own site goes the other way and promises chronological feeds with no ranking algorithm or ads. Bluesky's about page describes several feed choices rather than one forced timeline. We compare those models in Mastodon vs Bluesky vs a private network. For the video-first version of the same idea, see how the TikTok algorithm works.

What the open code does not tell you

Reading a recommender repository gives you structure, not outcomes. Four limits are worth stating plainly so you do not repeat folklore.

• It is not live. A published snapshot cannot show the weights, thresholds or experiments running today. The README itself says development is ongoing.
• It leaves out the heavy model. The README places the heavy ranker in a separate repository, and the signals description in the main one is brief.
• It does not explain behavior. Knowing that a fatigue filter exists does not tell you how many repeats it allows. Any post that claims to know the exact reach penalty for a link, a hashtag or a time of day is guessing.
• It describes one network. X has hundreds of millions of posts to sort through. A network with a few thousand members needs a different design, mostly simpler.

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

A simple scoring example

To see how a small network could rank without a learned model, take an invented formula. Say each candidate gets a score of 10 points for being from an account the member follows, plus 6 for an account they replied to in the last week, plus 4 for every reply the post has received in its first hour, capped at 12, minus 2 points per hour of age. Two posts compete for one slot.

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

Post A wins, but only narrowly. If Post B collects two more replies, it hits the cap and the gap closes, which is the intended behavior: a lively new post can beat a quieter familiar one. If Post B comes from a muted account, the hard filter removes it before scoring and the question never arises. The numbers are an example, 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.

Designing your own feed rules

You do not need X's machinery. You need a small set of rules you can explain and change. A practical order:

1. Start with Following. Time-ordered posts from followed accounts. This is the baseline everything else is compared against.
2. Add a simple score for the second tab. Recency, plus a boost for accounts the member interacts with, plus a boost for posts with replies. A weighted sum you can write on one line is enough.
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, and a limit on how often one post repeats across sessions.
5. Log every decision. For each shown post, store the score, the candidate source and the rule that placed it. Without this, you cannot answer a creator who asks why their post got no reach.
6. Add a "why am I seeing this" line. Even 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. Introduce a learned model later. Only when you have enough posts and reactions that your simple rule is clearly leaving value behind.

Ranking checklist before launch

• You can describe your ranking rule in three sentences a member would understand.
• Hard filters run before scoring and are covered by a test.
• Every shown post has a stored reason.
• There is a chronological option, and the member can pick it first.
• Paid status does not change reach unless your terms say so.
• You know who can change the ranking weights and how a change is recorded.

Does paying change reach?

X's Premium page lists benefits such as a checkmark after review, reduced ads and creator program access. We do not claim that any of them changes the main timeline score, because the pages we read do not say so. Our guide to X verification and paid tiers covers how that ladder is built.

For your own network, treat this as a policy decision, not a technical one. Three honest options exist: no reach benefit for paying, a small and disclosed benefit for specific surfaces such as replies, or an ad product where reach is sold and labelled. The only dishonest option is a hidden boost. Members notice, and they read it as a betrayal.

How our build handles it

Our Twitter clone has three named timelines: For You, Following and Bookmarks. Following is a chronological feed of the accounts a member follows. For You is a ranked mix that can include accounts they do not follow, and the operator can tune it. 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 counters for likes, reposts and views sit on the post itself so drawing a page does not recalculate them.

We do not publish the ranking signals here and we do not claim the build copies X's pipeline. It is original software with something for you to tune. The Twitter clone features page lists everything around the timeline, including the report queue and audit log that a feed needs next to it.

Glossary

• Candidate: a post that might be shown, before it has been scored.
• In-network: a post from an account the member follows.
• Out-of-network: a post from an account the member does not follow.
• Light ranker: a cheap model that prunes the candidate list.
• Heavy ranker: a larger model that scores the shortlist.
• Hydration: fetching the data a model needs about a post, author and viewer.
• Fatigue: reducing how often the same post or author repeats.

What to decide next

If ranking is also your ad surface, the Twitter clone business model shows how timelines, tiers and ads fit together. Pick which timeline opens first, write the ranking rule in three sentences, and decide in advance whether anything paid can touch reach. Then plan the launch around it: our microblogging launch checklist puts the timeline choice in sequence with moderation and seeding. If you want a working base to tune instead of building feeds from zero, look at the ready-made Twitter clone and the delivery process.