Export your own followers from Mastodon using the API

With decentralization and federation in mind, Mastodon allows exporting a list of all the accounts you follow directly from within the GUI.

This function generates a CSV file you can later import to another server. This function is especially helpful if you want to create a backup of your data or if you don’t want to do a full migration (and lose your first account), but open up a second account instead.

Unfortunately, Mastodon doesn’t provide an option to export a list of your own followers. Well, at least not from within the GUI. But hey, we have an API to play with!

I came up with the idea when I started my soft migration to a secondary account. In order to grow my network, I decided that I want to follow back as many accounts as possible.

Importing the accounts I follow was no problem at all since the Mastodon web interface provides an option to export your own follows. The generated CSV file can be imported on a second account, bringing back all your follows in the blink of an eye!

But what about your followers? As you might notice, the CSV option is missing in the web interface. Well, usually you don’t need to export your followers. While you can control which accounts you want to follow, your followers are an entirely different story.

Regardless of account migrations or recovery after data loss, you can’t bring back your followers unless they decide to follow your account again. This might be the reason why a GUI option to export your followers is missing - most people will never use it.

However, the necessary data is accessible using the Mastodon API. All we need is bash, curl, jq, and sed.

The Mastodon API provides an endpoint called /api/v1/accounts/$userid/followers that returns the followers of any account. Fortunately, we don’t have to deal with authentication since the endpoint is entirely public.

But there’s a catch: Calling the API only returns 40 to 80 results, depending on the configuration of the instance and the query options. While this looks like an artificial limitation at first glance, it prevents the API to return too large replies - just assume your account has 10.000 followers.

To fetch all accounts, we have to iterate over multiple virtual pages of the API result until we run out of pages to query. After the last page is fetched and we get no reference to a “next” page, we know that the operation is finished.

The script itself is pretty straightforward:

#!/bin/bash
# Fetch own followers via the Mastodon API
# Tested up to Mastodon v4.2.8

# Enter your user details
username="yourMastodonUsername"
instance="https://example.com"

# Preparations
echo "Get account ID from the given username..."
userid="$(curl --silent "${instance}/api/v1/accounts/lookup?acct=${username}" | jq -r .id)"

echo "Found account ID: $userid"
initial_url="${instance}/api/v1/accounts/${userid}/followers"

# Fetch initial JSON output
echo "Checking URL ${initial_url}..."
json_output=$(curl --silent "${initial_url}")
nextstep=$(curl --head --silent "${initial_url}" | grep -i "next" | cut -d ";" -f1 | sed -n 's/.*<\(.*\)>.*/\1/p')

# Main loop: Fetch all remaining accounts
while [ "${nextstep}" ]; do
  echo "Checking URL ${nextstep}..."
  json_output+=$(curl --silent "${nextstep}")
  nextstep=$(curl --head --silent "${nextstep}"  | grep -i "next" | cut -d ";" -f1 | sed -n 's/.*<\(.*\)>.*/\1/p')
done

# Save output to CSV file
echo "Writing CSV file..."
timestamp=$(date +%s)
echo "Account address,Show boosts,Notify on new posts"       >  ${username}_follower_accounts_${timestamp}.csv

echo "${json_output}" | jq -r '.[].acct | .+ ",true,false,"' >> ${username}_follower_accounts_${timestamp}.csv
echo "done!"

First, we have to get our account ID. We can easily perform a lookup using the /api/v1/accounts/lookup?acct= endpoint. Next, we grab the first batch of JSON by querying /api/v1/accounts/$userid/followers. This will not only return the first round of accounts but also provide the “next” URL in the HTTP response. Now, we simply extract the next URL, get the JSON reply from the API and check if we have a new “next” URL. We repeat this process until there is no “next” URL present in the HTTP response which indicates that we are on the very last page.

Finally, we have the entire API response in the json_output variable.

The last step consists of writing a proper CSV header and querying the JSON output we got earlier using jq. Finally, we write the prepared output into the CSV file.

The CSV we created has the same format as the following_accounts.csv created by the web interface when using the export of your follows. Thus, we can use this CSV and import it to the “Following list” using the web interface and follow all of our followers at once!

Do you have any comments or suggestions regarding this article? Please drop an e-mail to feedback@fabulous.systems!