How to Export Mastodon Lists With API Beyond Default Settings

Mastodon lists let you organize followed accounts into topic-based feeds. The default web interface lists export only list names and member IDs, without metadata like creation dates, list descriptions, or member account details. This limitation makes it hard to archive or migrate lists with full context. This article explains how to use the Mastodon REST API to export lists with additional data beyond what the default settings provide.

Understanding Mastodon List API Endpoints and Default Limitations

The Mastodon API provides two primary endpoints for list data. The GET /api/v1/lists endpoint returns a JSON array of list objects. Each object contains the list id, title, and replies_policy. The GET /api/v1/lists/:id/accounts endpoint returns the accounts that belong to a specific list. Each account object includes id, username, acct, display_name, url, avatar, and other profile fields.

The default export feature in the Mastodon web interface only outputs a CSV file with list names and member account IDs. It does not include list replies_policy, member display names, or member URLs. This limited export loses context that is useful when migrating between instances or auditing list composition.

API Response Fields Available Beyond Default Export

When you call the list accounts endpoint, each account object contains these fields that the default export omits:

• display_name: The user-set display name of the account.
• acct: The full account handle including the instance domain.
• url: The direct link to the account profile on the instance.
• avatar: The URL to the account avatar image.
• note: The account bio or description text.
• created_at: The timestamp when the account was created on Mastodon.

The list object itself includes the replies_policy field, which controls whether replies to list members appear in the list feed. This field is not exported by the default CSV export.

Prerequisites for API-Based List Export

Before you can export lists via the API, you need three things:

1. Create a Mastodon application token
   Go to Preferences > Development > New Application. Set the application name. Under Scopes, check the box for read:lists. You can also check read:accounts if you want full account details. Click Submit. Copy the token string from the Your access token field.
2. Choose an API client tool
   You can use any HTTP client that supports Bearer token authentication. Common tools include curl (command line), Postman (GUI), or a custom script in Python using the requests library. This guide uses curl commands for clarity.
3. Know your Mastodon instance base URL
   The base URL is the address of your Mastodon server, for example https://mastodon.social or https://yourinstance.com. All API requests start with this URL followed by /api/v1/.

Steps to Export All Lists With Full Member Details

The following steps retrieve every list on your account and export each list with all available member account fields into a structured JSON file.

1. Get the list of all lists
   Run this curl command, replacing YOUR_TOKEN with your access token and YOUR_INSTANCE with your instance URL:
   curl -H "Authorization: Bearer YOUR_TOKEN" https://YOUR_INSTANCE/api/v1/lists
   The response is a JSON array. Each object has an id field. Note the id of each list you want to export.
2. Export members of a single list
   For each list id, run this command, replacing LIST_ID with the actual id:
   curl -H "Authorization: Bearer YOUR_TOKEN" https://YOUR_INSTANCE/api/v1/lists/LIST_ID/accounts
   The response is a JSON array of account objects with all available fields.
3. Save the output to a file
   Append > list_ID.json to each curl command to save the output. For example:
   curl -H "Authorization: Bearer YOUR_TOKEN" https://YOUR_INSTANCE/api/v1/lists/12345/accounts > list_12345.json
4. Combine all list exports into one file
   Use a script to iterate over all list ids and merge the results. The following Python script does this in one pass:

   import requests
   import json
   
   base_url = "https://YOUR_INSTANCE"
   token = "YOUR_TOKEN"
   headers = {"Authorization": f"Bearer {token}"}
   
   # Get all lists
   response = requests.get(f"{base_url}/api/v1/lists", headers=headers)
   lists = response.json()
   
   all_data = []
   for lst in lists:
       list_id = lst["id"]
       resp = requests.get(f"{base_url}/api/v1/lists/{list_id}/accounts", headers=headers)
       accounts = resp.json()
       all_data.append({
           "list_id": list_id,
           "list_title": lst["title"],
           "replies_policy": lst.get("replies_policy"),
           "members": accounts
       })
   
   with open("all_lists_export.json", "w") as f:
       json.dump(all_data, f, indent=2)
   

5. Verify the exported file
   Open all_lists_export.json in a text editor or JSON viewer. Each list entry includes the list title, replies_policy, and an array of member account objects with full profile data including display_name, acct, url, and created_at.

Common Export Issues and How to Handle Them

API returns a 401 Unauthorized error

This error means your token is missing or invalid. Verify that you copied the token exactly, including no extra spaces. Ensure the token has the read:lists scope. If you created the token before adding the scope, delete it and create a new one.

API returns a 404 Not Found for a list id

This error occurs when the list id does not exist on your account, or the list belongs to a different user. Only list ids returned by the /api/v1/lists endpoint are valid for your account. Do not guess or reuse list ids from another instance.

Export file is empty or contains an empty array

An empty array [] for a list means the list has no members. This is normal for newly created lists. If you expected members, check that you added accounts to the list through the Mastodon web interface before exporting.

Rate limiting causes incomplete exports

Mastodon instances enforce rate limits on API calls. If you have many lists, the script may hit the rate limit and return HTTP 429 errors. To avoid this, add a delay between requests. In the Python script, insert time.sleep(1) inside the loop after each accounts request.

Default Export vs API Export: Feature Comparison

Item	Default CSV Export	API JSON Export
List title	Yes	Yes
List replies_policy	No	Yes
Member account ID	Yes	Yes
Member display_name	No	Yes
Member acct handle	No	Yes
Member profile URL	No	Yes
Member avatar URL	No	Yes
Member created_at	No	Yes
Export format	CSV	JSON
Authentication required	Web session	OAuth Bearer token

You can now export Mastodon lists with full metadata using the API. The JSON output preserves list policies and complete account profiles. Next, try using the replies_policy field to filter list feeds more precisely. For advanced automation, schedule the Python script with a cron job to keep your exports current.