Mastodon Export Archive Missing Bookmarks: Fix

You have downloaded your Mastodon data export archive but the bookmarks file is not included inside the zip. This happens because the standard export tool in Mastodon only includes a limited set of data types by default. Bookmarks are stored separately in the database and are not part of the basic archive package. This article explains why bookmarks are excluded and shows you how to retrieve them using the Mastodon API.

Why Bookmarks Are Missing from the Standard Export Archive

Mastodon’s export feature, located under Preferences > Import and export > Export data, creates a zip file containing CSV files for follows, followers, blocks, mutes, domain blocks, and lists. The archive also includes an outbox.json file with your public posts. Bookmarks are intentionally excluded from this default export for two reasons.

First, bookmarks are considered a private activity. Unlike public posts or follows, bookmarks are not shared with other users or instances. Including them in the export would create a privacy risk if the archive file is shared or stored in an insecure location. Second, the export system was designed before bookmarks became a core feature. The internal data pipeline for the export tool has not been updated to include the bookmarks table.

The same limitation applies to lists. While lists are included as a CSV file, the actual membership of each list is not exported. Bookmarks and list memberships require separate retrieval methods. The Mastodon API provides the only reliable way to extract bookmark data.

Steps to Export Bookmarks Using the Mastodon API

To retrieve your bookmarks, you must use the Mastodon API with an OAuth token that has the read:bookmarks scope. The following steps assume you are using a desktop browser and have access to your instance settings.

1. Generate an OAuth access token with read:bookmarks scope
   Open your Mastodon instance in a browser. Go to Preferences > Development. Click the New Application button. Enter a name for the application, such as “Bookmark Exporter.” Under Scopes, expand the read section and check only read:bookmarks. Do not select any write scopes. Click Submit. On the next page, copy the text next to Your access token. Store this token securely. You will use it in the next step.
2. Open the browser developer console
   In the same browser tab, open the developer tools. Press F12 on Windows or Cmd+Option+I on Mac. Click the Console tab. You will paste code here in the next step.
3. Run the API request to fetch bookmarks
   Type or paste the following JavaScript code into the console. Replace YOUR_ACCESS_TOKEN with the token you copied in step 1. Press Enter.

   fetch('https://YOUR_INSTANCE_URL/api/v1/bookmarks?limit=80', {
headers: { 'Authorization': 'Bearer YOUR_ACCESS_TOKEN' }
})
.then(response => response.json())
.then(data => console.log(JSON.stringify(data, null, 2)));
   Replace YOUR_INSTANCE_URL with your full Mastodon instance domain, for example mastodon.social.

4. Review the JSON output in the console
   The console displays a JSON array of your bookmarked toots. Each entry includes the toot ID, content, account details, media attachments, and timestamps. If you have more than 80 bookmarks, the response includes a Link header for pagination. To fetch the next page, copy the next URL from the Link header and repeat step 3 with that URL instead of the base endpoint.
5. Save the bookmark data to a file
   Right-click the JSON output in the console. Select Copy Object or Copy String. Open a text editor such as Notepad or Visual Studio Code. Paste the data. Save the file as bookmarks.json. This file contains all your bookmarks in a machine-readable format.

Common Issues When Retrieving Bookmarks

API returns 401 Unauthorized error

This error means the access token is missing, expired, or does not have the read:bookmarks scope. Go back to Preferences > Development and edit the application you created. Verify that read:bookmarks is checked under Scopes. Generate a new token if necessary. Copy the token again and replace the old one in your API request.

API returns empty array even though I have bookmarks

The API endpoint returns only bookmarks that belong to the user associated with the access token. Confirm that you are logged into the same account you used to create the application. If you are logged into a different account, the token will not have access to that account’s bookmarks. Log out and log in with the correct account before generating the token.

Console shows CORS error

A CORS error occurs when the browser blocks the API request due to cross-origin policy. This can happen if you are running the fetch code from a different domain than your Mastodon instance. Open the developer console on a page that is hosted on your Mastodon instance, such as your profile page or the preferences page. Do not run the code from a blank tab or a different website.

More than 80 bookmarks not returned

The default limit for the bookmarks endpoint is 20 items per page, but you can increase it up to 80. The example code uses limit=80 to fetch the maximum per page. If you have more than 80 bookmarks, you must handle pagination. Parse the Link header from the response to get the next page URL. Repeat the fetch request with that URL until no next link exists.

Mastodon Export Archive vs API Bookmark Retrieval

Item	Standard Export Archive	API Bookmark Retrieval
Data format	CSV and JSON files in a zip archive	JSON array returned from API endpoint
Bookmarks included	No	Yes, all bookmarks with full metadata
Requires OAuth token	No	Yes, with read:bookmarks scope
Privacy level	May contain public and private data	Only private bookmark data is returned
Pagination support	Not applicable	Yes, via HTTP Link header
Automation possible	Manual download only	Yes, with scripts or third-party tools

The standard export archive is suitable for migrating follows and blocks between instances. The API method is required for preserving bookmark data. Both methods complement each other for a complete data backup.

You can now retrieve your missing bookmarks using the Mastodon API and the OAuth token with read:bookmarks scope. Next, consider automating the export process with a scheduled script that calls the API periodically. For advanced users, the same API endpoint can be integrated into a dashboard or backup tool that stores bookmarks in a local database.