How to Migrate Mastodon Lists With the API

Moving a Mastodon account between instances often preserves followers but leaves your carefully organized lists behind. Mastodon lists let you group accounts by topic or workflow, and rebuilding them manually can take hours. This article explains how to export list data from your old account and import it into a new one using the Mastodon REST API. You will learn the exact API endpoints, authentication steps, and data formatting needed to complete the migration.

Why Mastodon Lists Do Not Transfer During Account Migration

Mastodon’s built-in account migration feature handles followers, follow requests, muted accounts, and blocked accounts. Lists are not included in this transfer because lists are local to each instance and reference account IDs that change when you move to a new server. Each Mastodon instance assigns a unique numeric ID to every account. After migration, your new account on the destination instance has a different ID. The old list data contains the old IDs, which are meaningless on the new instance.

To migrate lists, you must extract the list structure and member account IDs from the source instance, then recreate each list on the destination instance and map the old account IDs to their new equivalents. The Mastodon API provides endpoints for all of these operations. You can perform these steps manually using a tool like cURL or automate the process with a script.

Prerequisites for API-Based List Migration

Before starting, you need the following:

• Access to the old Mastodon instance where your lists currently exist
• An active Mastodon account on the destination instance
• API access tokens for both the source and destination accounts
• A tool to make HTTP requests such as cURL, Postman, or a custom script in Python or JavaScript
• Knowledge of the account IDs for each member you want to add to the new lists

Steps to Export Lists From the Source Instance

The first phase involves collecting all list metadata and member account IDs from your old Mastodon account. You need a valid access token for the source account with the read:lists scope.

1. Generate an access token on the source instance
   Go to Preferences > Development > New Application. Give the application a name such as “List Migration Tool.” Enable the read:lists and read:accounts scopes. Save the application and copy the access token string.
2. Retrieve all lists from the source account
   Send a GET request to https://source-instance.example/api/v1/lists with the header Authorization: Bearer YOUR_TOKEN. The response is a JSON array. Each object contains id and title fields. Record the list IDs and titles.
3. Fetch member account IDs for each list
   For each list ID from step 2, send a GET request to https://source-instance.example/api/v1/lists/LIST_ID/accounts. The response contains an array of account objects. Record the id field for each account. Save this data in a structured format such as JSON. Example output: {"list_title": "Work Colleagues", "member_ids": [12345, 67890, 11121]}.

Steps to Import Lists on the Destination Instance

After exporting the list data, switch to the destination instance. You need a new access token with write:lists and write:accounts scopes. Also, you must resolve the old account IDs to their new account IDs on the destination instance. The simplest method is to search for each account by username and domain using the Mastodon API search endpoint.

1. Generate an access token on the destination instance
   Navigate to Preferences > Development > New Application on the destination instance. Name the application and enable the write:lists, write:accounts, and read:accounts scopes. Copy the access token.
2. Resolve old account IDs to new account IDs
   For each member ID from your exported data, send a GET request to https://destination-instance.example/api/v2/search?q=@username@source-instance.example&type=accounts&limit=1. The q parameter should contain the full account handle including the source instance domain. The response includes an accounts array. Use the id field from the returned account object. Store this mapping for later use.
3. Create each list on the destination instance
   For each list title from your exported data, send a POST request to https://destination-instance.example/api/v1/lists with a JSON body: {"title": "Work Colleagues"}. The header must include Content-Type: application/json and Authorization: Bearer YOUR_TOKEN. The response contains the new list object including its id.
4. Add accounts to each new list
   For each new list created in step 3, send a POST request to https://destination-instance.example/api/v1/lists/LIST_ID/accounts with a JSON body: {"account_ids": ["NEW_ID_1", "NEW_ID_2"]}. The account_ids array must contain the resolved account IDs from step 2. Repeat for every list.

Common Issues and API Limitations

Account Search Returns No Results

The Mastodon search endpoint may not return accounts that are not federated to the destination instance. Ensure the account you are searching for has at least one follower or post that has reached the destination instance. Alternatively, use the destination instance’s web interface to manually locate the account and copy its numeric ID from the URL.

List Creation Fails With a 422 Error

This usually means the list title is too long or contains invalid characters. Mastodon list titles have a maximum length of 100 characters. Strip any special characters or truncate the title.

Rate Limiting Causing Request Failures

Mastodon instances enforce rate limits on API endpoints. If you have a large number of lists and members, you may hit the rate limit. Pause between requests or use exponential backoff. Check the X-RateLimit-Remaining header in the response to monitor your remaining requests.

Mastodon API Endpoints for List Migration

Operation	HTTP Method	Endpoint
List all lists	GET	/api/v1/lists
Get list members	GET	/api/v1/lists/:id/accounts
Search for an account	GET	/api/v2/search
Create a new list	POST	/api/v1/lists
Add accounts to a list	POST	/api/v1/lists/:id/accounts

You now have a complete method to migrate Mastodon lists between instances using the API. The process requires two access tokens, a search step to resolve account IDs, and sequential creation of lists and members. For large lists with hundreds of members, consider writing a script in Python or JavaScript that loops through the exported data and handles rate limiting automatically. After migration, verify your lists by opening the Lists section on the destination instance and confirming each list contains the expected accounts.