How to Backfill Federation History for a Newly Followed Mastodon Account

When you follow a new account on Mastodon, the server does not automatically fetch that account’s past posts. This means your federated timeline may show only new posts from that account, leaving a gap in your feed. The missing older content is not a bug but a design choice to reduce server load and storage usage. This article explains how to manually request a backfill of federation history for a newly followed Mastodon account so you can see their past public posts.

Why Mastodon Does Not Automatically Backfill Federation History

Mastodon is designed to be a lightweight, federated social network. Unlike centralized platforms that store every post from every user, Mastodon instances only store posts that arrive through the federated timeline or are explicitly fetched. When you follow a new account, the instance receives only the most recent post or a small batch of recent posts. This is called the “follow handshake.” The handshake transfers the latest status ID but not the full history.

The technical reason is that older posts may not be stored on the followed account’s home instance. Mastodon uses a distributed storage model where each instance holds only its own users’ posts. If the followed account’s instance has already pruned old posts due to storage limits, those posts are permanently unavailable. Backfill requests ask the remote instance to send any available older posts that it still holds.

Backfill is not enabled by default because it increases outbound traffic and processing load on both instances. A single backfill request can transfer hundreds of posts, which can slow down the server. For this reason, Mastodon provides three ways to backfill: a manual user interface toggle, an API endpoint for developers, and a server-level admin command.

Steps to Backfill Federation History for a Newly Followed Account

The exact steps depend on whether you are a regular user, a developer integrating with the API, or a server administrator. All methods require that the account was followed at least once before the backfill request is sent. If you follow an account and immediately request backfill, the server may not have completed the initial handshake yet.

Method 1: Using the Mastodon Web Interface

This method works on Mastodon version 4.0.0 and later. The backfill toggle is available directly on the account’s profile page.

1. Navigate to the followed account’s profile
   Open the Mastodon web interface in your browser. Go to the profile page of the account you want to backfill. You must already be following this account.
2. Open the account menu
   Click the three-dot menu button located near the follow/unfollow button on the profile. On mobile, this button is usually at the top right of the profile header.
3. Select the Backfill option
   From the dropdown menu, choose the option labeled “Backfill” or “Request older posts.” The exact wording may vary by Mastodon version. A confirmation dialog appears.
4. Confirm the request
   Click “Confirm” or “Request” in the dialog. The server sends a backfill request to the remote instance. Depending on the number of posts, the process may take several minutes to complete.

After the request is processed, the older posts appear in your home timeline and the account’s profile page on your instance. You do not need to refresh the page manually. The posts load as they are received.

Method 2: Using the Mastodon API

Developers and advanced users can trigger backfill via the Mastodon REST API. This method requires an access token with the read:accounts and write:accounts scopes.

1. Obtain the account ID
   Use the GET /api/v1/accounts/lookup endpoint with the account’s username and domain to retrieve the numeric account ID. For example: GET https://mastodon.example/api/v1/accounts/lookup?acct=user@remote.social
2. Send the backfill POST request
   Send a POST request to POST /api/v1/accounts/:id/backfill where :id is the numeric account ID from step 1. Include the authorization header with your bearer token. The server responds with HTTP 202 Accepted if the request is queued.
3. Monitor the backfill status
   Mastodon does not provide a dedicated endpoint to check backfill progress. You can verify completion by checking the account’s profile page on your instance. Older posts appear automatically once the backfill finishes.

The API method is useful for automating backfill for multiple accounts or integrating with third-party tools. The rate limit for backfill requests is typically one request per account per hour.

Method 3: Server Admin Backfill Command

Instance administrators can backfill posts for any account on their server using the tootctl command-line tool. This method does not require the user to manually request backfill.

1. Open the server’s terminal
   Log in to your Mastodon server via SSH. Navigate to the Mastodon installation directory, usually /home/mastodon/live.
2. Run the backfill command
   Execute: RAILS_ENV=production bin/tootctl accounts backfill [username]. Replace [username] with the full username including the domain, such as user@remote.social. The command queues a backfill job for that account.
3. Verify the job status
   Use RAILS_ENV=production bin/tootctl sidekiq queues to check the Sidekiq queue for backfill jobs. The job is processed asynchronously. The time required depends on the number of posts and the remote server’s response speed.

Admins can also enable automatic backfill for all new follows by setting the environment variable BACKFILL_ENABLED=true in the .env.production file. This setting triggers backfill for every new follow automatically, but it increases server load significantly.

Common Issues When Backfilling Federation History

Backfill Option Not Visible in the Web Interface

If you do not see the backfill option in the account menu, your Mastodon instance may be running a version older than 4.0.0. Check your instance version by visiting /about/more on your instance. If the version is older, use the API method or ask your admin to upgrade. Also verify that you are following the account. The backfill option appears only for accounts you already follow.

Backfill Request Fails or Returns an Error

A backfill request can fail if the remote instance is offline, rate-limited, or blocks the request. Mastodon returns HTTP 422 or 429 in such cases. Wait at least one hour before retrying. If the remote instance is blocking your instance entirely, backfill is not possible. The only workaround is to view the account’s posts directly on the remote instance.

Old Posts Still Not Appearing After Backfill

The remote instance may have already deleted old posts due to its own data retention policy. Mastodon instances typically keep posts for a limited time, often 30 days. If the posts were deleted before the backfill request, they are permanently lost. Additionally, the backfill process fetches only public posts. Followers-only or direct posts are not backfilled.

Item	Web Interface Method	API Method
Required Access	Regular user following the account	API token with read/write accounts scope
Mastodon Version	4.0.0 or later	Any version with API support
Rate Limit	One request per account per hour	One request per account per hour
Success Confirmation	Posts appear in timeline automatically	HTTP 202, then posts appear automatically

Backfill federation history fills gaps in your timeline when you follow a new Mastodon account. Use the web interface method for one-off requests. Use the API method for automation. Use the admin command for server-wide control. If backfill fails, check the remote instance’s availability and data retention policy. The backfill feature is available in Mastodon 4.0.0 and later. For earlier versions, the only option is to view the account’s posts directly on its home instance.