Mastodon Export Account Settings JSON: How to Read

When you export your Mastodon account settings, the platform generates a JSON file that contains your profile, preferences, and other configuration data. Many users export this file for backup or migration purposes but struggle to interpret the raw JSON structure. This article explains the key sections of the Mastodon export JSON file and shows you how to read each field. You will learn which settings are stored, how values are formatted, and where critical data like your bio and avatar URL reside.

Understanding the Mastodon Account Settings JSON Structure

The Mastodon account settings JSON is a structured file that uses key-value pairs to store your account configuration. The file is generated when you navigate to Settings > Export > Export account settings and click the export button. Mastodon produces a single JSON file with a name like mastodon_account_settings_20250215.json.

The file contains several top-level objects. Each object represents a category of settings. The most important top-level keys are:

• profile — stores your display name, bio, avatar, header image, and metadata fields.
• preferences — stores your user interface preferences such as default post privacy, language, and theme.
• identity_proofs — stores external identity proofs like linked Twitter or GitHub accounts.

The JSON uses standard data types: strings for text, numbers for numeric values, booleans for true/false flags, arrays for lists, and objects for nested groups. Dates are stored as ISO 8601 strings, for example "2025-02-15T10:30:00Z".

Before you can read the file, you need a text editor or a JSON viewer. Any plain text editor such as Notepad on Windows or TextEdit on macOS can open the file. For easier navigation, use a tool that supports JSON syntax highlighting, such as Visual Studio Code, Notepad++, or an online JSON viewer.

Top-Level Keys in the Export File

Open the exported JSON file in your editor. The file begins with a curly brace { and ends with }. The top-level keys are at the first indentation level. Typical keys include:

• "profile"
• "preferences"
• "identity_proofs"

Some instances may include additional keys such as "follows" or "mutes" depending on the Mastodon version. The core account settings are always under the three keys listed above.

Reading the Profile Section

The "profile" object contains all the data you see on your public Mastodon profile. Locate the "profile" key in the JSON. Below it is an object with the following common fields:

• display_name — a string. Example: "Jane Doe". This is the name shown on your profile and posts.
• note — a string. Example: "Software engineer and coffee lover.". This is your bio text. The string may include HTML tags such as <p> or <a>.
• avatar — a string containing a URL. Example: "https://mastodon.example.com/avatars/12345.png". This is the link to your profile picture as stored on the server.
• avatar_static — a string containing a URL. This is a static version of the avatar, used when animations are disabled.
• header — a string containing a URL. This is the link to your header image.
• header_static — a string containing a URL. Static version of the header image.
• locked — a boolean. true means you have a locked account where new followers must be approved. false means open.
• bot — a boolean. true marks the account as a bot.
• fields_attributes — an array of objects. Each object represents a metadata field on your profile. Each object has keys "name" and "value". Example: [{"name": "Website", "value": "https://janedoe.com"}].

To read a specific field, locate the key inside the profile object. For example, to see your bio, look for "note" and read the string value after the colon. If the value is null, the field is empty.

Reading the Preferences Section

The "preferences" object stores your user interface settings. Find the "preferences" key in the JSON. Common fields include:

• posting_default_visibility — a string. Possible values: "public", "unlisted", "private", "direct". This is the default privacy level for new posts.
• posting_default_sensitive — a boolean. true marks all new media as sensitive by default.
• posting_default_language — a string. Example: "en". This is the default language for your posts.
• reading_expand_media — a string. Possible values: "default", "show_all", "hide_all". Controls how media attachments are displayed in your timeline.
• reading_autoplay_gifs — a boolean. true allows animated GIFs to play automatically.
• theme — a string. Example: "mastodon-light" or "contrast". This is the selected theme.

Each preference key corresponds to a setting you can change in the Mastodon web interface under Settings > Preferences. The values are stored exactly as you set them. If you see a value you do not recognize, check the Mastodon preferences page for the matching option.

Reading the Identity Proofs Section

The "identity_proofs" object contains external identity verifications. This section is usually smaller than the others. Each proof is an object with keys such as:

• provider — a string. Example: "twitter" or "github".
• provider_username — a string. Example: "janedoe".
• updated_at — an ISO 8601 date string. Example: "2025-02-10T14:22:00Z".

If you have no identity proofs set up, the value of "identity_proofs" will be an empty object {}.

How to Interpret Nested Objects and Arrays

JSON uses curly braces {} for objects and square brackets [] for arrays. In the profile section, "fields_attributes" is an array. Each element in the array is an object with "name" and "value". The array can have zero or more elements. To read all metadata fields, look for the opening square bracket [ after "fields_attributes". Each object inside is separated by a comma.

For example, if the JSON shows:

"fields_attributes": [
  {
    "name": "Website",
    "value": "https://janedoe.com"
  },
  {
    "name": "Location",
    "value": "Portland, OR"
  }
]

This means your profile has two metadata fields: one named “Website” with the value “https://janedoe.com”, and one named “Location” with the value “Portland, OR”.

Common Issues When Reading the Export JSON

File Contains Only a Single Line of Text

By default, the export file is minified — all JSON is on one line. To read it, use a JSON formatter or a text editor with a pretty-print function. In Visual Studio Code, press Shift + Alt + F to format the document. Online tools like JSONLint also work.

Missing Expected Keys

If you expect a key like "follows" but do not see it, the export may only include account settings, not social graph data. To export followers and following lists, use the separate export options under Settings > Export > Export followers list and Export following list.

Values Appear as Null

A null value means the field is not set. For example, if you never added a header image, the "header" key will show null. This is normal and does not indicate an error.

Mastodon Export JSON vs CSV Export: Key Differences

Item	JSON Export	CSV Export
File format	Structured JSON with nested objects and arrays	Flat table with comma-separated values
Data included	Profile settings, preferences, identity proofs	Followers list, following list, blocks, mutes
Readability	Requires a JSON viewer or formatter for easy reading	Can be opened directly in spreadsheet software
Re-import capability	Can be re-imported into Mastodon via Settings > Import	Can be re-imported only for specific lists (follows, blocks)

The JSON export is the correct file for backing up your full account configuration. The CSV exports are better for transferring follower lists between instances.

You can now open any Mastodon account settings JSON file and identify the profile, preferences, and identity proofs sections. To verify your interpretation, compare the values in the JSON with the settings shown in the Mastodon web interface. For advanced users, the JSON file can be edited and re-imported to apply bulk changes, but ensure the JSON remains valid before importing.