How to Export Mastodon Profile Fields With API Token

You want to export your Mastodon profile fields — the custom text labels and values you set under your profile settings — so you can back them up or reuse them on another instance. Mastodon does not offer a one-click export for profile fields in the web interface. However, you can retrieve them programmatically using your account API token and a simple API call. This article explains how to generate the token, call the correct endpoint, and save the fields as a structured JSON file.

Understanding the Mastodon API and Profile Fields

Profile fields are custom key-value pairs you add to your Mastodon profile — for example, “Website” with a URL or “Pronouns” with text. Each field has a name, a value, and a verified_at timestamp if the value has been verified. The Mastodon API exposes these fields in the fields array of the Account object when you call the verify_credentials endpoint.

To access this data, you need an API access token with the read:accounts scope. This token is tied to your Mastodon account and allows the API to return your own profile data. You generate the token through the Mastodon web interface by creating a new application in the developer settings. The token is a long alphanumeric string that you pass in the Authorization header of your API request.

The API response is in JSON format. It includes not only profile fields but also your display name, bio, avatar URL, header image, follower count, and other metadata. For the export, you only need the fields array, but saving the entire profile object gives you a complete backup.

Steps to Export Profile Fields Using the API Token

1. Log in to your Mastodon instance
   Open your Mastodon instance in a web browser. Sign in with your account credentials. Ensure you are on the instance where you want to export profile fields — for example, mastodon.social or your own domain.
2. Navigate to Preferences > Development
   Click the gear icon in the top-right menu bar to open Preferences. In the left sidebar, click Development. This page lists any existing applications and lets you create new ones.
3. Create a new application
   Click the New Application button. A form appears. Enter a name for the application — for example, “Profile Export Tool”. The name is only for your reference and does not affect functionality.
4. Set the required API scope
   In the Scopes section, you need at minimum the read:accounts scope. Uncheck all other scopes unless you plan to use the token for other purposes. Click Submit to create the application.
5. Copy the access token
   After submission, the page shows the application details. Locate the field labeled Your access token. Click the copy icon or select the token string and copy it to your clipboard. Store this token securely — treat it like a password.
6. Open a terminal or command prompt
   On Windows, open Command Prompt or PowerShell. On macOS or Linux, open Terminal. Ensure curl is installed. Most systems include curl by default. If not, install it from your package manager or from curl.se.
7. Call the verify_credentials endpoint
   Run the following curl command, replacing YOUR_INSTANCE with your instance domain (for example, mastodon.social) and YOUR_TOKEN with the token you copied:

   curl -H "Authorization: Bearer YOUR_TOKEN" https://YOUR_INSTANCE/api/v1/accounts/verify_credentials

   Press Enter. The API returns a JSON object containing your full profile.

8. Save the response to a file
   To save the output to a file, redirect the response with the > operator. For example:

   curl -H "Authorization: Bearer YOUR_TOKEN" https://YOUR_INSTANCE/api/v1/accounts/verify_credentials > profile.json

   This creates a file named profile.json in the current directory. Open it with any text editor to view the data.

9. Extract the fields array
   Open profile.json in a text editor or use jq to filter only the fields. If you have jq installed, run:

   jq '.fields' profile.json > fields.json

   This creates a new file fields.json containing only the profile fields array. Each field object includes name, value, and verified_at.

Common Mistakes and Limitations When Exporting Profile Fields

API token scope is missing read:accounts

If your token does not include the read:accounts scope, the API returns a 403 Forbidden error. To fix this, delete the application in Preferences > Development and create a new one with the correct scope. Alternatively, edit the existing application — Mastodon allows scope changes on saved applications.

Using the wrong instance URL in the API call

The API endpoint must match the instance where you created the token. If you generated the token on mastodon.social but call mastodon.online, the request fails with a 401 Unauthorized or 404 Not Found. Always verify the instance domain in your browser address bar.

Token exposed in scripts or version control

Never hardcode your token in scripts that you commit to a public repository. Use environment variables or a configuration file excluded from version control. If your token is leaked, revoke it immediately by deleting the application in Preferences > Development.

Profile fields with HTML are exported as raw HTML

Mastodon profile fields support a subset of HTML tags like and . When exported, these tags appear as raw HTML in the value field. If you plan to import the fields into another service, you may need to strip or convert the HTML tags manually.