Mastodon Filter Export and Import: Walkthrough

You have spent time building a set of Mastodon filters to hide unwanted posts, keywords, and hashtags. When you move to a new Mastodon account or instance, you must rebuild those filters manually. Mastodon does not include a built-in export or import tool for filters in its standard web interface. This article explains how to export your filters using the Mastodon API and import them into another account using browser-based tools.

How Mastodon Filters Work and Why Exporting Is Not Built In

Mastodon filters let you hide or warn about posts that contain specific words, phrases, or hashtags. You can apply filters to the home timeline, notifications, or public timelines. Each filter has a title, a set of keywords, an expiration date, and a context list. Filters are stored per account in the Mastodon database. The official Mastodon web interface does not provide an Export or Import button for filters because the feature is considered low priority by the development team. The API does expose the filter data, which means you can use technical workarounds to transfer filters between accounts.

Before you start, you need a Mastodon account on the source instance where your filters exist and a second account on the destination instance where you want the filters to appear. The export and import process uses the Mastodon REST API. You do not need programming experience, but you must be comfortable using browser developer tools and copying JSON text. The steps below work on both Windows 10 and Windows 11 with any modern browser such as Chrome, Edge, or Firefox.

Steps to Export Filters from Your Source Mastodon Account

1. Log into the source Mastodon account
   Open your browser and sign in to the Mastodon instance where your filters are saved. Go to Preferences > Filters to confirm your filters exist.
2. Open the Browser Developer Tools
   Press Ctrl+Shift+I on Windows 10 or Windows 11 to open Developer Tools. Click the Network tab. Make sure the recording button is red, indicating it is capturing network requests.
3. Send a request to the filters API endpoint
   In the browser address bar, type the following URL and press Enter: https://[your-instance-domain]/api/v1/filters. Replace [your-instance-domain] with your Mastodon instance domain, for example mastodon.social. This URL sends a GET request to retrieve all your filters as JSON.
4. Locate the API response in the Network tab
   In the Network tab, look for a row named filters with the method GET and status 200. Click that row. Then click the Response tab. You will see a JSON array containing your filters. Each filter object includes fields such as id, title, context, filter_action, keywords, and expires_at.
5. Copy the JSON response to a file
   Select all the JSON text in the Response tab. Press Ctrl+A then Ctrl+C to copy. Open a plain text editor such as Notepad on Windows. Press Ctrl+V to paste the JSON. Save the file as mastodon-filters-export.json on your desktop. Keep this file safe because it contains the data you need for import.

Steps to Import Filters into Your Destination Mastodon Account

1. Log into the destination Mastodon account
   Sign in to the Mastodon instance where you want to add the filters. This can be the same instance with a different account or a completely different instance.
2. Open Developer Tools and the Network tab again
   Press Ctrl+Shift+I and click the Network tab. Keep it open.
3. Create a new filter manually to capture the API request format
   Go to Preferences > Filters. Click the Add new filter button. Fill in a temporary title such as test and add one keyword such as testkeyword. Do not click Save yet.
4. Intercept the POST request to the filters API
   In the Network tab, clear existing entries by clicking the clear button. Then click Save on the filter creation form. In the Network tab, look for a row named filters with the method POST. Click that row and then click the Headers tab. Note the request URL: https://[your-instance-domain]/api/v1/filters. Also note the Authorization header which contains your access token. This token is automatically sent by the web interface.
5. Send a POST request with your exported filter data
   Open a new browser tab. Use a tool like the Fetch API in the browser console, or use an online REST client such as Postman or Hoppscotch. For a quick method, open the browser console by pressing Ctrl+Shift+J. Paste the following JavaScript template, replacing the placeholder values with your actual data:
   fetch('https://[your-instance-domain]/api/v1/filters', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
'Content-Type': 'application/json'
},
body: JSON.stringify(YOUR_EXPORTED_FILTER_OBJECT)
});
   Replace YOUR_ACCESS_TOKEN with the token from the Headers tab you saw in step 4. Replace YOUR_EXPORTED_FILTER_OBJECT with the first filter object from your saved JSON file. Press Enter to execute. You should see a response with status 200 and the created filter object.
6. Repeat for each filter in your export file
   Open your saved JSON file. Copy each filter object one at a time and run the fetch command for each. After all filters are sent, go to Preferences > Filters in the destination account. All your filters should now appear.

Common Problems When Exporting and Importing Mastodon Filters

Filters Do Not Appear After Import

The most common cause is an incorrect access token. The token you copy from the Network tab is tied to the current browser session. If you signed out and signed in again, the token changes. Always copy the token from the same session where you are performing the import. Another cause is an invalid JSON structure. The Mastodon API expects a filter object with fields such as title, context, and keywords. If you send the entire array instead of a single object, the API returns a 422 error. Extract one object at a time from the array.

Filter Keywords Are Missing After Import

The exported JSON includes a keywords array inside each filter object. When you import, you must include the keywords array in the body of the POST request. If you omit the keywords field, the filter will be created with zero keywords and will not block anything. Verify that your exported JSON contains a keywords array with at least one entry. The keyword object has fields such as id, keyword, and whole_word. The id field is optional and can be set to null.

Filter Expiration Dates Are Incorrect

The expires_at field in the exported JSON uses ISO 8601 format with timezone offset. When you import the filter, the API accepts the same format. If the date is already in the past, the filter will be created but immediately expired. You can set expires_at to null to create a non-expiring filter. Edit the JSON before sending the POST request to remove the expires_at field or set it to null.

Item	Export Process	Import Process
API method	GET	POST
Endpoint	/api/v1/filters	/api/v1/filters
Data format	JSON array of filter objects	Single JSON filter object per request
Authentication	Browser session cookie	Bearer token from Authorization header
Tool used	Browser address bar or Network tab	Browser console fetch or REST client
Error if token missing	Redirect to login page	HTTP 401 Unauthorized

You can now transfer your Mastodon filters between accounts using the API export and import method. The process requires copying JSON data and sending POST requests from the browser console. After importing, verify each filter by checking the Filters page in your destination account preferences. For accounts with many filters, consider writing a small script that loops through the exported array and sends each filter automatically using the same fetch pattern described above.