Mastodon Export Pinned Posts: How to Handle Separately

When you export your Mastodon account data, the standard archive includes your statuses, media files, and followers list. But pinned posts — the tweets you have manually pinned to the top of your profile — are not included as a separate item in the default export. This can be confusing if you want to preserve your pinned posts when migrating to a new instance or backing up your profile structure. The Mastodon export tool does not provide a dedicated option for pinned posts because they are treated as a metadata flag attached to individual statuses. This article explains how to locate your pinned posts within the export archive and how to manually extract them for separate handling.

Why Pinned Posts Are Not Exported Separately

Mastodon does not treat pinned posts as a distinct content type. When you pin a post, the server adds a pinned flag to the post’s metadata in the database. The standard export process — accessed through Preferences > Import and Export > Export — collects all statuses, media files, followers, and other account data into a single ZIP archive. The archive contains an outbox.json file that lists every post in ActivityPub format. Each post object includes a type field. For pinned posts, the type value is Add rather than Create for regular posts. This subtle difference is the only way to identify pinned posts in the export.

The Mastodon developers chose this design because pinned posts are not a separate data entity. They are simply regular posts with an added flag. When you migrate to a new instance using the standard account migration tool, your pinned posts are not transferred automatically. The migration tool copies your followers, follow requests, lists, and muted or blocked accounts — but not your statuses or pinned posts. To preserve pinned posts, you must manually re-pin them after migration or use an alternative method to extract them from the export archive.

Steps to Extract Pinned Posts from the Mastodon Export Archive

Follow these steps to locate and extract your pinned posts from the standard Mastodon export. You will need a text editor that can handle large JSON files, such as Visual Studio Code, Notepad++, or any JSON viewer.

1. Generate the export archive
   Go to Preferences > Import and Export > Export. Click the Request your archive button. Mastodon will prepare a ZIP file containing your account data. Depending on the size of your account, this may take a few minutes. When the archive is ready, you will receive an email with a download link. Download the ZIP file to your computer.
2. Extract the ZIP archive
   Use your operating system’s file extraction tool to unzip the downloaded file. Inside, you will see folders named media_attachments, avatar, header, and a file named outbox.json. The outbox.json file contains all your posts in JSON format.
3. Open outbox.json in a JSON viewer
   Open outbox.json in a text editor or JSON viewer. The file structure begins with an @context and type field. Scroll down to the orderedItems array. Each object in this array represents one post.
4. Find the pinned posts
   Look for objects where the type field is Add. These are your pinned posts. Each Add object contains an object field with the full post data, including the post’s content, URL, and attachment URLs. Copy the entire Add object for each pinned post.
5. Create a separate JSON file for pinned posts
   Open a new file in your text editor. Paste the copied Add objects into this file. Save the file as pinned-posts.json. This file now contains only your pinned posts and can be used for manual re-pinning or archival purposes.
6. Re-pin manually on the new instance
   If you are migrating to a new Mastodon instance, you will need to re-create each pinned post manually. Use the URLs from the object field to locate the original posts on your old instance. If the old instance is still accessible, you can copy the content and attachments and create new posts on the new instance. Then pin each new post by clicking the three-dot menu on the post and selecting Pin.

Common Issues When Handling Pinned Posts in Exports

Pinned posts do not appear in the export at all

If your export archive does not contain any Add type objects, check that you generated the archive after pinning the posts. The export captures the state of your account at the moment you request it. If you pinned posts after the export was generated, they will not appear. Request a fresh export after pinning. Also verify that the posts are still pinned on your profile. Unpinned posts will not appear as Add objects.

The outbox.json file is too large to open

If you have thousands of posts, outbox.json can exceed the memory limits of basic text editors. Use a JSON streaming parser or a command-line tool like jq to filter only the Add objects. For example, run jq '.orderedItems[] | select(.type == "Add")' outbox.json > pinned-posts.json in a terminal. This command extracts only the pinned posts without loading the entire file into memory.

Pinned posts are not transferred during account migration

Account migration in Mastodon only moves your followers, follow requests, lists, and mute or block settings. Your statuses, including pinned posts, stay on the old instance. To preserve pinned posts, you must either export them manually as described above or keep the old instance active as a read-only archive. After migration, you can manually re-pin the posts on the new instance using the content from the export.

Item	Standard Export	Manual Pinned Post Extraction
Data included	All statuses, media, followers, follow requests, lists, mute/block lists	Only pinned posts identified by type: Add in outbox.json
File format	ZIP archive with outbox.json and media folders	Custom JSON file containing only pinned post objects
Ease of use	One-click export from Preferences	Requires manual JSON filtering or command-line tool
Migration compatibility	Followers and lists transfer automatically; statuses do not	Must re-create posts manually on the new instance

Mastodon’s standard export does not separate pinned posts because they are metadata flags rather than independent data entities. To handle pinned posts separately, you must extract them from the outbox.json file by filtering for type: Add objects. This method gives you a clean, portable file containing only the posts you have pinned. After migrating to a new instance, use this file to re-create and re-pin each post. For future backups, consider using a browser extension like Mastodon Pinned Post Exporter, which automates the extraction process directly from your profile page.